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

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

Original ERC · ← ERCs