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

Multisig Account Setup

← Back to KMD Client

Description

Section titled “Description”

This example demonstrates how to create multisig accounts using the KMD importMultisig() method. Key concepts:

  • A multisig account requires M-of-N signatures to authorize transactions
  • The threshold (M) is the minimum number of signatures required
  • The public keys (N) are the participants who can sign
  • The multisig version parameter (currently always 1) defines the format
  • The resulting multisig address is deterministically derived from the public keys, threshold, and version

Prerequisites

Section titled “Prerequisites”
  • LocalNet running (via algokit localnet start)
  • Covered operations:
  • generateKey() - Generate keys to use as multisig participants
  • importMultisig() - Create a multisig account from public keys

Run This Example

Section titled “Run This Example”

From the repository root:

Terminal window
cd examples
npm run example kmd_client/08-multisig-setup.ts

Code

Section titled “Code”

View source on GitHub

08-multisig-setup.ts
/**
 * Example: Multisig Account Setup
 *
 * This example demonstrates how to create multisig accounts using the KMD
 * `importMultisig()` method.
 *
 * Key concepts:
 * - A multisig account requires M-of-N signatures to authorize transactions
 * - The threshold (M) is the minimum number of signatures required
 * - The public keys (N) are the participants who can sign
 * - The multisig version parameter (currently always 1) defines the format
 * - The resulting multisig address is deterministically derived from the
 *   public keys, threshold, and version
 *
 * Prerequisites:
 * - LocalNet running (via `algokit localnet start`)
 *
 * Covered operations:
 * - generateKey() - Generate keys to use as multisig participants
 * - importMultisig() - Create a multisig account from public keys
 */


import { decodeAddress } from '@algorandfoundation/algokit-utils'
import {
  cleanupTestWallet,
  createKmdClient,
  createTestWallet,
  printError,
  printHeader,
  printInfo,
  printStep,
  printSuccess,
} from '../shared/utils.js'


/**
 * Format a byte array for display, showing first and last few bytes
 */
function formatBytesForDisplay(bytes: Uint8Array, showFirst = 4, showLast = 4): string {
  const hex = Buffer.from(bytes).toString('hex')
  if (bytes.length <= showFirst + showLast) {
    return hex
  }
  const firstBytes = hex.slice(0, showFirst * 2)
  const lastBytes = hex.slice(-(showLast * 2))
  return `${firstBytes}...${lastBytes}`
}


async function main() {
  printHeader('KMD Multisig Account Setup Example')


  const kmd = createKmdClient()
  let walletHandleToken = ''
  const walletPassword = 'test-password'


  try {
    // =========================================================================
    // Step 1: Create a Test Wallet
    // =========================================================================
    printStep(1, 'Creating a test wallet')


    const testWallet = await createTestWallet(kmd, walletPassword)
    walletHandleToken = testWallet.walletHandleToken


    printSuccess(`Test wallet created: ${testWallet.walletName}`)
    printInfo(`Wallet ID: ${testWallet.walletId}`)


    // =========================================================================
    // Step 2: Generate 3 Keys for Multisig Participants
    // =========================================================================
    printStep(2, 'Generating 3 keys to use as multisig participants')


    const participantAddresses: string[] = []
    const numParticipants = 3


    for (let i = 1; i <= numParticipants; i++) {
      const result = await kmd.generateKey({ walletHandleToken })
      participantAddresses.push(result.address.toString())
      printInfo(`Participant ${i}: ${result.address}`)
    }


    printSuccess(`Generated ${numParticipants} participant keys`)
    printInfo('')
    printInfo('These addresses will be used to create a 2-of-3 multisig account.')


    // =========================================================================
    // Step 3: Convert Addresses to Public Keys
    // =========================================================================
    printStep(3, 'Converting addresses to public keys')


    const publicKeys: Uint8Array[] = participantAddresses.map((addr) => {
      const decoded = decodeAddress(addr)
      return decoded.publicKey
    })


    printInfo('Public keys extracted from addresses:')
    publicKeys.forEach((pk, i) => {
      printInfo(`  Participant ${i + 1}: ${formatBytesForDisplay(pk)} (${pk.length} bytes)`)
    })


    printInfo('')
    printInfo('Note: Each Algorand address encodes a 32-byte public key.')
    printInfo('The address also includes a 4-byte checksum for error detection.')


    // =========================================================================
    // Step 4: Create the Multisig Account with importMultisig()
    // =========================================================================
    printStep(4, 'Creating a 2-of-3 multisig account with importMultisig()')


    const threshold = 2 // Minimum signatures required
    const multisigVersion = 1 // Multisig format version


    const multisigResult = await kmd.importMultisig({
      walletHandleToken,
      publicKeys,
      threshold,
      multisigVersion,
    })


    const multisigAddress = multisigResult.address.toString()


    printSuccess('Multisig account created successfully!')
    printInfo('')
    printInfo('ImportMultisigResponse fields:')
    printInfo(`  address: ${multisigAddress}`)
    printInfo('')
    printInfo('Parameters used:')
    printInfo(`  publicKeys:       ${numParticipants} participant keys`)
    printInfo(`  threshold:        ${threshold} (minimum signatures required)`)
    printInfo(`  multisigVersion:  ${multisigVersion}`)


    // =========================================================================
    // Step 5: Explain the Threshold Parameter
    // =========================================================================
    printStep(5, 'Understanding the threshold parameter')


    printInfo('')
    printInfo('What is the threshold?')
    printInfo('-'.repeat(40))
    printInfo('')
    printInfo(`The threshold (${threshold}) is the minimum number of signatures required`)
    printInfo('to authorize any transaction from this multisig account.')
    printInfo('')
    printInfo(`With a ${threshold}-of-${numParticipants} configuration:`)
    printInfo(`  - ${numParticipants} participants can potentially sign`)
    printInfo(`  - At least ${threshold} signatures are required`)
    printInfo(`  - Any ${threshold} of the ${numParticipants} participants can authorize a transaction`)
    printInfo('')
    printInfo('Common use cases:')
    printInfo('  - 2-of-3: Standard security (recover if one key is lost)')
    printInfo('  - 2-of-2: Joint control (both parties must agree)')
    printInfo('  - 3-of-5: Committee/board decisions')
    printInfo('  - 1-of-N: Any participant can act alone (hot wallet backup)')


    // =========================================================================
    // Step 6: Explain the Multisig Version Parameter
    // =========================================================================
    printStep(6, 'Understanding the multisig version parameter')


    printInfo('')
    printInfo('What is the multisig version?')
    printInfo('-'.repeat(40))
    printInfo('')
    printInfo(`The multisig version (${multisigVersion}) specifies the format of the multisig account.`)
    printInfo('')
    printInfo('Currently, version 1 is the only supported version on Algorand.')
    printInfo('This parameter exists for future compatibility if the multisig')
    printInfo('format is ever updated.')
    printInfo('')
    printInfo('Always use version 1 unless Algorand documentation specifies otherwise.')


    // =========================================================================
    // Step 7: Show Relationship Between Keys and Address
    // =========================================================================
    printStep(7, 'Relationship between public keys and multisig address')


    printInfo('')
    printInfo('How is the multisig address derived?')
    printInfo('-'.repeat(40))
    printInfo('')
    printInfo('The multisig address is deterministically computed from:')
    printInfo('  1. The multisig version')
    printInfo('  2. The threshold value')
    printInfo('  3. The ordered list of public keys')
    printInfo('')
    printInfo('Important properties:')
    printInfo('  - Same inputs always produce the same multisig address')
    printInfo('  - Changing the order of public keys changes the address')
    printInfo('  - Changing the threshold changes the address')
    printInfo('  - The address encodes the complete multisig configuration')
    printInfo('')
    printInfo('Multisig address structure:')
    printInfo(`  ${multisigAddress}`)
    printInfo('')
    printInfo('Participant addresses (order matters!):')
    participantAddresses.forEach((addr, i) => {
      printInfo(`  ${i + 1}. ${addr}`)
    })


    // =========================================================================
    // Step 8: Verify Multisig is Listed
    // =========================================================================
    printStep(8, 'Verifying the multisig account is in the wallet')


    const listResult = await kmd.listMultisig({ walletHandleToken })


    printSuccess(`Wallet contains ${listResult.addresses.length} multisig address(es)`)
    printInfo('')
    printInfo('Multisig addresses in wallet:')
    listResult.addresses.forEach((addr, i) => {
      const marker = addr.toString() === multisigAddress ? ' (our new multisig)' : ''
      printInfo(`  ${i + 1}. ${addr}${marker}`)
    })


    // =========================================================================
    // Step 9: Summary of Multisig Operations
    // =========================================================================
    printStep(9, 'What you can do with the multisig account')


    printInfo('')
    printInfo('Now that the multisig is imported, you can:')
    printInfo('')
    printInfo('  1. RECEIVE FUNDS: Send Algo or ASAs to the multisig address')
    printInfo(`     Address: ${multisigAddress}`)
    printInfo('')
    printInfo('  2. SIGN TRANSACTIONS: Use signMultisigTransaction() to add')
    printInfo('     signatures from participants whose keys are in this wallet')
    printInfo('')
    printInfo('  3. EXPORT CONFIGURATION: Use exportMultisig() to get the')
    printInfo('     full multisig parameters (keys, threshold, version)')
    printInfo('')
    printInfo('  4. DELETE: Use deleteMultisig() to remove from the wallet')
    printInfo('     (does not affect the blockchain account or funds)')
    printInfo('')
    printInfo('Note: To fully authorize a transaction, collect signatures from')
    printInfo(`at least ${threshold} participants, then combine and submit.`)


    // =========================================================================
    // Cleanup
    // =========================================================================
    printStep(10, 'Cleaning up test wallet')


    await cleanupTestWallet(kmd, walletHandleToken)
    walletHandleToken = '' // Mark as cleaned up


    printSuccess('Test wallet handle released')


    // =========================================================================
    // Summary
    // =========================================================================
    printHeader('Summary')
    printInfo('This example demonstrated multisig account setup in KMD:')
    printInfo('')
    printInfo('  importMultisig()')
    printInfo('    Parameters:')
    printInfo('      - walletHandleToken: Session token for the wallet')
    printInfo('      - publicKeys:        Array of Uint8Array participant keys')
    printInfo('      - threshold:         Minimum signatures required (M in M-of-N)')
    printInfo('      - multisigVersion:   Format version (always 1)')
    printInfo('    Returns:')
    printInfo('      - address:           The generated multisig Address')
    printInfo('')
    printInfo('Key takeaways:')
    printInfo('  - Multisig requires M-of-N signatures to authorize transactions')
    printInfo('  - The address is derived from version + threshold + ordered keys')
    printInfo('  - Same configuration always produces the same address')
    printInfo('  - Public keys are extracted from addresses using decodeAddress()')
    printInfo('  - multisigVersion should always be 1 (current Algorand standard)')
    printInfo('')
    printInfo('Note: The test wallet remains in KMD (wallets cannot be deleted via API).')
  } catch (error) {
    printError(`Error: ${error instanceof Error ? error.message : String(error)}`)
    printInfo('')
    printInfo('Troubleshooting:')
    printInfo('  - Ensure LocalNet is running: algokit localnet start')
    printInfo('  - If LocalNet issues occur: algokit localnet reset')
    printInfo('  - Check that KMD is accessible on port 4002')


    // Cleanup on error
    if (walletHandleToken) {
      await cleanupTestWallet(kmd, walletHandleToken)
    }


    process.exit(1)
  }
}


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

Other examples in KMD Client

Section titled “Other examples in KMD Client”