Multisig Account Management

Description

This example demonstrates how to manage multisig accounts using KMD:

listMultisig() - List all multisig accounts in a wallet
exportMultisig() - Get the multisig preimage information
deleteMultisig() - Remove a multisig account from the wallet Key concepts:
Multisig accounts can be listed to see all multisigs in a wallet
The multisig preimage contains the original parameters: publicKeys, threshold, version
Deleting a multisig only removes it from the wallet, not from the blockchain
Funds in a deleted multisig address remain on the blockchain

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
listMultisig() - List all multisig accounts in the wallet
exportMultisig() - Export the multisig preimage (configuration)
deleteMultisig() - Delete a multisig account from the wallet

Run This Example

From the repository root:

cd examples
npm run example kmd_client/09-multisig-management.ts

Code

View source on GitHub

/**
 * Example: Multisig Account Management
 *
 * This example demonstrates how to manage multisig accounts using KMD:
 * - listMultisig() - List all multisig accounts in a wallet
 * - exportMultisig() - Get the multisig preimage information
 * - deleteMultisig() - Remove a multisig account from the wallet
 *
 * Key concepts:
 * - Multisig accounts can be listed to see all multisigs in a wallet
 * - The multisig preimage contains the original parameters: publicKeys, threshold, version
 * - Deleting a multisig only removes it from the wallet, not from the blockchain
 * - Funds in a deleted multisig address remain on the blockchain
 *
 * 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
 * - listMultisig() - List all multisig accounts in the wallet
 * - exportMultisig() - Export the multisig preimage (configuration)
 * - deleteMultisig() - Delete a multisig account from the wallet
 */

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 Management 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`)

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

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

    const threshold = 2
    const multisigVersion = 1

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

    const multisigAddress = multisigResult.address.toString()

    printSuccess('Multisig account created!')
    printInfo(`Multisig address: ${multisigAddress}`)
    printInfo(`Configuration: ${threshold}-of-${numParticipants}`)

    // =========================================================================
    // Step 4: List All Multisig Accounts with listMultisig()
    // =========================================================================
    printStep(4, 'Listing all multisig accounts with listMultisig()')

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

    printSuccess(`Found ${listResult.addresses.length} multisig address(es) in wallet`)
    printInfo('')
    printInfo('ListMultisigResponse fields:')
    printInfo(`  addresses: Array of ${listResult.addresses.length} Address(es)`)
    printInfo('')
    printInfo('Multisig addresses in wallet:')
    listResult.addresses.forEach((addr, i) => {
      printInfo(`  ${i + 1}. ${addr}`)
    })

    printInfo('')
    printInfo('Note: listMultisig() returns all multisig addresses currently')
    printInfo('imported in the wallet. Each address represents a unique multisig')
    printInfo('configuration (different participants, threshold, or version).')

    // =========================================================================
    // Step 5: Export Multisig Preimage with exportMultisig()
    // =========================================================================
    printStep(5, 'Exporting multisig preimage with exportMultisig()')

    const exportResult = await kmd.exportMultisig({
      walletHandleToken,
      address: multisigResult.address,
    })

    printSuccess('Multisig preimage exported successfully!')
    printInfo('')
    printInfo('ExportMultisigResponse fields:')
    printInfo(`  multisigVersion: ${exportResult.multisigVersion}`)
    printInfo(`  threshold:       ${exportResult.threshold}`)
    printInfo(`  publicKeys:      Array of ${exportResult.publicKeys.length} Uint8Array(s)`)
    printInfo('')
    printInfo('Exported multisig configuration:')
    printInfo(`  Version:   ${exportResult.multisigVersion}`)
    printInfo(`  Threshold: ${exportResult.threshold} (minimum signatures required)`)
    printInfo(`  Public Keys:`)
    exportResult.publicKeys.forEach((pk, i) => {
      printInfo(`    ${i + 1}. ${formatBytesForDisplay(pk)} (${pk.length} bytes)`)
    })

    printInfo('')
    printInfo('What is the multisig preimage?')
    printInfo('-'.repeat(40))
    printInfo('The preimage contains the original parameters used to create')
    printInfo('the multisig address:')
    printInfo('  - multisigVersion: The format version (always 1)')
    printInfo('  - threshold: Minimum signatures required')
    printInfo('  - publicKeys: The ordered list of participant public keys')
    printInfo('')
    printInfo('This information is needed to:')
    printInfo('  - Reconstruct the multisig address')
    printInfo('  - Import the multisig into another wallet')
    printInfo('  - Verify the configuration of an existing multisig')

    // =========================================================================
    // Step 6: Verify Exported Info Matches Original
    // =========================================================================
    printStep(6, 'Verifying exported info matches original parameters')

    const versionMatches = exportResult.multisigVersion === multisigVersion
    const thresholdMatches = exportResult.threshold === threshold
    const keyCountMatches = exportResult.publicKeys.length === publicKeys.length

    // Check if all public keys match
    let allKeysMatch = keyCountMatches
    if (keyCountMatches) {
      for (let i = 0; i < publicKeys.length; i++) {
        const originalKey = publicKeys[i]
        const exportedKey = exportResult.publicKeys[i]
        if (originalKey.length !== exportedKey.length) {
          allKeysMatch = false
          break
        }
        for (let j = 0; j < originalKey.length; j++) {
          if (originalKey[j] !== exportedKey[j]) {
            allKeysMatch = false
            break
          }
        }
      }
    }

    printInfo('Verification results:')
    printInfo(`  Version matches:   ${versionMatches ? 'Yes' : 'No'} (expected: ${multisigVersion}, got: ${exportResult.multisigVersion})`)
    printInfo(`  Threshold matches: ${thresholdMatches ? 'Yes' : 'No'} (expected: ${threshold}, got: ${exportResult.threshold})`)
    printInfo(
      `  Key count matches: ${keyCountMatches ? 'Yes' : 'No'} (expected: ${publicKeys.length}, got: ${exportResult.publicKeys.length})`,
    )
    printInfo(`  All keys match:    ${allKeysMatch ? 'Yes' : 'No'}`)

    if (versionMatches && thresholdMatches && allKeysMatch) {
      printSuccess('All exported information matches the original parameters!')
    }

    // =========================================================================
    // Step 7: Delete the Multisig Account with deleteMultisig()
    // =========================================================================
    printStep(7, 'Deleting the multisig account with deleteMultisig()')

    printInfo(`Deleting multisig: ${multisigAddress}`)

    await kmd.deleteMultisig({
      walletHandleToken,
      address: multisigResult.address,
      walletPassword,
    })

    printSuccess('Multisig account deleted from wallet!')
    printInfo('')
    printInfo('deleteMultisig() parameters:')
    printInfo('  - walletHandleToken: Session token for the wallet')
    printInfo('  - address:           The multisig address to delete')
    printInfo('  - walletPassword:    Wallet password (required for security)')
    printInfo('')
    printInfo('Important notes about deleteMultisig():')
    printInfo('  - Only removes the multisig from the local KMD wallet')
    printInfo('  - Does NOT affect the blockchain account')
    printInfo('  - Any funds at the multisig address remain accessible')
    printInfo('  - To spend funds, re-import the multisig with the same parameters')

    // =========================================================================
    // Step 8: Verify Deletion by Listing Multisig Accounts Again
    // =========================================================================
    printStep(8, 'Verifying deletion by listing multisig accounts')

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

    printInfo('Multisig accounts after deletion:')
    if (listAfterDelete.addresses.length === 0) {
      printSuccess('No multisig accounts remaining in wallet')
    } else {
      printInfo(`Found ${listAfterDelete.addresses.length} multisig address(es):`)
      listAfterDelete.addresses.forEach((addr, i) => {
        printInfo(`  ${i + 1}. ${addr}`)
      })
    }

    // Check if the deleted address is still present
    const deletedAddressStillPresent = listAfterDelete.addresses.some((addr) => addr.toString() === multisigAddress)

    if (deletedAddressStillPresent) {
      printError('The deleted multisig address is still present (unexpected)')
    } else {
      printSuccess(`Confirmed: ${multisigAddress.slice(0, 8)}... is no longer in the wallet`)
    }

    // =========================================================================
    // Cleanup
    // =========================================================================
    printStep(9, '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 management in KMD:')
    printInfo('')
    printInfo('  listMultisig()')
    printInfo('    Parameters:')
    printInfo('      - walletHandleToken: Session token for the wallet')
    printInfo('    Returns:')
    printInfo('      - addresses:         Array of multisig Address objects')
    printInfo('')
    printInfo('  exportMultisig()')
    printInfo('    Parameters:')
    printInfo('      - walletHandleToken: Session token for the wallet')
    printInfo('      - address:           The multisig address to export')
    printInfo('    Returns:')
    printInfo('      - multisigVersion:   Multisig format version (1)')
    printInfo('      - threshold:         Minimum signatures required')
    printInfo('      - publicKeys:        Array of participant public keys')
    printInfo('')
    printInfo('  deleteMultisig()')
    printInfo('    Parameters:')
    printInfo('      - walletHandleToken: Session token for the wallet')
    printInfo('      - address:           The multisig address to delete')
    printInfo('      - walletPassword:    Wallet password (required)')
    printInfo('    Returns:')
    printInfo('      - (void)')
    printInfo('')
    printInfo('Key takeaways:')
    printInfo('  - listMultisig() shows all multisig accounts in the wallet')
    printInfo('  - exportMultisig() retrieves the original configuration (preimage)')
    printInfo('  - deleteMultisig() removes from wallet only, not blockchain')
    printInfo('  - Wallet password is required for deleteMultisig() for security')
    printInfo('  - Deleted multisigs can be re-imported with the same parameters')
    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)
})

Multisig Account Management

Description

Prerequisites

Run This Example

Code

Other examples in KMD Client