Crate stellar_fee_abstraction 

Fee Abstraction Module

This module provides utilities for implementing fee abstraction in Stellar contracts, allowing users to pay transaction fees in tokens instead of native XLM.

Core Features

• Target invocation and fee collection helper
• Fee Token Allowlist: Optional allowlist for accepted fee tokens
• Token Sweeping: Optional functions to collect accumulated fees
• Fee Validation: Utilities for validating fee amounts
• Approval strategies: utilities for collecting fee from users support two approval semantics:
  • FeeAbstractionApproval::Eager: always approve max_fee_amount (overwriting any existing allowance)
  • FeeAbstractionApproval::Lazy: only approve if the current allowance is less than max_fee_amount

Usage

This module provides storage functions and event helpers that can be integrated into a fee forwarding contract. The implementing contract is responsible for the authorization checks and who can manage fee tokens or sweep collected fees.

Structs

FeeCollected

Event emitted when a fee is collected from a user.

FeeTokenAllowlistUpdated

Event emitted when a fee token is added or removed from the allowlist.

ForwardExecuted

Event emitted when a call is forwarded to a target contract.

TokensSwept

Event emitted when tokens are swept from the contract.

Enums

FeeAbstractionApproval

Approval strategy for fee collection helpers.

FeeAbstractionError

Errors that can occur in fee abstraction operations.

FeeAbstractionStorageKey

Constants

FEE_ABSTRACTION_EXTEND_AMOUNT

TTL threshold for extending storage entries (in ledgers)

FEE_ABSTRACTION_TTL_THRESHOLD

TTL extension amount for storage entries (in ledgers)

Statics

__SPEC_XDR_EVENT_FEECOLLECTED

__SPEC_XDR_EVENT_FEETOKENALLOWLISTUPDATED

__SPEC_XDR_EVENT_FORWARDEXECUTED

__SPEC_XDR_EVENT_TOKENSSWEPT

__SPEC_XDR_TYPE_FEEABSTRACTIONERROR

Functions

collect_fee

Low-level helper to collect a fee from the user in a given token by checking whether the token is allowed when allow list is enabled.

collect_fee_and_invoke

Collect the fee and invoke the target contract (forward).

emit_fee_collected

Emits an event when a fee is collected from a user.

emit_fee_token_allowlist_updated

Emits an event when a fee token is added or removed from the allowlist.

emit_forward_executed

Emits an event when a call is forwarded to a target contract.

emit_tokens_swept

Emits an event when tokens are swept from the contract.

is_allowed_fee_token

Check if a token is allowed for fee payment.

is_fee_token_allowlist_enabled

Check if the fee token allowlist is enabled. It is considered enabled if at least one fee token has been added to the allowlist.

set_allowed_fee_token

Allow or disallow a token for fee payment.

sweep_token

Sweep accumulated tokens from the contract to a recipient.

validate_expiration_ledger

Validate the ledger is in the future.

validate_fee_bounds

Validate that the fee amount does not exceed the maximum allowed or is <= 0.