@breeztech/breez-sdk-spark 0.18.0-dev4 → 0.19.0

package/nodejs/breez_sdk_spark_wasm_bg.wasm.d.ts

@@ -18,6 +18,8 @@ export const bitcoinchainservicehandle_recommendedFees: (a: number) => any;
 export const breezsdk_addContact: (a: number, b: any) => any;
 export const breezsdk_addEventListener: (a: number, b: any) => any;
 export const breezsdk_authorizeLightningAddressTransfer: (a: number, b: any) => any;
+export const breezsdk_buildUnsignedLnurlPayPackage: (a: number, b: any) => any;
+export const breezsdk_buildUnsignedTransferPackage: (a: number, b: any) => any;
 export const breezsdk_buyBitcoin: (a: number, b: any) => any;
 export const breezsdk_checkLightningAddressAvailable: (a: number, b: any) => any;
 export const breezsdk_checkMessage: (a: number, b: any) => any;
@@ -48,6 +50,8 @@ export const breezsdk_optimizeLeaves: (a: number, b: any) => any;
 export const breezsdk_parse: (a: number, b: number, c: number) => any;
 export const breezsdk_prepareLnurlPay: (a: number, b: any) => any;
 export const breezsdk_prepareSendPayment: (a: number, b: any) => any;
+export const breezsdk_publishSignedLnurlPayPackage: (a: number, b: any) => any;
+export const breezsdk_publishSignedTransferPackage: (a: number, b: any) => any;
 export const breezsdk_receivePayment: (a: number, b: any) => any;
 export const breezsdk_recommendedFees: (a: number) => any;
 export const breezsdk_refundDeposit: (a: number, b: any) => any;
@@ -63,13 +67,18 @@ export const breezsdk_updateContact: (a: number, b: any) => any;
 export const breezsdk_updateUserSettings: (a: number, b: any) => any;
 export const connect: (a: any) => any;
 export const connectWithSigner: (a: any, b: any, c: any, d: number, e: number) => any;
+export const connectWithSigningOnlySigner: (a: any, b: any, c: any, d: number, e: number) => any;
 export const createTurnkeySigner: (a: any) => any;
+export const createTurnkeySigningOnlySigner: (a: any) => any;
 export const defaultConfig: (a: any) => any;
 export const defaultExternalSigners: (a: number, b: number, c: number, d: number, e: any, f: number) => [number, number, number];
 export const defaultMysqlStorageConfig: (a: number, b: number) => any;
 export const defaultPostgresStorageConfig: (a: number, b: number) => any;
 export const defaultServerConfig: (a: any) => any;
+export const defaultSessionStore: (a: number, b: any, c: number, d: number) => any;
 export const defaultStorage: (a: number, b: number) => number;
+export const defaultsessionstore_getSession: (a: number, b: number, c: number) => any;
+export const defaultsessionstore_setSession: (a: number, b: number, c: number, d: any) => any;
 export const externalbreezsignerhandle_decryptEcies: (a: number, b: number, c: number, d: number, e: number) => any;
 export const externalbreezsignerhandle_derivePublicKey: (a: number, b: number, c: number) => any;
 export const externalbreezsignerhandle_encryptEcies: (a: number, b: number, c: number, d: number, e: number) => any;
@@ -79,6 +88,10 @@ export const externalbreezsignerhandle_signEcdsaRecoverable: (a: number, b: any,
 export const externalbreezsignerhandle_signHashSchnorr: (a: number, b: number, c: number, d: number, e: number) => any;
 export const externalsigners_breezSigner: (a: number) => number;
 export const externalsigners_sparkSigner: (a: number) => number;
+export const externalsigningsignerhandle_derivePublicKey: (a: number, b: number, c: number) => any;
+export const externalsigningsignerhandle_signEcdsa: (a: number, b: any, c: number, d: number) => any;
+export const externalsigningsignerhandle_signEcdsaRecoverable: (a: number, b: any, c: number, d: number) => any;
+export const externalsigningsignerhandle_signHashSchnorr: (a: number, b: number, c: number, d: number, e: number) => any;
 export const externalsparksignerhandle_getIdentityPublicKey: (a: number) => any;
 export const externalsparksignerhandle_getPublicKeyForLeaf: (a: number, b: any) => any;
 export const externalsparksignerhandle_getStaticDepositPublicKey: (a: number, b: number) => any;
@@ -110,6 +123,7 @@ export const postgresStorage: (a: any) => number;
 export const sdkbuilder_build: (a: number) => any;
 export const sdkbuilder_new: (a: any, b: any) => number;
 export const sdkbuilder_newWithSigner: (a: any, b: any, c: any) => number;
+export const sdkbuilder_newWithSigningOnlySigner: (a: any, b: any, c: any) => number;
 export const sdkbuilder_withAccountNumber: (a: number, b: number) => number;
 export const sdkbuilder_withChainService: (a: number, b: any) => number;
 export const sdkbuilder_withDefaultStorage: (a: number, b: number, c: number) => any;
@@ -119,6 +133,7 @@ export const sdkbuilder_withMysqlBackend: (a: number, b: any) => [number, number
 export const sdkbuilder_withPaymentObserver: (a: number, b: any) => number;
 export const sdkbuilder_withPostgresBackend: (a: number, b: any) => [number, number, number];
 export const sdkbuilder_withRestChainService: (a: number, b: number, c: number, d: any, e: number) => number;
+export const sdkbuilder_withSessionStore: (a: number, b: any) => number;
 export const sdkbuilder_withSharedContext: (a: number, b: number) => number;
 export const sdkbuilder_withStorage: (a: number, b: any) => number;
 export const sdkbuilder_withStorageBackend: (a: number, b: number) => number;
@@ -149,12 +164,17 @@ export const intounderlyingsink_write: (a: number, b: any) => any;
 export const intounderlyingsource_cancel: (a: number) => void;
 export const intounderlyingsource_pull: (a: number, b: any) => any;
 export const __wbg_externalbreezsignerhandle_free: (a: number, b: number) => void;
+export const __wbg_defaultsessionstore_free: (a: number, b: number) => void;
+export const __wbg_externalsigningsignerhandle_free: (a: number, b: number) => void;
 export const __wbg_externalsparksignerhandle_free: (a: number, b: number) => void;
-export const wasm_bindgen__convert__closures_____invoke__h039d35996dc01d12: (a: number, b: number, c: any) => [number, number];
-export const wasm_bindgen__convert__closures_____invoke__h039d35996dc01d12_6: (a: number, b: number, c: any) => [number, number];
-export const wasm_bindgen__convert__closures_____invoke__h039d35996dc01d12_7: (a: number, b: number, c: any) => [number, number];
-export const wasm_bindgen__convert__closures_____invoke__h039d35996dc01d12_8: (a: number, b: number, c: any) => [number, number];
-export const wasm_bindgen__convert__closures_____invoke__h039d35996dc01d12_9: (a: number, b: number, c: any) => [number, number];
+export const __wbg_signingonlyexternalsigners_free: (a: number, b: number) => void;
+export const signingonlyexternalsigners_breezSigner: (a: number) => number;
+export const signingonlyexternalsigners_sparkSigner: (a: number) => number;
+export const wasm_bindgen__convert__closures_____invoke__h21f6855640435575: (a: number, b: number, c: any) => [number, number];
+export const wasm_bindgen__convert__closures_____invoke__h21f6855640435575_6: (a: number, b: number, c: any) => [number, number];
+export const wasm_bindgen__convert__closures_____invoke__h21f6855640435575_7: (a: number, b: number, c: any) => [number, number];
+export const wasm_bindgen__convert__closures_____invoke__h21f6855640435575_8: (a: number, b: number, c: any) => [number, number];
+export const wasm_bindgen__convert__closures_____invoke__h21f6855640435575_9: (a: number, b: number, c: any) => [number, number];
 export const wasm_bindgen__convert__closures_____invoke__h41057d61edf43a32: (a: number, b: number, c: any, d: any) => void;
 export const wasm_bindgen__convert__closures_____invoke__h3120db8c4a8a92b2: (a: number, b: number, c: any) => void;
 export const wasm_bindgen__convert__closures_____invoke__h3120db8c4a8a92b2_2: (a: number, b: number, c: any) => void;

package/nodejs/index.mjs

@@ -6,12 +6,15 @@ import pkg from './index.js';
 export const {
   connect,
   connectWithSigner,
+  connectWithSigningOnlySigner,
   createTurnkeySigner,
+  createTurnkeySigningOnlySigner,
   defaultConfig,
   defaultExternalSigners,
   defaultMysqlStorageConfig,
   defaultPostgresStorageConfig,
   defaultServerConfig,
+  defaultSessionStore,
   defaultStorage,
   getSparkStatus,
   initLogging,
@@ -23,8 +26,10 @@ export const {
   task_worker_entry_point,
   BitcoinChainServiceHandle,
   BreezSdk,
+  DefaultSessionStore,
   ExternalBreezSignerHandle,
   ExternalSigners,
+  ExternalSigningSignerHandle,
   ExternalSparkSignerHandle,
   IntoUnderlyingByteSource,
   IntoUnderlyingSink,
@@ -32,6 +37,7 @@ export const {
   PasskeyClient,
   PasskeyLabels,
   SdkBuilder,
+  SigningOnlyExternalSigners,
   TokenIssuer,
   WasmSdkContext,
   WasmStorageConfig,

package/nodejs/mysql-token-store/index.cjs

@@ -658,7 +658,7 @@ class MysqlTokenStore {
 
         let outputs = outputRows.map((row) => this._outputFromRow(row));
 
-        if (preferredOutputs && preferredOutputs.length > 0) {
+        if (preferredOutputs) {
           const preferredOutpoints = new Set(
             preferredOutputs.map((p) => `${p.prevTxHash}:${p.prevTxVout}`)
           );
@@ -667,75 +667,11 @@ class MysqlTokenStore {
           );
         }
 
-        let selectedOutputs;
-
-        if (target.type === "minTotalValue") {
-          const amount = BigInt(target.value);
-
-          const totalAvailable = outputs.reduce(
-            (sum, o) => sum + BigInt(o.output.tokenAmount),
-            0n
-          );
-          if (totalAvailable < amount) {
-            throw new TokenStoreError("InsufficientFunds");
-          }
-
-          const exactMatch = outputs.find(
-            (o) => BigInt(o.output.tokenAmount) === amount
-          );
-          if (exactMatch) {
-            selectedOutputs = [exactMatch];
-          } else {
-            if (selectionStrategy === "LargestFirst") {
-              outputs.sort(
-                (a, b) =>
-                  Number(
-                    BigInt(b.output.tokenAmount) - BigInt(a.output.tokenAmount)
-                  )
-              );
-            } else {
-              outputs.sort(
-                (a, b) =>
-                  Number(
-                    BigInt(a.output.tokenAmount) - BigInt(b.output.tokenAmount)
-                  )
-              );
-            }
-
-            selectedOutputs = [];
-            let remaining = amount;
-            for (const output of outputs) {
-              if (remaining <= 0n) break;
-              selectedOutputs.push(output);
-              remaining -= BigInt(output.output.tokenAmount);
-            }
-            if (remaining > 0n) {
-              throw new TokenStoreError("InsufficientFunds");
-            }
-          }
-        } else if (target.type === "maxOutputCount") {
-          const count = target.value;
-
-          if (selectionStrategy === "LargestFirst") {
-            outputs.sort(
-              (a, b) =>
-                Number(
-                  BigInt(b.output.tokenAmount) - BigInt(a.output.tokenAmount)
-                )
-            );
-          } else {
-            outputs.sort(
-              (a, b) =>
-                Number(
-                  BigInt(a.output.tokenAmount) - BigInt(b.output.tokenAmount)
-                )
-            );
-          }
-
-          selectedOutputs = outputs.slice(0, count);
-        } else {
-          throw new TokenStoreError(`Unknown target type: ${target.type}`);
-        }
+        const selectedOutputs = this._selectOutputs(
+          outputs,
+          target,
+          selectionStrategy
+        );
 
         const reservationId = this._generateId();
 
@@ -773,6 +709,212 @@ class MysqlTokenStore {
     }
   }
 
+  _selectOutputs(outputs, target, selectionStrategy) {
+    if (target.type === "minTotalValue") {
+      const amount = BigInt(target.value);
+      const totalAvailable = outputs.reduce(
+        (sum, o) => sum + BigInt(o.output.tokenAmount),
+        0n
+      );
+      if (totalAvailable < amount) {
+        throw new TokenStoreError("InsufficientFunds");
+      }
+
+      const exactMatch = outputs.find(
+        (o) => BigInt(o.output.tokenAmount) === amount
+      );
+      if (exactMatch) {
+        return [exactMatch];
+      }
+
+      if (selectionStrategy === "LargestFirst") {
+        outputs.sort(
+          (a, b) =>
+            Number(BigInt(b.output.tokenAmount) - BigInt(a.output.tokenAmount))
+        );
+      } else {
+        outputs.sort(
+          (a, b) =>
+            Number(BigInt(a.output.tokenAmount) - BigInt(b.output.tokenAmount))
+        );
+      }
+
+      const selected = [];
+      let remaining = amount;
+      for (const output of outputs) {
+        if (remaining <= 0n) break;
+        selected.push(output);
+        remaining -= BigInt(output.output.tokenAmount);
+      }
+      if (remaining > 0n) {
+        throw new TokenStoreError("InsufficientFunds");
+      }
+      return selected;
+    }
+
+    if (target.type === "maxOutputCount") {
+      const count = target.value;
+      if (selectionStrategy === "LargestFirst") {
+        outputs.sort(
+          (a, b) =>
+            Number(BigInt(b.output.tokenAmount) - BigInt(a.output.tokenAmount))
+        );
+      } else {
+        outputs.sort(
+          (a, b) =>
+            Number(BigInt(a.output.tokenAmount) - BigInt(b.output.tokenAmount))
+        );
+      }
+      return outputs.slice(0, count);
+    }
+
+    throw new TokenStoreError(`Unknown target type: ${target.type}`);
+  }
+
+  async selectTokenOutputs(
+    tokenIdentifier,
+    target,
+    preferredOutputs,
+    selectionStrategy
+  ) {
+    try {
+      if (
+        target.type === "minTotalValue" &&
+        (!target.value || target.value === "0")
+      ) {
+        throw new TokenStoreError("Amount to reserve must be greater than zero");
+      }
+      if (
+        target.type === "maxOutputCount" &&
+        (!target.value || target.value === 0)
+      ) {
+        throw new TokenStoreError("Count to reserve must be greater than zero");
+      }
+
+      const [metadataRows] = await this.pool.query(
+        "SELECT * FROM brz_token_metadata WHERE user_id = ? AND identifier = ?",
+        [this.identity, tokenIdentifier]
+      );
+      if (metadataRows.length === 0) {
+        throw new TokenStoreError(
+          `Token outputs not found for identifier: ${tokenIdentifier}`
+        );
+      }
+      const metadata = this._metadataFromRow(metadataRows[0]);
+
+      const [outputRows] = await this.pool.query(
+        `SELECT o.owner_public_key, o.revocation_commitment,
+                o.withdraw_bond_sats, o.withdraw_relative_block_locktime,
+                o.token_public_key, o.token_amount, o.token_identifier,
+                o.prev_tx_hash, o.prev_tx_vout
+         FROM brz_token_outputs o
+         WHERE o.user_id = ? AND o.token_identifier = ? AND o.reservation_id IS NULL`,
+        [this.identity, tokenIdentifier]
+      );
+
+      let outputs = outputRows.map((row) => this._outputFromRow(row));
+
+      if (preferredOutputs) {
+        const preferredOutpoints = new Set(
+          preferredOutputs.map((p) => `${p.prevTxHash}:${p.prevTxVout}`)
+        );
+        outputs = outputs.filter((o) =>
+          preferredOutpoints.has(`${o.prevTxHash}:${o.prevTxVout}`)
+        );
+      }
+
+      const selectedOutputs = this._selectOutputs(
+        outputs,
+        target,
+        selectionStrategy
+      );
+      return { metadata, outputs: selectedOutputs };
+    } catch (error) {
+      if (error instanceof TokenStoreError) throw error;
+      throw new TokenStoreError(
+        `Failed to select token outputs: ${error.message}`,
+        error
+      );
+    }
+  }
+
+  async reserveTokenOutputsByOutpoints(tokenIdentifier, outpoints, purpose) {
+    try {
+      if (!outpoints || outpoints.length === 0) {
+        throw new TokenStoreError("No outpoints provided");
+      }
+      return await this._withWriteTransaction(async (conn) => {
+        const [metadataRows] = await conn.query(
+          "SELECT * FROM brz_token_metadata WHERE user_id = ? AND identifier = ?",
+          [this.identity, tokenIdentifier]
+        );
+        if (metadataRows.length === 0) {
+          throw new TokenStoreError(
+            `Token outputs not found for identifier: ${tokenIdentifier}`
+          );
+        }
+        const metadata = this._metadataFromRow(metadataRows[0]);
+
+        const pairPlaceholders = outpoints.map(() => "(?, ?)").join(", ");
+        const selectParams = [this.identity, tokenIdentifier];
+        for (const o of outpoints) {
+          selectParams.push(o.prevTxHash, o.prevTxVout);
+        }
+        const [outputRows] = await conn.query(
+          `SELECT o.owner_public_key, o.revocation_commitment,
+                  o.withdraw_bond_sats, o.withdraw_relative_block_locktime,
+                  o.token_public_key, o.token_amount, o.token_identifier,
+                  o.prev_tx_hash, o.prev_tx_vout
+           FROM brz_token_outputs o
+           WHERE o.user_id = ? AND o.token_identifier = ? AND o.reservation_id IS NULL
+             AND (o.prev_tx_hash, o.prev_tx_vout) IN (${pairPlaceholders})`,
+          selectParams
+        );
+
+        const selectedOutputs = outputRows.map((row) =>
+          this._outputFromRow(row)
+        );
+
+        const distinct = new Set(
+          outpoints.map((o) => `${o.prevTxHash}:${o.prevTxVout}`)
+        );
+        if (selectedOutputs.length !== distinct.size) {
+          throw new TokenStoreError("InsufficientFunds");
+        }
+
+        const reservationId = this._generateId();
+        await conn.query(
+          "INSERT INTO brz_token_reservations (user_id, id, purpose, created_at) VALUES (?, ?, ?, UTC_TIMESTAMP(6))",
+          [this.identity, reservationId, purpose]
+        );
+
+        const updatePlaceholders = selectedOutputs
+          .map(() => "(?, ?)")
+          .join(", ");
+        const updateParams = [reservationId, this.identity];
+        for (const o of selectedOutputs) {
+          updateParams.push(o.prevTxHash, o.prevTxVout);
+        }
+        await conn.query(
+          `UPDATE brz_token_outputs SET reservation_id = ? WHERE user_id = ?
+             AND (prev_tx_hash, prev_tx_vout) IN (${updatePlaceholders})`,
+          updateParams
+        );
+
+        return {
+          id: reservationId,
+          tokenOutputs: { metadata, outputs: selectedOutputs },
+        };
+      });
+    } catch (error) {
+      if (error instanceof TokenStoreError) throw error;
+      throw new TokenStoreError(
+        `Failed to reserve token outputs by outpoints: ${error.message}`,
+        error
+      );
+    }
+  }
+
   async cancelReservation(id) {
     try {
       await this._withTransaction(async (conn) => {

package/nodejs/mysql-tree-store/index.cjs

@@ -43,6 +43,36 @@ const WRITE_LOCK_TIMEOUT_SECS = 30;
 const RESERVATION_TIMEOUT_SECS = 300;
 const SPENT_MARKER_CLEANUP_THRESHOLD_MS = 5 * 60 * 1000;
 
+/**
+ * Slim projection: only (id, value) for leaves the selection might use.
+ * Includes all leaves with value <= the max target (covers exact-match + the
+ * small-leaf accumulators for the minimum-amount path) plus the single
+ * smallest leaf with a larger value (covers the minimum-amount fallback case
+ * where one larger leaf is sufficient).
+ * Params: user id, max target, user id, max target.
+ */
+const SLIM_LEAF_CANDIDATES_SQL = `SELECT id, value
+  FROM brz_tree_leaves
+  WHERE user_id = ?
+    AND status = 'Available'
+    AND is_missing_from_operators = 0
+    AND reservation_id IS NULL
+    AND (
+      value <= ?
+      OR id = (
+        SELECT id FROM (
+          SELECT id FROM brz_tree_leaves
+          WHERE user_id = ?
+            AND status = 'Available'
+            AND is_missing_from_operators = 0
+            AND reservation_id IS NULL
+            AND value > ?
+          ORDER BY value
+          LIMIT 1
+        ) AS smallest_over
+      )
+    )`;
+
 /**
  * Derive a stable per-tenant lock name from a tenant identity pubkey. Hashes
  * a domain prefix together with the identity (SHA-256, first 8 bytes hex).
@@ -245,6 +275,32 @@ class MysqlTreeStore {
     }
   }
 
+  async getVerifiedLeafKeys() {
+    try {
+      // Project just the two pubkeys out of the JSON, skipping each leaf's
+      // `data` blob (up to five transactions). The filter matches the verified
+      // categories the SDK expects: every reserved leaf plus every Available
+      // one, and nothing non-Available and unreserved.
+      const [rows] = await this.pool.query(
+        `SELECT l.id AS id,
+                l.data->>'$.verifying_public_key' AS verifying,
+                l.data->>'$.signing_keyshare.public_key' AS keyshare
+         FROM brz_tree_leaves l
+         LEFT JOIN brz_tree_reservations r
+           ON l.reservation_id = r.id AND l.user_id = r.user_id
+         WHERE l.user_id = ?
+           AND (r.purpose IS NOT NULL OR l.status = 'Available')`,
+        [this.identity]
+      );
+      return rows.map((row) => [row.id, row.verifying, row.keyshare]);
+    } catch (error) {
+      throw new TreeStoreError(
+        `Failed to get verified leaf keys: ${error.message}`,
+        error
+      );
+    }
+  }
+
   async getLeaves() {
     try {
       const [rows] = await this.pool.query(
@@ -462,30 +518,12 @@ class MysqlTreeStore {
         );
         const available = Number(totalRows[0].total);
 
-        const [slimRows] = await conn.query(
-          `SELECT id, value
-           FROM brz_tree_leaves
-           WHERE user_id = ?
-             AND status = 'Available'
-             AND is_missing_from_operators = 0
-             AND reservation_id IS NULL
-             AND (
-               value <= ?
-               OR id = (
-                 SELECT id FROM (
-                   SELECT id FROM brz_tree_leaves
-                   WHERE user_id = ?
-                     AND status = 'Available'
-                     AND is_missing_from_operators = 0
-                     AND reservation_id IS NULL
-                     AND value > ?
-                   ORDER BY value
-                   LIMIT 1
-                 ) AS smallest_over
-               )
-             )`,
-          [this.identity, maxTarget, this.identity, maxTarget]
-        );
+        const [slimRows] = await conn.query(SLIM_LEAF_CANDIDATES_SQL, [
+          this.identity,
+          maxTarget,
+          this.identity,
+          maxTarget,
+        ]);
 
         const slimLeaves = slimRows.map((r) => ({
           id: r.id,
@@ -579,6 +617,86 @@ class MysqlTreeStore {
     }
   }
 
+  async trySelectLeaves(targetAmounts) {
+    try {
+      const targetAmount = targetAmounts ? this._totalSats(targetAmounts) : 0;
+      const maxTarget = this._maxTargetForPrefilter(targetAmounts);
+
+      return await this._withTransaction(async (conn) => {
+        const [slimRows] = await conn.query(SLIM_LEAF_CANDIDATES_SQL, [
+          this.identity,
+          maxTarget,
+          this.identity,
+          maxTarget,
+        ]);
+
+        const slimLeaves = slimRows.map((r) => ({
+          id: r.id,
+          value: Number(r.value),
+        }));
+
+        const selected = this._selectLeavesByTargetAmounts(slimLeaves, targetAmounts);
+        if (selected !== null && selected.length > 0) {
+          const fullLeaves = await this._fetchFullLeavesByIds(
+            conn,
+            selected.map((l) => l.id)
+          );
+          return { type: "exact", leaves: fullLeaves };
+        }
+
+        const minSelected = this._selectLeavesByMinimumAmount(slimLeaves, targetAmount);
+        if (minSelected !== null) {
+          const fullLeaves = await this._fetchFullLeavesByIds(
+            conn,
+            minSelected.map((l) => l.id)
+          );
+          return { type: "swapNeeded", leaves: fullLeaves };
+        }
+
+        return { type: "insufficientFunds" };
+      });
+    } catch (error) {
+      if (error instanceof TreeStoreError) throw error;
+      throw new TreeStoreError(
+        `Failed to try select leaves: ${error.message}`,
+        error
+      );
+    }
+  }
+
+  async tryReserveLeavesByIds(leafIds, purpose) {
+    try {
+      return await this._withWriteTransaction(async (conn) => {
+        if (!leafIds || leafIds.length === 0) {
+          throw new TreeStoreError("NonReservableLeaves");
+        }
+        // Every requested leaf must be available and unreserved; otherwise
+        // reserve nothing (the transaction rolls back).
+        const placeholders = leafIds.map(() => "?").join(", ");
+        const [availableRows] = await conn.query(
+          `SELECT id FROM brz_tree_leaves
+           WHERE user_id = ? AND id IN (${placeholders})
+             AND status = 'Available' AND is_missing_from_operators = 0
+             AND reservation_id IS NULL`,
+          [this.identity, ...leafIds]
+        );
+        if (availableRows.length !== leafIds.length) {
+          throw new TreeStoreError("NonReservableLeaves");
+        }
+        const fullLeaves = await this._fetchFullLeavesByIds(conn, leafIds);
+        const reservationId = this._generateId();
+        await this._createReservation(conn, reservationId, fullLeaves, purpose, 0);
+        return { id: reservationId, leaves: fullLeaves };
+      });
+    } catch (error) {
+      if (error instanceof TreeStoreError) throw error;
+      throw new TreeStoreError(
+        `Failed to try reserve leaves by ids: ${error.message}`,
+        error
+      );
+    }
+  }
+
   async now() {
     try {
       const [rows] = await this.pool.query("SELECT UTC_TIMESTAMP(6) AS now");
@@ -682,10 +800,24 @@ class MysqlTreeStore {
     if (!ids || ids.length === 0) return [];
     const placeholders = ids.map(() => "?").join(", ");
     const [rows] = await conn.query(
-      `SELECT data FROM brz_tree_leaves WHERE user_id = ? AND id IN (${placeholders})`,
+      `SELECT id, data FROM brz_tree_leaves WHERE user_id = ? AND id IN (${placeholders})`,
       [this.identity, ...ids]
     );
-    return rows.map((r) => parseJson(r.data));
+    const byId = new Map(rows.map((r) => [r.id, r.data]));
+    const ordered = ids
+      .map((id) => {
+        const data = byId.get(id);
+        byId.delete(id);
+        return data;
+      })
+      .filter((data) => data !== undefined)
+      .map((data) => parseJson(data));
+    if (ordered.length !== ids.length) {
+      throw new TreeStoreError(
+        `Could not resolve full data for all selected leaves (wanted ${ids.length}, got ${ordered.length})`
+      );
+    }
+    return ordered;
   }
 
   _selectLeavesByTargetAmounts(leaves, targetAmounts) {