react-native-nitro-ark 0.0.132 → 0.0.134

package/nitrogen/generated/shared/c++/LightningReceive.hpp

@@ -32,6 +32,7 @@
 
 #include <string>
 #include <optional>
+#include <vector>
 
 namespace margelo::nitro::nitroark {
 
@@ -40,15 +41,19 @@ namespace margelo::nitro::nitroark {
    */
   struct LightningReceive final {
   public:
+    std::string state     SWIFT_PRIVATE;
+    std::optional<std::string> phase     SWIFT_PRIVATE;
     std::string payment_hash     SWIFT_PRIVATE;
     std::string payment_preimage     SWIFT_PRIVATE;
     std::string invoice     SWIFT_PRIVATE;
-    std::optional<double> preimage_revealed_at     SWIFT_PRIVATE;
-    std::optional<double> finished_at     SWIFT_PRIVATE;
+    std::vector<std::string> htlc_vtxo_ids     SWIFT_PRIVATE;
+    std::optional<double> movement_id     SWIFT_PRIVATE;
+    std::optional<double> amount_sat     SWIFT_PRIVATE;
+    std::optional<double> settled_at     SWIFT_PRIVATE;
 
   public:
     LightningReceive() = default;
-    explicit LightningReceive(std::string payment_hash, std::string payment_preimage, std::string invoice, std::optional<double> preimage_revealed_at, std::optional<double> finished_at): payment_hash(payment_hash), payment_preimage(payment_preimage), invoice(invoice), preimage_revealed_at(preimage_revealed_at), finished_at(finished_at) {}
+    explicit LightningReceive(std::string state, std::optional<std::string> phase, std::string payment_hash, std::string payment_preimage, std::string invoice, std::vector<std::string> htlc_vtxo_ids, std::optional<double> movement_id, std::optional<double> amount_sat, std::optional<double> settled_at): state(state), phase(phase), payment_hash(payment_hash), payment_preimage(payment_preimage), invoice(invoice), htlc_vtxo_ids(htlc_vtxo_ids), movement_id(movement_id), amount_sat(amount_sat), settled_at(settled_at) {}
 
   public:
     friend bool operator==(const LightningReceive& lhs, const LightningReceive& rhs) = default;
@@ -64,20 +69,28 @@ namespace margelo::nitro {
     static inline margelo::nitro::nitroark::LightningReceive fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
       jsi::Object obj = arg.asObject(runtime);
       return margelo::nitro::nitroark::LightningReceive(
+        JSIConverter<std::string>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "state"))),
+        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "phase"))),
         JSIConverter<std::string>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "payment_hash"))),
         JSIConverter<std::string>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "payment_preimage"))),
         JSIConverter<std::string>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "invoice"))),
-        JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "preimage_revealed_at"))),
-        JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "finished_at")))
+        JSIConverter<std::vector<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "htlc_vtxo_ids"))),
+        JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "movement_id"))),
+        JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "amount_sat"))),
+        JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "settled_at")))
       );
     }
     static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::nitroark::LightningReceive& arg) {
       jsi::Object obj(runtime);
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "state"), JSIConverter<std::string>::toJSI(runtime, arg.state));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "phase"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.phase));
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "payment_hash"), JSIConverter<std::string>::toJSI(runtime, arg.payment_hash));
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "payment_preimage"), JSIConverter<std::string>::toJSI(runtime, arg.payment_preimage));
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "invoice"), JSIConverter<std::string>::toJSI(runtime, arg.invoice));
-      obj.setProperty(runtime, PropNameIDCache::get(runtime, "preimage_revealed_at"), JSIConverter<std::optional<double>>::toJSI(runtime, arg.preimage_revealed_at));
-      obj.setProperty(runtime, PropNameIDCache::get(runtime, "finished_at"), JSIConverter<std::optional<double>>::toJSI(runtime, arg.finished_at));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "htlc_vtxo_ids"), JSIConverter<std::vector<std::string>>::toJSI(runtime, arg.htlc_vtxo_ids));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "movement_id"), JSIConverter<std::optional<double>>::toJSI(runtime, arg.movement_id));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "amount_sat"), JSIConverter<std::optional<double>>::toJSI(runtime, arg.amount_sat));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "settled_at"), JSIConverter<std::optional<double>>::toJSI(runtime, arg.settled_at));
       return obj;
     }
     static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
@@ -88,11 +101,15 @@ namespace margelo::nitro {
       if (!nitro::isPlainObject(runtime, obj)) {
         return false;
       }
+      if (!JSIConverter<std::string>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "state")))) return false;
+      if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "phase")))) return false;
       if (!JSIConverter<std::string>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "payment_hash")))) return false;
       if (!JSIConverter<std::string>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "payment_preimage")))) return false;
       if (!JSIConverter<std::string>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "invoice")))) return false;
-      if (!JSIConverter<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "preimage_revealed_at")))) return false;
-      if (!JSIConverter<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "finished_at")))) return false;
+      if (!JSIConverter<std::vector<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "htlc_vtxo_ids")))) return false;
+      if (!JSIConverter<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "movement_id")))) return false;
+      if (!JSIConverter<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "amount_sat")))) return false;
+      if (!JSIConverter<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "settled_at")))) return false;
       return true;
     }
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-ark",
-  "version": "0.0.132",
+  "version": "0.0.134",
   "description": "Pure C++ Nitro Modules for Ark client",
   "source": "./src/index.tsx",
   "main": "./lib/module/index.js",
@@ -75,6 +75,7 @@
     "@eslint/js": "^9.22.0",
     "@evilmartians/lefthook": "^1.5.0",
     "@react-native/eslint-config": "^0.81.4",
+    "@react-native/jest-preset": "0.86.0",
     "@release-it/conventional-changelog": "^9.0.2",
     "@types/jest": "^29.5.5",
     "@types/react": "^19.2.0",
@@ -104,7 +105,7 @@
   ],
   "packageManager": "yarn@3.6.1",
   "jest": {
-    "preset": "react-native",
+    "preset": "@react-native/jest-preset",
     "modulePathIgnorePatterns": [
       "<rootDir>/example/node_modules",
       "<rootDir>/lib/"

package/src/NitroArk.nitro.ts

@@ -6,7 +6,6 @@ import type { HybridObject } from 'react-native-nitro-modules';
 
 export interface BarkConfigOpts {
   ark: string;
-  server_access_token?: string;
   /** Client identifier sent as `x-user-agent`, formatted as `<name>/<version>`. */
   user_agent?: string;
   esplora?: string;
@@ -185,6 +184,21 @@ export interface LightningPaymentResult {
   preimage?: string;
 }
 
+export type LightningPaymentOriginMethod =
+  | 'lightning-address'
+  | 'lnurl'
+  | 'custom';
+
+/**
+ * The original user-facing destination that was resolved to a Lightning
+ * invoice outside Bark. Only origin kinds that Bark can persist through this
+ * API are accepted; Rust validates the value again at the native boundary.
+ */
+export interface LightningPaymentOrigin {
+  method: LightningPaymentOriginMethod;
+  value: string;
+}
+
 export interface OnchainPaymentResult {
   txid: string; // Transaction ID
   amount_sat: number; // Amount in satoshis
@@ -229,11 +243,15 @@ export interface MailboxAuthorizationResult {
 }
 
 export interface LightningReceive {
+  state: string;
+  phase?: string;
   payment_hash: string;
   payment_preimage: string;
   invoice: string;
-  preimage_revealed_at?: number;
-  finished_at?: number;
+  htlc_vtxo_ids: string[];
+  movement_id?: number;
+  amount_sat?: number;
+  settled_at?: number;
 }
 
 export interface BarkMovementSubsystem {
@@ -339,9 +357,7 @@ export interface NitroArk extends HybridObject<{ ios: 'c++'; android: 'c++' }> {
   refreshServer(): Promise<void>;
   syncPendingBoards(): Promise<void>;
   maintenance(): Promise<void>;
-  maintenanceWithOnchain(): Promise<void>;
   maintenanceDelegated(): Promise<void>;
-  maintenanceWithOnchainDelegated(): Promise<void>;
   maintenanceRefresh(): Promise<void>;
   sync(): Promise<void>;
 
@@ -410,9 +426,11 @@ export interface NitroArk extends HybridObject<{ ios: 'c++'; android: 'c++' }> {
   ): BarkNotificationSubscription;
   history(): Promise<BarkMovement[]>;
   vtxos(): Promise<BarkVtxo[]>;
+  updateHistoryMetadata(movementId: number, patchJson: string): Promise<void>;
   decodeVtxoHex(vtxoHex: string): Promise<BarkVtxo>;
   importVtxo(vtxoHex: string): Promise<BarkVtxo>;
   dangerousDropVtxo(vtxoId: string): Promise<void>;
+  unlockVtxos(vtxoIds: string[]): Promise<void>;
   refreshVtxosDelegated(
     vtxoIds: string[]
   ): Promise<DelegatedRoundState | undefined>;
@@ -462,6 +480,15 @@ export interface NitroArk extends HybridObject<{ ios: 'c++'; android: 'c++' }> {
     wait: boolean,
     amountSat?: number
   ): Promise<LightningPaymentResult>;
+  /**
+   * Pays an invoice already resolved by the caller while preserving the
+   * original user-facing destination in Bark's movement history.
+   */
+  payLightningInvoiceWithOrigin(
+    invoice: string,
+    origin: LightningPaymentOrigin,
+    wait: boolean
+  ): Promise<LightningPaymentResult>;
   payLightningOffer(
     offer: string,
     wait: boolean,
@@ -483,19 +510,17 @@ export interface NitroArk extends HybridObject<{ ios: 'c++'; android: 'c++' }> {
   // --- Lightning Invoicing ---
   bolt11Invoice(
     amountMsat: number,
-    description?: string
+    description?: string,
+    token?: string
   ): Promise<Bolt11Invoice>;
-  lightningReceiveStatus(
-    paymentHash: string
-  ): Promise<LightningReceive | undefined>;
+  lightningReceiveStatus(paymentHash: string): Promise<LightningReceive>;
   checkLightningPayment(
     paymentHash: string,
     wait: boolean
   ): Promise<LightningPaymentResult>;
   tryClaimLightningReceive(
     paymentHash: string,
-    wait: boolean,
-    token?: string
+    wait: boolean
   ): Promise<LightningReceive>; // Throws on error
   tryClaimAllLightningReceives(wait: boolean): Promise<void>; // Throws on error
 

package/src/index.tsx

@@ -25,7 +25,7 @@ import type {
   NewAddressResult,
   KeyPairResult,
   MailboxAuthorizationResult,
-  LightningReceive,
+  LightningReceive as NitroLightningReceive,
   BarkNotificationEvent as NitroBarkNotificationEvent,
   BarkNotificationSubscription,
   BarkMovement as NitroBarkMovement,
@@ -61,37 +61,79 @@ export type ExitProgressState =
   | 'Claimable'
   | 'ClaimInProgress'
   | 'Claimed'
-  | 'VtxoAlreadySpent';
+  | 'VtxoAlreadySpent'
+  | 'Canceled';
+
+export type ExitStateKind =
+  | 'start'
+  | 'processing'
+  | 'awaiting-delta'
+  | 'claimable'
+  | 'claim-in-progress'
+  | 'claimed'
+  | 'vtxo-already-spent'
+  | 'canceled';
 
 export type BlockRef = NitroExitBlockRefResult;
 export type ExitTxOrigin = NitroExitTxOriginResult;
 export type ExitTxStatus = NitroExitTxStatusResult;
 export type ExitTx = NitroExitTxResult;
-export type ExitStateDetails = NitroExitStateDetailsResult;
+export type ExitStateDetails = Omit<NitroExitStateDetailsResult, 'kind'> & {
+  kind: ExitStateKind;
+};
 
 export type ExitProgressStatusResult = Omit<
   NitroExitProgressStatusResult,
-  'state'
+  'state' | 'state_details'
 > & {
   state: ExitProgressState;
+  state_details: ExitStateDetails;
 };
 
-export type ExitVtxoResult = Omit<NitroExitVtxoResult, 'state' | 'history'> & {
+export type ExitVtxoResult = Omit<
+  NitroExitVtxoResult,
+  'state' | 'state_details' | 'history' | 'history_details'
+> & {
   state: ExitProgressState;
+  state_details: ExitStateDetails;
   history: ExitProgressState[];
+  history_details: ExitStateDetails[];
 };
 
 export type ExitTransactionPackageResult = NitroExitTransactionPackageResult;
 
 export type ExitStatusResult = Omit<
   NitroExitStatusResult,
-  'state' | 'history'
+  'state' | 'state_details' | 'history' | 'history_details'
 > & {
   state: ExitProgressState;
+  state_details: ExitStateDetails;
   history: ExitProgressState[];
+  history_details: ExitStateDetails[];
   transactions: ExitTransactionPackageResult[];
 };
 
+export type LightningReceivePhase =
+  | 'awaiting_payment'
+  | 'htlcs_ready'
+  | 'preimage_revealed';
+
+type LightningReceiveBase = Omit<NitroLightningReceive, 'state' | 'phase'>;
+
+export type LightningReceive =
+  | (LightningReceiveBase & {
+      state: 'in_progress';
+      phase: LightningReceivePhase;
+      amount_sat?: undefined;
+      settled_at?: undefined;
+    })
+  | (LightningReceiveBase & {
+      state: 'settled';
+      phase?: undefined;
+      amount_sat: number;
+      settled_at: number;
+    });
+
 export type BarkMovementDestination = NitroBarkMovementDestination & {
   payment_method:
     | 'ark'
@@ -162,37 +204,85 @@ export type LightningPayment = Omit<LightningPaymentResult, 'state'> & {
   state: LightningPaymentState;
 };
 
+/**
+ * A user-facing payment identifier that has already been resolved to a
+ * Lightning invoice. `custom` preserves protocols Bark does not model
+ * natively while still recording their original identifier.
+ */
+export type LightningPaymentOrigin =
+  | { method: 'lightning-address'; value: string }
+  | { method: 'lnurl'; value: string }
+  | { method: 'custom'; value: string };
+
 export const NitroArkHybridObject =
   NitroModules.createHybridObject<NitroArk>('NitroArk');
 
 function enrichExitProgressStatus(
   result: NitroExitProgressStatusResult
 ): ExitProgressStatusResult {
-  const { state, ...rest } = result;
+  const { state, state_details, ...rest } = result;
   return {
     ...rest,
     state: state as ExitProgressState,
+    state_details: {
+      ...state_details,
+      kind: state_details.kind as ExitStateKind,
+    },
   };
 }
 
 function enrichExitVtxo(result: NitroExitVtxoResult): ExitVtxoResult {
-  const { state, history: stateHistory, ...rest } = result;
+  const {
+    state,
+    state_details,
+    history: stateHistory,
+    history_details,
+    ...rest
+  } = result;
   return {
     ...rest,
     state: state as ExitProgressState,
+    state_details: {
+      ...state_details,
+      kind: state_details.kind as ExitStateKind,
+    },
     history: stateHistory as ExitProgressState[],
+    history_details: history_details.map((details) => ({
+      ...details,
+      kind: details.kind as ExitStateKind,
+    })),
   };
 }
 
 function enrichExitStatus(result: NitroExitStatusResult): ExitStatusResult {
-  const { state, history: stateHistory, ...rest } = result;
+  const {
+    state,
+    state_details,
+    history: stateHistory,
+    history_details,
+    ...rest
+  } = result;
   return {
     ...rest,
     state: state as ExitProgressState,
+    state_details: {
+      ...state_details,
+      kind: state_details.kind as ExitStateKind,
+    },
     history: stateHistory as ExitProgressState[],
+    history_details: history_details.map((details) => ({
+      ...details,
+      kind: details.kind as ExitStateKind,
+    })),
   };
 }
 
+function enrichLightningReceive(
+  result: NitroLightningReceive
+): LightningReceive {
+  return result as LightningReceive;
+}
+
 // --- Management ---
 
 /** Returns the semver of the Bark wallet library compiled into the native module. */
@@ -300,42 +390,16 @@ export function syncPendingBoards(): Promise<void> {
   return NitroArkHybridObject.syncPendingBoards();
 }
 
-/**
- * Runs wallet maintenance tasks for offchain.
- * This includes refreshing vtxos that need to be refreshed.
- * @returns A promise that resolves on success.
- */
+/** Runs wallet maintenance, including on-chain synchronization and exit progression. */
 export function maintenance(): Promise<void> {
   return NitroArkHybridObject.maintenance();
 }
 
-/**
- * Runs wallet maintenance tasks for both offchain and onchain.
- * This includes refreshing vtxos that need to be refreshed.
- * @returns A promise that resolves on success.
- */
-export function maintenanceWithOnchain(): Promise<void> {
-  return NitroArkHybridObject.maintenanceWithOnchain();
-}
-
-/**
- * Runs delegated wallet maintenance tasks for offchain.
- * This includes refreshing vtxos that need to be refreshed using delegated signing.
- * @returns A promise that resolves on success.
- */
+/** Runs delegated wallet maintenance, including on-chain synchronization. */
 export function maintenanceDelegated(): Promise<void> {
   return NitroArkHybridObject.maintenanceDelegated();
 }
 
-/**
- * Runs delegated wallet maintenance tasks for both offchain and onchain.
- * This includes refreshing vtxos that need to be refreshed using delegated signing.
- * @returns A promise that resolves on success.
- */
-export function maintenanceWithOnchainDelegated(): Promise<void> {
-  return NitroArkHybridObject.maintenanceWithOnchainDelegated();
-}
-
 /**
  * Refreshes vtxos that need to be refreshed.
  * @returns A promise that resolves on success.
@@ -704,6 +768,29 @@ export function history(): Promise<BarkMovement[]> {
   return NitroArkHybridObject.history() as Promise<BarkMovement[]>;
 }
 
+/**
+ * Applies an RFC 7396 JSON Merge Patch to a wallet movement's metadata.
+ * The patch must serialize to a JSON object no larger than 16 KiB.
+ * @param movementId The Bark movement ID.
+ * @param patchJson The JSON object merge patch.
+ * @returns A promise that resolves after Bark persists the updated metadata.
+ */
+export function updateHistoryMetadata(
+  movementId: number,
+  patchJson: string
+): Promise<void> {
+  if (
+    !Number.isFinite(movementId) ||
+    !Number.isInteger(movementId) ||
+    movementId < 0 ||
+    movementId > 0xffffffff
+  ) {
+    throw new RangeError('movementId must be a finite unsigned 32-bit integer');
+  }
+
+  return NitroArkHybridObject.updateHistoryMetadata(movementId, patchJson);
+}
+
 /**
  * Gets the list of VTXOs as a JSON string for the loaded wallet.
  * @param no_sync If true, skips synchronization with the blockchain. Defaults to false.
@@ -742,6 +829,15 @@ export function dangerousDropVtxo(vtxoId: string): Promise<void> {
   return NitroArkHybridObject.dangerousDropVtxo(vtxoId);
 }
 
+/**
+ * Unlocks locked VTXOs and returns them to the spendable state.
+ * Already-spendable VTXOs are left unchanged. Spent, unknown, or malformed IDs reject the batch.
+ * @param vtxoIds VTXO IDs to unlock.
+ */
+export function unlockVtxos(vtxoIds: string[]): Promise<void> {
+  return NitroArkHybridObject.unlockVtxos(vtxoIds);
+}
+
 /**
  * Gets the first expiring VTXO blockheight for the loaded wallet.
  * @returns A promise resolving to the first expiring VTXO blockheight.
@@ -877,9 +973,10 @@ export function onchainSendMany(
  */
 export function bolt11Invoice(
   amountMsat: number,
-  description?: string
+  description?: string,
+  token?: string
 ): Promise<Bolt11Invoice> {
-  return NitroArkHybridObject.bolt11Invoice(amountMsat, description);
+  return NitroArkHybridObject.bolt11Invoice(amountMsat, description, token);
 }
 
 /**
@@ -889,8 +986,10 @@ export function bolt11Invoice(
  */
 export function lightningReceiveStatus(
   paymentHash: string
-): Promise<LightningReceive | undefined> {
-  return NitroArkHybridObject.lightningReceiveStatus(paymentHash);
+): Promise<LightningReceive> {
+  return NitroArkHybridObject.lightningReceiveStatus(paymentHash).then(
+    enrichLightningReceive
+  );
 }
 
 /**
@@ -912,21 +1011,17 @@ export function checkLightningPayment(
 }
 
 /**
- * Attempts to claim a Lightning payment, optionally using a claim token.
+ * Attempts to claim a Lightning payment.
  * @param paymentHash The payment hash of the Lightning payment.
  * @param wait Whether to wait for the claim to complete.
- * @param token Optional claim token used when no spendable VTXOs are owned.
- * @returns A promise resolving to the claimed LightningReceive if successful, or null if not.
+ * @returns A promise resolving to the current Lightning receive state.
  */
 export function tryClaimLightningReceive(
   paymentHash: string,
-  wait: boolean,
-  token?: string
+  wait: boolean
 ): Promise<LightningReceive> {
-  return NitroArkHybridObject.tryClaimLightningReceive(
-    paymentHash,
-    wait,
-    token
+  return NitroArkHybridObject.tryClaimLightningReceive(paymentHash, wait).then(
+    enrichLightningReceive
   );
 }
 
@@ -961,6 +1056,46 @@ export function payLightningInvoice(
   }));
 }
 
+/**
+ * Pays a Bolt11 invoice that the caller has already resolved from another
+ * user-facing payment identifier.
+ *
+ * This is a low-level counterpart to helpers such as `payLightningAddress`.
+ * It deliberately performs no remote discovery or callback request. Instead,
+ * it tells Bark which identifier produced the invoice so Bark can persist that
+ * identifier in the Lightning-send checkpoint and movement before settlement.
+ * This keeps payment provenance intact across interruption, history reloads,
+ * and wallet backups instead of recording only the one-time Bolt11 invoice.
+ *
+ * Callers remain responsible for resolving the origin, validating the returned
+ * invoice, and ensuring its amount matches the external protocol request.
+ * This API intentionally has no amount override: the resolved invoice must
+ * contain its exact payment amount.
+ *
+ * The origin becomes durable wallet history and is included in wallet
+ * database backups. Pass the original user-facing identifier, never a callback
+ * URL containing payer data, authorization tokens, or other secrets.
+ *
+ * @param invoice The already-resolved Bolt11 invoice to pay.
+ * @param origin The original destination to store in Bark's movement history.
+ * @param wait Whether to wait for the payment to complete.
+ * @returns A promise resolving to the current Lightning payment state.
+ */
+export function payLightningInvoiceWithOrigin(
+  invoice: string,
+  origin: LightningPaymentOrigin,
+  wait: boolean
+): Promise<LightningPayment> {
+  return NitroArkHybridObject.payLightningInvoiceWithOrigin(
+    invoice,
+    origin,
+    wait
+  ).then((result) => ({
+    ...result,
+    state: result.state as LightningPaymentState,
+  }));
+}
+
 /**
  * Sends a payment to a Bolt12 offer.
  * @param offer The Bolt12 offer.
@@ -1173,5 +1308,4 @@ export type {
   OnchainBalanceResult,
   NewAddressResult,
   KeyPairResult,
-  LightningReceive,
 } from './NitroArk.nitro';