Charms JS

TypeScript library for decoding Bitcoin transactions containing Charms data.

Installation

npm install charms-js

Usage

TypeScript

import { decodeTransaction, hasCharmsData } from 'charms-js';

// Example Bitcoin transaction hex containing Charms data
const txHex = '0200000000010...'; // Your transaction hex here


// Check if the transaction contains Charms data
const containsCharms = hasCharmsData(txHex);
console.log(`Contains Charms data: ${containsCharms}`);

if (containsCharms) {
  // Decode the transaction to get charm information (with verification)
  const charms = decodeTransaction(txHex);
  
  if ('error' in charms) {
    console.log(`Error: ${charms.error}`);
  } else {
    console.log('Charms:', JSON.stringify(charms, null, 2));
    console.log(`Found ${charms.length} charm(s)`);
  }
}

JavaScript

const { decodeTransaction, hasCharmsData } = require('charms-js');

// Example Bitcoin transaction hex containing Charms data
const txHex = '0200000000010...'; // Your transaction hex here


// Check if the transaction contains Charms data
const containsCharms = hasCharmsData(txHex);
console.log(`Contains Charms data: ${containsCharms}`);

if (containsCharms) {
  // Decode the transaction to get charm information (with verification)
  const charms = decodeTransaction(txHex);
  
  if ('error' in charms) {
    console.log(`Error: ${charms.error}`);
  } else {
    console.log('Charms:', JSON.stringify(charms, null, 2));
    console.log(`Found ${charms.length} charm(s)`);
  }
}

API

hasCharmsData(txHex: string): boolean

Checks if a Bitcoin transaction contains Charms data.

• Parameters:
  • txHex - Hex string of the Bitcoin transaction
• Returns: boolean - True if the transaction contains Charms data, false otherwise

decodeTransaction(txHex: string): CharmInstance[] | ErrorResponse

Decodes a Bitcoin transaction containing Charms data and returns detailed information about each charm.

• Parameters:
  • txHex - Hex string of the Bitcoin transaction
• Returns: CharmInstance[] | ErrorResponse - Array of detailed charm information or an error response

Types

CharmInstance

interface CharmInstance {
  utxo: {
    tx: string;
    index: number;
  };
  address: string;
  appId: string;
  app: string | null;
  appType?: string;
  verified?: boolean;       // Verification status when VK provided
  ticker?: string;
  remaining?: number;
  value?: number;
  name?: string;
  description?: string;
  url?: string;
  image?: string;
  image_hash?: string;
  decimals?: number;
  ref?: string;
  custom?: Record<string, any>;
}

ErrorResponse

interface ErrorResponse {
  error: string;
}

Example

See the complete example in examples/example.ts which demonstrates:

• Checking if a transaction contains Charms data
• Decoding transaction with verification
• Error handling

Run the example:

npx ts-node examples/example.ts

License

MIT