EIP-7713: Box type for EIP-712 messages

A mechanism for EIP-712 messages to contain parameters of arbitrary type

Abstract

This EIP defines a new type box for use in EIP-712 messages. A box value is a value of an arbitrary struct type whose underlying type is encapsulated and hidden from the outer struct but transparent and type-checkable by the wallet, and thus able to be fully inspected by the user prior to signing. A verifying contract can be made agnostic to the underlying type of a box value, but this type is not erased and can be verified on-chain if necessary.

Motivation

EIP-712 signatures have become a widely used primitive for users to express and authorize intents off-chain. Wide-ranging applications are able to define parameterized messages for users to sign in their wallet through a general-purpose interface that clearly surfaces the type, parameters, and domain of authorization. This crucially applies to hardware wallets as a last line of defense.

The general-purpose nature of EIP-712 is key to its success, but in addition wallets are able to develop special-purpose interfaces and capabilities for specific types of messages as they become more widely used. For example, ERC-2612 Permits are a well-known EIP-712 message that wallets display to the user in a special way that clearly surfaces the known implications and risks of signing.

Special-purpose interfaces improve usability and security for the user, but rely on standardized message types such as Permits. This EIP concerns the ability to standardize messages that contain within them parameters of arbitrary type.

A recent example is found in ERC-7683, which defines a struct with the following member:

/// @dev Arbitrary implementation-specific data
/// Can be used to define tokens, amounts, destination chains, fees, settlement parameters,
/// or any other order-type specific information
bytes orderData;

Defining this parameter with type bytes enables the message to contain data of arbitrary type and is sufficient to bind the signature to implementation-specific data, but it amounts to type erasure. As a consequence, the user will be presented with an opaque bytestring in hexadecimal format in the wallet’s signing interface. This negates the benefit of using EIP-712 signatures because the true contents of the parameter are invisible to the wallet’s general-purpose interface.

Another example is found in recent efforts to make ERC-1271 signatures secure against replay. Achieving this without making the message contents opaque to the signer requires embedding an application’s EIP-712 message inside an outer message that binds it to a specific account. The type of the outer message depends on the type of the inner message, and making the type reproducible by the smart contract account on-chain for verification requires an inefficient scheme to communicate the string-encoded type of the inner message as a part of the signature.

Both of these use cases would benefit from the ability to define EIP-712 struct parameters of arbitrary type in such a way that the verifying contract can be agnostic to the type of the parameter’s value in a message while the wallet retains the ability to transparently display it to the user for inspection.

Specification

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 and RFC 8174.

EIP-712 is extended as follows:

Typed structured data

A struct type may contain a boxed member by declaring it with type box. Example:

struct Envelope {
    address account;
    box contents;
}

A boxed member has an underlying unboxed type, which is an arbitrary struct type and may be different in each message.

encodeType

A boxed member is encoded as "box " || name. For example, the above Envelope struct is encoded as Envelope(address account,box contents).

encodeData

A boxed value is encoded as its underlying unboxed value, i.e., hashStruct(value) = keccak256(typeHash, encodeData(value)) where typeHash corresponds to the unboxed type and encodeData is operating on a value of that type.

signTypedData schema

A signature request for an EIP-712 message that involves a boxed member shall include the unboxed type as a part of the message object. A boxed value must be an object with properties value, primaryType, and types. The value shall be type-checked and encoded according to primaryType and types, analogously to an EIP-712 message (though without the \x19 prefix). The types defined in the message outside of the boxed value shall not be in scope for the encoding of a boxed value.

For example, a message for the Envelope type above may be represented as:

{
    domain: ...,
    primaryType: 'Envelope',
    types: {
        Envelope: [
            { name: 'account', type: 'address' },
            { name: 'contents', type: 'box' }
        ]
    },
    message: {
        account: '0x...',
        contents: {
            primaryType: 'Mail',
            types: {
                Mail: [
                    { name: 'greeting', type: 'string' }
                ]
            },
            value: {
                greeting: 'Hello world'
            }
        },
    }
}

JSON Schema of a boxed value

{
  type: 'object',
  properties: {
    value: {type: 'object'},
    primaryType: {type: 'string'},
    types: {
      type: 'object',
      additionalProperties: {
        type: 'array',
        items: {
          type: 'object',
          properties: {
            name: {type: 'string'},
            type: {type: 'string'}
          },
          required: ['name', 'type']
        }
      }
    }
  },
  required: ['value', 'primaryType', 'types']
}

Rationale

TBD

Security Considerations

Needs discussion.

Copyright

Copyright and related rights waived via CC0.

Citation

Please cite this document as:

Francisco Giordano (@frangio), "EIP-7713: Box type for EIP-712 messages [DRAFT]," Ethereum Improvement Proposals, no. 7713, May 2024. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-7713.