TypeScript SDK

git clone https://github.com/ksana-in-bitcoin/Ksana
(cd Ksana/sdk/ts && npm ci && npm run build && npm pack)
mkdir -p my-app/vendor && mv Ksana/sdk/ts/ksana-sdk-0.1.0.tgz my-app/vendor/
cd my-app
npm init -y
npm pkg set type=module
npm install ./vendor/ksana-sdk-0.1.0.tgz

import { KsanaRpcClient, SIGNET } from '@ksana/sdk';

const rpc = new KsanaRpcClient('https://signet.ksana.network/rpc', { timeoutMs: 30_000 });
// The parameters to sign with. A node on another network throws ChainMismatchError here.
const params = await rpc.getParams(SIGNET);
const { tip, finalized } = await rpc.getChainInfo();
console.log(`chain ${params.chain_id}, tip ${tip.height}, finalized ${finalized.height}`);

import { readFile } from 'node:fs/promises';
import { fromHex, isValidSecretKey, randomBytes } from '@ksana/sdk';

/** A new secret key: 32 random bytes that are a valid secp256k1 key. */
export function newSecretKey(): Uint8Array {
  for (;;) {
    const key = randomBytes(32);
    if (isValidSecretKey(key)) return key;
  }
}

/** Reads a key file of ksana-cli or ksana-keytool: the secret key as 64 hex digits. */
export async function readKeyFile(path: string): Promise<Uint8Array> {
  return fromHex((await readFile(path, 'utf8')).trim(), 32, path);
}

import { accountOf, accountToAddress, parseAccount, toHex } from '@ksana/sdk';
import { readKeyFile } from './keys.js';

const account = accountOf(await readKeyFile('alice.key')); // 32 bytes: the Taproot output key
const address = accountToAddress(account, 'signet');
console.log(toHex(account));
console.log(address);
// parseAccount takes 64 hex digits or a Taproot address of the given network
console.log(toHex(parseAccount(address, 'signet')) === toHex(account));

import {
  type KsanaRpcClient,
  type Params,
  type UnsignedVmOp,
  VMOP_VERSION,
  accountOf,
  encodeVmOp,
  feeFor,
  ksaAssetId,
  opCost,
  signedVmop,
} from '@ksana/sdk';

/** Sends `amount` base units of KSA to `to` on path B and returns the op's ID. */
export async function transfer(
  rpc: KsanaRpcClient,
  params: Params,
  secretKey: Uint8Array,
  to: Uint8Array,
  amount: bigint,
): Promise<Uint8Array> {
  const account = accountOf(secretKey);
  const [{ nonce }, estimate] = await Promise.all([rpc.getAccount(account), rpc.estimateFee()]);
  const maxGas = 10_000n; // a KSA transfer uses exactly 10,000 gas
  const unsigned: UnsignedVmOp = {
    version: VMOP_VERSION,
    chain_id: params.chain_id,
    account,
    nonce, // the account's next nonce
    fee: { kind: 'Token', amount: estimate.path_b.amount },
    max_gas: maxGas,
    action: { kind: 'AssetTransfer', asset: ksaAssetId(), to, amount },
  };
  // The suggested rate is per KiB of the op's cost: measure the signed op, then sign the real fee.
  const cost = opCost(params, encodeVmOp(signedVmop(unsigned, secretKey)).length, maxGas);
  const fee = feeFor(estimate.path_b.per_kib, cost, estimate.path_b.amount);
  const op = signedVmop({ ...unsigned, fee: { kind: 'Token', amount: fee } }, secretKey);
  const { op_id } = await rpc.submitOp(op); // RpcError -32010 or -32011 when the node refuses it
  return op_id;
}

import {
  KsanaRpcClient,
  SIGNET,
  UnisatAdapter,
  type UnsignedVmOp,
  VMOP_VERSION,
  type WalletAdapter,
  XverseAdapter,
  btcNetworkOf,
  encodeVmOp,
  feeFor,
  fromHex,
  ksaAssetId,
  opCost,
  signVmopWithWallet,
} from '@ksana/sdk';

const rpc = new KsanaRpcClient('https://signet.ksana.network/rpc', { timeoutMs: 30_000 });

/** Connects Unisat or Xverse, checks its network, and returns its Ksana account. */
export async function connect(
  kind: 'unisat' | 'xverse',
): Promise<{ wallet: WalletAdapter; address: string; account: Uint8Array }> {
  const wallet: WalletAdapter = kind === 'unisat' ? new UnisatAdapter() : new XverseAdapter();
  const params = await rpc.getParams(SIGNET);
  // A tb1 address does not tell the signet from testnet: ask the wallet, which may not know.
  const network = await wallet.getNetwork?.();
  if (network !== undefined && network.network !== btcNetworkOf(params)) {
    throw new Error(`switch the wallet to Bitcoin Signet (it is on ${network.name})`);
  }
  const { address, account } = await wallet.getAccount(); // throws unless the address is Taproot
  return { wallet, address, account: fromHex(account, 32) };
}

/** Sends KSA on path B: the wallet signs a message, and no bitcoin moves. Returns the op's ID. */
export async function send(
  wallet: WalletAdapter,
  account: Uint8Array,
  to: Uint8Array,
  amount: bigint,
): Promise<Uint8Array> {
  const params = await rpc.getParams(SIGNET);
  const [{ nonce }, estimate] = await Promise.all([rpc.getAccount(account), rpc.estimateFee()]);
  const maxGas = 10_000n;
  const unsigned: UnsignedVmOp = {
    version: VMOP_VERSION,
    chain_id: params.chain_id,
    account,
    nonce,
    fee: { kind: 'Token', amount: estimate.path_b.amount },
    max_gas: maxGas,
    action: { kind: 'AssetTransfer', asset: ksaAssetId(), to, amount },
  };
  // A wallet's signature encodes in at most 67 bytes: size the op without asking the wallet twice.
  const placeholder = { kind: 'Bip322Simple' as const, bytes: new Uint8Array(67) };
  const cost = opCost(params, encodeVmOp({ ...unsigned, sig: placeholder }).length, maxGas);
  const fee = feeFor(estimate.path_b.per_kib, cost, estimate.path_b.amount);
  const final: UnsignedVmOp = { ...unsigned, fee: { kind: 'Token', amount: fee } };
  // The wallet shows a message to sign: the op's sighash in hex.
  const op = await signVmopWithWallet(final, wallet);
  return (await rpc.submitOp(op)).op_id;
}

import type { KsanaRpcClient, OpStatus } from '@ksana/sdk';

/** Polls an op once a second until it is executed or final, or until `timeoutMs` passes. */
export async function waitFor(
  rpc: KsanaRpcClient,
  opId: Uint8Array,
  timeoutMs = 120_000,
): Promise<OpStatus> {
  const deadline = Date.now() + timeoutMs;
  for (;;) {
    const status = await rpc.getOpStatus(opId); // RpcError -32004 while the node does not know it
    if (status.status !== 'pending' && status.status !== 'skipped') return status;
    if (Date.now() > deadline) throw new Error(`still ${status.status} after ${timeoutMs} ms`);
    await new Promise((resolve) => setTimeout(resolve, 1_000));
  }
}

import { KsanaRpcClient, fromHex } from '@ksana/sdk';
import { waitFor } from './follow.js';

const rpc = new KsanaRpcClient('https://signet.ksana.network/rpc', { timeoutMs: 30_000 });
const opId = fromHex('6daa9848433a349d8f915102679c3cd8632f351c3ee4a17207a58839158dda99', 32);
const status = await waitFor(rpc, opId);
console.log(`${status.status} in block ${status.block?.height}, gas ${status.receipt?.gas_used}`);
if (status.block !== null) {
  const s = await rpc.getSettlement(status.block.hash);
  const confirmations = s.confirmed?.confirmations ?? 0;
  console.log(`settlement ${s.status}, ${confirmations} confirmations`);
  console.log(`Bitcoin txid ${s.txid_rpc}`);
  console.log(`btc_final ${s.btc_final}`);
}

import { subscribeBlocks, toHex } from '@ksana/sdk';

const sub = subscribeBlocks(
  'wss://signet.ksana.network/rpc',
  (block) => {
    console.log(`block ${block.height} ${toHex(block.hash)}, ${block.entries} entries`);
    sub.close(); // one block is enough for this example
  },
  { onError: (error) => console.error('subscription:', error.message) },
);

import {
  KsanaRpcClient,
  equalBytes,
  formatOpPosition,
  ksaAssetId,
  parseAccount,
  toHex,
} from '@ksana/sdk';

const rpc = new KsanaRpcClient('https://signet.ksana.network/rpc', { timeoutMs: 30_000 });
const address = 'tb1p6z9g9hz82q62tuvtkkymaq6rguhx0xttsvrkfzyme0k39cj9zzlsk7pwe9';
const account = parseAccount(address, 'signet');

const info = await rpc.getAccount(account);
const ksa = info.balances.find((b) => equalBytes(b.asset, ksaAssetId()))?.amount ?? 0n;
console.log(`nonce ${info.nonce}, ${ksa} base units of KSA, at block ${info.at.height}`);

// The account's ops, newest first: pass `next` as `before` for the next page
const page = await rpc.getAccountOps(account, { limit: 3 });
for (const op of page.ops) console.log(`${op.status} at ${op.block.height}: ${toHex(op.op_id)}`);
console.log('next', page.next === null ? null : formatOpPosition(page.next));

import { type ByteReader, concatBytes, sha256, u32le, u64le, utf8 } from '@ksana/sdk';

/** A deployed contract's ID: sha256(deployer, the deploy op's nonce as u64 LE, sha256(code)). */
export function contractId(deployer: Uint8Array, nonce: bigint, code: Uint8Array): Uint8Array {
  return sha256(concatBytes(deployer, u64le(nonce), sha256(code)));
}

/** Borsh u128: 16 bytes, little-endian. */
export function u128le(value: bigint): Uint8Array {
  if (value < 0n || value >= 1n << 128n) throw new RangeError(`not a u128: ${value}`);
  const out = new Uint8Array(16);
  for (let i = 0; i < 16; i++) out[i] = Number((value >> BigInt(8 * i)) & 0xffn);
  return out;
}

/** Borsh String: the UTF-8 length as u32 LE, then the bytes. */
export function borshString(text: string): Uint8Array {
  const bytes = utf8(text);
  return concatBytes(u32le(bytes.length), bytes);
}

/** Borsh Vec<u8>: the length as u32 LE, then the bytes (not the SDK's varBytes). */
export function borshBytes(bytes: Uint8Array): Uint8Array {
  return concatBytes(u32le(bytes.length), bytes);
}

/** Reads a Borsh u128. */
export function readU128(reader: ByteReader): bigint {
  const bytes = reader.read(16);
  let value = 0n;
  for (let i = 15; i >= 0; i--) value = (value << 8n) | BigInt(bytes[i] ?? 0);
  return value;
}

import {
  ByteReader,
  KsanaRpcClient,
  type Receipt,
  concatBytes,
  fromHex,
  ksaAssetId,
} from '@ksana/sdk';
import { readU128, u128le } from './borsh.js';

const rpc = new KsanaRpcClient('https://signet.ksana.network/rpc', { timeoutMs: 30_000 });
const pool = fromHex('2d6e5edc46352b2931657479fce65fdbf01aafc5acc3de7c27660ce19dda8171', 32);
const me = fromHex('d08a82dc475034a5f18bb589be8343472e67996b830764889bcbed12e24510bf', 32);

/** The output of a successful call; a revert or any other failure throws. */
function output(receipt: Receipt): ByteReader {
  if (!receipt.success) throw new Error(receipt.error ?? 'the call failed');
  return new ByteReader(receipt.output, 'output');
}

// reserves() -> (u128, u128): no arguments, so empty bytes
const noArgs = new Uint8Array(0);
const reserves = output(await rpc.call({ contract: pool, method: 'reserves', args: noArgs }));
const [tut, ksa] = [readU128(reserves), readU128(reserves)];
reserves.finish(); // throws if bytes are left over
console.log(`reserves: ${tut} TUT, ${ksa} KSA (base units)`);

// swap(id_in, amount_in, min_out) -> u128, simulated as `me` with 1 KSA attached
const amountIn = 100_000_000n;
const quote = await rpc.call({
  contract: pool,
  method: 'swap',
  args: concatBytes(ksaAssetId(), u128le(amountIn), u128le(1n)),
  funds: [{ asset: ksaAssetId(), amount: amountIn }],
  caller: me,
});
console.log(`1 KSA buys ${readU128(output(quote))} TUT base units; gas ${quote.gas_used}`);

import {
  type KsanaRpcClient,
  type Params,
  type UnsignedVmOp,
  type Utxo,
  VMOP_VERSION,
  type WalletAdapter,
  buildNativeTx,
  extractTransaction,
  ksaAssetId,
  nativeFirstInput,
  opId,
  signVmopWithWallet,
} from '@ksana/sdk';

/**
 * Builds a path C KSA transfer: the op rides in a Bitcoin transaction that the wallet signs and
 * pays for. Returns the raw transaction to broadcast and the op's ID.
 */
export async function nativeTransfer(
  rpc: KsanaRpcClient,
  params: Params,
  wallet: WalletAdapter,
  account: Uint8Array,
  utxos: Utxo[], // the account's confirmed coins
  to: Uint8Array,
  amount: bigint,
  feeRate: number, // sat/vB
): Promise<{ raw: Uint8Array; opId: Uint8Array }> {
  const first = utxos[0];
  if (first === undefined) throw new Error('no coins to pay the Bitcoin fee');
  const unsigned: UnsignedVmOp = {
    version: VMOP_VERSION,
    chain_id: params.chain_id,
    account,
    nonce: (await rpc.getAccount(account)).nonce, // plus your path C ops still waiting
    fee: { kind: 'BtcNative' }, // no KSA fee: the Bitcoin transaction pays
    max_gas: 10_000n, // at most params.native_max_gas
    action: { kind: 'AssetTransfer', asset: ksaAssetId(), to, amount },
  };
  // The signature covers the transaction's first input, so choose that coin before signing.
  const op = await signVmopWithWallet(unsigned, wallet, { firstInput: nativeFirstInput(first) });
  const draft = buildNativeTx({ op, utxos, changeScript: first.script, feeRate, params });
  const signed = await wallet.signPsbt(draft.psbt, draft.inputs.map((_, index) => ({ index })));
  return { raw: extractTransaction(signed), opId: opId(op) };
}

import {
  type KsanaRpcClient,
  SIGNET,
  type Utxo,
  type WalletAdapter,
  buildTopUp,
  extractTransaction,
  fromHex,
  getLock,
  p2trScriptFromOutputKey,
  quoteTopUp,
} from '@ksana/sdk';

/**
 * Buys all the KSA that lock `lockId` of a ksa-exchange contract still holds, for the wallet's
 * own account. Returns the raw transaction to broadcast, the claim op's ID, and the Bitcoin
 * height the transaction must confirm by.
 */
export async function topUp(
  rpc: KsanaRpcClient,
  wallet: WalletAdapter,
  utxos: Utxo[], // the wallet's confirmed coins
  exchange: Uint8Array,
  lockId: bigint,
  btcHeight: number, // the Bitcoin tip, for the expiry check
  feeRate: number, // sat/vB
): Promise<{ raw: Uint8Array; opId: Uint8Array; payBy: number }> {
  const params = await rpc.getParams(SIGNET);
  const buyer = fromHex((await wallet.getAccount()).account, 32);
  const lock = await getLock(rpc, exchange, lockId);
  const { satsForAll } = quoteTopUp(lock, 0n); // the sats that buy everything still locked
  const draft = buildTopUp({
    exchange,
    lockId,
    lock,
    beneficiary: buyer, // refused unless it is the lock's beneficiary
    sats: satsForAll,
    currentBtcHeight: btcHeight,
    utxos,
    changeScript: p2trScriptFromOutputKey(buyer),
    feeRate,
    params,
  });
  const signed = await wallet.signPsbt(draft.psbt, draft.inputs.map((_, index) => ({ index })));
  return { raw: extractTransaction(signed), opId: draft.opId, payBy: draft.payBy };
}

import { IndexerRpcClient, KsanaRpcClient, equalBytes } from '@ksana/sdk';

const rpc = new KsanaRpcClient('https://signet.ksana.network/rpc', { timeoutMs: 30_000 });
const indexer = new IndexerRpcClient('https://signet.ksana.network/indexer', {
  timeoutMs: 30_000,
});

// The indexer rebuilds the state from Bitcoin alone; compare its state root with the node's block.
const status = await indexer.status();
const { header } = await rpc.getBlock(status.height);
console.log(`indexer at ${status.height}, Bitcoin ${status.btc_height}, halted ${status.halted}`);
console.log('same state root as the node:', equalBytes(status.state_root, header.state_root));

import {
  ChainMismatchError,
  KsanaRpcClient,
  MAINNET,
  RPC_ERROR_CODES,
  RpcError,
} from '@ksana/sdk';

const rpc = new KsanaRpcClient('https://signet.ksana.network/rpc', { timeoutMs: 30_000 });

try {
  await rpc.getOpStatus(new Uint8Array(32)); // no op has this ID
} catch (e) {
  if (!(e instanceof RpcError) || e.code !== RPC_ERROR_CODES.NOT_FOUND) throw e;
  console.log(e.code, e.message);
}

try {
  await rpc.getParams(MAINNET); // the node is on the signet
} catch (e) {
  if (!(e instanceof ChainMismatchError)) throw e;
  console.log(e.chainId, e.expected, e.message.split(':')[0]);
}