Architecture

The diagram below shows how PrivateERC20 is composed. It inherits from standard OpenZeppelin contracts for access control and reentrancy protection, and delegates all encrypted arithmetic to the MPC precompile via the MpcCore library.

PrivateERC20 (abstract)
├── inherits: Context, ERC165, IPrivateERC20, AccessControl, ReentrancyGuard
├── storage:
│   ├── _balances: per-account encrypted balance (MPC ciphertext + user ciphertext)
│   ├── _allowances: mapping(address => mapping(address => Allowance))
│   ├── _totalSupply: ctUint256                    // always decrypts to real supply
│   └── _accountEncryptionAddress: mapping(address => address)
├── roles:
│   ├── DEFAULT_ADMIN_ROLE  → deployer
│   └── MINTER_ROLE         → bridges, vesting contracts, etc.
└── MpcCore (precompile at 0x64)
    ├── setPublic256(uint256) → gtUint256
    ├── validateCiphertext(itUint256) → gtUint256
    ├── transfer(gt, gt, gt) → (gt, gt, gtBool)
    ├── offBoard(gtUint256) → ctUint256
    ├── offBoardToUser(gtUint256, address) → ctUint256
    └── onBoard(ctUint256) → gtUint256

Key Concepts

Understanding COTI data types is essential before working with any PrivateERC20 function. Every encrypted operation moves values through these representations in a specific order: user input arrives as itUint256, gets loaded into gtUint256 for in-memory computation, and is stored back on-chain as ctUint256.

Term	Description
gtUint256	Garbled-text uint256 — an in-memory encrypted value used during MPC computation
ctUint256	Ciphertext uint256 — an encrypted value stored on-chain
itUint256	Input-text uint256 — an encrypted value submitted by a user (ciphertext + signature)
MpcCore	Solidity library that calls the COTI MPC precompile at address(0x64)
AES Key	A 16-byte (32 hex char) key derived per wallet during onboarding, used to decrypt balances