--- eip: 7962 title: Key Hash Based Tokens description: Extends privacy to ERC-721 and ERC-20 tokens. author: Alex Tian (@dugubuyan), Zhixiong Pan (@nake13), Geoffrey (@stbrahms) , liyingxuan (@LiYingxuan) discussions-to: https://ethereum-magicians.org/t/key-based-tokens/24422 status: Draft type: Standards Track category: ERC created: 2025-05-16 requires: 20, 712, 721, 2612, 5564 --- ## Abstract This EIP proposes two token interfaces: **ERC-KeyHash721** for non-fungible tokens (NFTs) and **ERC-KeyHash20** for fungible tokens (similar to [ERC-20](./eip-20.md)). Both of them utilize cryptographic key hashes (“keyHash”, or `keccak256(key)`) instead of Ethereum addresses to manage ownership. This enhances privacy by authorizing by the public key’s ECDSA signature (address derived from `keccak256(key[1:])`) and matching `keyHash = keccak256(key)`, without storing addresses on‑chain. Consequently, it empowers users to conduct transactions using any address they choose. By separating ownership from transaction initiation, these standards allow gas fees to be paid by third parties without relinquishing token control, making them suitable for batch transactions and gas sponsorship. Security is ensured by implementing robust ECDSA signature verification on key functions (`transfer`) to prevent message tampering. ## Motivation Traditional [ERC-721](./eip-721.md) and [ERC-20](./eip-20.md) tokens bind ownership to Ethereum addresses, which are publicly visible and may be linked to identities, compromising privacy. The key hash-based ownership model allows owners to prove control without exposing addresses, ideal for anonymous collectibles, private transactions, or decentralized identity use cases. Additionally, separating ownership from gas fee payment enables third-party gas sponsorship, improving user experience in high-gas or batch transaction scenarios. This proposal aligns with the privacy principles of [ERC-5564](./eip-5564.md) (Stealth Addresses) and extends them to token ownership. ## 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. ### Overview This proposal defines two token interfaces: - `IERCKeyHash721`: For non-fungible tokens (NFTs), each identified by a unique `tokenId`, with ownership managed via `keyHash` (`keccak256(key)`). - `IERCKeyHash20`: For fungible tokens, with balances associated with `keyHash`. Token operations (`transfer`) require the owner's key(an uncompressed secp256k1 public key) and an ECDSA signature produced by the private key corresponding to the key (i.e., the address derived from `keccak256(key[1:])` excluding the 0x04 prefix) to prove ownership, ensuring only legitimate owners can execute actions. Signatures follow [EIP-712](./eip-712.md) structured data hashing to prevent message tampering, with per-keyHash nonces and deadlines to prevent replay attacks. Implementers MAY optionally add administrative functions such as `mint` (create new tokens) and `destroy` (remove tokens) based on application requirements. These functions are not part of the core interface of this ERC; if provided, they SHOULD enforce strict access control, correct supply accounting, and preserve the key‑hash privacy model without exposing addresses. Notably, the approve function is intentionally omitted. The key is designed for one-time use and is revealed only during token transfer transactions. Once revealed, holdings are typically migrated to fresh keyHashes; implementations MAY disallow reuse of previously revealed keyHash. Since transactions can be submitted by any address, the signature must be generated by the address derived from the key. This binds authorization to the key while allowing any relayer address to submit and pay gas. ### ERC-KeyHash721: Non-Fungible Token Interface #### Interface ```solidity interface IERCKeyHash721 { // Events event KeyHashTransfer721(uint256 indexed tokenId, bytes32 indexed fromKeyHash, bytes32 indexed toKeyHash); event KeyHashBurn721(uint256 indexed tokenId, bytes32 indexed ownerKeyHash); // View functions (aligned with ERC-721) function name() external view returns (string memory); function symbol() external view returns (string memory); function tokenURI(uint256 tokenId) external view returns (string memory); function totalSupply() external view returns (uint256); function ownerOf(uint256 tokenId) external view returns (bytes32); // State-changing functions function mint(uint256 tokenId, bytes32 keyHash) external; function transfer(uint256 tokenId, bytes32 toKeyHash, bytes memory key, bytes memory signature, uint256 deadline) external; function destroy(uint256 tokenId, bytes memory key, bytes memory signature, uint256 deadline) external; } ``` #### Function Descriptions ##### `transfer` ```solidity transfer(uint256 tokenId, bytes32 toKeyHash, bytes memory key, bytes memory signature, uint256 deadline) external; ``` **Description**: Transfers the specified token from the current owner's `keyHash` to `toKeyHash`. The caller provides the owner's key to prove ownership. The signature is verified using [EIP-712](./eip-712.md) structured data. **Parameters**: - `tokenId`: `uint256` - The token ID to transfer. - `toKeyHash`: `bytes32` - The new owner's key hash. - `key`: `bytes` - MUST be a 65-byte uncompressed secp256k1 public key with prefix 0x04. - `signature`: `bytes` - ECDSA signature produced by the private key corresponding to the key, verifying ownership and preventing malicious relay attacks. - `deadline`: `uint256` - Signature expiration timestamp (Unix seconds). **Signature Message**: [EIP-712](./eip-712.md) structured data: ```solidity struct Transfer { uint256 tokenId; bytes32 toKeyHash; uint256 nonce; uint256 deadline; } ``` **Events**: Emits `KeyHashTransfer721(tokenId, fromKeyHash, toKeyHash)`. **Requirements**: - Token MUST exist (non-zero `fromKeyHash`). - `keccak256(key)` MUST equal the current `fromKeyHash`. - Signature MUST be valid. - `block.timestamp` MUST be <= `deadline`. - `toKeyHash` MUST NOT be zero. - Updates ownership to `toKeyHash`. - **Other Functions**: `name`, `symbol`, `tokenURI`, and `totalSupply` align with [ERC-721](./eip-721.md) . `ownerOf` returns `bytes32` (keyHash) instead of an address.`tokenURI` is part of the core interface and MAY return an empty string if metadata is not provided. #### Key Concepts - **Key (`key`)**: An uncompressed secp256k1 public key (65 bytes, starting with 0x04), used to prove ownership. Implementations MUST validate the key format: ```solidity require(key.length == 65 && key[0] == 0x04, "BAD_KEY_FMT"); ``` - **Key Hash (`keyHash`)**: A `bytes32` value representing `keccak256(key)`, identifying ownership without exposing addresses. - **Token Existence**: A token exists if its `keyHash` is non-zero. - **Nonce**: Nonces are tracked per keyHash and per contract. Each ERC-KeyHash contract maintains its ownmapping(bytes32 =>uint256)keyNonces. Cross-contract replay is already prevented by the EIP-712 domain (verifyingContract, chainId). Signers MUST serialize operations for the same keyHashwithin the same contract. ### ERC-KeyHash20: Fungible Token Interface #### Interface ```solidity interface IERCKeyHash20 { // Events event KeyHashTransfer20(bytes32 indexed fromKeyHash, bytes32 indexed toKeyHash, uint256 amount); // View functions (aligned with ERC-20) function name() external view returns (string memory); function symbol() external view returns (string memory); function decimals() external view returns (uint8); function totalSupply() external view returns (uint256); function balanceOf(bytes32 keyHash) external view returns (uint256); // State-changing functions function mint(bytes32 keyHash, uint256 amount) external; function transfer(bytes32 fromKeyHash, bytes32 toKeyHash, uint256 amount, bytes memory key, bytes memory signature, uint256 deadline, bytes32 leftKeyHash) external; } ``` #### Function Descriptions ##### `transfer` ```solidity transfer(bytes32 fromKeyHash, bytes32 toKeyHash, uint256 amount, bytes memory key, bytes memory signature, uint256 deadline, bytes32 leftKeyHash) ``` **Description**: Transfers `amount` tokens from `fromKeyHash` to `toKeyHash`, with remaining balance assigned to `leftKeyHash` (controlled by the sender). The caller provides the owner's key to prove ownership. The signature is verified using [EIP-712](./eip-712.md) structured data. Mimics Bitcoin's UTXO model for partial transfers. **Parameters**: - `fromKeyHash`: `bytes32` - Token owner's key hash. - `toKeyHash`: `bytes32` - Recipient's key hash. - `amount`: `uint256` - Amount to transfer. - `key`: `bytes` - MUST be a 65-byte uncompressed secp256k1 public key with prefix 0x04. - `signature`: `bytes` - ECDSA signature. - `deadline`: `uint256` - Signature expiration timestamp. - `leftKeyHash`: `bytes32` - Key hash for remaining balance (`balance - amount`). MUST NOT equal `toKeyHash` or `fromKeyHash` (strict mode to enforce key rotation and unlinkability). **Signature Message**: [EIP-712](./eip-712.md) structured data: ```solidity struct Transfer { bytes32 fromKeyHash; bytes32 toKeyHash; uint256 amount; uint256 nonce; uint256 deadline; bytes32 leftKeyHash; } ``` **Events**: Emits `KeyHashTransfer20(fromKeyHash, toKeyHash, amount)`. **Requirements**: - `fromKeyHash` MUST have sufficient balance (`balanceOf[fromKeyHash] >= amount`). - `keccak256(key)` MUST equal `fromKeyHash`. - Signature MUST be valid. - `block.timestamp` MUST be <= `deadline`. - `toKeyHash` and `leftKeyHash` MUST NOT be zero. - Updates balances: `balanceOf[fromKeyHash] = 0`, `balanceOf[toKeyHash] += amount`, `balanceOf[leftKeyHash] += (original balance - amount)`. - **Other Functions**: `name`, `symbol`, `decimals`, and `totalSupply` align with [ERC-20](./eip-20.md). `balanceOf` uses `bytes32` parameter. ### Signature Verification For `transfer`: 1. Verify `keccak256(key) == current keyHash`. 2. Compute [EIP-712](./eip-712.md) message hash: ```solidity bytes32 digest = keccak256(abi.encodePacked( "\x19\x01", DOMAIN_SEPARATOR, keccak256(abi.encode( TYPE_HASH, // Struct-specific type hash params // Struct fields (e.g., tokenId, toKeyHash, nonce, deadline) )) )); ``` 3. Recover signer address using `ecrecover(digest, signature)`. 4. REQUIRE signer == address(uint160(uint256(keccak256(key[1:])))), where key is a 65‑byte uncompressed secp256k1 public key (0x04 || X || Y) and key[1:] denotes the 64‑byte XY payload (prefix removed) 5. On successful verification, increment _keyNonces[currentOwnerKeyHash] (i.e., _keyNonces[ownerKeyHash] for ERC‑KeyHash721 and _keyNonces[fromKeyHash] for ERC‑KeyHash20) to prevent replay. 6. Verify `block.timestamp <= deadline`. ### Requirements - Contracts MUST maintain mappings: - ERC-KeyHash721: `tokenId` to `keyHash`. - ERC-KeyHash20: `keyHash` to balance. - MUST use per-keyHash nonces (`mapping(bytes32 => uint256) _keyNonces`) for replay protection. - MUST implement [EIP-712](./eip-712.md) for signature hashing. - MUST enforce `deadline` to limit signature validity. - MUST verify signatures and hash keys in `transfer`. - For ERC-KeyHash20, MUST enforce strict mode for `leftKeyHash` by requiring it to be different from both `toKeyHash` and `fromKeyHash`. This prevents change consolidation with the recipient or original account, promoting key rotation and unlinkability. ## Rationale ### Advantages of Key Hash - **Privacy**: `ownerOf` and `balanceOf` return `keyHash`, not addresses. Users can use unique key pairs per token or balance, reducing linkability. - **Gas Fee Separation**: Anyone can call `transfer` with a valid signature, paying gas fees, enabling batch transactions or gas sponsorship. - **Flexibility**: Aligns with [ERC-5564](./eip-5564.md) stealth addresses, extending privacy to tokens. ### Transfer Design - Open to any caller with valid signatures, ensuring only owners operate while allowing gas sponsorship. - [EIP-712](./eip-712.md) signatures prevent message tampering by including all critical parameters. - Per-keyHash nonces and deadlines prevent replay attacks. ## Backwards Compatibility This proposal is not compatible with [ERC-721](./eip-721.md) or [ERC-20](./eip-20.md) due to `bytes32` key hashes instead of addresses. Adapters can bridge to existing systems for privacy-focused use cases. ## Reference Implementation ### ERC-KeyHash721 Implementation ```solidity pragma solidity ^0.8.0; import "@openzeppelin/contracts/utils/cryptography/ECDSA.sol"; import "@openzeppelin/contracts/utils/cryptography/EIP712.sol"; contract KeyHashERC721 is EIP712 { using ECDSA for bytes32; string public name; string public symbol; mapping(uint256 => bytes32) private _tokenKeyHashes; mapping(uint256 => bool) private _destroyedTokens; uint256 public totalSupply; mapping(bytes32 => uint256) private _keyNonces; event KeyHashTransfer721(uint256 indexed tokenId, bytes32 indexed fromKeyHash, bytes32 indexed toKeyHash); event KeyHashBurn721(uint256 indexed tokenId, bytes32 indexed ownerKeyHash); bytes32 private constant TRANSFER_TYPEHASH = keccak256( "Transfer(uint256 tokenId,bytes32 toKeyHash,uint256 nonce,uint256 deadline)" ); bytes32 private constant DESTROY_TYPEHASH = keccak256( "Destroy(uint256 tokenId,uint256 nonce,uint256 deadline)" ); constructor(string memory _name, string memory _symbol) EIP712("KeyHashERC721", "1") { name = _name; symbol = _symbol; } function ownerOf(uint256 tokenId) external view returns (bytes32) { require(_tokenKeyHashes[tokenId] != 0 && !_destroyedTokens[tokenId], "Token does not exist"); return _tokenKeyHashes[tokenId]; } function tokenURI(uint256) external pure returns (string memory) { return ""; } function transfer( uint256 tokenId, bytes32 toKeyHash, bytes memory key, bytes memory signature, uint256 deadline ) external { require(toKeyHash != bytes32(0), "Invalid recipient hash"); require(_tokenKeyHashes[tokenId] != 0 && !_destroyedTokens[tokenId], "Token does not exist"); require(block.timestamp <= deadline, "Signature expired"); require(key.length == 65 && key[0] == 0x04, "BAD_KEY_FMT"); bytes32 currentKeyHash = _tokenKeyHashes[tokenId]; require(keccak256(key) == currentKeyHash, "BAD_KEYHASH"); uint256 nonce = _keyNonces[currentKeyHash]; bytes32 structHash = keccak256(abi.encode( TRANSFER_TYPEHASH, tokenId, toKeyHash, nonce, deadline )); bytes32 digest = _hashTypedDataV4(structHash); address signer = digest.recover(signature); address expectedAddress = _addressFromUncompressedKey(key); require(signer == expectedAddress, "Invalid signature"); _keyNonces[currentKeyHash] = nonce + 1; // 验签通过后再自增 _tokenKeyHashes[tokenId] = toKeyHash; emit KeyHashTransfer721(tokenId, currentKeyHash, toKeyHash); } function getNonce(bytes32 keyHash) external view returns (uint256) { return _keyNonces[keyHash]; } function _addressFromUncompressedKey(bytes memory key) internal pure returns (address) { // key: 65 bytes, [0] = 0x04, [1..32] = X, [33..64] = Y require(key.length == 65 && key[0] == 0x04, "BAD_KEY_FMT"); bytes32 x; bytes32 y; assembly { x := mload(add(key, 0x21)) // key[1..32] y := mload(add(key, 0x41)) // key[33..64] } bytes32 h = keccak256(abi.encodePacked(x, y)); // 64-byte XY return address(uint160(uint256(h))); } } ``` ### ERC-KeyHash20 Implementation ```solidity pragma solidity ^0.8.0; import "@openzeppelin/contracts/utils/cryptography/ECDSA.sol"; import "@openzeppelin/contracts/utils/cryptography/EIP712.sol"; contract KeyHashERC20 is EIP712 { using ECDSA for bytes32; string public name; string public symbol; uint8 public decimals; mapping(bytes32 => uint256) public balanceOf; uint256 public totalSupply; mapping(bytes32 => uint256) private _keyNonces; event KeyHashTransfer20(bytes32 indexed fromKeyHash, bytes32 indexed toKeyHash, uint256 amount); bytes32 private constant TRANSFER_TYPEHASH = keccak256( "Transfer(bytes32 fromKeyHash,bytes32 toKeyHash,uint256 amount,uint256 nonce,uint256 deadline,bytes32 leftKeyHash)" ); constructor(string memory _name, string memory _symbol) EIP712("KeyHashERC20", "1") { name = _name; symbol = _symbol; decimals = 18; } function transfer( bytes32 fromKeyHash, bytes32 toKeyHash, uint256 amount, bytes memory key, bytes memory signature, uint256 deadline, bytes32 leftKeyHash ) external { require(balanceOf[fromKeyHash] >= amount, "Insufficient balance"); require(toKeyHash != bytes32(0), "Invalid recipient hash"); require(leftKeyHash != bytes32(0), "Invalid leftKeyHash"); require(leftKeyHash != toKeyHash, "LEFT_EQ_TO"); require(leftKeyHash != fromKeyHash, "LEFT_EQ_FROM"); require(block.timestamp <= deadline, "Signature expired"); require(key.length == 65 && key[0] == 0x04, "BAD_KEY_FMT"); require(keccak256(key) == fromKeyHash, "BAD_KEYHASH"); uint256 nonce = _keyNonces[fromKeyHash]; bytes32 structHash = keccak256(abi.encode( TRANSFER_TYPEHASH, fromKeyHash, toKeyHash, amount, nonce, deadline, leftKeyHash )); bytes32 digest = _hashTypedDataV4(structHash); address signer = digest.recover(signature); address expectedAddress = _addressFromUncompressedKey(key); require(signer == expectedAddress, "Invalid signature"); _keyNonces[fromKeyHash] = nonce + 1; // 验签通过后再自增 uint256 remaining = balanceOf[fromKeyHash] - amount; balanceOf[fromKeyHash] = 0; balanceOf[toKeyHash] += amount; balanceOf[leftKeyHash] += remaining; emit KeyHashTransfer20(fromKeyHash, toKeyHash, amount); } function getNonce(bytes32 keyHash) external view returns (uint256) { return _keyNonces[keyHash]; } function _addressFromUncompressedKey(bytes memory key) internal pure returns (address) { // key: 65 bytes, [0] = 0x04, [1..32] = X, [33..64] = Y require(key.length == 65 && key[0] == 0x04, "BAD_KEY_FMT"); bytes32 x; bytes32 y; assembly { x := mload(add(key, 0x21)) // key[1..32] y := mload(add(key, 0x41)) // key[33..64] } bytes32 h = keccak256(abi.encodePacked(x, y)); // 64-byte XY return address(uint160(uint256(h))); } } ``` ## Security Considerations - **Replay Attacks**: - **Mitigation**: Per-keyHash nonces (`_keyNonces[keyHash]`) increment after each operation, invalidating old signatures. - **Design**: Similar to [EIP-2612](./eip-2612.md) permit mechanism, ensuring owner-controlled nonce sequences. - **Message Tampering**: - **Mitigation**: [EIP-712](./eip-712.md) structured signatures include all critical parameters (`tokenId`, `toKeyHash`, `amount`, `leftKeyHash`, etc.), preventing relayer tampering. Signatures are function-specific (`TRANSFER_TYPEHASH`, `DESTROY_TYPEHASH`). - **Audit**: Contracts MUST be audited to ensure no parameter omissions or hash collisions. - **Signature Expiration**: - **Mitigation**: `deadline` parameter ensures signatures expire, reducing risks of leaked signatures. - **Privacy Limitations**: - **Issue**: Public keys (key) are revealed in calldata; the corresponding Ethereum addresses can be derived off‑chain from keccak256(key[1:]). Use fresh keys (toKeyHash / leftKeyHash) to reduce linkability. - **Recommendation**: Use new key pairs per token or balance to minimize linkability. Store `hashKey` securely, as it is sensitive. - **Key Management**: - **Risk**: Loss or compromise of the private key corresponding to `key` results in loss of control. Store private keys securely. - **Recommendation**: Use safe systems to save `key`. - **Gas Costs**: - **Issue**: Signature verification and [EIP-712](./eip-712.md) hashing increase gas costs. - **Recommendation**: Optimize implementations and consider gas sponsorship to offset costs. - **Signature Malleability**: Implementations MUST reject malleable signatures (low‑S, v ∈ {27, 28}). OpenZeppelin’s ECDSA helpers enforce these checks by default. ## Copyright Copyright and related rights waived via [CC0](../LICENSE.md).