​

ICP Ledger Canister

​

Overview

• Token Transfers: Send ICP tokens between accounts
• Balance Queries: Check account balances
• Transaction History: Query historical blocks and transactions
• ICRC-1 Standard: Full implementation of the ICRC-1 fungible token standard
• ICRC-2 Standard: Approve/transfer_from pattern for delegation
• Archive Canisters: Automatic archival of historical blocks for scalability

​

Account Model

​

Legacy AccountIdentifier

• Domain separator (“\x0Aaccount-id”)
• Principal
• Subaccount (32 bytes, defaults to zeros)

​

ICRC-1 Account

• owner: Principal that owns the account
• subaccount: Optional 32-byte blob (defaults to zeros)

​

Token Units

• 1 ICP = 100,000,000 e8s
• Transfer fee: 10,000 e8s (0.0001 ICP)

​

Core Methods

​

ICRC-1 Standard Methods

​

icrc1_transfer

• BadFee: Incorrect fee amount provided
• InsufficientFunds: Source account has insufficient balance
• TooOld: Transaction is older than 24 hours
• CreatedInFuture: Transaction timestamp is in the future
• Duplicate: Transaction with same memo and timestamp already exists
• TemporarilyUnavailable: Ledger is temporarily unavailable
• GenericError: Other error with description

​

icrc1_balance_of

​

icrc1_metadata

​

icrc1_supported_standards

​

icrc1_name

​

icrc1_symbol

​

icrc1_decimals

​

icrc1_fee

​

icrc1_total_supply

​

icrc1_minting_account

​

ICRC-2 Standard Methods

​

icrc2_approve

• BadFee: Incorrect fee
• InsufficientFunds: Insufficient balance to pay fee
• AllowanceChanged: Current allowance doesn’t match expected_allowance
• Expired: Expiration time is in the past
• TooOld: Transaction too old
• CreatedInFuture: Transaction timestamp in future
• Duplicate: Duplicate transaction
• TemporarilyUnavailable: Service temporarily unavailable
• GenericError: Other error

​

icrc2_transfer_from

• InsufficientAllowance: Not enough allowance for transfer + fee
• BadFee: Incorrect fee
• InsufficientFunds: Source account has insufficient balance
• TooOld: Transaction too old
• CreatedInFuture: Transaction in future
• Duplicate: Duplicate transaction
• TemporarilyUnavailable: Service unavailable
• GenericError: Other error

​

icrc2_allowance

​

Legacy Methods

​

transfer

​

account_balance

​

account_identifier

​

Query Methods

​

query_blocks

​

archives

​

tip_of_chain

​

transfer_fee

​

Archive Canisters

​

Archive Query Methods

​

get_blocks

​

get_encoded_blocks

​

Data Types

​

Block

​

Transaction

​

Operation

​

Transaction Deduplication

1. Each transaction can include a created_at_time timestamp
2. Transactions are deduplicated based on (sender, memo, created_at_time)
3. Deduplication window is 24 hours
4. If a duplicate is detected, the original block index is returned

​

Best Practices

​

For Developers

1. Use ICRC-1 Format: Prefer ICRC-1 Account format over legacy AccountIdentifier
2. Set Timestamps: Always set created_at_time for deduplication
3. Handle Errors: Properly handle all error variants
4. Use Query Methods: Use query methods for read operations (faster, cheaper)
5. Archive Access: Check archived_blocks when querying old transactions
6. Fee Checking: Always check current fee with icrc1_fee() before transfers

​

For Users

1. Transaction IDs: Save block indices for transaction tracking
2. Subaccounts: Use subaccounts to manage multiple addresses under one principal
3. Memo Usage: Use memos to track payment purposes
4. Approval Limits: Set reasonable allowance limits and expiration times

​

Examples

​

Transfer ICP (ICRC-1)

const result = await ledger.icrc1_transfer({
  from_subaccount: [],
  to: {
    owner: recipientPrincipal,
    subaccount: []
  },
  amount: 100_000_000n, // 1 ICP
  fee: [],
  memo: [],
  created_at_time: [BigInt(Date.now()) * 1_000_000n]
});

if ('Ok' in result) {
  console.log('Transfer successful, block:', result.Ok);
} else {
  console.error('Transfer failed:', result.Err);
}

​

Check Balance

const balance = await ledger.icrc1_balance_of({
  owner: myPrincipal,
  subaccount: []
});

console.log('Balance:', balance, 'e8s');
console.log('Balance:', Number(balance) / 100_000_000, 'ICP');

​

Approve and Transfer From

// Step 1: Approve spender
const approveResult = await ledger.icrc2_approve({
  from_subaccount: [],
  spender: {
    owner: spenderPrincipal,
    subaccount: []
  },
  amount: 100_000_000n, // 1 ICP
  fee: [],
  memo: [],
  created_at_time: [BigInt(Date.now()) * 1_000_000n],
  expected_allowance: [],
  expires_at: []
});

// Step 2: Spender transfers from approved account
const transferResult = await ledger.icrc2_transfer_from({
  spender_subaccount: [],
  from: {
    owner: approverPrincipal,
    subaccount: []
  },
  to: {
    owner: recipientPrincipal,
    subaccount: []
  },
  amount: 50_000_000n, // 0.5 ICP
  fee: [],
  memo: [],
  created_at_time: [BigInt(Date.now()) * 1_000_000n]
});

​

Query Transaction History

const response = await ledger.query_blocks({
  start: 0n,
  length: 100n
});

console.log('Total blocks:', response.chain_length);
console.log('Returned blocks:', response.blocks.length);

// Check archived blocks
for (const archived of response.archived_blocks) {
  console.log('Archive canister:', archived.callback.principal);
  console.log('Block range:', archived.start, 'to', archived.start + archived.length);
}

​

Common Patterns

​

Subaccount Generation

import { sha256 } from '@noble/hashes/sha256';

function generateSubaccount(seed: string): Uint8Array {
  const hash = sha256(new TextEncoder().encode(seed));
  return new Uint8Array([...hash, ...new Array(8).fill(0)].slice(0, 32));
}

const subaccount = generateSubaccount('user-123');

​

Polling for Confirmation

async function waitForBlock(blockIndex: bigint): Promise<Block> {
  for (let i = 0; i < 30; i++) {
    const response = await ledger.query_blocks({
      start: blockIndex,
      length: 1n
    });
    
    if (response.blocks.length > 0) {
      return response.blocks[0];
    }
    
    await new Promise(resolve => setTimeout(resolve, 1000));
  }
  
  throw new Error('Block not found after 30 seconds');
}

​

See Also

• NNS Governance API
• SNS Canisters API
• ICRC-1 Standard
• ICRC-2 Standard