[Draft-5] EIP-5559: Off-Chain Data Write Protocol

[nick.eth]

@NameSys

EIP-3668, or ‘CCIP-Read’ in short, has been key to retrieving off-chain data for a variety of contracts on Ethereum blockchain, ranging from price feeds for DeFi contracts, to more recently records for ENS users.

3668 was actually written for ENS, so this isn’t really accurate.

@NameSys

The latter case is more interesting

No need to throw shade on DeFi

I think this first paragraph can probably be omitted entirely, though.

@NameSys

EIP-5559 was the first step toward such a tolerant ‘CCIP-Write’ protocol which outlined how write deferrals could be made to L2 and centralised databases.

If this is going to be a PR to 5559, it shouldn’t refer to 5559 in the third person. This will replace that spec. In general the spec still needs rewriting to be a comprehensive replacement that doesn’t reference the earlier version.

@NameSys

The arbitrary metadata field captures all the relevant information that the client may require to update a user’s data on their favourite storage.

I mentioned this on the previous draft: I don’t see any reason to require all reverts to have the same signature and pack their domain-specific data into a metadata field. It seems clearer and cleaner to just encode that data as arguments of the revert directly.

@NameSys

A Solana storage handler simply requires the hex-encoded programId and the manager account on the Solana blockchain; programId is equivalent to a contract address on Solana.

Is Solana support something we really need to encode into 5559? I don’t see anyone demanding it, and each additional storage handler adds complexity for implementers.

Relatedly, this spec should specify whether clients are required to implement all the handlers or only some - and if only some, we need to consider how they can tell an unknown 5559-based revert apart from any other revert reason.

@NameSys

Since Solana natively uses base58 encoding in its virtual machine setup, programId values must be hex-encoded according to EIP-2308 for storage on Ethereum. These hex-encoded values in the metadata must eventually be decoded back to base58 for usage on Solana.

I think you mean to say that they should be base56 decoded and stored natively; hex is simply a representation commonly used by Ethereum libraries; data in Ethereum is natively stored as bytes.

@NameSys

(
    bytes32 programId, // Program (= contract) address on Solana; hex-encoded
    bytes32 account // Manager account on Solana; hex-encoded
) = getMetadata(node); // Arbitrary code
// programId = 0x37868885bbaf236c5d2e7a38952f709e796a1c99d6c9d142a1a41755d7660de3
// account = 0xe853e0dcc1e57656bd760325679ea960d958a0a704274a5a12330208ba0f428f
bytes metadata = abi.encode(programId, account);

It seems a little odd to show first unpacking these values, then packing them back up again. I think it would be clearer to leave out the first part and note that the derivation of those two values is up to the implementer.

@NameSys

// Decode off-chain data from encoded calldata in revert
let [node, key, value] = abi.decode(callData);

Isn’t callData supposed to be opaque to the implementing client?

@NameSys

// Call the Solana program using connected wallet with off-chain data
// [!] Only approved manager in the Solana program should call
if (wallet.publicKey === account === program.isManagerFor(account, msg.sender)) {
    await program(wallet).setValue(node, key, value);
}

Where does account come from? Isn’t access control also something that should be opaque to the implementer?

@NameSys

(
    address contract, // Contract address on L2
    uint256 chainId // L2 ChainID
) = getMetadata(node); // Arbitrary code
// contract = 0x32f94e75cde5fa48b6469323742e6004d701409b
// chainId = 21
bytes metadata = abi.encode(contract, chainId);

I mentioned this on the previous draft - a contract being able to prompt a user to make an arbitrary transaction to any chain is an enormous security vulnerability. Absent some other mitigation, we need to put restrictions on the payload.

@NameSys

If a dataSigner is included in the metadata

What is the mechanism by which it would not be included?

@NameSys

It is possible for the dataSigner to exist off-chain instead and not be returned in the metadata; for this scenario, refer to additional details in section ‘Off-Chain Signers’.

Why does being offchain preclude us from deriving an address for the signer?

@NameSys

In the above example, the client must first verify that the eth_sign is signed by a matching dataSigner

I would say instead that “the signature will be produced by the account with address dataSigner”; eth_sign is an implementation detail. It’s also worth noting that this could facilitate apps prompting the user to change wallets where necessary.

@NameSys

One way to bypass this difficulty is by storing the CID cheaply in an L2 contract; this method requires the client to update the data on both the decentralised storage as well as the L2 contract through two chained deferrals. CCIP-Read in this case is also expected to read from two storages to be able to fully handle a read call.

It would help to state explicitly that this standard doesn’t describe a mechanism for this.

@NameSys

The client must request the user for an IPNS signature verifiable against the IPNS CID returned in the ipnsSigner metadata.

Since both keys are derived from a single signature, can’t we instead encode the address of the signer from which the keys are derived?

@NameSys

There are several ways of providing this version data to the clients, e.g. a dedicated API, IPFS Pub/Sub, L2 indexer etc. It is therefore left up to individual implementations and/or protocols to choose their own desired method for version indexing

This is a basic requirement in order to implement this standard; I think we need to tell users how they can retrieve the version number.

@NameSys

e.g. ENSIP-16/-19 for ENS

Can you clarify? How would these standards help with this?

@NameSys

With version data in hand, the client can move on to signing the off-chain data using the dataSigner key.

If you’re not going to specify key derivation inline here, you at least need to mention that the key is derived, and where to read that section of the spec.

@NameSys

Once signed, the client must encode the off-chain data, the data signature and the approval signature in a CCIP-Read-compatible payload.

Can you be more specific here?

@NameSys

broadcast the IPNS update by signing and publishing the incremented version to the gatewayurl.

Using what API?

@NameSys

  // Calculate salt for keygen by hashing concatenated info, hashed password and hex-encoded signature using SHA256 algorithm
  let salt = sha256(`${info}:${sha256(password || "")}:${signature}`);

I don’t think there’s any reason to include the signature in the salt, since it’s already included in the kdf.

@NameSys

username may be prompted from the user by the client or determined by the protocol. This public field allows users to switch their protocol-specific IPNS namespace in the future. For instance, protocols may set username deterministically as equal to caip10 or some protocol-specific function of node; see example below.

This still needs to be more prescriptive. Say I’m implementing this in the ENS Manager app; how do I know how to treat the username?

@NameSys

During the initialisation step when the user sets on-chain ipnsSigner for the first time, the clients must prompt the user for their choice of storage type. Depending on the user’s choice, IPNS CID can be posted on chain with an appropriate index.

/* Setting IPNS signer on-chain during initialisation setup */
// IPNS signer derived from keygen() in CIDv1 format
let cid = 'bafyreibcli3vlmr4et6oekv3xdjx2sm6k4tioynbavmwgrsevklujpzywu';
// IPNS signer is function of node for 'nodeType' storage; remove constant 'e5010172002408011220' prefix from hex-encoded payload to save gas
if (storage === 'nodeType') setIpnsSigner(node, cid.encode('hex').replace('e5010172002408011220', ''));
// IPNS signer is function of wallet for 'walletType' storage; remove constant 'e5010172002408011220' prefix from hex-encoded payload to save gas
if (storage === 'walletType') setIpnsSigner(bytes32(uint256(uint160(wallet))), cid.encode('hex').replace('e5010172002408011220', ''));

This seems to add a lot of complexity to the protocol. Could we just specify one or the other? I’d be in favor of a single signer per wallet for simplicity; if users want to separate their names they can use multiple accounts, and this then mirrors the security profile of the names themselves.

@NameSys

CCIP-Write-enabled contracts should implement an appropriate internal mechanism for fetching IPNS signer as a function of node or wallet. This mechanism must follow the previously mentioned fallback strategy: the contract must first check if nodeType storage exists for a given node, and if no ipnsSigner exists for a node, then the contract should check for fallback walletType storage for a wallet and return the result in the revert.

I don’t think there’s any practical way to do this in a CCIP-Read callback that doesn’t just work out to relying on the gateway to be honest.

@NameSys

Revert StorageHandledByDatabase()

The case of StorageHandledByDatabase() handler is a subset of the decentralised storage handler, in the sense that the clients should simply skip interpreting IPNS related metadata. There is additionally no concept of storage types for off-chain database handlers. Other than that, the entire process is the same as StorageHandledByIPNS().

Based on reading this, I don’t understand how I would implement the signing process for StorageHandledByDatabase.

@NameSys

Off-Chain Signers

It is possible to further save on gas costs by not storing the dataSigner metadata on chain. In detail, instead of storing the dataSigner on chain for verification, clients can provide the user with the option to,

• request an approval for an off-chain dataSigner signed by the owner or manager of a node, and
• post this approval and the off-chain dataSigner along with the off-chain data in encoded form.

CCIP-Read-enabled contracts can then verify during resolution time that the approval attached with the data comes from the node’s manager or owner and that it approves the expected dataSigner. Using this mechanism of delegating signatures to an off-chain signer, no on-chain dataSigner needs to be posted. This additional saving comes at the cost of one additional approval signature approval that the clients must prompt from the user. This signature must have the following message payload format:

Requesting Signature To Approve Data Signer\n\nOrigin: ${username}\nApproved Signer: ${dataSigner}\nApproved By: ${caip10}

where dataSigner must be checksummed.

I think we should specify one mechanism or the other, not both.

It’s not clear to me why an additional signature is required here; can you elaborate?

@NameSys

Data Signatures

Signature(s) sigData accompanying the off-chain data must implement the following format in their message payloads:

Requesting Signature To Update Off-Chain Data\n\nOrigin: ${username}\nData Type: ${dataType}\nData Value: ${dataValue}

where dataType parameters are protocol-specific; they are defined in ENSIP-5, ENSIP-7 and ENSIP-9 for ENS (formerly EIP-634, EIP-1577 and EIP-2308 respectively), e.g. text/avatar, address/60 etc.

Is this intended to be part of the “Revert StorageHandledByDatabase()” section? I think it would be clearer if most of these sections were moved up the spec to the main section on each storage type, with only the bits that are actually shared kept in common down below.

@NameSys

Data Signatures

Signature(s) sigData accompanying the off-chain data must implement the following format in their message payloads:

Requesting Signature To Update Off-Chain Data\n\nOrigin: ${username}\nData Type: ${dataType}\nData Value: ${dataValue}

where dataType parameters are protocol-specific; they are defined in ENSIP-5, ENSIP-7 and ENSIP-9 for ENS (formerly EIP-634, EIP-1577 and EIP-2308 respectively), e.g. text/avatar, address/60 etc.

I don’t think there’s anywhere we specify a format like text/avatar or address/60. This needs more detail and some examples.

@NameSys

bytes encodedData = abi.encode(['bytes'], [dataValue])

Why is this nested? Is it intended to represent arbitrary data the app supplies?

And what “off-chain data file”? Is this specifying the encoding of IPFS files? Wouldn’t that be up to the CCIP-Read handler to define and interpret? Why prescribe it here?

@NameSys

For any storage other than a blockchain with a wallet extension, the client must call the gatewayUrl via a POST request. The structure of the POST is protocol-specific and left up to individual protocols to handle internally.

How can anyone implement this spec if it doesn’t specify an API for the POST request?

@NameSys

Note that we didn’t yet define the paths for the off-chain data files either, i.e. where should the file containing off-chain data be stored and later referred to in CCIP-Read-compatible contracts? These path schemes are also native to each implementation and are therefore left up to each protocol to define along with the previously mentioned parameters. The combined total of five parameters should be defined by the protocols through a native improvement proposal. For example, POST format, username, protocol, dataType, and path for ENS are described in ENSIP-19.

What do you mean by “protocol” in this context? Are you referring to new extensions of 5559 for new storage types? Most of this seems like something the implementer can specify, and needn’t standardize unless they want others to interoperate with it; in most cases the API that a CCIP-Read enabled contract uses to talk to its gateway is an internal implementation decision.

@NameSys

This proposal outlines the methods that clients should implement in order to handle StorageHandledByDatabase() and StorageHandledByIPNS() reverts made by off-chain resolvers. Methods in this document are designed to securely and autonomously incorporate off-chain storages - in particular databases and decentralised storages - in ENS resolvers. By implementing these methods in their resolvers to store records, ENS service providers can take advantage of cheap and often free nature of most off-chain storages.

I think that if 5559 is written correctly, there should be no need for a separate ENS-specific spec; a client should be able to simply implement 5559 and leave the ENS-specific details to the resolver contract and its gateway.

@NameSys

POST request for IPNS storage needs to be handled in a custom manner through the namesys-client (or w3name-client) client-side libraries.

A spec can’t and shouldn’t require a specific client library. It needs to specify things at a sufficient level of granularity that you could write a client library based on it.

I don’t think there’s any reason to specify internal data formats here, though - those are an implementation detail for specific resolvers to implement.

Can I suggest that going forward, GitHub would be a more productive way to collaborate on this? A PR has all the tools built in for commenting on specific lines, tracking revisions etc; doing this all via forum threads makes it difficult to keep track of the spec as it evolves.