ERC-7699 ERC-20 Transfer Reference Extension
Draft · Tokens · created 2024-04-26
An extension standard that lets a transfer reference be attached when sending an ERC-20 token, so the recipient can immediately link the payment to a specific order or invoice.
Why it is needed
The ERC-20 token standard has no feature for attaching a reference to a payment, unlike the "memo to recipient's account" field in a bank transfer. In traditional finance, a reference is included with a remittance, as in field 70 (Remittance Information) of SWIFT MT103 or the RmtInf field of ISO 20022, making it easy to match a payment against a specific invoice. Current token transfers, by contrast, retain only sender, recipient, and amount, so merchants or service providers who need to match a deposit to a specific order or invoice must rely on an external off-chain system or build a separate payment proxy contract. This standard adds minimal functions carrying a reference to the existing transfer and transferFrom, helping users and merchants easily identify and settle transactions, and narrowing the gap between traditional finance and decentralized finance.
What to implement
function transfer(address to, uint256 amount, bytes calldata transferReference) external returns (bool);: Sends the caller's amount of tokens to to, together with the transferReference data. Returns a boolean indicating success.function transferFrom(address from, address to, uint256 amount, bytes calldata transferReference) external returns (bool);: Sends from's tokens to to within the approved allowance, together with the reference data. Returns a boolean indicating success.event TransferReference(bytes32 indexed loggedReference);: An event signaling that a transfer carrying a reference has occurred, recording the logged reference value loggedReference.
In depth
Extended interface and event emission rules
An ERC-20 contract adopting this ERC must implement the IERC7699 interface (EIP-165 identifier 0x1522573a). The reference-carrying transfer and transferFrom must, in addition to the standard transfer behavior, emit a TransferReference event carrying loggedReference. The corresponding ERC-20 Transfer event must be emitted after the TransferReference event, ideally immediately following it. This ordering rule lets clients find the matching Transfer log from the reference event. A transfer of zero amount must also be treated the same as a normal transfer and emit a TransferReference event.
transferReference and loggedReference may differ
The transferReference passed at call time is a bytes type with no length limit, while loggedReference recorded in the event is a bytes32 type. If the reference is under 33 bytes it may be copied as is, or it may be a value processed or derived from structured reference data; this is left to the implementer. The two values should therefore not be expected to be identical. Although the standard does not limit the reference length, calldata and execution gas costs naturally encourage users to keep it short.
An empty reference does not emit an event
transferReference may be an empty value. In this case, and only in this case, the TransferReference event must not be emitted. As a result it behaves identically to a normal ERC-20 transfer without a reference. Also, the TransferReference event must not be declared with the anonymous modifier, since the event signature must remain in the log to be filterable by subscriptions.
Reasons for the type choices
transferReference was initially considered as bytes32. The idea was to encourage either a short reference as in traditional finance, or the Keccak-256 hash of the reference content, but it was settled as bytes to leave room for structured data calls, such as passing reference data that includes a signature to enable additional verification processing. Conversely, keeping the event side as bytes calldata was also considered, but during the log topic indexing needed for subscription filters, the content gets hashed anyway into a bytes32 form. With a bytes32 type, up to 32 bytes of unhashed, directly readable reference can be retained. The parameter name was set to transferReference, in line with the widely used traditional banking term for payment reference.
Compatibility with existing ERC-20
This extension is fully backward compatible with the existing ERC-20 standard. The new functions can be used alongside the existing transfer and transferFrom. An upgradeable existing ERC-20 token can add this functionality via an upgrade without affecting its storage layout, and newly created tokens can choose whether to adopt it as needed.
Proposal status
This document is a proposal in Draft status, created in April 2024. Its content may change or progress may stall, so it is advisable to check the latest status before implementing.
Things to watch out for
- Privacy exposure of reference data: Because a payment reference remains publicly on the blockchain, it may reveal sensitive information about the transaction or the parties involved. For example, if a reference such as 0x20240002 is recorded, it publicly reveals that the payment is for the recipient's second invoice of 2024. Implementers and users should carefully consider the privacy implications and may consider protecting reference data with privacy-preserving techniques such as encryption.
- Possibility of reference value manipulation: This ERC does not mandate validation of reference data. A malicious party could manipulate a reference to deceive users, merchants, or service providers. If an attacker attaches someone else's reference to illicit funds, the recipient could face legal or compliance risk such as suspected involvement in money laundering, and if a user discovers a payment they did not make, the resulting refund requests or disputes increase the recipient's administrative burden. Implementations may consider proper payer verification and methods for generating unique, verifiable references, but this falls outside the scope of this standard as an extension area.