index.d.ts

/* tslint:disable */
/* eslint-disable */

/* auto-generated by NAPI-RS */

export declare function setLogListener(
  callback?: (...args: any[]) => any | undefined | null,
  minLevel?: string | undefined | null,
): void
export declare function generateMnemonic(): string
/**
 * Derive the node public key from a mnemonic and network without building the full node.
 * This replicates the exact derivation path used in `build_with_store_internal()`:
 *   mnemonic -> BIP39 seed -> BIP32 master xprv -> 32-byte secret -> KeysManager -> node_id
 * Runs in ~1ms vs ~4s for full node construction.
 */
export declare function deriveNodeId(mnemonicStr: string, networkStr: string): string
export interface ScoringParamOverrides {
  basePenaltyMsat?: number
  basePenaltyAmountMultiplierMsat?: number
  liquidityPenaltyMultiplierMsat?: number
  liquidityPenaltyAmountMultiplierMsat?: number
  historicalLiquidityPenaltyMultiplierMsat?: number
  historicalLiquidityPenaltyAmountMultiplierMsat?: number
  antiProbingPenaltyMsat?: number
  consideredImpossiblePenaltyMsat?: number
  linearSuccessProbability?: boolean
  probingDiversityPenaltyMsat?: number
  liquidityOffsetHalfLifeSecs?: number
  historicalNoUpdatesHalfLifeSecs?: number
  manualNodePenalties?: Record<string, number>
}
export interface MdkNodeOptions {
  network: string
  mdkApiKey: string
  vssUrl: string
  esploraUrl: string
  rgsUrl: string
  mnemonic: string
  lspNodeId: string
  lspAddress: string
  scoringParamOverrides?: ScoringParamOverrides
}
export interface PaymentMetadata {
  bolt11: string
  paymentHash: string
  expiresAt: number
  scid: string
}
export interface ReceivedPayment {
  paymentHash: string
  amount: number
}
/** Result of a successful outbound payment. */
export interface PaymentResult {
  /** Opaque payment identifier. Always present - can be used to correlate async BOLT12 payments. */
  paymentId: string
  /**
   * The payment hash from the invoice/offer (identifies the HTLC).
   * Available immediately for BOLT11; populated from the PaymentSuccessful event for BOLT12.
   */
  paymentHash?: string
  /** The payment preimage (proof of payment). Available after the payment succeeds. */
  preimage?: string
}
export interface PaymentEvent {
  eventType: PaymentEventType
  paymentHash: string
  amountMsat?: number
  reason?: string
  payerNote?: string
  /** Opaque payment identifier. Present for Sent and Failed (outbound) events. */
  paymentId?: string
  /** Payment preimage (proof of payment). Present for Sent events. */
  preimage?: string
}
export const enum PaymentEventType {
  Claimable = 0,
  Received = 1,
  Failed = 2,
  Sent = 3
}
export interface NodeChannel {
  channelId: string
  counterpartyNodeId: string
  shortChannelId?: string
  inboundCapacityMsat: number
  outboundCapacityMsat: number
  isChannelReady: boolean
  isUsable: boolean
  isPublic: boolean
}
export declare class MdkNode {
  constructor(options: MdkNodeOptions)
  /**
   * Destroy the node, dropping the inner Rust Node and its tokio runtime immediately.
   * This prevents zombie processes on serverless platforms where GC is non-deterministic.
   * After calling destroy(), any further method calls on this node will panic.
   *
   * Always disconnects all peers first to close TCP connections. This is critical on
   * serverless platforms (e.g., Vercel) where the execution context may freeze after the
   * handler returns — a lingering TCP connection tricks the LSP into thinking the peer
   * is still reachable, causing it to forward HTLCs directly instead of intercepting
   * them and sending a webhook.
   */
  destroy(): void
  getNodeId(): string
  start(): void
  stop(): void
  /** Start the node and sync wallets. Call once before polling for events. */
  startReceiving(): void
  /**
   * Get the next payment event without ACKing it.
   * Returns None if no events are available.
   * Call ack_event() after successfully handling the event.
   */
  nextEvent(): PaymentEvent | null
  /**
   * ACK the current event after successfully handling it.
   * Must be called after next_event() returns an event, before calling next_event() again.
   */
  ackEvent(): void
  /** Stop the node. Call when done polling. */
  stopReceiving(): void
  syncWallets(): void
  getBalance(): number
  /**
   * Get balance without starting/stopping the node.
   * Use this when the node is already running via start_receiving().
   */
  getBalanceWhileRunning(): number
  listChannels(): Array<NodeChannel>
  /**
   * Manually sync the RGS snapshot.
   *
   * If `do_full_sync` is true, the RGS snapshot will be updated from scratch. Otherwise, the
   * snapshot will be updated from the last known sync point.
   */
  syncRgs(doFullSync: boolean): number
  receivePayment(minThresholdMs: number, quietThresholdMs: number): Array<ReceivedPayment>
  getInvoice(amount: number, description: string, expirySecs: number): PaymentMetadata
  /**
   * Get invoice without starting/stopping the node.
   * Use this when the node is already running via start_receiving().
   */
  getInvoiceWhileRunning(amount: number, description: string, expirySecs: number): PaymentMetadata
  /**
   * Get variable amount invoice without starting/stopping the node.
   * Use this when the node is already running via start_receiving().
   */
  getVariableAmountJitInvoiceWhileRunning(description: string, expirySecs: number): PaymentMetadata
  getInvoiceWithScid(
    humanReadableScid: string,
    amount: number,
    description: string,
    expirySecs: number,
  ): PaymentMetadata
  getVariableAmountJitInvoice(description: string, expirySecs: number): PaymentMetadata
  getVariableAmountJitInvoiceWithScid(
    humanReadableScid: string,
    description: string,
    expirySecs: number,
  ): PaymentMetadata
  /**
   * Get a BOLT12 offer for receiving via LSPS4 JIT channel.
   * Use this when the node is already running via start_receiving().
   */
  getBolt12OfferWhileRunning(amount: number, description: string, expirySecs?: number | undefined | null): string
  /**
   * Get a variable amount BOLT12 offer for receiving via LSPS4 JIT channel.
   * Use this when the node is already running via start_receiving().
   */
  getVariableAmountBolt12OfferWhileRunning(description: string, expirySecs?: number | undefined | null): string
  /**
   * Register LSPS4 and sync gossip for BOLT12 receive.
   * Call this on startup if you want to accept payments for existing offers.
   */
  setupBolt12Receive(): void
  /**
   * Unified payment method that auto-detects the destination type.
   *
   * Only supports variable-amount destinations where we set the amount:
   * - BOLT12 offers (lno...)
   * - LNURL (lnurl...)
   * - Lightning addresses (user@domain)
   * - Zero-amount BOLT11 invoices
   *
   * For fixed-amount BOLT11 invoices, amount_msat can be omitted (the invoice amount is used).
   * For variable-amount destinations, amount_msat is required.
   */
  pay(
    destination: string,
    amountMsat?: number | undefined | null,
    waitForPaymentSecs?: number | undefined | null,
  ): PaymentResult
  /**
   * Unified payment method that auto-detects the destination type.
   * Use this when the node is already running via start_receiving().
   *
   * Supports all destination types:
   * - BOLT11 invoices (fixed or variable amount)
   * - BOLT12 offers (lno...)
   * - LNURL (lnurl...)
   * - Lightning addresses (user@domain)
   *
   * For fixed-amount BOLT11 invoices, amount_msat can be omitted (the invoice amount is used).
   * For variable-amount destinations, amount_msat is required.
   */
  payWhileRunning(
    destination: string,
    amountMsat?: number | undefined | null,
    waitForPaymentSecs?: number | undefined | null,
  ): PaymentResult
}