Contract authorization
How to authorize Aquarius contract calls without the official SDKs, and the exact authorization tree each write operation needs.
Every Aquarius write runs require_auth on your account, and some also need authorization for nested calls such as token transfers. The official SDKs build that authorization on the client for every call they sign. This page is for integrations in other languages: it describes the same pattern and lists the authorization tree of each operation.
Authorize a call in four steps
Build the invocation tree. The root is the contract function you call, with its exact arguments. Below it, add every nested call that requires your authorization, also with its exact arguments: the token transfers and share burns listed in the table below.
Attach it as a source-account entry. Wrap the root invocation in a
SorobanAuthorizationEntrywith source-account credentials and put it in theauthlist of theInvokeHostFunctionoperation. The transaction signature covers a source-account entry, so it needs no separate signature.Simulate in enforcing mode. Call the RPC's
simulateTransactionwithauthModeset toenforce. Simulation then checks the tree you supplied and fails if the call needs authorization the tree does not contain.Assemble resources and fee only. Take the footprint, resource limits, and resource fee from the simulation, and keep the operation and its
authlist exactly as you built them. Stellar SDK assembly helpers fill an emptyauthlist from the simulation result: clear the simulated authorization before assembling, then compare the assembled operation with the one you built and do not sign if it changed.
Then sign the envelope and submit it. For a call that needs no authorization, pass an empty auth list and keep it empty through assembly.
Read-only calls and estimates (estimate_swap, get_pools, and others) can use recording simulation to obtain return values. Their recorded authorization never enters a transaction you sign.
Authorization trees
Arguments use the parameter names of the contract interface. router is the router address, pool is the pool contract address (see get_pools), collector is your fee collector, and factory is the provider swap fee factory. share_token is the pool's LP share token (share_id on the pool). Transfer and burn amounts are i128; every other argument keeps the type of the function signature. The user (or sender, owner, operator) argument is the transaction source account.
Router swap, exact input
router.swap_chained(user, swaps_chain, token_in, in_amount, out_min)
token_in.transfer(user, router, in_amount)
Router swap, exact output
router.swap_chained_strict_receive(user, swaps_chain, token_in, out_amount, max_in)
token_in.transfer(user, router, max_in); the router refunds the unused input
Router single-pool swap
router.swap(user, tokens, token_in, token_out, pool_index, in_amount, out_min)
pool.swap(user, in_idx, out_idx, in_amount, out_min), which contains token_in.transfer(user, pool, in_amount)
Direct pool swap, exact input
pool.swap(user, in_idx, out_idx, in_amount, out_min)
token_in.transfer(user, pool, in_amount)
Direct pool swap, exact output
pool.swap_strict_receive(user, in_idx, out_idx, out_amount, in_max)
token_in.transfer(user, pool, in_max); the pool refunds the unused input
Provider-fee swap
collector.swap_chained(user, swaps_chain, token_in, in_amount, out_min, fee_fraction) or collector.swap_chained_strict_receive(user, swaps_chain, token_in, out_amount, in_max, fee_fraction)
token_in.transfer(user, collector, in_amount) or token_in.transfer(user, collector, in_max)
Provider-fee swap to a recipient
collector.swap_chained_to(user, to, swaps_chain, token_in, in_amount, out_min, fee_fraction) or collector.swap_chained_strict_receive_to(user, to, swaps_chain, token_in, out_amount, in_max, fee_fraction)
token_in.transfer(user, collector, in_amount) or token_in.transfer(user, collector, in_max); to does not sign
Claim provider fees
collector.claim_fees(operator, token) or collector.claim_fees_and_swap(operator, swaps_chain, token, out_min)
None
Deploy a fee collector
factory.deploy_swap_fee_contract(operator, fee_destination, max_swap_fee_fraction, swap_fee_fraction_denominator)
None
Create a pool
router.init_standard_pool(user, tokens, fee_fraction), router.init_stableswap_pool(user, tokens, fee_fraction) or router.init_concentrated_pool(user, tokens, fee)
payment_token.transfer(user, payment_address, amount) when the call deploys a new pool and amount is above zero; none otherwise. See pool creation payment
Router deposit
router.deposit(user, tokens, pool_index, desired_amounts, min_shares)
pool.deposit(user, desired_amounts, min_shares), which contains token.transfer(user, pool, desired_amounts[i]) per pool token: every token on volatile pools, including zero amounts; nonzero amounts only on stable and concentrated pools
Router withdraw
router.withdraw(user, tokens, pool_index, share_amount, min_amounts)
pool.withdraw(user, share_amount, min_amounts), which contains share_token.burn(user, share_amount) on volatile and stable pools and nothing on concentrated pools
Direct pool deposit
pool.deposit(user, desired_amounts, min_shares)
token.transfer(user, pool, desired_amounts[i]) per pool token: every token on volatile pools, including zero amounts; nonzero amounts only on stable and concentrated pools
Direct pool withdraw
pool.withdraw(user, share_amount, min_amounts)
share_token.burn(user, share_amount) on volatile and stable pools; none on concentrated pools
Router reward claim
router.claim(user, tokens, pool_index)
pool.claim(user)
Direct reward claim
pool.claim(user)
None
Rewards opt-in or opt-out
pool.set_rewards_state(user, state)
None
Concentrated deposit
pool.deposit_position(sender, tick_lower, tick_upper, desired_amounts, min_liquidity)
token.transfer(sender, pool, desired_amounts[i]) per nonzero amount; the pool refunds what the range does not use
Concentrated withdraw
pool.withdraw_position(owner, tick_lower, tick_upper, amount, min_amounts)
None
Concentrated fee claim
pool.claim_position_fees(owner, tick_lower, tick_upper) or pool.claim_all_position_fees(owner)
None
The collector authorizes its own transfer into the router as the current contract, so a provider-fee tree ends at your transfer into the collector. AQUA rewards on every pool type can be claimed through the router or directly on the pool.
Pool creation payment
The router reads the payment for a new pool from its own configuration: payment_token from get_init_pool_payment_token, payment_address from get_init_pool_payment_address, and amount from get_standard_pool_payment_amount, get_stable_pool_payment_amount or get_conc_pool_payment_amount, by pool type. Read them by simulation before you build the tree.
init_standard_pool and init_concentrated_pool return the existing pool when one with the same tokens and fee already exists, and then transfer nothing. init_stableswap_pool deploys a new pool on every call, so it always transfers the payment. An authorized transfer that the call never makes does not fail the transaction, so a tree that includes the payment also works when the pool already exists.
Related reference
Router & pool contracts — signatures and parameters of the router, pool, and provider fee functions.
Contract interface reference — concentrated pool functions.
Backend API — the Find Path API that returns
swaps_chain.Error codes — contract errors returned by simulation and execution.
Last updated