@fiber-confidence/sdk

A pre-flight reliability SDK for Fiber payments on CKB.

@fiber-confidence/sdk estimates whether a CKB Fiber payment is likely to succeed before you attempt to execute it. It reads node, peer, channel, graph, route, and fee signals, then returns an explainable 0–100 confidence score with actionable recommendations.

Installation

Install the package via your preferred package manager:

# npm
npm install @fiber-confidence/sdk

# pnpm
pnpm add @fiber-confidence/sdk

# yarn
yarn add @fiber-confidence/sdk

Quickstart

1. Connecting via the Fastify API Client

If you are running the apps/api service, you can query it directly using the SDK client:

import { FiberConfidence } from "@fiber-confidence/sdk";

const confidence = new FiberConfidence({
  mode: "api",
  apiUrl: "http://localhost:4000" // Your Fastify API endpoint
});

const result = await confidence.analyze({
  invoice: "fibt_mock_good_ckb_100000000",
  maxFee: "2000"
});

console.log(result.confidence); // e.g. 91
console.log(result.level);      // "very_high"
console.log(result.recommendation.action); // "proceed"
console.log(result.recommendation.message); // "Payment has a high probability of success."

2. Using In-Process Mock Adapter

You can also use the library completely offline/in-process for development and mocking:

import { FiberConfidence } from "@fiber-confidence/sdk";

const confidence = new FiberConfidence({
  mode: "mock"
});

const result = await confidence.analyze({
  invoice: "fibt_mock_good_ckb_100000000"
});

3. Using Server-Side JSON-RPC

If you want the SDK to communicate directly with a live Fiber node:

import { FiberConfidence } from "@fiber-confidence/sdk";

const confidence = new FiberConfidence({
  mode: "rpc",
  rpcUrl: "http://127.0.0.1:8227",
  timeoutMs: 8000,
  apiKey: "your-dev-secret" // optional
});

const result = await confidence.analyze({
  invoice: "fibt_..."
});

Mock Invoices

For testing in mock mode, the SDK deterministically supports the following invoices:

• fibt_mock_good_ckb_100000000 (High success confidence)
• fibt_mock_medium_ckb_50000000000 (Medium confidence)
• fibt_mock_bad_ckb_999999999999999 (Low confidence due to liquidity)
• fibt_mock_no_route (Low confidence, routing failure)
• fibt_mock_offline (Aborts due to target offline)
• fibt_mock_unsupported_asset (Aborts due to asset mismatch)

Deterministic Scoring Weights

The SDK computes scores based on the following weights:

• Node Health (20%)
• Peer Connectivity (15%)
• Liquidity (30%)
• Route Availability (25%)
• Fee Risk (5%)
• Time Risk (5%)

License

MIT