ERC-8227: Encrypted Token

// SPDX-License-Identifier: CC0-1.0
pragma solidity >=0.8.0;

/// @title ERC-8227 Encrypted Token Interface
/// @notice An interface for tokens with FHE-encrypted balances
///         and zero-knowledge transfer verification.

interface IERC8227 {

    // ──────────────────────────────────────────────
    //  Custom Errors
    // ──────────────────────────────────────────────

    error ProofVerificationFailed(bytes32 proofHash);
    error NonceAlreadyUsed(uint256 nonce);
    error InvalidCiphertext();
    error InsufficientEncryptedBalance();
    error KeyVersionMismatch(uint256 expected, uint256 provided);

    // ──────────────────────────────────────────────
    //  Events
    // ──────────────────────────────────────────────

    /// @notice Emitted on every blind transfer.
    /// @dev    The `amount` field is intentionally absent.
    ///         The `proofHash` allows anyone to verify the transfer
    ///         was valid without learning the amount.
    /// @param  from        The sender address.
    /// @param  to          The recipient address.
    /// @param  proofHash   Keccak256 hash of the ZK proof.
    /// @param  keyVersion  The FHE key version used for this transfer.
    event BlindTransfer(
        address indexed from,
        address indexed to,
        bytes32 proofHash,
        uint256 keyVersion
    );

    /// @notice Emitted when an encrypted approval is set.
    /// @param  owner    The token owner.
    /// @param  spender  The approved spender.
    event BlindApproval(
        address indexed owner,
        address indexed spender
    );

    /// @notice Emitted when tokens are minted (encrypted).
    /// @param  to         The recipient.
    /// @param  proofHash  Proof that mint is authorized and valid.
    event BlindMint(
        address indexed to,
        bytes32 indexed proofHash
    );

    /// @notice Emitted when tokens are burned (encrypted).
    /// @param  from       The address burning tokens.
    /// @param  proofHash  Proof that burn is valid.
    event BlindBurn(
        address indexed from,
        bytes32 indexed proofHash
    );

    /// @notice Emitted when the FHE key is rotated.
    /// @param  oldVersion  The previous key version.
    /// @param  newVersion  The new key version.
    event KeyRotated(
        uint256 indexed oldVersion,
        uint256 indexed newVersion
    );

    // ──────────────────────────────────────────────
    //  ERC-20 Compatible (Public Metadata)
    // ──────────────────────────────────────────────

    /// @notice Returns the token name.
    function name() external view returns (string memory);

    /// @notice Returns the token symbol.
    function symbol() external view returns (string memory);

    /// @notice Returns the number of decimals.
    function decimals() external view returns (uint8);

    /// @notice Returns the total supply.
    /// @dev    If `isTotalSupplyConfidential()` returns `false`, this MUST
    ///         return the actual total supply. If it returns `true`, this
    ///         MUST return 0 and the contract MUST implement
    ///         `IERC8227_ConfidentialSupply`.
    function totalSupply() external view returns (uint256);

    /// @notice Returns whether the total supply is confidential.
    /// @dev    This value is fixed at deployment and MUST NOT change over the
    ///         lifetime of the contract. It exists so that a consumer can tell
    ///         a hidden supply from a genuine supply of 0 without probing
    ///         [ERC-165](./eip-165.md) for an extension.
    /// @return `true` if the total supply is hidden, `false` if it is public.
    function isTotalSupplyConfidential() external view returns (bool);

    // ──────────────────────────────────────────────
    //  Encrypted Balance Queries
    // ──────────────────────────────────────────────

    /// @notice Returns the encrypted balance of `account`.
    /// @dev    The returned bytes are an FHE ciphertext. Only `account`
    ///         (or a party holding the decryption key) can decrypt it.
    ///         External observers see opaque bytes.
    /// @param  account  The address to query.
    /// @return The FHE ciphertext of the balance.
    function encryptedBalanceOf(address account)
        external
        view
        returns (bytes memory);

    /// @notice Returns the FHE scheme identifier used by this token.
    /// @dev    Allows wallets and protocols to select the correct
    ///         decryption/re-encryption logic.
    ///         Example return values: "TFHE-v0.3", "OpenFHE-BFV", "CONCRETE-v1"
    /// @return A string identifying the FHE scheme and version.
    function encryptionScheme() external view returns (string memory);

    /// @notice Returns the public encryption key of the token contract.
    /// @dev    Users encrypt their inputs with this key before submitting.
    ///         The contract (or its FHE co-processor) holds the
    ///         corresponding secret key.
    /// @return The public key bytes.
    function publicKey() external view returns (bytes memory);

    /// @notice Returns the current FHE key version.
    /// @dev    Incremented on each key rotation. Proofs MUST reference
    ///         the active key version to be accepted.
    /// @return The current key version number.
    function keyVersion() external view returns (uint256);

    /// @notice Returns whether a given key version is currently active.
    /// @param  version  The key version to query.
    /// @return True if the version is the current active key.
    function isKeyActive(uint256 version) external view returns (bool);

    // ──────────────────────────────────────────────
    //  Blind Transfers
    // ──────────────────────────────────────────────

    /// @notice Transfer an encrypted amount to `to`.
    /// @dev    The `encryptedAmount` is an FHE ciphertext of the amount.
    ///         The `proof` is a ZK proof attesting:
    ///           1. sender balance >= amount (non-negative remainder)
    ///           2. amount >= 0
    ///           3. new sender balance = old sender balance - amount
    ///           4. new recipient balance = old recipient balance + amount
    ///         The contract MUST verify the proof on-chain before applying
    ///         the homomorphic balance update.
    /// @param  to               The recipient address.
    /// @param  encryptedAmount  FHE ciphertext of the transfer amount.
    /// @param  proof            ZK proof of transfer validity.
    /// @return True if the transfer was verified and applied.
    function blindTransfer(
        address to,
        bytes calldata encryptedAmount,
        bytes calldata proof
    ) external returns (bool);

    /// @notice Transfer from `from` to `to` using an encrypted approval.
    /// @dev    Requires prior `blindApprove` from `from` to `msg.sender`.
    ///         The proof MUST additionally attest that the transfer
    ///         does not exceed the encrypted allowance.
    /// @param  from             The sender address.
    /// @param  to               The recipient address.
    /// @param  encryptedAmount  FHE ciphertext of the transfer amount.
    /// @param  proof            ZK proof including allowance verification.
    /// @return True if the transfer was verified and applied.
    function blindTransferFrom(
        address from,
        address to,
        bytes calldata encryptedAmount,
        bytes calldata proof
    ) external returns (bool);

    // ──────────────────────────────────────────────
    //  Encrypted Approvals
    // ──────────────────────────────────────────────

    /// @notice Approve `spender` to transfer up to `encryptedAmount`.
    /// @dev    The allowance is stored as an FHE ciphertext.
    ///         Subsequent `blindTransferFrom` calls deduct from this
    ///         allowance homomorphically.
    ///         The proof MUST attest that the ciphertext is well-formed
    ///         and non-negative. It MUST NOT require a balance check at
    ///         approval time — balance sufficiency is checked at transfer time.
    /// @param  spender          The approved spender.
    /// @param  encryptedAmount  FHE ciphertext of the max allowance.
    /// @param  proof            Proof that the ciphertext is valid and non-negative.
    /// @return True if the approval was set.
    function blindApprove(
        address spender,
        bytes calldata encryptedAmount,
        bytes calldata proof
    ) external returns (bool);

    /// @notice Returns the encrypted allowance of `spender` for `owner`.
    /// @param  owner    The token owner.
    /// @param  spender  The approved spender.
    /// @return The FHE ciphertext of the remaining allowance.
    function encryptedAllowance(address owner, address spender)
        external
        view
        returns (bytes memory);

    // ──────────────────────────────────────────────
    //  Selective Disclosure (OPTIONAL)
    // ──────────────────────────────────────────────

    /// @notice Verify a property proof about an account's balance.
    /// @dev    Allows an account to prove a predicate about their balance
    ///         (e.g., "my balance >= 1000") without revealing the balance.
    ///         The `predicate` encodes the condition type and threshold.
    ///         The `proof` is a ZK proof binding the predicate to the
    ///         account's actual encrypted balance.
    ///         The proof MUST be generated by `account` or an authorized
    ///         delegate. Third-party probing is not possible — proof
    ///         generation requires knowledge of the plaintext balance.
    /// @param  account    The address whose balance is being proven.
    /// @param  predicate  Encoded predicate (condition + threshold).
    /// @param  proof      ZK proof of the predicate's truth.
    /// @return True if the predicate is verified.
    function verifyBalancePredicate(
        address account,
        bytes calldata predicate,
        bytes calldata proof
    ) external view returns (bool);

    // ──────────────────────────────────────────────
    //  Mint / Burn (OPTIONAL)
    // ──────────────────────────────────────────────

    /// @notice Mint encrypted tokens to `to`.
    /// @dev    Only callable by authorized minter.
    ///         The `encryptedAmount` is added homomorphically to
    ///         the recipient's encrypted balance.
    /// @param  to               The recipient.
    /// @param  encryptedAmount  FHE ciphertext of the mint amount.
    /// @param  proof            Proof of authorized minting.
    function blindMint(
        address to,
        bytes calldata encryptedAmount,
        bytes calldata proof
    ) external;

    /// @notice Burn encrypted tokens from `msg.sender`.
    /// @param  encryptedAmount  FHE ciphertext of the burn amount.
    /// @param  proof            Proof that balance >= amount.
    function blindBurn(
        bytes calldata encryptedAmount,
        bytes calldata proof
    ) external;
}

bytes4 constant IERC8227_ID = type(IERC8227).interfaceId;

interface IERC8227_Shielded is IERC8227 {
    event Shielded(address indexed account, uint256 amount);
    event Unshielded(address indexed account, uint256 amount);

    /// @notice Move tokens from public ERC-20 balance to encrypted balance.
    function shield(uint256 amount) external;

    /// @notice Move tokens from encrypted balance to public ERC-20 balance.
    /// @param  proof  Proof of sufficient encrypted balance.
    function unshield(uint256 amount, bytes calldata proof) external;
}

interface IERC8227_ConfidentialSupply is IERC8227 {
    /// @dev MUST revert if `isTotalSupplyConfidential()` returns `false`.
    function totalSupplyEncrypted() external view returns (bytes memory);
}

interface IERC8227_Fees is IERC8227 {
    event FeeCollected(address indexed payer, address indexed recipient, uint256 amount);
    function feeConfig() external view returns (
        address feeRecipient,
        uint256 feeBasisPoints,
        uint256 pGasPerGate
    );
    function estimateBlindTransferCost() external view returns (uint256 pGas);
}

interface IERC8227_Batch is IERC8227 {
    function blindBatchTransfer(
        address[] calldata recipients,
        bytes[] calldata encryptedAmounts,
        bytes calldata batchProof
    ) external returns (bool);
}

// Predicate = abi.encode(PredicateType, threshold)
enum PredicateType {
    GTE,    // balance >= threshold
    LTE,    // balance <= threshold
    EQ,     // balance == threshold
    NEQ,    // balance != threshold
    RANGE   // lowerBound <= balance <= upperBound
}

// For RANGE type:
// predicate = abi.encode(PredicateType.RANGE, lowerBound, upperBound)

publicInputs = {
    from:                address,    // sender
    to:                  address,    // recipient
    encryptedAmountHash: bytes32,    // hash of the encrypted amount
    oldBalanceHashFrom:  bytes32,    // hash of sender's pre-transfer encrypted balance
    newBalanceHashFrom:  bytes32,    // hash of sender's post-transfer encrypted balance
    oldBalanceHashTo:    bytes32,    // hash of recipient's pre-transfer encrypted balance
    newBalanceHashTo:    bytes32,    // hash of recipient's post-transfer encrypted balance
    nonce:               uint256     // replay protection
}