Charms JS

TypeScript SDK for decoding Bitcoin transactions containing Charms data.

Installation

npm install charms-js

Usage

Browser (Automatic WASM initialization)

import { extractCharmsForWallet } from "charms-js";

// Simple usage - WASM auto-initializes
const charms = await extractCharmsForWallet(
  txHex,
  txId,
  walletOutpoints,
  "testnet4"
);

console.log("Charms found:", charms);

Requirements for Browser:

• Copy charms_lib_bg.wasm to your public/ directory
• The library will automatically load and initialize the WASM module

Node.js (Manual WASM initialization)

import { initializeWasm, extractCharmsForWallet } from "charms-js/dist/node";

// Manual WASM initialization required
const wasmBindings = await import("charms-js/dist/wasm/charms_lib_bg.js");
const fs = require("fs");
const wasmBuffer = fs.readFileSync("path/to/charms_lib_bg.wasm");

const wasmModule = await WebAssembly.instantiate(wasmBuffer, {
  "./charms_lib_bg.js": wasmBindings,
});

wasmBindings.__wbg_set_wasm(wasmModule.instance.exports);
initializeWasm(wasmBindings);

// Now you can use the library
const charms = await extractCharmsForWallet(
  txHex,
  txId,
  walletOutpoints,
  "testnet4"
);

File Structure

src/
├── index.ts          # Browser entry point (auto-init WASM)
├── node.ts           # Node.js entry point (manual init)
├── browser.ts        # Browser-specific WASM auto-initialization
├── wasm-integration.ts # Core WASM integration logic
├── wallet-adapter.ts # Wallet filtering utilities
└── wasm/            # WASM binaries and bindings
    ├── charms_lib_bg.wasm
    └── charms_lib_bg.js

API Reference

extractCharmsForWallet(txHex, txId, walletOutpoints, network?)

Extracts charms from a transaction, filtered by wallet ownership.

Parameters:

• txHex: Transaction hex string
• txId: Transaction ID
• walletOutpoints: Set of wallet-owned outpoints (txid:vout)
• network: 'mainnet' or 'testnet4' (default: 'testnet4')

Returns: Promise<CharmObj[]>

extractAndVerifySpell(txHex, network?, txId?, mock?)

Extracts and optionally verifies charms from a transaction.

Parameters:

• txHex: Transaction hex string
• network: 'mainnet' or 'testnet4' (default: 'testnet4')
• txId: Optional transaction ID (calculated automatically if not provided)
• mock: If true, skip proof verification (for mock/test proofs). Default: false

Returns: Promise<CharmExtractionResult>

Example - Production (with verification):

import { extractAndVerifySpell } from "charms-js";

const result = await extractAndVerifySpell(txHex, "mainnet");
if (result.success) {
  console.log("Charms:", result.charms);
}

Example - Testnet with mock proofs (skip verification):

// For testnet transactions using mock proofs
const result = await extractAndVerifySpell(txHex, "testnet4", undefined, true);

Note: Mock proofs are used in testnet for development/testing. Production transactions on mainnet should always use mock=false (default) to verify the proof cryptographically.

Browser-only functions

• isWasmReady(): Check if WASM is initialized

Types

interface CharmExtractionResult {
  success: boolean;
  charms: CharmObj[];
  error?: string; // Present if success is false
  message?: string; // Human-readable status message
}

interface CharmObj {
  appId: string;
  amount: number; // Amount in satoshis
  version: number;
  metadata: {
    ticker?: string;
    name?: string;
    description?: string;
    image?: string;
    image_hash?: string;
    url?: string;
  };
  app: Record<string, any>;
  outputIndex: number; // Zero-based output index in the transaction
  txid: string; // Transaction ID in display format (little-endian, reversed bytes)
  address: string; // Bitcoin address for this output (P2PKH, P2SH, P2WPKH, P2WSH, or P2TR)
}

Important Notes

Transaction ID Format: The txid field is returned in display format (little-endian, reversed bytes), which matches the format used by block explorers like mempool.space. This is the standard format for displaying transaction IDs to users.

Output Index: The outputIndex corresponds to the position of this charm's output in the transaction, starting from 0. Use this with txid to uniquely identify the UTXO: ${txid}:${outputIndex}

Address: The address field contains the Bitcoin address that controls this output. This is extracted directly from the output's scriptPubKey and supports all standard address types including Taproot (P2TR).

Migration from v3.0.x

Browser users: Replace manual WASM initialization with direct imports:

// OLD (manual)
await ensureWasmInitialized();
const charms = await extractCharmsForWallet(...);

// NEW (automatic)
import { extractCharmsForWallet } from 'charms-js';
const charms = await extractCharmsForWallet(...);

• The WASM extraction operates on txHex. The txid included in CharmObj is provided for identification and wallet filtering convenience.

License

MIT