Architecture Overview

At a high level, the AVNU Paymaster is composed of a service layer and on-chain contracts. It abstracts gas fees for users by determining how fees are paid. In the case of gas-free transactions, it also determines who sponsors the transaction. Here's how the core components interact:

For the detailed Paymaster API specification defined by SNIP-29, see the official schema:SNIP-29 Paymaster API JSON
is composed of a service layer and on-chain contracts. It abstracts gas fees for users by determining how fees are paid. In the case of gas-free transactions, it also determines who sponsors the transaction. Here's how the core components interact:

Components and Roles

Paymaster Service: The Rust-based backend that handles logic, pricing, authorization, and routing of transactions through relayers.

Forwarder Contract: The central on-chain contract that validates and forwards transactions. It ensures only whitelisted relayers can interact and enforces execution constraints.

Relayer Accounts: These accounts are responsible for submitting & paying for transactions to the blockchain. Each relayer can process one transaction at a time due to nonce handling.

Estimate Account: A specific relayer dedicated to estimating transaction fees. It must maintain a stable nonce, which is why it should not be used for actual execution.

Gas Tank: An account dedicated to receive all users token payment, it will be use to swap tokens back to STRK and refill relayers once a while.

High-Level Flow

This architecture ensures a clear separation of responsibilities, safe nonce management, and the ability to scale horizontally and vertically by managing relayer accounts effectively.

Forwarder

The Forwarder is the core on-chain contract of the AVNU Paymaster. It executes user transactions, collects gas fees, and ensures that only authorized relayers can submit transactions.

✅ Audited by Nethermind - Read the audit & Read the code

Responsibilities

• Executes transactions on behalf of users (gasless & gasfree)
• Restricts access to whitelisted relayers
• Collects gas tokens and routes them to a configurable recipient (The GasTank)
• Emits events for sponsored (gasfree) flows
• Supports ownership and upgradability

How it works

There are two main methods:

• execute(...): For gasless transactions. The user pays in any supported token. Tokens are routed to the gas_fees_recipient.
• execute_sponsored(...): For gasfree/sponsored transactions. No token transfer is done; instead, a SponsoredTransaction event is emitted with custom metadata.

Other functions let you set or get the gas fees recipient(aka Gas Tank), all gated by ownership checks.

Relayers, GasTank & Estimate Accounts

All contracts representing the Relayers, the Gas Tank or the Estimate account are Ready(formerly ArgentX) Contracts - Read the code