@nervosnetwork/fiber-js 0.5.1

package/src/index.ts

@@ -0,0 +1,193 @@
+
+import DbWorker from "./db.worker.ts";
+import FiberWorker from "./fiber.worker.ts";
+import { Mutex } from "async-mutex";
+import { DbWorkerInitializationOptions, FiberInvokeRequest, FiberInvokeResponse, FiberWorkerInitializationOptions } from "./types/general.ts";
+import { AbandonChannelParams, AcceptChannelParams, AcceptChannelResult, ListChannelsParams, ListChannelsResult, OpenChannelParams, OpenChannelResult, ShutdownChannelParams, UpdateChannelParams } from "./types/channel.ts";
+import { GraphChannelsParams, GraphChannelsResult, GraphNodesParams, GraphNodesResult } from "./types/graph.ts";
+import { NodeInfoResult } from "./types/info.ts";
+import { GetInvoiceResult, InvoiceParams, InvoiceResult, NewInvoiceParams, ParseInvoiceParams, ParseInvoiceResult } from "./types/invoice.ts";
+import { BuildPaymentRouterResult, BuildRouterParams, GetPaymentCommandParams, GetPaymentCommandResult, SendPaymentCommandParams, SendPaymentWithRouterParams } from "./types/payment.ts";
+import { ConnectPeerParams, DisconnectPeerParams, ListPeerResult } from "./types/peer.ts";
+
+const DEFAULT_BUFFER_SIZE = 50 * (1 << 20);
+/**
+ * A Fiber Wasm instance
+ */
+class Fiber {
+    private dbWorker: Worker | null
+    private fiberWorker: Worker | null
+    private inputBuffer: SharedArrayBuffer
+    private outputBuffer: SharedArrayBuffer
+    private commandInvokeLock: Mutex;
+    /**
+     * Construct a Fiber Wasm instance.
+     * inputBuffer and outputBuffer are buffers used for transporting data between database and fiber wasm. Set them to appropriate sizes.
+     * @param inputBufferSize Size of inputBuffer
+     * @param outputBufferSize Size of outputBuffer
+     */
+    constructor(inputBufferSize = DEFAULT_BUFFER_SIZE, outputBufferSize = DEFAULT_BUFFER_SIZE) {
+        this.dbWorker = new DbWorker();
+        this.fiberWorker = new FiberWorker();
+        this.inputBuffer = new SharedArrayBuffer(inputBufferSize);
+        this.outputBuffer = new SharedArrayBuffer(outputBufferSize);
+        this.commandInvokeLock = new Mutex();
+    }
+
+    /**
+     * Start the Fiber Wasm instance.
+     * @param config Config file for fiber
+     * @param fiberKeyPair keypair used for fiber
+     * @param ckbSecretKey secret key for CKB
+     * @param chainSpec Chain spec if chain is neither testnet nor mainnet
+     * @param logLevel log level, such as `trace`, `debug`, `info`, `error`
+     * @param databasePrefix Name prefix of IndexedDB store. Defaults to `/wasm`
+     * 
+     */
+    async start(
+        config: string,
+        fiberKeyPair: Uint8Array,
+        ckbSecretKey: Uint8Array,
+        chainSpec?: string,
+        logLevel: "trace" | "debug" | "info" | "error" = "info",
+        databasePrefix?: string) {
+        this.dbWorker.postMessage({
+            inputBuffer: this.inputBuffer,
+            outputBuffer: this.outputBuffer,
+            logLevel: logLevel
+        } as DbWorkerInitializationOptions);
+        this.fiberWorker.postMessage({
+            inputBuffer: this.inputBuffer,
+            outputBuffer: this.outputBuffer,
+            ckbSecretKey,
+            config,
+            fiberKeyPair,
+            logLevel,
+            chainSpec,
+            databasePrefix
+        } as FiberWorkerInitializationOptions);
+        await new Promise<void>((res, rej) => {
+            this.dbWorker.onmessage = () => res();
+            this.dbWorker.onerror = (evt) => rej(evt);
+        });
+        await new Promise<void>((res, rej) => {
+            this.fiberWorker.onmessage = () => res();
+            this.fiberWorker.onerror = (evt) => rej(evt);
+        });
+
+    }
+    invokeCommand(name: string, args?: any[]): Promise<any> {
+        // Why use lock here?
+        // fiber-wasm provided async APIs. Use lock here to avoid mixture of different calls
+        return this.commandInvokeLock.runExclusive(async () => {
+            this.fiberWorker.postMessage({
+                name,
+                args: args || []
+            } as FiberInvokeRequest);
+            return await new Promise((resolve, reject) => {
+                const clean = () => {
+                    this.fiberWorker.removeEventListener("message", resolveFn);
+                    this.fiberWorker.removeEventListener("error", errorFn);
+                }
+                const resolveFn = (evt: MessageEvent<FiberInvokeResponse>) => {
+                    if (evt.data.ok === true) {
+                        resolve(evt.data.data);
+                    } else {
+                        reject(evt.data.error);
+                    }
+                    clean();
+
+                };
+                const errorFn = (evt: ErrorEvent) => {
+                    reject(evt);
+                    clean();
+
+                };
+                this.fiberWorker.addEventListener("message", resolveFn);
+                this.fiberWorker.addEventListener("error", errorFn);
+            })
+        })
+
+    }
+    /**
+     * Stop the fiber instance.
+     */
+    async stop() {
+        this.dbWorker.terminate();
+        this.fiberWorker.terminate();
+    }
+    async openChannel(params: OpenChannelParams): Promise<OpenChannelResult> {
+        return await this.invokeCommand("open_channel", [params]);
+    }
+    async acceptChannel(params: AcceptChannelParams): Promise<AcceptChannelResult> {
+        return await this.invokeCommand("accept_channel", [params]);
+    }
+    async abandonChannel(params: AbandonChannelParams): Promise<void> {
+        await this.invokeCommand("abandon_channel", [params]);
+    }
+    async listChannels(params: ListChannelsParams): Promise<ListChannelsResult> {
+        return await this.invokeCommand("list_channels", [params]);
+    }
+    async shutdownChannel(params: ShutdownChannelParams): Promise<void> {
+        await this.invokeCommand("shutdown_channel", [params]);
+    }
+    async updateChannel(params: UpdateChannelParams): Promise<void> {
+        await this.invokeCommand("update_channel", [params]);
+    }
+    async graphNodes(params: GraphNodesParams): Promise<GraphNodesResult> {
+        return await this.invokeCommand("graph_nodes", [params]);
+    }
+    async graphChannels(params: GraphChannelsParams): Promise<GraphChannelsResult> {
+        return await this.invokeCommand("graph_channels", [params]);
+    }
+    async nodeInfo(): Promise<NodeInfoResult> {
+        return await this.invokeCommand("node_info");
+    }
+    async newInvoice(params: NewInvoiceParams): Promise<InvoiceResult> {
+        return await this.invokeCommand("new_invoice", [params]);
+    }
+    async parseInvoice(params: ParseInvoiceParams): Promise<ParseInvoiceResult> {
+        return await this.invokeCommand("parse_invoice", [params]);
+    }
+    async getInvoice(params: InvoiceParams): Promise<GetInvoiceResult> {
+        return await this.invokeCommand("get_invoice", [params]);
+    }
+    async cancelInvoice(params: InvoiceParams): Promise<GetInvoiceResult> {
+        return await this.invokeCommand("cancel_invoice", [params]);
+    }
+    async sendPayment(params: SendPaymentCommandParams): Promise<GetPaymentCommandResult> {
+        return await this.invokeCommand("send_payment", [params]);
+    }
+    async getPayment(params: GetPaymentCommandParams): Promise<GetPaymentCommandResult> {
+        return await this.invokeCommand("get_payment", [params]);
+    }
+    async buildRouter(params: BuildRouterParams): Promise<BuildPaymentRouterResult> {
+        return await this.invokeCommand("build_router", [params]);
+    }
+    async sendPaymentWithRouter(params: SendPaymentWithRouterParams): Promise<GetPaymentCommandResult> {
+        return await this.invokeCommand("send_payment_with_router", [params]);
+    }
+    async connectPeer(params: ConnectPeerParams): Promise<void> {
+        await this.invokeCommand("connect_peer", [params]);
+    }
+    async disconnectPeer(params: DisconnectPeerParams): Promise<void> {
+        await this.invokeCommand("disconnect_peer", [params]);
+    }
+    async listPeers(): Promise<ListPeerResult> {
+        return await this.invokeCommand("list_peers");
+    }
+}
+
+export { Fiber };
+
+/**
+ * Generate a random 32-byte secret key.
+ * @returns The secret key.
+ */
+export function randomSecretKey(): Uint8Array {
+    const arr = new Uint8Array(32);
+    crypto.getRandomValues(arr);
+    return arr;
+}
+
+export * from "./types/general.ts";

package/src/types/channel.ts

@@ -0,0 +1,100 @@
+import { HexString } from "./general";
+
+interface Script {
+    code_hash: HexString;
+    hash_type: "data" | "type" | "data1" | "data2";
+    args: string;
+}
+
+interface OpenChannelParams {
+    peer_id: string;
+    funding_amount: HexString;
+    public?: boolean;
+    funding_udt_type_script?: Script;
+    shutdown_script?: Script;
+    commitment_delay_epoch?: HexString;
+    commitment_fee_rate?: HexString;
+    funding_fee_rate?: HexString;
+    tlc_expiry_delta?: HexString;
+    tlc_min_value?: HexString;
+    tlc_fee_proportional_millionths?: HexString;
+    max_tlc_value_in_flight?: HexString;
+    max_tlc_number_in_flight?: HexString;
+}
+interface OpenChannelResult {
+    temporary_channel_id: HexString;
+}
+interface AbandonChannelParams {
+    channel_id: HexString;
+}
+interface AcceptChannelParams {
+    temporary_channel_id: HexString;
+    funding_amount: HexString;
+    shutdown_script?: Script;
+    max_tlc_value_in_flight?: HexString;
+    max_tlc_number_in_flight?: HexString;
+    tlc_min_value?: HexString;
+    tlc_fee_proportional_millionths?: HexString;
+    tlc_expiry_delta?: HexString;
+}
+interface AcceptChannelResult {
+    channel_id: HexString;
+}
+interface ListChannelsParams {
+    peer_id?: string;
+    include_closed?: boolean;
+}
+
+interface ChannelState {
+    state_name: string;
+    state_flags: string;
+}
+interface Channel {
+    channel_id: HexString;
+    is_public: boolean;
+    channel_outpoint: HexString;
+    peer_id: HexString;
+    funding_udt_type_script?: Script;
+    state: ChannelState;
+    local_balance: HexString;
+    offered_tlc_balance: HexString;
+    remote_balance: HexString;
+    received_tlc_balance: HexString;
+    latest_commitment_transaction_hash?: HexString;
+    created_at: HexString;
+    enabled: boolean;
+    tlc_expiry_delta: HexString;
+    tlc_fee_proportional_millionths: HexString;
+}
+
+interface ShutdownChannelParams {
+    channel_id: HexString;
+    close_script?: Script;
+    fee_rate?: HexString;
+    force?: boolean;
+}
+
+interface UpdateChannelParams {
+    channel_id: HexString;
+    enabled?: boolean;
+    tlc_expiry_delta?: HexString;
+    tlc_minimum_value?: HexString;
+    tlc_fee_proportional_millionths?: HexString;
+}
+interface ListChannelsResult {
+    channels: Channel[];
+}
+export type {
+    OpenChannelParams,
+    Script,
+    OpenChannelResult,
+    AbandonChannelParams,
+    AcceptChannelParams,
+    AcceptChannelResult,
+    ListChannelsParams,
+    Channel,
+    ChannelState,
+    ShutdownChannelParams,
+    UpdateChannelParams,
+    ListChannelsResult
+}

package/src/types/general.ts

@@ -0,0 +1,34 @@
+interface DbWorkerInitializationOptions {
+    inputBuffer: SharedArrayBuffer;
+    outputBuffer: SharedArrayBuffer;
+    logLevel: string;
+}
+interface FiberWorkerInitializationOptions {
+    inputBuffer: SharedArrayBuffer;
+    outputBuffer: SharedArrayBuffer;
+    logLevel: string;
+    fiberKeyPair: Uint8Array;
+    ckbSecretKey: Uint8Array;
+    config: string;
+    chainSpec?: string;
+    databasePrefix?: string;
+}
+
+interface FiberInvokeRequest {
+    name: string;
+    args: any[];
+};
+type FiberInvokeResponse = { ok: true; data: any; } | { ok: false; error: string };
+
+type HexString = `0x${string}`;
+
+type HashAlgorithm = "ckb_hash" | "sha_256";
+
+export type {
+    DbWorkerInitializationOptions,
+    FiberWorkerInitializationOptions,
+    FiberInvokeRequest,
+    FiberInvokeResponse,
+    HexString,
+    HashAlgorithm
+}

package/src/types/graph.ts

@@ -0,0 +1,101 @@
+import { Script } from "./channel";
+import { HexString } from "./general"
+
+interface GraphNodesParams {
+    limit?: HexString;
+    after?: HexString;
+}
+type UdtScript = Script;
+type DepType = "code" | "dep_group";
+
+interface UdtCellDep {
+    out_point: OutPoint;
+    dep_type: DepType;
+}
+
+interface OutPoint {
+    tx_hash: HexString;
+    index: HexString;
+}
+
+interface UdtDep {
+    cell_dep?: UdtCellDep;
+    type_id?: Script;
+}
+
+interface UdtCellDep {
+    out_point: OutPoint;
+    dep_type: DepType;
+}
+
+interface UdtArgInfo {
+    name: string;
+    script: UdtScript;
+    auto_accept_amount?: HexString;
+    cell_deps: UdtDep[];
+}
+type UdtCfgInfos = UdtArgInfo[];
+
+interface NodeInfo {
+    node_name: string;
+    addresses: string[];
+    node_id: HexString;
+    timestamp: HexString;
+    chain_hash: HexString;
+    auto_accept_min_ckb_funding_amount: HexString;
+    udt_cfg_infos: UdtCfgInfos;
+}
+
+interface GraphNodesResult {
+    nodes: NodeInfo[];
+    last_cursor: HexString;
+}
+interface GraphChannelsParams {
+    limit?: HexString;
+    after?: HexString;
+}
+
+interface ChannelUpdateInfo {
+    timestamp: HexString;
+    enabled: boolean;
+    outbound_liquidity?: HexString;
+    tlc_expiry_delta: HexString;
+    tlc_minimum_value: HexString;
+    fee_rate: HexString;
+}
+
+interface ChannelInfo {
+    channel_outpoint: HexString;
+    node1: HexString;
+    node2: HexString;
+    created_timestamp: HexString;
+    update_info_of_node1?: ChannelUpdateInfo;
+    update_info_of_node2?: ChannelUpdateInfo;
+    capacity: HexString;
+    chain_hash: HexString;
+    udt_type_script?: Script;
+
+}
+interface GraphChannelsResult {
+    channels: ChannelInfo[];
+    last_cursor: HexString;
+}
+export type {
+    GraphNodesParams,
+    GraphNodesResult,
+    GraphChannelsParams,
+    GraphChannelsResult,
+    ChannelInfo,
+    ChannelUpdateInfo,
+    DepType,
+    HexString,
+    NodeInfo,
+    OutPoint,
+    Script,
+    UdtCellDep,
+    UdtArgInfo,
+    UdtCfgInfos,
+    UdtDep,
+    UdtScript,
+
+}

package/src/types/info.ts

@@ -0,0 +1,25 @@
+import { Script } from "./channel";
+import { HexString } from "./general";
+import { UdtCfgInfos } from "./graph";
+
+interface NodeInfoResult {
+    version: string;
+    commit_hash: string;
+    node_id: string;
+    node_name?: string;
+    addresses: string[];
+    chain_hash: HexString;
+    open_channel_auto_accept_min_ckb_funding_amount: HexString;
+    auto_accept_channel_ckb_funding_amount: HexString;
+    default_funding_lock_script: Script;
+    tlc_expiry_delta: HexString;
+    tlc_min_value: HexString;
+    tlc_fee_proportional_millionths: HexString;
+    channel_count: HexString;
+    pending_channel_count: HexString;
+    peers_count: HexString;
+    udt_cfg_infos: UdtCfgInfos;
+}
+
+
+export type { NodeInfoResult }

package/src/types/invoice.ts

@@ -0,0 +1,75 @@
+import { Script } from "./channel";
+import { HashAlgorithm, HexString } from "./general"
+
+type Currency = "Fibb" | "Fibt" | "Fibd";
+type CkbInvoiceStatus = "Open" | "Cancelled" | "Expired" | "Received" | "Paid";
+interface NewInvoiceParams {
+    amount: HexString;
+    description?: string;
+    currency: Currency;
+    payment_preimage: HexString;
+    expiry?: HexString;
+    fallback_address?: string;
+    final_expiry_delta?: HexString;
+    udt_type_script?: Script;
+    hash_algorithm?: HashAlgorithm;
+}
+type CkbScript = HexString;
+type Attribute = { FinalHtlcTimeout: HexString } |
+{ FinalHtlcMinimumExpiryDelta: HexString } |
+{ ExpiryTime: HexString } |
+{ Description: string } |
+{ FallbackAddr: string } |
+{ UdtScript: CkbScript } |
+{ PayeePublicKey: string } |
+{ HashAlgorithm: number } |
+{ Feature: HexString };
+
+
+interface InvoiceData {
+    timestamp: HexString;
+    payment_hash: HexString;
+    attrs: Attribute[];
+}
+interface CkbInvoice {
+    currency: Currency;
+    amount?: HexString;
+    signature?: string;
+    data: InvoiceData;
+}
+
+interface InvoiceResult {
+    invoice_address: string;
+    invoice: CkbInvoice;
+}
+
+interface ParseInvoiceParams {
+    invoice: string;
+}
+interface ParseInvoiceResult {
+    invoice: CkbInvoice;
+}
+interface InvoiceParams {
+    payment_hash: HexString;
+}
+
+interface GetInvoiceResult {
+    invoice_address: string;
+    invoice: CkbInvoice;
+    status: CkbInvoiceStatus;
+}
+
+export type {
+    NewInvoiceParams,
+    InvoiceResult,
+    Attribute,
+    CkbInvoice,
+    CkbInvoiceStatus,
+    CkbScript,
+    Currency,
+    GetInvoiceResult,
+    InvoiceData,
+    InvoiceParams,
+    ParseInvoiceParams,
+    ParseInvoiceResult
+}

package/src/types/payment.ts

@@ -0,0 +1,91 @@
+import { Script } from "./channel";
+import { HexString } from "./general"
+type PaymentSessionStatus = "Created" | "Inflight" | "Success" | "Failed";
+
+interface PaymentCustomRecords {
+    [k: HexString]: HexString;
+}
+interface SessionRouteNode {
+    pubkey: string;
+    amount: HexString;
+    channel_outpoint: HexString;
+}
+interface GetPaymentCommandResult {
+    payment_hash: HexString;
+    status: PaymentSessionStatus;
+    created_at: HexString;
+    last_updated_at: HexString;
+    failed_error?: string;
+    fee: HexString;
+    custom_records?: PaymentCustomRecords;
+    /// Only available in debug mode
+    router?: SessionRouteNode[];
+}
+interface HopHint {
+    pubkey: string;
+    channel_outpoint: HexString;
+    fee_rate: HexString;
+    tlc_expiry_delta: HexString;
+}
+interface HopRequire {
+    pubkey: string;
+    channel_outpoint: HexString;
+}
+interface RouterHop {
+    target: HexString;
+    channel_outpoint: HexString;
+    amount_received: HexString;
+    incoming_tlc_expiry: HexString;
+}
+interface GetPaymentCommandParams {
+    payment_hash: HexString;
+}
+interface SendPaymentCommandParams {
+    target_pubkey?: string;
+    amount?: HexString;
+    payment_hash?: HexString;
+    final_tlc_expiry_delta?: HexString;
+    tlc_expiry_limit?: HexString;
+    invoice?: string;
+    timeout?: HexString;
+    max_fee_amount?: HexString;
+    max_parts?: HexString;
+    keysend?: boolean;
+    udt_type_script?: Script;
+    allow_self_payment?: boolean;
+    custom_records?: PaymentCustomRecords;
+    hop_hints?: HopHint[];
+    dry_run?: boolean;
+}
+interface BuildRouterParams {
+    amount?: HexString;
+    udt_type_script?: Script;
+    hops_info: HopRequire[];
+    final_tlc_expiry_delta?: HexString;
+}
+interface BuildPaymentRouterResult {
+    router_hops: RouterHop[];
+}
+interface SendPaymentWithRouterParams {
+    payment_hash?: HexString;
+    router: RouterHop[];
+    invoice?: string;
+    custom_records?: PaymentCustomRecords;
+    keysend?: boolean;
+    udt_type_script?: Script;
+    dry_run?: boolean;
+}
+export type {
+    GetPaymentCommandResult,
+    BuildPaymentRouterResult,
+    BuildRouterParams,
+    HopHint,
+    HopRequire,
+    PaymentCustomRecords,
+    PaymentSessionStatus,
+    RouterHop,
+    SendPaymentCommandParams,
+    SendPaymentWithRouterParams,
+    SessionRouteNode,
+    GetPaymentCommandParams
+}

package/src/types/peer.ts

@@ -0,0 +1,29 @@
+import { HexString } from "./general"
+
+interface ConnectPeerParams {
+    address: string;
+    save?: boolean;
+
+}
+
+interface DisconnectPeerParams {
+    peer_id: string;
+}
+
+interface PeerInfo {
+    pubkey: string;
+    peer_id: string;
+    addresses: string[];
+}
+
+interface ListPeerResult {
+    peers: PeerInfo[];
+}
+
+
+export type {
+    ConnectPeerParams,
+    DisconnectPeerParams,
+    ListPeerResult,
+    PeerInfo
+ }

package/src/worker.d.ts

@@ -0,0 +1,13 @@
+declare module "*.worker.ts" {
+  class WebpackWorker extends Worker {
+    constructor();
+  }
+  export default WebpackWorker;
+}
+
+declare module "*.worker" {
+  class WebpackWorker extends Worker {
+    constructor();
+  }
+  export default WebpackWorker;
+}

package/tsconfig.json

@@ -0,0 +1,34 @@
+{
+  "compilerOptions": {
+    "outDir": "./dist/",
+    "noImplicitAny": true,
+    "module": "ESNext",
+    "target": "es2020",
+    "allowJs": true,
+    "mapRoot": "dist",
+    "sourceMap": true,
+    "declaration": true,
+    "declarationDir": "dist",
+    "rootDir": "src",
+    "declarationMap": true,
+    "typeRoots": [
+      "/src"
+    ],
+    "allowSyntheticDefaultImports": true,
+    "lib": [
+      "ES2024",
+      "WebWorker",
+      "ESNext"
+    ],
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "emitDeclarationOnly": true
+  },
+  "exclude": [
+    "webpack.config.js",
+    "dist/**",
+    "node_modules/**",
+    "jest.config.js",
+    "esbuild.config.*"
+  ]
+}