Swaps

Anoma Pay can swap one shielded token for another in a single atomic transaction. The user’s token A leaves the shielded pool, is traded on a public venue, and the proceeds re-enter the shielded pool as token B in one on-chain execution. If any step fails, the whole transaction reverts and the user keeps their original balance.

private resource (token A) → [unwrap → swap on venue → wrap] → private resource (token B)

Swaps are currently filled through Bebop , an RFQ (request-for-quote) venue where professional market makers quote a firm price. The quote’s minimum buy amount is exactly what the user receives. Additional on-chain routing sources are planned, which will extend swaps to a wider set of tokens and venues.

How a swap executes

A swap transaction is composed of three balanced resource legs:

All three legs are proven and executed atomically. The forwarder holds funds only transiently, inside the transaction, meaning that it has no custody of user funds before or after. See Generic Calls for how this mechanism works at the protocol level.

The quote lifecycle

Bebop quotes are firm but short-lived. Because the swap’s out-amount is signed into the action tree before proving starts, the quote must remain valid through the entire proving window. The backend enforces this twice:

1. At validation: the quote must have enough lifetime left to cover proof generation (a configurable safety margin). Too-old quotes are rejected before any proving cost is incurred.
2. Before broadcast: a quote that expired while proofs were being generated aborts the submission rather than reverting on-chain.

Both rejections surface the stable error code SWAP_QUOTE_EXPIRED. On this error, fetch a fresh quote, rebuild, and resubmit.

Building a swap

import { TransferBackendClient } from "@anomaorg/anoma-app-sdk";
 
const backend = new TransferBackendClient("https://backend.anoma.money");
 
const quote = await backend.swapQuote(chain.network, {
  sellTokenAddress: tokenA.address,
  buyTokenAddress: tokenB.address,
  sellAmount: 10_000_000n,                                  // 10 USDC (6 decimals)
  genericForwarderAddress: chain.genericCallForwarderAddress,
});
// quote.buyAmount      — expected amount of token B
// quote.minBuyAmount   — guaranteed minimum (what the swap actually fills at)
// quote.expiry         — Unix timestamp; the quote is executable until then
// quote.approvalTarget — contract the sell token must be approved to
// quote.tx             — { to, value, data }: the venue transaction to execute

import { buildSwapCalls } from "@anomaorg/anoma-app-sdk";
 
const calls = buildSwapCalls({
  tokenA: tokenA.address,
  tokenB: tokenB.address,
  sellAmount: 10_000_000n,
  minBuyAmount: BigInt(quote.minBuyAmount),
  txData: quote.tx.data,                  // opaque venue calldata
  destinationAddress: quote.tx.to,        // venue settlement contract
  txAmount: BigInt(quote.tx.value),
  approvalTarget: quote.approvalTarget,
});
// calls[0] — tokenA.approve(approvalTarget, sellAmount)
// calls[1] — the venue swap transaction
// calls[2] — tokenB.approve(Permit2, minBuyAmount)

import {
  TransferBuilder,
  SwapResolver,
  PayloadBuilder,
} from "@anomaorg/anoma-app-sdk";
 
const transferBuilder = await TransferBuilder.init(
  chain.transferLogicVerifyingKey,
  chain.trivialLogicVerifyingKey
);
const resolver = new SwapResolver(transferBuilder, keyring, chain);
 
const resolved = resolver.resolve({
  senderResources: resources,             // the user's token A resources
  tokenA,
  tokenB,
  swapAmount: 10_000_000n,                // excludes the fee
  minBuyAmount: BigInt(quote.minBuyAmount),
  calls,
  fee,                                    // Relayer fee, paid in token A
});

const parameters = new PayloadBuilder(resolved)
  .withAuthorization(keyring.authorityKeyPair.privateKey)
  .build();
 
const { transaction_hash: txId } = await backend.transfer(parameters);

After submission the transaction follows the same lifecycle as a transfer, see Transaction lifecycle.

Slippage settings

By default (“auto”), the committed minimum is the quote’s own minBuyAmount (the market maker’s firm price). A custom slippage tolerance recomputes the committed minimum as buyAmount × (1 − slippage) instead.

Errors

What’s next

RFQ is the first swap venue, chosen because firm, longer-lived quotes fit naturally with proving-time constraints. Support for on-chain routing sources (DEX aggregation) is in the works, the execution model described above already accommodates them, and the SDK surface is venue-agnostic. Quotes arrive in the same shape regardless of where they are filled.