Skip to main content

Fee forwarder

FeeForwarderContract collects a fee in fee_token, invokes a target, and returns the target's raw Val. Collection and invocation share one transaction.

Entry points​

fn forward(
e: Env,
fee_token: Address,
fee_amount: i128,
max_fee_amount: i128,
expiration_ledger: u32,
target_contract: Address,
target_fn: Symbol,
target_args: Vec<Val>,
user: Address,
fee_recipient: Address,
) -> Val

fn forward_dynamic(
e: Env,
fee_token: Address,
fee_amount: i128,
max_fee_amount: i128,
expiration_ledger: u32,
target_contract: Address,
target_fn: Symbol,
target_args: Vec<Val>,
user: Address,
fee_recipient: Address,
) -> Val

e is the Soroban environment. It is not a serialized invocation argument.

ArgumentUnit or typeMeaning
fee_tokenAddressToken contract used for the relay fee.
fee_amounti128, fee-token atomic unitsActual charge. It must be positive and at most max_fee_amount.
max_fee_amounti128, fee-token atomic unitsSigned fee cap.
expiration_ledgeru32, ledger sequenceSigned live-until ledger for the fee allowance.
target_contractAddressContract to invoke after collection.
target_fnSymbolTarget entry point.
target_argsVec<Val>Positional target arguments.
userAddressFee payer that must authorize.
fee_recipientAddressSigned destination of the actual fee.

Fee-token atomic units use that token's decimals. They match market token-dec only when both flows use the same token.

Signed arguments​

Both functions call user.require_auth_for_args. The authorization root names the invoked forwarder function and contains these arguments in order:

Positionforwardforward_dynamic
0fee_tokenfee_token
1max_fee_amountmax_fee_amount
2expiration_ledgerexpiration_ledger
3fee_recipientfee_recipient
4target_contracttarget_contract
5target_fntarget_fn
6target_argsOmitted

fee_amount is unsigned in both variants. The submitter chooses the actual charge within the signed cap. The payer is the authorization entry's address. With forward, changing any target argument needs fresh authorization. With forward_dynamic, the submitter can change every target argument under the same root authorization.

A market create_order sub-invocation binds its order arguments. Its escrow transfer appears beneath that market authorization. Permissionless fills need no user authorization. The nested authorization tree therefore has its own scope. It does not turn forward_dynamic into a signature over the complete target invocation.

Dynamic arguments remain mutable

The dynamic root does not bind the router's batch, report, or keeper argument. Nested target authorizations bind the user actions that need authorization. A target can accept different unsigned arguments and still succeed. The forwarder can then collect the fee without producing the action a caller expected.

Collection and the fee allowance​

collect_and_invoke first rejects a target_fn of transfer_from or burn_from. It also rejects the forwarder itself as fee_recipient. It then calls collect_fee with FeeAbstractionApproval::Eager. Collection runs before the target:

  1. Approve max_fee_amount from user to the forwarder, with the signed expiration_ledger.
  2. Pull the full max_fee_amount from user into the forwarder through transfer_from.
  3. Transfer fee_amount from the forwarder to fee_recipient.
  4. Return max_fee_amount - fee_amount to user when the remainder is positive.
  5. Emit fee_collected, then invoke the target.

The approval overwrites an existing allowance to the forwarder. Successful collection consumes the full approval, so the resulting allowance is zero. The user's fee authorization includes one token approve sub-invocation:

approve(user, forwarder, max_fee_amount, expiration_ledger)

Target calls that authenticate user follow beneath the same root. Their nested transfers carry their own signed arguments. The forwarder authorizes its transfer_from as the spender. The fee and refund transfers authenticate the forwarder's own frame, so they add no user authorization entry.

A trap restores all state to its value before the invocation. That includes the previous allowance, token transfers, target writes, and events.

The forwarder holds the cap during collection. Successful collection distributes the entire cap before the target call. Unrelated token balances have no withdrawal entry.

The cap must be spendable

The fee leg temporarily pulls the full cap. A balance sufficient for the quoted fee can still fail this transfer. The remainder returns before the target runs. The user also needs the funds that the target action spends after collection.

Expiration​

expiration_ledger belongs to the token allowance. Authorization entries also carry their own signatureExpirationLedger. Orders carry a separate order expiration. These deadlines are distinct. A valid allowance deadline does not extend an expired authorization or order.

The forwarder passes expiration_ledger unchanged to approve. The fee token enforces its deadline rules. The library's lazy-expiration check does not run. For the Stellar Asset Contract, a positive approval needs a deadline at or after execution. The deadline must also fit the network's maximum live-until ledger.

Atomicity​

The forwarder invokes its target strictly through invoke_contract. A target trap reverts the fee. A successful target return commits the collection.

Router targetTarget outcomeFee outcome
multicallAny batch failure trapsReverted
multicall_tryRecoverable errors appear in returned elementsCollected
create_and_fillA batch or fill failure trapsReverted
create_and_try_fillA recoverable fill failure leaves the created orders restingCollected

An empty multicall can succeed and collect a fee. An empty create-and-fill batch traps and reverts the fee.

Transaction success can include a failed fill

An isolated router failure is a returned value. It can leave the transaction successful and the relay fee collected. The router reference defines the result encoding and the failures that abort the whole transaction.

Errors​

CodeVariantCondition
6001TargetNotAllowedtarget_fn is transfer_from or burn_from.
6002InvalidRecipientfee_recipient is the forwarder.
5003InvalidFeeBoundsfee_amount <= 0 or fee_amount > max_fee_amount.

The forwarder declares codes 6001 and 6002. Code 5003 comes from FeeAbstractionError. A zero-fee invocation raises 5003.

The library also declares these codes:

CodeVariantReachability through these entry points
5000FeeTokenNotAllowedThe allowlist count stays zero, so every fee token passes.
5001FeeTokenAlreadyAllowedOnly an allowlist mutation raises this. The forwarder exports none.
5002TokenCountOverflowOnly an allowlist mutation raises this.
5004NoTokensToSweepOnly a sweep raises this. The forwarder exports none.
5005InvalidUserCollection checks whether user is the forwarder. Root authorization fails first for that address.
5006InvalidExpirationLedgerOnly the lazy approval path raises this. The forwarder uses eager approval.

Token and target errors propagate from those contracts. Missing authorization, malformed arguments, prohibited re-entry, and resource limits can produce host failures. The market error catalog defines errors from market targets.

Events​

Emitting contractTopicsData map
Fee forwarderfee_collected, user: Address, recipient: Addressamount: i128, token: Address

amount is the actual fee in fee-token atomic units. token is fee_token. Successful collection emits one event, including when the target returns an isolated failure. A trap reverts the event. The token emits its own transfer and approval events. The target emits its own events.

Storage​

The forwarder has no constructor, configuration setters, owner, or upgrade entry. It declares no storage keys and extends no storage time-to-live.

collect_fee reads the library's instance key FeeAbstractionStorageKey::Count. An absent count is zero, which disables the fee-token allowlist. The forwarder never writes that key. The library's persistent allowlist keys therefore remain unused by these entry points.