ERC-7962 Key-hash based token (Key Hash Based Tokens)
Review · Tokens · created 2025-05-16
A standard that records token ownership using a hash of the public key (keyHash) instead of an Ethereum address, allowing NFTs and fungible tokens to be held and transferred without leaving an address on-chain.
Why it is needed
Existing ERC-721 and ERC-20 tie token ownership to an Ethereum address. Addresses are publicly visible and can be linked to an identity, so who holds which token is exposed and privacy is weakened. Also, transfer transactions usually must be sent directly by the owner's address, so moving a token requires that address to hold ether for gas, and it is hard to build a structure where someone else pays the gas. This proposal manages ownership by the hash of a public key instead of an address, so ownership can be proven without exposing an address. It fits anonymous collectibles, private trades, and decentralized identity, and separating ownership from gas payment also enables batch processing or gas sponsorship where a third party covers the gas. It is a proposal to extend the privacy principle of stealth addresses (ERC-5564) to token ownership itself.
What to implement
event KeyHashTransfer721(uint256 indexed tokenId, bytes32 indexed fromKeyHash, bytes32 indexed toKeyHash);: An event emitted whenever an NFT's owning keyHash changes. Minting is recorded with fromKeyHash as 0, and burning with toKeyHash as 0function name() external view returns (string memory);: Returns the token namefunction symbol() external view returns (string memory);: Returns the token symbolfunction tokenURI(uint256 tokenId) external view returns (string memory);: Returns the token metadata URI. May return an empty string if there is no metadatafunction totalSupply() external view returns (uint256);: Returns the total supplyfunction ownerOf(uint256 tokenId) external view returns (bytes32);: Returns the owner of the token as a keyHash (bytes32) instead of an addressfunction nonces(bytes32 keyHash) external view returns (uint256);: Returns the nonce value that the next valid signature for the given keyHash must usefunction transfer(uint256 tokenId, bytes32 toKeyHash, bytes memory key, bytes memory signature, uint256 deadline) external;: Changes the NFT's owning keyHash to toKeyHash by presenting the owner's public key and an EIP-712 signature. Anyone can call this and pay the gas on the owner's behalffunction decimals() external view returns (uint8);: Returns the token's number of decimal placesfunction balanceOf(bytes32 keyHash) external view returns (uint256);: Returns the balance linked to a keyHash instead of an addressfunction transfer(bytes32 fromKeyHash, bytes32 toKeyHash, uint256 amount, bytes memory key, bytes memory signature, uint256 deadline, bytes32 leftKeyHash) external;: Sends amount from fromKeyHash's balance to toKeyHash and moves the entire remaining amount to leftKeyHash, a new keyHash for change
In depth
Key hash ownership model
key is a 65-byte uncompressed secp256k1 public key starting with 0x04, and implementations must verify key.length == 65 && key[0] == 0x04. keyHash is a bytes32 value produced by keccak256(key) and is used as the ownership identifier. ERC-KeyHash721 must maintain a mapping from tokenId to keyHash, and ERC-KeyHash20 must maintain a mapping from keyHash to balance. The address used for signature verification is derived from keccak256(key[1:]) over the 64-byte XY with the 0x04 prefix removed. An NFT is considered to exist if its keyHash is nonzero
KeyHash721's transfer specification
transfer(tokenId, toKeyHash, key, signature, deadline) moves the NFT from its current owning keyHash to toKeyHash. The signed message is the EIP-712 struct Transfer(tokenId, toKeyHash, nonce, deadline). The requirements are that the token exists (fromKeyHash is nonzero), keccak256(key) equals the current fromKeyHash, the signature is valid, block.timestamp is at or before the deadline, and toKeyHash is nonzero. On success it emits KeyHashTransfer721(tokenId, fromKeyHash, toKeyHash). ownerOf returns a bytes32 keyHash instead of an address
KeyHash20's UTXO-style change separation
KeyHash20's transfer is modeled on Bitcoin's UTXO scheme: it sends amount to toKeyHash and moves the entire remaining balance (balance - amount) to leftKeyHash. As a result, balanceOf[fromKeyHash] becomes 0, and the amount is added to toKeyHash and leftKeyHash. leftKeyHash must not equal toKeyHash or fromKeyHash, and must not be 0. Since the key is exposed in calldata during a transfer, leaving the change at fromKeyHash would leave funds sitting at a keyHash whose public key is already known. Strict mode guarantees that the public keys of all keyHashes holding a balance have not yet been revealed. Even if the change is zero, the KeyHashTransfer20 event must still be emitted exactly once
Signature verification procedure and nonces
The verification order is as follows. Check that keccak256(key) matches the current keyHash, compute the EIP-712 digest, then recover the signer address with ecrecover. The signer must equal address(uint160(uint256(keccak256(key[1:])))). After verification passes, _keyNonces[keyHash] is incremented to prevent reuse, and block.timestamp is checked to be at or before the deadline. Nonces are managed per keyHash and per contract, and can be looked up with nonces(bytes32). Cross-contract reuse is prevented by the verifyingContract and chainId fields of the EIP-712 domain. Contracts must implement ERC-5267's eip712Domain() so wallets can know the domain, and operations on the same keyHash within the same contract must be processed in order by the signer
Events and indexing rules
Every change in ownership or balance must be observable through an event. In KeyHash721, token creation emits KeyHashTransfer721 with fromKeyHash = bytes32(0), and burning emits it with toKeyHash = bytes32(0). In KeyHash20, creation emits KeyHashTransfer20(bytes32(0), keyHash, bytes32(0), amount, 0), and burning emits KeyHashTransfer20(keyHash, bytes32(0), bytes32(0), amount, 0). For each event, an indexer subtracts amount + leftAmount from fromKeyHash and adds amount to toKeyHash and leftAmount to leftKeyHash, while ignoring updates to bytes32(0). A wallet can reconstruct all of its holdings by filtering the indexed toKeyHash and leftKeyHash topics against the set of keyHashes it controls
The deliberate omission of approve and one-time keys
This standard has no approve. The key is designed to be one-time use, revealed only in the transfer transaction, and once revealed it is standard practice to move the holdings to a new keyHash. Implementations may disallow reuse of a keyHash that has already been revealed. Since a transaction can be submitted from any address, authority is tied not to the caller's address but to the signature from the address derived from the key. Administrative functions like mint and destroy are not part of the core interface, and if provided, strict access control, accurate supply accounting, and preserving the privacy model that does not expose addresses are recommended. Also, because it uses a bytes32 keyHash, it is not compatible with existing ERC-721 or ERC-20, though an adapter can bridge it to existing systems
Proposal status
This proposal is currently in Review status. Since it is still under review, the interface and detailed specification may change going forward
Things to watch out for
- Public key exposure and linkability: When transferring, the public key (key) is exposed in calldata, and the corresponding Ethereum address can be computed off-chain as keccak256(key[1:]). A new key pair should be used for each token or balance, with new keys used for toKeyHash and leftKeyHash, to reduce linkability
- The transaction graph is public: Since fromKeyHash, toKeyHash, and leftKeyHash all appear together in the same calldata, the flow of funds within the contract can be tracked publicly, and the chain of change keyHashes can be followed indefinitely. Since balanceOf is public and leftKeyHash must be a new value, the pre-transfer balance can also be computed as amount + balanceOf(leftKeyHash). If secrecy of amounts or flows is needed, additional mechanisms such as zero-knowledge proofs or mixing are required
- Key loss and leakage: If the private key corresponding to a key is lost or leaked, control of the token is lost. The private key must be kept in a secure system, while the keyHash itself is a value exposed on chain and does not need separate protection
- Rejecting signature malleability: Implementations must reject malleable signatures. The s value must lie in the lower half of the curve order, and v must be 27 or 28. OpenZeppelin's ECDSA helper performs this check by default
- Increased gas cost: Signature verification and EIP-712 hashing increase gas costs compared to ordinary tokens. Implementations should be optimized, and gas sponsorship should be considered to offset the cost