Add EIP: Box type for EIP-712 messages (#8594)

* Add EIP: Box types for EIP-712 messages * add example * add discussions link * use gh username * move link * add 7683 link * add syntax highlighting * Update EIPS/eip-draft_box_types_712.md Co-authored-by: xinbenlv <[email protected]> * Update EIPS/eip-draft_box_types_712.md Co-authored-by: Andrew B Coathup <[email protected]> * rename * update title * reword abstract * wording * fix github username * add whitespace around code block * remove comments * review wording * change 7683 link * try erc link * Revert "try erc link" This reverts commit dd596a0. * Update eip-7713.md --------- Co-authored-by: xinbenlv <[email protected]> Co-authored-by: Andrew B Coathup <[email protected]> Co-authored-by: Sam Wilson <[email protected]>
ethereum · Jun 25, 2024 · e1ec3e7 · e1ec3e7
1 parent fafbc56
commit e1ec3e7
Showing 1 changed file with 138 additions and 0 deletions.
diff --git a/EIPS/eip-7713.md b/EIPS/eip-7713.md
@@ -0,0 +1,138 @@
+---
+eip: 7713
+title: Box type for EIP-712 messages
+description: A mechanism for EIP-712 messages to contain parameters of arbitrary type
+author: Francisco Giordano (@frangio)
+discussions-to: https://ethereum-magicians.org/t/eip-7713-box-types-for-eip-712-messages/20092
+status: Draft
+type: Standards Track
+category: Interface
+created: 2024-05-23
+requires: 712
+---
+
+## Abstract
+
+This EIP defines a new type `box` for use in [EIP-712](./eip-712.md) 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](./eip-2612.md) 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](./eip-7683.md), which defines a struct with the following member:
+
+```solidity
+/// @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](./eip-1271.md) 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:
+
+```solidity
+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:
+
+```js
+{
+    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
+
+```js
+{
+  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 <!-- TODO -->
+
+## Security Considerations
+
+Needs discussion. <!-- TODO -->
+
+## Copyright
+
+Copyright and related rights waived via [CC0](../LICENSE.md).