@effectstream/sync 0.102.0 → 0.103.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effectstream/sync",
-  "version": "0.102.0",
+  "version": "0.103.1",
   "license": "(MIT OR Apache-2.0)",
   "homepage": "https://effectstream.github.io/docs/",
   "repository": {
@@ -13,10 +13,10 @@
   },
   "exports": "./src/mod.ts",
   "dependencies": {
-    "@effectstream/config": "0.102.0",
-    "@effectstream/db": "0.102.0",
-    "@effectstream/log": "0.102.0",
-    "@effectstream/utils": "0.102.0",
+    "@effectstream/config": "0.103.1",
+    "@effectstream/db": "0.103.1",
+    "@effectstream/log": "0.103.1",
+    "@effectstream/utils": "0.103.1",
     "@midnight-ntwrk/ledger-v8": "8.1.0",
     "@midnight-ntwrk/midnight-js-indexer-public-data-provider": "4.1.1",
     "@midnight-ntwrk/onchain-runtime": "npm:@midnight-ntwrk/onchain-runtime-v3@3.0.0",

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

@@ -19,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<
@@ -78,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",
@@ -183,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") {
@@ -205,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,
@@ -224,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,
             },
           },
         });
@@ -261,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,
             },
           },
@@ -296,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/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;
 }

package/src/sync-protocols/solana/SolanaClient.ts

@@ -43,9 +43,39 @@ export type SolanaTransaction = {
       writable: string[];
       readonly: string[];
     } | null;
+    /**
+     * SPL token balances after the transaction, one record per (token account,
+     * mint) pair it touched. Returned by `getBlock` with
+     * `transactionDetails: "full"`; absent on transactions that touched no token
+     * account, and on validators old enough not to report them.
+     *
+     * `accountIndex` indexes the SAME resolved list as `pre`/`postBalances` — see
+     * {@link resolveAccountKeys} — so a token account reached through a lookup
+     * table is only findable after resolution.
+     */
+    postTokenBalances?: SolanaTokenBalance[] | null;
+    /** Pre-state counterpart of {@link postTokenBalances}. */
+    preTokenBalances?: SolanaTokenBalance[] | null;
   } | null;
 };
 
+export type SolanaTokenBalance = {
+  /** Index into the resolved account list, NOT into `message.accountKeys` alone. */
+  accountIndex: number;
+  mint: string;
+  /** Optional: older validators omit it. */
+  owner?: string;
+  /** The owning token program, i.e. SPL Token or Token-2022. Optional for the same reason. */
+  programId?: string;
+  uiTokenAmount: {
+    /** Raw u64 in base units, as a string. */
+    amount: string;
+    decimals: number;
+    uiAmount: number | null;
+    uiAmountString?: string;
+  };
+};
+
 /**
  * The account list `pre`/`postBalances` are indexed against: static message
  * keys first, then lookup-table writable addresses, then lookup-table readonly

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

@@ -1,6 +1,9 @@
 import {
   ConfigSyncProtocolType,
   type PrimitiveEntry,
+  SOLANA_PRIMITIVE_ACCOUNT_BALANCE,
+  SOLANA_PRIMITIVE_PROGRAM_LOG,
+  SOLANA_PRIMITIVE_TOKEN_ACCOUNT,
 } from "@effectstream/config";
 import { BaseDataFetcher } from "../base/fetcher.ts";
 import type { DataFetched } from "../base/fetcher.ts";
@@ -17,7 +20,11 @@ import type {
   Page,
   PrimitiveType,
 } from "./types.ts";
-import { resolveAccountKeys, SolanaClient } from "./SolanaClient.ts";
+import {
+  resolveAccountKeys,
+  SolanaClient,
+  type SolanaTokenBalance,
+} from "./SolanaClient.ts";
 import { requestTimeoutOf } from "../common/http.ts";
 import { extractProgramLogs } from "./program-logs.ts";
 import { call, sleep, type Operation } from "effection";
@@ -48,6 +55,19 @@ export class SolanaFetcher extends BaseDataFetcher<
    */
   private lastKnownBlockTime: number | undefined;
 
+  /**
+   * Messages already logged by `warnOnce`. `readPrimitives` runs per transaction,
+   * so a misconfigured primitive would otherwise emit an identical line thousands
+   * of times during catch-up and bury everything else.
+   */
+  private readonly warnedOnce = new Set<string>();
+
+  private warnOnce(message: string): void {
+    if (this.warnedOnce.has(message)) return;
+    this.warnedOnce.add(message);
+    console.warn(message);
+  }
+
   constructor(
     readonly config: ConfigType,
   ) {
@@ -252,6 +272,7 @@ export class SolanaFetcher extends BaseDataFetcher<
             writable: string[];
             readonly: string[];
           } | null;
+          postTokenBalances?: SolanaTokenBalance[] | null;
         } | null;
       }[];
     },
@@ -290,65 +311,142 @@ export class SolanaFetcher extends BaseDataFetcher<
       for (const entry of primitiveEntries) {
         const prim = entry.primitive;
 
-        // ── SOLANA:AccountBalance — watch an address's lamport balance ──
-        if (prim.address) {
-          const idx = accountKeys.indexOf(prim.address);
-          if (idx === -1) continue;
-          allPrimitives.push({
-            syncProtocol: {
-              name: entry.syncProtocol,
-              blockNumber: slot,
-              transactionHash: txHash,
-              contractAddress: prim.address,
-              logIndex: txIndex,
-            },
-            primitive: prim.name,
-            output: {
-              payloadType: "solana:balance",
-              payload: {
-                address: prim.address,
-                lamports: postBalances[idx] ?? 0,
-                slot,
+        // Dispatch on `prim.type`, NOT on which optional fields happen to be set.
+        // `SolanaPrimitive` is a flat bag of optionals, so field-truthy dispatch
+        // fails two ways once a third primitive exists: a TokenAccount entry
+        // matches no field branch and silently emits nothing, and any field it
+        // shares with an earlier branch (`address` being the natural name for a
+        // token account) routes it into that branch instead. Neither is a type
+        // error. `type` is always populated at runtime because
+        // `Primitive.getConfig()` sets it and runtime/src/main.ts replaces the
+        // config entry with its output.
+        switch (prim.type) {
+          // ── SOLANA:AccountBalance — watch an address's lamport balance ──
+          case SOLANA_PRIMITIVE_ACCOUNT_BALANCE: {
+            if (!prim.address) continue;
+            const idx = accountKeys.indexOf(prim.address);
+            if (idx === -1) continue;
+            allPrimitives.push({
+              syncProtocol: {
+                name: entry.syncProtocol,
+                blockNumber: slot,
+                transactionHash: txHash,
+                contractAddress: prim.address,
+                logIndex: txIndex,
               },
-            },
-          });
-          continue;
-        }
-
-        // ── SOLANA:ProgramLog — logs the watched programId actually emitted ──
-        if (prim.programId) {
-          // Source of truth is the log stream's invoke/success framing, NOT
-          // accountKeys: naming a program as an account doesn't invoke it, and
-          // a program reached through a lookup table isn't in accountKeys at
-          // all. See program-logs.ts.
-          const programLogs = extractProgramLogs(logs, prim.programId);
-          if (programLogs == null) continue;
-          // Filter by eventType if specified — against this program's own lines
-          // only, so another program can't trigger it by echoing the string.
-          if (prim.eventType) {
-            const hasMatchingLog = programLogs.some((log) =>
-              log.includes(prim.eventType!)
-            );
-            if (!hasMatchingLog) continue;
+              primitive: prim.name,
+              output: {
+                payloadType: "solana:balance",
+                payload: {
+                  address: prim.address,
+                  lamports: postBalances[idx] ?? 0,
+                  slot,
+                },
+              },
+            });
+            continue;
           }
-          allPrimitives.push({
-            syncProtocol: {
-              name: entry.syncProtocol,
-              blockNumber: slot,
-              transactionHash: txHash,
-              contractAddress: prim.programId,
-              logIndex: txIndex,
-            },
-            primitive: prim.name,
-            output: {
-              payloadType: "solana:transaction",
-              payload: {
-                programId: prim.programId,
-                slot,
-                logMessages: programLogs,
+
+          // ── SOLANA:ProgramLog — logs the watched programId actually emitted ──
+          case SOLANA_PRIMITIVE_PROGRAM_LOG: {
+            if (!prim.programId) continue;
+            // Source of truth is the log stream's invoke/success framing, NOT
+            // accountKeys: naming a program as an account doesn't invoke it, and
+            // a program reached through a lookup table isn't in accountKeys at
+            // all. See program-logs.ts.
+            const programLogs = extractProgramLogs(logs, prim.programId);
+            if (programLogs == null) continue;
+            // Filter by eventType if specified — against this program's own lines
+            // only, so another program can't trigger it by echoing the string.
+            if (prim.eventType) {
+              const hasMatchingLog = programLogs.some((log) =>
+                log.includes(prim.eventType!)
+              );
+              if (!hasMatchingLog) continue;
+            }
+            allPrimitives.push({
+              syncProtocol: {
+                name: entry.syncProtocol,
+                blockNumber: slot,
+                transactionHash: txHash,
+                contractAddress: prim.programId,
+                logIndex: txIndex,
               },
-            },
-          });
+              primitive: prim.name,
+              output: {
+                payloadType: "solana:transaction",
+                payload: {
+                  programId: prim.programId,
+                  slot,
+                  logMessages: programLogs,
+                },
+              },
+            });
+            continue;
+          }
+
+          // ── SOLANA:TokenAccount — SPL balance of a watched token account ──
+          case SOLANA_PRIMITIVE_TOKEN_ACCOUNT: {
+            // An entry with no filter would match every token balance on chain.
+            // The primitive constructor rejects that, so reaching here means a
+            // hand-built config bypassed it.
+            if (!prim.mint && !prim.owner && !prim.tokenAccount) {
+              this.warnOnce(
+                `[Solana] primitive "${prim.name}" is ${SOLANA_PRIMITIVE_TOKEN_ACCOUNT} with no ` +
+                  `mint, owner or tokenAccount — it would match every token balance, so it is skipped.`,
+              );
+              continue;
+            }
+            for (const bal of tx.meta.postTokenBalances ?? []) {
+              if (prim.mint && bal.mint !== prim.mint) continue;
+              if (prim.owner && bal.owner !== prim.owner) continue;
+              if (prim.tokenProgramId && bal.programId !== prim.tokenProgramId) {
+                continue;
+              }
+              // `accountIndex` indexes the RESOLVED list, same as postBalances, so
+              // a token account pulled in via a lookup table is only findable here
+              // (security fix B3 applied to token balances).
+              const tokenAccount = accountKeys[bal.accountIndex];
+              if (tokenAccount == null) continue;
+              if (prim.tokenAccount && tokenAccount !== prim.tokenAccount) {
+                continue;
+              }
+              allPrimitives.push({
+                syncProtocol: {
+                  name: entry.syncProtocol,
+                  blockNumber: slot,
+                  transactionHash: txHash,
+                  contractAddress: bal.mint,
+                  logIndex: txIndex,
+                },
+                primitive: prim.name,
+                output: {
+                  payloadType: "solana:token-balance",
+                  payload: {
+                    tokenAccount,
+                    mint: bal.mint,
+                    owner: bal.owner ?? "",
+                    amount: bal.uiTokenAmount.amount,
+                    decimals: bal.uiTokenAmount.decimals,
+                    slot,
+                  },
+                },
+              });
+            }
+            continue;
+          }
+
+          default:
+            // A Solana sync protocol carrying a primitive type this fetcher does
+            // not implement produced nothing and said nothing before. Warn once
+            // per type rather than per transaction, which would be thousands of
+            // identical lines during catch-up.
+            this.warnOnce(
+              `[Solana] primitive "${prim.name}" has unsupported type "${prim.type}" — ignored. ` +
+                `Supported: ${SOLANA_PRIMITIVE_ACCOUNT_BALANCE}, ${SOLANA_PRIMITIVE_PROGRAM_LOG}, ` +
+                `${SOLANA_PRIMITIVE_TOKEN_ACCOUNT}.`,
+            );
+            continue;
         }
       }
     }

package/src/sync-protocols/solana/read-primitives.test.ts

@@ -1,4 +1,9 @@
 import { expect, test } from "bun:test";
+import {
+  SOLANA_PRIMITIVE_ACCOUNT_BALANCE,
+  SOLANA_PRIMITIVE_PROGRAM_LOG,
+  SOLANA_PRIMITIVE_TOKEN_ACCOUNT,
+} from "@effectstream/config";
 import { SolanaFetcher } from "./fetcher.ts";
 import type { ConfigType } from "./types.ts";
 
@@ -33,13 +38,25 @@ function run(fetcher: SolanaFetcher, slot: number, block: any, entries: any[]) {
   return step.value as any[];
 }
 
+// `type` is what readPrimitives dispatches on. These fixtures used to omit it,
+// which the old field-truthy dispatch tolerated — real configs always carry it,
+// because `Primitive.getConfig()` sets it and runtime/src/main.ts substitutes its
+// output for the raw config entry.
 const programLogEntry = {
   syncProtocol: "parallelSolanaRPC",
-  primitive: { name: "WatchedLog", programId: WATCHED_PROGRAM },
+  primitive: {
+    name: "WatchedLog",
+    type: SOLANA_PRIMITIVE_PROGRAM_LOG,
+    programId: WATCHED_PROGRAM,
+  },
 };
 const balanceEntry = {
   syncProtocol: "parallelSolanaRPC",
-  primitive: { name: "WatchedBalance", address: WATCHED_ADDRESS },
+  primitive: {
+    name: "WatchedBalance",
+    type: SOLANA_PRIMITIVE_ACCOUNT_BALANCE,
+    address: WATCHED_ADDRESS,
+  },
 };
 
 /** A transaction that genuinely invoked the watched program. */
@@ -136,7 +153,12 @@ test("eventType filters against the program's OWN lines only", () => {
   });
   const entry = {
     syncProtocol: "parallelSolanaRPC",
-    primitive: { name: "WatchedLog", programId: WATCHED_PROGRAM, eventType: "MARKER" },
+    primitive: {
+      name: "WatchedLog",
+      type: SOLANA_PRIMITIVE_PROGRAM_LOG,
+      programId: WATCHED_PROGRAM,
+      eventType: "MARKER",
+    },
   };
   expect(run(makeFetcher(), 42, { transactions: [tx] }, [entry])).toEqual([]);
 });
@@ -186,3 +208,228 @@ test("dispatches both primitive kinds from one transaction", () => {
 test("returns nothing when no primitives are configured", () => {
   expect(run(makeFetcher(), 42, { transactions: [invokingTx()] }, [])).toEqual([]);
 });
+
+// ───────────────────────── SOLANA:TokenAccount ─────────────────────────
+
+const MINT = "Mint111111111111111111111111111111111111111";
+const OTHER_MINT = "0therMint11111111111111111111111111111111";
+const TOKEN_ACCOUNT = "Tok111111111111111111111111111111111111111";
+const OWNER = "0wner11111111111111111111111111111111111111";
+const TOKEN_PROGRAM = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+const TOKEN_2022_PROGRAM = "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb";
+
+const tokenEntry = {
+  syncProtocol: "parallelSolanaRPC",
+  primitive: {
+    name: "WatchedToken",
+    type: SOLANA_PRIMITIVE_TOKEN_ACCOUNT,
+    mint: MINT,
+  },
+};
+
+/** `meta.postTokenBalances` record shape, per the JSON-RPC `getBlock` response. */
+function tokenBalance(overrides: Record<string, unknown> = {}) {
+  return {
+    accountIndex: 0,
+    mint: MINT,
+    owner: OWNER,
+    programId: TOKEN_PROGRAM,
+    uiTokenAmount: {
+      amount: "1500000000",
+      decimals: 9,
+      uiAmount: 1.5,
+      uiAmountString: "1.5",
+    },
+    ...overrides,
+  };
+}
+
+/** A successful transaction carrying token balances. */
+function tokenTx(
+  balances: Record<string, unknown>[],
+  overrides: Record<string, unknown> = {},
+) {
+  return {
+    transaction: {
+      message: { accountKeys: [TOKEN_ACCOUNT, WATCHED_PROGRAM] },
+      signatures: ["sig-tok"],
+    },
+    meta: {
+      err: null,
+      logMessages: [],
+      postBalances: [0, 0],
+      postTokenBalances: balances,
+      ...overrides,
+    },
+  };
+}
+
+test("TokenAccount emits the post balance for a watched mint", () => {
+  const out = run(makeFetcher(), 11, { transactions: [tokenTx([tokenBalance()])] }, [
+    tokenEntry,
+  ]);
+  expect(out.length).toBe(1);
+  expect(out[0].primitive).toBe("WatchedToken");
+  expect(out[0].output.payloadType).toBe("solana:token-balance");
+  expect(out[0].output.payload).toEqual({
+    tokenAccount: TOKEN_ACCOUNT,
+    mint: MINT,
+    owner: OWNER,
+    // Raw u64 as a string: 1.5 tokens at 9 decimals does not survive a JS number
+    // once amounts get large, so the grammar carries the base units.
+    amount: "1500000000",
+    decimals: 9,
+    slot: 11,
+  });
+});
+
+test("TokenAccount resolves lookup-table token accounts (security fix B3)", () => {
+  // `accountIndex` indexes the resolved list — static keys, then ALT writable, then
+  // ALT readonly — so a token account reached through an ALT is at an index past
+  // the end of message.accountKeys. Without resolution this reads undefined and
+  // drops the balance silently.
+  // Two static keys (indices 0-1), then ALT writable (2), then ALT readonly (3),
+  // so the watched token account sits at index 3 — past the end of accountKeys.
+  const tx = tokenTx([tokenBalance({ accountIndex: 3 })], {
+    loadedAddresses: {
+      writable: ["W1111111111111111111111111111111111111111111"],
+      readonly: [TOKEN_ACCOUNT],
+    },
+  });
+  tx.transaction.message.accountKeys = [OTHER_PROGRAM, WATCHED_PROGRAM];
+  const out = run(makeFetcher(), 12, { transactions: [tx] }, [tokenEntry]);
+  expect(out.length).toBe(1);
+  expect(out[0].output.payload.tokenAccount).toBe(TOKEN_ACCOUNT);
+});
+
+test("TokenAccount SKIPS a reverted transaction (security fix B2)", () => {
+  const tx = tokenTx([tokenBalance()], { err: { InstructionError: [0, "Custom"] } });
+  expect(run(makeFetcher(), 13, { transactions: [tx] }, [tokenEntry])).toEqual([]);
+});
+
+test("TokenAccount ignores balances for a different mint", () => {
+  const tx = tokenTx([tokenBalance({ mint: OTHER_MINT })]);
+  expect(run(makeFetcher(), 14, { transactions: [tx] }, [tokenEntry])).toEqual([]);
+});
+
+test("TokenAccount narrows by owner", () => {
+  const entry = {
+    syncProtocol: "parallelSolanaRPC",
+    primitive: {
+      name: "WatchedToken",
+      type: SOLANA_PRIMITIVE_TOKEN_ACCOUNT,
+      mint: MINT,
+      owner: OWNER,
+    },
+  };
+  expect(
+    run(makeFetcher(), 15, { transactions: [tokenTx([tokenBalance()])] }, [entry]),
+  ).toHaveLength(1);
+  expect(
+    run(
+      makeFetcher(),
+      15,
+      { transactions: [tokenTx([tokenBalance({ owner: "someone-else" })])] },
+      [entry],
+    ),
+  ).toEqual([]);
+});
+
+test("TokenAccount narrows by tokenProgramId, separating Token-2022", () => {
+  const entry = {
+    syncProtocol: "parallelSolanaRPC",
+    primitive: {
+      name: "WatchedToken",
+      type: SOLANA_PRIMITIVE_TOKEN_ACCOUNT,
+      mint: MINT,
+      tokenProgramId: TOKEN_2022_PROGRAM,
+    },
+  };
+  // Same mint, classic SPL Token program — must not match a Token-2022 filter.
+  expect(
+    run(makeFetcher(), 16, { transactions: [tokenTx([tokenBalance()])] }, [entry]),
+  ).toEqual([]);
+  expect(
+    run(
+      makeFetcher(),
+      16,
+      { transactions: [tokenTx([tokenBalance({ programId: TOKEN_2022_PROGRAM })])] },
+      [entry],
+    ),
+  ).toHaveLength(1);
+});
+
+test("TokenAccount narrows by tokenAccount", () => {
+  const entry = {
+    syncProtocol: "parallelSolanaRPC",
+    primitive: {
+      name: "WatchedToken",
+      type: SOLANA_PRIMITIVE_TOKEN_ACCOUNT,
+      tokenAccount: TOKEN_ACCOUNT,
+    },
+  };
+  expect(
+    run(makeFetcher(), 17, { transactions: [tokenTx([tokenBalance()])] }, [entry]),
+  ).toHaveLength(1);
+  // accountIndex 1 resolves to WATCHED_PROGRAM, not the watched token account.
+  expect(
+    run(
+      makeFetcher(),
+      17,
+      { transactions: [tokenTx([tokenBalance({ accountIndex: 1 })])] },
+      [entry],
+    ),
+  ).toEqual([]);
+});
+
+test("TokenAccount emits one primitive per matching balance record", () => {
+  const tx = tokenTx([
+    tokenBalance(),
+    tokenBalance({ accountIndex: 1, owner: "second-owner" }),
+    tokenBalance({ mint: OTHER_MINT, accountIndex: 1 }),
+  ]);
+  const out = run(makeFetcher(), 18, { transactions: [tx] }, [tokenEntry]);
+  expect(out.length).toBe(2);
+  expect(out.map((p) => p.output.payload.owner)).toEqual([OWNER, "second-owner"]);
+});
+
+test("TokenAccount tolerates a transaction with no token balances", () => {
+  expect(run(makeFetcher(), 19, { transactions: [invokingTx()] }, [tokenEntry]))
+    .toEqual([]);
+});
+
+test("a TokenAccount entry is never treated as an AccountBalance", () => {
+  // The regression the type dispatch exists for. `SolanaPrimitive` is a flat bag of
+  // optionals, so a config can set `address` on a TokenAccount entry — under the old
+  // field-truthy dispatch (`if (prim.address)` first) that emitted a lamport-balance
+  // event under the token primitive's name.
+  const entry = {
+    syncProtocol: "parallelSolanaRPC",
+    primitive: {
+      name: "WatchedToken",
+      type: SOLANA_PRIMITIVE_TOKEN_ACCOUNT,
+      mint: MINT,
+      address: TOKEN_ACCOUNT,
+    },
+  };
+  const out = run(makeFetcher(), 20, { transactions: [tokenTx([tokenBalance()])] }, [
+    entry,
+  ]);
+  expect(out.length).toBe(1);
+  expect(out[0].output.payloadType).toBe("solana:token-balance");
+  expect(out[0].output.payload).not.toHaveProperty("lamports");
+});
+
+test("an unsupported primitive type is ignored rather than misrouted", () => {
+  const entry = {
+    syncProtocol: "parallelSolanaRPC",
+    primitive: {
+      name: "FromTheFuture",
+      type: "SOLANA:NotImplementedYet",
+      address: WATCHED_ADDRESS,
+      programId: WATCHED_PROGRAM,
+    },
+  };
+  expect(run(makeFetcher(), 21, { transactions: [invokingTx()] }, [entry]))
+    .toEqual([]);
+});

package/test/zswap-decoder.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from "bun:test";
+import { Buffer } from "node:buffer";
+import { decodeZswapEvent } from "../src/sync-protocols/midnight/zswap-decoder.ts";
+
+// Synthetic events built per the real midnight-ledger 8.x wire format:
+// "midnight:event[v9]:" tag + TopoSortedNodes envelope wrapping the event
+// struct. Both blobs round-trip through the native ledger-v8 deserializer.
+
+function compactU32(n: number): Buffer {
+  if (n < 64) return Buffer.from([n << 2]);
+  if (n < 16384) {
+    const v = (n << 2) | 0b01;
+    return Buffer.from([v & 0xff, (v >> 8) & 0xff]);
+  }
+  throw new Error("value too large for this helper");
+}
+
+const TX_HASH = Buffer.alloc(32, 0xaa);
+const BODY32 = Buffer.alloc(32, 0xbb);
+// logical=3, physical=1
+const SEGMENTS = Buffer.from([0x03, 0x00, 0x01, 0x00]);
+const CONTRACT_NONE = Buffer.from([0x01]);
+
+function wrapEnvelope(data: Buffer): string {
+  return Buffer.concat([
+    Buffer.from("midnight:event[v9]:", "ascii"),
+    compactU32(1), // node count
+    compactU32(0), // child count of the single node
+    compactU32(data.length),
+    data,
+  ]).toString("hex");
+}
+
+describe("decodeZswapEvent", () => {
+  test("decodes a ZswapInput (nullifier) event", () => {
+    const raw = wrapEnvelope(Buffer.concat([
+      TX_HASH,
+      SEGMENTS,
+      Buffer.from([0x00]), // variant: ZswapInput
+      BODY32, // nullifier
+      CONTRACT_NONE,
+    ]));
+    expect(decodeZswapEvent(raw)).toEqual({
+      kind: "nullifier",
+      nullifier: "bb".repeat(32),
+      txHash: "aa".repeat(32),
+      logicalSegment: 3,
+    });
+  });
+
+  test("decodes a ZswapOutput (commitment) event", () => {
+    const raw = wrapEnvelope(Buffer.concat([
+      TX_HASH,
+      SEGMENTS,
+      Buffer.from([0x01]), // variant: ZswapOutput
+      BODY32, // commitment
+      Buffer.from([0x02]), // ZswapPreimageEvidence::None
+      CONTRACT_NONE,
+      compactU32(7), // mt_index
+    ]));
+    expect(decodeZswapEvent(raw)).toEqual({
+      kind: "commitment",
+      commitment: "bb".repeat(32),
+      mtIndex: "7",
+      txHash: "aa".repeat(32),
+      logicalSegment: 3,
+    });
+  });
+
+  test("returns null for undecodable input", () => {
+    expect(decodeZswapEvent("deadbeef")).toBeNull();
+    expect(decodeZswapEvent("")).toBeNull();
+  });
+});