Tips & tricks

How much TPS can a single Relayer handle?

In theory, a Relayer could handle more than 1 transaction per second. But in practice, we recommend assuming 1 Relayer = 1 TPS for reliability and nonce safety.

Because each transaction needs a fresh, incremented nonce, two transactions submitted too closely in time by the same Relayer can cause nonce collisions or failures. This will change in the future when Starknet introduces nonce abstraction, removing this bottleneck.

✅ Rule of thumb: 1 Relayer per 1 expected peak TPS.

How many relayers should I deploy?

Estimate your maximum expected transactions per second (TPS) during your busiest period, and deploy at least that many relayers.

✅ Example: if your dApp could receive 50 tx/sec during a mint or campaign → deploy at least 50 relayers for safe and smooth operation.

📌 You can always deploy more relayers later using:

cargo run --bin paymaster-cli deploy-relayers ...

Do I need to rebalance relayers manually?

No. The Paymaster handles auto-rebalancing between the Gas Tanker and relayers when configured. It swaps supported tokens (like USDC, ETH, DOG, etc.) to STRK via a DEX (e.g., AVNU)

Redistributes STRK to relayers evenly.

Can I add new gas tokens?

Yes — super easily. Supporting a new token only requires:

Adding its contract address to supported_tokens in the config
Ensuring a price feed is available (e.g., via AVNU Impulse API)

✅ That’s 1 line in your config file.

What’s the difference between gasless and gasfree again?

Type	Who Pays?	Use Case
Gasless	The user, but with any token you support	Let users pay in USDC/DOG instead of STRK
Gasfree	You (the dApp/paymaster)	Sponsor user tx for onboarding, rewards, etc

Can I switch from AVNU Paymaster to my own later and vice-versa?

Yes! That’s the power of SNIP‑29.

Integrate now using the AVNU Paymaster endpoint → when you're ready, deploy your own instance and just switch the endpoint.

Nothing changes in your client integration.

How do I sponsor a transaction?

What if I want to sponsor only some transactions?

You can customize sponsorship using the webhook mode. All it takes is you to Implement an external service/endpoint to decide in real time if a tx is eligible

You could easily do for example sponsor "only the first tx", "free if the user holds this NFT", etc

full guide on sponsoring.webhook.

Can I run multiple Paymaster instances in parallel?

Yes, this is horizontal scaling. For that, you can use the relayer "lock" mode in your configuration:

Choose:

"segregated": each instance has its own set of relayers (simpler)
"shared": multiple instances coordinate access via Redis locks

This lets you scale horizontally without nonce issues.

How do I configure things securely?

Use this pattern:

Sensitive data (e.g., relayer private keys) → env vars
General config → JSON profile
emporary overrides/testing → CLI args

Env > CLI > Profile
The Paymaster merges them automatically in this priority order.

How do I monitor my Paymaster?

Use OpenTelemetry.

The Paymaster can export metrics, logs, and traces to Prometheus or AWS (via OTEL Collector).

To enable it:

Set monitoring.*.endpoint in config
Add auth headers via env vars if needed

Docs cover both local Prometheus and AWS OTEL setup examples.

Why does the estimate account need to be separate?

Because it must never send real transactions. It’s used only to simulate and estimate transaction costs. If reused for execution, it will get stuck due to nonce drift.

✅ Keep it isolated and always funded.