ERC-7682 Auxiliary funding notification feature (Auxiliary Funds Capability)

Draft · Accounts & wallets · created 2024-04-09

A feature that lets a wallet inform an app that it has additional funds available beyond the on-chain balance. Apps can then avoid blocking the user for insufficient balance.

Why it is needed

Many apps check the on-chain balance of a user's address before allowing an action. For example, when swapping tokens on a decentralized exchange (DEX), the app often blocks the trade outright if that address lacks enough of the token. However, some wallets can access funds that aren't visible from the address's on-chain balance alone, such as onramping off-chain funds on the spot, or a wallet that manages multiple accounts moving assets from another account to the one that needs them. If a wallet has no way to tell the app about this additional funding, a user who can actually pay ends up unnecessarily blocked by the balance check. This standard defines a common way for wallets to communicate that fact to apps.

In depth

Advertising the auxiliaryFunds capability

A wallet that can access auxiliary funds MUST include an auxiliaryFunds object in the wallet_getCapabilities response, with the supported field set to true, for each chain on which those funds can be used. It MAY optionally include an assets field listing the addresses of assets with additional access; if this array is absent, the app SHOULD assume the wallet has additional access to all assets. A chain's native asset (such as Ether on Ethereum) MUST be represented as "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE" per EIP-7528. No constraints are placed on the source of the auxiliary funds.

The requiredAssets parameter

If a wallet supports auxiliaryFunds, the app MAY include a requiredAssets parameter in the capabilities.auxiliaryFunds object of its wallet_sendCalls request. Each entry consists of address, amount (a hex string representing an integer in the asset's smallest unit), standard ("erc20", "erc721", "erc1155"), and tokenId (required for ERC-721 and ERC-1155). Since call data alone cannot reliably reveal the assets and amounts needed for execution, having the app specify them lets the wallet prepare, bridge, or swap the assets. However, even a wallet that advertises auxiliaryFunds may fail to interpret requiredAssets, so apps should handle the unsupported case gracefully. Rather than being listed in requiredAssets, native asset requirements SHOULD be inferred by the wallet from the call's call.value field.

Field rules by token standard

ERC-20 only needs the amount field, while ERC-721 and ERC-1155 need both amount and tokenId. The meaning of amount differs by standard. For ERC-20 it's a quantity in the smallest unit (wei for an 18-decimal token); for ERC-721 it's the NFT count (usually "0x01" for a single NFT); for ERC-1155 it's the quantity of the specified token ID. For extensibility, future token standards MUST define any additional required fields as properties at the root of the asset object. Wallets MUST also cross-check the amount value in requiredAssets against the asset contract's decimal() value to interpret it with the correct decimal precision.

Atomic execution and error codes

The auxiliary fund preparation process, such as bridging or swapping, is independent of the wallet_sendCalls execution lifecycle. The atomicRequired field applies only to the execution of the call bundle, not to fund preparation. Error codes defined for preparation failures are 5770 (fund preparation failed, e.g. a bridge or swap error), 5771 (asset not supported), 5772 (auxiliary funds no longer supported on that chain), and 5773 (malformed requiredAssets). Since fund preparation can take time, apps SHOULD track progress via wallet_getCallsStatus.

App implementation guidance and compatibility

If the connected wallet advertises the auxiliaryFunds capability, the app SHOULD NOT block user actions based on an asset balance check. requiredAssets SHOULD only be included when the wallet advertises the auxiliaryFunds capability, and SHOULD be sent with optional: true, which gives the information to wallets that support this feature while keeping compatibility with wallets that don't. As a design rationale, an alternative of providing a URL to query auxiliary balances was also considered, but a single boolean was judged sufficient as a signal not to block on balance checks, and it imposes the least implementation burden on apps. The shape of this capability is left open to be extended with more advanced features if needed.

Proposal status

This proposal is still in Draft status. Its contents may change, so implementers should check the latest original text.

Things to watch out for

Original ERC · ← ERCs