react-native-nitro-ark/src/NitroArk.nitro.ts

Pure C++ Nitro Modules for Ark client

import type { HybridObject } from 'react-native-nitro-modules';

// --- Interfaces matching C structs ---

// Note: BarkError is handled via Promise rejection, not exposed directly.

export interface BarkConfigOpts {
  ark?: string;
  esplora?: string;
  bitcoind?: string;
  bitcoind_cookie?: string;
  bitcoind_user?: string;
  bitcoind_pass?: string;
  vtxo_refresh_expiry_threshold?: number;
  fallback_fee_rate?: number;
  htlc_recv_claim_delta: number;
  vtxo_exit_margin: number;
  round_tx_required_confirmations: number;
}

export interface BarkCreateOpts {
  regtest?: boolean;
  signet?: boolean;
  bitcoin?: boolean;
  mnemonic: string;
  birthday_height?: number;
  config?: BarkConfigOpts;
}

export interface BarkArkInfo {
  network: string;
  server_pubkey: string;
  round_interval: number; // u64
  nb_round_nonces: number; // u16
  vtxo_exit_delta: number; // u16
  vtxo_expiry_delta: number; // u16
  htlc_send_expiry_delta: number; // u16
  max_vtxo_amount: number; // u64
  required_board_confirmations: number; // u8
}

// Helper interface for sendManyOnchain
export interface BarkSendManyOutput {
  destination: string;
  amountSat: number; // uint64_t -> number
}

interface BarkVtxo {
  amount: number; // u64
  expiry_height: number; // u32
  server_pubkey: string;
  exit_delta: number; // u16
  anchor_point: string;
  point: string;
  state: string;
}

export interface BoardResult {
  funding_txid: string;
  vtxos: string[];
}

export interface Bolt11Invoice {
  payment_request: string;
  payment_secret: string;
  payment_hash: string;
}

export interface ArkoorPaymentResult {
  amount_sat: number; // u64
  destination_pubkey: string;
  vtxos: BarkVtxo[];
}

export interface LightningSendResult {
  invoice: string;
  payment_hash: string;
  amount: number; // u64
  htlc_vtxos: BarkVtxo[];
  movement_id: number; // u32
  preimage: string | null;
}

export interface OnchainPaymentResult {
  txid: string; // Transaction ID
  amount_sat: number; // Amount in satoshis
  destination_address: string; // Destination address
}

export interface OffchainBalanceResult {
  spendable: number; // u64
  pending_lightning_send: number; // u64
  pending_in_round: number; // u64
  pending_exit: number; // u64
  pending_board: number; // u64
}

export interface OnchainBalanceResult {
  // All coinbase outputs not yet matured
  immature: number;
  // Unconfirmed UTXOs generated by a wallet tx
  trusted_pending: number;
  // Unconfirmed UTXOs received from an external wallet
  untrusted_pending: number;
  // Confirmed and immediately spendable balance
  confirmed: number;
}

export interface NewAddressResult {
  user_pubkey: string;
  ark_id: string;
  address: string;
}

export interface KeyPairResult {
  public_key: string;
  secret_key: string;
}

export interface LightningReceive {
  payment_hash: string;
  payment_preimage: string;
  invoice: string;
  preimage_revealed_at?: number;
  finished_at?: number;
}

export interface BarkMovementSubsystem {
  name: string;
  kind: string;
}

export interface BarkMovementDestination {
  destination: string;
  payment_method: string;
  amount_sat: number;
}

export interface BarkMovement {
  id: number;
  status: string; // 'pending' | 'finished' | 'failed' | 'cancelled'
  subsystem: BarkMovementSubsystem;
  metadata_json: string;
  intended_balance_sat: number;
  effective_balance_sat: number;
  offchain_fee_sat: number;
  sent_to: BarkMovementDestination[];
  received_on: BarkMovementDestination[];
  input_vtxos: string[];
  output_vtxos: string[];
  exited_vtxos: string[];
  created_at: string;
  updated_at: string;
  completed_at?: string;
}

export type RoundStatusType =
  | 'confirmed'
  | 'unconfirmed'
  | 'pending'
  | 'failed'
  | 'canceled';

export interface RoundStatus {
  status: RoundStatusType;
  funding_txid?: string;
  unsigned_funding_txids?: string[];
  error?: string;
  is_final: boolean;
  is_success: boolean;
}

// --- Nitro Module Interface ---

export interface NitroArk extends HybridObject<{ ios: 'c++'; android: 'c++' }> {
  // --- Management ---
  createMnemonic(): Promise<string>;
  createWallet(datadir: string, opts: BarkCreateOpts): Promise<void>;
  loadWallet(datadir: string, config: BarkCreateOpts): Promise<void>;
  isWalletLoaded(): Promise<boolean>;
  closeWallet(): Promise<void>;
  refreshServer(): Promise<void>;
  syncPendingBoards(): Promise<void>;
  maintenance(): Promise<void>;
  maintenanceWithOnchain(): Promise<void>;
  maintenanceRefresh(): Promise<void>;
  sync(): Promise<void>;
  syncExits(): Promise<void>;
  syncPendingRounds(): Promise<void>;

  // --- Wallet Info ---
  getArkInfo(): Promise<BarkArkInfo>;
  offchainBalance(): Promise<OffchainBalanceResult>;
  deriveStoreNextKeypair(): Promise<KeyPairResult>;
  peakKeyPair(index: number): Promise<KeyPairResult>;
  peakAddress(index: number): Promise<NewAddressResult>;
  newAddress(): Promise<NewAddressResult>;
  signMessage(message: string, index: number): Promise<string>;
  signMesssageWithMnemonic(
    message: string,
    mnemonic: string,
    network: string,
    index: number
  ): Promise<string>;
  deriveKeypairFromMnemonic(
    mnemonic: string,
    network: string,
    index: number
  ): Promise<KeyPairResult>;
  verifyMessage(
    message: string,
    signature: string,
    publicKey: string
  ): Promise<boolean>;
  history(): Promise<BarkMovement[]>;
  vtxos(): Promise<BarkVtxo[]>;
  getFirstExpiringVtxoBlockheight(): Promise<number | undefined>;
  getNextRequiredRefreshBlockheight(): Promise<number | undefined>;
  getExpiringVtxos(threshold: number): Promise<BarkVtxo[]>;

  // --- Onchain Operations ---
  onchainBalance(): Promise<OnchainBalanceResult>;
  onchainSync(): Promise<void>;
  onchainListUnspent(): Promise<string>; // Returns JSON string
  onchainUtxos(): Promise<string>; // Returns JSON string
  onchainAddress(): Promise<string>; // Returns address string
  onchainSend(
    destination: string,
    amountSat: number,
    feeRate?: number // Optional fee rate in sat/vB
  ): Promise<OnchainPaymentResult>; // Returns txid and details
  // Note: feeRate is optional, if not provided, default fee rate will be used
  onchainDrain(
    destination: string,
    feeRate?: number // Optional fee rate in sat/vB
  ): Promise<string>; // Returns txid
  // Note: feeRate is optional, if not provided, default fee rate will be used
  onchainSendMany(
    outputs: BarkSendManyOutput[],
    feeRate?: number // Optional fee rate in sat/vB
  ): Promise<string>; // Returns txid
  // Note: feeRate is optional, if not provided, default fee rate will be used

  // --- Ark & Lightning Payments ---
  boardAmount(amountSat: number): Promise<BoardResult>; // Returns JSON status
  boardAll(): Promise<BoardResult>; // Returns JSON status
  validateArkoorAddress(address: string): Promise<void>;
  sendArkoorPayment(
    destination: string,
    amountSat: number
  ): Promise<ArkoorPaymentResult>;
  payLightningInvoice(
    destination: string,
    amountSat?: number
  ): Promise<LightningSendResult>;
  payLightningOffer(
    offer: string,
    amountSat?: number
  ): Promise<LightningSendResult>;
  payLightningAddress(
    addr: string,
    amountSat: number,
    comment: string
  ): Promise<LightningSendResult>;
  sendRoundOnchainPayment(
    destination: string,
    amountSat: number
  ): Promise<RoundStatus>;

  // --- Lightning Invoicing ---
  bolt11Invoice(amountMsat: number): Promise<Bolt11Invoice>;
  lightningReceiveStatus(
    paymentHash: string
  ): Promise<LightningReceive | undefined>;
  checkLightningPayment(
    paymentHash: string,
    wait: boolean
  ): Promise<string | null>;
  tryClaimLightningReceive(
    paymentHash: string,
    wait: boolean,
    token?: string
  ): Promise<LightningReceive>; // Throws on error
  tryClaimAllLightningReceives(wait: boolean): Promise<void>; // Throws on error

  // --- Offboarding / Exiting ---
  offboardSpecific(
    vtxoIds: string[],
    destinationAddress: string
  ): Promise<RoundStatus>;
  offboardAll(destinationAddress: string): Promise<RoundStatus>;
}