Cellframe JS library

----- UPDATE Mon Feb 10 04:04:49 PM CET 2025 -----

Library now uses wasm build of cellframe-tool-sign, and works on node.js, build is still experimental for browser environment but soon will be refactored to work on both environments out of the box.

----------------------------------------------------------------------

A TypeScript/JavaScript SDK for interacting with the Cellframe network, featuring cellframe's Dilithium post-quantum cryptography wallet's. This SDK runs cellframes signing tool executable: https://gitlab.demlabs.net/cellframe/cellframe-tool-sign, current latest commit hash 011f1cf6f6a99be3f47f7b7c1b7e444add248a1e, you can clone the repository, build it yourself and place cellframe-tool-sing inside bin dir of project root.

In future version library will be using WASM so it will work on clientside, currently it only runs on node.js

Tested on node version v22.2.0

Features

• Dilithium wallet creation and management
• Support for wallet recovery from mnemonics
• Transaction creation and signing
• Network interaction through JSON-RPC
• Base58/Hex address conversions

Installation

npm install cellframe.js

Basic Usage

Creating a Wallet

You can create a wallet either from mnemonics or generate a new one:

import { DilithiumWalletManager } from "cellframe.js";

// Initialize from existing mnemonics
const mnemonic = [
  "retort",
  "polygraph",
  "lenient" /* ... rest of mnemonic words */,
];

const wallet = await DilithiumWalletManager.createWalletFromMnemonic(
  mnemonic,
  "Backbone", // Network name
  1 // Dilithium kind (1 is default for Cellframe)
);

// Or generate a new wallet
const { wallet: newWallet, mnemonic: newMnemonic } =
  await DilithiumWalletManager.createNewWallet(
    "0x0404202200000000", // Network ID
    1 // Dilithium kind
  );

Setting up the Provider

The CellframeProvider is your main interface for interacting with the network:

import { CellframeProvider } from "cellframe.js";

const provider = new CellframeProvider(
  wallet, // Your wallet instance
  "http://rpc.cellframe.net", // RPC endpoint
  "" // Optional port
);

Checking Wallet Balance

const { totalValue, availableOutputs } = await provider.rpcGetWalletBalance(
  "Backbone", // Network name
  "CELL" // Token name
);

console.log("Total balance:", totalValue);
console.log("Available outputs:", availableOutputs.length);

Sending Tokens

The simplified way using rpcSendTokens:

const transactionParams = {
  network: "Backbone",
  chain: "main",
  recipientAddress:
    "Rj7J7MiX2bWy8sNyXkDyAZqnT1s388KF14Qgqh8BE5SHBznnBbGBEGDWzsXxzH1vbrbpaAF2Q8bWXfBUZyFYr3GR5tUzVwUgcNHYdmZg",
  amount: "50000000000000000",
  token: "CELL",
  networkFee: "0", // Optional, defaults to 0
  // validatorFee is optional - will be fetched from network if not provided
};

const result = await provider.rpcSendTokens(transactionParams);

Manual Transaction Creation

For more control over the transaction process:

// 1. Get wallet outputs
const outputsResponse = await provider.rpcGetWalletOutputs({
  network: "Backbone",
  addr: wallet.address,
  token: "CELL",
});

// 2. Parse outputs
const { totalValue, outputs } = provider.parseWalletOutputs(outputsResponse);

// 3. Calculate change
const change = await provider.calculateChange(
  totalValue,
  sendAmount,
  networkFee,
  validatorFee
);

// 4. Create transaction structure
const { inputs, outputs, conditionalOutputs } =
  provider.createTransactionStructure(
    availableOutputs,
    sendAmount,
    recipientAddress,
    change,
    validatorFee,
    senderAddress
  );

// 5. Send transaction
const result = await provider.rpcCreateAndSendTransaction(
  "Backbone",
  "main",
  inputs,
  outputs,
  conditionalOutputs
);

Common Operations

Converting Between Address Formats

import { DilithiumBaseWallet } from "cellframe.js";

// Convert hex to base58
const base58Address = DilithiumBaseWallet.hexToBase58(hexAddress);

// Get address from wallet
const walletAddress = DilithiumBaseWallet.hexToBase58(wallet.address);

Getting Validator Fees

// Get recommended validator fee from network
const validatorFee = await provider.rpcGetRecommendedValidatorFee("Backbone");

Error Handling

The SDK includes comprehensive error handling. Always wrap operations in try-catch blocks:

try {
  const result = await provider.rpcSendTokens(transactionParams);
  console.log("Transaction successful:", result);
} catch (error) {
  if (error instanceof Error) {
    console.error("Transaction failed:", error.message);
  }
}

Network Configuration

Currently supported networks:

const networks = {
  Backbone: { id: "0x0404202200000000" },
  KelVPN: { id: "0x1807202300000000" },
};

Best Practices

1. Always check wallet balance before attempting transactions
2. Use recommended validator fees from the network
3. Handle errors appropriately
4. Keep mnemonics secure
5. Verify addresses before sending transactions
6. Use the simplified rpcSendTokens method for basic transfers
7. Use manual transaction creation for more complex scenarios

Testing

The SDK includes comprehensive test examples demonstrating various use cases. Check the tests directory for detailed examples of:

• Wallet creation and recovery
• Balance checking
• Transaction sending
• Address conversion
• Output management

Run the tests using:

npm run test