Single Signature

Description

This example demonstrates how to create an ed25519 keypair and sign transactions using the low-level transact package APIs. Key concepts:

Creating a keypair using tweetnacl (ed25519 signature scheme)
Using generateAddressWithSigners() to derive an Algorand address from the public key
Understanding the relationship between ed25519 public key and Algorand address
Signing transactions with a raw ed25519 signer function

Prerequisites

LocalNet running (via algokit localnet start)

Run This Example

From the repository root:

cd examples
npm run example transact/09-single-sig.ts

Code

View source on GitHub

/**
 * Example: Single Signature
 *
 * This example demonstrates how to create an ed25519 keypair and sign transactions
 * using the low-level transact package APIs.
 *
 * Key concepts:
 * - Creating a keypair using tweetnacl (ed25519 signature scheme)
 * - Using generateAddressWithSigners() to derive an Algorand address from the public key
 * - Understanding the relationship between ed25519 public key and Algorand address
 * - Signing transactions with a raw ed25519 signer function
 *
 * Prerequisites:
 * - LocalNet running (via `algokit localnet start`)
 */

import { AlgorandClient } from '@algorandfoundation/algokit-utils'
import {
  Transaction,
  TransactionType,
  assignFee,
  generateAddressWithSigners,
  type PaymentTransactionFields,
} from '@algorandfoundation/algokit-utils/transact'
import nacl from 'tweetnacl'
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('Single Signature Example')

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

  // Step 2: Create a keypair using tweetnacl
  printStep(2, 'Create Keypair Using tweetnacl')

  // The keypair generation uses a cryptographically secure random number generator
  const keypair = nacl.sign.keyPair()

  printInfo(`Public key (32 bytes): ${Buffer.from(keypair.publicKey).toString('hex').slice(0, 32)}...`)
  printInfo(`Secret key (64 bytes): ${Buffer.from(keypair.secretKey).toString('hex').slice(0, 32)}... (truncated for security)`)
  printInfo('')
  printInfo('Note: The secret key in ed25519 is 64 bytes because it contains')
  printInfo('      both the 32-byte private seed AND the 32-byte public key.')

  // Step 3: Derive Algorand address using generateAddressWithSigners
  printStep(3, 'Derive Algorand Address with generateAddressWithSigners()')

  // generateAddressWithSigners() does the following internally:
  // 1. Takes the 32-byte ed25519 public key
  // 2. Computes a 4-byte checksum using SHA-512/256
  // 3. Concatenates: public_key (32 bytes) + checksum (4 bytes) = 36 bytes
  // 4. Base32 encodes the 36 bytes to get the 58-character Algorand address
  const account = generateAddressWithSigners({
    ed25519Pubkey: keypair.publicKey,
    rawEd25519Signer: async (bytesToSign: Uint8Array) => {
      return nacl.sign.detached(bytesToSign, keypair.secretKey)
    },
  })

  printInfo(`Ed25519 public key (hex): ${Buffer.from(keypair.publicKey).toString('hex')}`)
  printInfo(`Algorand address (base32): ${account.addr.toString()}`)
  printInfo('')
  printInfo('The Algorand address is derived from the public key by:')
  printInfo('  1. Computing SHA-512/256 checksum of the public key')
  printInfo('  2. Appending last 4 bytes of checksum to public key')
  printInfo('  3. Base32 encoding the result (36 bytes -> 58 characters)')

  // Step 4: Fund the account from dispenser
  printStep(4, 'Fund Account from Dispenser')
  const dispenser = await getLocalNetFundedAccount(algorand)
  const fundingAmount = 2_000_000n // 2 ALGO

  const suggestedParams = await algod.suggestedParams()

  const fundTx = new Transaction({
    type: TransactionType.Payment,
    sender: dispenser.addr,
    firstValid: suggestedParams.firstValid,
    lastValid: suggestedParams.lastValid,
    genesisHash: suggestedParams.genesisHash,
    genesisId: suggestedParams.genesisId,
    payment: {
      receiver: account.addr,
      amount: fundingAmount,
    },
  })

  const fundTxWithFee = assignFee(fundTx, {
    feePerByte: suggestedParams.fee,
    minFee: suggestedParams.minFee,
  })

  const signedFundTx = await dispenser.signer([fundTxWithFee], [0])
  await algod.sendRawTransaction(signedFundTx)
  await waitForConfirmation(algod, fundTxWithFee.txId())

  const balance = await getAccountBalance(algorand, account.addr.toString())
  printInfo(`Funded account with ${formatAlgo(fundingAmount)}`)
  printInfo(`Account balance: ${formatAlgo(balance.microAlgo)}`)

  // Step 5: Create a payment transaction to demonstrate signing
  printStep(5, 'Create Payment Transaction')

  const paymentAmount = 100_000n // 0.1 ALGO
  // Use AlgorandClient helper for the receiver (this example focuses on sender signing)
  const receiver = algorand.account.random()

  const payParams = await algod.suggestedParams()

  const paymentFields: PaymentTransactionFields = {
    receiver: receiver.addr,
    amount: paymentAmount,
  }

  const paymentTx = new Transaction({
    type: TransactionType.Payment,
    sender: account.addr,
    firstValid: payParams.firstValid,
    lastValid: payParams.lastValid,
    genesisHash: payParams.genesisHash,
    genesisId: payParams.genesisId,
    payment: paymentFields,
  })

  const paymentTxWithFee = assignFee(paymentTx, {
    feePerByte: payParams.fee,
    minFee: payParams.minFee,
  })

  printInfo(`Payment amount: ${formatAlgo(paymentAmount)}`)
  printInfo(`Sender: ${shortenAddress(account.addr.toString())}`)
  printInfo(`Receiver: ${shortenAddress(receiver.addr.toString())}`)
  printInfo(`Transaction ID: ${paymentTxWithFee.txId()}`)

  // Step 6: Sign the transaction (explaining the process)
  printStep(6, 'Sign Transaction with ed25519 Signature')

  printInfo('Signing process:')
  printInfo('  1. Transaction is encoded to msgpack bytes')
  printInfo('  2. Bytes are prefixed with "TX" (to prevent cross-protocol attacks)')
  printInfo('  3. The prefixed bytes are signed using ed25519 with the secret key')
  printInfo('  4. Signature (64 bytes) is attached to create a SignedTransaction')
  printInfo('')

  // The signer function handles all of this internally
  // account.signer([transaction], [indices]) signs the specified transactions
  const signedTxns = await account.signer([paymentTxWithFee], [0])

  printInfo(`Signed transaction size: ${signedTxns[0].length} bytes`)
  printInfo('Transaction signed successfully!')

  // Step 7: Submit and verify
  printStep(7, 'Submit Transaction')
  await algod.sendRawTransaction(signedTxns)
  printInfo('Transaction submitted to network')

  const pendingInfo = await waitForConfirmation(algod, paymentTxWithFee.txId())
  printInfo(`Transaction confirmed in round: ${pendingInfo.confirmedRound}`)

  // Step 8: Verify balances
  printStep(8, 'Verify Balances')

  const senderBalanceAfter = await getAccountBalance(algorand, account.addr.toString())
  let receiverBalanceAfter: bigint
  try {
    const info = await getAccountBalance(algorand, receiver.addr.toString())
    receiverBalanceAfter = info.microAlgo
  } catch {
    receiverBalanceAfter = 0n
  }

  printInfo(`Sender balance after: ${formatAlgo(senderBalanceAfter.microAlgo)}`)
  printInfo(`Receiver balance after: ${formatAlgo(receiverBalanceAfter)}`)

  const expectedSenderBalance = fundingAmount - paymentAmount - (paymentTxWithFee.fee ?? 0n)
  if (senderBalanceAfter.microAlgo === expectedSenderBalance) {
    printSuccess('Sender balance verified!')
  }

  if (receiverBalanceAfter === paymentAmount) {
    printSuccess('Receiver received the payment!')
  }

  // Summary
  printInfo('')
  printInfo('Summary - Single Signature Key Points:')
  printInfo('  - ed25519 is the signature algorithm used by Algorand')
  printInfo('  - Public key (32 bytes) -> Algorand address (58 chars base32)')
  printInfo('  - generateAddressWithSigners() bridges raw crypto to Algorand')
  printInfo('  - The signer function signs transaction bytes with ed25519')
  printInfo('  - Each transaction requires a valid signature from the sender')

  printSuccess('Single signature example completed!')
}

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

Single Signature

Description

Prerequisites

Run This Example

Code

Other examples in Transactions