Relayers and meta transactions

You want a user to transact without holding the native token for gas.

Who this is for: developers building a gasless or "sponsored transaction" flow. Prerequisites: Account Abstraction & Intents (concept: read this first for what a smart account and paymaster are); Networks & Endpoints.

How gasless transactions work on Lumia

Lumia's account-abstraction stack (ERC-4337: smart account, factory, EntryPoint, paymaster; see /lumia/architecture/account-abstraction) is the path that's been built and exercised as a demo on Beam testnet. A paymaster contract, LumiaPaymaster, is a Foundry-based reference implementation deployed per-integrator via a script, not a single shared instance you point at. See /reference/contract-addresses for the EntryPoint address and the deploy-your-own model, and /reference/sdks for its packaging status.

This means "meta-transaction" on Lumia today is, concretely: submit a UserOperation to the EntryPoint through a bundler, with your own deployed LumiaPaymaster sponsoring gas according to whatever policy you configure (per-account, global, or a gas allowance). It is not a classic ERC-2771 trusted-forwarder relay pattern layered on top of ordinary transactions.

Steps (paymaster-sponsored path)

1

Deploy your own LumiaPaymaster instance

forge script script/DeployLumiaPaymaster.s.sol --rpc-url https://beam-rpc.lumia.org --broadcast

2

Fund the paymaster contract

Fund it with native token so it can pay for the gas it sponsors.

3

Build the UserOperation

Build the UserOperation for the call you want sponsored, referencing the EntryPoint address from /reference/contract-addresses, and your paymaster's address in the paymasterAndData field.

4

Submit it to a bundler

Submit the UserOperation to a bundler pointed at Lumia Beam.

Verify it worked

Look up the resulting UserOperation hash (or its included transaction hash, once bundled) on the Beam explorer (https://beam-explorer.lumia.org/) and confirm the sender account paid zero native-token gas out of its own balance. The paymaster's balance should have decreased instead.

Troubleshooting

UserOperation rejected by the bundler

Confirm the EntryPoint address matches the one in /reference/contract-addresses exactly; a stale or mistyped address is the most common cause.

Paymaster sponsorship silently not applied

Check the paymaster's own native-token balance; an empty paymaster can't sponsor gas.