Abstract

This EIP proposes a standardized URI scheme for chain-specific payment requests, enabling users to specify transactions in the form “send me X tokens of type Y on chain Z”. The URI format includes essential components such as the recipient’s blockchain account, the amount of tokens, the token contract address, and optional success and error callback URLs. This standard aims to eliminate ambiguity in multi-chain payment requests, ensuring clarity and accuracy in peer-to-peer transactions and vendor or dApp requests across different blockchain networks.

Motivation

The ongoing expansion of the Ethereum network into a multi-chain ecosystem has introduced complexities regarding the execution of payment requests. Users and developers currently face a lack of clarity on which chain a payment request should be fulfilled, particularly when similar assets exist across multiple chains. This ambiguity complicates peer-to-peer transactions and vendor or dApp requests, leading to inefficiencies and a higher potential for errors. This standard will ensure that payment requests are clearly understood and correctly executed, regardless of the chain, thus significantly enhancing the user experience in a multi-chain environment.

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.

The format of the payment request URI is:

cspr://<recipient>/<amount>/<token-address>?on-success=<success-callback-url>&on-error=<error-callback-url>
  • cspr:// - [REQUIRED] Short for “Chain-Specific Payment Request”. Indicates a blockchain-based payment request.
  • <recipient> - [REQUIRED] The blockchain account requesting the payment (represented as a CAIP-10 account identifier).
  • <amount> - [REQUIRED] The amount of tokens to be sent, specified as an integer or decimal number.
  • <token-address> - [REQUIRED] The contract address of the ERC-20 token to send (represented as a base64 encoded string). The special value native can be used to request the native currency of the specified chain (if the chain supports a native currency).
  • <success-callback-url> - [OPTIONAL] The URL to redirect the user to after the transaction is confirmed.
  • <error-callback-url> - [OPTIONAL] The URL to redirect the user to after the transaction fails.

Examples

Requesting 1 eth on Base Mainnet to address 0x1111111111111111111111111111111111111111 with a specified success callback URL:

cspr://eip155:8453:0x1111111111111111111111111111111111111111/1/native?on-success=https://example.com

Requesting 0.5 BTC on Bitcoin mainnet:

cspr://bip122:000000000019d6689c085ae165831e93:128Lkh3S7CkDTBZ8W7BbpsN3YYizJMp8p6/0.5/native

Requesting 100 USDC on Ethereum Mainnet:

cspr://eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb/100/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48

Error Handling

Wallets or applications parsing these URIs MUST validate the format of the recipient account. If any component of the URI does not meet the specified requirements or format, an error should be displayed to the user.

Rationale

The design of this URI standard for blockchain-based payment requests addresses the need for a clear and unambiguous method to initiate transactions across multiple Ethereum chains, including mainnet and various Layer 2 networks. The rationale for each component of the URI structure is as follows:

  • cspr:// Prefix: This prefix explicitly identifies the URI as a blockchain-based payment request, ensuring systems recognize and correctly handle these URIs. It follows the precedent of other protocol-specific URI schemes like mailto:// for email and http:// for web links.
  • Recipient: The recipient is specified using a CAIP-10 account identifier, a standardized format for representing blockchain addresses. With CAIP-10, you can easily identify the recipient’s blockchain network and corresponding address, regardless of the underlying address conventions.
  • Amount Specification: Specifying the amount in the URI clarifies the transaction’s intent, allowing users to verify the amount before sending. This helps prevent mistakes and fraud. The amount is specified as an integer or decimal number for clarity, precision, and ease of verification.
  • Token Address: Requiring the token address ensures the URI specifies the exact token to be sent, eliminating ambiguity. It supports both ERC-20 tokens and the native currency of a chain (if supported).
  • Callback URLs: Including callback URLs allows redirection to a specified URL after the transaction is confirmed or fails, enhancing the user experience by providing a seamless return to the application or website.

The token address in this URI standard is represented as a base64 encoded string to support both EVM and non-EVM chains, as all current address schemes are a subset of base64.

Alternative Designs Considered:

  • Including Transaction Parameters: Additional transaction parameters (e.g., gas limit, gas price) were considered but are recommended to be handled by the user’s wallet application to keep the URI scheme focused on payment requests and avoid overloading the user with technical details.
  • Token Parameter Optionality: Initially, the token parameter was considered optional, with its omission implying the native currency of the specified chain. However, not all chains support a native currency, so requiring explicit token specification increases clarity and reduces potential errors.
  • An ethereum:// prefix: Initially proposed as a standardized URI scheme for the Ethereum ecosystem, the ethereum:// prefix aimed to provide a consistent identifier. However, to accommodate non-EVM chains, it is more practical to use a more generic identifier that is not limited to Ethereum.
  • ENS Support: We initially considered adding optional ENS support, but determined it was unnecessary. Because the URI scheme isn’t user-facing, including ENS would add unneeded complexity without providing tangible benefits. Additionally, ENS names that resemble addresses introduce potential security risks. Instead, adhering to the CAIP-10 standard for chain-specific account identifiers is a more practical choice.

ERC-681 is a related standard that defines a similar URI scheme for specifying token transfers in Ethereum. However, ERC-681 includes additional parameters for specifying transaction details, which were deemed unnecessary for the scope of this standard. The focus of this EIP is on simplicity and clarity in payment request specifications, with the expectation that transaction details will be handled by the user’s wallet application.

ERC-831 is another related standard that specifies a URI format for Ethereum. Instead of focusing exclusively on Ethereum and its rollups, this EIP is designed to be compatible with all blockchains. The primary distinction lies in the selection of the URI identifier.

Backwards Compatibility

Due to the unique choice in URI prefix, this EIP is not backwards compatible with ERC-681 or ERC-831.

Security Considerations

As there are many similarities to ERC-681, all the same security considerations apply and have been summarized below.

The security and trustworthiness of URLs are crucial, especially since they can trigger irreversible transactions. Altering the recipient’s address or the transaction amount can lead to significant financial gain for attackers. Therefore, users should only trust URLs from verified and secure sources.

To ensure the transaction amount matches the user’s intention, it should be clearly and easily verifiable by the user, including its magnitude. For ERC-20 token transactions, if the payer’s client can access the blockchain or another reliable source for token contract details, the interface should present the amount in the token’s specified units. If not, it should show the amount as stated in the URL, potentially warning the user about the uncertainty of the unit. Using scientific notation with an exponent that matches the token’s nominal unit (e.g., 18 for ether) is recommended to aid user verification.

Validate callback URLs rigorously to prevent redirection to phishing sites. Wallet developers should follow browser security best practices for URL validation.

Wallet applications must recognize chains that lack native currency support and should block native currency payment requests on these chains.

Copyright and related rights waived via CC0.