> For the complete documentation index, see [llms.txt](https://docs.aqua.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aqua.network/developers/reference/contract-authorization.md).

# 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](https://docs.aqua.network/developers/integrating-with-aquarius.md#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](#authorization-trees).
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.

{% hint style="warning" %}
**Never sign the authorization that simulation records.** In recording mode, simulation returns an authorization entry for every `require_auth` the call reached on your account. A pool can hold any Soroban token, and a token's `transfer` can run arbitrary code, including a call that requires your authorization for something unrelated, such as a transfer of your pool shares. Signing the recorded authorization approves that call as well. A tree built from the arguments you intend covers only those calls, and enforcing simulation fails if the contract asks for anything else.
{% endhint %}

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](https://docs.aqua.network/developers/reference/addresses-and-networks.md), `pool` is the pool contract address (see `get_pools`), `collector` is your [fee collector](https://docs.aqua.network/developers/code-examples/add-fees-to-swap.md), 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](#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](https://docs.aqua.network/developers/reference/router-and-pool-contracts.md) — signatures and parameters of the router, pool, and provider fee functions.
* [Contract interface reference](https://docs.aqua.network/developers/concentrated-liquidity/contract-interface-reference.md) — concentrated pool functions.
* [Backend API](https://docs.aqua.network/developers/reference/backend-api.md) — the Find Path API that returns `swaps_chain`.
* [Error codes](https://docs.aqua.network/developers/reference/error-codes.md) — contract errors returned by simulation and execution.
