--- eip: 7963 title: Oracle-Permissioned ERC-20 with ZK Proofs description: Extension with oracle-permissioned transfers validated via zero-knowledge proofs of payment instructions author: Siyuan Zheng (@andrewcoder666) , Xiaoyu Liu (@elizabethxiaoyu) , Wenwei Ma (@madyinglight) , Jun Meng Tan (@chadxgpt) , Yuxiang Fu (@tmac4096) , Kecheng Gao (@thanks-v-me-50) , Alwin Ng Jun Wei (@alwinngjw) , Chenxin Wang (@3235773541) , Xiang Gao (@GaoYiRu) , yuanshanhshan (@xunayuan) , Hao Zou (@BruceZH0915) , Yanyi Liang , Yuehua Zhang (@astroyhzcc) discussions-to: https://ethereum-magicians.org/t/eip-7963-oracle-permissioned-erc-20-with-zk-proofs/24180 status: Draft type: Standards Track category: ERC created: 2025-05-13 requires: 20, 1967 --- ## Abstract This proposal extends [ERC-20](./eip-20.md) tokens with oracle-permissioned transfers validated by zero-knowledge proofs. Token transfers are only valid when an external "Transfer Oracle" pre-approves them using off-chain payment instructions in a standardized JSON format, proven on-chain via ZK proofs. The standard defines: + `ITransferOracle` – a minimal interface that any ERC-20-compatible contract can consult to decide whether transfers should succeed + `approveTransfer` flow – whereby an issuer deposits a one-time approval in the oracle with a ZK-proof attesting that the approval matches a canonicalized payment instruction message + `canTransfer` query – whereby the token contract atomically consumes an approval when the holder initiates the transfer + Generic data structures, events, and hooks that allow alternative permissioning logics (KYC lists, travel-rule attestations, CBDC quotas) to share the same plumbing The scheme is issuer-agnostic, proof-system-agnostic, and network-agnostic (L1/L2). The payment instruction format is compatible with ISO 20022 pain.001 for interoperability with existing financial systems, but does not require implementers to access proprietary ISO specifications. Reference implementation uses RISC Zero as the proving system, but the standard admits any ZK-proof system. ## Motivation Institutional tokenisation requires _both_ ERC-20 fungibility **and** legally enforceable control over who may send value to whom and why. Hard-coding rules in every token contract is brittle and non-standard. Centralising rules in a singleton oracle and proving off-chain documentation on-chain gives: + **Compliance traceability** – every transfer links to a signed payment order recognised by traditional finance systems. + **Issuer flexibility** – any institution can swap out its oracle logic without breaking ERC-20 compatibility. + **Composability** – DeFi protocols can interact with permissioned tokens using familiar ERC-20 flows, while downstream permission checks are encapsulated in the oracle. ## Specification The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. ### Interfaces ```solidity /// @notice One-time ZK-backed approval for a single transfer. struct TransferApproval { address sender; address recipient; uint256 minAmt; // Minimum allowed transfer amount (inclusive) uint256 maxAmt; // Maximum allowed transfer amount (inclusive) uint256 expiry; // UNIX seconds; 0 == never expires bytes32 proofId; // keccak256(root‖debtorHash‖creditorHash) } /// @title External oracle consulted by permissioned tokens. interface ITransferOracle { /// @dev Verifies zk-proof and stores a one-time approval. /// @return proofId – unique handle for off-chain reconciliation function approveTransfer( TransferApproval calldata approval, bytes calldata proof, // ZK proof bytes (system-specific) bytes calldata publicInputs // ABI-encoded public outputs ) external returns (bytes32 proofId); /// @dev Atomically consumes an approval that covers `amount`. /// MUST revert if no such approval exists. function canTransfer( address token, address issuer, address sender, address recipient, uint256 amount ) external returns (bytes32 proofId); } ``` ### Transfer Hook A _Permissioned ERC-20_ **MUST** consult the oracle on every value-moving transfer (every `transfer` and `transferFrom`) before the balances of `from` and `to` are updated, and **MUST** revert the transfer unless the oracle returns a valid `proofId`. Mints and burns (transfers from or to the zero address) **MAY** bypass this check. For a transfer of `amount` from `from` to `to`, the token **MUST** perform the equivalent of: ```solidity bytes32 proofId = ORACLE.canTransfer(address(this), owner(), from, to, amount); // canTransfer MUST revert if no valid approval exists // ... update balances ... emit TransferValidated(proofId); ``` `ORACLE` is the address of the `ITransferOracle` instance consulted by the token, typically fixed at construction. This requirement applies to all ERC-20 implementations: implementations based on OpenZeppelin's ERC-20 MAY satisfy it by overriding the internal `_update(address from, address to, uint256 amount)` function, while other implementations **MUST** enforce the equivalent check within their own `transfer` and `transferFrom` logic. ### Validation Requirements The oracle implementation **MUST** enforce the following validation rules when processing `approveTransfer`: ```solidity require(minAmt <= maxAmt, "Invalid amount range"); require(sender != address(0), "Invalid sender address"); require(recipient != address(0), "Invalid recipient address"); require(expiry > block.timestamp || expiry == 0, "Approval already expired"); ``` ### Approval Consumption Behavior **Single-Use Policy**: Each approval is consumed entirely when a matching transfer occurs. Approvals **CANNOT** be partially consumed or reused for multiple transfers. **Amount Matching**: A transfer with `amount` is valid if and only if `minAmt <= amount <= maxAmt` (both bounds inclusive). **Best-Match Selection**: When multiple valid approvals exist for the same (issuer, sender, recipient) triplet, the oracle **SHOULD** consume the approval with the smallest amount range to preserve larger approvals for potentially larger transfers. **Expiry Handling**: Expired approvals (where `block.timestamp >= expiry` and `expiry != 0`) **MUST** be ignored during transfer validation but **MAY** remain in storage for auditing purposes. ### Events ```solidity event TransferApproved( address indexed issuer, address indexed sender, address indexed recipient, uint256 minAmt, uint256 maxAmt, uint256 expiry, bytes32 proofId ); event ApprovalConsumed( address indexed issuer, address indexed sender, address indexed recipient, uint256 amount, bytes32 proofId ); event TransferValidated(bytes32 indexed proofId); ``` ### Payment Instruction Message Format Payment instructions **MUST** be JSON objects with the following structure: ```json { "messageId": "string", "creationDateTime": "RFC 3339 timestamp", "paymentInfo": { "debtor": { "name": "string", "identifier": "string", "identifierScheme": "string" }, "creditor": { "name": "string", "identifier": "string", "identifierScheme": "string" }, "amount": { "value": "string (in milli-units)", "currency": "string (three-letter currency code)" }, "executionDate": "RFC 3339 timestamp" } } ``` **Field Definitions:** - `messageId`: Unique identifier for this payment instruction - `creationDateTime`: When the instruction was created ([RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) format, UTC) - `debtor.identifier`: Sender's account identifier (Ethereum address, IBAN, BIC, etc.) - `debtor.identifierScheme`: Type of identifier (e.g., "ethereum_address", "iban", "bic", "swift") - `creditor.identifier`: Recipient's account identifier - `creditor.identifierScheme`: Type of identifier - `amount.value`: Transfer amount in **milli-units** (integers only, no decimals) - `amount.currency`: Three-letter currency code (e.g., "USD", "EUR", "GBP") - `executionDate`: When the transfer should execute (becomes approval expiry) **Milli-unit Conversion**: All monetary amounts **MUST** be represented as integers in milli-units (10⁻³) to avoid floating-point precision issues: - 1 milli-unit = 0.001 base currency units - Example: 1.50 USD = "1500" milli-units - Example: 0.001 BTC = "1" milli-unit ### Message Canonicalization To ensure deterministic hashing, payment instructions **MUST** be canonicalized before Merkle tree construction: 1. **JSON Canonicalization**: Apply [RFC 8785 (JCS)](https://www.rfc-editor.org/rfc/rfc8785) - Sort object keys lexicographically - Remove insignificant whitespace - Use minimal JSON encoding 2. **Text Normalization**: Apply UTF-8 Normalization Form C (NFC), as defined in [Unicode Standard Annex #15](https://www.unicode.org/reports/tr15/tr15-57.html), to all string fields 3. **Timestamp Format**: All timestamps **MUST** use [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) format in UTC (e.g., "2025-01-03T10:30:00Z") **Example Canonicalization:** Input: ```json { "amount": { "value": "1500", "currency": "USD" }, "debtor": { "name": "Alice" } } ``` Output (canonical): ```json {"amount":{"currency":"USD","value":"1500"},"debtor":{"name":"Alice"}} ``` ### Merkle-and-Proof Requirements The merkle tree root is used to verify that the public inputs actually come from the original off-chain payment instruction. The ZK proof system validates that all fields belong to the same committed payment message through Merkle proof verification. | Public Inputs | Purpose | Rationale | | --- | --- | --- | | `root` | Merkle root of payment instruction | Data-integrity and field binding | | `debtorHash` | Hash of debtor (sender) data | Privacy-preserving sender identification | | `creditorHash` | Hash of creditor (recipient) data | Privacy-preserving recipient identification | | `minAmountMilli`/`maxAmountMilli` | Value bounds in milli-units | Anti-front-running protection | | `currencyHash` | Hash of currency code | Currency validation | | `expiry` | Execution date as timestamp | Prevents replay and ensures timeliness | The ZK proof system **MUST** verify: 1. **Hash Integrity**: All provided hashes match computed hashes of the actual data 2. **Amount Bounds**: The transfer amount falls within the specified range 3. **Merkle Proofs**: All fields (debtor, creditor, amount, currency, expiry) belong to the same committed message 4. **Expiry Validation**: The execution date is consistent and not expired *The oracle MAY accept additional public inputs, e.g., extended currency validation, jurisdiction codes, sanctions list epochs* ### Proof System Flexibility This standard is **proof-system-agnostic**. Implementations **MAY** use any ZK proof system (Groth16, PLONK, STARKs, etc.) as long as they: 1. Validate the required public inputs listed above 2. Ensure proper Merkle proof verification for field binding 3. Maintain the same security guarantees ### Upgradeability + Token and Oracle **MAY** be behind [ERC-1967](./eip-1967.md) proxies. + Verifier is stateless; safe to swap when a new proof system is adopted. + Oracle logic can be upgraded independently of token contracts. ## Rationale Keeping oracle logic out of the token contract preserves fungibility and lets one oracle serve hundreds of issuers. `TransferApproval` uses _amount ranges_ so issuers can sign a single approval before the final FX quote is known. `canTransfer` returns the `proofId`, enabling downstream analytics and regulators to join on-chain transfers with off-chain payment system messages. The Merkle proof requirement ensures that all approval data comes from the same authentic payment instruction, preventing field substitution attacks where an attacker might try to combine legitimate data from different transactions. **Amount Range Design**: The `minAmt`/`maxAmt` bounds accommodate scenarios where the exact transfer amount is unknown at approval time (e.g., currency conversion with fluctuating exchange rates). The inclusive bounds (`minAmt <= amount <= maxAmt`) provide clear validation semantics, while the single-use consumption policy prevents approval reuse attacks. **Best-Match Selection**: When multiple approvals overlap, selecting the approval with the smallest range optimizes for approval preservation, allowing issuers to create both broad approvals (e.g., 0-1000 tokens) and specific approvals (e.g., 100-110 tokens) without the specific approval being wastefully consumed by small transfers. ## Backwards Compatibility Existing ERC-20 consumers remain unaffected; a failed `transfer` simply reverts. Wallets and exchanges **should** surface the oracle's revert messages so users know they lack approval. ## Reference Implementation A minimal reference implementation is available in the assets directory. It uses RISC Zero as the proving system, chosen for: + **Transparent Setup**: No trusted ceremony required + **Developer Experience**: Write verification logic in Rust + **Performance**: Efficient proof generation and verification + **Auditability**: Clear, readable verification code Any other ZK proof system satisfying the requirements in [Proof System Flexibility](#proof-system-flexibility) MAY be substituted. + **Solidity Contracts**: - [`PermissionedERC20.sol`](../assets/eip-7963/eip-permissioned-erc20/contracts/PermissionedERC20.sol) - ERC-20 token with oracle-based transfer validation - [`TransferOracle.sol`](../assets/eip-7963/eip-permissioned-erc20/contracts/TransferOracle.sol) - Manages one-time transfer approvals with ZK proof verification - [`ITransferOracle.sol`](../assets/eip-7963/eip-permissioned-erc20/contracts/interfaces/ITransferOracle.sol) - Oracle interface definition - [`RiscZeroVerifier.sol`](../assets/eip-7963/eip-permissioned-erc20/contracts/verifier/RiscZeroVerifier.sol) - RISC Zero proof verification contract + **ZK Guest Program**: - [`lib.rs`](../assets/eip-7963/eip-permissioned-erc20/zk/methods/guest/src/lib.rs) - Rust-based RISC Zero guest program for payment instruction validation and Merkle proof verification ## Security Considerations + **Replay Protection** – approvals are one-time and keyed by `proofId`. + **Field Binding** – Merkle proofs ensure all approval data comes from the same committed message. + **Oracle Risk** – issuers SHOULD deploy dedicated oracles; a compromised oracle only endangers its own tokens. + **Proof System Security** – the chosen ZK proof system must provide computational soundness and zero-knowledge properties. + **Hash Function Security** – implementations should use cryptographically secure hash functions (e.g., Keccak256, SHA256). + **Amount Validation** – strict bounds checking prevents amount manipulation attacks. ## Copyright Copyright and related rights waived via [CC0](../LICENSE.md).