Skip to main content
Starknet’s privacy pool holds funds in a shielded balance, so amounts and balances stay off the public ledger. avnu’s paymaster lets users interact with that pool without compromising their privacy: actions are proven client-side with zk-proofs, and the relayer submits the transaction on-chain, so you never expose a public account to pay gas and link yourself back to your private balance.
Preview. Private transactions rely on the Starknet privacy SDK and @avnu/avnu-sdk >= 4.1.0-next.2. The API surface may still change. Questions? Reach out on Telegram.

​
How it works

A private transaction never moves tokens from a public account. Instead, it goes through three steps:
  1. Private balance. Tokens you deposit into the privacy pool are held as shielded notes, so balances and amounts stay off the public ledger.
  2. Proof. Each action (withdraw, transfer, swap) becomes a proof you build client-side with the privacy SDK, against a recent provingBlockId.
  3. Execution. The paymaster bundles the proof into a single on-chain transaction through its forwarder contract, and can pay the gas on your behalf.

​
Fee modes

Every private transaction carries two costs: the gas fee that goes to the network, and the pool fee that goes to the privacy pool. Who pays each one, and in which token, depends on the fee mode you pick.
ModeGas feePool feeFee token
sponsoredPaid by relayerPaid by user from private balanceAlways STRK (hardcoded)
sponsored_private (recommended)Paid by relayerPaid by user from private balanceUser’s choice via fee_mode.pool_fee_token
gasless (default)Paid by user from private balancePaid by user from private balanceUser’s choice via fee_mode.gas_token
On the avnu app, avnu sponsors the gas, so users only pay the pool fee. When you integrate private transactions yourself, you decide who pays: let users cover gas with gasless, or sponsor it for them using a paymaster API key from the Portal with sponsored or sponsored_private. The API key setup is the same as gasfree.
Go with sponsored_private. The relayer covers gas while the user pays the pool fee in any supported token, and the paymaster converts the base STRK amount through its price oracle.
sponsored_private only works with private transaction types (apply_action / invoke_and_apply_action). Using it with invoke, deploy, or deploy_and_invoke returns error 168 (SPONSORED_PRIVATE_REQUIRES_PRIVACY).

​
Transaction types

TypeWhenExample
apply_actionNo user call neededWithdraw, private swap
invoke_and_apply_actionA user call is required (such as an approve), wrapped in execute_from_outside and signed by the userDeposit

​
Prerequisites

Before you start, make sure you have:
  • @avnu/avnu-sdk >= 4.1.0-next.2, which adds the private: true flag to quoteToCalls
  • the Starknet privacy SDK, which builds the proof and the executor call
  • a funded private balance for the token you want to sell, so deposit into the pool first
  • the paymaster client pointing at starknet.paymaster.avnu.fi, or sepolia.paymaster.avnu.fi for testing

​
Next steps

Private Swap via avnu

Execute a sponsored, gasless private swap step by step