Skip to content

Developer Resources

Community-built open source tools exist for building on top of Cauldron programmatically. These are third-party projects not maintained by Riften Labs.

Tool Type Description
CashLab TypeScript library Programmatic API for trade construction and pool interaction
VegaBCH CLI application Command-line interface for executing trades
BCHCockpit Web application Browser-based tool for discovering and withdrawing pool positions

All three are built by the same developer (hosseinzoda). CashLab is the foundational library; VegaBCH and BCHCockpit both depend on it.

CashLab

CashLab is a set of TypeScript packages for BCH DeFi. The @cashlab/cauldron package provides programmatic access to Cauldron trade construction and pool interaction. It works in both Node.js and browser environments.

Installation

npm install @cashlab/common @cashlab/cauldron

@cashlab/common is always required alongside @cashlab/cauldron. It provides the transaction construction primitives (SpendableCoin, PayoutRule, createPayoutTx, etc.) that the cauldron package builds on.

Key Concepts

Export Description
ExchangeLab Main class for constructing and verifying trades
constructTradeBestRateForTargetDemand() Route a trade across multiple pools for optimal rate
createTradeTx() Build the signed trade transaction
verifyTradeTx() Verify the transaction satisfies pool constraints
generatePoolV0LockingBytecode() Generate locking script for a V0 pool
buildPoolV0RedeemScriptBytecode() Build redeem script for pool withdrawal

Example: Constructing a Trade

The following example shows how to construct a trade that buys tokens with BCH, routing across multiple pools for the best rate:

import { cauldron, TokenId, NATIVE_BCH_TOKEN_ID } from '@cashlab/cauldron';
import type { PoolV0Parameters, PoolV0, TradeResult, TradeTxResult } from '@cashlab/cauldron';

const exlab = new cauldron.ExchangeLab();

// Define the trade: supply BCH, demand tokens
const supply_token_id: TokenId = 'BCH';
const demand_token_id: TokenId = '<token_id_hex>';

// Pool parameters (fetched from an indexer or Electrum)
const pool_params: PoolV0Parameters = {
  withdraw_pubkey_hash: '<pool_withdraw_pubkey_hash>',
};
const pool_locking_bytecode = exlab.generatePoolV0LockingBytecode(pool_params);

const input_pools: PoolV0[] = [
  {
    version: '0',
    parameters: pool_params,
    outpoint: {
      index: 0,
      txhash: hexToBin('<txhash_hex>'),
    },
    output: {
      locking_bytecode: pool_locking_bytecode,
      token: {
        amount: 1000000n,
        token_id: '<token_id_hex>',
      },
      amount: 500000000n,
    },
  },
  // ... additional pools for better routing
];

// Find the best route across pools for 50000 tokens
const demand: bigint = 50000n;
const result: TradeResult = exlab.constructTradeBestRateForTargetDemand(
  supply_token_id,
  demand_token_id,
  demand,
  input_pools
);

// Build the transaction
const txfee_per_byte: bigint = 1n;
const tx_result: TradeTxResult = exlab.createTradeTx(
  result.pool_trade_list,
  input_coins,     // SpendableCoin[] from your wallet
  payout_rules,    // PayoutRule[] for trade outputs
  null,
  txfee_per_byte
);

// Verify and broadcast
exlab.verifyTradeTx(tx_result);
// tx_result.txbin is the raw transaction ready for broadcast

!!! note One side of every Cauldron trade must be native BCH. Direct token-to-token swaps require routing through BCH as an intermediary.

For the full @cashlab/common API (transaction construction, UTXO types, payout rules), see the common package documentation.

VegaBCH CLI

VegaBCH is a command-line tool for BCH DeFi operations. It wraps CashLab with wallet management, Electrum connectivity, and a daemon mode.

Installation

npm install -g vegabch

Configuration

VegaBCH requires a JSON config file passed via --config <path>. The simplest setup is standalone mode:

{
  "type": "standalone",
  "vega_storage_file": "./vega-storage.json",
  "main_electrum_node": "wss://electrum.imaginary.cash:50004",
  "cauldron_indexer_node": "wss://electrum.cauldron.quest:50004"
}

VegaBCH also supports a daemon mode (persistent HTTP/RPC server) and a client mode (connects to a running daemon). See the VegaBCH README for details.

Trading with VegaBCH

Trading is a two-step process:

Step 1: Construct the trade - finds the optimal route across pools:

# Buy tokens with BCH (get at least 100 tokens)
vegabch cauldron:construct-trade BCH <token_id> 100 trade.json \
  --config config.json \
  --txfee-per-byte 1 \
  --target-demand \
  --decimal-amounts
  • --target-demand (default): the demand output will be >= the requested amount
  • --target-supply: the supply input will be <= the requested amount
  • --decimal-amounts: use token-defined decimal places (e.g., 1.00000000 = 1 BCH)

Step 2: Fund and broadcast - signs with your wallet and sends:

vegabch cauldron:fund-trade trade.json \
  --config config.json \
  --wallet mywallet \
  --txfee-per-byte 1 \
  --broadcast

Wallet Setup

# Generate a new HD wallet
vegabch wallet:generate mywallet seed --config config.json

# Or import an existing mnemonic
vegabch wallet:create mywallet seed \
  --config config.json \
  --mnemonic 'your twelve words here'

# Pin it as the default
vegabch wallet:pin mywallet --config config.json

# Check balance
vegabch wallet:balance --config config.json

Cauldron Command Reference

Command Description
cauldron:construct-trade SUPPLY DEMAND AMOUNT [OUTPUT] Construct optimal multi-pool trade
cauldron:fund-trade TRADE_FILE Fund trade with wallet, optionally broadcast

BCHCockpit

BCHCockpit is a browser-based tool for discovering and withdrawing Cauldron V0 liquidity pool positions. It was built as a fallback for when the official Cauldron frontend is unavailable.

What It Does

  • Wallet management: Add wallets via BIP39 mnemonic or as watch-only
  • Pool discovery: Scans for Cauldron V0 pools associated with your wallet addresses
  • Withdrawal: Withdraw your liquidity from discovered pools

BCHCockpit runs entirely in the browser. It connects directly to Electrum servers for blockchain data and resolves token metadata via BCMR (Bitcoin Cash Metadata Registry). No backend server is required.

!!! warning BCHCockpit is designed for pool withdrawal only. It does not support trading, pool creation, or deposits.

Using the Hosted Version

The easiest way to use BCHCockpit is the hosted version at hosseinzoda.github.io/bchcockpit/. No installation required.

Self-Hosting

git clone https://github.com/hosseinzoda/bchcockpit.git
cd bchcockpit
npm install
npm run build    # Build static files for production
npm run start    # Or run dev server