@unicitylabs/sphere-sdk 0.17.6 → 0.18.0-dev.2

package/dist/modules/payments-v2/index.cjs

@@ -2036,6 +2036,8 @@ var STORE_KEYS = {
   deliveryJournal: "delivery-journal",
   mintJournal: "mint-journal",
   nftMintJournal: "nft-mint-journal",
+  customMintJournal: "custom-mint-journal",
+  burnJournal: "burn-journal",
   shortfalls: "shortfalls",
   settlingLinks: "settling",
   streamCursor: (s) => `cursor:${s}`,
@@ -3301,6 +3303,8 @@ function createMachineStores(kv) {
     deliveryJournal: new DeliveryJournal(kv),
     mintJournal: new ListStore(kv, STORE_KEYS.mintJournal, (e) => e.mintId),
     nftMintJournal: new ListStore(kv, STORE_KEYS.nftMintJournal, (e) => e.mintId),
+    customMintJournal: new ListStore(kv, STORE_KEYS.customMintJournal, (e) => e.mintId),
+    burnJournal: new ListStore(kv, STORE_KEYS.burnJournal, (e) => e.burnId),
     shortfalls: new ListStore(kv, STORE_KEYS.shortfalls, (e) => e.transferId)
   };
 }
@@ -4036,7 +4040,12 @@ var Converger = class {
     } catch (err) {
       retryAfterMs ??= retryAfterMsOf(err);
     }
-    for (const replay of [() => this.deps.replayMints(), () => this.deps.replayNftMints()]) {
+    for (const replay of [
+      () => this.deps.replayMints(),
+      () => this.deps.replayNftMints(),
+      () => this.deps.replayCustomMints(),
+      () => this.deps.replayBurns()
+    ]) {
       try {
         progress = await replay() > 0 || progress;
       } catch (err) {
@@ -4047,14 +4056,17 @@ var Converger = class {
   }
   /** §4 heartbeat predicate — read fresh from the §6 stores, never cached. */
   async pendingWork() {
-    const [backstop, journal, mints, nftMints] = await Promise.all([
+    const [backstop, journal, mints, nftMints, customMints, burns] = await Promise.all([
       this.deps.stores.backstop.list(),
       this.deps.stores.deliveryJournal.list(),
       this.deps.stores.mintJournal.list(),
-      this.deps.stores.nftMintJournal.list()
+      this.deps.stores.nftMintJournal.list(),
+      this.deps.stores.customMintJournal.list(),
+      this.deps.stores.burnJournal.list()
     ]);
-    const mintsOpen = mints.length > 0 || nftMints.length > 0;
-    return backstop.length > 0 || journal.some((e) => e.undeliverable !== true) || mintsOpen;
+    const mintsOpen = mints.length > 0 || nftMints.length > 0 || customMints.length > 0;
+    const burnsOpen = burns.some((e) => !e.settled);
+    return backstop.length > 0 || journal.some((e) => e.undeliverable !== true) || mintsOpen || burnsOpen;
   }
   async resumePass() {
     const report = await resumeAll(this.filteredMachineDeps(), {
@@ -4802,6 +4814,7 @@ function mintParams(recipientPubkey, coinId, amount) {
 
 // modules/payments-v2/mint.ts
 var ATTENTION_MINT_UNRESOLVED = "mint:unresolved";
+var INVENTORY_SCAN_PAGE_LIMIT = 50;
 function runMintUnderJournal(deps, input) {
   return mintUnderJournal(deps, input);
 }
@@ -4854,6 +4867,15 @@ async function finalizeMint(deps, input) {
   deps.noteHeldState(token.blob.tokenId, (await deps.engine.deliveryKeys(bytes)).stateHash);
   deps.refreshView();
 }
+async function tokenInServerInventory(storagePort, tokenId) {
+  let page = await storagePort.listInventory();
+  for (let i = 0; i < INVENTORY_SCAN_PAGE_LIMIT; i++) {
+    if (page.items.some((item) => item.tokenId === tokenId && item.status === "active")) return true;
+    if (!page.more) return false;
+    page = await storagePort.listInventory(page.cursor);
+  }
+  return false;
+}
 async function replayCoinMints(deps) {
   let resolved = 0;
   for (const entry of await deps.mintJournal.list()) {
@@ -5031,6 +5053,12 @@ async function decodeView(deps, tokenId, bytes) {
 
 // modules/payments-v2/inventory/token-data.ts
 async function readTokenData(deps, tokenId) {
+  return deps.engine.readTokenData(await heldToken(deps, tokenId));
+}
+async function readTokenJustification(deps, tokenId) {
+  return deps.engine.readTokenJustification(await heldToken(deps, tokenId));
+}
+async function heldToken(deps, tokenId) {
   if (deps.view.stateHashOf(tokenId) === void 0) {
     throw new SphereError(`Token ${tokenId} is not in inventory`, "VALIDATION_ERROR");
   }
@@ -5038,7 +5066,200 @@ async function readTokenData(deps, tokenId) {
   if (bytes === void 0) {
     throw new SphereError(`Token ${tokenId} has no blob in storage`, "STORAGE_ERROR");
   }
-  return deps.engine.readTokenData(await deps.engine.decodeToken({ tokenId, token: bytes }));
+  return deps.engine.decodeToken({ tokenId, token: bytes });
+}
+
+// modules/payments-v2/mint-custom.ts
+var HEX32 = /^[0-9a-f]{64}$/;
+function assertRequest(request) {
+  if (request.tokenType.length !== 32) {
+    throw new SphereError("mintCustom: tokenType must be 32 bytes", "VALIDATION_ERROR");
+  }
+  if (request.salt.length < 16 || request.salt.length > 64) {
+    throw new SphereError("mintCustom: salt must be 16 to 64 bytes", "VALIDATION_ERROR");
+  }
+  if (request.data.length === 0) {
+    throw new SphereError("mintCustom: data must not be empty", "VALIDATION_ERROR");
+  }
+  for (const asset of request.assets) {
+    if (!HEX32.test(asset.coinId) || asset.amount <= 0n) {
+      throw new SphereError("mintCustom: assets need a 64-hex coinId and a positive amount", "VALIDATION_ERROR");
+    }
+  }
+}
+async function runCustomMintUnderJournal(deps, input) {
+  try {
+    assertRequest(input.request);
+  } catch (err) {
+    return { success: false, error: messageOf(err) };
+  }
+  const entry = journalEntryOf2(input.mintId, input.request, deps.now());
+  await deps.customMintJournal.upsert(entry);
+  let tokenId;
+  try {
+    tokenId = await mintJournaled2(deps, entry, input.request.mintJustificationVerifiers);
+  } catch (err) {
+    deps.armHeartbeat();
+    return { success: false, error: messageOf(err) };
+  }
+  return { success: true, tokenId };
+}
+async function replayCustomMints(deps) {
+  let resolved = 0;
+  for (const entry of await deps.customMintJournal.list()) {
+    if (deps.isActiveOp(entry.mintId)) continue;
+    try {
+      if (entry.tokenId !== "" && await deps.tokenInServerInventory(entry.tokenId)) {
+        await deps.customMintJournal.removeByKey(entry.mintId);
+      } else {
+        await mintJournaled2(deps, entry, void 0);
+      }
+      resolved += 1;
+    } catch {
+      continue;
+    }
+  }
+  return resolved;
+}
+function journalEntryOf2(mintId, request, createdAt) {
+  return {
+    mintId,
+    tokenId: "",
+    dataHex: bytesToHex(request.data),
+    saltHex: bytesToHex(request.salt),
+    tokenTypeHex: bytesToHex(request.tokenType),
+    justificationHex: request.justification ? bytesToHex(request.justification) : null,
+    assets: request.assets.map((a) => ({ coinId: a.coinId, amount: a.amount.toString() })),
+    createdAt
+  };
+}
+async function mintJournaled2(deps, entry, mintJustificationVerifiers) {
+  const token = await deps.engine.mintDataToken(
+    {
+      recipientPubkey: deps.ownPubkeyBytes,
+      data: hexToBytes(entry.dataHex),
+      tokenType: hexToBytes(entry.tokenTypeHex),
+      salt: hexToBytes(entry.saltHex),
+      ...entry.justificationHex !== null ? { justification: hexToBytes(entry.justificationHex) } : {},
+      ...mintJustificationVerifiers ? { mintJustificationVerifiers } : {}
+    },
+    { transferId: entry.mintId }
+  );
+  if (entry.tokenId !== "" && token.blob.tokenId !== entry.tokenId) {
+    throw new SphereError(`minted token ${token.blob.tokenId}, but the journal names ${entry.tokenId}`, "VALIDATION_ERROR");
+  }
+  if (entry.tokenId === "") {
+    await deps.customMintJournal.upsert({ ...entry, tokenId: token.blob.tokenId });
+  }
+  await finalizeMint(deps, {
+    mintId: entry.mintId,
+    token,
+    assets: entry.assets,
+    journal: deps.customMintJournal
+  });
+  return token.blob.tokenId;
+}
+
+// modules/payments-v2/burn.ts
+var HEX322 = /^[0-9a-f]{64}$/;
+async function heldToken2(deps, tokenId) {
+  const bytes = (await deps.storagePort.getBlobs([tokenId])).get(tokenId);
+  if (bytes === void 0) {
+    throw new SphereError(`Token ${tokenId} has no blob in storage; it is not held here`, "STORAGE_ERROR");
+  }
+  return deps.engine.decodeToken({ tokenId, token: bytes });
+}
+function assetsOf(token) {
+  return (token.value?.assets ?? []).map((a) => ({ coinId: a.coinId, amount: a.amount.toString() }));
+}
+async function runBurnUnderJournal(deps, input) {
+  const { burnId } = input;
+  const { tokenId, reasonBytes } = input.request;
+  if (!HEX322.test(tokenId) || reasonBytes.length === 0) {
+    return { success: false, burnId, tokenId, error: "burn: tokenId must be 64 hex and reasonBytes non-empty" };
+  }
+  let token;
+  try {
+    token = await heldToken2(deps, tokenId);
+    if (!deps.engine.isOwnedBy(token, deps.engine.getIdentity().chainPubkey)) {
+      throw new SphereError(`Token ${tokenId} is not owned by this wallet`, "VALIDATION_ERROR");
+    }
+  } catch (err) {
+    return { success: false, burnId, tokenId, error: messageOf(err) };
+  }
+  const entry = {
+    burnId,
+    tokenId,
+    reasonHex: bytesToHex(reasonBytes),
+    burnedTokenHex: null,
+    settled: false,
+    assets: assetsOf(token),
+    createdAt: deps.now()
+  };
+  await deps.burnJournal.upsert(entry);
+  try {
+    const settled = await burnJournaled(deps, entry, token, { applied: false });
+    return { success: true, burnId, tokenId, burnedToken: hexToBytes(settled.burnedTokenHex ?? "") };
+  } catch (err) {
+    deps.armHeartbeat();
+    return { success: false, burnId, tokenId, error: messageOf(err) };
+  }
+}
+async function replayBurns(deps) {
+  let progressed = 0;
+  for (const entry of await deps.burnJournal.list()) {
+    if (entry.settled || deps.isActiveOp(entry.burnId)) continue;
+    try {
+      const token = entry.burnedTokenHex === null ? await heldToken2(deps, entry.tokenId) : null;
+      const applied = entry.burnedTokenHex !== null && !await deps.tokenInServerInventory(entry.tokenId);
+      await burnJournaled(deps, entry, token, { applied });
+      progressed += 1;
+    } catch {
+      continue;
+    }
+  }
+  return progressed;
+}
+async function pendingBurns(deps) {
+  return (await deps.burnJournal.list()).map((entry) => ({
+    burnId: entry.burnId,
+    tokenId: entry.tokenId,
+    reasonBytes: hexToBytes(entry.reasonHex),
+    burnedToken: entry.burnedTokenHex === null ? null : hexToBytes(entry.burnedTokenHex),
+    settled: entry.settled,
+    createdAt: entry.createdAt
+  }));
+}
+async function acknowledgeBurn(deps, burnId) {
+  const entry = await deps.burnJournal.getByKey(burnId);
+  if (entry === void 0) return;
+  if (!entry.settled) {
+    throw new SphereError(`Burn ${burnId} is not settled yet; it cannot be acknowledged`, "VALIDATION_ERROR");
+  }
+  await deps.burnJournal.removeByKey(burnId);
+}
+async function burnJournaled(deps, entry, token, state) {
+  let current = entry;
+  if (current.burnedTokenHex === null) {
+    if (token === null) throw new SphereError("burn replay needs the held token to certify", "VALIDATION_ERROR");
+    const burned = await deps.engine.burn(
+      { token, reasonBytes: hexToBytes(current.reasonHex) },
+      { transferId: current.burnId }
+    );
+    if (burned.blob.tokenId !== current.tokenId) {
+      throw new SphereError(`burned token ${burned.blob.tokenId}, but the journal names ${current.tokenId}`, "VALIDATION_ERROR");
+    }
+    current = { ...current, burnedTokenHex: bytesToHex(burned.blob.token) };
+    await deps.burnJournal.upsert(current);
+  }
+  if (!state.applied) {
+    await deps.storagePort.applyDelta({ transferId: current.burnId, spent: [current.tokenId], added: [] });
+  }
+  await deps.recordSent({ transferId: current.burnId, assets: current.assets, tokenId: current.tokenId });
+  current = { ...current, settled: true };
+  await deps.burnJournal.upsert(current);
+  deps.refreshView();
+  return current;
 }
 
 // modules/payments-v2/send-whole.ts
@@ -5226,7 +5447,6 @@ async function takeSourceBlobs(deps, sourceIds) {
 
 // modules/payments-v2/PaymentsFacade.ts
 var MAX_RESELECT = 8;
-var INVENTORY_SCAN_PAGE_LIMIT = 50;
 var PaymentsFacade = class {
   constructor(deps) {
     this.deps = deps;
@@ -5263,6 +5483,8 @@ var PaymentsFacade = class {
       refreshView: () => this.view.delta(),
       replayMints: () => replayCoinMints(this.mintDeps()),
       replayNftMints: () => replayNftMints(this.mintDeps()),
+      replayCustomMints: () => replayCustomMints(this.mintDeps()),
+      replayBurns: () => replayBurns(this.mintDeps()),
       isActiveOp: (id) => this.activeMoneyOps.has(id),
       emit: deps.emit,
       now: () => this.nowMs()
@@ -5358,6 +5580,9 @@ var PaymentsFacade = class {
   tokenData(tokenId) {
     return readTokenData(this.readDeps(), tokenId);
   }
+  tokenJustification(tokenId) {
+    return readTokenJustification(this.readDeps(), tokenId);
+  }
   nft(tokenId) {
     return readNft(this.readDeps(), tokenId);
   }
@@ -5406,8 +5631,12 @@ var PaymentsFacade = class {
     return this.track(this.mintInner(coinId, amount));
   }
   mintNft(request) {
-    return this.track(this.ownedMint((mintId) => runNftMintUnderJournal(this.mintDeps(), { mintId, request })));
+    return this.track(this.ownedOp((mintId) => runNftMintUnderJournal(this.mintDeps(), { mintId, request })));
   }
+  mintCustom = (request) => this.track(this.ownedOp((mintId) => runCustomMintUnderJournal(this.mintDeps(), { mintId, request })));
+  burn = (request) => this.track(this.ownedOp((burnId) => runBurnUnderJournal(this.mintDeps(), { burnId, request })));
+  pendingBurns = () => this.track(pendingBurns(this.mintDeps()));
+  acknowledgeBurn = (burnId) => this.track(acknowledgeBurn(this.mintDeps(), burnId));
   // §4 retry verb: coalesces onto the running pass — NEVER re-issue send() (#631/#676).
   async resumeNow() {
     if (!this.started) return;
@@ -5431,12 +5660,15 @@ var PaymentsFacade = class {
   nowMs() {
     return (this.deps.now ?? Date.now)();
   }
-  /** One snapshot serves the coin and the NFT mint, live and replayed. */
+  /** One snapshot serves the coin, NFT and custom mints and the burn, live and replayed. */
   mintDeps() {
     return {
       engine: this.engine(),
       mintJournal: this.machineStores.mintJournal,
       nftMintJournal: this.machineStores.nftMintJournal,
+      customMintJournal: this.machineStores.customMintJournal,
+      burnJournal: this.machineStores.burnJournal,
+      recordSent: (input) => this.historyStore.recordSent(input),
       storagePort: this.deps.storagePort,
       recordMint: (input) => this.historyStore.recordMint(input),
       armHeartbeat: () => this.heartbeat.arm(),
@@ -5445,7 +5677,7 @@ var PaymentsFacade = class {
       ownPubkeyBytes: this.ownPubkeyBytes,
       nftTokenType: this.deps.nftTokenType,
       isActiveOp: (mintId) => this.activeMoneyOps.has(mintId),
-      tokenInServerInventory: (tokenId) => this.tokenInServerInventory(tokenId),
+      tokenInServerInventory: (tokenId) => tokenInServerInventory(this.deps.storagePort, tokenId),
       emit: this.deps.emit,
       now: () => this.nowMs()
     };
@@ -5766,29 +5998,18 @@ var PaymentsFacade = class {
     if (!/^(?:[0-9a-f]{2})+$/.test(coinId) || amount <= 0n) {
       return { success: false, error: "coinId must be even-length lowercase hex and amount positive" };
     }
-    return this.ownedMint((mintId) => runMintUnderJournal(this.mintDeps(), { mintId, coinId, amount }));
+    return this.ownedOp((mintId) => runMintUnderJournal(this.mintDeps(), { mintId, coinId, amount }));
   }
-  /** A live mint under a fresh id — its replay stays hands-off while this attempt runs. */
-  async ownedMint(run) {
-    const mintId = this.newId();
-    this.activeMoneyOps.add(mintId);
+  /** A live money op under a fresh id — its replay stays hands-off while this attempt runs (§7). */
+  async ownedOp(run) {
+    const id = this.newId();
+    this.activeMoneyOps.add(id);
     try {
-      return await run(mintId);
+      return await run(id);
     } finally {
-      this.activeMoneyOps.delete(mintId);
+      this.activeMoneyOps.delete(id);
     }
   }
-  async tokenInServerInventory(tokenId) {
-    let page = await this.deps.storagePort.listInventory();
-    for (let i = 0; i < INVENTORY_SCAN_PAGE_LIMIT; i++) {
-      if (page.items.some((item) => item.tokenId === tokenId && item.status === "active")) {
-        return true;
-      }
-      if (!page.more) return false;
-      page = await this.deps.storagePort.listInventory(page.cursor);
-    }
-    return false;
-  }
   // ── wiring internals ───────────────────────────────────────────────────────
   engine() {
     return this.currentEngine ?? this.deps.engineRef();