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 });
// 签名要用的参数。节点若在别的网络上，这里会抛出 ChainMismatchError。
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';

/** 一把新私钥：32 个随机字节，且是一把有效的 secp256k1 密钥。 */
export function newSecretKey(): Uint8Array {
  for (;;) {
    const key = randomBytes(32);
    if (isValidSecretKey(key)) return key;
  }
}

/** 读取 ksana-cli 或 ksana-keytool 的密钥文件：64 位十六进制的私钥。 */
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 字节：Taproot 输出公钥
const address = accountToAddress(account, 'signet');
console.log(toHex(account));
console.log(address);
// parseAccount 接受 64 位十六进制，或给定网络上的 Taproot 地址
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';

/** 走路径 B 把 `amount` 个最小单位的 KSA 发给 `to`，返回操作 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; // 一笔 KSA 转账正好用 10,000 gas
  const unsigned: UnsignedVmOp = {
    version: VMOP_VERSION,
    chain_id: params.chain_id,
    account,
    nonce, // 账户的下一个 nonce
    fee: { kind: 'Token', amount: estimate.path_b.amount },
    max_gas: maxGas,
    action: { kind: 'AssetTransfer', asset: ksaAssetId(), to, amount },
  };
  // 建议费率按操作成本每 KiB 计：先量出签好名的操作有多大，再签上真正的手续费。
  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 或 -32011
  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 });

/** 连接 Unisat 或 Xverse，检查它所在的网络，返回它的 Ksana 账户。 */
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);
  // 光凭 tb1 地址分不清 signet 和 testnet：要问钱包，而钱包未必知道。
  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(); // 地址不是 Taproot 就抛出异常
  return { wallet, address, account: fromHex(account, 32) };
}

/** 走路径 B 发送 KSA：钱包签一条消息，不动用任何比特币。返回操作 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 },
  };
  // 钱包的签名编码后最多 67 字节：这样不必让钱包签两次，就能算出操作的大小。
  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 } };
  // 钱包会显示一条待签的消息：写成十六进制的操作签名哈希。
  const op = await signVmopWithWallet(final, wallet);
  return (await rpc.submitOp(op)).op_id;
}

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

/** 每秒轮询一次操作，直到它执行完毕或已最终，或者过了 `timeoutMs`。 */
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
    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(); // 这个例子有一个区块就够了
  },
  { 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}`);

// 账户的操作，最新的在前：把 `next` 作为 `before` 传入，就能取下一页
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';

/** 已部署合约的 ID：把 deployer、部署操作的 nonce（u64 LE）和 sha256(code) 连在一起，再取 sha256。 */
export function contractId(deployer: Uint8Array, nonce: bigint, code: Uint8Array): Uint8Array {
  return sha256(concatBytes(deployer, u64le(nonce), sha256(code)));
}

/** Borsh u128：16 字节，小端。 */
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：先是 UTF-8 编码的长度（u32 LE），再是这些字节。 */
export function borshString(text: string): Uint8Array {
  const bytes = utf8(text);
  return concatBytes(u32le(bytes.length), bytes);
}

/** Borsh Vec<u8>：先是长度（u32 LE），再是这些字节（不同于 SDK 的 varBytes）。 */
export function borshBytes(bytes: Uint8Array): Uint8Array {
  return concatBytes(u32le(bytes.length), bytes);
}

/** 读取一个 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);

/** 成功调用的输出；revert 或其他任何失败都会抛出异常。 */
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)：没有参数，所以是空字节
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(); // 有剩余字节时抛出异常
console.log(`reserves: ${tut} TUT, ${ksa} KSA (base units)`);

// swap(id_in, amount_in, min_out) -> u128，以 `me` 的身份模拟，附带 1 KSA
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';

/**
 * 构建一笔路径 C 的 KSA 转账：操作搭载在一笔比特币交易里，由钱包签名并付费。
 * 返回待广播的原始交易和操作 ID。
 */
export async function nativeTransfer(
  rpc: KsanaRpcClient,
  params: Params,
  wallet: WalletAdapter,
  account: Uint8Array,
  utxos: Utxo[], // 账户已确认的币
  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, // 还要加上你仍在等待的路径 C 操作笔数
    fee: { kind: 'BtcNative' }, // 不付 KSA 手续费：由比特币交易付费
    max_gas: 10_000n, // 最多 params.native_max_gas
    action: { kind: 'AssetTransfer', asset: ksaAssetId(), to, amount },
  };
  // 签名覆盖交易的第一个输入，所以要在签名之前选定这枚币。
  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';

/**
 * 为钱包自己的账户，买下 ksa-exchange 合约中锁定 `lockId` 仍持有的全部 KSA。
 * 返回待广播的原始交易、领取操作的 ID，以及这笔交易最晚要在哪个比特币高度确认。
 */
export async function topUp(
  rpc: KsanaRpcClient,
  wallet: WalletAdapter,
  utxos: Utxo[], // 钱包已确认的币
  exchange: Uint8Array,
  lockId: bigint,
  btcHeight: number, // 比特币链顶的高度，用于检查到期
  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); // 买下仍锁定的全部 KSA 所需的聪数
  const draft = buildTopUp({
    exchange,
    lockId,
    lock,
    beneficiary: buyer, // 不是锁定的受益账户就会被拒绝
    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,
});

// 索引器只凭比特币重建状态；拿它的状态根与节点的区块比对。
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)); // 没有哪笔操作的 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); // 节点在 signet 上
} catch (e) {
  if (!(e instanceof ChainMismatchError)) throw e;
  console.log(e.chainId, e.expected, e.message.split(':')[0]);
}