Skip to main content

@provablehq/shield-swap-sdk

@provablehq/shield-swap-sdk is a viem-shaped client for shield_swap_v3.aleo, the concentrated-liquidity AMM on Aleo: private two-phase swaps, liquidity management, direct on-chain reads, and a typed off-chain DEX API — all composed onto one client via extend(). Chain reads and writes sit flat on the client (client.getPool, client.swap); the DEX API sits under client.api, so a call site always shows whether a value came from the chain or the service.

The Integrating Shield Swap guide walks the full flow — client setup, quote, the two-phase swap and claim, liquidity, and balances. The /api/shield-swap reference pages document each action's parameters, return shape, and errors.

Installation​

npm install @provablehq/veil-core @provablehq/shield-swap-sdk

Signing with a local private key also needs @provablehq/sdk as a peer — it derives the blinded identity a private swap is claimed with. A connected wallet performs that derivation itself, so the dependency is not needed on the wallet path.

Client pairings​

The signer determines which @provablehq/veil-core client shieldSwapActions extends. In a browser dApp, pair it with @provablehq/veil-aleo-react-hooks; the connected wallet holds the keys and records and proves, so the app carries no key, proving config, or scanner. In a bot, script, or agent trader, pair it with @provablehq/veil-aleo-sdk for a local key with delegated or local proving. Read-only pool and price queries need only a PublicClient over a transport — no key, proving, or scanner.

Example​

A local-key client swapping on testnet. createAleoClient wires the account, transport, and proving config in one call; the scanner finds the private records the swap spends.

import { loadNetwork } from '@provablehq/veil-aleo-sdk'
import { shieldSwapActions } from '@provablehq/shield-swap-sdk'

const aleo = await loadNetwork('testnet')
const { walletClient } = aleo.createAleoClient({
  privateKey: PRIVATE_KEY,
  networkUrl: 'https://edge.provable.com/api/v2',
  provingMode: 'delegated',
  proverUrl: 'https://edge.provable.com/api/prove',
  records: aleo.createRemoteScanner({
    url: 'https://edge.provable.com/api/scanner',
  }),
})
const client = walletClient.extend(
  shieldSwapActions({ api: {} }),
)

const handle = await client.swap({
  poolKey,
  tokenInId,
  amountIn: 1_000_000n,     // raw atomic amount, bigint
  expectedOut,              // a real quote, scaled to base units
  slippageBps: 50,          // 0.5%
  tokenInProgram,           // the token's wrapper program
  imports,                  // token program sources for dynamic dispatch
})
// …then claim once the request finalizes:
const { amountOut } = await client.claimSwapOutput({ handle, imports })

The guide shows where each input comes from — pool discovery, quoting, the imports map — and the wallet-signer variants.

Key exports​

  • shieldSwapActions(config) — the extend() decorator; chain reads/writes flat on the client, the DEX API under .api. Defaults to shield_swap_v3.aleo and the Provable API; override with shieldSwapActions({ program, api: { baseUrl } }).
  • Swaps — swap → claimSwapOutput (the two-phase private swap), the serializable SwapHandle between them, and SwapOutputNotFinalizedError for the retry loop.
  • Liquidity — createPool, mint, increaseLiquidity, decreaseLiquidity, collect, burn.
  • Reads — getPool, getSlot, getSwapOutput; combined balances via getBalances and getPrivateBalances.
  • DEX API auth — client.authenticateShieldSwap() (session handshake signed by the account, auto-renewing), ApiClient.getReferralStatus / redeemReferralCode for the one-time referral-code gate, and ApiClient.createApiToken / listApiTokens / revokeApiToken for long-lived ss_… keys passed as api: { apiToken }. Most API endpoints beyond discovery are bearer-gated — see the guide.
  • Wallet grants — SHIELD_SWAP_ALGORITHM_GRANTS, shieldSwapAlgorithmGrants — the connect-time algorithm allowlist a wallet-signer setup passes so the wallet may derive blinded identities.

Concurrent swaps and record management​

Enable recordManagement when creating the wallet client, then attach shieldSwapActions(). Local swaps can select different records from shared inventory when several trades sell the same token. A separate persistent blinded identity store retains the handles needed to claim their outputs.

The concurrent swaps walkthrough covers client configuration, six-record preparation, submission, claims, and partial failures. The record management guide documents storage, defaults, fee limits, helper programs, and recovery. Coordination is off by default and does not start automatic maintenance.

Subpaths​

  • @provablehq/shield-swap-sdk/agent — createShieldSwapAgentTools({ client, api, includeWrites? }) and shieldSwapAgentToolSchemas(). Read tools are included by default; money-moving write tools are opt-in via includeWrites.
  • @provablehq/shield-swap-sdk/mcp — createShieldSwapMcpServer({ client, api }).

The package README covers program imports and codegen in full: README.