@fiber-pay/sdk 0.1.0-rc.1

package/dist/browser.d.ts

@@ -0,0 +1,895 @@
+import { z } from 'zod';
+
+/**
+ * CKB Address Encoding (Bech32m)
+ * Encode CKB lock scripts to human-readable addresses
+ */
+interface Script$1 {
+    code_hash: string;
+    hash_type: 'type' | 'data' | 'data1' | 'data2';
+    args: string;
+}
+/**
+ * Convert a CKB lock script to a bech32m-encoded address
+ * @param script - The lock script to encode
+ * @param network - The CKB network ('testnet' or 'mainnet')
+ * @returns Bech32m-encoded CKB address
+ */
+declare function scriptToAddress(script: Script$1, network: 'testnet' | 'mainnet'): string;
+
+/**
+ * Fiber Network Node RPC Types (Fiber v0.6.1)
+ *
+ * The types in this file are intended to align with the upstream RPC spec:
+ * https://github.com/nervosnetwork/fiber/blob/v0.6.1/crates/fiber-lib/src/rpc/README.md
+ */
+/** Hex-encoded string (prefixed with 0x). The RPC serializes most numeric values as hex strings. */
+type HexString = `0x${string}`;
+/** A 256-bit hash digest (Hash256 in the RPC spec). */
+type Hash256 = HexString;
+/** Public key for a node (Pubkey in the RPC spec). */
+type Pubkey = HexString;
+/** Private key (Privkey in the RPC spec). */
+type Privkey = HexString;
+/** Peer ID in libp2p format. */
+type PeerId = string;
+/** Multiaddr format for network addresses. */
+type Multiaddr = string;
+/** Channel ID (Hash256). */
+type ChannelId = Hash256;
+/** Payment hash (Hash256). */
+type PaymentHash = Hash256;
+/** Script structure for CKB. */
+interface Script {
+    code_hash: HexString;
+    hash_type: 'type' | 'data' | 'data1' | 'data2';
+    args: HexString;
+}
+/** Transaction out point. */
+interface OutPoint {
+    tx_hash: Hash256;
+    index: HexString;
+}
+/** UDT (User Defined Token) script (UdtScript in the RPC spec). */
+type UdtScript = Script;
+type Currency = 'Fibb' | 'Fibt' | 'Fibd';
+type HashAlgorithm = 'CkbHash' | 'Sha256';
+/** Recoverable signature (InvoiceSignature in the RPC spec). */
+type InvoiceSignature = HexString;
+/**
+ * Invoice attribute types as returned by the RPC.
+ * Each attribute is an object with a single key indicating the attribute type.
+ */
+type Attribute = 
+/** Deprecated since v0.6.0, preserved for compatibility. */
+{
+    FinalHtlcTimeout: HexString;
+}
+/** Final TLC minimum expiry delta in milliseconds. */
+ | {
+    FinalHtlcMinimumExpiryDelta: HexString;
+}
+/** Invoice expiry time in seconds. */
+ | {
+    ExpiryTime: HexString;
+}
+/** Human-readable invoice description. */
+ | {
+    Description: string;
+}
+/** Fallback address for on-chain settlement. */
+ | {
+    FallbackAddr: string;
+}
+/** UDT script for token invoices. */
+ | {
+    UdtScript: UdtScript;
+}
+/** Payee public key. */
+ | {
+    PayeePublicKey: Pubkey;
+}
+/** Hash algorithm used in the payment hash lock. */
+ | {
+    HashAlgorithm: HashAlgorithm;
+}
+/** Feature flags list. */
+ | {
+    Feature: string[];
+}
+/** Payment secret. */
+ | {
+    PaymentSecret: Hash256;
+};
+interface InvoiceData {
+    timestamp: HexString;
+    payment_hash: PaymentHash;
+    attrs: Attribute[];
+}
+interface CkbInvoice {
+    currency: Currency;
+    amount?: HexString;
+    signature?: InvoiceSignature;
+    data: InvoiceData;
+}
+type CkbInvoiceStatus = 'Open' | 'Cancelled' | 'Expired' | 'Received' | 'Paid';
+declare enum ChannelState {
+    NegotiatingFunding = "NEGOTIATING_FUNDING",
+    CollaboratingFundingTx = "COLLABORATING_FUNDING_TX",
+    SigningCommitment = "SIGNING_COMMITMENT",
+    AwaitingTxSignatures = "AWAITING_TX_SIGNATURES",
+    AwaitingChannelReady = "AWAITING_CHANNEL_READY",
+    ChannelReady = "CHANNEL_READY",
+    ShuttingDown = "SHUTTING_DOWN",
+    Closed = "CLOSED"
+}
+/** Channel state flags are serialized as flag names by upstream RPC and may evolve. */
+type ChannelStateFlags = string[];
+/** TLC status. The upstream spec defines OutboundTlcStatus / InboundTlcStatus, which may evolve. */
+type TlcStatus = {
+    Outbound: unknown;
+} | {
+    Inbound: unknown;
+};
+interface Htlc {
+    id: HexString;
+    amount: HexString;
+    payment_hash: PaymentHash;
+    expiry: HexString;
+    forwarding_channel_id?: Hash256;
+    forwarding_tlc_id?: HexString;
+    status: TlcStatus;
+}
+interface Channel {
+    channel_id: ChannelId;
+    is_public: boolean;
+    channel_outpoint: OutPoint | null;
+    peer_id: PeerId;
+    funding_udt_type_script: Script | null;
+    state: {
+        state_name: ChannelState;
+        state_flags?: ChannelStateFlags;
+    };
+    local_balance: HexString;
+    offered_tlc_balance: HexString;
+    remote_balance: HexString;
+    received_tlc_balance: HexString;
+    pending_tlcs: Htlc[];
+    latest_commitment_transaction_hash: Hash256 | null;
+    created_at: HexString;
+    enabled: boolean;
+    tlc_expiry_delta: HexString;
+    tlc_fee_proportional_millionths: HexString;
+    shutdown_transaction_hash: Hash256 | null;
+}
+interface PeerInfo {
+    pubkey: Pubkey;
+    peer_id: PeerId;
+    address: Multiaddr;
+}
+type PaymentStatus = 'Created' | 'Inflight' | 'Success' | 'Failed';
+/**
+ * Custom records for payments.
+ *
+ * Keys are hex-encoded u32 values (e.g. `0x1`, range 0..=65535),
+ * values are hex-encoded byte arrays (0x-prefixed).
+ */
+type PaymentCustomRecords = Record<string, HexString>;
+interface SessionRouteNode {
+    pubkey: Pubkey;
+    amount: HexString;
+    channel_outpoint: OutPoint;
+}
+interface SessionRoute {
+    nodes: SessionRouteNode[];
+}
+interface PaymentInfo {
+    payment_hash: PaymentHash;
+    status: PaymentStatus;
+    created_at: HexString;
+    last_updated_at: HexString;
+    failed_error?: string;
+    fee: HexString;
+    custom_records?: PaymentCustomRecords;
+    routers?: SessionRoute[];
+}
+interface HopHint {
+    pubkey: Pubkey;
+    channel_outpoint: OutPoint;
+    fee_rate: HexString;
+    tlc_expiry_delta: HexString;
+}
+interface UdtCellDep {
+    out_point: OutPoint;
+    dep_type: 'code' | 'dep_group';
+}
+interface UdtDep {
+    cell_dep?: UdtCellDep | null;
+    type_id?: Script | null;
+}
+interface UdtArgInfo {
+    name: string;
+    script: UdtScript;
+    auto_accept_amount?: HexString;
+    cell_deps: UdtDep[];
+}
+type UdtCfgInfos = UdtArgInfo[];
+interface NodeInfo {
+    version: string;
+    commit_hash: string;
+    node_id: Pubkey;
+    features: string[];
+    node_name: string | null;
+    addresses: Multiaddr[];
+    chain_hash: Hash256;
+    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;
+}
+interface ChannelUpdateInfo {
+    timestamp: HexString;
+    enabled: boolean;
+    outbound_liquidity?: HexString;
+    tlc_expiry_delta: HexString;
+    tlc_minimum_value: HexString;
+    fee_rate: HexString;
+}
+interface GraphNodeInfo {
+    node_name: string;
+    version: string;
+    addresses: Multiaddr[];
+    features: string[];
+    node_id: Pubkey;
+    timestamp: HexString;
+    chain_hash: Hash256;
+    auto_accept_min_ckb_funding_amount: HexString;
+    udt_cfg_infos: UdtCfgInfos;
+}
+interface GraphChannelInfo {
+    channel_outpoint: OutPoint;
+    node1: Pubkey;
+    node2: Pubkey;
+    created_timestamp: HexString;
+    update_info_of_node1?: ChannelUpdateInfo | null;
+    update_info_of_node2?: ChannelUpdateInfo | null;
+    capacity: HexString;
+    chain_hash: Hash256;
+    udt_type_script?: Script | null;
+}
+interface ConnectPeerParams {
+    address: Multiaddr;
+    save?: boolean;
+}
+/** connect_peer returns None in v0.6.1 */
+type ConnectPeerResult = null;
+interface DisconnectPeerParams {
+    peer_id: PeerId;
+}
+interface ListPeersResult {
+    peers: PeerInfo[];
+}
+interface OpenChannelParams {
+    peer_id: PeerId;
+    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: ChannelId;
+}
+interface AcceptChannelParams {
+    temporary_channel_id: ChannelId;
+    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: ChannelId;
+}
+interface ListChannelsParams {
+    peer_id?: PeerId;
+    include_closed?: boolean;
+}
+interface ListChannelsResult {
+    channels: Channel[];
+}
+interface ShutdownChannelParams {
+    channel_id: ChannelId;
+    close_script?: Script;
+    fee_rate?: HexString;
+    force?: boolean;
+}
+interface AbandonChannelParams {
+    channel_id: ChannelId;
+}
+interface UpdateChannelParams {
+    channel_id: ChannelId;
+    enabled?: boolean;
+    tlc_expiry_delta?: HexString;
+    tlc_minimum_value?: HexString;
+    tlc_fee_proportional_millionths?: HexString;
+}
+interface SendPaymentParams {
+    target_pubkey?: Pubkey;
+    amount?: HexString;
+    payment_hash?: PaymentHash;
+    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 SendPaymentResult extends PaymentInfo {
+}
+interface GetPaymentParams {
+    payment_hash: PaymentHash;
+}
+interface GetPaymentResult extends PaymentInfo {
+}
+interface NewInvoiceParams {
+    amount: HexString;
+    description?: string;
+    currency: Currency;
+    payment_preimage?: Hash256;
+    payment_hash?: PaymentHash;
+    expiry?: HexString;
+    fallback_address?: string;
+    final_expiry_delta?: HexString;
+    udt_type_script?: Script;
+    hash_algorithm?: HashAlgorithm;
+    allow_mpp?: boolean;
+}
+interface NewInvoiceResult {
+    invoice_address: string;
+    invoice: CkbInvoice;
+}
+interface ParseInvoiceParams {
+    invoice: string;
+}
+interface ParseInvoiceResult {
+    invoice: CkbInvoice;
+}
+interface GetInvoiceParams {
+    payment_hash: PaymentHash;
+}
+interface GetInvoiceResult {
+    invoice_address: string;
+    invoice: CkbInvoice;
+    status: CkbInvoiceStatus;
+}
+interface CancelInvoiceParams {
+    payment_hash: PaymentHash;
+}
+interface CancelInvoiceResult {
+    invoice_address: string;
+    invoice: CkbInvoice;
+    status: CkbInvoiceStatus;
+}
+interface SettleInvoiceParams {
+    payment_hash: PaymentHash;
+    payment_preimage: Hash256;
+}
+interface HopRequire {
+    pubkey: Pubkey;
+    channel_outpoint?: OutPoint | null;
+}
+interface BuildRouterParams {
+    amount?: HexString;
+    udt_type_script?: Script;
+    hops_info: HopRequire[];
+    final_tlc_expiry_delta?: HexString;
+}
+interface RouterHop {
+    target: Pubkey;
+    channel_outpoint: OutPoint;
+    amount_received: HexString;
+    incoming_tlc_expiry: HexString;
+}
+interface BuildRouterResult {
+    router_hops: RouterHop[];
+}
+interface SendPaymentWithRouterParams {
+    payment_hash?: PaymentHash;
+    router: RouterHop[];
+    invoice?: string;
+    custom_records?: PaymentCustomRecords;
+    keysend?: boolean;
+    udt_type_script?: Script;
+    dry_run?: boolean;
+}
+interface GraphNodesParams {
+    limit?: HexString;
+    after?: HexString;
+}
+interface GraphNodesResult {
+    nodes: GraphNodeInfo[];
+    last_cursor: HexString;
+}
+interface GraphChannelsParams {
+    limit?: HexString;
+    after?: HexString;
+}
+interface GraphChannelsResult {
+    channels: GraphChannelInfo[];
+    last_cursor: HexString;
+}
+/** Cross-chain hub invoice variant. */
+type CchInvoice = {
+    Fiber: string;
+} | {
+    Lightning: string;
+};
+/** Cross-chain hub order status. */
+type CchOrderStatus = 'Pending' | 'IncomingAccepted' | 'OutgoingInFlight' | 'OutgoingSettled' | 'Succeeded' | 'Failed';
+/** Reason for removing a TLC in Dev module APIs. */
+type RemoveTlcReason = {
+    RemoveTlcFulfill: Hash256;
+} | {
+    RemoveTlcFail: HexString;
+};
+/** TLC id wrapper in watchtower-related types. */
+type TLCId = {
+    Offered: HexString;
+} | {
+    Received: HexString;
+};
+/** Minimal CKB cell output representation used by watchtower revocation data. */
+interface CellOutput {
+    capacity: HexString;
+    lock: Script;
+    type?: Script | null;
+}
+/** Settlement TLC data used by watchtower operations. */
+interface SettlementTlc {
+    tlc_id: TLCId;
+    hash_algorithm: HashAlgorithm;
+    payment_amount: HexString;
+    payment_hash: Hash256;
+    expiry: HexString;
+    local_key: Privkey;
+    remote_key: Pubkey;
+}
+/** Settlement data used by watchtower operations. */
+interface SettlementData {
+    local_amount: HexString;
+    remote_amount: HexString;
+    tlcs: SettlementTlc[];
+}
+/** Revocation data used by watchtower operations. */
+interface RevocationData {
+    commitment_number: HexString;
+    aggregated_signature: HexString;
+    output: CellOutput;
+    output_data: HexString;
+}
+interface NodeInfoResult extends NodeInfo {
+}
+interface JsonRpcRequest<T = unknown> {
+    jsonrpc: '2.0';
+    id: number | string;
+    method: string;
+    params: T[];
+}
+interface JsonRpcResponse<T = unknown> {
+    jsonrpc: '2.0';
+    id: number | string;
+    result?: T;
+    error?: JsonRpcError;
+}
+interface JsonRpcError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+
+/**
+ * Security Policy Types
+ * Configuration for AI agent spending limits and guardrails
+ */
+
+declare const SpendingLimitSchema: z.ZodObject<{
+    maxPerTransaction: z.ZodString;
+    maxPerWindow: z.ZodString;
+    windowSeconds: z.ZodNumber;
+    currentSpent: z.ZodOptional<z.ZodString>;
+    windowStart: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type SpendingLimit = z.infer<typeof SpendingLimitSchema>;
+declare const RecipientPolicySchema: z.ZodObject<{
+    allowlist: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    blocklist: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    allowUnknown: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+type RecipientPolicy = z.infer<typeof RecipientPolicySchema>;
+declare const RateLimitSchema: z.ZodObject<{
+    maxTransactions: z.ZodNumber;
+    windowSeconds: z.ZodNumber;
+    cooldownSeconds: z.ZodDefault<z.ZodNumber>;
+    currentCount: z.ZodOptional<z.ZodNumber>;
+    windowStart: z.ZodOptional<z.ZodNumber>;
+    lastTransaction: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type RateLimit = z.infer<typeof RateLimitSchema>;
+declare const ChannelPolicySchema: z.ZodObject<{
+    allowOpen: z.ZodDefault<z.ZodBoolean>;
+    allowClose: z.ZodDefault<z.ZodBoolean>;
+    allowForceClose: z.ZodDefault<z.ZodBoolean>;
+    maxFundingAmount: z.ZodOptional<z.ZodString>;
+    minFundingAmount: z.ZodOptional<z.ZodString>;
+    maxChannels: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type ChannelPolicy = z.infer<typeof ChannelPolicySchema>;
+declare const SecurityPolicySchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodDefault<z.ZodString>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    spending: z.ZodOptional<z.ZodObject<{
+        maxPerTransaction: z.ZodString;
+        maxPerWindow: z.ZodString;
+        windowSeconds: z.ZodNumber;
+        currentSpent: z.ZodOptional<z.ZodString>;
+        windowStart: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    recipients: z.ZodOptional<z.ZodObject<{
+        allowlist: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        blocklist: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        allowUnknown: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    rateLimit: z.ZodOptional<z.ZodObject<{
+        maxTransactions: z.ZodNumber;
+        windowSeconds: z.ZodNumber;
+        cooldownSeconds: z.ZodDefault<z.ZodNumber>;
+        currentCount: z.ZodOptional<z.ZodNumber>;
+        windowStart: z.ZodOptional<z.ZodNumber>;
+        lastTransaction: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    channels: z.ZodOptional<z.ZodObject<{
+        allowOpen: z.ZodDefault<z.ZodBoolean>;
+        allowClose: z.ZodDefault<z.ZodBoolean>;
+        allowForceClose: z.ZodDefault<z.ZodBoolean>;
+        maxFundingAmount: z.ZodOptional<z.ZodString>;
+        minFundingAmount: z.ZodOptional<z.ZodString>;
+        maxChannels: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    confirmationThreshold: z.ZodOptional<z.ZodString>;
+    auditLogging: z.ZodDefault<z.ZodBoolean>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+type SecurityPolicy = z.infer<typeof SecurityPolicySchema>;
+type ViolationType = 'SPENDING_LIMIT_PER_TX' | 'SPENDING_LIMIT_PER_WINDOW' | 'RATE_LIMIT_EXCEEDED' | 'RATE_LIMIT_COOLDOWN' | 'RECIPIENT_NOT_ALLOWED' | 'RECIPIENT_BLOCKED' | 'CHANNEL_OPEN_NOT_ALLOWED' | 'CHANNEL_CLOSE_NOT_ALLOWED' | 'CHANNEL_FORCE_CLOSE_NOT_ALLOWED' | 'CHANNEL_FUNDING_EXCEEDS_MAX' | 'CHANNEL_FUNDING_BELOW_MIN' | 'MAX_CHANNELS_REACHED' | 'REQUIRES_CONFIRMATION';
+interface PolicyViolation {
+    type: ViolationType;
+    message: string;
+    details: {
+        requested?: string;
+        limit?: string;
+        recipient?: string;
+        remaining?: string;
+        cooldownRemaining?: number;
+    };
+}
+interface PolicyCheckResult {
+    allowed: boolean;
+    violations: PolicyViolation[];
+    requiresConfirmation: boolean;
+}
+type AuditAction = 'PAYMENT_SENT' | 'PAYMENT_RECEIVED' | 'INVOICE_CREATED' | 'INVOICE_VALIDATED' | 'HOLD_INVOICE_CREATED' | 'HOLD_INVOICE_SETTLED' | 'CHANNEL_OPENED' | 'CHANNEL_CLOSED' | 'POLICY_VIOLATION' | 'POLICY_UPDATED' | 'NODE_STARTED' | 'NODE_STOPPED';
+interface AuditLogEntry {
+    timestamp: number;
+    action: AuditAction;
+    success: boolean;
+    details: Record<string, unknown>;
+    policyViolations?: PolicyViolation[];
+    sessionId?: string;
+    agentId?: string;
+}
+interface KeyConfig {
+    /** Base directory for key storage */
+    baseDir: string;
+    /** Password for key encryption (should come from secure source) */
+    encryptionPassword?: string;
+    /** Whether to generate keys if they don't exist */
+    autoGenerate: boolean;
+}
+interface KeyInfo {
+    /** Public key (hex) */
+    publicKey: HexString;
+    /** Whether the key is encrypted */
+    encrypted: boolean;
+    /** Key file path */
+    path: string;
+    /** Key creation timestamp */
+    createdAt?: number;
+}
+interface AgentSession {
+    /** Unique session ID */
+    sessionId: string;
+    /** Agent identifier */
+    agentId: string;
+    /** Session start time */
+    startedAt: number;
+    /** Session expiry time */
+    expiresAt?: number;
+    /** Session-specific policy overrides */
+    policyOverrides?: Partial<SecurityPolicy>;
+    /** Session metadata */
+    metadata?: Record<string, unknown>;
+}
+declare const DEFAULT_SECURITY_POLICY: SecurityPolicy;
+
+/**
+ * Utility Functions
+ * Common utilities for hex conversion, CKB amount calculation, and random generation
+ */
+
+/**
+ * Convert number to hex string
+ */
+declare function toHex(value: number | bigint): HexString;
+/**
+ * Convert hex string to bigint
+ */
+declare function fromHex(hex: HexString): bigint;
+/**
+ * Convert CKB amount (in CKB units) to shannons (hex)
+ */
+declare function ckbToShannons(ckb: number | string): HexString;
+/**
+ * Convert shannons (hex) to CKB amount
+ */
+declare function shannonsToCkb(shannons: HexString): number;
+/**
+ * Generate a random 32-byte hex string (for payment preimage)
+ */
+declare function randomBytes32(): HexString;
+/**
+ * Convert a Fiber node id (hex-encoded compressed secp256k1 pubkey, 33 bytes)
+ * to a libp2p peer id (base58btc encoded sha2-256 multihash).
+ */
+declare function nodeIdToPeerId(nodeId: string): Promise<string>;
+/**
+ * Build a canonical multiaddr by appending/replacing /p2p/<peerId>.
+ */
+declare function buildMultiaddr(address: string, peerId: string): string;
+/**
+ * Build a canonical multiaddr from a node id and base address.
+ */
+declare function buildMultiaddrFromNodeId(address: string, nodeId: string): Promise<string>;
+/**
+ * Build a best-effort local multiaddr from an RPC URL and peer id.
+ * Uses rpcPort + 1 as inferred P2P port when advertised addresses are unavailable.
+ */
+declare function buildMultiaddrFromRpcUrl(rpcUrl: string, peerId: string): string;
+
+/**
+ * Fiber RPC Client
+ * Type-safe JSON-RPC client for Fiber Network Node
+ */
+
+interface RpcClientConfig {
+    /** RPC endpoint URL */
+    url: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Custom headers */
+    headers?: Record<string, string>;
+    /**
+     * Biscuit token for authentication.
+     *
+     * Prefer server-side usage. In browser apps, avoid embedding long-lived
+     * privileged tokens and use a trusted backend/proxy where possible.
+     */
+    biscuitToken?: string;
+}
+declare class FiberRpcError extends Error {
+    code: number;
+    data?: unknown | undefined;
+    constructor(code: number, message: string, data?: unknown | undefined);
+    static fromJsonRpcError(error: JsonRpcError): FiberRpcError;
+}
+declare class FiberRpcClient {
+    private requestId;
+    private config;
+    private readonly channelStateAliases;
+    constructor(config: RpcClientConfig);
+    /**
+     * Make a raw JSON-RPC call
+     *
+     * Useful for advanced/experimental RPCs not wrapped by convenience methods.
+     *
+     * @example
+     * ```ts
+     * const result = await client.call<MyResult>('some_method', [{ foo: 'bar' }]);
+     * ```
+     */
+    call<TResult>(method: string, params?: unknown[]): Promise<TResult>;
+    /**
+     * Connect to a peer
+     */
+    connectPeer(params: ConnectPeerParams): Promise<ConnectPeerResult>;
+    /**
+     * Disconnect from a peer
+     */
+    disconnectPeer(params: DisconnectPeerParams): Promise<null>;
+    /**
+     * List all connected peers
+     */
+    listPeers(): Promise<ListPeersResult>;
+    /**
+     * Open a new channel with a peer
+     */
+    openChannel(params: OpenChannelParams): Promise<OpenChannelResult>;
+    /**
+     * Accept a channel opening request
+     */
+    acceptChannel(params: AcceptChannelParams): Promise<AcceptChannelResult>;
+    /**
+     * List all channels
+     */
+    listChannels(params?: ListChannelsParams): Promise<ListChannelsResult>;
+    private normalizeChannelStateName;
+    private normalizeChannel;
+    /**
+     * Shutdown (close) a channel
+     */
+    shutdownChannel(params: ShutdownChannelParams): Promise<null>;
+    /**
+     * Abandon a pending channel
+     */
+    abandonChannel(params: AbandonChannelParams): Promise<null>;
+    /**
+     * Update channel parameters
+     */
+    updateChannel(params: UpdateChannelParams): Promise<null>;
+    /**
+     * Send a payment
+     */
+    sendPayment(params: SendPaymentParams): Promise<SendPaymentResult>;
+    /**
+     * Get payment status
+     */
+    getPayment(params: GetPaymentParams): Promise<GetPaymentResult>;
+    /**
+     * Create a new invoice
+     */
+    newInvoice(params: NewInvoiceParams): Promise<NewInvoiceResult>;
+    /**
+     * Parse an invoice string
+     */
+    parseInvoice(params: ParseInvoiceParams): Promise<ParseInvoiceResult>;
+    /**
+     * Get invoice by payment hash
+     */
+    getInvoice(params: GetInvoiceParams): Promise<GetInvoiceResult>;
+    /**
+     * Cancel an open invoice
+     */
+    cancelInvoice(params: CancelInvoiceParams): Promise<CancelInvoiceResult>;
+    /**
+     * Settle a hold invoice with the preimage
+     * Used for conditional/escrow payments where the invoice was created
+     * with a payment_hash (no preimage provided upfront)
+     */
+    settleInvoice(params: SettleInvoiceParams): Promise<null>;
+    /**
+     * Build a custom route for payment
+     * Useful for channel rebalancing (circular payments) and advanced routing
+     */
+    buildRouter(params: BuildRouterParams): Promise<BuildRouterResult>;
+    /**
+     * Send a payment using a pre-built route from buildRouter()
+     * Use with allow_self_payment for channel rebalancing
+     */
+    sendPaymentWithRouter(params: SendPaymentWithRouterParams): Promise<SendPaymentResult>;
+    /**
+     * List nodes in the network graph
+     */
+    graphNodes(params?: GraphNodesParams): Promise<GraphNodesResult>;
+    /**
+     * List channels in the network graph
+     */
+    graphChannels(params?: GraphChannelsParams): Promise<GraphChannelsResult>;
+    /**
+     * Get local node information
+     */
+    nodeInfo(): Promise<NodeInfoResult>;
+    /**
+     * Check if the node is reachable
+     */
+    ping(): Promise<boolean>;
+    /**
+     * Wait for the node to be ready
+     */
+    waitForReady(options?: {
+        timeout?: number;
+        interval?: number;
+    }): Promise<void>;
+    /**
+     * Wait for a payment to reach a terminal state (Success or Failed)
+     * Polls get_payment at the specified interval.
+     *
+     * @returns The final payment result
+     * @throws FiberRpcError on timeout
+     */
+    waitForPayment(paymentHash: PaymentHash, options?: {
+        timeout?: number;
+        interval?: number;
+    }): Promise<GetPaymentResult>;
+    /**
+     * Wait for a channel to reach ChannelReady state.
+     * Polls list_channels at the specified interval.
+     *
+     * @returns The channel info once ready
+     * @throws FiberRpcError on timeout or if channel disappears
+     */
+    waitForChannelReady(channelId: ChannelId, options?: {
+        timeout?: number;
+        interval?: number;
+    }): Promise<Channel>;
+    /**
+     * Wait for an invoice to reach a specific status.
+     * Useful for hold invoice workflows: wait for 'Received' before settling.
+     *
+     * @returns The invoice info once the target status is reached
+     * @throws FiberRpcError on timeout
+     */
+    waitForInvoiceStatus(paymentHash: PaymentHash, targetStatus: CkbInvoiceStatus | CkbInvoiceStatus[], options?: {
+        timeout?: number;
+        interval?: number;
+    }): Promise<GetInvoiceResult>;
+    /**
+     * Watch for incoming payments on specified invoices.
+     * Polls invoice statuses and calls the callback when a status changes.
+     * Use an AbortSignal to stop watching.
+     *
+     * @example
+     * ```typescript
+     * const controller = new AbortController();
+     * client.watchIncomingPayments({
+     *   paymentHashes: [hash1, hash2],
+     *   onPayment: (invoice) => console.log('Payment received!', invoice),
+     *   signal: controller.signal,
+     * });
+     * // Later: controller.abort(); to stop watching
+     * ```
+     */
+    watchIncomingPayments(options: {
+        /** Payment hashes of invoices to watch */
+        paymentHashes: PaymentHash[];
+        /** Callback when an invoice status changes to Received or Paid */
+        onPayment: (invoice: GetInvoiceResult) => void;
+        /** Polling interval in ms (default: 3000) */
+        interval?: number;
+        /** AbortSignal to stop watching */
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+
+export { type AbandonChannelParams, type AcceptChannelParams, type AcceptChannelResult, type AgentSession, type Attribute, type AuditAction, type AuditLogEntry, type BuildRouterParams, type BuildRouterResult, type CancelInvoiceParams, type CancelInvoiceResult, type CchInvoice, type CchOrderStatus, type CellOutput, type Channel, type ChannelId, type ChannelPolicy, ChannelPolicySchema, ChannelState, type ChannelStateFlags, type ChannelUpdateInfo, type CkbInvoice, type CkbInvoiceStatus, type ConnectPeerParams, type ConnectPeerResult, type Currency, DEFAULT_SECURITY_POLICY, type DisconnectPeerParams, FiberRpcClient, FiberRpcError, type GetInvoiceParams, type GetInvoiceResult, type GetPaymentParams, type GetPaymentResult, type GraphChannelInfo, type GraphChannelsParams, type GraphChannelsResult, type GraphNodeInfo, type GraphNodesParams, type GraphNodesResult, type Hash256, type HashAlgorithm, type HexString, type HopHint, type HopRequire, type Htlc, type InvoiceData, type InvoiceSignature, type JsonRpcError, type JsonRpcRequest, type JsonRpcResponse, type KeyConfig, type KeyInfo, type ListChannelsParams, type ListChannelsResult, type ListPeersResult, type Multiaddr, type NewInvoiceParams, type NewInvoiceResult, type NodeInfo, type NodeInfoResult, type OpenChannelParams, type OpenChannelResult, type OutPoint, type ParseInvoiceParams, type ParseInvoiceResult, type PaymentCustomRecords, type PaymentHash, type PaymentInfo, type PaymentStatus, type PeerId, type PeerInfo, type PolicyCheckResult, type PolicyViolation, type Privkey, type Pubkey, type RateLimit, RateLimitSchema, type RecipientPolicy, RecipientPolicySchema, type RemoveTlcReason, type RevocationData, type RouterHop, type Script$1 as Script, type SecurityPolicy, SecurityPolicySchema, type SendPaymentParams, type SendPaymentResult, type SendPaymentWithRouterParams, type SessionRoute, type SessionRouteNode, type SettleInvoiceParams, type SettlementData, type SettlementTlc, type ShutdownChannelParams, type SpendingLimit, SpendingLimitSchema, type TLCId, type TlcStatus, type UdtArgInfo, type UdtCellDep, type UdtCfgInfos, type UdtDep, type UdtScript, type UpdateChannelParams, type ViolationType, buildMultiaddr, buildMultiaddrFromNodeId, buildMultiaddrFromRpcUrl, ckbToShannons, fromHex, nodeIdToPeerId, randomBytes32, scriptToAddress, shannonsToCkb, toHex };