Atomic Swap

← Back to Transactions

Description

This example demonstrates how to perform an atomic swap of ALGO for ASA between two parties. In an atomic swap:

• Party A sends ASA to Party B
• Party B sends ALGO to Party A
• Each party signs ONLY their own transaction
• Signatures are combined and submitted together
• Both transfers succeed or both fail (atomicity) Key difference from regular atomic groups: different parties sign different transactions.

Prerequisites

• LocalNet running (via algokit localnet start)

Run This Example

From the repository root:

cd examples
npm run example transact/08-atomic-swap.ts

Code

View source on GitHub

08-atomic-swap.ts

/**
 * Example: Atomic Swap
 *
 * This example demonstrates how to perform an atomic swap of ALGO for ASA between two parties.
 * In an atomic swap:
 * - Party A sends ASA to Party B
 * - Party B sends ALGO to Party A
 * - Each party signs ONLY their own transaction
 * - Signatures are combined and submitted together
 * - Both transfers succeed or both fail (atomicity)
 *
 * Key difference from regular atomic groups: different parties sign different transactions.
 *
 * Prerequisites:
 * - LocalNet running (via `algokit localnet start`)
 */

import { AlgorandClient } from '@algorandfoundation/algokit-utils'
import type { PendingTransactionResponse } from '@algorandfoundation/algokit-utils/algod-client'
import {
  Transaction,
  TransactionType,
  assignFee,
  groupTransactions,
  type AssetConfigTransactionFields,
  type AssetTransferTransactionFields,
  type PaymentTransactionFields,
} from '@algorandfoundation/algokit-utils/transact'
import {
  createAlgodClient,
  formatAlgo,
  getAccountBalance,
  printHeader,
  printInfo,
  printStep,
  printSuccess,
  shortenAddress,
  waitForConfirmation,
} from '../shared/utils.js'

/**
 * Gets a funded account from LocalNet's KMD wallet
 */
async function getLocalNetFundedAccount(algorand: AlgorandClient) {
  return await algorand.account.kmd.getLocalNetDispenserAccount()
}

async function main() {
  printHeader('Atomic Swap Example (ALGO <-> ASA)')

  // Step 1: Initialize clients
  printStep(1, 'Initialize Algod Client')
  const algod = createAlgodClient()
  const algorand = AlgorandClient.defaultLocalNet()
  printInfo('Connected to LocalNet Algod')

  // Step 2: Get Party A from KMD (asset owner)
  printStep(2, 'Setup Party A (Asset Owner)')
  const partyA = await getLocalNetFundedAccount(algorand)
  const partyABalanceBefore = await getAccountBalance(algorand, partyA.addr.toString())
  printInfo(`Party A address: ${shortenAddress(partyA.addr.toString())}`)
  printInfo(`Party A ALGO balance: ${formatAlgo(partyABalanceBefore.microAlgo)}`)

  // Step 3: Generate and fund Party B using AlgorandClient helper
  printStep(3, 'Setup Party B (ALGO holder)')
  const partyB = algorand.account.random()

  // Fund Party B with ALGO for the swap + fees
  const suggestedParams = await algod.suggestedParams()
  const partyBFundingAmount = 10_000_000n // 10 ALGO (will use 5 ALGO for swap)

  const fundBTx = new Transaction({
    type: TransactionType.Payment,
    sender: partyA.addr,
    firstValid: suggestedParams.firstValid,
    lastValid: suggestedParams.lastValid,
    genesisHash: suggestedParams.genesisHash,
    genesisId: suggestedParams.genesisId,
    payment: {
      receiver: partyB.addr,
      amount: partyBFundingAmount,
    },
  })

  const fundBTxWithFee = assignFee(fundBTx, {
    feePerByte: suggestedParams.fee,
    minFee: suggestedParams.minFee,
  })

  const signedFundBTx = await partyA.signer([fundBTxWithFee], [0])
  await algod.sendRawTransaction(signedFundBTx)
  await waitForConfirmation(algod, fundBTxWithFee.txId())

  const partyBBalanceBefore = await getAccountBalance(algorand, partyB.addr.toString())
  printInfo(`Party B address: ${shortenAddress(partyB.addr.toString())}`)
  printInfo(`Party B ALGO balance: ${formatAlgo(partyBBalanceBefore.microAlgo)}`)

  // Step 4: Party A creates an asset
  printStep(4, 'Party A Creates Asset')

  const assetTotal = 1_000_000n // 1,000,000 units (no decimals for simplicity)
  const assetDecimals = 0
  const assetName = 'Swap Token'
  const assetUnitName = 'SWAP'

  const createParams = await algod.suggestedParams()

  const assetConfigFields: AssetConfigTransactionFields = {
    assetId: 0n,
    total: assetTotal,
    decimals: assetDecimals,
    defaultFrozen: false,
    assetName: assetName,
    unitName: assetUnitName,
    url: 'https://example.com/swap-token',
    manager: partyA.addr,
    reserve: partyA.addr,
    freeze: partyA.addr,
    clawback: partyA.addr,
  }

  const createAssetTx = new Transaction({
    type: TransactionType.AssetConfig,
    sender: partyA.addr,
    firstValid: createParams.firstValid,
    lastValid: createParams.lastValid,
    genesisHash: createParams.genesisHash,
    genesisId: createParams.genesisId,
    assetConfig: assetConfigFields,
  })

  const createAssetTxWithFee = assignFee(createAssetTx, {
    feePerByte: createParams.fee,
    minFee: createParams.minFee,
  })

  const signedCreateTx = await partyA.signer([createAssetTxWithFee], [0])
  await algod.sendRawTransaction(signedCreateTx)
  const createPendingInfo = (await waitForConfirmation(algod, createAssetTxWithFee.txId())) as PendingTransactionResponse

  const assetId = createPendingInfo.assetId
  if (!assetId) {
    throw new Error('Asset ID not found')
  }

  printInfo(`Created asset: ${assetName} (${assetUnitName})`)
  printInfo(`Asset ID: ${assetId}`)
  printInfo(`Party A holds: ${assetTotal} ${assetUnitName}`)

  // Step 5: Party B opts into the asset
  printStep(5, 'Party B Opts Into Asset')

  const optInParams = await algod.suggestedParams()

  const optInFields: AssetTransferTransactionFields = {
    assetId: assetId,
    receiver: partyB.addr,
    amount: 0n,
  }

  const optInTx = new Transaction({
    type: TransactionType.AssetTransfer,
    sender: partyB.addr,
    firstValid: optInParams.firstValid,
    lastValid: optInParams.lastValid,
    genesisHash: optInParams.genesisHash,
    genesisId: optInParams.genesisId,
    assetTransfer: optInFields,
  })

  const optInTxWithFee = assignFee(optInTx, {
    feePerByte: optInParams.fee,
    minFee: optInParams.minFee,
  })

  const signedOptInTx = await partyB.signer([optInTxWithFee], [0])
  await algod.sendRawTransaction(signedOptInTx)
  await waitForConfirmation(algod, optInTxWithFee.txId())

  printInfo(`Party B opted into asset ID: ${assetId}`)
  printSuccess('Opt-in successful!')

  // Step 6: Build the atomic swap transactions
  printStep(6, 'Build Atomic Swap Transactions')

  const swapAssetAmount = 100n // Party A sends 100 SWAP to Party B
  const swapAlgoAmount = 5_000_000n // Party B sends 5 ALGO to Party A

  printInfo(`Swap terms:`)
  printInfo(`  - Party A sends: ${swapAssetAmount} ${assetUnitName} -> Party B`)
  printInfo(`  - Party B sends: ${formatAlgo(swapAlgoAmount)} -> Party A`)

  const swapParams = await algod.suggestedParams()

  // Transaction 1: Party A sends ASA to Party B
  const asaSendFields: AssetTransferTransactionFields = {
    assetId: assetId,
    receiver: partyB.addr,
    amount: swapAssetAmount,
  }

  const asaSendTx = new Transaction({
    type: TransactionType.AssetTransfer,
    sender: partyA.addr,
    firstValid: swapParams.firstValid,
    lastValid: swapParams.lastValid,
    genesisHash: swapParams.genesisHash,
    genesisId: swapParams.genesisId,
    assetTransfer: asaSendFields,
  })

  const asaSendTxWithFee = assignFee(asaSendTx, {
    feePerByte: swapParams.fee,
    minFee: swapParams.minFee,
  })

  // Transaction 2: Party B sends ALGO to Party A
  const algoSendFields: PaymentTransactionFields = {
    receiver: partyA.addr,
    amount: swapAlgoAmount,
  }

  const algoSendTx = new Transaction({
    type: TransactionType.Payment,
    sender: partyB.addr,
    firstValid: swapParams.firstValid,
    lastValid: swapParams.lastValid,
    genesisHash: swapParams.genesisHash,
    genesisId: swapParams.genesisId,
    payment: algoSendFields,
  })

  const algoSendTxWithFee = assignFee(algoSendTx, {
    feePerByte: swapParams.fee,
    minFee: swapParams.minFee,
  })

  printInfo('Transaction 1: Party A sends ASA to Party B')
  printInfo('Transaction 2: Party B sends ALGO to Party A')

  // Step 7: Group the transactions using groupTransactions()
  printStep(7, 'Group Transactions with groupTransactions()')

  const groupedTransactions = groupTransactions([asaSendTxWithFee, algoSendTxWithFee])

  const groupId = groupedTransactions[0].group
  printInfo(`Group ID assigned to both transactions`)
  printInfo(`Group ID (base64): ${groupId ? Buffer.from(groupId).toString('base64') : 'undefined'}`)
  printSuccess('Transactions grouped successfully!')

  // Step 8: Each party signs ONLY their transaction
  printStep(8, 'Each Party Signs Their Own Transaction')

  printInfo('Party A signs transaction 0 (ASA transfer)')
  const signedAsaTx = await partyA.signer([groupedTransactions[0]], [0])

  printInfo('Party B signs transaction 1 (ALGO payment)')
  const signedAlgoTx = await partyB.signer([groupedTransactions[1]], [0])

  printSuccess('Both parties signed their respective transactions!')
  printInfo('Note: Party A cannot see/modify Party B\'s transaction and vice versa')
  printInfo('The atomic group ensures both execute or neither does')

  // Step 9: Combine signatures and submit
  printStep(9, 'Combine Signatures and Submit Atomic Swap')

  // Concatenate signed transactions in group order
  const combinedSignedTxns = new Uint8Array([...signedAsaTx[0], ...signedAlgoTx[0]])

  printInfo('Submitting atomic swap to network...')
  await algod.sendRawTransaction(combinedSignedTxns)

  const swapTxId = groupedTransactions[0].txId()
  const pendingInfo = await waitForConfirmation(algod, swapTxId)
  printInfo(`Atomic swap confirmed in round: ${pendingInfo.confirmedRound}`)
  printSuccess('Atomic swap executed successfully!')

  // Step 10: Verify the swap results
  printStep(10, 'Verify Swap Results')

  // Get Party A's balances after swap
  const partyABalanceAfter = await getAccountBalance(algorand, partyA.addr.toString())
  const partyAAssetInfo = await algod.accountAssetInformation(partyA.addr.toString(), assetId)
  const partyAAssetBalance = partyAAssetInfo.assetHolding?.amount ?? 0n

  // Get Party B's balances after swap
  const partyBBalanceAfter = await getAccountBalance(algorand, partyB.addr.toString())
  const partyBAssetInfo = await algod.accountAssetInformation(partyB.addr.toString(), assetId)
  const partyBAssetBalance = partyBAssetInfo.assetHolding?.amount ?? 0n

  printInfo('Party A (after swap):')
  printInfo(`  - ALGO: ${formatAlgo(partyABalanceAfter.microAlgo)}`)
  printInfo(`  - ${assetUnitName}: ${partyAAssetBalance} (sent ${swapAssetAmount}, remaining: ${assetTotal - swapAssetAmount})`)

  printInfo('Party B (after swap):')
  printInfo(`  - ALGO: ${formatAlgo(partyBBalanceAfter.microAlgo)}`)
  printInfo(`  - ${assetUnitName}: ${partyBAssetBalance} (received ${swapAssetAmount})`)

  // Verify Party A received ALGO
  // Party A's balance should have increased by swapAlgoAmount minus fees paid for various transactions
  // We check that they received roughly the ALGO from the swap
  printInfo('')
  printInfo('Verification:')

  // Verify Party B received ASA
  if (partyBAssetBalance !== swapAssetAmount) {
    throw new Error(`Party B ASA balance mismatch: expected ${swapAssetAmount}, got ${partyBAssetBalance}`)
  }
  printSuccess(`Party B received ${swapAssetAmount} ${assetUnitName}`)

  // Verify Party A's ASA balance decreased
  const expectedPartyAAsaBalance = assetTotal - swapAssetAmount
  if (partyAAssetBalance !== expectedPartyAAsaBalance) {
    throw new Error(`Party A ASA balance mismatch: expected ${expectedPartyAAsaBalance}, got ${partyAAssetBalance}`)
  }
  printSuccess(`Party A ASA balance correctly reduced to ${partyAAssetBalance} ${assetUnitName}`)

  // Verify Party B's ALGO balance decreased (sent 5 ALGO + fee)
  const partyBAlgoDecrease = partyBBalanceBefore.microAlgo - partyBBalanceAfter.microAlgo
  if (partyBAlgoDecrease < swapAlgoAmount) {
    throw new Error(`Party B should have sent at least ${swapAlgoAmount} microALGO`)
  }
  printSuccess(`Party B sent ${formatAlgo(swapAlgoAmount)} (plus ${formatAlgo(partyBAlgoDecrease - swapAlgoAmount)} in fees)`)

  printInfo('')
  printInfo('Atomic Swap Summary:')
  printInfo(`  - Party A gave: ${swapAssetAmount} ${assetUnitName}`)
  printInfo(`  - Party A received: ${formatAlgo(swapAlgoAmount)}`)
  printInfo(`  - Party B gave: ${formatAlgo(swapAlgoAmount)}`)
  printInfo(`  - Party B received: ${swapAssetAmount} ${assetUnitName}`)

  printSuccess('Atomic swap example completed successfully!')
}

main().catch((error) => {
  console.error('Error:', error)
  process.exit(1)
})

---

Other examples in Transactions

• Payment Transaction
• Payment with Close
• Asset Create
• Asset Transfer
• Asset Freeze
• Asset Clawback
• Atomic Transaction Group
• Atomic Swap
• Single Signature
• Multisig
• Logic Signature
• Fee Calculation
• Encoding/Decoding
• Application Call