Multisig Program Signing (Delegated Multisig Logic Signatures) with KMD

← Back to KMD Client

Description

This example demonstrates how to sign programs with multisig using the KMD signMultisigProgram() method. It shows:

• Creating a 2-of-3 multisig account
• Creating a simple TEAL program (logic signature)
• Compiling the TEAL program using algod tealCompile
• Signing the program with the first participant (partial signature)
• Signing the program with the second participant (completing the multisig)
• Understanding delegated multisig logic signatures What is Multisig Program Signing? Multisig program signing creates a “delegated multisig logic signature”. This combines two powerful concepts: 1. Multisig: Requiring multiple parties to approve 2. Delegated Logic Signatures: Authorizing a program to act on behalf of an account With a delegated multisig lsig:
• The multisig account authorizes a program to sign transactions
• Multiple parties must sign the program (meeting the threshold)
• Once signed, the program can authorize transactions within its logic
• No further interaction needed from the multisig participants Use cases for delegated multisig logic signatures:
• Multi-party controlled recurring payments
• Joint account automation (e.g., business partners authorizing limit)
• Escrow with automated release conditions
• DAO treasury with programmatic spending rules

Prerequisites

• LocalNet running (via algokit localnet start)
• Covered operations:
• signMultisigProgram() - Sign a compiled TEAL program with a multisig participant

Run This Example

From the repository root:

cd examples
npm run example kmd_client/13-multisig-program-signing.ts

Code

View source on GitHub

13-multisig-program-signing.ts

/**
 * Example: Multisig Program Signing (Delegated Multisig Logic Signatures) with KMD
 *
 * This example demonstrates how to sign programs with multisig using the KMD
 * `signMultisigProgram()` method. It shows:
 *   - Creating a 2-of-3 multisig account
 *   - Creating a simple TEAL program (logic signature)
 *   - Compiling the TEAL program using algod tealCompile
 *   - Signing the program with the first participant (partial signature)
 *   - Signing the program with the second participant (completing the multisig)
 *   - Understanding delegated multisig logic signatures
 *
 * What is Multisig Program Signing?
 * Multisig program signing creates a "delegated multisig logic signature".
 * This combines two powerful concepts:
 *   1. Multisig: Requiring multiple parties to approve
 *   2. Delegated Logic Signatures: Authorizing a program to act on behalf of an account
 *
 * With a delegated multisig lsig:
 *   - The multisig account authorizes a program to sign transactions
 *   - Multiple parties must sign the program (meeting the threshold)
 *   - Once signed, the program can authorize transactions within its logic
 *   - No further interaction needed from the multisig participants
 *
 * Use cases for delegated multisig logic signatures:
 *   - Multi-party controlled recurring payments
 *   - Joint account automation (e.g., business partners authorizing limit)
 *   - Escrow with automated release conditions
 *   - DAO treasury with programmatic spending rules
 *
 * Prerequisites:
 * - LocalNet running (via `algokit localnet start`)
 *
 * Covered operations:
 * - signMultisigProgram() - Sign a compiled TEAL program with a multisig participant
 */

import { Address, encodeAddress } from '@algorandfoundation/algokit-utils';
import type { MultisigSig } from '@algorandfoundation/algokit-utils/kmd-client';
import {
  LogicSig,
  LogicSigAccount,
  type MultisigSignature,
} from '@algorandfoundation/algokit-utils/transact';
import {
  cleanupTestWallet,
  createAlgodClient,
  createKmdClient,
  createTestWallet,
  loadTealSource,
  printError,
  printHeader,
  printInfo,
  printStep,
  printSuccess,
  shortenAddress,
} from '../shared/utils.js';
// Use algorand-msgpack for decoding the multisig response
import { IntMode, decode as msgpackDecode } from 'algorand-msgpack';

/**
 * Format a byte array for display, showing first and last few bytes
 *
 * @param bytes - The bytes to format
 * @param showFirst - Number of bytes to show at the start (default: 8)
 * @param showLast - Number of bytes to show at the end (default: 8)
 * @returns Formatted hex string with ellipsis if truncated
 */
function formatBytesForDisplay(bytes: Uint8Array, showFirst = 8, showLast = 8): 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}`;
}

/**
 * Decode the KMD multisig response bytes into a MultisigSig structure.
 * The KMD API returns msgpack-encoded MultisigSig with wire keys:
 * - 'subsig' -> subsignatures array
 * - 'thr' -> threshold
 * - 'v' -> version
 * Each subsig has:
 * - 'pk' -> publicKey
 * - 's' -> signature (optional)
 */
function decodeKmdMultisigResponse(multisigBytes: Uint8Array): MultisigSig {
  const decoded = msgpackDecode(multisigBytes, {
    intMode: IntMode.AS_ENCODED,
    useMap: true,
    rawBinaryStringKeys: true,
    rawBinaryStringValues: true,
  }) as Map<Uint8Array, unknown>;

  // Helper to find value by string key in Map with Uint8Array keys
  const findByKey = (map: Map<Uint8Array, unknown>, key: string): unknown => {
    const keyBytes = new TextEncoder().encode(key);
    for (const [k, v] of map) {
      if (k.length === keyBytes.length && k.every((b, i) => b === keyBytes[i])) {
        return v;
      }
    }
    return undefined;
  };

  const subsigArray = findByKey(decoded, 'subsig') as Array<Map<Uint8Array, unknown>>;
  const threshold = findByKey(decoded, 'thr') as number;
  const version = findByKey(decoded, 'v') as number;

  const subsignatures = subsigArray.map(subsigMap => {
    const publicKey = findByKey(subsigMap, 'pk') as Uint8Array;
    const signature = findByKey(subsigMap, 's') as Uint8Array | undefined;
    return { publicKey, signature };
  });

  return { subsignatures, threshold, version };
}

/**
 * Convert a KMD MultisigSig to the transact MultisigSignature format
 */
function kmdMultisigToTransactMultisig(kmdMsig: MultisigSig): MultisigSignature {
  return {
    version: kmdMsig.version,
    threshold: kmdMsig.threshold,
    subsigs: kmdMsig.subsignatures.map(subsig => ({
      publicKey: subsig.publicKey,
      sig: subsig.signature,
    })),
  };
}

/**
 * Count the number of signatures in a KMD MultisigSig
 */
function countSignatures(msig: MultisigSig): number {
  return msig.subsignatures.filter(subsig => subsig.signature !== undefined).length;
}

async function main() {
  printHeader('KMD Multisig Program Signing Example');

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

  try {
    // =========================================================================
    // Step 1: Create a Test Wallet
    // =========================================================================
    printStep(1, 'Creating a test wallet for multisig program signing');

    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: Address[] = [];
    const publicKeys: Uint8Array[] = [];
    const numParticipants = 3;

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

    printSuccess(`Generated ${numParticipants} participant keys`);

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

    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;

    printSuccess('Multisig account created!');
    printInfo(`Multisig Address: ${multisigAddress}`);
    printInfo(`Threshold: ${threshold}-of-${numParticipants}`);
    printInfo('');
    printInfo('This multisig address will be used as the delegator for the logic signature.');

    // =========================================================================
    // Step 4: Create a Simple TEAL Program
    // =========================================================================
    printStep(4, 'Creating a simple TEAL program');

    // Load TEAL logic signature from shared artifacts
    // This program approves payment transactions up to 1 ALGO
    // In production, you'd have more sophisticated logic
    const tealSource = loadTealSource('delegated-payment-limit.teal');

    printInfo('TEAL Program Source:');
    printInfo('');
    tealSource.split('\n').forEach(line => {
      printInfo(`    ${line}`);
    });
    printInfo('');
    printInfo('This program approves payment transactions up to 1 ALGO.');
    printInfo('When signed by a multisig account, it creates a "delegated multisig lsig".');

    // =========================================================================
    // Step 5: Compile the TEAL Program
    // =========================================================================
    printStep(5, 'Compiling the TEAL program using algod tealCompile');

    const compileResult = await algod.tealCompile(tealSource);

    // Decode base64 result to Uint8Array
    const programBytes = new Uint8Array(Buffer.from(compileResult.result, 'base64'));

    printSuccess('TEAL program compiled successfully!');
    printInfo('');
    printInfo('Compilation Result:');
    printInfo(`  Hash (program address): ${compileResult.hash}`);
    printInfo(`  Compiled size:          ${programBytes.length} bytes`);
    printInfo(`  Compiled bytes:         ${formatBytesForDisplay(programBytes)}`);

    // =========================================================================
    // Step 6: Sign with the First Participant (Partial Signature)
    // =========================================================================
    printStep(6, 'Signing the program with the first participant');

    printInfo(`First signer: ${shortenAddress(participantAddresses[0].toString())}`);
    printInfo('');

    const firstSignResult = await kmd.signMultisigProgram({
      walletHandleToken,
      address: multisigAddress,
      program: programBytes,
      publicKey: publicKeys[0],
      walletPassword,
    });

    printSuccess('First signature obtained!');
    printInfo('');
    printInfo('SignProgramMultisigResponse fields:');
    printInfo(`  multisig: Uint8Array (${firstSignResult.multisig.length} bytes)`);
    printInfo('');

    // Decode and display the partial multisig signature
    const partialKmdMultisig = decodeKmdMultisigResponse(firstSignResult.multisig);
    const sigCount1 = countSignatures(partialKmdMultisig);

    printInfo('Partial Multisig Signature:');
    printInfo(`  version:   ${partialKmdMultisig.version}`);
    printInfo(`  threshold: ${partialKmdMultisig.threshold}`);
    printInfo(`  subsigs:   ${partialKmdMultisig.subsignatures.length} participants`);
    printInfo(`  Signatures collected: ${sigCount1} of ${threshold} required`);
    printInfo('');
    printInfo('Subsignature details:');
    partialKmdMultisig.subsignatures.forEach((subsig, i) => {
      const hasSig = subsig.signature !== undefined;
      const status = hasSig ? '✓ SIGNED' : '○ pending';
      const addr = encodeAddress(subsig.publicKey);
      printInfo(`  ${i + 1}. ${shortenAddress(addr)} - ${status}`);
    });

    printInfo('');
    printInfo('Note: With only 1 signature, the multisig lsig is not yet valid.');
    printInfo(`      We need ${threshold} signatures (${threshold - sigCount1} more required).`);

    // =========================================================================
    // Step 7: Sign with the Second Participant (Complete the Multisig)
    // =========================================================================
    printStep(7, 'Signing the program with the second participant');

    printInfo(`Second signer: ${shortenAddress(participantAddresses[1].toString())}`);
    printInfo('');
    printInfo('Passing the partial multisig from Step 6 to collect the second signature...');
    printInfo('');

    const secondSignResult = await kmd.signMultisigProgram({
      walletHandleToken,
      address: multisigAddress,
      program: programBytes,
      publicKey: publicKeys[1],
      walletPassword,
      partialMultisig: partialKmdMultisig, // Pass the partial signature from first signer
    });

    printSuccess('Second signature obtained!');
    printInfo('');

    // Decode and display the completed multisig signature
    const completedKmdMultisig = decodeKmdMultisigResponse(secondSignResult.multisig);
    const sigCount2 = countSignatures(completedKmdMultisig);

    printInfo('Completed Multisig Signature:');
    printInfo(`  version:   ${completedKmdMultisig.version}`);
    printInfo(`  threshold: ${completedKmdMultisig.threshold}`);
    printInfo(`  Signatures collected: ${sigCount2} of ${threshold} required`);
    printInfo('');
    printInfo('Subsignature details:');
    completedKmdMultisig.subsignatures.forEach((subsig, i) => {
      const hasSig = subsig.signature !== undefined;
      const status = hasSig ? '✓ SIGNED' : '○ pending';
      const addr = encodeAddress(subsig.publicKey);
      printInfo(`  ${i + 1}. ${shortenAddress(addr)} - ${status}`);
    });

    printInfo('');
    printSuccess(`Threshold met! ${sigCount2} >= ${threshold} signatures collected.`);
    printInfo('The delegated multisig logic signature is now fully authorized.');

    // =========================================================================
    // Step 8: Create a LogicSigAccount with the Multisig Signature
    // =========================================================================
    printStep(8, 'Creating a LogicSigAccount with the multisig signature');

    printInfo('A delegated multisig LogicSigAccount combines:');
    printInfo('  1. The compiled program (logic)');
    printInfo('  2. The multisig signature (delegation proof from multiple parties)');
    printInfo('  3. The multisig delegator address');
    printInfo('');

    // Get the program address (hash of "Program" + logic)
    const nonDelegatedLsig = new LogicSig(programBytes);
    const programAddress = nonDelegatedLsig.address();

    // Create a LogicSigAccount for delegation
    const lsigAccount = new LogicSigAccount(programBytes, [], multisigAddress);

    // Convert KMD MultisigSig to transact's MultisigSignature format
    const completedMultisig = kmdMultisigToTransactMultisig(completedKmdMultisig);
    lsigAccount.msig = completedMultisig;

    printSuccess('LogicSigAccount created with multisig signature!');
    printInfo('');
    printInfo('LogicSigAccount properties:');
    printInfo(`  Program address:   ${shortenAddress(programAddress.toString())}`);
    printInfo(`  Delegator address: ${shortenAddress(multisigAddress.toString())} (multisig)`);
    printInfo(`  Has msig:          ${lsigAccount.msig !== undefined}`);
    printInfo(`  Logic size:        ${lsigAccount.logic.length} bytes`);
    printInfo('');

    // Show the distinction between program address and delegator
    printInfo('Important distinction:');
    printInfo(`  - Program address: ${shortenAddress(programAddress.toString())}`);
    printInfo('    Hash of the logic - this is the "contract account" in non-delegated mode');
    printInfo('');
    printInfo(`  - lsigAccount.addr: ${shortenAddress(lsigAccount.addr.toString())}`);
    printInfo('    This is the DELEGATOR - the multisig account authorizing the program');
    printInfo('');
    printInfo('When using this delegated multisig lsig, transactions will be authorized');
    printInfo(
      `as if signed by the multisig account ${shortenAddress(multisigAddress.toString())}.`,
    );

    // =========================================================================
    // Step 9: Explain How Delegated Multisig Logic Signatures Work
    // =========================================================================
    printStep(9, 'Understanding delegated multisig logic signatures');

    printInfo('Delegated Multisig Logic Signatures combine two concepts:');
    printInfo('');
    printInfo('1. MULTISIG AUTHORIZATION:');
    printInfo('   - Multiple parties (2-of-3 in this example) must approve');
    printInfo('   - Each party signs the program bytes with their key');
    printInfo('   - Signatures are collected via partialMultisig parameter');
    printInfo('   - Once threshold is met, the authorization is complete');
    printInfo('');
    printInfo('2. DELEGATED LOGIC SIGNATURE:');
    printInfo('   - The program defines the rules for transactions');
    printInfo('   - The multisig signature authorizes the program');
    printInfo('   - Anyone with the lsig can submit transactions (if program approves)');
    printInfo('   - No further interaction from the multisig signers needed');
    printInfo('');
    printInfo('Key differences from regular multisig transactions:');
    printInfo('   - Multisig Txn: Signers approve EACH transaction');
    printInfo('   - Multisig Lsig: Signers approve the PROGRAM once, then');
    printInfo('                   the program approves transactions automatically');
    printInfo('');
    printInfo('Example workflow for using the delegated multisig lsig:');
    printInfo('');
    printInfo('  1. Create a Transaction with sender = multisig address');
    printInfo('');
    printInfo('  2. Use the LogicSigAccount.signer to sign:');
    printInfo('');
    printInfo('     const signedTxns = await lsigAccount.signer([txn], [0])');
    printInfo('');
    printInfo('  3. The signed transaction includes:');
    printInfo('     - lsig.logic:  The compiled TEAL program');
    printInfo('     - lsig.msig:   The multisig delegation signature');
    printInfo('');
    printInfo('  4. When submitted, the network validates:');
    printInfo('     - The multisig signature is valid (threshold met)');
    printInfo('     - The program logic approves the transaction');

    // =========================================================================
    // 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 program signing with KMD:');
    printInfo('');
    printInfo('  signMultisigProgram() - Sign a TEAL program with multisig');
    printInfo('     Parameters:');
    printInfo('       - walletHandleToken: The wallet session token');
    printInfo('       - address: The multisig account address (delegator)');
    printInfo('       - program: The compiled TEAL program bytes');
    printInfo('       - publicKey: The public key of the signer (must be in wallet)');
    printInfo('       - walletPassword: The wallet password');
    printInfo('       - partialMultisig: (optional) Existing partial signature to add to');
    printInfo('     Returns:');
    printInfo('       - multisig: Uint8Array (msgpack-encoded MultisigSig)');
    printInfo('');
    printInfo('Multisig program signing workflow:');
    printInfo('  1. Create a multisig account with importMultisig()');
    printInfo('  2. Write a TEAL program with the desired authorization logic');
    printInfo('  3. Compile the program using algod.tealCompile()');
    printInfo('  4. Sign with first participant using signMultisigProgram()');
    printInfo('  5. Sign with additional participants, passing partialMultisig');
    printInfo('  6. Once threshold is met, create LogicSigAccount with msig');
    printInfo('  7. Use LogicSigAccount.signer to sign authorized transactions');
    printInfo('');
    printInfo('Key points:');
    printInfo('  - Each participant signs the PROGRAM (not transactions)');
    printInfo('  - The partialMultisig parameter chains signatures together');
    printInfo('  - The response contains msgpack-encoded MultisigSignature');
    printInfo('  - Unlike signMultisigTransaction, program signing is done ONCE');
    printInfo('  - The resulting lsig can sign unlimited transactions (per program logic)');
    printInfo('');
    printInfo('Security considerations:');
    printInfo('  - Write program logic carefully - it controls your multisig account!');
    printInfo('  - Multiple parties review and sign the program code');
    printInfo('  - Consider time bounds, amount limits, and recipient restrictions');
    printInfo('  - The delegated lsig grants ongoing authorization until program expires');
    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');
    printInfo('  - Check that Algod is accessible on port 4001');

    // 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

• KMD Version Information
• Wallet Creation and Listing
• Wallet Session Management
• Key Generation
• Key Import and Export
• Key Listing and Deletion
• Master Key Export
• Multisig Account Setup
• Multisig Account Management
• Transaction Signing with KMD
• Multisig Transaction Signing with KMD
• Program Signing (Delegated Logic Signatures) with KMD
• Multisig Program Signing (Delegated Multisig Logic Signatures) with KMD