@unicitylabs/sphere-sdk 0.9.1-dev.10 → 0.9.1-dev.11

package/dist/index.d.cts

@@ -1890,6 +1890,26 @@ type WalletApiPaymentRequestsPage = {
     cursor: string | null;
     syncEpoch: bigint;
 };
+/**
+ * One §16 history wire record (§10 — the server never writes history rows).
+ * `memo` / `counterpartyNametag` are S6 `enc1.` envelopes, verbatim (§8.3) —
+ * encrypted on POST, returned encrypted on GET, decrypted by the owner only.
+ */
+interface WalletApiHistoryRecord {
+    dedupKey: string;
+    id: string;
+    type: string;
+    ts: string;
+    assets: {
+        coinId: string;
+        amount: string;
+    }[];
+    transferId?: string;
+    tokenId?: string;
+    counterpartyPubkey?: string;
+    memo?: string;
+    counterpartyNametag?: string;
+}
 /**
  * The narrow, STRUCTURAL slice of the wallet-api client this module needs:
  * the E.3 intent lifecycle, blob uploads for spend outputs, and the §10
@@ -1924,21 +1944,24 @@ interface PaymentsWalletApiPort {
     /** Upload to a presigned PUT (a 412 = already present = success — §5.2). */
     uploadBlob(putUrl: string, bytes: Uint8Array): Promise<void>;
     /** §10: client-asserted history records (§16 wire shape), deduped by dedupKey server-side. */
-    postHistoryRecords(records: {
-        dedupKey: string;
-        id: string;
-        type: string;
-        ts: string;
-        assets: {
-            coinId: string;
-            amount: string;
-        }[];
-        transferId?: string;
-        tokenId?: string;
-        counterpartyPubkey?: string;
-        memo?: string;
-        counterpartyNametag?: string;
-    }[]): Promise<void>;
+    postHistoryRecords(records: WalletApiHistoryRecord[]): Promise<void>;
+    /**
+     * §10/§16: read the client-written history log back — newest-first keyset
+     * pages (`{records, more, cursor, syncEpoch}`). The READ side of the §10 log:
+     * a reloaded thin wallet rebuilds its history from here (the in-memory cache
+     * is process-lifetime; the durable log lives on the server). `memo` /
+     * `counterpartyNametag` come back as the verbatim S6 `enc1.` envelopes — the
+     * owner decrypts them with its own field key on display (§8.3).
+     */
+    listHistory(options?: {
+        before?: string;
+        limit?: number;
+    }): Promise<{
+        records: WalletApiHistoryRecord[];
+        more: boolean;
+        cursor: string | null;
+        syncEpoch: bigint;
+    }>;
     /** Network name — scopes the persisted payment-request cursor (mirrors the mailbox cursor). */
     readonly network?: string;
     /** `POST /v1/payment-requests` (§16) — `memo` MUST already be an S6 envelope (§8.3). */
@@ -2538,10 +2561,39 @@ declare class PaymentsModule {
      */
     addToHistory(entry: Omit<TransactionHistoryEntry, 'id' | 'dedupKey'>): Promise<void>;
     /**
-     * Load history from the local token storage provider into the in-memory cache.
-     * Also performs one-time migration from legacy KV storage.
+     * Load history into the in-memory cache.
+     *
+     * In the wallet-api composition (the `walletApi` client is present) the
+     * durable §10 history log lives on the SERVER — the thin storage provider
+     * keeps none — so the cache is rebuilt from `walletApi.listHistory()`. The
+     * twin of the #521 inventory reload bug: `_historyCache` is process-lifetime,
+     * so a reload (tab refresh) must re-pull it or render an empty history.
+     * Compositions WITHOUT `walletApi` keep the legacy local path below.
      */
     loadHistory(): Promise<void>;
+    /**
+     * Rebuild `_historyCache` from the server's §10 history log (the wallet-api
+     * composition). Pages newest-first via the keyset cursor until `more:false`
+     * or the page cap; dedups by `dedupKey` (a hydrate-then-receive in the same
+     * session must not double-list). The S6 `memo` / `counterpartyNametag`
+     * envelopes are decrypted with the owner's own field key on the way in.
+     *
+     * Best-effort, like the §10 history POST: history is untrusted DISPLAY data,
+     * so a backend outage during hydration must NEVER fail `load()` (the money
+     * path) — the in-session cache is left intact and the pull retries next load.
+     */
+    private hydrateHistoryFromServer;
+    /**
+     * Map one §16 history wire record onto the display
+     * {@link TransactionHistoryEntry}. `counterpartyNametag` lands on the role-
+     * appropriate field (sender for RECEIVED, recipient otherwise); the S6 memo +
+     * nametag envelopes decrypt under THIS wallet's field key (self-scoped at
+     * rest — §8.3), surfaced as absent if they don't decrypt rather than as
+     * ciphertext (same rule as mailbox/payment-request memos).
+     */
+    private historyEntryFromWire;
+    /** S6 field decrypt that surfaces an undecryptable envelope as absent (§8.3). */
+    private tryDecryptField;
     /**
      * Import history entries from remote TXF data into local store.
      * Delegates to the local TokenStorageProvider's importHistoryEntries() for

package/dist/index.d.ts

@@ -1890,6 +1890,26 @@ type WalletApiPaymentRequestsPage = {
     cursor: string | null;
     syncEpoch: bigint;
 };
+/**
+ * One §16 history wire record (§10 — the server never writes history rows).
+ * `memo` / `counterpartyNametag` are S6 `enc1.` envelopes, verbatim (§8.3) —
+ * encrypted on POST, returned encrypted on GET, decrypted by the owner only.
+ */
+interface WalletApiHistoryRecord {
+    dedupKey: string;
+    id: string;
+    type: string;
+    ts: string;
+    assets: {
+        coinId: string;
+        amount: string;
+    }[];
+    transferId?: string;
+    tokenId?: string;
+    counterpartyPubkey?: string;
+    memo?: string;
+    counterpartyNametag?: string;
+}
 /**
  * The narrow, STRUCTURAL slice of the wallet-api client this module needs:
  * the E.3 intent lifecycle, blob uploads for spend outputs, and the §10
@@ -1924,21 +1944,24 @@ interface PaymentsWalletApiPort {
     /** Upload to a presigned PUT (a 412 = already present = success — §5.2). */
     uploadBlob(putUrl: string, bytes: Uint8Array): Promise<void>;
     /** §10: client-asserted history records (§16 wire shape), deduped by dedupKey server-side. */
-    postHistoryRecords(records: {
-        dedupKey: string;
-        id: string;
-        type: string;
-        ts: string;
-        assets: {
-            coinId: string;
-            amount: string;
-        }[];
-        transferId?: string;
-        tokenId?: string;
-        counterpartyPubkey?: string;
-        memo?: string;
-        counterpartyNametag?: string;
-    }[]): Promise<void>;
+    postHistoryRecords(records: WalletApiHistoryRecord[]): Promise<void>;
+    /**
+     * §10/§16: read the client-written history log back — newest-first keyset
+     * pages (`{records, more, cursor, syncEpoch}`). The READ side of the §10 log:
+     * a reloaded thin wallet rebuilds its history from here (the in-memory cache
+     * is process-lifetime; the durable log lives on the server). `memo` /
+     * `counterpartyNametag` come back as the verbatim S6 `enc1.` envelopes — the
+     * owner decrypts them with its own field key on display (§8.3).
+     */
+    listHistory(options?: {
+        before?: string;
+        limit?: number;
+    }): Promise<{
+        records: WalletApiHistoryRecord[];
+        more: boolean;
+        cursor: string | null;
+        syncEpoch: bigint;
+    }>;
     /** Network name — scopes the persisted payment-request cursor (mirrors the mailbox cursor). */
     readonly network?: string;
     /** `POST /v1/payment-requests` (§16) — `memo` MUST already be an S6 envelope (§8.3). */
@@ -2538,10 +2561,39 @@ declare class PaymentsModule {
      */
     addToHistory(entry: Omit<TransactionHistoryEntry, 'id' | 'dedupKey'>): Promise<void>;
     /**
-     * Load history from the local token storage provider into the in-memory cache.
-     * Also performs one-time migration from legacy KV storage.
+     * Load history into the in-memory cache.
+     *
+     * In the wallet-api composition (the `walletApi` client is present) the
+     * durable §10 history log lives on the SERVER — the thin storage provider
+     * keeps none — so the cache is rebuilt from `walletApi.listHistory()`. The
+     * twin of the #521 inventory reload bug: `_historyCache` is process-lifetime,
+     * so a reload (tab refresh) must re-pull it or render an empty history.
+     * Compositions WITHOUT `walletApi` keep the legacy local path below.
      */
     loadHistory(): Promise<void>;
+    /**
+     * Rebuild `_historyCache` from the server's §10 history log (the wallet-api
+     * composition). Pages newest-first via the keyset cursor until `more:false`
+     * or the page cap; dedups by `dedupKey` (a hydrate-then-receive in the same
+     * session must not double-list). The S6 `memo` / `counterpartyNametag`
+     * envelopes are decrypted with the owner's own field key on the way in.
+     *
+     * Best-effort, like the §10 history POST: history is untrusted DISPLAY data,
+     * so a backend outage during hydration must NEVER fail `load()` (the money
+     * path) — the in-session cache is left intact and the pull retries next load.
+     */
+    private hydrateHistoryFromServer;
+    /**
+     * Map one §16 history wire record onto the display
+     * {@link TransactionHistoryEntry}. `counterpartyNametag` lands on the role-
+     * appropriate field (sender for RECEIVED, recipient otherwise); the S6 memo +
+     * nametag envelopes decrypt under THIS wallet's field key (self-scoped at
+     * rest — §8.3), surfaced as absent if they don't decrypt rather than as
+     * ciphertext (same rule as mailbox/payment-request memos).
+     */
+    private historyEntryFromWire;
+    /** S6 field decrypt that surfaces an undecryptable envelope as absent (§8.3). */
+    private tryDecryptField;
     /**
      * Import history entries from remote TXF data into local store.
      * Delegates to the local TokenStorageProvider's importHistoryEntries() for

package/dist/index.js

@@ -9814,6 +9814,7 @@ function computeHistoryDedupKey(type, tokenId, transferId) {
   return `${type}_${crypto.randomUUID()}`;
 }
 var MAX_SYNCED_HISTORY_ENTRIES = 5e3;
+var MAX_HISTORY_HYDRATION_PAGES = 100;
 var SEND_ENGINE_OP_TIMEOUT_MS = 6e4;
 var DELIVERY_POLL_INTERVAL_MS = 3e4;
 function enrichWithRegistry(info) {
@@ -12103,10 +12104,20 @@ var PaymentsModule = class _PaymentsModule {
     this.deps.emitEvent("history:updated", historyEntry);
   }
   /**
-   * Load history from the local token storage provider into the in-memory cache.
-   * Also performs one-time migration from legacy KV storage.
+   * Load history into the in-memory cache.
+   *
+   * In the wallet-api composition (the `walletApi` client is present) the
+   * durable §10 history log lives on the SERVER — the thin storage provider
+   * keeps none — so the cache is rebuilt from `walletApi.listHistory()`. The
+   * twin of the #521 inventory reload bug: `_historyCache` is process-lifetime,
+   * so a reload (tab refresh) must re-pull it or render an empty history.
+   * Compositions WITHOUT `walletApi` keep the legacy local path below.
    */
   async loadHistory() {
+    if (this.deps.walletApi?.listHistory) {
+      await this.hydrateHistoryFromServer(this.deps.walletApi);
+      return;
+    }
     const provider = this.getLocalTokenStorageProvider();
     if (provider?.getHistoryEntries) {
       this._historyCache = await provider.getHistoryEntries();
@@ -12138,6 +12149,75 @@ var PaymentsModule = class _PaymentsModule {
       }
     }
   }
+  /**
+   * Rebuild `_historyCache` from the server's §10 history log (the wallet-api
+   * composition). Pages newest-first via the keyset cursor until `more:false`
+   * or the page cap; dedups by `dedupKey` (a hydrate-then-receive in the same
+   * session must not double-list). The S6 `memo` / `counterpartyNametag`
+   * envelopes are decrypted with the owner's own field key on the way in.
+   *
+   * Best-effort, like the §10 history POST: history is untrusted DISPLAY data,
+   * so a backend outage during hydration must NEVER fail `load()` (the money
+   * path) — the in-session cache is left intact and the pull retries next load.
+   */
+  async hydrateHistoryFromServer(api) {
+    const byDedupKey = /* @__PURE__ */ new Map();
+    try {
+      let before;
+      for (let page = 0; page < MAX_HISTORY_HYDRATION_PAGES; page++) {
+        const result = await api.listHistory(before !== void 0 ? { before } : {});
+        for (const wire of result.records) {
+          if (!byDedupKey.has(wire.dedupKey)) {
+            byDedupKey.set(wire.dedupKey, this.historyEntryFromWire(wire));
+          }
+        }
+        if (!result.more || result.cursor === null) break;
+        before = result.cursor;
+      }
+    } catch (err) {
+      logger.warn("Payments", "history hydration from server failed (kept in-memory; retries next load):", err);
+      return;
+    }
+    this._historyCache = [...byDedupKey.values()];
+  }
+  /**
+   * Map one §16 history wire record onto the display
+   * {@link TransactionHistoryEntry}. `counterpartyNametag` lands on the role-
+   * appropriate field (sender for RECEIVED, recipient otherwise); the S6 memo +
+   * nametag envelopes decrypt under THIS wallet's field key (self-scoped at
+   * rest — §8.3), surfaced as absent if they don't decrypt rather than as
+   * ciphertext (same rule as mailbox/payment-request memos).
+   */
+  historyEntryFromWire(wire) {
+    const asset = wire.assets[0];
+    const coinId = asset?.coinId ?? "";
+    const received = wire.type === "RECEIVED";
+    const memo = this.tryDecryptField(wire.memo);
+    const nametag = this.tryDecryptField(wire.counterpartyNametag);
+    return {
+      id: wire.id,
+      dedupKey: wire.dedupKey,
+      type: wire.type,
+      amount: asset?.amount ?? "0",
+      coinId,
+      symbol: this.getCoinSymbol(coinId),
+      timestamp: Date.parse(wire.ts),
+      ...wire.transferId !== void 0 ? { transferId: wire.transferId } : {},
+      ...wire.tokenId !== void 0 ? { tokenId: wire.tokenId } : {},
+      ...wire.counterpartyPubkey !== void 0 ? received ? { senderPubkey: wire.counterpartyPubkey } : { recipientPubkey: wire.counterpartyPubkey } : {},
+      ...nametag !== void 0 ? received ? { senderNametag: nametag } : { recipientNametag: nametag } : {},
+      ...memo !== void 0 ? { memo } : {}
+    };
+  }
+  /** S6 field decrypt that surfaces an undecryptable envelope as absent (§8.3). */
+  tryDecryptField(envelope) {
+    if (envelope === void 0) return void 0;
+    try {
+      return decryptField(this.getFieldEncryptionKey(), envelope);
+    } catch {
+      return void 0;
+    }
+  }
   /**
    * Import history entries from remote TXF data into local store.
    * Delegates to the local TokenStorageProvider's importHistoryEntries() for