fiberprobe 0.1.0

package/dist/client/index.js

@@ -0,0 +1,162 @@
+/**
+ * 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)
+ * ```
+ */
+// ── JSON-RPC transport ────────────────────────────────────────────────────────
+let requestId = 0;
+/**
+ * Send a single JSON-RPC 2.0 request to the FNN node and return the result.
+ * Throws if the response contains a JSON-RPC error object.
+ *
+ * @param url    - Full HTTP URL of the FNN RPC endpoint
+ * @param method - JSON-RPC method name
+ * @param params - Method parameters (passed as the first array element per FNN convention)
+ */
+async function rpc(url, method, params = {}) {
+    const id = ++requestId;
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ jsonrpc: '2.0', id, method, params: [params] }),
+    });
+    if (!response.ok) {
+        throw new Error(`FNN RPC HTTP error ${response.status}: ${response.statusText}`);
+    }
+    const json = await response.json();
+    if (json.error) {
+        throw new Error(`FNN RPC error [${json.error.code}]: ${json.error.message}`);
+    }
+    return json.result;
+}
+// ── FiberClient ───────────────────────────────────────────────────────────────
+export class FiberClient {
+    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 = 'http://127.0.0.1:8227') {
+        this.rpcUrl = rpcUrl;
+    }
+    // ── Node ───────────────────────────────────────────────────────────────────
+    /** Returns identifying information and operational stats for the running FNN node. */
+    async nodeInfo() {
+        return rpc(this.rpcUrl, 'node_info');
+    }
+    // ── Peers ──────────────────────────────────────────────────────────────────
+    /** Lists all peers currently connected to this node. */
+    async listPeers() {
+        return rpc(this.rpcUrl, 'list_peers');
+    }
+    /**
+     * Connects to a remote Fiber peer by multiaddr.
+     * @param address - Multiaddr of the remote peer
+     * @param save    - Persist this address for reconnection on restart
+     */
+    async connectPeer(address, save = true) {
+        return rpc(this.rpcUrl, 'connect_peer', { address, save });
+    }
+    // ── Channels ───────────────────────────────────────────────────────────────
+    /**
+     * 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.
+     */
+    async listChannels(options = {}) {
+        const result = await rpc(this.rpcUrl, 'list_channels', options);
+        return result.channels;
+    }
+    /**
+     * 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
+     */
+    async openChannel(params) {
+        return rpc(this.rpcUrl, 'open_channel', params);
+    }
+    /**
+     * Initiates cooperative shutdown of a channel.
+     * @param channel_id - Channel to close
+     * @param force      - Force-close unilaterally. Incurs a time-lock penalty.
+     */
+    async shutdownChannel(channel_id, force = false) {
+        return rpc(this.rpcUrl, 'shutdown_channel', { channel_id, force });
+    }
+    // ── Payments ───────────────────────────────────────────────────────────────
+    /**
+     * Sends a payment or performs a dry-run feasibility check.
+     * Set dry_run: true to validate routing and estimate fees without
+     * broadcasting the payment.
+     */
+    async sendPayment(params) {
+        return rpc(this.rpcUrl, 'send_payment', params);
+    }
+    /**
+     * Fetches current status and details of a payment by its hash.
+     * Poll this after sendPayment() to track Inflight → Success/Failed transitions.
+     */
+    async getPayment(payment_hash) {
+        return rpc(this.rpcUrl, 'get_payment', { payment_hash });
+    }
+    /**
+     * Builds and validates a payment route without sending.
+     * Use this to inspect hop details and confirm a path exists before committing.
+     */
+    async buildRouter(params) {
+        return rpc(this.rpcUrl, 'build_router', params);
+    }
+    // ── Invoices ───────────────────────────────────────────────────────────────
+    /**
+     * 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)
+     */
+    async newInvoice(params) {
+        return rpc(this.rpcUrl, 'new_invoice', params);
+    }
+    /** Fetches an invoice and its current payment status by payment hash. */
+    async getInvoice(payment_hash) {
+        return rpc(this.rpcUrl, 'get_invoice', { payment_hash });
+    }
+    /** Cancels an Open invoice, preventing it from being paid. */
+    async cancelInvoice(payment_hash) {
+        return rpc(this.rpcUrl, 'cancel_invoice', { payment_hash });
+    }
+    // ── Network Graph ──────────────────────────────────────────────────────────
+    /**
+     * 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.
+     */
+    async graphChannels(limit = 100, after) {
+        return rpc(this.rpcUrl, 'graph_channels', {
+            limit: '0x' + limit.toString(16),
+            ...(after !== undefined && { after }),
+        });
+    }
+    // ── Invoice Parsing ──────────────────────────────────────────────────────────
+    /**
+     * 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...)
+     */
+    async parseInvoice(invoice) {
+        return rpc(this.rpcUrl, 'parse_invoice', { invoice });
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

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

package/dist/client/types.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Fiber Network RPC Types — derived from the official FNN RPC specification.
+ * All hex values are 0x-prefixed strings representing u128 amounts in shannon.
+ */
+export type Hash256 = string;
+export type Pubkey = string;
+export type PeerId = string;
+export type ChannelStateName = 'NegotiatingFunding' | 'CollaboratingFundingTx' | 'SigningCommitment' | 'AwaitingTxSignatures' | 'AwaitingChannelReady' | 'ChannelReady' | 'ShuttingDown' | 'Closed';
+/** Channel state as returned by the RPC: an object, not a bare string. */
+export interface ChannelState {
+    state_name: ChannelStateName;
+    state_flags?: string;
+}
+export interface Channel {
+    channel_id: Hash256;
+    is_public: boolean;
+    is_acceptor: boolean;
+    is_one_way: boolean;
+    channel_outpoint?: string;
+    pubkey: Pubkey;
+    funding_udt_type_script?: object;
+    state: ChannelState;
+    local_balance: string;
+    remote_balance: string;
+    offered_tlc_balance: string;
+    received_tlc_balance: string;
+    pending_tlcs: Htlc[];
+    latest_commitment_transaction_hash?: Hash256;
+    created_at: string;
+    enabled: boolean;
+    tlc_expiry_delta: number;
+    tlc_fee_proportional_millionths: string;
+    shutdown_transaction_hash?: Hash256;
+    failure_detail?: string | null;
+}
+export interface Htlc {
+    id: number;
+    amount: string;
+    payment_hash: Hash256;
+    expiry: number;
+    status: {
+        Outbound: string;
+    } | {
+        Inbound: string;
+    };
+}
+export interface ListChannelsResult {
+    channels: Channel[];
+}
+export type PaymentStatus = 'Created' | 'Inflight' | 'Success' | 'Failed';
+export interface SessionRouteNode {
+    pubkey: Pubkey;
+    amount: string;
+    channel_outpoint: string;
+}
+export interface SessionRoute {
+    nodes: SessionRouteNode[];
+}
+export interface Payment {
+    payment_hash: Hash256;
+    status: PaymentStatus;
+    created_at: number;
+    last_updated_at: number;
+    failed_error?: string;
+    fee: string;
+    routers: SessionRoute[];
+}
+export interface SendPaymentParams {
+    invoice?: string;
+    target_pubkey?: Pubkey;
+    amount?: string;
+    payment_hash?: Hash256;
+    max_fee_amount?: string;
+    timeout?: number;
+    keysend?: boolean;
+    dry_run?: boolean;
+    allow_self_payment?: boolean;
+}
+export type InvoiceStatus = 'Open' | 'Cancelled' | 'Expired' | 'Received' | 'Paid';
+export interface InvoiceResult {
+    invoice_address: string;
+    invoice: object;
+    status: InvoiceStatus;
+}
+export interface NewInvoiceParams {
+    amount: string;
+    currency: 'Fibb' | 'Fibt' | 'Fibd';
+    description?: string;
+    expiry?: number;
+    final_expiry_delta?: number;
+}
+export interface ChannelUpdateInfo {
+    timestamp: number;
+    enabled: boolean;
+    outbound_liquidity?: string;
+    tlc_expiry_delta: number;
+    tlc_minimum_value: string;
+    fee_rate: number;
+}
+export interface GraphChannel {
+    channel_outpoint: string;
+    node1: Pubkey;
+    node2: Pubkey;
+    capacity: string;
+    update_info_of_node1?: ChannelUpdateInfo;
+    update_info_of_node2?: ChannelUpdateInfo;
+    udt_type_script?: object;
+}
+export interface GraphChannelsResult {
+    channels: GraphChannel[];
+    last_cursor: string;
+}
+export interface NodeInfo {
+    version: string;
+    pubkey: Pubkey;
+    node_name?: string;
+    addresses: string[];
+    channel_count: number;
+    peers_count: number;
+}
+export interface PeerInfo {
+    pubkey: Pubkey;
+    address: string;
+}
+export interface ListPeersResult {
+    peers: PeerInfo[];
+}
+export interface RouterHop {
+    target: Pubkey;
+    channel_outpoint: string;
+    amount_received: string;
+    incoming_tlc_expiry: number;
+}
+export interface ParsedInvoiceAttr {
+    description?: string;
+    final_htlc_minimum_expiry_delta?: string;
+    payee_public_key?: Pubkey;
+    expiry?: string;
+}
+export interface ParsedInvoiceData {
+    timestamp: string;
+    payment_hash: Hash256;
+    attrs: ParsedInvoiceAttr[];
+}
+export interface ParsedInvoice {
+    currency: 'Fibb' | 'Fibt' | 'Fibd';
+    amount: string;
+    signature: string;
+    data: ParsedInvoiceData;
+}
+export interface ParseInvoiceResult {
+    invoice: ParsedInvoice;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/client/types.js

@@ -0,0 +1,6 @@
+/**
+ * Fiber Network RPC Types — derived from the official FNN RPC specification.
+ * All hex values are 0x-prefixed strings representing u128 amounts in shannon.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/client/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * fnn-ts — TypeScript SDK for Fiber Network Node (FNN)
+ *
+ * @packageDocumentation
+ */
+export { FiberClient } from './client/index.js';
+export { PaymentChecker } from './payment/checker.js';
+export { FiberError, RouteNotFoundError, InsufficientCapacityError, TemporaryChannelFailureError, PeerUnreachableError, PaymentTimeoutError, FeeInsufficientError, AmountBelowMinimumError, UnknownFiberError, } from './client/errors.js';
+export type { Hash256, Pubkey, PeerId, Channel, ChannelState, Payment, PaymentStatus, SendPaymentParams, InvoiceResult, InvoiceStatus, NewInvoiceParams, GraphChannel, GraphChannelsResult, NodeInfo, ListPeersResult, } from './client/types.js';
+export type { CanPayParams, PaymentCheckResult, ProbePayParams, ProbeResult, CanReceiveParams, ReceiveCheckResult, ChannelCapacityEntry, } from './payment/checker.js';
+export { FiberEventEmitter } from './payment/events.js';
+export type { WatchPaymentOptions, WatchInvoiceOptions, WatchChannelOptions, BackoffProfile, CancelFn, } from './payment/events.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAwB,mBAAmB,CAAA;AACjE,OAAO,EAAE,cAAc,EAAE,MAAqB,sBAAsB,CAAA;AAEpE,OAAO,EACL,UAAU,EACV,kBAAkB,EAClB,yBAAyB,EACzB,4BAA4B,EAC5B,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,EACvB,iBAAiB,GAClB,MAA6C,oBAAoB,CAAA;AAElE,YAAY,EACV,OAAO,EAAE,MAAM,EAAE,MAAM,EACvB,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,aAAa,EAAE,iBAAiB,EACzC,aAAa,EAAE,aAAa,EAAE,gBAAgB,EAC9C,YAAY,EAAE,mBAAmB,EACjC,QAAQ,EAAE,eAAe,GAC1B,MAA6C,mBAAmB,CAAA;AAEjE,YAAY,EACV,YAAY,EAAE,kBAAkB,EAChC,cAAc,EAAE,WAAW,EAC3B,gBAAgB,EAAE,kBAAkB,EACpC,oBAAoB,GACrB,MAA6C,sBAAsB,CAAA;AAEpE,OAAO,EAAE,iBAAiB,EAAE,MAAkB,qBAAqB,CAAA;AAEnE,YAAY,EACV,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,cAAc,EACd,QAAQ,GACT,MAA6C,qBAAqB,CAAA"}

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * fnn-ts — TypeScript SDK for Fiber Network Node (FNN)
+ *
+ * @packageDocumentation
+ */
+export { FiberClient } from './client/index.js';
+export { PaymentChecker } from './payment/checker.js';
+export { FiberError, RouteNotFoundError, InsufficientCapacityError, TemporaryChannelFailureError, PeerUnreachableError, PaymentTimeoutError, FeeInsufficientError, AmountBelowMinimumError, UnknownFiberError, } from './client/errors.js';
+export { FiberEventEmitter } from './payment/events.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAwB,mBAAmB,CAAA;AACjE,OAAO,EAAE,cAAc,EAAE,MAAqB,sBAAsB,CAAA;AAEpE,OAAO,EACL,UAAU,EACV,kBAAkB,EAClB,yBAAyB,EACzB,4BAA4B,EAC5B,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,EACvB,iBAAiB,GAClB,MAA6C,oBAAoB,CAAA;AAkBlE,OAAO,EAAE,iBAAiB,EAAE,MAAkB,qBAAqB,CAAA"}

package/dist/payment/checker.d.ts

@@ -0,0 +1,165 @@
+/**
+ * PaymentChecker — pre-flight payment feasibility analysis for Fiber Network.
+ *
+ * Solves two problems every Fiber application faces:
+ *
+ *  1. canPay()     — Will this payment succeed before I try to send it?
+ *  2. canReceive() — Do I have enough inbound capacity to receive a payment?
+ *
+ * Design note: send_payment's dry_run flag was evaluated as a data source
+ * for canPay() and rejected. Live testnet testing confirmed dry-run payment
+ * sessions are never queryable via get_payment, even immediately after
+ * creation — the RPC returns "Payment session not found" on instant lookup.
+ * This means dry_run cannot supply route or fee detail synchronously or
+ * asynchronously.
+ *
+ * canPay() instead performs static graph reachability analysis:
+ *   1. parseInvoice() resolves the destination pubkey and amount
+ *   2. listChannels() checks for a direct channel to the destination
+ *   3. graphChannels() + BFS finds a multi-hop path if no direct channel exists
+ *   4. Each hop is scored against published outbound_liquidity, exactly as
+ *      a live router would need to evaluate route viability
+ *
+ * canReceive() scans open ChannelReady channels and sums usable inbound
+ * capacity, correctly accounting for in-flight received TLCs.
+ */
+import type { FiberClient } from '../client/index.js';
+import type { Pubkey } from '../client/types.js';
+import { FiberError } from '../client/errors.js';
+export interface CanPayParams {
+    /** Fiber invoice string (fibb… / fibt… / fibd…) */
+    invoice: string;
+    /** Maximum hops to search when pathfinding through the public graph. Defaults to 5. */
+    maxHops?: number;
+}
+export interface PaymentCheckResult {
+    /** Whether a viable route was found through direct or public-graph channels. */
+    canPay: boolean;
+    /**
+     * Confidence score: 0–100.
+     *
+     *   80–100  High.     Route is liquid, short, and well-capitalised.
+     *   60–79   Moderate. Route found but some liquidity is uncertain.
+     *   30–59   Low.      Route exists but liquidity is thin or unverifiable.
+     *   0       None.     No route found.
+     *
+     * This reflects known liquidity at the time of the check — actual channel
+     * balances can shift before a real payment is attempted. Treat this as a
+     * probability signal, not a guarantee.
+     */
+    confidence: number;
+    /** Destination pubkey resolved from the invoice. */
+    destinationPubkey?: Pubkey;
+    /** Amount requested by the invoice, in shannon (hex). */
+    amount?: string;
+    /** Number of hops in the discovered route. 0 if paid via a direct channel. */
+    hopCount?: number;
+    /** Human-readable issues identified during analysis. */
+    issues: string[];
+    /** Structured error when no route could be found. */
+    error?: FiberError;
+}
+export interface ProbePayParams {
+    /** Destination node pubkey to probe. */
+    targetPubkey: Pubkey;
+    /** Amount to probe for, in shannon (hex string). */
+    amount: string;
+    /** Max seconds to wait for the probe to resolve. Defaults to 15. */
+    timeoutSeconds?: number;
+}
+export interface ProbeResult {
+    /**
+     * True when the probe reached the destination and was rejected only for
+     * having an unrecognised (fake) payment hash — proof the entire route had
+     * enough live liquidity to carry this exact amount, right now.
+     */
+    isViable: boolean;
+    /** Raw terminal failed_error string from the RPC, for diagnostics. */
+    terminalError?: string;
+    /** Structured error when the probe failed due to a real routing/liquidity issue. */
+    error?: FiberError;
+    /** Wall-clock time the probe took to resolve, in milliseconds. */
+    latencyMs: number;
+}
+export interface CanReceiveParams {
+    /** Amount in shannon to check receivability for (hex string). */
+    amount: string;
+    /** Optional UDT type script hash for multi-asset capacity checks. */
+    udtTypeScriptHash?: string;
+}
+export interface ReceiveCheckResult {
+    canReceive: boolean;
+    totalInboundCapacity: bigint;
+    activeChannelCount: number;
+    channelBreakdown: ChannelCapacityEntry[];
+    issues: string[];
+}
+export interface ChannelCapacityEntry {
+    channelId: string;
+    pubkey: string;
+    usableInbound: bigint;
+    isEnabled: boolean;
+}
+/**
+ * Pre-flight payment feasibility analysis for Fiber Network applications.
+ *
+ * @example
+ * ```ts
+ * const checker = new PaymentChecker(client)
+ *
+ * const result = await checker.canPay({ invoice: 'fibt...' })
+ * if (!result.canPay) {
+ *   console.error(result.error?.message)
+ *   return
+ * }
+ * console.log(`Confidence: ${result.confidence}%  Hops: ${result.hopCount}`)
+ *
+ * const rx = await checker.canReceive({ amount: '0x174876e800' })
+ * if (!rx.canReceive) console.warn('Low inbound capacity:', rx.issues)
+ * ```
+ */
+export declare class PaymentChecker {
+    private readonly client;
+    constructor(client: FiberClient);
+    /**
+     * Performs a pre-flight feasibility check for an outgoing Fiber payment.
+     *
+     * Process:
+     *   1. Resolves the destination pubkey and amount from the invoice.
+     *   2. Checks for a direct ChannelReady channel to the destination —
+     *      if found, this is the highest-confidence path.
+     *   3. Otherwise, searches the public network graph via BFS to find
+     *      the shortest multi-hop path to the destination.
+     *   4. Scores each hop against published outbound liquidity data and
+     *      combines scores using weakest-link logic, since a payment fails
+     *      if any single hop lacks capacity.
+     */
+    canPay(params: CanPayParams): Promise<PaymentCheckResult>;
+    /**
+     * Checks whether this node has sufficient inbound capacity to receive a payment.
+     *
+     * Usable inbound per channel = remote_balance − received_tlc_balance.
+     * Only ChannelReady + enabled channels are included.
+     */
+    canReceive(params: CanReceiveParams): Promise<ReceiveCheckResult>;
+    /**
+     * Performs a live liquidity probe against a real destination pubkey.
+     *
+     * Sends a real HTLC using a randomly generated, never-revealed preimage.
+     * Funds cannot be lost: since the preimage is never shared, no node along
+     * the route -- including the destination -- can ever claim the payment.
+     *
+     * Terminal outcomes:
+     *   - Destination returns IncorrectOrUnknownPaymentDetails: the entire
+     *     route had enough live liquidity right now to carry this exact
+     *     amount. This is a genuine empirical signal, not a static estimate.
+     *   - Any other failure (e.g. TemporaryChannelFailure): a specific hop
+     *     lacks liquidity or is unreachable. Parsed into a typed FiberError.
+     *
+     * This is slower and costs a brief HTLC lock on every hop versus canPay(),
+     * so use canPay() as the fast default and probePay() when you need
+     * ground-truth confidence immediately before a real payment.
+     */
+    probePay(params: ProbePayParams): Promise<ProbeResult>;
+}
+//# sourceMappingURL=checker.d.ts.map

package/dist/payment/checker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checker.d.ts","sourceRoot":"","sources":["../../src/payment/checker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAe,oBAAoB,CAAA;AAC9D,OAAO,KAAK,EAAyB,MAAM,EAAE,MAAM,oBAAoB,CAAA;AACvE,OAAO,EAAE,UAAU,EAAsB,MAAM,qBAAqB,CAAA;AAKpE,MAAM,WAAW,YAAY;IAC3B,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAA;IACf,uFAAuF;IACvF,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,gFAAgF;IAChF,MAAM,EAAE,OAAO,CAAA;IACf;;;;;;;;;;;OAWG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB,oDAAoD;IACpD,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,wDAAwD;IACxD,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,qDAAqD;IACrD,KAAK,CAAC,EAAE,UAAU,CAAA;CACnB;AAGD,MAAM,WAAW,cAAc;IAC7B,wCAAwC;IACxC,YAAY,EAAE,MAAM,CAAA;IACpB,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAA;IACd,oEAAoE;IACpE,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,QAAQ,EAAE,OAAO,CAAA;IACjB,sEAAsE;IACtE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,oFAAoF;IACpF,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAA;CAClB;AACD,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAA;IACd,qEAAqE;IACrE,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,OAAO,CAAA;IACnB,oBAAoB,EAAE,MAAM,CAAA;IAC5B,kBAAkB,EAAE,MAAM,CAAA;IAC1B,gBAAgB,EAAE,oBAAoB,EAAE,CAAA;IACxC,MAAM,EAAE,MAAM,EAAE,CAAA;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAM,MAAM,CAAA;IACrB,MAAM,EAAS,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB,SAAS,EAAM,OAAO,CAAA;CACvB;AAsID;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,MAAM;IAAnC,YAA6B,MAAM,EAAE,WAAW,EAAI;IAEpD;;;;;;;;;;;;OAYG;IACG,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA4G9D;IAED;;;;;OAKG;IACG,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAoDtE;IAED;;;;;;;;;;;;;;;;;OAiBG;IACG,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC,CAiD3D;CACF"}