Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

  1. 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.

  2. Attach it as a source-account entry. Wrap the root invocation in a SorobanAuthorizationEntry with source-account credentials and put it in the auth list of the InvokeHostFunction operation. The transaction signature covers a source-account entry, so it needs no separate signature.

  3. Simulate in enforcing mode. Call the RPC's simulateTransaction with authMode set to enforce. Simulation then checks the tree you supplied and fails if the call needs authorization the tree does not contain.

  4. Assemble resources and fee only. Take the footprint, resource limits, and resource fee from the simulation, and keep the operation and its auth list exactly as you built them. Stellar SDK assembly helpers fill an empty auth list 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.

Operation
Root call
Sub-invocations

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.

Last updated