ERC-7700 Cross-chain Storage Router Protocol

Draft · Other · created 2024-04-30

A standard that lets a smart contract route a data storage request to another contract on L1, to an L2, or to an external database, avoiding expensive mainnet storage costs. Data stored this way can be read back using CCIP-Read (EIP-3668).

Why it is needed

Storing data on the Ethereum mainnet (L1) is expensive in gas. For that reason, many services keep data on an L2 or an external database and only fetch it for reading using the existing CCIP-Read (EIP-3668) standard. However, since CCIP-Read only handles reads, each service has had to design its own method for safely writing data to the external storage. In particular, when storing to a database, a separate security mechanism must be designed so that an L1 contract can later verify the data is genuine. This standard defines a common way for a contract to indicate where a storage request should be routed, allowing apps to work without knowing what storage lies underneath. It is a proposal that pairs writing (CCIP-Store) with reading (CCIP-Read) to complete the lifecycle of cross-chain data.

In depth

Revert-based routing structure

When the storage function is called, instead of storing the data the L1 contract reverts with a StorageRoutedTo__() error that returns metadata about where the data is stored. The client interprets this revert and resubmits the data to the specified location. This document defines three routers: StorageRoutedToL1(), StorageRoutedToL2(), and StorageRoutedToDatabase(). Data stored this way is read by EIP-3668 (CCIP-Read) compatible contracts to complete the data lifecycle. New routers such as StorageRoutedToSolana() and StorageRoutedToIPFS() are also mentioned as examples.

L1/L2 Routers

StorageRoutedToL1(address contractL1) only needs the address of the L1 contract to route to. StorageRoutedToL2(address contractL2, uint256 chainId) only needs a list of L2 chain IDs and the corresponding contract addresses. In both cases the client must build a transaction with exactly the same calldata as the original call and call the same function on the routed contract. In other words, the calldata must be unchanged before and after routing. Metadata can be obtained from arbitrary on-chain code such as getMetadata(node), or it may be a global constant.

Database Router and the Client's Four Steps

StorageRoutedToDatabase(string gatewayUrl) only returns the gatewayUrl that will handle off-chain storage as the revert, and the L1 does not need to store any other data. After the revert, the client goes through four steps. First, it obtains a secret signature sigKeygen from the user to generate a deterministic dataSigner key pair. Second, it signs the calldata with the generated signer's private key to produce dataSig. Third, it obtains an approval signature from the user that approves the dataSigner. Fourth, it sends the calldata to the gateway together with dataSig, approval, and dataSigner.

Deterministic Key Generation keygen()

The signing key is deterministically derived from a wallet signature via keygen(username, sigKeygen, spice). username is a CAIP-10 identifier of the form eip155:${chainId}:${wallet}, built from the EIP-155 chain ID and the checksummed address. spice is an optional password from the user stretched with PBKDF2, where pepper is keccak256(abi.encodePacked(username)) and the iteration count is fixed at 500,000 to prevent brute-force attacks. inputKey is sha256(sigKeygen), and salt is sha256(`${username}:${spice}:${sigKeygen}`); these are fed into HKDF (dLen 42) to obtain a secp256k1 key pair. The sigKeygen message contains Origin (username), Protocol (in the form eth:${chainId}:${contract}, unique per contract), and Extradata (keccak256(abi.encodePacked(spice, wallet))).

Data Signing and Signer Approval

Since the derived signer is per-wallet, multiple keys on one node, or data for multiple nodes held by one wallet, can be signed in bulk in the background without prompting the user again. The dataSig message contains Origin, Data Type, and Data Value, where dataType joins nested keys with /. For example, ENS's text > avatar becomes text/avatar, and address > 60 becomes address/60. Since dataSigner is not stored on L1, an approval signed by the node's owner or manager must be submitted alongside it. The approval message contains Origin, the checksummed Approved Signer, and Approved By (CAIP-10). With this design, the number of wallet signatures is fixed at 2 regardless of how many updates are made.

CCIP-Read Compatible Payload and POST Format

The final payload for the off-chain data file is identified by the fixed selector callback.signedData.selector = 0x2b45eb2b and is constructed as abi.encode(['bytes4','address','bytes32','bytes32','bytes'], [funcSelector, dataSigner, dataSig, approval, encodedData]). The client sends this data together with the original value used for indexing to the gateway in a POST request. The POST body contains node, preimage, chainId, approval, and per-field value, signature, timestamp, and data. A CCIP-Read-compatible contract decodes the four parameters, verifies that approval is an approval from the owner or manager and that dataSig is a signature from dataSigner, then interprets and returns the encodedData value.

Rules for Adding New Routers

A StorageRoutedTo__() revert for a new storage backend must be registered as a separate ERC proposal that references this document. Each proposal must document in detail the router's structure and the metadata implementers must return, and must include the exact format of any message payload requiring a signature and a complete description of any custom cryptographic techniques used for security, accessibility, and privacy.

Proposal status

This document is still in Draft status. Since it is a proposal whose content may change, the latest source should be checked before implementation.

Things to watch out for

Original ERC · ← ERCs