Update documentation for 128-bit and 256-bit encrypted types support

build-on-coti/tools/contracts-library/mpc-core.md

@@ -24,6 +24,8 @@ struct itUint8
 struct itUint16
 struct itUint32
 struct itUint64
+struct itUint128
+struct itUint256
 struct itString
 ```
 
@@ -35,6 +37,8 @@ type gtUint8
 type gtUint16
 type gtUint32
 type gtUint64
+type gtUint128
+type gtUint256
 struct gtString
 ```
 
@@ -46,6 +50,8 @@ type ctUint8
 type ctUint16
 type ctUint32
 type ctUint64
+type ctUint128
+struct ctUint256
 struct ctString
 ```
 
@@ -57,13 +63,15 @@ struct utUint8
 struct utUint16
 struct utUint32
 struct utUint64
+struct utUint128
+struct utUint256
 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.
+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. The same functions are available for itUint128/gtUint128/ctUint128 and itUint256/gtUint256/ctUint256 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
@@ -122,6 +130,18 @@ function setPublic64(uint64 pt) returns (gtUint64)
 
 * Onboards the given clear input to the gcEVM, resulting in a Garbledtext™.
 
+```solidity
+function setPublic128(uint128 pt) returns (gtUint128)
+```
+
+* Onboards the given clear input to the gcEVM, resulting in a Garbledtext™.
+
+```solidity
+function setPublic256(uint256 pt) returns (gtUint256)
+```
+
+* Onboards the given clear input to the gcEVM, resulting in a Garbledtext™.
+
 ```solidity
 function rand64() returns (gtUint64)
 ```
@@ -257,7 +277,7 @@ function mux(gtBool bit, gtUint64 a, gtUint64 b) returns (gtUint64)
 ### Enums
 
 ```solidity
-enum MPC_TYPE { SBOOL_T, SUINT8_T, SUINT16_T, SUINT32_T, SUINT64_T }
+enum MPC_TYPE { SBOOL_T, SUINT8_T, SUINT16_T, SUINT32_T, SUINT64_T, SUINT128_T, SUINT256_T }
 ```
 
 * Represent different MPC data types

build-on-coti/tools/contracts-library/tokens/private-erc20.md

@@ -43,99 +43,99 @@ function accountEncryptionAddress(address account) view returns (address)
 ```
 
 ```solidity
-function balanceOf(address account) view returns (ctUint64)
+function balanceOf(address account) view returns (ctUint256)
 ```
 
 ```solidity
-function balanceOf() returns (gtUint64)
+function balanceOf() returns (gtUint256)
 ```
 
 ```solidity
 function setAccountEncryptionAddress(address addr) returns (bool)
 ```
 
 ```solidity
-function transfer(address to, itUint64 calldata value) returns (gtBool)
+function transfer(address to, itUint256 calldata value) returns (gtBool)
 ```
 
 ```solidity
-function transfer(address to, gtUint64 value) returns (gtBool)
+function transfer(address to, gtUint256 value) returns (gtBool)
 ```
 
 ```solidity
 function allowance(address owner, address spender) view returns (Allowance memory)
 ```
 
 ```solidity
-function allowance(address account, bool isSpender) returns (gtUint64)
+function allowance(address account, bool isSpender) returns (gtUint256)
 ```
 
 ```solidity
 function reencryptAllowance(address account, bool isSpender) returns (bool)
 ```
 
 ```solidity
-function approve(address spender, itUint64 calldata value) returns (bool)
+function approve(address spender, itUint256 calldata value) returns (bool)
 ```
 
 ```solidity
-function approve(address spender, gtUint64 value) returns (bool)
+function approve(address spender, gtUint256 value) returns (bool)
 ```
 
 ```solidity
-function transferFrom(address from, address to, itUint64 calldata value) returns (gtBool)
+function transferFrom(address from, address to, itUint256 calldata value) returns (gtBool)
 ```
 
 ```solidity
-function transferFrom(address from, address to, gtUint64 value) returns (gtBool)
+function transferFrom(address from, address to, gtUint256 value) returns (gtBool)
 ```
 
 ```solidity
-function _transfer(address from, address to, gtUint64 value) returns (gtBool)
+function _transfer(address from, address to, gtUint256 value) returns (gtBool)
 ```
 
 ```solidity
-function _update(address from, address to, gtUint64 value) returns (gtBool)
+function _update(address from, address to, gtUint256 value) returns (gtBool)
 ```
 
 ```solidity
-function _getBalance(address account) returns (gtUint64)
+function _getBalance(address account) returns (gtUint256)
 ```
 
 ```solidity
 function _getAccountEncryptionAddress(address account) view returns (address)
 ```
 
 ```solidity
-function _updateBalance(address account, gtUint64 balance)
+function _updateBalance(address account, gtUint256 balance)
 ```
 
 ```solidity
-function _mint(address account, gtUint64 value) returns (gtBool)
+function _mint(address account, gtUint256 value) returns (gtBool)
 ```
 
 ```solidity
-function _burn(address account, gtUint64 value) returns (gtBool)
+function _burn(address account, gtUint256 value) returns (gtBool)
 ```
 
 ```solidity
-function _approve(address owner, address spender, gtUint64 value)
+function _approve(address owner, address spender, gtUint256 value)
 ```
 
 ```solidity
-function _spendAllowance(address owner, address spender, gtUint64 value)
+function _spendAllowance(address owner, address spender, gtUint256 value)
 ```
 
 ```solidity
-function _safeOnboard(ctUint64 value) returns (gtUint64)
+function _safeOnboard(ctUint256 value) returns (gtUint256)
 ```
 
 ```solidity
-event Transfer(address indexed from, address indexed to, ctUint64 senderValue, ctUint64 receiverValue);
+event Transfer(address indexed from, address indexed to, ctUint256 senderValue, ctUint256 receiverValue);
 ```
 
 ```solidity
-event Approval(address indexed owner, address indexed spender, ctUint64 ownerValue, ctUint64 spenderValue);
+event Approval(address indexed owner, address indexed spender, ctUint256 ownerValue, ctUint256 spenderValue);
 ```
 
 ## Errors

build-on-coti/tools/ethers.js.md

@@ -148,11 +148,24 @@ async function encryptValue(plaintextValue: bigint | number | string, contractAd
 ```
 
 * **Parameters**:
-  * `plaintextValue`: The value to encrypt, which can be of type `bigint`, `number`, or `string`.
+  * `plaintextValue`: The value to encrypt, which can be of type `bigint`, `number`, or `string`. For numeric values, must be 128 bits or smaller.
   * `contractAddress`: The smart contract address to which the encryption is related.
   * `functionSelector`: The function identifier for the contract interaction.
 * **Returns**: A `Promise<itUint | itString>`, depending on the type of the plaintext value.
-* **Description**: Encrypts the provided plaintext using the user’s AES key. If the AES key is not available, it attempts to generate or recover it via onboarding. The function handles both integer and string values and returns the encrypted result accordingly.
+* **Description**: Encrypts the provided plaintext using the user's AES key. If the AES key is not available, it attempts to generate or recover it via onboarding. The function handles both integer (up to 128 bits) and string values and returns the encrypted result accordingly. For values larger than 128 bits, use `encryptValue256` instead.
+* **Throws**: `Error` if numeric values exceed 128 bits or if the AES key cannot be generated or recovered.
+
+```typescript
+async function encryptValue256(plaintextValue: bigint | number, contractAddress: string, functionSelector: string): Promise<itUint256>
+```
+
+* **Parameters**:
+  * `plaintextValue`: The value to encrypt, which can be of type `bigint` or `number` (must be 256 bits or smaller).
+  * `contractAddress`: The smart contract address to which the encryption is related.
+  * `functionSelector`: The function identifier for the contract interaction.
+* **Returns**: A `Promise<itUint256>`, containing the encrypted ciphertext with `ciphertextHigh` and `ciphertextLow` properties and signature.
+* **Description**: Encrypts the provided plaintext using the user's AES key for 256-bit encrypted values. If the AES key is not available, it attempts to generate or recover it via onboarding. This function only accepts numeric values (bigint or number); for string encryption, use `encryptValue` instead.
+* **Throws**: `Error` if the plaintext value exceeds 256 bits or if the AES key cannot be generated or recovered.
 
 ```typescript
 async function decryptValue(ciphertext: ctUint | ctString): Promise<bigint | string>
@@ -161,7 +174,16 @@ async function decryptValue(ciphertext: ctUint | ctString): Promise<bigint | str
 * **Parameters**:
   * `ciphertext`: The encrypted value, which can either be of type `ctUint` (for integers) or `ctString` (for strings).
 * **Returns**: A `Promise<bigint | string>`, depending on the ciphertext type.
-* **Description**: Decrypts the provided ciphertext using the AES key stored in the user’s onboarding information. If the AES key is missing, it attempts to onboard the user or recover the key. The method supports decryption for both integers and strings.
+* **Description**: Decrypts the provided ciphertext using the AES key stored in the user's onboarding information. If the AES key is missing, it attempts to onboard the user or recover the key. The method supports decryption for both integers and strings.
+
+```typescript
+async function decryptValue256(ciphertext: ctUint256): Promise<bigint>
+```
+
+* **Parameters**:
+  * `ciphertext`: The encrypted value of type `ctUint256` (an object with `ciphertextHigh` and `ciphertextLow` properties, both bigint).
+* **Returns**: A `Promise<bigint>`, the decrypted plaintext value.
+* **Description**: Decrypts the provided 256-bit ciphertext using the AES key stored in the user's onboarding information. If the AES key is missing, it attempts to onboard the user or recover the key. This method only accepts `ctUint256` type ciphertexts; for string decryption, use `decryptValue` instead.
 
 ```typescript
 async function generateOrRecoverAes(onboardContractAddress: string = ONBOARD_CONTRACT_ADDRESS): Promise<void>
@@ -238,11 +260,24 @@ async function encryptValue(plaintextValue: bigint | number | string, contractAd
 ```
 
 * **Parameters**:
-  * `plaintextValue`: The value to encrypt, which can be of type `bigint`, `number`, or `string`.
+  * `plaintextValue`: The value to encrypt, which can be of type `bigint`, `number`, or `string`. For numeric values, must be 128 bits or smaller.
   * `contractAddress`: The address of the smart contract involved in the encryption.
   * `functionSelector`: A string that identifies the specific contract function to which this encryption pertains.
 * **Returns**: A promise that resolves to either `itUint` or `itString`, depending on the type of the value.
-* **Description**: Encrypts the provided `plaintextValue` using the user’s AES key. If the AES key is missing, it attempts to generate or recover it. It handles both `bigint` and `string` values.
+* **Description**: Encrypts the provided `plaintextValue` using the user's AES key. If the AES key is missing, it attempts to generate or recover it. It handles both `bigint` (up to 128 bits) and `string` values. For values larger than 128 bits, use `encryptValue256` instead.
+* **Throws**: `Error` if numeric values exceed 128 bits or if the AES key cannot be generated or recovered.
+
+```typescript
+async function encryptValue256(plaintextValue: bigint | number, contractAddress: string, functionSelector: string): Promise<itUint256>
+```
+
+* **Parameters**:
+  * `plaintextValue`: The value to encrypt, which can be of type `bigint` or `number` (must be 256 bits or smaller).
+  * `contractAddress`: The address of the smart contract involved in the encryption.
+  * `functionSelector`: A string that identifies the specific contract function to which this encryption pertains.
+* **Returns**: A promise that resolves to `itUint256`, containing the encrypted ciphertext with `ciphertextHigh` and `ciphertextLow` properties and signature.
+* **Description**: Encrypts the provided `plaintextValue` using the user's AES key for 256-bit encrypted values. If the AES key is missing, it attempts to generate or recover it. This function only accepts numeric values (bigint or number); for string encryption, use `encryptValue` instead.
+* **Throws**: `Error` if the plaintext value exceeds 256 bits or if the AES key cannot be generated or recovered.
 
 ```typescript
 async function decryptValue(ciphertext: ctUint | ctString): Promise<string | bigint>
@@ -251,7 +286,16 @@ async function decryptValue(ciphertext: ctUint | ctString): Promise<string | big
 * **Parameters**:
   * `ciphertext`: The encrypted value, either a `ctUint` (for integers) or a `ctString` (for strings).
 * **Returns**: A promise that resolves to either a `string` or `bigint`, depending on the ciphertext type.
-* **Description**: Decrypts the given ciphertext using the user’s AES key. If the AES key is not available, it attempts to generate or recover it. Handles both integer and string decryption.
+* **Description**: Decrypts the given ciphertext using the user's AES key. If the AES key is not available, it attempts to generate or recover it. Handles both integer and string decryption.
+
+```typescript
+async function decryptValue256(ciphertext: ctUint256): Promise<bigint>
+```
+
+* **Parameters**:
+  * `ciphertext`: The encrypted value of type `ctUint256` (an object with `ciphertextHigh` and `ciphertextLow` properties, both bigint).
+* **Returns**: A promise that resolves to `bigint`, the decrypted plaintext value.
+* **Description**: Decrypts the given 256-bit ciphertext using the user's AES key. If the AES key is not available, it attempts to generate or recover it. This method only accepts `ctUint256` type ciphertexts; for string decryption, use `decryptValue` instead.
 
 ```typescript
 function enableAutoOnboard()
@@ -272,11 +316,11 @@ function clearUserOnboardInfo()
 * **Description**: Clears the stored user onboarding information by setting `_userOnboardInfo` to `undefined`.
 
 ```typescript
-async function generateOrRecoverAes(onboardContractAddress: string = DEVNET_ONBOARD_CONTRACT_ADDRESS)
+async function generateOrRecoverAes(onboardContractAddress: string = ONBOARD_CONTRACT_ADDRESS)
 ```
 
 * **Parameters**:
-  * `onboardContractAddress`: The contract address for onboarding purposes. Defaults to `DEVNET_ONBOARD_CONTRACT_ADDRESS`.
+  * `onboardContractAddress`: The contract address for onboarding purposes. Defaults to `ONBOARD_CONTRACT_ADDRESS`.
 * **Description**: Attempts to generate or recover the user’s AES key:
   * If the AES key exists in the user’s onboarding info, it returns immediately.
   * If the user’s RSA key and transaction hash are available, the AES key is recovered from the blockchain transaction using `recoverAesFromTx`.

build-on-coti/tools/typescript-sdk.md

@@ -105,12 +105,40 @@ function buildInputText(plaintext: bigint, sender, contractAddress, functionSele
 Encrypts a plaintext (up to 64 bits) and generates a signed transaction payload.
 
 * **Parameters:**
-  * `plaintext`: The data to be encrypted (must be smaller than 64 bits).
+  * `plaintext`: The data to be encrypted (must be smaller than 2^64, i.e., 64 bits or smaller).
   * `sender`: The sender's information containing their wallet and user key.
   * `contractAddress`: The Ethereum contract address.
   * `functionSelector`: The function selector for the contract function.
 * **Returns:** An `itUint` object containing the encrypted ciphertext and signature.
 
+```typescript
+function prepareIT(plaintext: bigint, sender, contractAddress, functionSelector): itUint
+```
+
+Encrypts a plaintext (up to 128 bits) and generates a signed transaction payload.
+
+* **Parameters:**
+  * `plaintext`: The data to be encrypted (must be 128 bits or smaller).
+  * `sender`: The sender's information containing their wallet and user key.
+  * `contractAddress`: The Ethereum contract address.
+  * `functionSelector`: The function selector for the contract function.
+* **Returns:** An `itUint` object containing the encrypted ciphertext and signature.
+* **Throws:** `RangeError` if plaintext size exceeds 128 bits. For 256-bit plaintexts, use `prepareIT256` instead.
+
+```typescript
+function prepareIT256(plaintext: bigint, sender, contractAddress, functionSelector): itUint256
+```
+
+Encrypts a plaintext (up to 256 bits) and generates a signed transaction payload.
+
+* **Parameters:**
+  * `plaintext`: The data to be encrypted (must be 256 bits or smaller).
+  * `sender`: The sender's information containing their wallet and user key.
+  * `contractAddress`: The Ethereum contract address.
+  * `functionSelector`: The function selector for the contract function.
+* **Returns:** An `itUint256` object containing the encrypted ciphertext (with `ciphertextHigh` and `ciphertextLow` properties) and signature.
+* **Throws:** `RangeError` if plaintext size exceeds 256 bits.
+
 ```typescript
 function buildStringInputText(plaintext: string, sender, contractAddress, functionSelector): itString
 ```
@@ -135,6 +163,17 @@ Decrypts an AES-encrypted ciphertext and returns the original plaintext as a `bi
   * `userKey`: The user key for AES decryption.
 * **Returns:** The decrypted plaintext as a `bigint`.
 
+```typescript
+function decryptUint256(ciphertext: ctUint256, userKey: string): bigint
+```
+
+Decrypts an AES-encrypted 256-bit ciphertext and returns the original plaintext as a `bigint`.
+
+* **Parameters:**
+  * `ciphertext`: The encrypted 256-bit ciphertext object with `ciphertextHigh` and `ciphertextLow` properties (type `ctUint256`).
+  * `userKey`: The user key for AES decryption (hex string, 32 characters).
+* **Returns:** The decrypted plaintext as a `bigint`.
+
 ```typescript
 function decryptString(ciphertext: { value: bigint[] }, userKey: string): string
 ```
@@ -152,3 +191,4 @@ Decrypts an AES-encrypted ciphertext representing a string.
 Generates a random 128-bit AES key.
 
 * **Returns:** A string containing the random bytes.
+

how-coti-works/advanced-topics/precompiles.md

@@ -14,8 +14,11 @@ pragma solidity ^0.8.19;
 interface ExtendedOperations {
 
     function OnBoard(bytes1 metaData, uint256 ct) external returns (uint256 result);
+    function OnBoard(bytes1 metaData, uint256 ctHigh, uint256 ctLow) external returns (uint256 result);
     function OffBoard(bytes1 metaData, uint256 ct) external returns (uint256 result);
+    function OffBoard256(bytes1 metaData, uint256 gt) external returns (uint256 ctHigh, uint256 ctLow);
     function OffBoardToUser(bytes1 metaData, uint256 ct, bytes calldata addr) external returns (uint256 result);
+    function OffBoardToUser256(bytes1 metaData, uint256 ct, bytes calldata addr) external returns (uint256 ctHigh, uint256 ctLow);
     function SetPublic(bytes1 metaData, uint256 ct) external returns (uint256 result);
     function Rand(bytes1 metaData) external returns (uint256 result);
     function RandBoundedBits(bytes1 metaData, uint8 numBits) external returns (uint256 result);
@@ -46,6 +49,7 @@ interface ExtendedOperations {
     function Transfer(bytes4 metaData, uint256 a, uint256 b, uint256 amount) external returns (uint256 new_a, uint256 new_b, uint256 res);
     function TransferWithAllowance(bytes5 metaData, uint256 a, uint256 b, uint256 amount, uint256 allowance) external returns (uint256 new_a, uint256 new_b, uint256 res, uint256 new_allowance);
     function ValidateCiphertext(bytes1 metaData, uint256 ciphertext, bytes calldata signature) external returns (uint256 result);
+    function ValidateCiphertext(bytes1 metaData, uint256 ciphertextHigh, uint256 ciphertextLow, bytes calldata signature) external returns (uint256 result);
     function GetUserKey(bytes calldata signedEK) external returns (bytes memory encryptedKey);
     function SHA256Fixed432BitInput(uint256 amount, uint256 seed1, uint256 seed2, uint256 padding1, uint256 padding2, bytes calldata addr) external returns (bytes memory result);
 }