Skip to content
light theme Algorand Developer Portal dark theme Algorand Developer Portal Algorand Developer Portal

Signer Configuration

← Back to Algorand Client

Description

Section titled “Description”

This example demonstrates how to configure transaction signers on AlgorandClient:

  • setDefaultSigner() to set a fallback signer for all transactions
  • setSignerFromAccount() to register a signer from an Account object
  • setSigner() to register a signer for a specific address
  • How signers are automatically used when sending transactions
  • Registering multiple signers for different accounts
  • How the default signer is used when no specific signer is registered
  • getSigner() and getAccount() to retrieve previously registered signers

Prerequisites

Section titled “Prerequisites”
  • LocalNet running (via algokit localnet start)

Run This Example

Section titled “Run This Example”

From the repository root:

Terminal window
cd examples
npm run example algorand_client/03-signer-config.ts

Code

Section titled “Code”

View source on GitHub

03-signer-config.ts
/**
 * Example: Signer Configuration
 *
 * This example demonstrates how to configure transaction signers on AlgorandClient:
 * - setDefaultSigner() to set a fallback signer for all transactions
 * - setSignerFromAccount() to register a signer from an Account object
 * - setSigner() to register a signer for a specific address
 * - How signers are automatically used when sending transactions
 * - Registering multiple signers for different accounts
 * - How the default signer is used when no specific signer is registered
 * - getSigner() and getAccount() to retrieve previously registered signers
 *
 * Prerequisites:
 * - LocalNet running (via `algokit localnet start`)
 */


import { AlgorandClient, algo } from '@algorandfoundation/algokit-utils'
import { printError, printHeader, printInfo, printStep, printSuccess, shortenAddress } from '../shared/utils.js'


async function main() {
  printHeader('Signer Configuration Example')


  // Initialize client and verify LocalNet is running
  const algorand = AlgorandClient.defaultLocalNet()


  try {
    await algorand.client.algod.status()
    printSuccess('Connected to LocalNet')
  } catch (error) {
    printError(`Failed to connect to LocalNet: ${error instanceof Error ? error.message : String(error)}`)
    printInfo('Make sure LocalNet is running (e.g., algokit localnet start)')
    return
  }


  // Step 1: Create random test accounts
  printStep(1, 'Create random test accounts using algorand.account.random()')
  printInfo('algorand.account.random() creates a new account with a randomly generated keypair')
  printInfo('The account is automatically registered with its signer in the AccountManager')


  const account1 = algorand.account.random()
  const account2 = algorand.account.random()
  const account3 = algorand.account.random()


  printInfo(`\nCreated accounts:`)
  printInfo(`  Account 1: ${shortenAddress(account1.addr.toString())}`)
  printInfo(`  Account 2: ${shortenAddress(account2.addr.toString())}`)
  printInfo(`  Account 3: ${shortenAddress(account3.addr.toString())}`)


  printSuccess('Created 3 random test accounts')


  // Step 2: Fund the accounts from the dispenser
  printStep(2, 'Fund accounts from the LocalNet dispenser')
  printInfo('Using the dispenser account to fund our test accounts')


  const dispenser = await algorand.account.dispenserFromEnvironment()
  printInfo(`Dispenser address: ${shortenAddress(dispenser.addr.toString())}`)


  // Fund all three accounts
  const fundAmount = algo(10)
  printInfo(`\nFunding each account with ${fundAmount.algo} ALGO...`)


  for (const account of [account1, account2, account3]) {
    await algorand.send.payment({
      sender: dispenser.addr,
      receiver: account.addr,
      amount: fundAmount,
    })
  }


  printSuccess('Funded all accounts with 10 ALGO each')


  // Step 3: Demonstrate setSignerFromAccount()
  printStep(3, 'Demonstrate setSignerFromAccount() - Register signer from an account object')
  printInfo('setSignerFromAccount() registers the signer from an account that can sign transactions')
  printInfo('This is useful when you have an account object and want to register it for signing')


  // Create a new AlgorandClient to demonstrate registering signers explicitly
  const algorand2 = AlgorandClient.defaultLocalNet()


  // Register account1's signer
  printInfo(`\nRegistering signer for Account 1: ${shortenAddress(account1.addr.toString())}`)
  algorand2.setSignerFromAccount(account1)


  printInfo('Now Account 1 can be used as a sender in transactions')


  // Send a payment from account1 to account2
  const payment1Result = await algorand2.send.payment({
    sender: account1.addr,
    receiver: account2.addr,
    amount: algo(1),
  })


  printInfo(`\nPayment transaction sent:`)
  printInfo(`  From: ${shortenAddress(account1.addr.toString())}`)
  printInfo(`  To: ${shortenAddress(account2.addr.toString())}`)
  printInfo(`  Amount: 1 ALGO`)
  printInfo(`  Transaction ID: ${payment1Result.txIds[0]}`)
  printInfo(`  Confirmed in round: ${payment1Result.confirmation.confirmedRound}`)


  printSuccess('Successfully sent payment using registered signer')


  // Step 4: Demonstrate setSigner() - Register signer for a specific address
  printStep(4, 'Demonstrate setSigner() - Register signer for a specific address')
  printInfo('setSigner(address, signer) registers a TransactionSigner for a specific address')
  printInfo('This gives you fine-grained control over which signer to use for each address')


  // Create another AlgorandClient to demonstrate setSigner
  const algorand3 = AlgorandClient.defaultLocalNet()


  // Register account2's signer using setSigner
  printInfo(`\nRegistering signer for Account 2 using setSigner():`)
  printInfo(`  Address: ${shortenAddress(account2.addr.toString())}`)
  algorand3.setSigner(account2.addr, account2.signer)


  // Send a payment from account2 to account3
  const payment2Result = await algorand3.send.payment({
    sender: account2.addr,
    receiver: account3.addr,
    amount: algo(0.5),
  })


  printInfo(`\nPayment transaction sent:`)
  printInfo(`  From: ${shortenAddress(account2.addr.toString())}`)
  printInfo(`  To: ${shortenAddress(account3.addr.toString())}`)
  printInfo(`  Amount: 0.5 ALGO`)
  printInfo(`  Transaction ID: ${payment2Result.txIds[0]}`)
  printInfo(`  Confirmed in round: ${payment2Result.confirmation.confirmedRound}`)


  printSuccess('Successfully sent payment using setSigner()')


  // Step 5: Demonstrate setDefaultSigner()
  printStep(5, 'Demonstrate setDefaultSigner() - Set a fallback signer for all transactions')
  printInfo('setDefaultSigner() sets a signer that will be used when no specific signer is registered')
  printInfo('This is useful when you have a primary account that signs most transactions')


  // Create a new AlgorandClient and set account3 as the default signer
  const algorand4 = AlgorandClient.defaultLocalNet()


  printInfo(`\nSetting Account 3 as the default signer: ${shortenAddress(account3.addr.toString())}`)
  algorand4.setDefaultSigner(account3)


  // Now we can send a transaction from account3 without explicitly registering it
  // The default signer will be used
  const payment3Result = await algorand4.send.payment({
    sender: account3.addr,
    receiver: account1.addr,
    amount: algo(0.25),
  })


  printInfo(`\nPayment transaction sent using default signer:`)
  printInfo(`  From: ${shortenAddress(account3.addr.toString())}`)
  printInfo(`  To: ${shortenAddress(account1.addr.toString())}`)
  printInfo(`  Amount: 0.25 ALGO`)
  printInfo(`  Transaction ID: ${payment3Result.txIds[0]}`)
  printInfo(`  Confirmed in round: ${payment3Result.confirmation.confirmedRound}`)


  printSuccess('Successfully sent payment using default signer')


  // Step 6: Demonstrate multiple signers with default fallback
  printStep(6, 'Demonstrate multiple signers with default fallback')
  printInfo('You can register multiple signers and have a default as fallback')
  printInfo('Specific signers take precedence over the default signer')


  // Create a new AlgorandClient with multiple signers
  const algorand5 = AlgorandClient.defaultLocalNet()


  // Set account1 as the default signer
  printInfo(`\nSetting up signers:`)
  printInfo(`  Default signer: Account 1 (${shortenAddress(account1.addr.toString())})`)
  algorand5.setDefaultSigner(account1)


  // Also register account2's signer explicitly
  printInfo(`  Registered signer: Account 2 (${shortenAddress(account2.addr.toString())})`)
  algorand5.setSignerFromAccount(account2)


  // Send from account2 (uses registered signer)
  printInfo(`\nSending from Account 2 (uses registered signer):`)
  const payment4Result = await algorand5.send.payment({
    sender: account2.addr,
    receiver: account3.addr,
    amount: algo(0.1),
  })
  printInfo(`  Transaction ID: ${payment4Result.txIds[0]}`)
  printInfo(`  Confirmed in round: ${payment4Result.confirmation.confirmedRound}`)


  // Send from account1 (uses default signer)
  printInfo(`\nSending from Account 1 (uses default signer):`)
  const payment5Result = await algorand5.send.payment({
    sender: account1.addr,
    receiver: account3.addr,
    amount: algo(0.1),
  })
  printInfo(`  Transaction ID: ${payment5Result.txIds[0]}`)
  printInfo(`  Confirmed in round: ${payment5Result.confirmation.confirmedRound}`)


  printSuccess('Successfully demonstrated signer priority (specific > default)')


  // Step 7: Error handling - No signer registered
  printStep(7, 'Error handling - Attempting to send without a registered signer')
  printInfo('When no signer is registered for an address and no default signer is set,')
  printInfo('an error will be thrown when trying to send a transaction')


  // Create a new AlgorandClient without any signers
  const algorand6 = AlgorandClient.defaultLocalNet()
  const unregisteredAccount = algorand6.account.random()


  printInfo(`\nAttempting to send from unregistered account: ${shortenAddress(unregisteredAccount.addr.toString())}`)
  printInfo('(Note: algorand.account.random() automatically registers the signer,')
  printInfo(' but if we create a fresh client and only have the address, it will fail)')


  // Create yet another client that doesn't have the signer registered
  const algorand7 = AlgorandClient.defaultLocalNet()


  try {
    // Try to send from the address without registering a signer
    await algorand7.send.payment({
      sender: unregisteredAccount.addr, // This address has no signer in algorand7
      receiver: account1.addr,
      amount: algo(0.01),
    })
    printInfo('Unexpectedly succeeded')
  } catch (error) {
    printSuccess('Caught expected error when no signer is registered')
    printInfo(`Error message: ${error instanceof Error ? error.message : String(error)}`)
  }


  // Step 8: Method chaining
  printStep(8, 'Method chaining - Configure signers fluently')
  printInfo('All signer methods return the AlgorandClient, allowing method chaining')


  const algorand8 = AlgorandClient.defaultLocalNet()
    .setDefaultSigner(account1)
    .setSignerFromAccount(account2)
    .setSigner(account3.addr, account3.signer)


  printInfo(`\nConfigured AlgorandClient with chained calls:`)
  printInfo(`  .setDefaultSigner(account1)`)
  printInfo(`  .setSignerFromAccount(account2)`)
  printInfo(`  .setSigner(account3.addr, account3.signer)`)


  // Verify all signers work
  const balances: Record<string, bigint> = {}
  for (const [name, account] of [
    ['Account 1', account1],
    ['Account 2', account2],
    ['Account 3', account3],
  ] as const) {
    const info = await algorand8.account.getInformation(account.addr)
    balances[name] = info.balance.microAlgo
  }


  printInfo(`\nCurrent balances:`)
  for (const [name, balance] of Object.entries(balances)) {
    printInfo(`  ${name}: ${(Number(balance) / 1_000_000).toFixed(6)} ALGO`)
  }


  printSuccess('Successfully configured AlgorandClient with method chaining')


  // Step 9: Retrieve signers and accounts with getSigner() and getAccount()
  printStep(9, 'Retrieve signers and accounts with getSigner() and getAccount()')
  printInfo('algorand.account.getSigner(address) retrieves the TransactionSigner registered for an address')
  printInfo('algorand.account.getAccount(address) retrieves the full AddressWithSigner for an address')


  // Retrieve the signer for account1 (registered via method chaining in step 8)
  const retrievedSigner = algorand8.account.getSigner(account1.addr)
  printInfo(`\nRetrieved signer for Account 1: ${shortenAddress(account1.addr.toString())}`)
  printSuccess('getSigner() returned a TransactionSigner')


  // Retrieve the full AddressWithSigner for account2
  const retrievedAccount = algorand8.account.getAccount(account2.addr)
  printInfo(`\nRetrieved account for Account 2: ${shortenAddress(retrievedAccount.addr.toString())}`)
  printSuccess('getAccount() returned AddressWithSigner (addr + signer)')


  // Use the retrieved signer in a transaction via addTransaction
  const txnWithRetrievedSigner = await algorand8.send.payment({
    sender: account1.addr,
    receiver: account2.addr,
    amount: algo(0.05),
    signer: retrievedSigner,
  })
  printInfo(`\nPayment sent using retrieved signer:`)
  printInfo(`  Transaction ID: ${txnWithRetrievedSigner.txIds[0]}`)
  printInfo(`  Confirmed in round: ${txnWithRetrievedSigner.confirmation.confirmedRound}`)


  printSuccess('Successfully retrieved and used signers via getSigner() and getAccount()')


  // Step 10: Summary
  printStep(10, 'Summary')
  printInfo('Signer configuration methods:')
  printInfo('')
  printInfo('setDefaultSigner(signer):')
  printInfo('  - Sets a fallback signer for all transactions')
  printInfo('  - Used when no specific signer is registered for an address')
  printInfo('  - Accepts TransactionSigner or AddressWithTransactionSigner')
  printInfo('')
  printInfo('setSignerFromAccount(account):')
  printInfo('  - Registers a signer from an account object')
  printInfo('  - Account must have addr and signer properties')
  printInfo('  - Supports Account, LogicSigAccount, MultisigAccount, etc.')
  printInfo('')
  printInfo('setSigner(address, signer):')
  printInfo('  - Registers a TransactionSigner for a specific address')
  printInfo('  - Gives fine-grained control over signing')
  printInfo('')
  printInfo('getSigner(address):')
  printInfo('  - Retrieves the TransactionSigner registered for an address')
  printInfo('  - Falls back to default signer if no specific signer registered')
  printInfo('')
  printInfo('getAccount(address):')
  printInfo('  - Retrieves the AddressWithSigner for an address')
  printInfo('  - Returns both the address and its registered signer')
  printInfo('')
  printInfo('Signer resolution order:')
  printInfo('  1. Specific signer registered for the address')
  printInfo('  2. Default signer (if set)')
  printInfo('  3. Error thrown if no signer found')
  printInfo('')
  printInfo('Best practices:')
  printInfo('  - Use algorand.account.random() for test accounts (auto-registers signer)')
  printInfo('  - Set a default signer for your primary signing account')
  printInfo('  - Register additional signers as needed for multi-account workflows')
  printInfo('  - Method chaining makes configuration concise and readable')


  printSuccess('Signer Configuration example completed!')
}


main().catch((error) => {
  printError(`Unhandled error: ${error instanceof Error ? error.message : String(error)}`)
  process.exit(1)
})

Other examples in Algorand Client

Section titled “Other examples in Algorand Client”