ERC-7963 Oracle-permissioned ERC-20 (ZK proof) (Oracle-Permissioned ERC-20 with ZK Proofs)

Last Call · Tokens · created 2025-05-13

An extension standard that has an external oracle pre-approve ERC-20 token transfers and verifies onchain, via a zero-knowledge proof, that the approval matches an off-chain payment instruction.

Why it is needed

For an institution such as a bank or corporation to issue an asset as a token, it needs both ERC-20 compatibility and a means to legally control who sends to whom and why. However, embedding such control rules directly into each token contract is fragile and unstandardized. The token must be redeployed every time the rules change, and there is no common way to link onchain transfer records to payment instruction documents recognized by traditional finance. This standard separates the rules out into a dedicated oracle contract and has off-chain documents attested onchain via zero-knowledge proofs. As a result, every transfer becomes traceable, linked to a signed payment instruction recognized by traditional financial systems. Issuers can change the oracle logic without breaking ERC-20 compatibility, and DeFi protocols can interact with the permissioned token using the familiar ERC-20 flow.

What to implement

In depth

Transfer hook: every value movement goes through the oracle

A permissioned ERC-20 MUST call the oracle's canTransfer before updating balances on every transfer and transferFrom, and MUST revert the transfer if the oracle does not return a valid proofId. Mints and burns coming from or going to the zero address MAY skip this check. An OpenZeppelin-based implementation can satisfy this by overriding the internal _update(address from, address to, uint256 amount) function, and other implementations must enforce an equivalent check within their own transfer and transferFrom logic. On the oracle side, canTransfer should only be processed when msg.sender is the token itself and that token is one the oracle is responsible for, and the issuer is determined by the oracle's own configuration, not by the caller.

TransferApproval structure and validation rules at registration

A single approval consists of sender, recipient, a lower bound minAmt and upper bound maxAmt for the allowed amount (both inclusive), an expiry timestamp expiry (0 meaning no expiry), and a proofId obtained by concatenating root, debtorHash, and creditorHash and hashing with keccak256. When processing approveTransfer, the oracle MUST check that minAmt <= maxAmt, that sender and recipient are not the zero address, and that expiry is either later than the current time or 0. The reason for expressing the amount as a range is to support cases such as currency exchange where the exact amount is not known at approval time. The issuer can pre-sign an approval before the final exchange rate is settled.

Approval consumption rules: single-use, range matching, best match selection

An approval is single-use and is consumed in full once a matching transfer occurs. Partial consumption or reuse across multiple transfers MUST NOT be allowed. A transfer amount is valid only if it satisfies minAmt <= amount <= maxAmt, inclusive on both ends. If multiple valid approvals exist for the same (issuer, sender, recipient) combination, the oracle SHOULD consume the approval with the narrowest amount range. This is to prevent a small transfer from wasting a wide approval (e.g. 0 to 1000) when a narrow approval (e.g. 100 to 110) is also available. Expired approvals (expiry not 0 and block.timestamp >= expiry) must be ignored during validation, but MAY be kept in storage for audit purposes.

Payment instruction format and expression in milliunits

A payment instruction must be JSON with a fixed structure. It includes a unique identifier messageId, a creation timestamp creationDateTime, and under paymentInfo the debtor's and creditor's name, identifier, identifierScheme, the amount (amount.value, amount.currency), and the scheduled execution date executionDate. The identifier can be an Ethereum address, IBAN, BIC, etc., and identifierScheme indicates which kind it is. The amount must be written as an integer in milliunits (0.001 of the base currency unit) to avoid decimal rounding errors. For example, 1.50 USD is written as "1500". currency is a three-letter currency code such as USD or EUR, and executionDate becomes the approval's expiry time. This format is compatible with ISO 20022 pain.001, but implementers do not need to consult the paid ISO specification.

What canonicalization, the Merkle tree, and the proof guarantee

To obtain a deterministic hash, the instruction must be canonicalized before building the Merkle tree. RFC 8785 (JCS) is applied to the JSON to sort keys lexicographically and remove unnecessary whitespace, all strings use UTF-8 NFC normalization, and all timestamps use UTC-based RFC 3339 format. The public inputs are the instruction's Merkle root root, the debtor and creditor data hashes debtorHash and creditorHash, the amount range minAmountMilli and maxAmountMilli, the currency hash currencyHash, and the expiry. The proof system must verify that the hashes match the actual data, that the amount falls within the range, that all fields belong to the same committed message, and that the expiry is valid. Because the Merkle proof binds the fields into one message, it prevents field-substitution attacks that splice together legitimate data from different transactions.

Proof system neutrality and upgrade path

This standard is not tied to a specific zero-knowledge proof system. Any system, such as Groth16, PLONK, or STARK, can be used as long as it verifies the required public inputs, checks the Merkle proof for field binding, and preserves the same security guarantees. The token and oracle can be placed behind an ERC-1967 proxy. Because the verifier is stateless, it can be safely swapped out when a new proof system is adopted, and the oracle logic can be upgraded independently of the token contract. Giving each issuer a dedicated oracle means that if one is compromised, the damage is limited to that oracle's tokens.

Limitations of the reference implementation and proposal status

The reference implementation provides PermissionedERC20.sol, TransferOracle.sol, ITransferOracle.sol, and a RISC Zero guest program (lib.rs), but the verifier is a placeholder that only checks the shape of the inputs rather than actually verifying a zero-knowledge proof, and the guest's hashing and canonicalization helpers are also placeholders. The source explicitly states that this asset is not a complete implementation and is not suitable for production deployment. Implementers must separately provide a sound verifier and guest program that actually enforce the specification's proof and canonicalization requirements. This proposal is also currently in Review status, so its content may still change.

Things to watch out for

Original ERC · ← ERCs