SDK Overview

The taurusSwap SDK is a TypeScript library for interacting with Orbital AMM pools. It handles all the complex math (solving the torus invariant), state reading, and transaction construction.

What the SDK Does

• Reads pool state — Decodes global state and box storage into typed objects
• Computes quotes — Solves the torus invariant to find output amounts
• Builds transactions — Constructs atomic transaction groups for swaps, adding liquidity, and claiming fees
• Handles unit conversions — Converts between display, raw, and scaled units automatically

What It Doesn't Do

• Sign transactions — You provide a signer (from Pera, Defly, etc.)
• Send transactions — You call algodClient.sendGroupTransaction
• Manage wallets — Use algosdk or a wallet adapter for that

Three-Layer Architecture

┌─────────────────────────────────┐
│  @taurus-swap/sdk/algorand       │  ← Transaction builders
│  - buildSwapTransactionGroup()  │
│  - buildAddLiquidityGroup()     │
│  - signAndSend()                │
├─────────────────────────────────┤
│  @taurus-swap/sdk/pool           │  ← Pool-level operations
│  - readPoolState()              │
│  - getSwapQuote()               │
│  - computeDepositPerToken()     │
├─────────────────────────────────┤
│  @taurus-swap/sdk/math           │  ← Pure math (BigInt)
│  - solveTorusInvariant()        │
│  - polarDecompose()             │
│  - consolidateTicks()           │
└─────────────────────────────────┘

Design Principles

• Pure BigInt — Zero runtime floats. All math uses integer arithmetic for determinism.
• Reference-accurate — The SDK matches the Python reference implementation to 15+ decimal places.
• Type-safe — Full TypeScript types for all inputs and outputs.
• Composable — Each function is a pure building block. Chain them together for complex operations.

Minimal Example

import {
  readPoolState,
  getSwapQuote,
  buildSwapTransactionGroup
} from '@taurus-swap/sdk';
import algosdk from 'algosdk';

// Initialize
const algodClient = new algosdk.Algodv2(
  'TOKEN',
  'https://testnet-api.algonode.cloud',
  ''
);

const POOL_APP_ID = 758284478;

// Read pool state
const poolState = await readPoolState(algodClient, POOL_APP_ID);

// Get quote
const quote = await getSwapQuote(poolState, {
  tokenInIndex: 0,
  tokenOutIndex: 1,
  amountIn: 100_000_000n  // 100 USDC
});

console.log(`Output: ${quote.amountOut} microunits`);
console.log(`Price impact: ${quote.priceImpact * 100}%`);

// Build and sign transaction
const { txGroup, signer } = await buildSwapTransactionGroup(
  algodClient,
  POOL_APP_ID,
  account,
  {
    tokenInIndex: 0,
    tokenOutIndex: 1,
    amountIn: 100_000_000n,
    minOut: quote.amountOut * 995n / 1000n,  // 0.5% slippage
    claimedOut: quote.amountOut
  }
);

const result = await algodClient.sendGroupTransaction(txGroup).do();
console.log('TX ID:', result.txId);

Modules

Error Handling

The SDK throws typed errors for common failure modes:

import {
  InsufficientLiquidityError,
  InvalidTradeDirectionError,
  TickCrossingError,
  BoxNotFoundError
} from '@taurus-swap/sdk';

try {
  const quote = await getSwapQuote(poolState, trade);
} catch (err) {
  if (err instanceof InsufficientLiquidityError) {
    // Pool doesn't have enough output tokens
  } else if (err instanceof TickCrossingError) {
    // Trade would cross too many ticks
  }
}

Next Steps

• Installation — Package setup
• Reading Pool State — Decode on-chain state
• Quoting Swaps — Compute trade outputs
• Executing Swaps — Build and send transactions