--- id: TIP-1045 title: Payment Transaction Classification description: Defines consensus rules for classifying transactions as payment lane eligible using an allow-list of call targets/selectors and bounded auxiliary payloads. authors: @0xrusowsky, Arsenii Kulikov @klkvr, Dan Robinson @danrobinson, Tanishk Goyal @legion2002 status: Approved related: TIP-1010, TIP-1000, Payment Lane Specification, TIP-20, TIP-1034 protocolVersion: T5 --- # TIP-1045: Payment Transaction Classification ## Abstract This TIP formalizes the consensus rules for classifying a transaction as payment lane eligible under TIP-1010. Starting with the T5 hardfork, consensus requires every call in the transaction to match a payment call allow-list entry (target + selector + ABI encoding constraints) and requires auxiliary payload fields such as access lists and authorization lists to satisfy the restrictions below. ## Motivation TIP-1010 defines the payment lane gas budget but leaves the classification criteria underspecified — only requiring that the transaction targets a TIP-20 address. As payment lane eligibility expands beyond TIP-20 calls, consensus needs a generic but stable predicate that can be maintained indefinitely for historical validation. This TIP therefore enshrines only the minimum long-term consensus rule: a transaction is payment lane eligible if every call it contains matches an allow-listed payment call shape and the transaction satisfies the auxiliary-payload restrictions below. Builders MAY apply stricter local policy when selecting transactions for the payment lane, but such heuristics are intentionally left out of scope. --- # Specification A transaction qualifies for the payment lane when all of the following hold: 1. EVERY call it contains is an allow-listed payment call. 2. `access_list` is empty. 3. `authorization_list` and `tempo_authorization_list` are empty. 4. If `key_authorization` is present, `len(rlp(key_authorization)) <= 1024` bytes. These auxiliary-payload restrictions prevent transactions from consuming payment-lane capacity with non-payment metadata. Unbounded sidecars are excluded from the payment lane, while `key_authorization` remains eligible only under a fixed size bound. ## Payment Call Allow-List A call qualifies as a payment call if, for some entry in the payment call allow-list table, all of the following hold: 1. It is NOT a contract-creation request. 2. Its target satisfies the entry's target-match predicate. 3. The first 4 bytes of its calldata equal the entry's selector. 4. Its calldata satisfies the size and encoding constraints derived from the entry's signature, as defined below. Calldata MUST be the canonical ABI encoding for the entry's signature. Additional constraints depend on whether the entry's parameters contain any dynamic ABI types (`bytes`, `string`, dynamic arrays, or tuples/arrays transitively containing them): - **Static-only entries**: calldata MUST have no trailing bytes; equivalently, its length MUST be the 4-byte selector plus one 32-byte ABI word per parameter. - **Entries with any dynamic type**: calldata's total length MUST be `<= 2048` bytes. The initial payment call allow-list is: | Target | Selector | Function | |--------|----------|----------| | TIP-20 | `transfer(address,uint256)` | Simple transfer | | TIP-20 | `transferWithMemo(address,uint256,bytes32)` | Transfer with memo | | TIP-20 | `transferFrom(address,address,uint256)` | Delegated transfer | | TIP-20 | `transferFromWithMemo(address,address,uint256,bytes32)` | Delegated transfer with memo | | TIP-20 | `approve(address,uint256)` | Spending approval | | TIP-20 | `mint(address,uint256)` | Token mint | | TIP-20 | `mintWithMemo(address,uint256,bytes32)` | Mint with memo | | TIP-20 | `burn(uint256)` | Token burn | | TIP-20 | `burnWithMemo(uint256,bytes32)` | Burn with memo | | TIP20ChannelEscrow | `open(address,address,uint96,bytes32,address,uint32)` | Open channel | | TIP20ChannelEscrow | `topUp((address,address,address,bytes32,address),uint96,uint32)` | Top up channel | | TIP20ChannelEscrow | `settle((address,address,address,bytes32,address),uint96,bytes)` | Settle channel | | TIP20ChannelEscrow | `close((address,address,address,bytes32,address),uint96,uint96,bytes)` | Close channel | The `Target` column may specify either an exact target precompile address or an address class. For TIP-20 precompiles, the match is against the `0x20C000000000000000000000` prefix. Calls with empty calldata, unrecognized selectors, target/selector combinations not present in the allow-list, malformed ABI encoding, or calldata that violates the matched entry's size or encoding constraints, do not match any allow-list entry. ## Access Lists Any transaction carrying a non-empty `access_list` MUST be classified as general, regardless of its type, targets, or calldata. Access lists can carry arbitrary addresses and storage keys as transaction metadata. ## Authorization Lists Any transaction carrying a non-empty `authorization_list` (EIP-7702) or non-empty `tempo_authorization_list` MUST be classified as general. Both fields are unbounded in entry count and each entry carries attacker-chosen signed payloads. `key_authorization` is exempt from this restriction and MAY be present in payment transactions. It is a single, size-bounded structure tied to onboarding the transaction's sender, and removing it from the payment lane would break first-transaction UX without offering a comparable data-injection surface. To bound the data-injection surface that `key_authorization` itself can carry, payment transactions MUST satisfy `len(rlp(key_authorization)) <= 1024` bytes. Any payment-eligible transaction whose `key_authorization` exceeds this bound MUST be classified as general. The 1 KB ceiling comfortably fits realistic provisioning payloads with limits and scopes. No consensus-level cap is placed on the overall transaction size: payment transactions are free to batch many TIP-20 calls in a single tx, and any tx-size shaping is left to the builder. ## Transaction Types For legacy, EIP-2930, EIP-1559, and EIP-7702 transactions, the single top-level call must match the payment call allow-list, `access_list` must be empty, `authorization_list` must be empty, and any `key_authorization` must satisfy the 1024-byte RLP bound. For account-abstraction (type `0x76`) transactions, `calls` must be non-empty, every call in the batch must individually match the payment call allow-list, `access_list` must be empty, `tempo_authorization_list` must be empty, and any `key_authorization` must satisfy the 1024-byte RLP bound. No other transaction fields participate in consensus payment classification. In particular, signature fields, fee sponsorship fields, and validity-window fields do not affect payment versus general classification. ## Pre-T5 (Backward Compatibility) Before T5, only the legacy TIP-20 address prefix check is enforced at the consensus level. # Invariants 1. **Classification completeness**: Every transaction MUST be classified as exactly one of payment or general — never both, never neither. 2. **Allow-list strictness**: A transaction containing any call that does not match an allow-listed `(target, selector, calldata constraint)` entry MUST be classified as general and subject to `general_gas_limit`. 3. **Canonical calldata**: Static-only entries MUST have exactly the static ABI-encoded length. Entries with dynamic types MUST use canonical ABI encoding and MUST be at most 2048 bytes. Any malformed encoding, trailing bytes, or size violation MUST be classified as general. 4. **No contract creation**: Any transaction or AA call that creates a new contract MUST be classified as general. 5. **AA atomicity**: An AA transaction is a payment only if `calls` is non-empty and **all** of its calls independently match the payment call allow-list. A single non-qualifying call MUST cause the entire transaction to be classified as general. 6. **Bounded key authorization**: Any transaction whose `key_authorization` is present and whose RLP encoding exceeds 1024 bytes MUST be classified as general. No consensus cap is placed on the overall transaction size. 7. **No access lists**: Any transaction with a non-empty `access_list` MUST be classified as general, regardless of type, targets, or calldata. Non-empty access lists allow carrying arbitrary data at payment lane gas prices. 8. **No authorization lists**: Any transaction with a non-empty `authorization_list` or non-empty `tempo_authorization_list` MUST be classified as general.