ERC-7963: Oracle-Permissioned ERC-20 with ZK Proofs

Abstract

This proposal extends ERC-20 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.

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. Moving rules into a dedicated oracle contract 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", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.

Interfaces

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:

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.

The oracle MUST revert canTransfer unless msg.sender is token and token is a token the oracle serves. The oracle determines the issuer of token from its own configuration; the issuer is not supplied by the caller.

Validation Requirements

The oracle implementation MUST enforce the following validation rules when processing approveTransfer:

Approval Consumption Behavior

Single-Use Policy: Each approval is consumed entirely when a matching transfer occurs. Approvals MUST NOT 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

Payment Instruction Message Format

Payment instructions MUST be JSON objects with the following structure:

Field Definitions:

• messageId: Unique identifier for this payment instruction
• creationDateTime: When the instruction was created (RFC 3339 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)

   • 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, to all string fields

3. Timestamp Format: All timestamps MUST use RFC 3339 format in UTC (e.g., "2025-01-03T10:30:00Z")

Example Canonicalization:

Input:

Output (canonical):

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.

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 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 an issuer change its permissioning rules without redeploying the token. 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 MAY be substituted.

• Solidity Contracts:

  • PermissionedERC20.sol - ERC-20 token with oracle-based transfer validation
  • TransferOracle.sol - Manages one-time transfer approvals with ZK proof verification
  • ITransferOracle.sol - Oracle interface definition
  • RiscZeroVerifier.sol - RISC Zero proof verification contract

• ZK Guest Program:

  • 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.