# MPC Core

The [**MPC Core**](https://github.com/coti-io/coti-contracts/blob/main/contracts/utils/mpc/MpcCore.sol) is a library that simplifies interactions with the precompiled contracts which provide core functionalities for secure multi-party computation (MPC) using the COTI protocol.

## Usage

```solidity
// SPDX-License-Identifier: MIT

pragma solidity 0.8.19;

import "@coti-io/coti-contracts/contracts/utils/mpc/MpcCore.sol";

contract MyContract { ... }
```

## Types

### Inputtext

```solidity
struct itBool
struct itUint8
struct itUint16
struct itUint32
struct itUint64
struct itString
```

### Garbledtext

```solidity
type gtBool
type gtUint8
type gtUint16
type gtUint32
type gtUint64
struct gtString
```

### Ciphertext

```solidity
type ctBool
type ctUint8
type ctUint16
type ctUint32
type ctUint64
struct ctString
```

### Usertext

```solidity
struct utBool
struct utUint8
struct utUint16
struct utUint32
struct utUint64
struct utString
```

## Functions

{% hint style="info" %}
Since private data types mostly support the same functions, we have chosen to list only the functions pertaining to the itUint64, gtUint64 and ctUint64 types. See [**MpcCore.sol**](https://github.com/coti-io/coti-contracts/blob/main/contracts/utils/mpc/MpcCore.sol) for the full list of supported functions.
{% endhint %}

### Special Functions

```solidity
function getUserKey(bytes calldata signedEK, bytes calldata signature) returns (bytes memory keyShare0, bytes memory keyShare1)
```

* Retrieves the user's AES encryption key in encrypted format, by using the provided RSA public key to encrypt it.
* A valid signature using the EOA private key is used to validate the account ownership.

```solidity
function validateCiphertext(itUint64 memory input) returns (gtUint64)
```

* Verifies that a given inputtext has a valid signature and onboards it into the gcEVM, returning a Garbledtext™ value.
* If the input is not valid, the call will revert with no return data and no additional gas will be consumed.

```solidity
function onBoard(ctUint64 ct) returns (gtUint64)
```

* The function onboards a given Ciphertext to the gcEVM, resulting in a Garbledtext™ value.
* Must be invoked with ciphertext encrypted by the **system AES key**, such as ciphertexts that are generated by calling `offboard`.

```solidity
function offBoard(gtUint64 pt) returns (ctUint64)
```

* The function offboards the given Garbledtext™ from the gcEVM, resulting in a Ciphertext.
* The offboarding process uses the **network AES key** to encrypt the value inside the Garbledtext™.

```solidity
function offBoardToUser(gtUint64 pt, address addr) returns (ctUint64)
```

* The function offboards the given Garbledtext™ from the gcEVM, resulting in a Ciphertext.
* The offboarding process uses the **user AES key** associated with the given address to encrypt the value inside the Garbledtext™.

```solidity
function offBoardCombined(gtUint64 pt, address addr) returns (utUint64 memory ut)
```

* The function offboards the given Garbledtext™ from the gcEVM, resulting in a struct containing two Ciphertexts.
* The offboarding process uses both the **network AES key** and the **user AES key** associated with the given address to encrypt the value inside the Garbledtext™.

```solidity
function decrypt(gtUint64 ct) returns (uint64)
```

* Returns the clear value of the given Ciphertext.

```solidity
function setPublic64(uint64 pt) returns (gtUint64)
```

* Onboards the given clear input to the gcEVM, resulting in a Garbledtext™.

```solidity
function rand64() returns (gtUint64)
```

* Generates an encrypted random value in Garbledtext™ form.

```solidity
function randBoundedBits64(uint8 numBits) returns (gtUint64)
```

* Generates an encrypted random value that falls within the range of \[0, 2^numBits] in Garbledtext™ form.

```solidity
function transfer(gtUint64 a, gtUint64 b, gtUint64 amount) returns (gtUint64, gtUint64, gtBool)
```

* Returns the encrypted balances of two accounts (one starting with balance `a`, the other starting with balance `b`) as a result of transferring `amount` from the account with balance `a` to the account with balance `b`, along with an encrypted boolean value indicating whether the transfer would succeed.
* If `a` is less than `amount`, then the resulting values of `a` and `b` will remain unchanged.

```solidity
function transferWithAllowance(gtUint64 a, gtUint64 b, gtUint64 amount, gtUint64 allowance) returns (gtUint64, gtUint64, gtBool, gtUint64)
```

* Returns the encrypted balances of two accounts (one starting with balance `a`, the other starting with balance `b`) as a result of transferring `amount` with allowance `allowance` from the account with balance `a` to the account with balance `b`, along with an encrypted boolean value indicating whether the transfer would succeed.
* If `a` is less than `amount` or if `amount` is greater than `allowance`, then the resulting values of `a` and `b` will remain unchanged.

### Arithmetic Functions

```solidity
function add(gtUint64 a, gtUint64 b) returns (gtUint64)
```

```solidity
function checkedAdd(gtUint64 a, gtUint64 b) returns (gtUint64)
```

```solidity
function checkedAddWithOverflowBit(gtUint64 a, gtUint64 b) returns (gtBool, gtUint64)
```

```solidity
function sub(gtUint64 a, gtUint64 b) returns (gtUint64)
```

```solidity
function checkedSub(gtUint64 a, gtUint64 b) returns (gtUint64)
```

```solidity
function checkedSubWithOverflowBit(gtUint64 a, gtUint64 b) returns (gtBool, gtUint64)
```

```solidity
function mul(gtUint64 a, gtUint64 b) returns (gtUint64)
```

```solidity
function checkedMul(gtUint64 a, gtUint64 b) returns (gtUint64)
```

```solidity
function checkedMulWithOverflowBit(gtUint64 a, gtUint64 b) returns (gtBool, gtUint64)
```

```solidity
function div(gtUint64 a, gtUint64 b) returns (gtUint64)
```

```solidity
function rem(gtUint64 a, gtUint64 b) returns (gtUint64)
```

```solidity
function and(gtUint64 a, gtUint64 b) returns (gtUint64)
```

```solidity
function or(gtUint64 a, gtUint64 b) returns (gtUint64)
```

```solidity
function xor(gtUint64 a, gtUint64 b) returns (gtUint64)
```

```solidity
function shl(gtUint64 a, uint8 b) returns (gtUint64)
```

```solidity
function shr(gtUint64 a, uint8 b) returns (gtUint64)
```

```solidity
function eq(gtUint64 a, gtUint64 b) returns (gtBool)
```

```solidity
function ne(gtUint64 a, gtUint64 b) returns (gtBool)
```

```solidity
function ge(gtUint64 a, gtUint64 b) returns (gtBool)
```

```solidity
function gt(gtUint64 a, gtUint64 b) returns (gtBool)
```

```solidity
function le(gtUint64 a, gtUint64 b) returns (gtBool)
```

```solidity
function lt(gtUint64 a, gtUint64 b) returns (gtBool)
```

```solidity
function min(gtUint64 a, gtUint64 b) returns (gtUint64)
```

```solidity
function max(gtUint64 a, gtUint64 b) returns (gtUint64)
```

```solidity
function mux(gtBool bit, gtUint64 a, gtUint64 b) returns (gtUint64)
```

* Returns an encrypted value (either `a` or `b`) based on the encrypted boolean input
* If `bit` is **false**, then the returned value is equal to `a`
* If `bit` is **true**, then the returned value is equal to `b`

### Enums

```solidity
enum MPC_TYPE { SBOOL_T, SUINT8_T, SUINT16_T, SUINT32_T, SUINT64_T }
```

* Represent different MPC data types

```solidity
enum ARGS { BOTH_SECRET, LHS_PUBLIC, RHS_PUBLIC }
```

* Represent different argument types

### Encoding Functions

```solidity
function combineEnumsToBytes2(MPC_TYPE mpcType, ARGS argsType) returns (bytes2)
```

* Combines an `MPC_TYPE` and `ARGS` into a `bytes2` value.

```solidity
function combineEnumsToBytes3(MPC_TYPE mpcType1, MPC_TYPE mpcType2, ARGS argsType) returns (bytes3)
```

* Combines two `MPC_TYPE` values and an `ARGS` value into a `bytes3` value.

```solidity
function combineEnumsToBytes4(MPC_TYPE mpcType1, MPC_TYPE mpcType2, MPC_TYPE mpcType3, ARGS argsType) returns (bytes4)
```

* Combines three `MPC_TYPE` values and an `ARGS` value into a `bytes4` value.

```solidity
function combineEnumsToBytes5(MPC_TYPE mpcType1, MPC_TYPE mpcType2, MPC_TYPE mpcType3, MPC_TYPE mpcType4, ARGS argsType) returns (bytes5)
```

* Combines four `MPC_TYPE` values and an `ARGS` value into a `bytes4` value.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.coti.io/coti-documentation/build-on-coti/tools/contracts-library/mpc-core.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.