From b766c1d1cc918e5aac6a1d6b5d5a9a7c0cf02db8 Mon Sep 17 00:00:00 2001 From: Michael Standen Date: Tue, 22 Oct 2024 11:31:45 +1300 Subject: [PATCH 01/13] Add Wallet Transaction Intents draft --- ERCS/erc-TBA.md | 495 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 495 insertions(+) create mode 100644 ERCS/erc-TBA.md diff --git a/ERCS/erc-TBA.md b/ERCS/erc-TBA.md new file mode 100644 index 0000000000..8ffbc9b2d0 --- /dev/null +++ b/ERCS/erc-TBA.md @@ -0,0 +1,495 @@ +--- +title: Wallet Transaction Intents +description: Wallet support for transactions with prerequisites +author: Agustín Aguilar (@agusx1211), Michael Standen (@ScreamingHawk) +discussions-to: +status: Draft +type: Standards Track +category: ERC +created: 2024-10-22 +--- + +## Abstract + +This ERC addresses the lack of communication channels between the dapp and smart contract wallets. Wallets are tasked with sending transactions on behalf of the user, but dapps craft these transactions. The challenge is that dapps don't have a way of communicating the prerequisites for these transactions, so wallets can't fulfill them. + +To solve this issue, an additional optional field is included in the transaction request. This field is a list of "requirements" that the wallet has to fulfill for the requested transactions to be considered "ready." + +Wallets can use this list of requirements, alongside their knowledge about the addresses of the user, to decide how to act next. Depending on the availability of funds and the list of requirements, the options could be: send the transaction right away, send the transaction with a prefix that fulfills the requirements, or ask the user to select a path to fulfill the requirements. + +Wallets would be tasked with finding all possible paths to fulfill these requirements, while dapps SHOULD NOT attempt to check the requirements themselves, letting the wallet handle scenarios like "low balance" or "low allowance." + +## Motivation + +It is fairly common for dapps to reside only on one network, but this comes at the cost of shrinking the direct liquidity that these dapps can access. This happens because most users only have funds on a limited number of networks. As the number of networks grows, the likelihood of intersection between the networks chosen by the dapp and the user decreases. + +Given that dapps don't have a way of communicating with the wallet about their "final intent," they can only use `eth_sendTransaction` to communicate the last action that the user should take. However, it is up to the user to "guess" what prior actions need to be executed to fulfill the prerequisites of that final action. + +This guessing may involve consolidating funds into a single network or exchanging assets into another asset accepted by the dapp. This is a cumbersome process for the user and results in a highly degraded UX. + +## 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. + +A new JSON-RPC method called `wallet_sendIntendedTransaction` is defined. This method takes the same object parameters as `eth_sendTransaction` (`from`, `to`, `gas`, `gasPrice`, `value`, `data`, `maxFeePerGas`, `maxPriorityFeePerGas`), and additionally defines a new `requirements` field. + +The `requirements` field MUST contain a list of "prerequisites" that an address must have before the transaction is considered valid. Wallets MUST ensure that these `requirements` are met before attempting to send the transaction, which is expected to fail otherwise. + +Any number of `requirements` MAY be passed with `wallet_sendIntendedTransaction`. The JSON schema for any requirement is: + +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A string representing the type of the requirement payload. For example, it could denote the category or classification of the requirement." + }, + "version": { + "type": "number", + "description": "A number indicating the version of this type of requirement. Useful for handling different versions of the same payload type." + }, + "payload": { + "type": "object", + "description": "An object defining the specifics of the requirement. The structure of this object depends on the 'type' and 'version' fields." + } + }, + "required": ["type", "version", "payload"], + "additionalProperties": false +} +``` + +Example: + +```json +{ + "type": "ERC20_MIN_BALANCE", + "version": 1, + "payload": { + // See below... + } +} +``` + +### Requirement Types + +This document specifies an initial set of requirement types. The standard supports updating these requirements or adding new kinds of requirements. + +Updates and new requirements will be added in supplementary ERCs. Wallets SHOULD support the latest versions of each requirement type, but MAY choose to support older versions as well. Wallets MAY choose to support only a subset of the requirement types. + +Wallets MAY support custom requirement types that are not part of the standard. These custom requirement types MUST NOT conflict with the standard requirement types. + +Versions MAY NOT be backwards compatible. Dapps and wallets MUST check the `version` field to determine how to handle the payload. + +#### ERC20 Minimum Balance + +Requires that a given address MUST have a minimum balance of an [ERC-20](./eip-20.md) token. + +* Type: `ERC20_MIN_BALANCE` +* Version: `1` +* Schema: + +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "properties": { + "owner": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The Ethereum address of the account that must meet the minimum token amount." + }, + "token": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The Ethereum address of the ERC20 token contract. For example, the USDC token address: 0xA0b86991C6218b36c1d19D4a2e9EB0cE3606eB48." + }, + "minAmount": { + "type": "string", + "pattern": "^[0-9]+$", + "description": "The minimum number of ERC20 tokens (as a string) that the address must hold." + } + }, + "required": ["owner", "token", "minAmount"], + "additionalProperties": false +} +``` + +Example: + +```json +{ + "type": "ERC20_MIN_BALANCE", + "version": 1, + "payload": { + "owner": "0x1234567890abcdef1234567890abcdef12345678", + "token": "0xA0b86991C6218b36c1d19D4a2e9EB0cE3606eB48", + "minAmount": "1000" + } +} +``` + +#### ERC20 Minimum Allowance + +Requires that a given address MUST have a minimum allowance of an [ERC-20](./eip-20.md) token for a specified spender. + +* Type: `ERC20_MIN_ALLOWANCE` +* Version: `1` +* Schema: + +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "properties": { + "token": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The Ethereum address of the ERC20 token contract." + }, + "owner": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The Ethereum address of the wallet that owns the tokens." + }, + "spender": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The Ethereum address allowed to spend the tokens." + }, + "minAllowance": { + "type": "string", + "pattern": "^[0-9]+$", + "description": "The minimum required allowance as a string." + } + }, + "required": ["token", "owner", "spender", "minAllowance"], + "additionalProperties": false +} +``` + +Example: + +```json +{ + "type": "ERC20_MIN_ALLOWANCE", + "version": 1, + "payload": { + "token": "0xA0b86991C6218b36c1d19D4a2e9EB0cE3606eB48", + "owner": "0x1234567890abcdef1234567890abcdef12345678", + "spender": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd", + "minAllowance": "1000" + } +} +``` + +#### ERC721 Ownership + +Requires that a given address MUST own a specific [ERC-721](./eip-721.md) token. + +* Type: `ERC721_OWNERSHIP` +* Version: `1` +* Schema: + +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "properties": { + "token": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The Ethereum address of the ERC721 token contract." + }, + "owner": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The Ethereum address of the wallet that should own the token." + }, + "tokenId": { + "type": "string", + "pattern": "^[0-9]+$", + "description": "The ID of the token that must be owned." + } + }, + "required": ["token", "owner", "tokenId"], + "additionalProperties": false +} +``` + +Example: + +```json +{ + "type": "ERC721_OWNERSHIP", + "version": 1, + "payload": { + "token": "0x1234567890abcdef1234567890abcdef12345678", + "owner": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd", + "tokenId": "1" + } +} +``` + +#### ERC721 Approval + +Requires that a given address MUST have an [ERC-721](./eip-721.md) token approved for a specified spender. + +* Type: `ERC721_APPROVAL` +* Version: `1` +* Schema: + +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "properties": { + "token": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The Ethereum address of the ERC721 token contract." + }, + "owner": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The Ethereum address of the wallet that owns the token." + }, + "spender": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The Ethereum address that should have approval." + }, + "tokenId": { + "type": "string", + "pattern": "^[0-9]+$", + "description": "The ID of the token that must be approved." + } + }, + "required": ["token", "owner", "spender", "tokenId"], + "additionalProperties": false +} +``` + +Example: + +```json +{ + "type": "ERC721_APPROVAL", + "version": 1, + "payload": { + "token": "0x1234567890abcdef1234567890abcdef12345678", + "owner": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd", + "spender": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd", + "tokenId": "1" + } +} +``` + +#### ERC1155 Minimum Balance + +Requires that a given address MUST have a minimum balance of an [ERC-1155](./eip-1155.md) token. + +* Type: `ERC1155_MIN_BALANCE` +* Version: `1` +* Schema: + +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "properties": { + "token": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The Ethereum address of the ERC1155 token contract." + }, + "owner": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The Ethereum address of the wallet that should own the token." + }, + "tokenId": { + "type": "string", + "pattern": "^[0-9]+$", + "description": "The ID of the token that must be owned." + }, + "minBalance": { + "type": "string", + "pattern": "^[0-9]+$", + "description": "The minimum balance required." + } + }, + "required": ["token", "owner", "tokenId", "minBalance"], + "additionalProperties": false +} +``` + +Example: + +```json +{ + "type": "ERC1155_MIN_BALANCE", + "version": 1, + "payload": { + "token": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd", + "owner": "0x1234567890abcdef1234567890abcdef12345678", + "tokenId": "2", + "minBalance": "10" + } +} +``` + +#### ERC1155 Approval + +Requires that a given address MUST have an [ERC-1155](./eip-1155.md) token approved for a specified operator. + +* Type: `ERC1155_APPROVAL` +* Version: `1` +* Schema: + +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "properties": { + "token": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The Ethereum address of the ERC1155 token contract." + }, + "owner": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The Ethereum address of the wallet that owns the tokens." + }, + "operator": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]{40}$", + "description": "The Ethereum address that should have operator approval." + } + }, + "required": ["token", "owner", "operator"], + "additionalProperties": false +} +``` + +Example: + +```json +{ + "type": "ERC1155_APPROVAL", + "version": 1, + "payload": { + "token": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd", + "owner": "0x1234567890abcdef1234567890abcdef12345678", + "operator": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd" + } +} +``` + +### Capabilities Discovery + +To enable dapps to use the `wallet_sendIntendedTransaction` method effectively, they need to understand which requirement types and versions the wallet supports. A new JSON-RPC method called `wallet_intentCapabilities` JSON-RPC is defined to address this by allowing dapps to query the wallet’s supported requirement types and versions, ensuring compatibility. + +The `wallet_intentCapabilities` method takes no parameters and returns an object detailing the supported requirement types and versions. This helps dapps construct valid transaction requests and avoid potential incompatibilities. + +The response is a JSON object structured as follows: + +* `requirementTypes`: An array of objects, each representing a supported requirement type. + * `type`: A string specifying the requirement type (e.g., `ERC20_MIN_BALANCE`, `ERC721_OWNERSHIP`). + * `versions`: An array of numbers indicating the versions of this requirement type supported by the wallet. + +Example response: + +```json +{ + "requirementTypes": [ + { + "type": "ERC20_MIN_BALANCE", + "versions": [1] + }, + { + "type": "ERC20_MIN_ALLOWANCE", + "versions": [1] + }, + { + "type": "ERC721_OWNERSHIP", + "versions": [1] + }, + { + "type": "ERC721_APPROVAL", + "versions": [1] + }, + { + "type": "ERC1155_MIN_BALANCE", + "versions": [1] + }, + { + "type": "ERC1155_APPROVAL", + "versions": [1] + } + ] +} +``` + +Dapps SHOULD call `wallet_intentCapabilities` before sending an `wallet_sendIntendedTransaction` request to identify the requirement types and versions supported by the wallet. + +A wallet that does not support the `wallet_intentCapabilities` method MUST be assumed lack any support for the `wallet_sendIntendedTransaction` method. + +A wallet MAY choose to extend the `wallet_intentCapabilities` result with capabilities specific to the wallet implementation. These additional capabilities MAY NOT be standardized and are intended for wallet specific features. + +## Rationale + +### Requirement Types + +The initial set of requirement types was chosen to cover the most common prerequisites for transactions. These requirements are based on the most common token standards ([ERC-20](./eip-20.md), [ERC-721](./eip-721.md), and [ERC-1155](./eip-1155.md)) and their most common use cases. + +The use of the `type` and `version` fields allows for future extensibility. New requirement types can be added without breaking compatibility with existing wallets. Wallets can choose to support new requirement types and versions as they see fit. + +This solution is preferrable over a single requirement type with a complex payload, as it allows wallets to support only the requirement types they are interested in. This reduces the complexity of the implementation and the risk of errors. + +### Capabilities Discovery + +Dapps can use the `wallet_intentCapabilities` method to query the wallet's supported requirement types and versions before sending an `wallet_sendIntendedTransaction` request. This allows dapps to adjust their behavior based on the wallet's capabilities. + +Allowing wallets to extend the `wallet_intentCapabilities` response with additional capabilities specific to the wallet implementation enables wallets to communicate additional information to dapps. For dapps that are tightly integrated with a specific wallet, this can provide additional feature support and optimizations. + +## Backwards Compatibility + +No backward compatibility issues found. + +## Reference Implementation + +A high level sample flow of how an transaction with an `ERC20_MIN_ALLOWANCE` requirement could be handled: + +```mermaid +sequenceDiagram + participant D as Dapp + participant W as Wallet Provider + participant C as Chain + D->>+W: wallet_sendIntendedTransaction + W->>C: ERC20.allowance() + alt Not approved + W->>W: Prepend approve calldata + end + W->>+C: Submit tx + deactivate C + W-->>-D: Done +``` + +Note that implementation details will vary between wallets. The wallet MAY require user interaction to approve the altered transaction, or MAY automatically approve the transaction if the requirements are met. + +For more complex requirements, the flow may involve multiple steps, such as consolidating funds or exchanging assets. Wallets are expected to handle these scenarios and provide a seamless experience to the user. + +## Security Considerations + +This ERC does not introduce any new security risks or trust assumptions. + +Users already trust their wallet provider to craft, manipulate and send transactions on their behalf. This ERC only adds a new field to the transaction request, which the wallet can use to make more informed decisions about transaction construction. + +Dapps may opt out of using this feature if they wish to handle requirement fulfillment themselves. + +## Copyright + +Copyright and related rights waived via [CC0](../LICENSE.md). From 8a504bd7faf0cd9e3da1936722b0abb980496f65 Mon Sep 17 00:00:00 2001 From: Michael Standen Date: Tue, 22 Oct 2024 13:58:43 +1300 Subject: [PATCH 02/13] Add discussion link --- ERCS/erc-TBA.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ERCS/erc-TBA.md b/ERCS/erc-TBA.md index 8ffbc9b2d0..fec8d00b29 100644 --- a/ERCS/erc-TBA.md +++ b/ERCS/erc-TBA.md @@ -2,7 +2,7 @@ title: Wallet Transaction Intents description: Wallet support for transactions with prerequisites author: Agustín Aguilar (@agusx1211), Michael Standen (@ScreamingHawk) -discussions-to: +discussions-to: https://ethereum-magicians.org/t/wallet-transaction-intents/21426 status: Draft type: Standards Track category: ERC From fa05264c875c06937d20be0a04ae20c4a4b0363c Mon Sep 17 00:00:00 2001 From: Michael Standen Date: Thu, 24 Oct 2024 07:14:39 +1300 Subject: [PATCH 03/13] Update ERC number and discussion link --- ERCS/{erc-TBA.md => erc-7795.md} | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) rename ERCS/{erc-TBA.md => erc-7795.md} (99%) diff --git a/ERCS/erc-TBA.md b/ERCS/erc-7795.md similarity index 99% rename from ERCS/erc-TBA.md rename to ERCS/erc-7795.md index fec8d00b29..8827d21e61 100644 --- a/ERCS/erc-TBA.md +++ b/ERCS/erc-7795.md @@ -1,8 +1,9 @@ --- +eip: 7795 title: Wallet Transaction Intents description: Wallet support for transactions with prerequisites author: Agustín Aguilar (@agusx1211), Michael Standen (@ScreamingHawk) -discussions-to: https://ethereum-magicians.org/t/wallet-transaction-intents/21426 +discussions-to: https://ethereum-magicians.org/t/erc-7795-wallet-transaction-intents/21426 status: Draft type: Standards Track category: ERC From 30e6ba338bd4ed9b86b3a1dede3fa3fa50857735 Mon Sep 17 00:00:00 2001 From: Michael Standen Date: Thu, 24 Oct 2024 09:50:33 +1300 Subject: [PATCH 04/13] Format ERC with dash --- ERCS/erc-7795.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/ERCS/erc-7795.md b/ERCS/erc-7795.md index 8827d21e61..cb56bc0536 100644 --- a/ERCS/erc-7795.md +++ b/ERCS/erc-7795.md @@ -83,7 +83,7 @@ Wallets MAY support custom requirement types that are not part of the standard. Versions MAY NOT be backwards compatible. Dapps and wallets MUST check the `version` field to determine how to handle the payload. -#### ERC20 Minimum Balance +#### ERC-20 Minimum Balance Requires that a given address MUST have a minimum balance of an [ERC-20](./eip-20.md) token. @@ -131,7 +131,7 @@ Example: } ``` -#### ERC20 Minimum Allowance +#### ERC-20 Minimum Allowance Requires that a given address MUST have a minimum allowance of an [ERC-20](./eip-20.md) token for a specified spender. @@ -185,7 +185,7 @@ Example: } ``` -#### ERC721 Ownership +#### ERC-721 Ownership Requires that a given address MUST own a specific [ERC-721](./eip-721.md) token. @@ -233,7 +233,7 @@ Example: } ``` -#### ERC721 Approval +#### ERC-721 Approval Requires that a given address MUST have an [ERC-721](./eip-721.md) token approved for a specified spender. @@ -287,7 +287,7 @@ Example: } ``` -#### ERC1155 Minimum Balance +#### ERC-1155 Minimum Balance Requires that a given address MUST have a minimum balance of an [ERC-1155](./eip-1155.md) token. @@ -341,7 +341,7 @@ Example: } ``` -#### ERC1155 Approval +#### ERC-1155 Approval Requires that a given address MUST have an [ERC-1155](./eip-1155.md) token approved for a specified operator. From 99ff91cb69bc82ec0c71d70a30cb5b3facaceae7 Mon Sep 17 00:00:00 2001 From: Michael Standen Date: Thu, 24 Oct 2024 09:53:46 +1300 Subject: [PATCH 05/13] First ERC ref is a link --- ERCS/erc-7795.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ERCS/erc-7795.md b/ERCS/erc-7795.md index cb56bc0536..e93ebab5a9 100644 --- a/ERCS/erc-7795.md +++ b/ERCS/erc-7795.md @@ -75,7 +75,7 @@ Example: ### Requirement Types -This document specifies an initial set of requirement types. The standard supports updating these requirements or adding new kinds of requirements. +This document specifies an initial set of requirement types. The initial set includes requirements for common uses of [ERC-20](./eip-20.md), [ERC-721](./eip-721.md), and [ERC-1155](./eip-1155.md). The standard supports updating these requirements or adding new kinds of requirements. Updates and new requirements will be added in supplementary ERCs. Wallets SHOULD support the latest versions of each requirement type, but MAY choose to support older versions as well. Wallets MAY choose to support only a subset of the requirement types. From b94f379bf3528044b01dba202f37c3744600c048 Mon Sep 17 00:00:00 2001 From: Agusx1211 Date: Mon, 28 Oct 2024 17:07:31 +0000 Subject: [PATCH 06/13] Add authors --- ERCS/erc-7795.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ERCS/erc-7795.md b/ERCS/erc-7795.md index e93ebab5a9..a726404acb 100644 --- a/ERCS/erc-7795.md +++ b/ERCS/erc-7795.md @@ -2,7 +2,7 @@ eip: 7795 title: Wallet Transaction Intents description: Wallet support for transactions with prerequisites -author: Agustín Aguilar (@agusx1211), Michael Standen (@ScreamingHawk) +author: Agustín Aguilar (@agusx1211), Michael Standen (@ScreamingHawk), Peter Kieltyka (@pkieltyka), William Hua (@attente), Philippe Castonguay (@PhABC) discussions-to: https://ethereum-magicians.org/t/erc-7795-wallet-transaction-intents/21426 status: Draft type: Standards Track From 13d70b5fd3a448a6f2bbafae6ce4d0c6e22111ec Mon Sep 17 00:00:00 2001 From: Agusx1211 Date: Thu, 31 Oct 2024 16:52:01 +0000 Subject: [PATCH 07/13] Add example use cases --- ERCS/erc-7795.md | 82 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) diff --git a/ERCS/erc-7795.md b/ERCS/erc-7795.md index a726404acb..80e7137e17 100644 --- a/ERCS/erc-7795.md +++ b/ERCS/erc-7795.md @@ -491,6 +491,88 @@ Users already trust their wallet provider to craft, manipulate and send transact Dapps may opt out of using this feature if they wish to handle requirement fulfillment themselves. +## Examples + +This ERC serves as a foundational component for building user experiences that rely on cross-chain actions. It can be leveraged in various ways, depending on the combination of use cases and wallet implementations. + +### Marketplace Interaction with Bridge Using an EOA Wallet + +A user wants to purchase ERC-721 tokens on **Chain A** but only has funds on **Chain B**. The user employs an Externally Owned Account (EOA) based wallet. The dApp requests an intended transaction using `wallet_sendIntendedTransaction`, which includes the marketplace transaction alongside the requirement of owning funds on Chain A. + +In this scenario, the wallet **MAY** prompt the user to sign the necessary transactions to fulfill the requirements before proceeding with the main transaction. The wallet **SHOULD** compute possible solutions to meet the requirements and **MUST** ensure that these prerequisites are met prior to executing the main transaction. + +```mermaid +sequenceDiagram + participant D as Dapp + participant W as Wallet + participant U as User + participant CA as Chain A + participant CB as Chain B + D->>+W: wallet_sendIntendedTransaction + W->>W: Compute solutions for requirements + W->>U: Prompt to sign bridge transaction from Chain B to Chain A + U-->>W: User approves + W->>CB: Send bridge transaction + CB-->>W: Transaction receipt + W->>W: Wait for requirements to be fulfilled + W->>U: Prompt to sign intended transaction + U-->>W: User approves + W->>CA: Send main transaction + CA-->>W: Transaction receipt + W-->>-D: Transaction completed +``` + +### Bridge, Swap, and Payment Using a Smart Contract Wallet + +A dApp requests a payment from a user, which **MUST** be made in **Token Z** on **Chain B**, but the user holds **Token Y** on **Chain A**. The dApp requests an intended transaction using `wallet_sendIntendedTransaction`, including the payment transaction alongside the requirement of having enough Token Z on Chain B. + +In this scenario, the Smart Contract Wallet **MAY** prompt the user to sign all the necessary transactions at once, executing them in the appropriate order. The wallet **SHOULD** compute solutions to fulfill the requirements and **MUST** ensure that all prerequisites are satisfied before proceeding with the main transaction. + +The signed transactions **MAY** be sent simultaneously to bundlers, who execute them as they become available, allowing the operation to complete even if the wallet disconnects. + +```mermaid +sequenceDiagram + participant D as Dapp + participant W as Wallet + participant U as User + participant CA as Chain A + participant CB as Chain B + participant BA as Bundler A + participant BB as Bundler B + D->>+W: wallet_sendIntendedTransaction + W->>W: Compute solutions for requirements + par Single interaction + W->>U: Prompt sign bridge from A to B + W->>U: Prompt sign swap from Y to Z + W->>U: Prompt sign intended transaction + end + U-->>W: Approved + par In parallel + W->>BA: Send bridge transaction + W->>BB: Send swap transaction + W->>BB: Send main transaction + end + activate BB + BB-->>BB: Wait for requirements + BA->>CA: Execute bridge transaction + CA-->>BA: Receipt + BA-->>W: Receipt + BB-->>BB: Got requirements for swap + deactivate BB + BB->>CB: Execute swap transaction + CB-->>BB: Receipt + BB-->>BB: Wait for requirements + BB->>CB: Execute main transaction + CB-->>BB: Receipt + BB-->>W: Receipt + W-->>-D: Done +``` + +These examples demonstrate how this ERC enables communication between dApps and wallets, making complex cross-chain interactions possible. Wallets **MAY** implement and execute these operations in any way they see fit, including using solver networks or manually sending the transactions. By leveraging the `wallet_sendIntendedTransaction` method, wallets and dApps **CAN** provide a seamless user experience for complex transactions that involve multiple steps across different chains.## Examples + +This ERC serves as a foundational component for building user experiences that rely on cross-chain actions. It can be leveraged in various ways, depending on the combination of use cases and wallet implementations. + + ## Copyright Copyright and related rights waived via [CC0](../LICENSE.md). From 6b3c27bcf9a22fa6896f9b4721f70da6fdb7ca82 Mon Sep 17 00:00:00 2001 From: Michael Standen Date: Mon, 25 Nov 2024 11:14:46 +1300 Subject: [PATCH 08/13] Leverage 5792 for 7795 --- ERCS/erc-7795.md | 733 ++++++++++++++++++++++++----------------------- 1 file changed, 372 insertions(+), 361 deletions(-) diff --git a/ERCS/erc-7795.md b/ERCS/erc-7795.md index 80e7137e17..de82e3cb0b 100644 --- a/ERCS/erc-7795.md +++ b/ERCS/erc-7795.md @@ -1,63 +1,46 @@ --- eip: 7795 -title: Wallet Transaction Intents -description: Wallet support for transactions with prerequisites +title: Wallet Call Token Requirements +description: EIP-5792 extension for common ERC-20, ERC-721 and ERC-1155 transaction prerequisites author: Agustín Aguilar (@agusx1211), Michael Standen (@ScreamingHawk), Peter Kieltyka (@pkieltyka), William Hua (@attente), Philippe Castonguay (@PhABC) discussions-to: https://ethereum-magicians.org/t/erc-7795-wallet-transaction-intents/21426 status: Draft type: Standards Track category: ERC created: 2024-10-22 +requires: 5792 --- ## Abstract -This ERC addresses the lack of communication channels between the dapp and smart contract wallets. Wallets are tasked with sending transactions on behalf of the user, but dapps craft these transactions. The challenge is that dapps don't have a way of communicating the prerequisites for these transactions, so wallets can't fulfill them. - -To solve this issue, an additional optional field is included in the transaction request. This field is a list of "requirements" that the wallet has to fulfill for the requested transactions to be considered "ready." - -Wallets can use this list of requirements, alongside their knowledge about the addresses of the user, to decide how to act next. Depending on the availability of funds and the list of requirements, the options could be: send the transaction right away, send the transaction with a prefix that fulfills the requirements, or ask the user to select a path to fulfill the requirements. - -Wallets would be tasked with finding all possible paths to fulfill these requirements, while dapps SHOULD NOT attempt to check the requirements themselves, letting the wallet handle scenarios like "low balance" or "low allowance." +This ERC extends [EIP-5792](./eip-5792.md) by defining capabilities that allow dApps to specify common token prerequisites for transactions, such as having certain ERC-20, ERC-721, or ERC-1155 tokens. Wallets can then help users meet these requirements before executing the transactions. ## Motivation -It is fairly common for dapps to reside only on one network, but this comes at the cost of shrinking the direct liquidity that these dapps can access. This happens because most users only have funds on a limited number of networks. As the number of networks grows, the likelihood of intersection between the networks chosen by the dapp and the user decreases. +It is fairly common for dApps to reside only on one network, but this comes at the cost of shrinking the direct liquidity that these dApps can access. This happens because most users only have funds on a limited number of networks. As the number of networks grows, the likelihood of intersection between the networks chosen by the dApp and the user decreases. -Given that dapps don't have a way of communicating with the wallet about their "final intent," they can only use `eth_sendTransaction` to communicate the last action that the user should take. However, it is up to the user to "guess" what prior actions need to be executed to fulfill the prerequisites of that final action. +Given that dApps don't have a way of communicating with the wallet about their "final intent", they can only use transaction requests to communicate the last action that the user should take. However, it is up to the user to "guess" what prior actions need to be executed to fulfill the prerequisites of that final action. -This guessing may involve consolidating funds into a single network or exchanging assets into another asset accepted by the dapp. This is a cumbersome process for the user and results in a highly degraded UX. +This guessing may involve consolidating funds into a single network or exchanging assets into another asset accepted by the dApp. This is a cumbersome process for the user and results in a highly degraded UX. ## 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. -A new JSON-RPC method called `wallet_sendIntendedTransaction` is defined. This method takes the same object parameters as `eth_sendTransaction` (`from`, `to`, `gas`, `gasPrice`, `value`, `data`, `maxFeePerGas`, `maxPriorityFeePerGas`), and additionally defines a new `requirements` field. +This ERC extends [EIP-5792](./eip-5792.md) by adding new capabilities that can be used with the `wallet_sendCalls` and `wallet_getCapabilities` methods. These capabilities allow specifying different types of transaction requirements for common token standards that wallets can handle. -The `requirements` field MUST contain a list of "prerequisites" that an address must have before the transaction is considered valid. Wallets MUST ensure that these `requirements` are met before attempting to send the transaction, which is expected to fail otherwise. +### ERC-20 Minimum Balance Capability -Any number of `requirements` MAY be passed with `wallet_sendIntendedTransaction`. The JSON schema for any requirement is: +A dApp can use the `erc20MinBalance` capability in a `wallet_sendCalls` request to request that a wallet ensure the owner has a minimum balance of a specified ERC-20 token. -```json -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "A string representing the type of the requirement payload. For example, it could denote the category or classification of the requirement." - }, - "version": { - "type": "number", - "description": "A number indicating the version of this type of requirement. Useful for handling different versions of the same payload type." - }, - "payload": { - "type": "object", - "description": "An object defining the specifics of the requirement. The structure of this object depends on the 'type' and 'version' fields." - } - }, - "required": ["type", "version", "payload"], - "additionalProperties": false +#### `wallet_getCapabilities` Response + +Schema: + +```typescript +type Erc20MinBalanceCapability = { + supported: boolean; + versions: string[]; } ``` @@ -65,55 +48,72 @@ Example: ```json { - "type": "ERC20_MIN_BALANCE", - "version": 1, - "payload": { - // See below... + "0x1": { + "erc20MinBalance": { + "supported": true, + "versions": ["1.0"] + } } } ``` -### Requirement Types +#### `wallet_sendCalls` Request + +Version 1.0 Schema: + +```typescript +type Erc20MinBalanceParams = { + version: string; + chainId: `0x${string}`; // Hex chain id + owner: `0x${string}`; // Address + token: `0x${string}`; // Address + minAmount: `0x${string}`; // Hex value +}; +``` -This document specifies an initial set of requirement types. The initial set includes requirements for common uses of [ERC-20](./eip-20.md), [ERC-721](./eip-721.md), and [ERC-1155](./eip-1155.md). The standard supports updating these requirements or adding new kinds of requirements. +This capability requests that the `owner` address **MUST** have a balance of at least `minAmount` of `token` on `chainId` before the transaction is executed. -Updates and new requirements will be added in supplementary ERCs. Wallets SHOULD support the latest versions of each requirement type, but MAY choose to support older versions as well. Wallets MAY choose to support only a subset of the requirement types. +Example: -Wallets MAY support custom requirement types that are not part of the standard. These custom requirement types MUST NOT conflict with the standard requirement types. +```json +[ + { + "version": "1.0", + "from": "0xd46e8dd67c5d32be8058bb8eb970870f07244567", + "calls": [ + { + "to": "0xd46e8dd67c5d32be8058bb8eb970870f07244567", + "value": "0x00", + "data": "0x...", + "chainId": "0x01", + } + ], + "capabilities": { + "erc20MinBalance": { + "version": "1.0", + "chainId": "0x01", + "owner": "0xd46e8dd67c5d32be8058bb8eb970870f07244567", + "token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", + "minAmount": "0x0f4240" + } + } + } +] +``` -Versions MAY NOT be backwards compatible. Dapps and wallets MUST check the `version` field to determine how to handle the payload. +### ERC-20 Minimum Allowance Capability -#### ERC-20 Minimum Balance +A dApp can use the `erc20MinAllowance` capability in a `wallet_sendCalls` request to request that a wallet ensure the owner has a minimum allowance of a specified ERC-20 token. +Note this capability does not imply that the owner has a balance of the token, only that the allowance is equal to or greater than the specified amount. -Requires that a given address MUST have a minimum balance of an [ERC-20](./eip-20.md) token. +#### `wallet_getCapabilities` Response -* Type: `ERC20_MIN_BALANCE` -* Version: `1` -* Schema: +Schema: -```json -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "type": "object", - "properties": { - "owner": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The Ethereum address of the account that must meet the minimum token amount." - }, - "token": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The Ethereum address of the ERC20 token contract. For example, the USDC token address: 0xA0b86991C6218b36c1d19D4a2e9EB0cE3606eB48." - }, - "minAmount": { - "type": "string", - "pattern": "^[0-9]+$", - "description": "The minimum number of ERC20 tokens (as a string) that the address must hold." - } - }, - "required": ["owner", "token", "minAmount"], - "additionalProperties": false +```typescript +type Erc20MinAllowanceCapability = { + supported: boolean; + versions: string[]; } ``` @@ -121,101 +121,73 @@ Example: ```json { - "type": "ERC20_MIN_BALANCE", - "version": 1, - "payload": { - "owner": "0x1234567890abcdef1234567890abcdef12345678", - "token": "0xA0b86991C6218b36c1d19D4a2e9EB0cE3606eB48", - "minAmount": "1000" - } + "0x1": { + "erc20MinAllowance": { + "supported": true, + "versions": ["1.0"] + } + } } ``` -#### ERC-20 Minimum Allowance - -Requires that a given address MUST have a minimum allowance of an [ERC-20](./eip-20.md) token for a specified spender. +#### `wallet_sendCalls` Request -* Type: `ERC20_MIN_ALLOWANCE` -* Version: `1` -* Schema: +Version 1.0 Schema: -```json -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "type": "object", - "properties": { - "token": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The Ethereum address of the ERC20 token contract." - }, - "owner": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The Ethereum address of the wallet that owns the tokens." - }, - "spender": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The Ethereum address allowed to spend the tokens." - }, - "minAllowance": { - "type": "string", - "pattern": "^[0-9]+$", - "description": "The minimum required allowance as a string." - } - }, - "required": ["token", "owner", "spender", "minAllowance"], - "additionalProperties": false -} +```typescript +type Erc20MinAllowanceParams = { + version: string; + chainId: `0x${string}`; // Hex chain id + owner: `0x${string}`; // Address + operator: `0x${string}`; // Address + token: `0x${string}`; // Address + minAmount: `0x${string}`; // Hex value +}; ``` +This capability requests that the `owner` address **MUST** have an allowance of at least `minAmount` of `token` for `operator` on `chainId` before the transaction is executed. + Example: ```json -{ - "type": "ERC20_MIN_ALLOWANCE", - "version": 1, - "payload": { - "token": "0xA0b86991C6218b36c1d19D4a2e9EB0cE3606eB48", - "owner": "0x1234567890abcdef1234567890abcdef12345678", - "spender": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd", - "minAllowance": "1000" +[ + { + "version": "1.0", + "from": "0xd46e8dd67c5d32be8058bb8eb970870f07244567", + "calls": [ + { + "to": "0xd46e8dd67c5d32be8058bb8eb970870f07244567", + "value": "0x00", + "data": "0x...", + "chainId": "0x01", + } + ], + "capabilities": { + "erc20MinAllowance": { + "version": "1.0", + "chainId": "0x01", + "owner": "0xd46e8dd67c5d32be8058bb8eb970870f07244567", + "token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", + "operator": "0xd46e8dd67c5d32be8058bb8eb970870f07244567", + "minAmount": "0x0f4240" + } + } } -} +] ``` -#### ERC-721 Ownership +### ERC-721 Ownership Capability -Requires that a given address MUST own a specific [ERC-721](./eip-721.md) token. +A dApp can use the `erc721Ownership` capability in a `wallet_sendCalls` request to request that a wallet ensure the owner has ownership of a specified ERC-721 token. -* Type: `ERC721_OWNERSHIP` -* Version: `1` -* Schema: +#### `wallet_getCapabilities` Response -```json -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "type": "object", - "properties": { - "token": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The Ethereum address of the ERC721 token contract." - }, - "owner": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The Ethereum address of the wallet that should own the token." - }, - "tokenId": { - "type": "string", - "pattern": "^[0-9]+$", - "description": "The ID of the token that must be owned." - } - }, - "required": ["token", "owner", "tokenId"], - "additionalProperties": false +Schema: + +```typescript +type Erc721OwnershipCapability = { + supported: boolean; + versions: string[]; } ``` @@ -223,106 +195,72 @@ Example: ```json { - "type": "ERC721_OWNERSHIP", - "version": 1, - "payload": { - "token": "0x1234567890abcdef1234567890abcdef12345678", - "owner": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd", - "tokenId": "1" + "0x1": { + "erc721Ownership": { + "supported": true, + "versions": ["1.0"] + } } } ``` -#### ERC-721 Approval +#### `wallet_sendCalls` Request -Requires that a given address MUST have an [ERC-721](./eip-721.md) token approved for a specified spender. +Version 1.0 Schema: -* Type: `ERC721_APPROVAL` -* Version: `1` -* Schema: - -```json -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "type": "object", - "properties": { - "token": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The Ethereum address of the ERC721 token contract." - }, - "owner": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The Ethereum address of the wallet that owns the token." - }, - "spender": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The Ethereum address that should have approval." - }, - "tokenId": { - "type": "string", - "pattern": "^[0-9]+$", - "description": "The ID of the token that must be approved." - } - }, - "required": ["token", "owner", "spender", "tokenId"], - "additionalProperties": false -} +```typescript +type Erc721OwnershipParams = { + version: string; + chainId: `0x${string}`; // Hex chain id + owner: `0x${string}`; // Address + token: `0x${string}`; // Address + tokenId: `0x${string}`; // Hex value +}; ``` +This capability requests that the `owner` address **MUST** have ownership of `tokenId` of `token` on `chainId` before the transaction is executed. + Example: ```json -{ - "type": "ERC721_APPROVAL", - "version": 1, - "payload": { - "token": "0x1234567890abcdef1234567890abcdef12345678", - "owner": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd", - "spender": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd", - "tokenId": "1" +[ + { + "version": "1.0", + "from": "0xd46e8dd67c5d32be8058bb8eb970870f07244567", + "calls": [ + { + "to": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d", + "value": "0x00", + "data": "0x...", + "chainId": "0x01", + } + ], + "capabilities": { + "erc721Ownership": { + "version": "1.0", + "chainId": "0x01", + "owner": "0xd46e8dd67c5d32be8058bb8eb970870f07244567", + "token": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d", + "tokenId": "0x10" + } + } } -} +] ``` -#### ERC-1155 Minimum Balance +### ERC-721 Approval Capability -Requires that a given address MUST have a minimum balance of an [ERC-1155](./eip-1155.md) token. +A dApp can use the `erc721Approval` capability in a `wallet_sendCalls` request to request that a wallet ensure the owner has approved a specified ERC-721 token. +Note this capability does not imply that the owner has a balance of the token, only that the allowance is equal to or greater than the specified amount. -* Type: `ERC1155_MIN_BALANCE` -* Version: `1` -* Schema: +#### `wallet_getCapabilities` Response -```json -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "type": "object", - "properties": { - "token": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The Ethereum address of the ERC1155 token contract." - }, - "owner": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The Ethereum address of the wallet that should own the token." - }, - "tokenId": { - "type": "string", - "pattern": "^[0-9]+$", - "description": "The ID of the token that must be owned." - }, - "minBalance": { - "type": "string", - "pattern": "^[0-9]+$", - "description": "The minimum balance required." - } - }, - "required": ["token", "owner", "tokenId", "minBalance"], - "additionalProperties": false +Schema: + +```typescript +type Erc721ApprovalCapability = { + supported: boolean; + versions: string[]; } ``` @@ -330,48 +268,73 @@ Example: ```json { - "type": "ERC1155_MIN_BALANCE", - "version": 1, - "payload": { - "token": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd", - "owner": "0x1234567890abcdef1234567890abcdef12345678", - "tokenId": "2", - "minBalance": "10" + "0x1": { + "erc721Approval": { + "supported": true, + "versions": ["1.0"] + } } } ``` -#### ERC-1155 Approval +#### `wallet_sendCalls` Request + +Version 1.0 Schema: -Requires that a given address MUST have an [ERC-1155](./eip-1155.md) token approved for a specified operator. +```typescript +type Erc721ApprovalParams = { + version: string; + chainId: `0x${string}`; // Hex chain id + owner: `0x${string}`; // Address + operator: `0x${string}`; // Address + token: `0x${string}`; // Address + tokenId: `0x${string}`; // Hex value +}; +``` + +This capability requests that the `owner` address **MUST** have approved `operator` to transfer `tokenId` of `token` on `chainId` before the transaction is executed. -* Type: `ERC1155_APPROVAL` -* Version: `1` -* Schema: +Example: ```json -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "type": "object", - "properties": { - "token": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The Ethereum address of the ERC1155 token contract." - }, - "owner": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The Ethereum address of the wallet that owns the tokens." - }, - "operator": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]{40}$", - "description": "The Ethereum address that should have operator approval." +[ + { + "version": "1.0", + "from": "0xd46e8dd67c5d32be8058bb8eb970870f07244567", + "calls": [ + { + "to": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d", + "value": "0x00", + "data": "0x...", + "chainId": "0x01", + } + ], + "capabilities": { + "erc721Approval": { + "version": "1.0", + "chainId": "0x01", + "owner": "0xd46e8dd67c5d32be8058bb8eb970870f07244567", + "operator": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d", + "token": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d", + "tokenId": "0x10" + } } - }, - "required": ["token", "owner", "operator"], - "additionalProperties": false + } +] +``` + +### ERC-1155 Minimum Balance Capability + +A dApp can use the `erc1155MinBalance` capability in a `wallet_sendCalls` request to request that a wallet ensure the owner has a minimum balance of a specified ERC-1155 token. + +#### `wallet_getCapabilities` Response + +Schema: + +```typescript +type Erc1155MinBalanceCapability = { + supported: boolean; + versions: string[]; } ``` @@ -379,109 +342,153 @@ Example: ```json { - "type": "ERC1155_APPROVAL", - "version": 1, - "payload": { - "token": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd", - "owner": "0x1234567890abcdef1234567890abcdef12345678", - "operator": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd" + "0x1": { + "erc1155MinBalance": { + "supported": true, + "versions": ["1.0"] + } } } ``` -### Capabilities Discovery +#### `wallet_sendCalls` Request -To enable dapps to use the `wallet_sendIntendedTransaction` method effectively, they need to understand which requirement types and versions the wallet supports. A new JSON-RPC method called `wallet_intentCapabilities` JSON-RPC is defined to address this by allowing dapps to query the wallet’s supported requirement types and versions, ensuring compatibility. +Version 1.0 Schema: -The `wallet_intentCapabilities` method takes no parameters and returns an object detailing the supported requirement types and versions. This helps dapps construct valid transaction requests and avoid potential incompatibilities. - -The response is a JSON object structured as follows: +```typescript +type Erc1155MinBalanceParams = { + version: string; + chainId: `0x${string}`; // Hex chain id + owner: `0x${string}`; // Address + token: `0x${string}`; // Address + tokenId: `0x${string}`; // Hex value + minAmount: `0x${string}`; // Hex value +}; +``` -* `requirementTypes`: An array of objects, each representing a supported requirement type. - * `type`: A string specifying the requirement type (e.g., `ERC20_MIN_BALANCE`, `ERC721_OWNERSHIP`). - * `versions`: An array of numbers indicating the versions of this requirement type supported by the wallet. +This capability requests that the `owner` address **MUST** have a balance of at least `minAmount` of `tokenId` of `token` on `chainId` before the transaction is executed. -Example response: +Example: ```json -{ - "requirementTypes": [ - { - "type": "ERC20_MIN_BALANCE", - "versions": [1] - }, - { - "type": "ERC20_MIN_ALLOWANCE", - "versions": [1] - }, - { - "type": "ERC721_OWNERSHIP", - "versions": [1] - }, - { - "type": "ERC721_APPROVAL", - "versions": [1] - }, - { - "type": "ERC1155_MIN_BALANCE", - "versions": [1] - }, - { - "type": "ERC1155_APPROVAL", - "versions": [1] +[ + { + "version": "1.0", + "from": "0xd46e8dd67c5d32be8058bb8eb970870f07244567", + "calls": [ + { + "to": "0x631998e91476da5b870d741192fc5cbc55f5a52e", + "value": "0x00", + "data": "0x...", + "chainId": "0x01", + } + ], + "capabilities": { + "erc1155MinBalance": { + "version": "1.0", + "chainId": "0x01", + "owner": "0xd46e8dd67c5d32be8058bb8eb970870f07244567", + "token": "0x631998e91476da5b870d741192fc5cbc55f5a52e", + "tokenId": "0x10", + "minAmount": "0x0f4240" + } } - ] -} + } +] ``` -Dapps SHOULD call `wallet_intentCapabilities` before sending an `wallet_sendIntendedTransaction` request to identify the requirement types and versions supported by the wallet. +### ERC-1155 Minimum Allowance Capability -A wallet that does not support the `wallet_intentCapabilities` method MUST be assumed lack any support for the `wallet_sendIntendedTransaction` method. +A dApp can use the `erc1155MinAllowance` capability in a `wallet_sendCalls` request to request that a wallet ensure the owner has a minimum allowance of a specified ERC-1155 token. +Note this capability does not imply that the owner has a balance of the token, only that the allowance is equal to or greater than the specified amount. -A wallet MAY choose to extend the `wallet_intentCapabilities` result with capabilities specific to the wallet implementation. These additional capabilities MAY NOT be standardized and are intended for wallet specific features. +#### `wallet_getCapabilities` Response -## Rationale +Schema: -### Requirement Types +```typescript +type Erc1155MinAllowanceCapability = { + supported: boolean; + versions: string[]; +} +``` -The initial set of requirement types was chosen to cover the most common prerequisites for transactions. These requirements are based on the most common token standards ([ERC-20](./eip-20.md), [ERC-721](./eip-721.md), and [ERC-1155](./eip-1155.md)) and their most common use cases. +Example: -The use of the `type` and `version` fields allows for future extensibility. New requirement types can be added without breaking compatibility with existing wallets. Wallets can choose to support new requirement types and versions as they see fit. +```json +{ + "0x1": { + "erc1155MinAllowance": { + "supported": true, + "versions": ["1.0"] + } + } +} +``` -This solution is preferrable over a single requirement type with a complex payload, as it allows wallets to support only the requirement types they are interested in. This reduces the complexity of the implementation and the risk of errors. +#### `wallet_sendCalls` Request -### Capabilities Discovery +Version 1.0 Schema: -Dapps can use the `wallet_intentCapabilities` method to query the wallet's supported requirement types and versions before sending an `wallet_sendIntendedTransaction` request. This allows dapps to adjust their behavior based on the wallet's capabilities. +```typescript +type Erc1155MinAllowanceParams = { + version: string; + chainId: `0x${string}`; // Hex chain id + owner: `0x${string}`; // Address + operator: `0x${string}`; // Address + token: `0x${string}`; // Address + tokenId: `0x${string}`; // Hex value + minAmount: `0x${string}`; // Hex value +}; +``` -Allowing wallets to extend the `wallet_intentCapabilities` response with additional capabilities specific to the wallet implementation enables wallets to communicate additional information to dapps. For dapps that are tightly integrated with a specific wallet, this can provide additional feature support and optimizations. +This capability requests that the `owner` address **MUST** have an allowance of at least `minAmount` of `tokenId` of `token` for `operator` on `chainId` before the transaction is executed. -## Backwards Compatibility +Example: -No backward compatibility issues found. +```json +[ + { + "version": "1.0", + "from": "0xd46e8dd67c5d32be8058bb8eb970870f07244567", + "calls": [ + { + "to": "0x631998e91476da5b870d741192fc5cbc55f5a52e", + "value": "0x00", + "data": "0x...", + "chainId": "0x01", + } + ], + "capabilities": { + "erc1155MinAllowance": { + "version": "1.0", + "chainId": "0x01", + "owner": "0xd46e8dd67c5d32be8058bb8eb970870f07244567", + "operator": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d", + "token": "0x631998e91476da5b870d741192fc5cbc55f5a52e", + "tokenId": "0x10", + "minAmount": "0x0f4240" + } + } + } +] +``` -## Reference Implementation +## Rationale -A high level sample flow of how an transaction with an `ERC20_MIN_ALLOWANCE` requirement could be handled: +This ERC extends [EIP-5792](./eip-5792.md) rather than defining new RPC methods because: -```mermaid -sequenceDiagram - participant D as Dapp - participant W as Wallet Provider - participant C as Chain - D->>+W: wallet_sendIntendedTransaction - W->>C: ERC20.allowance() - alt Not approved - W->>W: Prepend approve calldata - end - W->>+C: Submit tx - deactivate C - W-->>-D: Done -``` +1. **Consistency**: Leverages existing capability discovery mechanism +2. **Composability**: Requirements can be combined with other [EIP-5792](./eip-5792.md) capabilities +3. **Flexibility**: Wallets can implement only the requirements they support +4. **Extensibility**: New requirement types can be added as additional capabilities -Note that implementation details will vary between wallets. The wallet MAY require user interaction to approve the altered transaction, or MAY automatically approve the transaction if the requirements are met. +The decision to split requirements into individual capabilities rather than a single capability type allows: -For more complex requirements, the flow may involve multiple steps, such as consolidating funds or exchanging assets. Wallets are expected to handle these scenarios and provide a seamless experience to the user. +1. Granular support by wallets +2. Clear capability discovery +3. Independent versioning of requirement types +4. Simpler implementation for basic wallets ## Security Considerations @@ -489,42 +496,49 @@ This ERC does not introduce any new security risks or trust assumptions. Users already trust their wallet provider to craft, manipulate and send transactions on their behalf. This ERC only adds a new field to the transaction request, which the wallet can use to make more informed decisions about transaction construction. -Dapps may opt out of using this feature if they wish to handle requirement fulfillment themselves. +DApps **MAY** opt out of using this feature if they wish to handle requirement fulfillment themselves. ## Examples This ERC serves as a foundational component for building user experiences that rely on cross-chain actions. It can be leveraged in various ways, depending on the combination of use cases and wallet implementations. +Not shown in the examples below are the `wallet_getCallsStatus` and `wallet_showCallsStatus` methods, which are used to query the status of a call bundle and display it to the user. The dApp **MAY** use these methods to provide a better user experience while waiting for the transactions to be fulfilled. More information can be found in the [EIP-5792](./eip-5792.md) specification. + ### Marketplace Interaction with Bridge Using an EOA Wallet -A user wants to purchase ERC-721 tokens on **Chain A** but only has funds on **Chain B**. The user employs an Externally Owned Account (EOA) based wallet. The dApp requests an intended transaction using `wallet_sendIntendedTransaction`, which includes the marketplace transaction alongside the requirement of owning funds on Chain A. +A user wants to purchase ERC-721 tokens on **Chain A** but only has funds on **Chain B**. The user employs an Externally Owned Account (EOA) based wallet. The dApp requests an intended transaction using `wallet_sendCalls`, which includes the marketplace transaction alongside the requirement of owning funds on Chain A. In this scenario, the wallet **MAY** prompt the user to sign the necessary transactions to fulfill the requirements before proceeding with the main transaction. The wallet **SHOULD** compute possible solutions to meet the requirements and **MUST** ensure that these prerequisites are met prior to executing the main transaction. ```mermaid sequenceDiagram - participant D as Dapp + participant D as DApp participant W as Wallet - participant U as User + actor U as User participant CA as Chain A participant CB as Chain B - D->>+W: wallet_sendIntendedTransaction + activate D + D->>+W: wallet_getCapabilities + W-->>-D: Capabilities + D->>D: Validate supported capabilities + D->>+W: wallet_sendCalls W->>W: Compute solutions for requirements - W->>U: Prompt to sign bridge transaction from Chain B to Chain A - U-->>W: User approves - W->>CB: Send bridge transaction - CB-->>W: Transaction receipt + W->>+U: Prompt to sign bridge transaction from Chain B to Chain A + U-->>-W: User approves + W->>+CB: Send bridge transaction + CB-->>-W: Transaction receipt W->>W: Wait for requirements to be fulfilled - W->>U: Prompt to sign intended transaction - U-->>W: User approves - W->>CA: Send main transaction - CA-->>W: Transaction receipt + W->>+U: Prompt to sign intended transaction + U-->>-W: User approves + W->>+CA: Send main transaction + CA-->>-W: Transaction receipt W-->>-D: Transaction completed + deactivate D ``` ### Bridge, Swap, and Payment Using a Smart Contract Wallet -A dApp requests a payment from a user, which **MUST** be made in **Token Z** on **Chain B**, but the user holds **Token Y** on **Chain A**. The dApp requests an intended transaction using `wallet_sendIntendedTransaction`, including the payment transaction alongside the requirement of having enough Token Z on Chain B. +A dApp requests a payment from a user, which **MUST** be made in **Token Z** on **Chain B**, but the user holds **Token Y** on **Chain A**. The dApp requests an intended transaction using `wallet_sendCalls`, including the payment transaction alongside the requirement of having enough Token Z on Chain B. In this scenario, the Smart Contract Wallet **MAY** prompt the user to sign all the necessary transactions at once, executing them in the appropriate order. The wallet **SHOULD** compute solutions to fulfill the requirements and **MUST** ensure that all prerequisites are satisfied before proceeding with the main transaction. @@ -532,14 +546,14 @@ The signed transactions **MAY** be sent simultaneously to bundlers, who execute ```mermaid sequenceDiagram - participant D as Dapp + participant D as DApp participant W as Wallet - participant U as User + actor U as User participant CA as Chain A participant CB as Chain B participant BA as Bundler A participant BB as Bundler B - D->>+W: wallet_sendIntendedTransaction + D->>+W: wallet_sendCalls W->>W: Compute solutions for requirements par Single interaction W->>U: Prompt sign bridge from A to B @@ -568,10 +582,7 @@ sequenceDiagram W-->>-D: Done ``` -These examples demonstrate how this ERC enables communication between dApps and wallets, making complex cross-chain interactions possible. Wallets **MAY** implement and execute these operations in any way they see fit, including using solver networks or manually sending the transactions. By leveraging the `wallet_sendIntendedTransaction` method, wallets and dApps **CAN** provide a seamless user experience for complex transactions that involve multiple steps across different chains.## Examples - -This ERC serves as a foundational component for building user experiences that rely on cross-chain actions. It can be leveraged in various ways, depending on the combination of use cases and wallet implementations. - +These examples demonstrate how this ERC enables communication between dApps and wallets, making complex cross-chain interactions possible. Wallets **MAY** implement and execute these operations in any way they see fit, including using solver networks or manually sending the transactions. By leveraging the `wallet_sendCalls` method, wallets and dApps can provide a seamless user experience for complex transactions that involve multiple steps across different chains. ## Copyright From 083257dc46e3e414b5054a290c9320d4c698461f Mon Sep 17 00:00:00 2001 From: Michael Standen Date: Mon, 25 Nov 2024 11:21:15 +1300 Subject: [PATCH 09/13] ERC links --- ERCS/erc-7795.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/ERCS/erc-7795.md b/ERCS/erc-7795.md index de82e3cb0b..3716e0d430 100644 --- a/ERCS/erc-7795.md +++ b/ERCS/erc-7795.md @@ -1,7 +1,7 @@ --- eip: 7795 -title: Wallet Call Token Requirements -description: EIP-5792 extension for common ERC-20, ERC-721 and ERC-1155 transaction prerequisites +title: Wallet Call Token Capabilities +description: Wallet Call API extension for transaction prerequisites for common token standards author: Agustín Aguilar (@agusx1211), Michael Standen (@ScreamingHawk), Peter Kieltyka (@pkieltyka), William Hua (@attente), Philippe Castonguay (@PhABC) discussions-to: https://ethereum-magicians.org/t/erc-7795-wallet-transaction-intents/21426 status: Draft @@ -13,7 +13,7 @@ requires: 5792 ## Abstract -This ERC extends [EIP-5792](./eip-5792.md) by defining capabilities that allow dApps to specify common token prerequisites for transactions, such as having certain ERC-20, ERC-721, or ERC-1155 tokens. Wallets can then help users meet these requirements before executing the transactions. +This ERC extends [EIP-5792](./eip-5792.md) by defining capabilities that allow dApps to specify common token prerequisites for transactions, such as having certain [ERC-20](./eip-20.md), [ERC-721](./eip-721.md), or [ERC-1155](./eip-1155.md) tokens. Wallets can then help users meet these requirements before executing the transactions. ## Motivation @@ -31,7 +31,7 @@ This ERC extends [EIP-5792](./eip-5792.md) by adding new capabilities that can b ### ERC-20 Minimum Balance Capability -A dApp can use the `erc20MinBalance` capability in a `wallet_sendCalls` request to request that a wallet ensure the owner has a minimum balance of a specified ERC-20 token. +A dApp can use the `erc20MinBalance` capability in a `wallet_sendCalls` request to request that a wallet ensure the owner has a minimum balance of a specified [ERC-20](./eip-20.md) token. #### `wallet_getCapabilities` Response @@ -103,7 +103,7 @@ Example: ### ERC-20 Minimum Allowance Capability -A dApp can use the `erc20MinAllowance` capability in a `wallet_sendCalls` request to request that a wallet ensure the owner has a minimum allowance of a specified ERC-20 token. +A dApp can use the `erc20MinAllowance` capability in a `wallet_sendCalls` request to request that a wallet ensure the owner has a minimum allowance of a specified [ERC-20](./eip-20.md) token. Note this capability does not imply that the owner has a balance of the token, only that the allowance is equal to or greater than the specified amount. #### `wallet_getCapabilities` Response @@ -178,7 +178,7 @@ Example: ### ERC-721 Ownership Capability -A dApp can use the `erc721Ownership` capability in a `wallet_sendCalls` request to request that a wallet ensure the owner has ownership of a specified ERC-721 token. +A dApp can use the `erc721Ownership` capability in a `wallet_sendCalls` request to request that a wallet ensure the owner has ownership of a specified [ERC-721](./eip-721.md) token. #### `wallet_getCapabilities` Response @@ -250,7 +250,7 @@ Example: ### ERC-721 Approval Capability -A dApp can use the `erc721Approval` capability in a `wallet_sendCalls` request to request that a wallet ensure the owner has approved a specified ERC-721 token. +A dApp can use the `erc721Approval` capability in a `wallet_sendCalls` request to request that a wallet ensure the owner has approved a specified [ERC-721](./eip-721.md) token. Note this capability does not imply that the owner has a balance of the token, only that the allowance is equal to or greater than the specified amount. #### `wallet_getCapabilities` Response @@ -325,7 +325,7 @@ Example: ### ERC-1155 Minimum Balance Capability -A dApp can use the `erc1155MinBalance` capability in a `wallet_sendCalls` request to request that a wallet ensure the owner has a minimum balance of a specified ERC-1155 token. +A dApp can use the `erc1155MinBalance` capability in a `wallet_sendCalls` request to request that a wallet ensure the owner has a minimum balance of a specified [ERC-1155](./eip-1155.md) token. #### `wallet_getCapabilities` Response @@ -399,7 +399,7 @@ Example: ### ERC-1155 Minimum Allowance Capability -A dApp can use the `erc1155MinAllowance` capability in a `wallet_sendCalls` request to request that a wallet ensure the owner has a minimum allowance of a specified ERC-1155 token. +A dApp can use the `erc1155MinAllowance` capability in a `wallet_sendCalls` request to request that a wallet ensure the owner has a minimum allowance of a specified [ERC-1155](./eip-1155.md) token. Note this capability does not imply that the owner has a balance of the token, only that the allowance is equal to or greater than the specified amount. #### `wallet_getCapabilities` Response @@ -506,7 +506,7 @@ Not shown in the examples below are the `wallet_getCallsStatus` and `wallet_show ### Marketplace Interaction with Bridge Using an EOA Wallet -A user wants to purchase ERC-721 tokens on **Chain A** but only has funds on **Chain B**. The user employs an Externally Owned Account (EOA) based wallet. The dApp requests an intended transaction using `wallet_sendCalls`, which includes the marketplace transaction alongside the requirement of owning funds on Chain A. +A user wants to purchase [ERC-721](./eip-721.md) tokens on **Chain A** but only has funds on **Chain B**. The user employs an Externally Owned Account (EOA) based wallet. The dApp requests an intended transaction using `wallet_sendCalls`, which includes the marketplace transaction alongside the requirement of owning funds on Chain A. In this scenario, the wallet **MAY** prompt the user to sign the necessary transactions to fulfill the requirements before proceeding with the main transaction. The wallet **SHOULD** compute possible solutions to meet the requirements and **MUST** ensure that these prerequisites are met prior to executing the main transaction. From 0cce21b8fd628abfc55e0ec58f11c2a623694e83 Mon Sep 17 00:00:00 2001 From: Michael Standen Date: Mon, 25 Nov 2024 11:22:26 +1300 Subject: [PATCH 10/13] Update discussion link --- ERCS/erc-7795.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ERCS/erc-7795.md b/ERCS/erc-7795.md index 3716e0d430..44a66a2d2e 100644 --- a/ERCS/erc-7795.md +++ b/ERCS/erc-7795.md @@ -3,7 +3,7 @@ eip: 7795 title: Wallet Call Token Capabilities description: Wallet Call API extension for transaction prerequisites for common token standards author: Agustín Aguilar (@agusx1211), Michael Standen (@ScreamingHawk), Peter Kieltyka (@pkieltyka), William Hua (@attente), Philippe Castonguay (@PhABC) -discussions-to: https://ethereum-magicians.org/t/erc-7795-wallet-transaction-intents/21426 +discussions-to: https://ethereum-magicians.org/t/erc-7795-wallet-call-token-capabilities/21426 status: Draft type: Standards Track category: ERC From fd11f4c9140df282f9bd1983e3539762b1644c0d Mon Sep 17 00:00:00 2001 From: Michael Standen Date: Mon, 25 Nov 2024 11:23:53 +1300 Subject: [PATCH 11/13] Lint fixes --- ERCS/erc-7795.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ERCS/erc-7795.md b/ERCS/erc-7795.md index 44a66a2d2e..82bafd71d7 100644 --- a/ERCS/erc-7795.md +++ b/ERCS/erc-7795.md @@ -1,7 +1,7 @@ --- eip: 7795 title: Wallet Call Token Capabilities -description: Wallet Call API extension for transaction prerequisites for common token standards +description: Wallet Call API extension for transaction prerequisites for common token types author: Agustín Aguilar (@agusx1211), Michael Standen (@ScreamingHawk), Peter Kieltyka (@pkieltyka), William Hua (@attente), Philippe Castonguay (@PhABC) discussions-to: https://ethereum-magicians.org/t/erc-7795-wallet-call-token-capabilities/21426 status: Draft @@ -498,9 +498,9 @@ Users already trust their wallet provider to craft, manipulate and send transact DApps **MAY** opt out of using this feature if they wish to handle requirement fulfillment themselves. -## Examples +### Reference Implementation -This ERC serves as a foundational component for building user experiences that rely on cross-chain actions. It can be leveraged in various ways, depending on the combination of use cases and wallet implementations. +This ERC serves as a foundational component for building user experiences that rely on cross-chain actions. It can be leveraged in various ways, depending on the combination of use cases and wallet implementations. Consider the following high-level examples. Not shown in the examples below are the `wallet_getCallsStatus` and `wallet_showCallsStatus` methods, which are used to query the status of a call bundle and display it to the user. The dApp **MAY** use these methods to provide a better user experience while waiting for the transactions to be fulfilled. More information can be found in the [EIP-5792](./eip-5792.md) specification. From 1e23ccd1a89728d8a07cd8f3cefd32f27164e917 Mon Sep 17 00:00:00 2001 From: Michael Standen Date: Thu, 28 Nov 2024 10:08:13 +1300 Subject: [PATCH 12/13] Fix heading level --- ERCS/erc-7795.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ERCS/erc-7795.md b/ERCS/erc-7795.md index 82bafd71d7..779074dabe 100644 --- a/ERCS/erc-7795.md +++ b/ERCS/erc-7795.md @@ -498,7 +498,7 @@ Users already trust their wallet provider to craft, manipulate and send transact DApps **MAY** opt out of using this feature if they wish to handle requirement fulfillment themselves. -### Reference Implementation +## Reference Implementation This ERC serves as a foundational component for building user experiences that rely on cross-chain actions. It can be leveraged in various ways, depending on the combination of use cases and wallet implementations. Consider the following high-level examples. From 7053361ff8269bddae68769d2785446e50eb6af2 Mon Sep 17 00:00:00 2001 From: Michael Standen Date: Thu, 28 Nov 2024 10:09:48 +1300 Subject: [PATCH 13/13] Fix section order --- ERCS/erc-7795.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/ERCS/erc-7795.md b/ERCS/erc-7795.md index 779074dabe..3474d1e0dd 100644 --- a/ERCS/erc-7795.md +++ b/ERCS/erc-7795.md @@ -490,14 +490,6 @@ The decision to split requirements into individual capabilities rather than a si 3. Independent versioning of requirement types 4. Simpler implementation for basic wallets -## Security Considerations - -This ERC does not introduce any new security risks or trust assumptions. - -Users already trust their wallet provider to craft, manipulate and send transactions on their behalf. This ERC only adds a new field to the transaction request, which the wallet can use to make more informed decisions about transaction construction. - -DApps **MAY** opt out of using this feature if they wish to handle requirement fulfillment themselves. - ## Reference Implementation This ERC serves as a foundational component for building user experiences that rely on cross-chain actions. It can be leveraged in various ways, depending on the combination of use cases and wallet implementations. Consider the following high-level examples. @@ -584,6 +576,14 @@ sequenceDiagram These examples demonstrate how this ERC enables communication between dApps and wallets, making complex cross-chain interactions possible. Wallets **MAY** implement and execute these operations in any way they see fit, including using solver networks or manually sending the transactions. By leveraging the `wallet_sendCalls` method, wallets and dApps can provide a seamless user experience for complex transactions that involve multiple steps across different chains. +## Security Considerations + +This ERC does not introduce any new security risks or trust assumptions. + +Users already trust their wallet provider to craft, manipulate and send transactions on their behalf. This ERC only adds a new field to the transaction request, which the wallet can use to make more informed decisions about transaction construction. + +DApps **MAY** opt out of using this feature if they wish to handle requirement fulfillment themselves. + ## Copyright Copyright and related rights waived via [CC0](../LICENSE.md).