fiberprobe 0.1.0

package/README.md

@@ -0,0 +1,197 @@
+# fnn-ts
+
+A TypeScript SDK for Fiber Network Node (FNN) that answers the question every payment-channel application eventually asks: **will this payment actually go through?**
+
+Built for the "Gone in 60ms" Fiber Network Infrastructure Hackathon, Category 2: Node, Routing & Diagnostics.
+---
+## The problem
+
+Fiber, like Lightning, splits channel state into two categories. Total capacity is public, broadcast via gossip. The actual balance split between the two peers in a channel is private and changes with every payment. This is by design: publishing live balances would leak the entire financial graph of the network.
+
+The result is that no RPC can honestly answer "can I pay this amount right now?" A `dry_run` flag exists on `send_payment`, but we tested it directly against live FNN v0.8.1 nodes and confirmed it does not help: dry-run sessions return `Created` immediately with no route detail, and are never queryable afterward, not even the instant after creation (`get_payment` returns `Payment session not found`). Whatever data a real router computes during a dry run is discarded, not surfaced.
+
+Every wallet, checkout flow, and payment bot built on Fiber runs into this same wall. `fnn-ts` is the SDK layer that solves it properly, and it does so two ways, because there are two different questions a developer actually needs answered.
+
+## Two tiers, because one estimate isn't enough
+
+### `canPay()` — free, instant, approximate
+
+Resolves the destination from an invoice, checks for a direct channel, and falls back to a breadth-first search over the public channel graph if no direct channel exists. Each hop is scored against whatever `outbound_liquidity` operators have chosen to publish (most don't; it's optional and frequently `null`), combined using weakest-link logic since a payment fails the moment any single hop can't forward it. Costs nothing, takes milliseconds, and is right most of the time. But it can only ever be an estimate, because gossip-announced capacity is not the same as current usable liquidity.
+
+### `probePay()` — the ground truth
+
+This is the part of the SDK we're most confident about, because we built it by directly verifying how Lightning-style networks solve this exact problem, then proved it works against our own live Fiber testnet nodes before writing a line of production code.
+
+The mechanism: generate a random 32-byte value, hash it, and send a real HTLC to the destination's pubkey using that fake hash as the payment hash, no invoice involved. The payment travels the real route with real HTLCs locked at every hop. Because the true preimage was never generated by the destination and never revealed by us, no node on the path, including the destination, can ever claim the funds. Two outcomes are possible:
+
+- The destination receives the HTLC and rejects it with `IncorrectOrUnknownPaymentDetails`. This is the "successful failure": the only reason it failed is that we made up the hash. Every hop along the entire route had enough live liquidity to carry this exact amount, at this exact moment. Verified live on our own 3-node testnet topology (Alice → Bob → Carol, 2 hops): resolved in 577ms.
+- The HTLC gets rejected by an intermediate hop, e.g. `TemporaryChannelFailure` or an explicit insufficient-liquidity error. That hop, specifically, doesn't have the capacity right now. We tested this too, by probing for an amount larger than any real channel could carry, and got back the actual RPC error with real numbers: `max outbound liquidity 89100000000 is insufficient, required amount: 409600000000000`.
+
+No funds move. No invoice is required. The cost is a brief HTLC lock at each hop while the probe resolves (observed under 600ms end to end on testnet) and it should be used when a real payment is imminent and the answer needs to be right, not just probably right.
+
+Fiber currently implements this using HTLCs, same as Bitcoin Lightning. PTLCs (Point Time-Locked Contracts) are a documented future upgrade in the Fiber litepaper aimed at closing a route-correlation privacy gap that HTLC-based probing shares with Lightning. `probePay()` is built against what Fiber ships today; when PTLCs land, the probing mechanism will need the corresponding update, and we've noted this as a tracked item below.
+
+### `canReceive()` — inbound capacity, correctly computed
+
+Sums usable inbound capacity across `ChannelReady` channels: `remote_balance` minus `received_tlc_balance`, so in-flight HTLCs aren't double-counted as available. Simple on paper, but we found and fixed two real bugs here during live testing (see below) that would have silently under-reported capacity in production.
+
+---
+
+## What's actually been proven, not just implemented
+
+Everything in this SDK has been run against real FNN v0.8.1 nodes on Fiber testnet, not mocked. Along the way we found and fixed five bugs that only showed up under real conditions:
+
+1. **`graph_channels`' `limit` param must be a hex string**, not a plain integer, like every other numeric RPC field. A naive integer call fails outright.
+2. **The public graph paginates.** Testnet has 600+ channels; a single 500-entry page silently missed our own freshly opened channel. Fixed with cursor-based pagination via the `after` param, looping until `last_cursor` stabilizes.
+3. **`funding_udt_type_script` is returned as `null`, not omitted**, for native CKB channels. A `!== undefined` check let every native channel get misclassified as a UDT channel and excluded from `canReceive()`, reporting 0 capacity on a channel that actually had 891 CKB available.
+4. **`outbound_liquidity` is `null`, not `undefined`**, when an operator hasn't published it. Same class of bug, this time crashing `canPay()`'s hop scoring on real graph data.
+5. **`peer_id` was renamed to `pubkey`** across `Channel` and related types in FNN v0.8.0; our first type pass, written from RPC docs alone, still used the old field name.
+
+None of these would have surfaced from reading documentation. They surfaced from running three real nodes, opening real channels, and generating real invoices.
+
+---
+
+## Quick start
+
+```ts
+import { FiberClient, PaymentChecker } from 'fnn-ts'
+
+const client = new FiberClient('http://127.0.0.1:8227') // your FNN node's RPC address
+const checker = new PaymentChecker(client)
+
+// Fast, free, approximate
+const estimate = await checker.canPay({ invoice: 'fibt1...' })
+console.log(estimate.confidence, estimate.hopCount)
+
+// Slower, costs a brief HTLC lock, gives you the real answer
+const probe = await checker.probePay({
+  targetPubkey: estimate.destinationPubkey!,
+  amount: estimate.amount!,
+})
+console.log(probe.isViable, probe.latencyMs, probe.terminalError)
+
+// Inbound capacity, correctly computed
+const rx = await checker.canReceive({ amount: '0x3B9ACA00' }) // 10 CKB
+console.log(rx.canReceive, rx.totalInboundCapacity)
+```
+
+Every method returns typed results. `FiberError` and its subclasses (`RouteNotFoundError`, `InsufficientCapacityError`, `TemporaryChannelFailureError`, `PeerUnreachableError`, `PaymentTimeoutError`, `FeeInsufficientError`, `AmountBelowMinimumError`) each carry a machine-readable `code` and a plain-English `suggestion`, so an application can branch on failure type without parsing raw RPC strings itself.
+
+For payment and invoice lifecycle without manual polling loops, `FiberEventEmitter` wraps adaptive backoff (250ms up to 10s, capped attempts) behind `watchPayment()`, `watchInvoice()`, and `watchChannel()`, each returning a cancel function.
+
+---
+
+## Running the demo yourself
+
+The demo runs three real FNN nodes locally on Fiber testnet and a React app that calls the SDK against them live. Nothing is mocked.
+
+### 1. Get the FNN binary
+
+```bash
+mkdir fnn-node && cd fnn-node
+wget https://github.com/nervosnetwork/fiber/releases/download/v0.8.1/fnn_v0.8.1-x86_64-linux.tar.gz
+tar xzf fnn_v0.8.1-x86_64-linux.tar.gz
+```
+
+(For other platforms, check `https://api.github.com/repos/nervosnetwork/fiber/releases/tags/v0.8.1` for the matching asset.)
+
+### 2. Set up three nodes
+
+Repeat this for three directories (e.g. `fnn-node`, `fnn-node-bob`, `fnn-node-carol`), each with a distinct P2P and RPC port. The shipped `config/testnet/config.yml` needs only two lines changed per node:
+
+```yaml
+fiber:
+  listening_addr: "/ip4/0.0.0.0/tcp/8228"   # unique per node: 8228, 8229, 8231...
+rpc:
+  listening_addr: "127.0.0.1:8227"          # unique per node: 8227, 8237, 8247...
+```
+
+For each node, generate a CKB account and export its key:
+
+```bash
+ckb-cli account new
+ckb-cli account export --lock-arg <LOCK_ARG> --extended-privkey-path ./ckb/exported-key
+head -n 1 ./ckb/exported-key > ./ckb/key
+chmod 600 ./ckb/key && rm ./ckb/exported-key
+```
+
+Fund each node's testnet address at the Pudge Faucet: `https://faucet.nervos.org/`
+
+Start each node:
+
+```bash
+FIBER_SECRET_KEY_PASSWORD=<your password> RUST_LOG=info ./fnn -c config.yml -d .
+```
+
+### 3. Connect peers and open channels
+
+```bash
+# From node A's RPC, connect to node B's P2P address (from its startup log)
+curl -X POST -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"connect_peer","params":[{"address":"/ip4/127.0.0.1/tcp/<PORT>/p2p/<PEER_ID>"}]}' \
+  http://127.0.0.1:\<RPC_PORT\>
+
+# Open a channel (funding well above both sides' auto-accept minimum avoids a manual accept step)
+curl -X POST -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":2,"method":"open_channel","params":[{"pubkey":"<TARGET_PUBKEY>","funding_amount":"0x174876e800","public":true}]}' \
+  http://127.0.0.1:<RPC_PORT>
+```
+
+Poll `list_channels` until `state.state_name` reads `ChannelReady`. This project's own test topology has no direct channel between the sender and the second recipient, forcing `canPay()`'s BFS and `probePay()`'s live route to actually traverse a real intermediate hop rather than a trivial direct case.
+
+### 4. Run the demo app
+
+```bash
+cd demo
+npm install
+npm run dev
+```
+
+Open `http://localhost:5173`. The Vite dev server proxies `/rpc-alice`, `/rpc-bob`, `/rpc-carol` to each node's RPC port (see `demo/vite.config.ts`), so the browser never needs CORS access to raw node ports directly.
+
+---
+
+## API reference
+
+| Module | What it does |
+|---|---|
+| `FiberClient` | Fully typed HTTP JSON-RPC client. Every method typed against the live FNN v0.8.1 RPC surface, not just the docs. |
+| `PaymentChecker.canPay()` | Free static route + liquidity estimate via direct-channel check or graph BFS. |
+| `PaymentChecker.probePay()` | Live empirical route verification via riskless HTLC probing. Ground truth, not an estimate. |
+| `PaymentChecker.canReceive()` | Real inbound capacity across `ChannelReady` channels, correctly excluding in-flight HTLCs. |
+| `FiberEventEmitter` | Adaptive-backoff watchers for payment, invoice, and channel lifecycle, no manual polling loops. |
+| `FiberError` + subclasses | Typed error hierarchy parsed from raw RPC failure strings, each with a `code` and a `suggestion`. |
+
+---
+
+## Honest limitations
+
+- `probePay()` briefly locks a real HTLC on every hop along the route while it resolves. In our testing this resolved in well under a second, but if an intermediate node is unreachable, the HTLC could sit until `tlc_expiry_delta` lapses rather than failing fast. Set `timeoutSeconds` accordingly for your use case.
+- `canPay()`'s confidence score reflects gossip-announced liquidity, which most operators don't publish (`outbound_liquidity` is frequently `null`). Treat it as a heuristic, not a guarantee, which is exactly why `probePay()` exists.
+- No local "Mission Control"-style penalty cache yet (see roadmap). Every `probePay()` call is independent; nothing is remembered between calls in this version.
+- Built and tested against FNN v0.8.1's current HTLC implementation. PTLC support is on Fiber's roadmap, not yet shipped, and this SDK will need updates when it lands.
+
+---
+
+## Roadmap
+
+- Local in-memory penalty tracking for `probePay()`: remember which channels failed recently and skip them in the next BFS pass without re-probing, with a decay window so temporary conditions aren't treated as permanent.
+- PTLC support once Fiber ships it, since the probing mechanism's privacy properties depend on the underlying lock type.
+- Multi-asset (UDT/RGB++) coverage in `canReceive()` beyond the CKB-native path already implemented.
+- Wider RPC coverage in `FiberClient` (currently covers node, peer, channel, payment, invoice, and graph operations; not yet CCH cross-chain endpoints).
+
+---
+
+## Why this belongs in the ecosystem, not just a hackathon repo
+
+Every wallet, merchant checkout, and payment bot that gets built on Fiber will hit the exact liquidity-visibility wall this SDK addresses, on day one of integration. Right now each of them would either reinvent this from scratch or ship with silent failure modes, exactly the kind of gap that makes a new payment network frustrating to build on.
+
+`fnn-ts` is meant to be the layer that sits between `fnn`'s RPC and application code, so that question doesn't have to be solved twice. It's typed, it's tested against real infrastructure rather than assumptions from documentation, and the failures it caught along the way (five of them, detailed above) are the kind that would otherwise ship silently into production and degrade user experience the first time someone hits an edge case.
+
+---
+
+## Project info
+
+Category 2: Node, Routing & Diagnostics Infrastructure, "Gone in 60ms" Fiber Network Infrastructure Hackathon (July 2026).
+
+Repository: `github.com/Linnnetteseven/fnn-ts`

package/dist/client/errors.d.ts

@@ -0,0 +1,70 @@
+/**
+ * FiberError — typed error hierarchy for Fiber RPC failures.
+ *
+ * The Fiber RPC returns payment failures as raw `failed_error` strings.
+ * This module parses those strings into structured, actionable error
+ * classes so application code can branch on error type and surface
+ * meaningful messages to developers and users.
+ *
+ * @example
+ * ```ts
+ * const err = FiberError.parse(payment.failed_error)
+ * if (err instanceof InsufficientCapacityError) {
+ *   console.log(err.suggestion)
+ * }
+ * ```
+ */
+export declare abstract class FiberError extends Error {
+    abstract readonly code: string;
+    abstract readonly suggestion: string;
+    readonly raw?: string;
+    constructor(message: string, raw?: string);
+    /**
+     * Parse a raw Fiber RPC failed_error string into a typed FiberError.
+     * Matches against known error patterns using normalised lowercase comparison.
+     *
+     * @param raw - The failed_error string from a Payment or RPC response
+     */
+    static parse(raw: string): FiberError;
+}
+export declare class RouteNotFoundError extends FiberError {
+    readonly code = "ROUTE_NOT_FOUND";
+    readonly suggestion: string;
+    constructor(raw?: string);
+}
+export declare class InsufficientCapacityError extends FiberError {
+    readonly code = "INSUFFICIENT_CAPACITY";
+    readonly suggestion: string;
+    constructor(raw?: string);
+}
+export declare class TemporaryChannelFailureError extends FiberError {
+    readonly code = "TEMPORARY_CHANNEL_FAILURE";
+    readonly suggestion: string;
+    constructor(raw?: string);
+}
+export declare class PeerUnreachableError extends FiberError {
+    readonly code = "PEER_UNREACHABLE";
+    readonly suggestion: string;
+    constructor(raw?: string);
+}
+export declare class PaymentTimeoutError extends FiberError {
+    readonly code = "PAYMENT_TIMEOUT";
+    readonly suggestion: string;
+    constructor(raw?: string);
+}
+export declare class FeeInsufficientError extends FiberError {
+    readonly code = "FEE_INSUFFICIENT";
+    readonly suggestion = "The fee offered was rejected by a node on the route. Increase max_fee_amount and retry.";
+    constructor(raw?: string);
+}
+export declare class AmountBelowMinimumError extends FiberError {
+    readonly code = "AMOUNT_BELOW_MINIMUM";
+    readonly suggestion: string;
+    constructor(raw?: string);
+}
+export declare class UnknownFiberError extends FiberError {
+    readonly code = "UNKNOWN";
+    readonly suggestion = "An unrecognised error was returned by the Fiber node. Inspect the raw field for the original error string.";
+    constructor(raw?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/client/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/client/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,8BAAsB,UAAW,SAAQ,KAAK;IAC5C,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAQ,MAAM,CAAA;IACpC,QAAQ,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IAErB,YAAY,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAOxC;IAED;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAgCpC;CACF;AAID,qBAAa,kBAAmB,SAAQ,UAAU;IAChD,QAAQ,CAAC,IAAI,qBAA0B;IACvC,QAAQ,CAAC,UAAU,SAGsC;IACzD,YAAY,GAAG,CAAC,EAAE,MAAM,EAEvB;CACF;AAED,qBAAa,yBAA0B,SAAQ,UAAU;IACvD,QAAQ,CAAC,IAAI,2BAAgC;IAC7C,QAAQ,CAAC,UAAU,SAG+B;IAClD,YAAY,GAAG,CAAC,EAAE,MAAM,EAEvB;CACF;AAED,qBAAa,4BAA6B,SAAQ,UAAU;IAC1D,QAAQ,CAAC,IAAI,+BAAoC;IACjD,QAAQ,CAAC,UAAU,SAE+C;IAClE,YAAY,GAAG,CAAC,EAAE,MAAM,EAEvB;CACF;AAED,qBAAa,oBAAqB,SAAQ,UAAU;IAClD,QAAQ,CAAC,IAAI,sBAA2B;IACxC,QAAQ,CAAC,UAAU,SAGmC;IACtD,YAAY,GAAG,CAAC,EAAE,MAAM,EAEvB;CACF;AAED,qBAAa,mBAAoB,SAAQ,UAAU;IACjD,QAAQ,CAAC,IAAI,qBAA0B;IACvC,QAAQ,CAAC,UAAU,SAEwD;IAC3E,YAAY,GAAG,CAAC,EAAE,MAAM,EAEvB;CACF;AAED,qBAAa,oBAAqB,SAAQ,UAAU;IAClD,QAAQ,CAAC,IAAI,sBAA2B;IACxC,QAAQ,CAAC,UAAU,6FAA4F;IAC/G,YAAY,GAAG,CAAC,EAAE,MAAM,EAEvB;CACF;AAED,qBAAa,uBAAwB,SAAQ,UAAU;IACrD,QAAQ,CAAC,IAAI,0BAA+B;IAC5C,QAAQ,CAAC,UAAU,SAEwC;IAC3D,YAAY,GAAG,CAAC,EAAE,MAAM,EAEvB;CACF;AAED,qBAAa,iBAAkB,SAAQ,UAAU;IAC/C,QAAQ,CAAC,IAAI,aAAkB;IAC/B,QAAQ,CAAC,UAAU,gHAA+G;IAClI,YAAY,GAAG,CAAC,EAAE,MAAM,EAEvB;CACF"}

package/dist/client/errors.js

@@ -0,0 +1,132 @@
+/**
+ * FiberError — typed error hierarchy for Fiber RPC failures.
+ *
+ * The Fiber RPC returns payment failures as raw `failed_error` strings.
+ * This module parses those strings into structured, actionable error
+ * classes so application code can branch on error type and surface
+ * meaningful messages to developers and users.
+ *
+ * @example
+ * ```ts
+ * const err = FiberError.parse(payment.failed_error)
+ * if (err instanceof InsufficientCapacityError) {
+ *   console.log(err.suggestion)
+ * }
+ * ```
+ */
+// ── Base class ────────────────────────────────────────────────────────────────
+export class FiberError extends Error {
+    raw;
+    constructor(message, raw) {
+        super(message);
+        this.name = this.constructor.name;
+        if (raw !== undefined) {
+            this.raw = raw;
+        }
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    /**
+     * Parse a raw Fiber RPC failed_error string into a typed FiberError.
+     * Matches against known error patterns using normalised lowercase comparison.
+     *
+     * @param raw - The failed_error string from a Payment or RPC response
+     */
+    static parse(raw) {
+        const n = raw.toLowerCase();
+        if (n.includes('no_route') ||
+            n.includes('noroute') ||
+            n.includes('unknown_next_peer')) {
+            return new RouteNotFoundError(raw);
+        }
+        if (n.includes('insufficient') || n.includes('capacity')) {
+            return new InsufficientCapacityError(raw);
+        }
+        if (n.includes('temporary_channel_failure') ||
+            n.includes('temporarychannelfailure')) {
+            return new TemporaryChannelFailureError(raw);
+        }
+        if ((n.includes('peer') || n.includes('node')) &&
+            (n.includes('unreachable') ||
+                n.includes('disconnected') ||
+                n.includes('not_connected'))) {
+            return new PeerUnreachableError(raw);
+        }
+        if (n.includes('timeout') || n.includes('expir')) {
+            return new PaymentTimeoutError(raw);
+        }
+        if (n.includes('fee')) {
+            return new FeeInsufficientError(raw);
+        }
+        if (n.includes('amount') && n.includes('minimum')) {
+            return new AmountBelowMinimumError(raw);
+        }
+        return new UnknownFiberError(raw);
+    }
+}
+// ── Concrete error types ──────────────────────────────────────────────────────
+export class RouteNotFoundError extends FiberError {
+    code = 'ROUTE_NOT_FOUND';
+    suggestion = 'No payment route exists to the destination. Verify the recipient ' +
+        'has at least one open, public channel with sufficient inbound capacity, ' +
+        'and that your node is connected to the Fiber network.';
+    constructor(raw) {
+        super('No route found to the payment destination.', raw);
+    }
+}
+export class InsufficientCapacityError extends FiberError {
+    code = 'INSUFFICIENT_CAPACITY';
+    suggestion = 'Outbound channel capacity is too low for this amount plus fees. ' +
+        'Open a new channel with more funding, or ask your peer to push ' +
+        'liquidity to your side on an existing channel.';
+    constructor(raw) {
+        super('Insufficient outbound capacity to route this payment.', raw);
+    }
+}
+export class TemporaryChannelFailureError extends FiberError {
+    code = 'TEMPORARY_CHANNEL_FAILURE';
+    suggestion = 'A channel on the route reported a transient failure. ' +
+        'This is usually self-resolving — wait a few seconds and retry.';
+    constructor(raw) {
+        super('A channel on the payment route reported a temporary failure.', raw);
+    }
+}
+export class PeerUnreachableError extends FiberError {
+    code = 'PEER_UNREACHABLE';
+    suggestion = 'The destination peer appears offline or disconnected. ' +
+        'Check your own node connectivity, then verify the recipient node ' +
+        'is reachable on the Fiber network before retrying.';
+    constructor(raw) {
+        super('The destination peer is unreachable.', raw);
+    }
+}
+export class PaymentTimeoutError extends FiberError {
+    code = 'PAYMENT_TIMEOUT';
+    suggestion = 'The payment timed out before the destination acknowledged it. ' +
+        'Retry with a higher timeout value or during quieter network conditions.';
+    constructor(raw) {
+        super('Payment timed out before completion.', raw);
+    }
+}
+export class FeeInsufficientError extends FiberError {
+    code = 'FEE_INSUFFICIENT';
+    suggestion = 'The fee offered was rejected by a node on the route. Increase max_fee_amount and retry.';
+    constructor(raw) {
+        super('Fee was insufficient for the discovered payment route.', raw);
+    }
+}
+export class AmountBelowMinimumError extends FiberError {
+    code = 'AMOUNT_BELOW_MINIMUM';
+    suggestion = 'The payment amount is below the minimum TLC value enforced by ' +
+        'one or more channels on the route. Try a larger amount.';
+    constructor(raw) {
+        super('Payment amount is below the channel minimum.', raw);
+    }
+}
+export class UnknownFiberError extends FiberError {
+    code = 'UNKNOWN';
+    suggestion = 'An unrecognised error was returned by the Fiber node. Inspect the raw field for the original error string.';
+    constructor(raw) {
+        super('An unknown Fiber error occurred.', raw);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/client/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/client/errors.ts"],"names":[],"mappings":"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"}

package/dist/client/index.d.ts

@@ -0,0 +1,112 @@
+/**
+ * FiberClient — fully typed HTTP JSON-RPC client for Fiber Network Node (FNN).
+ *
+ * Communicates with a running FNN instance via its JSON-RPC endpoint
+ * (default: http://127.0.0.1:8227). Every method is typed against the
+ * official FNN RPC specification so callers get compile-time safety and
+ * inline documentation instead of raw invokeCommand() calls.
+ *
+ * @example
+ * ```ts
+ * const client = new FiberClient('http://127.0.0.1:8227')
+ * const info    = await client.nodeInfo()
+ * console.log(info.pubkey, info.channel_count)
+ * ```
+ */
+import type { Channel, Payment, SendPaymentParams, InvoiceResult, NewInvoiceParams, ListPeersResult, GraphChannelsResult, NodeInfo, RouterHop, ParseInvoiceResult, Hash256 } from './types.js';
+export declare class FiberClient {
+    private readonly rpcUrl;
+    /**
+     * @param rpcUrl - HTTP URL of the FNN RPC endpoint. Defaults to the standard
+     *                 local node address. Override for remote nodes or custom ports.
+     */
+    constructor(rpcUrl?: string);
+    /** Returns identifying information and operational stats for the running FNN node. */
+    nodeInfo(): Promise<NodeInfo>;
+    /** Lists all peers currently connected to this node. */
+    listPeers(): Promise<ListPeersResult>;
+    /**
+     * Connects to a remote Fiber peer by multiaddr.
+     * @param address - Multiaddr of the remote peer
+     * @param save    - Persist this address for reconnection on restart
+     */
+    connectPeer(address: string, save?: boolean): Promise<void>;
+    /**
+     * Lists channels on this node, optionally filtered by peer pubkey.
+     * @param options.pubkey         - Filter to channels with a specific peer
+     * @param options.include_closed - Include closed channels. Defaults to false.
+     */
+    listChannels(options?: {
+        pubkey?: string;
+        include_closed?: boolean;
+    }): Promise<Channel[]>;
+    /**
+     * Opens a new payment channel with a connected peer.
+     * @param params.pubkey         - Peer pubkey to open the channel with
+     * @param params.funding_amount - CKB to lock in the channel (hex u128, shannon)
+     * @param params.public         - Announce to the network graph
+     */
+    openChannel(params: {
+        pubkey: string;
+        funding_amount: string;
+        public?: boolean;
+    }): Promise<{
+        temporary_channel_id: Hash256;
+    }>;
+    /**
+     * Initiates cooperative shutdown of a channel.
+     * @param channel_id - Channel to close
+     * @param force      - Force-close unilaterally. Incurs a time-lock penalty.
+     */
+    shutdownChannel(channel_id: Hash256, force?: boolean): Promise<void>;
+    /**
+     * Sends a payment or performs a dry-run feasibility check.
+     * Set dry_run: true to validate routing and estimate fees without
+     * broadcasting the payment.
+     */
+    sendPayment(params: SendPaymentParams): Promise<Payment>;
+    /**
+     * Fetches current status and details of a payment by its hash.
+     * Poll this after sendPayment() to track Inflight → Success/Failed transitions.
+     */
+    getPayment(payment_hash: Hash256): Promise<Payment>;
+    /**
+     * Builds and validates a payment route without sending.
+     * Use this to inspect hop details and confirm a path exists before committing.
+     */
+    buildRouter(params: {
+        amount?: string;
+        hops_info: {
+            pubkey: string;
+            channel_outpoint?: string;
+        }[];
+    }): Promise<{
+        router_hops: RouterHop[];
+    }>;
+    /**
+     * Creates a new Fiber invoice for receiving a payment.
+     * @param params.amount   - Amount in shannon (hex u128)
+     * @param params.currency - Fibb (mainnet) | Fibt (testnet) | Fibd (devnet)
+     */
+    newInvoice(params: NewInvoiceParams): Promise<InvoiceResult>;
+    /** Fetches an invoice and its current payment status by payment hash. */
+    getInvoice(payment_hash: Hash256): Promise<InvoiceResult>;
+    /** Cancels an Open invoice, preventing it from being paid. */
+    cancelInvoice(payment_hash: Hash256): Promise<InvoiceResult>;
+    /**
+     * Fetches public channels from the Fiber network graph.
+     * Used by PaymentChecker to score route liquidity during canPay() analysis.
+     * @param limit - Maximum channels to return. Defaults to 100.
+     */
+    graphChannels(limit?: number, after?: string): Promise<GraphChannelsResult>;
+    /**
+     * Parses an encoded Fiber invoice string without attempting payment.
+     * Extracts amount, payment_hash, and the destination pubkey (payee_public_key)
+     * from the attrs array. Used by PaymentChecker.canPay() to resolve the
+     * payment destination before running graph reachability analysis.
+     *
+     * @param invoice - The encoded invoice string (fibb.../fibt.../fibd...)
+     */
+    parseInvoice(invoice: string): Promise<ParseInvoiceResult>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EACV,OAAO,EACP,OAAO,EACP,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAEhB,eAAe,EACf,mBAAmB,EACnB,QAAQ,EACR,SAAS,EACT,kBAAkB,EAClB,OAAO,EACR,MAAM,YAAY,CAAA;AAqCnB,qBAAa,WAAW;IAKV,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJnC;;;OAGG;IACH,YAA6B,MAAM,GAAE,MAAgC,EAAI;IAIzE,sFAAsF;IAChF,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,CAElC;IAID,wDAAwD;IAClD,SAAS,IAAI,OAAO,CAAC,eAAe,CAAC,CAE1C;IAED;;;;OAIG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,UAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAE7D;IAID;;;;OAIG;IACG,YAAY,CAChB,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,OAAO,CAAA;KAAO,GAC1D,OAAO,CAAC,OAAO,EAAE,CAAC,CAGpB;IAED;;;;;OAKG;IACG,WAAW,CAAC,MAAM,EAAE;QACxB,MAAM,EAAW,MAAM,CAAA;QACvB,cAAc,EAAG,MAAM,CAAA;QACvB,MAAM,CAAC,EAAU,OAAO,CAAA;KACzB,GAAG,OAAO,CAAC;QAAE,oBAAoB,EAAE,OAAO,CAAA;KAAE,CAAC,CAE7C;IAED;;;;OAIG;IACG,eAAe,CAAC,UAAU,EAAE,OAAO,EAAE,KAAK,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvE;IAID;;;;OAIG;IACG,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC,CAE7D;IAED;;;OAGG;IACG,UAAU,CAAC,YAAY,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAExD;IAED;;;OAGG;IACG,WAAW,CAAC,MAAM,EAAE;QACxB,MAAM,CAAC,EAAI,MAAM,CAAA;QACjB,SAAS,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;SAAE,EAAE,CAAA;KAC3D,GAAG,OAAO,CAAC;QAAE,WAAW,EAAE,SAAS,EAAE,CAAA;KAAE,CAAC,CAExC;IAID;;;;OAIG;IACG,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,aAAa,CAAC,CAEjE;IAED,yEAAyE;IACnE,UAAU,CAAC,YAAY,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CAE9D;IAED,8DAA8D;IACxD,aAAa,CAAC,YAAY,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CAEjE;IAID;;;;OAIG;IACG,aAAa,CAAC,KAAK,SAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAM7E;IAID;;;;;;;OAOG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAE/D;CACF"}