@effectstream/sync 0.101.1 → 0.103.0

package/src/sync-protocols/base/state.ts

@@ -69,11 +69,62 @@ export abstract class SyncState<
   public lastPage: undefined | LastPage<Page, RootPage>;
   /** Timestamp of the last successful fetch (readData completed without error). */
   public lastSuccessfulFetchMs: number = 0;
+  /**
+   * Wall-clock time of the last completed pass through the fetch loop, whatever
+   * its outcome (fetched, caught up, or errored).
+   *
+   * This — not `lastSuccessfulFetchMs` — is the hang detector. A chain that is
+   * caught up never calls `readData`, so its last-successful-fetch time is
+   * indistinguishable from that of a chain wedged inside a request that will
+   * never return. The loop still cycles in the first case and does not in the
+   * second, so a heartbeat that is stale by many polling intervals means the
+   * loop is stuck in `stateToInput`/`readData`.
+   */
+  public lastPollAtMs: number = 0;
   /** Number of consecutive errors since the last successful fetch. */
   public consecutiveErrors: number = 0;
   /** Timestamp of the most recent error, or 0 if no error has occurred. */
   public lastErrorTimestamp: number = 0;
 
+  // ── Streaming producer (see startAsync + orchestration/sync.ts) ──
+  /**
+   * Whether {@link SyncState#startAsync} runs a long-lived producer that this
+   * protocol depends on for its data (a subscription/stream), as opposed to the
+   * base-class no-op used by polled chains.
+   *
+   * `startSync` supervises and restarts the producer only when this is true.
+   * A polled chain must leave it false, or its no-op `startAsync` would be
+   * "restarted" forever.
+   */
+  public readonly hasAsyncProducer: boolean = false;
+  /**
+   * How many times the streaming producer has been restarted after dying —
+   * either by throwing or by returning (a producer that returns has ended its
+   * stream). Surfaced on `/health`; a climbing count means a flapping upstream.
+   */
+  public producerRestarts: number = 0;
+  /**
+   * Producer failures, tracked separately from {@link consecutiveErrors}.
+   *
+   * That counter belongs to the fetch loop and is only cleared by a successful
+   * `readData`, so sharing it conflated two independent signals: an idle
+   * streaming chain would report `erroring` long after its producer recovered,
+   * and a successful poll would erase the record of a flapping producer.
+   */
+  public producerErrors: number = 0;
+  /** Wall-clock time of the last producer failure, or 0 if none. */
+  public lastProducerErrorMs: number = 0;
+
+  /**
+   * Resolved polling interval for this protocol, stamped by `startSync`.
+   *
+   * Single source of truth: `/health` derives its wedged threshold from this
+   * rather than reaching back into `fetcher.config.syncProtocol`, which it can
+   * only do through an unchecked cast that would fail silently to a default if
+   * the config shape ever moved.
+   */
+  public pollingIntervalMs: number = 0;
+
   // ── Backpressure observability (see common/page-helpers.ts + README) ──
   /** Resolved fetch cap (`maxBufferedPages`); set on each backpressure check, 0 until the first. */
   public bufferCap: number = 0;

package/src/sync-protocols/bitcoin/fetcher.ts

@@ -27,6 +27,7 @@ import type {
   BitcoinTxId,
 } from "@effectstream/utils";
 import { blockNumberRelation } from "../common/utils.ts";
+import { DEFAULT_REQUEST_TIMEOUT_MS, fetchWithTimeout } from "../common/http.ts";
 import type { ConfigType } from "./types.ts";
 
 const SATOSHIS_PER_BTC = 100_000_000;
@@ -457,6 +458,8 @@ type BitcoinRpcClientOptions = {
   url: string;
   username?: string | null;
   password?: string | null;
+  /** Per-request deadline; defaults to {@link DEFAULT_REQUEST_TIMEOUT_MS}. */
+  requestTimeoutMs?: number;
 };
 
 type BitcoinRpcRequest = {
@@ -515,16 +518,21 @@ export class BitcoinRpcClient {
   private async call<TResult>(
     request: BitcoinRpcRequest,
   ): Promise<TResult> {
-    const response = await fetch(this.options.url, {
-      method: "POST",
-      headers: this.buildHeaders(),
-      body: JSON.stringify({
-        jsonrpc: "2.0",
-        id: ++this.nextId,
-        method: request.method,
-        params: request.params ?? [],
-      }),
-    });
+    const response = await fetchWithTimeout(
+      this.options.url,
+      {
+        method: "POST",
+        headers: this.buildHeaders(),
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: ++this.nextId,
+          method: request.method,
+          params: request.params ?? [],
+        }),
+      },
+      `Bitcoin ${request.method}`,
+      this.options.requestTimeoutMs,
+    );
     if (!response.ok) {
       const body = await response.text();
       throw new Error(

package/src/sync-protocols/celestia/CelestiaClient.ts

@@ -54,6 +54,11 @@ const CELESTIA_NODE_URL = ENV.getString(
   "http://localhost:26658",
 );
 const CELESTIA_AUTH_TOKEN = ENV.getString("CELESTIA_AUTH_TOKEN", "");
+/**
+ * Fallback per-request deadline, kept for compatibility with deployments that
+ * set it. The protocol config's `requestTimeoutMs` takes precedence — see the
+ * constructor.
+ */
 const CELESTIA_RPC_TIMEOUT_MS = parseInt(
   ENV.getString("CELESTIA_RPC_TIMEOUT_MS", "15000"),
 );
@@ -77,9 +82,18 @@ export function celestiaNamespaceToBase64(hex: string): string {
 
 export class CelestiaClient {
   private readonly rpcUrl: string;
+  /**
+   * Per-attempt deadline. Unlike the other clients this one retries internally
+   * (see `rpc` below), so this bounds each attempt rather than the whole call.
+   */
+  private readonly requestTimeoutMs: number;
 
-  constructor(rpcUrl: string = CELESTIA_NODE_URL) {
+  constructor(
+    rpcUrl: string = CELESTIA_NODE_URL,
+    requestTimeoutMs: number = CELESTIA_RPC_TIMEOUT_MS,
+  ) {
     this.rpcUrl = rpcUrl;
+    this.requestTimeoutMs = requestTimeoutMs;
   }
 
   private async rpc<T>(method: string, params: unknown[]): Promise<T | null> {
@@ -95,7 +109,7 @@ export class CelestiaClient {
           method: "POST",
           headers,
           body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
-          signal: AbortSignal.timeout(CELESTIA_RPC_TIMEOUT_MS),
+          signal: AbortSignal.timeout(this.requestTimeoutMs),
         });
         const json = await res.json();
         if (json.error) {

package/src/sync-protocols/celestia/fetcher.ts

@@ -2,6 +2,7 @@ import {
   ConfigSyncProtocolType,
   type PrimitiveEntry,
 } from "@effectstream/config";
+import { requestTimeoutOf } from "../common/http.ts";
 import { BaseDataFetcher } from "../base/fetcher.ts";
 import type { DataFetched } from "../base/fetcher.ts";
 import type {
@@ -37,7 +38,10 @@ export class CelestiaFetcher extends BaseDataFetcher<
     readonly config: ConfigType,
   ) {
     super(config.syncProtocol.name);
-    this.client = new CelestiaClient(config.network.rpcUrl);
+    this.client = new CelestiaClient(
+      config.network.rpcUrl,
+      requestTimeoutOf(config.syncProtocol),
+    );
   }
 
   @bound

package/src/sync-protocols/celestia/state.ts

@@ -10,6 +10,7 @@ import type { ConfigNetworkType, SyncProtocolWithNetwork } from "@effectstream/c
 import { getPage } from "@effectstream/db";
 import { CelestiaClient } from "./CelestiaClient.ts";
 import { applyDelay } from "../common/utils.ts";
+import { requestTimeoutOf } from "../common/http.ts";
 import { bufferAtCap } from "../common/page-helpers.ts";
 
 export class CelestiaSyncState extends SyncState<
@@ -135,7 +136,10 @@ export class CelestiaSyncState extends SyncState<
       page,
       config,
       fetcher,
-      new CelestiaClient(config.network.rpcUrl),
+      new CelestiaClient(
+        config.network.rpcUrl,
+        requestTimeoutOf(config.syncProtocol),
+      ),
       dbConn,
     );
   }

package/src/sync-protocols/common/http.ts

@@ -0,0 +1,77 @@
+/**
+ * Bounded HTTP for sync-protocol RPC clients.
+ *
+ * `fetch` has no default timeout. Against a blackholed endpoint — a load
+ * balancer that drops its backend, a socket left half-open by a NAT rebind —
+ * the connection is established and simply never answers, so the promise never
+ * settles. For a sync protocol that is the worst possible failure: `readData`
+ * never returns, so the fetch loop in `orchestration/sync.ts` never reaches its
+ * `catch`, `consecutiveErrors` stays 0, `lastSuccessfulFetchMs` freezes, and
+ * the merge blocks on that chain's page forever. The node stops producing
+ * blocks and reports nothing wrong.
+ *
+ * Deliberately timeout-only, with NO internal retry. The fetch loop already
+ * retries: it catches, counts the error, sleeps `pollingInterval` and re-runs
+ * the same page range (fetches are idempotent — `lastPage` only advances on a
+ * complete `DataFetched`). Retrying inside the client as well would double the
+ * backoff and, worse, hide failures from `consecutiveErrors`, which is what the
+ * health endpoint reports on.
+ *
+ * Regression test: `sync/test/rpc-timeout.test.ts` points each client at a
+ * blackhole and asserts it rejects rather than hanging.
+ */
+
+/** Used when a protocol config carries no `requestTimeoutMs`. */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
+
+/** Thrown when a request exceeds its budget, so callers can tell it apart. */
+export class RequestTimeoutError extends Error {
+  constructor(
+    readonly label: string,
+    readonly timeoutMs: number,
+  ) {
+    super(`[${label}] request timed out after ${timeoutMs}ms`);
+    this.name = "RequestTimeoutError";
+  }
+}
+
+/**
+ * `fetch` with a hard deadline.
+ *
+ * @param label   Prefix for the thrown error, e.g. `"Bitcoin getblockhash"`.
+ * @param timeoutMs Falls back to {@link DEFAULT_REQUEST_TIMEOUT_MS}.
+ * @param signal  Optional caller signal; aborting either one aborts the request.
+ */
+export async function fetchWithTimeout(
+  url: string,
+  init: RequestInit,
+  label: string,
+  timeoutMs: number = DEFAULT_REQUEST_TIMEOUT_MS,
+  signal?: AbortSignal,
+): Promise<Response> {
+  const timeoutSignal = AbortSignal.timeout(timeoutMs);
+  const combined = signal
+    ? AbortSignal.any([signal, timeoutSignal])
+    : timeoutSignal;
+
+  try {
+    return await fetch(url, { ...init, signal: combined });
+  } catch (err) {
+    // Surface our own error for the timeout case; a caller-supplied abort and
+    // ordinary transport failures propagate unchanged.
+    if (timeoutSignal.aborted && !(signal?.aborted ?? false)) {
+      throw new RequestTimeoutError(label, timeoutMs);
+    }
+    throw err;
+  }
+}
+
+/**
+ * Resolve the timeout for a protocol config. Optional in the schema, so this
+ * centralises the fallback instead of repeating `?? DEFAULT` at each client.
+ */
+export function requestTimeoutOf(
+  syncProtocol: { requestTimeoutMs?: number } | undefined,
+): number {
+  return syncProtocol?.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+}

package/src/sync-protocols/midnight/MidnightClient.ts

@@ -30,11 +30,19 @@ export interface MidnightGqlBlockState {
         intentHash:  string;
         outputIndex: number;
         owner:       string;
+        /** u128 value as a decimal string */
+        value:       string;
+        /** hex-encoded serialized token type */
+        tokenType:   string;
       }[];
       unshieldedCreatedOutputs?: {
         intentHash:  string;
         outputIndex: number;
         owner:       string;
+        /** u128 value as a decimal string */
+        value:       string;
+        /** hex-encoded serialized token type */
+        tokenType:   string;
       }[];
       // Present only on RegularTransaction (selected via inline fragment): the
       // coin-commitment Merkle tree root after this transaction.
@@ -54,7 +62,7 @@ export interface MidnightGqlBlockState {
 export interface BlockFetchOptions {
   /** Include contractActions in the transaction fields (needed for MidnightGenericPrimitive). Default: true */
   contractActions?: boolean;
-  /** Include zswapLedgerEvents in the transaction fields (needed for MidnightNullifierPrimitive). Default: true */
+  /** Include zswapLedgerEvents in the transaction fields (needed for MidnightNullifierAndCommitmentPrimitive). Default: true */
   zswapLedgerEvents?: boolean;
   /** Include unshieldedSpentOutputs (needed for MidnightUnshieldedSpendPrimitive). Default: false */
   unshieldedSpentOutputs?: boolean;
@@ -150,10 +158,10 @@ export class MidnightClient {
       ? `zswapLedgerEvents { id raw maxId }`
       : "";
     const unshieldedSpentField = unshieldedSpentOutputs
-      ? `unshieldedSpentOutputs { intentHash outputIndex owner }`
+      ? `unshieldedSpentOutputs { intentHash outputIndex owner value tokenType }`
       : "";
     const unshieldedCreatedField = unshieldedCreatedOutputs
-      ? `unshieldedCreatedOutputs { intentHash outputIndex owner }`
+      ? `unshieldedCreatedOutputs { intentHash outputIndex owner value tokenType }`
       : "";
     // zswapMerkleTreeRoot lives on RegularTransaction, not the Transaction
     // interface, so it must be selected through an inline fragment.

package/src/sync-protocols/midnight/fetcher.ts

@@ -1,4 +1,5 @@
 import { BaseDataFetcher } from "../base/fetcher.ts";
+import { requestTimeoutOf } from "../common/http.ts";
 import type {
   Block,
   ConfigType,
@@ -18,7 +19,7 @@ import type { RootOutput, RootPage } from "../types.ts";
 import { bound } from "@effectstream/utils";
 import { MidnightClient, type BlockFetchOptions, type MidnightGqlBlockState } from "./MidnightClient.ts";
 import { ContractState, StateValue } from "@midnight-ntwrk/onchain-runtime";
-import { decodeZswapInputEvent } from "./zswap-decoder.ts";
+import { decodeZswapEvent } from "./zswap-decoder.ts";
 import { decodeTokenMints } from "./mint-decoder.ts";
 
 export class MidnightFetcher extends BaseDataFetcher<
@@ -59,6 +60,7 @@ export class MidnightFetcher extends BaseDataFetcher<
     this.client = new MidnightClient(
       indexerHttp,
       this.networkId,
+      requestTimeoutOf(config.syncProtocol),
     );
   }
 
@@ -76,14 +78,14 @@ export class MidnightFetcher extends BaseDataFetcher<
     const blockFetchOptions: BlockFetchOptions = {
       contractActions: this.config.primitives.some(
         (p) =>
-          p.primitive.type !== "Midnight:Nullifier" &&
+          p.primitive.type !== "Midnight:NullifierAndCommitment" &&
           p.primitive.type !== "Midnight:UnshieldedSpend" &&
           p.primitive.type !== "Midnight:UnshieldedCreate" &&
           p.primitive.type !== "Midnight:ZswapRoot" &&
           p.primitive.type !== "Midnight:TokenMint",
       ),
       zswapLedgerEvents: this.config.primitives.some(
-        (p) => p.primitive.type === "Midnight:Nullifier",
+        (p) => p.primitive.type === "Midnight:NullifierAndCommitment",
       ),
       unshieldedSpentOutputs: this.config.primitives.some(
         (p) => p.primitive.type === "Midnight:UnshieldedSpend",
@@ -181,8 +183,8 @@ export class MidnightFetcher extends BaseDataFetcher<
     const syncResults: PrimitiveType[] = [];
 
     for (const primitiveEntry of primitiveEntries) {
-      if (primitiveEntry.primitive.type === "Midnight:Nullifier") {
-        syncResults.push(...this.fetchNullifiers(height, primitiveEntry, block));
+      if (primitiveEntry.primitive.type === "Midnight:NullifierAndCommitment") {
+        syncResults.push(...this.fetchZswapEvents(height, primitiveEntry, block));
       } else if (primitiveEntry.primitive.type === "Midnight:UnshieldedSpend") {
         syncResults.push(...this.fetchUnshieldedSpends(height, primitiveEntry, block));
       } else if (primitiveEntry.primitive.type === "Midnight:UnshieldedCreate") {
@@ -203,16 +205,19 @@ export class MidnightFetcher extends BaseDataFetcher<
   }
 
   @bound
-  fetchNullifiers(
+  fetchZswapEvents(
     height: number,
     primitiveEntry: PrimitiveEntryType,
     block: MidnightGqlBlockState,
   ): PrimitiveType[] {
+    const capture = primitiveEntry.primitive.capture ?? "both";
     const results: PrimitiveType[] = [];
     for (const tx of block.block.transactions) {
       for (const event of tx.zswapLedgerEvents ?? []) {
-        const decoded = decodeZswapInputEvent(event.raw);
+        const decoded = decodeZswapEvent(event.raw);
         if (!decoded) continue;
+        if (decoded.kind === "nullifier" && capture === "commitments") continue;
+        if (decoded.kind === "commitment" && capture === "nullifiers") continue;
         results.push({
           syncProtocol: {
             name: primitiveEntry.syncProtocol,
@@ -222,12 +227,10 @@ export class MidnightFetcher extends BaseDataFetcher<
           },
           primitive: primitiveEntry.primitive.name,
           output: {
-            payloadType: "midnight-nullifier",
+            payloadType: `midnight-${decoded.kind}`,
             payload: {
-              nullifier: decoded.nullifier,
-              txHash: decoded.txHash,
+              ...decoded,
               eventId: event.id,
-              logicalSegment: decoded.logicalSegment,
             },
           },
         });
@@ -259,6 +262,8 @@ export class MidnightFetcher extends BaseDataFetcher<
               owner: spend.owner,
               intentHash: spend.intentHash,
               outputIndex: spend.outputIndex,
+              value: spend.value,
+              tokenType: spend.tokenType,
               txHash: tx.hash,
             },
           },
@@ -294,6 +299,8 @@ export class MidnightFetcher extends BaseDataFetcher<
               owner: created.owner,
               intentHash: created.intentHash,
               outputIndex: created.outputIndex,
+              value: created.value,
+              tokenType: created.tokenType,
               txHash: tx.hash,
             },
           },

package/src/sync-protocols/midnight/types.ts

@@ -35,7 +35,7 @@ export type CommonFunnelArgs = {
 // Graphql Block
 // =============
 
-// Interfaces approximated from GraphQL schema served by indexer v1.3.1
+// Interfaces approximated from GraphQL schema served by indexer v4.3.3 (/api/v3)
 
 interface ContractCallOrDeploy {
   address: MidnightAddress;

package/src/sync-protocols/midnight/zswap-decoder.ts

@@ -1,58 +1,26 @@
-import { Buffer } from "node:buffer";
 import * as ledger from '@midnight-ntwrk/ledger-v8';
 
-// TODO This alternative implementation should be the native way to decode the event.
-function new_decodeZswapInputEvent(rawHex: string): ledger.Event | null {
-  try {
-    const bytes = Uint8Array.from(
-      Buffer.from(rawHex.replace(/^0x/, ""), "hex"),
-    );
-    const event = ledger.Event.deserialize(bytes);
-    console.log("event", event);
-    // if (event.type === "ZswapInput") {
-      // event.nullifier  — Uint8Array (32 bytes)
-      // event.source.transactionHash
-      // event.source.logicalSegment
-    // } else if (event.type === "ZswapOutput") {
-      // event.commitment, etc.
-    // }
-  } catch {
-    return null;
-  }
-  return null;
-}
-
-// ─── SCALE compact integer decoder ───────────────────────────────────────────
+// Wire format of a raw zswap ledger event, for reference (midnight-ledger 8.x,
+// `midnight-ledger/ledger/src/events.rs` + `storage-core/src/arena.rs`):
 //
-// Bottom 2 bits of the first byte are the mode:
-//   00 = 1-byte  (value in bits [7:2])
-//   01 = 2-byte
-//   10 = 4-byte
-//   11 = n-byte length prefix
+//   19 bytes  outer tag "midnight:event[v9]:"
+//   then a TopoSortedNodes envelope (NOT the struct directly):
+//     compact_u32 node count, and per node: compact_u32 child count,
+//     compact_u64 child indices, compact_u32 data length, data bytes.
+//   The root node's data is:
+//     32 bytes  EventSource.transaction_hash
+//      2 bytes  logical_segment  (LE u16)
+//      2 bytes  physical_segment (LE u16)
+//      1 byte   EventDetails variant: 0=ZswapInput, 1=ZswapOutput, 2+=other
+//     ZswapInput:  32-byte nullifier  + Option<Sp<ContractAddress>> byte
+//     ZswapOutput: 32-byte commitment + variable-length preimage evidence
+//                  + Option<Sp<ContractAddress>> byte + compact_u64 mt_index
+//   A Some(..) contract address is a SEPARATE node in the envelope, shifting
+//   all offsets — so positional parsing is not viable; always deserialize via
+//   the ledger bindings.
 
-function readScaleU32(b: Uint8Array, pos: number): [number, number] {
-  const first = b[pos];
-  const mode = first & 0b11;
-  if (mode === 0b00) {
-    return [(first & 0xFC) >> 2, pos + 1];
-  } else if (mode === 0b01) {
-    const second = b[pos + 1];
-    const v0 = ((first & 0xFC) >> 2) | ((second & 0x03) << 6);
-    const v1 = (second & 0xFC) >> 2;
-    return [(v0 | (v1 << 8)) >>> 0, pos + 2];
-  } else if (mode === 0b10) {
-    const s = b[pos + 1], t = b[pos + 2], u = b[pos + 3];
-    const v0 = ((first & 0xFC) >> 2) | ((s & 0x03) << 6);
-    const v1 = ((s & 0xFC) >> 2) | ((t & 0x03) << 6);
-    const v2 = ((t & 0xFC) >> 2) | ((u & 0x03) << 6);
-    const v3 = (u & 0xFC) >> 2;
-    return [(v0 | (v1 << 8) | (v2 << 16) | (v3 << 24)) >>> 0, pos + 4];
-  } else {
-    const n = ((first & 0xFC) >> 2) + 4;
-    let val = 0;
-    for (let i = 0; i < n; i++) val |= b[pos + 1 + i] << (i * 8);
-    return [val >>> 0, pos + 1 + n];
-  }
+function normalizeHex(hex: string): string {
+  return (hex.startsWith("0x") ? hex.slice(2) : hex).toLowerCase();
 }
 
 function hexToBytes(hex: string): Uint8Array {
@@ -64,60 +32,90 @@ function hexToBytes(hex: string): Uint8Array {
   return arr;
 }
 
-function bytesToHex(bytes: Uint8Array): string {
-  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
-}
-
-// ─── Binary layout for "midnight:event[v9]:" ─────────────────────────────────
-//   19 bytes   outer tag "midnight:event[v9]:"
-//   32 bytes   EventSource.transaction_hash
-//    2 bytes   EventSource.logical_segment  (LE u16)
-//    2 bytes   EventSource.physical_segment (LE u16, skipped)
-//   SCALE u32  EventDetails variant: 0=ZswapInput, 1=ZswapOutput, 2+=other
-//
-//   ZswapInput: 4-byte contract_id + 32-byte CoinNullifier
-
-const OUTER_TAG = "midnight:event[v9]:";
-
-export interface DecodedZswapInput {
-  /** 32-byte transaction hash, hex */
-  txHash: string;
-  /** Logical segment index */
-  logicalSegment: number;
-  /** 32-byte nullifier, hex */
-  nullifier: string;
-}
+/** A zswap ledger event decoded via the native ledger-v8 bindings. */
+export type DecodedZswapEvent =
+  | {
+    kind: "nullifier";
+    /** 32-byte nullifier, hex */
+    nullifier: string;
+    /** 32-byte transaction hash, hex */
+    txHash: string;
+    /** Logical segment index */
+    logicalSegment: number;
+    /** Contract address that spent the coin, hex — absent for user coins */
+    contract?: string;
+  }
+  | {
+    kind: "commitment";
+    /** 32-byte coin commitment, hex */
+    commitment: string;
+    /** Index of the commitment in the zswap Merkle tree, u64 as decimal string */
+    mtIndex: string;
+    /** 32-byte transaction hash, hex */
+    txHash: string;
+    /** Logical segment index */
+    logicalSegment: number;
+    /** Contract address that received the coin, hex — absent for user coins */
+    contract?: string;
+  };
 
 /**
- * Decode a raw SCALE-encoded zswap ledger event.
- * Returns the decoded data if the event is a ZswapInput (nullifier spend),
- * or `null` for ZswapOutput / other variants.
+ * Decode a raw zswap ledger event (ZswapInput or ZswapOutput) using the
+ * native ledger-v8 WASM deserializer.  The indexer's `zswapLedgerEvents`
+ * field only ever carries these two variants, so a `null` return means the
+ * event could not be decoded (e.g. a ledger event-format version bump) and
+ * is logged.
  */
-export function decodeZswapInputEvent(
-  rawHex: string,
-): DecodedZswapInput | null {
+export function decodeZswapEvent(rawHex: string): DecodedZswapEvent | null {
+  let event: ledger.Event;
   try {
-    const b = hexToBytes(rawHex);
-    let pos = OUTER_TAG.length;
-
-    const txHash = bytesToHex(b.slice(pos, pos + 32));
-    pos += 32;
-    const logicalSegment = b[pos] | (b[pos + 1] << 8);
-    pos += 2;
-    pos += 2; // skip physical segment
-
-    const [variant, p1] = readScaleU32(b, pos);
-    pos = p1;
-
-    if (variant !== 0) {
-      return null; // ZswapOutput or other — not a nullifier event
-    }
-
-    pos += 4; // skip 4-byte contract_id
-
-    const nullifier = bytesToHex(b.slice(pos, pos + 32));
-    return { txHash, logicalSegment, nullifier };
-  } catch {
+    event = ledger.Event.deserialize(hexToBytes(rawHex));
+  } catch (err) {
+    console.warn(
+      "[midnight] failed to deserialize zswap ledger event — ledger event format may have changed",
+      { raw: rawHex, error: String(err) },
+    );
     return null;
   }
+  // EventDetails is an open union ({ tag: string } catch-all), so narrow manually.
+  const content = event.content as {
+    tag: string;
+    nullifier?: string;
+    commitment?: string;
+    contract?: string;
+    mtIndex?: bigint;
+  };
+  const source = {
+    txHash: normalizeHex(event.source.transactionHash),
+    logicalSegment: event.source.logicalSegment,
+  };
+  const contract = content.contract != null
+    ? { contract: normalizeHex(content.contract) }
+    : {};
+  if (content.tag === "zswapInput" && content.nullifier != null) {
+    return {
+      kind: "nullifier",
+      nullifier: normalizeHex(content.nullifier),
+      ...contract,
+      ...source,
+    };
+  }
+  if (
+    content.tag === "zswapOutput" &&
+    content.commitment != null &&
+    content.mtIndex != null
+  ) {
+    return {
+      kind: "commitment",
+      commitment: normalizeHex(content.commitment),
+      mtIndex: content.mtIndex.toString(),
+      ...contract,
+      ...source,
+    };
+  }
+  console.warn(
+    "[midnight] unexpected zswap ledger event variant",
+    { raw: rawHex, tag: content.tag },
+  );
+  return null;
 }