@fiber-pay/runtime 0.1.0-rc.2 → 0.1.0-rc.4

package/README.md

@@ -1,6 +1,6 @@
 # @fiber-pay/runtime
 
-Runtime monitor + job orchestration for Fiber (`fnn v0.6.1`).
+Runtime monitor + job orchestration for Fiber (`fnn v0.7.1`).
 
 ## Quick start
 
@@ -104,8 +104,8 @@ curl -fsS "$PROXY_A/jobs/$PAYMENT_JOB_ID/events" | jq
 ## One-command regression (recommended)
 
 ```bash
-pnpm e2e:runtime-jobs
-JOB_TIMEOUT_SEC=420 CHANNEL_CLEANUP_TIMEOUT_SEC=120 pnpm e2e:runtime-jobs -- --json
+pnpm e2e
+CHANNEL_READY_TIMEOUT_SEC=420 CHANNEL_CLOSE_TIMEOUT_SEC=180 pnpm e2e
 ```
 
 ## Handy job commands

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ChannelId, Channel, PaymentHash, PeerInfo, OpenChannelParams, ShutdownChannelParams, AcceptChannelParams, AbandonChannelParams, UpdateChannelParams, OpenChannelResult, AcceptChannelResult, NewInvoiceParams, CancelInvoiceParams, SettleInvoiceParams, GetInvoiceResult, SendPaymentParams, FiberRpcClient } from '@fiber-pay/sdk';
+import { ChannelId, Channel, PaymentHash, PeerInfo, OpenChannelParams, ShutdownChannelParams, AcceptChannelParams, AbandonChannelParams, UpdateChannelParams, OpenChannelResult, AcceptChannelResult, NewInvoiceParams, CancelInvoiceParams, SettleInvoiceParams, GetInvoiceResult, SendPaymentParams, FiberRpcClient, PaymentStatus, HexString } from '@fiber-pay/sdk';
 import { EventEmitter } from 'node:events';
 
 type AlertPriority = 'critical' | 'high' | 'medium' | 'low';
@@ -97,6 +97,12 @@ interface AlertBackend {
     stop?(): Promise<void>;
 }
 
+interface FormatRuntimeAlertOptions {
+    color?: 'auto' | 'always' | 'never';
+    prefix?: string;
+}
+declare function formatRuntimeAlert(alert: Alert, options?: FormatRuntimeAlertOptions): string;
+
 type JobType = 'payment' | 'invoice' | 'channel';
 type JobState = 'queued' | 'executing' | 'inflight' | 'waiting_retry' | 'invoice_created' | 'invoice_active' | 'invoice_received' | 'invoice_settled' | 'invoice_expired' | 'invoice_cancelled' | 'channel_opening' | 'channel_accepting' | 'channel_abandoning' | 'channel_updating' | 'channel_awaiting_ready' | 'channel_ready' | 'channel_closing' | 'channel_closed' | 'succeeded' | 'failed' | 'cancelled';
 declare const TERMINAL_JOB_STATES: Set<JobState>;
@@ -309,6 +315,108 @@ interface RuntimeBootstrap {
 }
 declare function startRuntimeService(configInput?: RuntimeConfigInput): Promise<RuntimeBootstrap>;
 
+/**
+ * Classify an RPC / job failure into a structured error.
+ *
+ * `failedError` is the raw `failed_error` string from Fiber's `get_payment` response.
+ * `error` is any caught JS exception.
+ */
+declare function classifyRpcError(error: unknown, failedError?: string): ClassifiedError;
+
+declare class SqliteJobStore {
+    private readonly db;
+    constructor(dbPath: string);
+    private runMigrations;
+    createJob<P, R>(job: Omit<Job<P, R>, 'id' | 'createdAt' | 'updatedAt'>): Job<P, R>;
+    updateJob<P, R>(id: string, updates: Partial<Job<P, R>>): Job<P, R>;
+    getJob<P = unknown, R = unknown>(id: string): Job<P, R> | undefined;
+    getJobByIdempotencyKey<P = unknown, R = unknown>(key: string): Job<P, R> | undefined;
+    listJobs<P = unknown, R = unknown>(filter?: JobFilter): Job<P, R>[];
+    deleteJob(id: string): void;
+    /** Return jobs that are ready to be retried right now. */
+    getRetryableJobs<P = unknown, R = unknown>(now?: number): Job<P, R>[];
+    /** Return jobs in non-terminal states (for recovery after daemon restart). */
+    getInProgressJobs<P = unknown, R = unknown>(): Job<P, R>[];
+    addJobEvent(jobId: string, eventType: JobEventType, fromState?: JobState, toState?: JobState, data?: Record<string, unknown>): JobEvent;
+    listJobEvents(jobId: string): JobEvent[];
+    close(): void;
+    private rowToJob;
+}
+
+interface JobManagerEvents {
+    'job:created': [job: RuntimeJob];
+    'job:state_changed': [job: RuntimeJob, from: JobState];
+    'job:succeeded': [job: RuntimeJob];
+    'job:failed': [job: RuntimeJob];
+    'job:cancelled': [job: RuntimeJob];
+}
+interface JobManagerConfig {
+    schedulerIntervalMs?: number;
+    maxConcurrentJobs?: number;
+    retryPolicy?: RetryPolicy;
+}
+declare class JobManager extends EventEmitter<JobManagerEvents> {
+    private readonly rpc;
+    private readonly store;
+    private readonly retryPolicy;
+    private readonly schedulerIntervalMs;
+    private readonly maxConcurrentJobs;
+    private running;
+    private schedulerTimer;
+    private readonly active;
+    constructor(rpc: FiberRpcClient, store: SqliteJobStore, config?: JobManagerConfig);
+    ensurePayment(params: PaymentJobParams, options?: {
+        idempotencyKey?: string;
+        maxRetries?: number;
+    }): Promise<PaymentJob>;
+    manageInvoice(params: InvoiceJobParams, options?: {
+        idempotencyKey?: string;
+        maxRetries?: number;
+        reuseTerminal?: boolean;
+    }): Promise<InvoiceJob>;
+    manageChannel(params: ChannelJobParams, options?: {
+        idempotencyKey?: string;
+        maxRetries?: number;
+        reuseTerminal?: boolean;
+    }): Promise<ChannelJob>;
+    getJob(id: string): RuntimeJob | undefined;
+    listJobs(filter?: JobFilter): RuntimeJob[];
+    cancelJob(id: string): void;
+    start(): void;
+    stop(): Promise<void>;
+    private createOrReuseJob;
+    private tick;
+    private schedule;
+    private recover;
+    private execute;
+    private buildEventData;
+}
+
+declare const defaultPaymentRetryPolicy: RetryPolicy;
+/**
+ * Decide whether a job should be retried given its error and current retry count.
+ */
+declare function shouldRetry(error: ClassifiedError, retryCount: number, policy: RetryPolicy): boolean;
+/**
+ * Compute the next retry delay using exponential backoff with random jitter.
+ * retryCount is the number of retries already attempted (0-based before this retry).
+ */
+declare function computeRetryDelay(retryCount: number, policy: RetryPolicy): number;
+
+type MachineEvent = 'send_issued' | 'payment_inflight' | 'payment_success' | 'payment_failed_retryable' | 'payment_failed_permanent' | 'invoice_created' | 'invoice_received' | 'invoice_settled' | 'invoice_expired' | 'invoice_cancelled' | 'channel_opening' | 'channel_accepting' | 'channel_abandoning' | 'channel_updating' | 'channel_closing' | 'channel_ready' | 'channel_closed' | 'channel_failed' | 'retry_delay_elapsed' | 'cancel';
+interface Transition {
+    from: JobState | JobState[];
+    event: MachineEvent;
+    to: JobState;
+}
+declare class JobStateMachine {
+    private readonly table;
+    constructor(transitions: Transition[]);
+    transition(current: JobState, event: MachineEvent): JobState | null;
+    isTerminal(state: JobState): boolean;
+}
+declare const paymentStateMachine: JobStateMachine;
+
 interface RpcMonitorProxyConfig {
     listen: string;
     targetUrl: string;
@@ -412,112 +520,142 @@ declare class MemoryStore implements Store {
     listAlerts(filters?: AlertFilter): Alert[];
 }
 
-declare class SqliteJobStore {
-    private readonly db;
-    constructor(dbPath: string);
-    private runMigrations;
-    createJob<P, R>(job: Omit<Job<P, R>, 'id' | 'createdAt' | 'updatedAt'>): Job<P, R>;
-    updateJob<P, R>(id: string, updates: Partial<Job<P, R>>): Job<P, R>;
-    getJob<P = unknown, R = unknown>(id: string): Job<P, R> | undefined;
-    getJobByIdempotencyKey<P = unknown, R = unknown>(key: string): Job<P, R> | undefined;
-    listJobs<P = unknown, R = unknown>(filter?: JobFilter): Job<P, R>[];
-    deleteJob(id: string): void;
-    /** Return jobs that are ready to be retried right now. */
-    getRetryableJobs<P = unknown, R = unknown>(now?: number): Job<P, R>[];
-    /** Return jobs in non-terminal states (for recovery after daemon restart). */
-    getInProgressJobs<P = unknown, R = unknown>(): Job<P, R>[];
-    addJobEvent(jobId: string, eventType: JobEventType, fromState?: JobState, toState?: JobState, data?: Record<string, unknown>): JobEvent;
-    listJobEvents(jobId: string): JobEvent[];
-    close(): void;
-    private rowToJob;
-}
-
-interface JobManagerEvents {
-    'job:created': [job: RuntimeJob];
-    'job:state_changed': [job: RuntimeJob, from: JobState];
-    'job:succeeded': [job: RuntimeJob];
-    'job:failed': [job: RuntimeJob];
-    'job:cancelled': [job: RuntimeJob];
-}
-interface JobManagerConfig {
-    schedulerIntervalMs?: number;
-    maxConcurrentJobs?: number;
-    retryPolicy?: RetryPolicy;
-}
-declare class JobManager extends EventEmitter<JobManagerEvents> {
-    private readonly rpc;
-    private readonly store;
-    private readonly retryPolicy;
-    private readonly schedulerIntervalMs;
-    private readonly maxConcurrentJobs;
-    private running;
-    private schedulerTimer;
-    private readonly active;
-    constructor(rpc: FiberRpcClient, store: SqliteJobStore, config?: JobManagerConfig);
-    ensurePayment(params: PaymentJobParams, options?: {
-        idempotencyKey?: string;
-        maxRetries?: number;
-    }): Promise<PaymentJob>;
-    manageInvoice(params: InvoiceJobParams, options?: {
-        idempotencyKey?: string;
-        maxRetries?: number;
-        reuseTerminal?: boolean;
-    }): Promise<InvoiceJob>;
-    manageChannel(params: ChannelJobParams, options?: {
-        idempotencyKey?: string;
-        maxRetries?: number;
-        reuseTerminal?: boolean;
-    }): Promise<ChannelJob>;
-    getJob(id: string): RuntimeJob | undefined;
-    listJobs(filter?: JobFilter): RuntimeJob[];
-    cancelJob(id: string): void;
-    start(): void;
-    stop(): Promise<void>;
-    private createOrReuseJob;
-    private tick;
-    private schedule;
-    private recover;
-    private execute;
-    private buildEventData;
-}
-
-type MachineEvent = 'send_issued' | 'payment_inflight' | 'payment_success' | 'payment_failed_retryable' | 'payment_failed_permanent' | 'invoice_created' | 'invoice_received' | 'invoice_settled' | 'invoice_expired' | 'invoice_cancelled' | 'channel_opening' | 'channel_accepting' | 'channel_abandoning' | 'channel_updating' | 'channel_closing' | 'channel_ready' | 'channel_closed' | 'channel_failed' | 'retry_delay_elapsed' | 'cancel';
-interface Transition {
-    from: JobState | JobState[];
-    event: MachineEvent;
-    to: JobState;
-}
-declare class JobStateMachine {
-    private readonly table;
-    constructor(transitions: Transition[]);
-    transition(current: JobState, event: MachineEvent): JobState | null;
-    isTerminal(state: JobState): boolean;
-}
-declare const paymentStateMachine: JobStateMachine;
-
 /**
- * Classify an RPC / job failure into a structured error.
+ * Payment Proof & Tracking System
+ * Records, stores, and verifies payment evidence for audit trail and reconciliation
  *
- * `failedError` is the raw `failed_error` string from Fiber's `get_payment` response.
- * `error` is any caught JS exception.
+ * IMPORTANT LIMITATION:
+ * Fiber Network RPC currently does NOT return the payment preimage to the sender
+ * after a successful payment. In standard Lightning protocol, the preimage serves
+ * as cryptographic proof of payment (SHA256(preimage) === payment_hash).
+ *
+ * Until Fiber exposes the preimage in send_payment/get_payment responses:
+ * - Payment proofs are based on RPC status (Success/Failed) rather than preimage
+ * - For invoices YOU create (as receiver), preimage IS available
+ * - This limitation affects sender-side proof verification only
+ *
+ * Tracking issue: Preimage not exposed in Fiber RPC send_payment result
  */
-declare function classifyRpcError(error: unknown, failedError?: string): ClassifiedError;
 
-declare const defaultPaymentRetryPolicy: RetryPolicy;
-/**
- * Decide whether a job should be retried given its error and current retry count.
- */
-declare function shouldRetry(error: ClassifiedError, retryCount: number, policy: RetryPolicy): boolean;
 /**
- * Compute the next retry delay using exponential backoff with random jitter.
- * retryCount is the number of retries already attempted (0-based before this retry).
+ * Complete payment proof record
  */
-declare function computeRetryDelay(retryCount: number, policy: RetryPolicy): number;
-
-interface FormatRuntimeAlertOptions {
-    color?: 'auto' | 'always' | 'never';
-    prefix?: string;
+interface PaymentProof {
+    /** Unique identifier (payment hash) */
+    id: string;
+    /** Status at time of recording */
+    status: PaymentStatus;
+    /** Original invoice string */
+    invoice: string;
+    /** Invoice details extracted */
+    invoiceDetails: {
+        paymentHash: string;
+        amountCkb: number;
+        description?: string;
+    };
+    /** Payment execution details */
+    execution: {
+        amountCkb: number;
+        feeCkb: number;
+        actualTimestamp: number;
+        requestTimestamp: number;
+    };
+    /** Proof of payment */
+    proof: {
+        preimage?: HexString;
+        peerAddress?: string;
+        channelUsed?: string;
+        routePath?: string[];
+    };
+    /** Verification status */
+    verified: boolean;
+    verifiedAt?: number;
+    verificationMethod?: 'preimage_hash' | 'rpc_status' | 'manual';
+    /** Metadata for audit trail */
+    metadata: {
+        createdAt: number;
+        updatedAt: number;
+        notes?: string;
+    };
+}
+interface PaymentProofSummary {
+    totalProofs: number;
+    verifiedCount: number;
+    pendingCount: number;
+    failedCount: number;
+    totalAmountCkb: number;
+    totalFeesCkb: number;
+    timeRange: {
+        earliest?: number;
+        latest?: number;
+    };
+}
+declare class PaymentProofManager {
+    private proofs;
+    private proofFilePath;
+    private maxStoredProofs;
+    constructor(dataDir: string);
+    /**
+     * Load proofs from disk
+     */
+    load(): Promise<void>;
+    /**
+     * Save proofs to disk
+     */
+    save(): Promise<void>;
+    /**
+     * Record a payment proof after successful execution
+     */
+    recordPaymentProof(paymentHash: string, invoice: string, invoiceDetails: {
+        paymentHash: string;
+        amountCkb: number;
+        description?: string;
+    }, execution: {
+        amountCkb: number;
+        feeCkb: number;
+        actualTimestamp: number;
+        requestTimestamp: number;
+    }, status: PaymentStatus, proof?: {
+        preimage?: HexString;
+        peerAddress?: string;
+        channelUsed?: string;
+        routePath?: string[];
+    }): PaymentProof;
+    /**
+     * Get proof by payment hash
+     */
+    getProof(paymentHash: string): PaymentProof | undefined;
+    /**
+     * Verify a proof's authenticity
+     */
+    verifyProof(proof: PaymentProof): {
+        valid: boolean;
+        reason: string;
+    };
+    /**
+     * Get payment timeline between two timestamps
+     */
+    getPaymentChain(startTime: number, endTime: number): PaymentProof[];
+    /**
+     * Get summary statistics
+     */
+    getSummary(): PaymentProofSummary;
+    /**
+     * Export proofs as audit report
+     */
+    exportAuditReport(startTime?: number, endTime?: number): string;
+    /**
+     * Verify preimage hash (SHA256 of preimage = payment_hash)
+     */
+    private verifyPreimageHash;
+    /**
+     * Remove oldest proofs to keep storage bounded
+     */
+    private pruneOldestProofs;
+    /**
+     * Ensure directory exists
+     */
+    private ensureDirectory;
 }
-declare function formatRuntimeAlert(alert: Alert, options?: FormatRuntimeAlertOptions): string;
 
-export { type Alert, type AlertBackend, type AlertBackendConfig, type AlertFilter, type AlertInput, type AlertPriority, type AlertType, type ChannelBalanceChangedData, type ChannelJob, type ChannelJobAction, type ChannelJobAlertData, type ChannelJobParams, type ChannelJobResult, type ChannelStateChangedData, type ClassifiedError, type ErrorCategory, FiberMonitorService, type FileAlertConfig, type InvoiceJob, type InvoiceJobAction, type InvoiceJobAlertData, type InvoiceJobParams, type InvoiceJobResult, type Job, type JobEvent, type JobEventType, type JobFilter, JobManager, type JobState, type JobType, MemoryStore, type PaymentJob, type PaymentJobAlertData, type PaymentJobParams, type PaymentJobResult, type PeerEventData, type PendingTlcChangedData, type RetryPolicy, type RpcHealthData, RpcMonitorProxy, type RuntimeConfig, type RuntimeConfigInput, type RuntimeJob, SqliteJobStore, type StdoutAlertConfig, TERMINAL_JOB_STATES, type TrackedInvoiceState, type TrackedPaymentState, type WebhookAlertConfig, type WebsocketAlertConfig, alertPriorityOrder, alertTypeValues, classifyRpcError, computeRetryDelay, createRuntimeConfig, defaultPaymentRetryPolicy, defaultRuntimeConfig, formatRuntimeAlert, isAlertPriority, isAlertType, parseListenAddress, paymentStateMachine, shouldRetry, startRuntimeService };
+export { type Alert, type AlertBackend, type AlertBackendConfig, type AlertFilter, type AlertInput, type AlertPriority, type AlertType, type ChannelBalanceChangedData, type ChannelJob, type ChannelJobAction, type ChannelJobAlertData, type ChannelJobParams, type ChannelJobResult, type ChannelStateChangedData, type ClassifiedError, type ErrorCategory, FiberMonitorService, type FileAlertConfig, type InvoiceJob, type InvoiceJobAction, type InvoiceJobAlertData, type InvoiceJobParams, type InvoiceJobResult, type Job, type JobEvent, type JobEventType, type JobFilter, JobManager, type JobState, type JobType, MemoryStore, type PaymentJob, type PaymentJobAlertData, type PaymentJobParams, type PaymentJobResult, type PaymentProof, PaymentProofManager, type PaymentProofSummary, type PeerEventData, type PendingTlcChangedData, type RetryPolicy, type RpcHealthData, RpcMonitorProxy, type RuntimeConfig, type RuntimeConfigInput, type RuntimeJob, SqliteJobStore, type StdoutAlertConfig, TERMINAL_JOB_STATES, type TrackedInvoiceState, type TrackedPaymentState, type WebhookAlertConfig, type WebsocketAlertConfig, alertPriorityOrder, alertTypeValues, classifyRpcError, computeRetryDelay, createRuntimeConfig, defaultPaymentRetryPolicy, defaultRuntimeConfig, formatRuntimeAlert, isAlertPriority, isAlertType, parseListenAddress, paymentStateMachine, shouldRetry, startRuntimeService };