@unicitylabs/sphere-sdk 0.14.1 → 0.14.2

package/dist/index.d.cts

@@ -164,6 +164,7 @@ interface PendingTransfer {
     deliveryPending: boolean;
     createdAt: number;
 }
+type ConnectionStatus$1 = 'connected' | 'degraded' | 'offline';
 interface PaymentsV2 {
     assets(coinId?: string): Promise<Asset[]>;
     tokens(filter?: {
@@ -180,6 +181,7 @@ interface PaymentsV2 {
     }>;
     pendingTransfers(): Promise<PendingTransfer[]>;
     resumeNow(): Promise<void>;
+    connectionStatus(): ConnectionStatus$1;
     readonly requests: PaymentsRequestsApi;
 }
 
@@ -1148,6 +1150,19 @@ interface PeerInfo {
     chainPubkey: string;
     /** L3 DIRECT address (DIRECT://...) */
     directAddress: string;
+    /**
+     * Network the peer's identity binding DECLARES ('testnet2', …) — absent when
+     * the binding carries none, which is every binding published so far. Parsed
+     * only, never invented: money refuses a PROVEN foreign network (§5.6).
+     *
+     * Absent is also the STRUCTURAL answer on the `@nametag` and `DIRECT://`
+     * routes of the Nostr transport, whichever binding is out there: those two
+     * resolve through nostr-js-sdk's `queryBindingBy*`, whose parser drops every
+     * content field outside its whitelist and never hands back the signed event
+     * (#734 tracks the upstream fix). Only routes that parse the raw event —
+     * `resolveTransportPubkeyInfo`, `discoverAddresses` — can populate it today.
+     */
+    network?: string;
     /** Event timestamp */
     timestamp: number;
 }
@@ -2298,12 +2313,17 @@ interface FacadeSession {
      * stream nudge resumes. The facade registers handleEpochChange here.
      */
     subscribeEpochChange(handler: (epoch: string) => Promise<void>): () => void;
+    /**
+     * The session's CURRENT status — REQUIRED, and the ONE source `connectionStatus()`
+     * and `connection:status` both come from ('offline' before first contact).
+     */
+    status(): ConnectionStatus$1;
     /**
      * Optional connection-status feed (same wiring pattern as the streams; the
      * emission point is the session's existing `connection:status` transition).
      * The facade's heartbeat resets its backoff on a 'connected' recovery.
      */
-    subscribeStatus?(handler: (status: 'connected' | 'degraded' | 'offline') => void): () => void;
+    subscribeStatus?(handler: (status: ConnectionStatus$1) => void): () => void;
 }
 interface IntentWireLike {
     transferId: string;

package/dist/index.d.ts

@@ -164,6 +164,7 @@ interface PendingTransfer {
     deliveryPending: boolean;
     createdAt: number;
 }
+type ConnectionStatus$1 = 'connected' | 'degraded' | 'offline';
 interface PaymentsV2 {
     assets(coinId?: string): Promise<Asset[]>;
     tokens(filter?: {
@@ -180,6 +181,7 @@ interface PaymentsV2 {
     }>;
     pendingTransfers(): Promise<PendingTransfer[]>;
     resumeNow(): Promise<void>;
+    connectionStatus(): ConnectionStatus$1;
     readonly requests: PaymentsRequestsApi;
 }
 
@@ -1148,6 +1150,19 @@ interface PeerInfo {
     chainPubkey: string;
     /** L3 DIRECT address (DIRECT://...) */
     directAddress: string;
+    /**
+     * Network the peer's identity binding DECLARES ('testnet2', …) — absent when
+     * the binding carries none, which is every binding published so far. Parsed
+     * only, never invented: money refuses a PROVEN foreign network (§5.6).
+     *
+     * Absent is also the STRUCTURAL answer on the `@nametag` and `DIRECT://`
+     * routes of the Nostr transport, whichever binding is out there: those two
+     * resolve through nostr-js-sdk's `queryBindingBy*`, whose parser drops every
+     * content field outside its whitelist and never hands back the signed event
+     * (#734 tracks the upstream fix). Only routes that parse the raw event —
+     * `resolveTransportPubkeyInfo`, `discoverAddresses` — can populate it today.
+     */
+    network?: string;
     /** Event timestamp */
     timestamp: number;
 }
@@ -2298,12 +2313,17 @@ interface FacadeSession {
      * stream nudge resumes. The facade registers handleEpochChange here.
      */
     subscribeEpochChange(handler: (epoch: string) => Promise<void>): () => void;
+    /**
+     * The session's CURRENT status — REQUIRED, and the ONE source `connectionStatus()`
+     * and `connection:status` both come from ('offline' before first contact).
+     */
+    status(): ConnectionStatus$1;
     /**
      * Optional connection-status feed (same wiring pattern as the streams; the
      * emission point is the session's existing `connection:status` transition).
      * The facade's heartbeat resets its backoff on a 'connected' recovery.
      */
-    subscribeStatus?(handler: (status: 'connected' | 'degraded' | 'offline') => void): () => void;
+    subscribeStatus?(handler: (status: ConnectionStatus$1) => void): () => void;
 }
 interface IntentWireLike {
     transferId: string;

package/dist/index.js

@@ -851,6 +851,15 @@ var LIMITS = {
 var COMPOSING_INDICATOR_KIND = 25050;
 var TIMESTAMP_RANDOMIZATION = 2 * 24 * 60 * 60;
 var EVENT_KINDS = NOSTR_EVENT_KINDS;
+function declaredNetwork(event) {
+  let value;
+  try {
+    value = JSON.parse(event.content)?.network;
+  } catch {
+    return void 0;
+  }
+  return typeof value === "string" && value !== "" ? value : void 0;
+}
 var NostrTransportProvider = class _NostrTransportProvider {
   id = "nostr";
   name = "Nostr Transport";
@@ -1347,6 +1356,26 @@ var NostrTransportProvider = class _NostrTransportProvider {
   }
   /**
    * Convert a BindingInfo (from nostr-js-sdk) to PeerInfo (sphere-sdk type).
+   *
+   * `network` IS DELIBERATELY ABSENT HERE — a live limitation, not an oversight
+   * (#734). `queryBindingByNametag`/`queryBindingByAddress` are the whole public
+   * resolution API for `@nametag` and `DIRECT://`, and both hardcode
+   * `parseBindingInfo` inside the SDK's PRIVATE `queryWithFirstSeenWins`: the
+   * caller never sees the signed event that resolution selected, and the parse
+   * has already dropped every content field outside its whitelist. Re-querying
+   * raw would mean re-deriving UNIP-01 ownership ourselves (marker preference,
+   * cross-author first-seen-wins, ambiguity→null, multi-relay settle — all
+   * private), and a second resolver that can disagree with the SDK's is worse
+   * than a missing field on a MONEY guard. Nothing can declare a network today
+   * regardless: the publish builders whitelist the same fields.
+   *
+   * CONSEQUENCE, stated plainly: for `@nametag` and `DIRECT://` recipients the
+   * §5.6 cross-network guard can only SIGNAL (`recipient:network-unverified`),
+   * never refuse. Upstream #734 must add `network` to the binding builders AND
+   * to `BindingInfo`; the tripwire in
+   * tests/unit/payments-v2/recipient-network.transport.test.ts fails the day it
+   * lands, so this wiring cannot be forgotten. Do not "fix" this by inventing a
+   * value — a stamped network is what made the guard unfalsifiable (#733).
    */
   async bindingInfoToPeerInfo(binding, nametag) {
     return {
@@ -1373,11 +1402,13 @@ var NostrTransportProvider = class _NostrTransportProvider {
     const bindingEvent = events[0];
     try {
       const content = JSON.parse(bindingEvent.content);
+      const network = declaredNetwork(bindingEvent);
       return {
         nametag: content.nametag || void 0,
         transportPubkey: bindingEvent.pubkey,
         chainPubkey: content.public_key || "",
         directAddress: content.direct_address || "",
+        ...network !== void 0 ? { network } : {},
         timestamp: bindingEvent.created_at * 1e3
       };
     } catch {
@@ -1413,11 +1444,13 @@ var NostrTransportProvider = class _NostrTransportProvider {
     for (const [pubkey, event] of byAuthor) {
       try {
         const content = JSON.parse(event.content);
+        const network = declaredNetwork(event);
         results.push({
           nametag: content.nametag || void 0,
           transportPubkey: pubkey,
           chainPubkey: content.public_key || "",
           directAddress: content.direct_address || "",
+          ...network !== void 0 ? { network } : {},
           timestamp: event.created_at * 1e3
         });
       } catch {
@@ -12011,6 +12044,31 @@ function distinctOpCount(entries) {
   return new Set(entries.map((entry) => entry.opIndex)).size;
 }
 
+// modules/payments-v2/recipient.ts
+var ATTENTION_RECIPIENT_NETWORK_UNVERIFIED = "recipient:network-unverified";
+async function requireSameNetworkRecipient(deps, identifier) {
+  const recipient = await deps.resolveRecipient(identifier);
+  if (recipient === null || recipient.chainPubkey === "") {
+    throw new SphereError(`Recipient ${identifier} has no published chain pubkey`, "INVALID_RECIPIENT");
+  }
+  if (recipient.network === null) {
+    deps.emit("transfer:attention", {
+      transferId: "",
+      // the gate precedes plan allocation — no transferId exists yet
+      code: ATTENTION_RECIPIENT_NETWORK_UNVERIFIED,
+      detail: `could not verify the network of recipient ${identifier} \u2014 assuming this session's "${deps.network}"`
+    });
+    return recipient;
+  }
+  if (recipient.network !== deps.network) {
+    throw new SphereError(
+      `Recipient ${identifier} is on network "${recipient.network}" but this session is on "${deps.network}" \u2014 a cross-network deposit is unrecoverable`,
+      "INVALID_RECIPIENT"
+    );
+  }
+  return recipient;
+}
+
 // modules/payments-v2/restore.ts
 var ATTENTION_RESEED_REJECTED = "intent:reseed-rejected";
 var ALL_STREAMS = ["inventory", "mailbox", "payment_requests", "history"];
@@ -13603,6 +13661,10 @@ var PaymentsFacade = class {
   history(page) {
     return this.historyStore.page(page ?? {});
   }
+  /** §4: read through to the session — the same value `connection:status` carries (sphere#473). No session ⇒ 'offline'. */
+  connectionStatus() {
+    return this.started ? this.deps.session.status() : "offline";
+  }
   /** §4 pending-transfers UI surface — derived on read, never cached (convergence.ts). */
   pendingTransfers() {
     return derivePendingTransfers(this.machineStores, this.machineDeps.decryptPayload);
@@ -13677,7 +13739,7 @@ var PaymentsFacade = class {
     this.deps.emit("transfer:updated", failed);
   }
   async sendWithPolicy(request, run) {
-    const recipient = await this.requireSameNetworkRecipient(request.recipient);
+    const recipient = await requireSameNetworkRecipient(this.deps, request.recipient);
     for (let attempt = 0; ; attempt++) {
       let ctx;
       try {
@@ -13700,20 +13762,6 @@ var PaymentsFacade = class {
       if (surfaced !== null) return surfaced;
     }
   }
-  /** §5.6 cross-network deposit trap: refused BEFORE any reserve/certification. */
-  async requireSameNetworkRecipient(identifier) {
-    const recipient = await this.deps.resolveRecipient(identifier);
-    if (recipient === null || recipient.chainPubkey === "") {
-      throw new SphereError(`Recipient ${identifier} has no published chain pubkey`, "INVALID_RECIPIENT");
-    }
-    if (recipient.network !== this.deps.network) {
-      throw new SphereError(
-        `Recipient ${identifier} is on network "${recipient.network}" but this session is on "${this.deps.network}" \u2014 a cross-network deposit is unrecoverable`,
-        "INVALID_RECIPIENT"
-      );
-    }
-    return recipient;
-  }
   async runAttempt(ctx) {
     this.activeMoneyOps.add(ctx.transferId);
     try {
@@ -14090,19 +14138,12 @@ var PaymentsFacade = class {
   }
   toUiToken(tokenId, coinId, amount) {
     const now = this.nowMs();
-    return toToken(
-      tokenId,
-      { assets: [], createdAt: now, updatedAt: now },
-      { coinId, amount: amount.toString() },
-      this.deps.registry,
-      { transferring: true, suspectedSpent: false }
-    );
+    const snapshot = { assets: [], createdAt: now, updatedAt: now };
+    const flags = { transferring: true, suspectedSpent: false };
+    return toToken(tokenId, snapshot, { coinId, amount: amount.toString() }, this.deps.registry, flags);
   }
   track(op) {
-    const settled = op.then(
-      () => void 0,
-      () => void 0
-    );
+    const settled = op.then(() => void 0, () => void 0);
     this.pendingOps.add(settled);
     void settled.finally(() => this.pendingOps.delete(settled));
     return op;
@@ -15203,7 +15244,8 @@ async function resolveRecipientInfo(identifier, network, resolvePeer) {
   if (!peer?.chainPubkey) return null;
   return {
     chainPubkey: peer.chainPubkey,
-    network,
+    // Only what the binding declares (blank declares nothing) — never a local stamp.
+    network: peer.network || null,
     ...peer.nametag !== void 0 ? { nametag: peer.nametag } : {}
   };
 }