@effectstream/sm 0.102.0 → 0.103.1

package/README.md

@@ -77,7 +77,7 @@ inferred at call sites rather than imported directly.
 
 Subpath exports:
 
-- `@effectstream/sm/builtin`: `PrimitiveTypeERC20`, `PrimitiveTypeERC721`, `PrimitiveTypeERC1155`, `PrimitiveTypeCardanoTransfer`, `PrimitiveTypeMidnightGeneric`, and 20+ more chain-specific event tags.
+- `@effectstream/sm/builtin`: `PrimitiveTypeEVMERC20`, `PrimitiveTypeEVMERC721`, `PrimitiveTypeEVMERC1155`, `PrimitiveTypeEVMEffectstreamL2`, `PrimitiveTypeCardanoTransfer`, `PrimitiveTypeMidnightGeneric`, `PrimitiveTypeUtxorpcGeneric`, and 20+ more chain-specific event tags.
 - `@effectstream/sm/grammar`: the underlying grammar/parsing utilities, also re-exported from `@effectstream/concise`.
 
 ## Examples

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effectstream/sm",
-  "version": "0.102.0",
+  "version": "0.103.1",
   "license": "(MIT OR Apache-2.0)",
   "homepage": "https://effectstream.github.io/docs/",
   "repository": {
@@ -17,14 +17,14 @@
     "./grammar": "./primitives/src/grammar.ts"
   },
   "dependencies": {
-    "@effectstream/concise": "0.102.0",
-    "@effectstream/config": "0.102.0",
-    "@effectstream/coroutine": "0.102.0",
-    "@effectstream/crypto": "0.102.0",
-    "@effectstream/db": "0.102.0",
-    "@effectstream/event-client": "0.102.0",
-    "@effectstream/log": "0.102.0",
-    "@effectstream/utils": "0.102.0",
+    "@effectstream/concise": "0.103.1",
+    "@effectstream/config": "0.103.1",
+    "@effectstream/coroutine": "0.103.1",
+    "@effectstream/crypto": "0.103.1",
+    "@effectstream/db": "0.103.1",
+    "@effectstream/event-client": "0.103.1",
+    "@effectstream/log": "0.103.1",
+    "@effectstream/utils": "0.103.1",
     "pg": "8.21.0",
     "pg-tx": "^1.0.1",
     "@sinclair/typebox": "0.34.41",

package/primitives/src/builtin.ts

@@ -1,7 +1,13 @@
 // list of built-in primitives
 // this list is exposed to the effectstream-sdk modules via the @effectstream/sm/builtin module
+import {
+  SOLANA_PRIMITIVE_ACCOUNT_BALANCE,
+  SOLANA_PRIMITIVE_PROGRAM_LOG,
+  SOLANA_PRIMITIVE_TOKEN_ACCOUNT,
+} from "@effectstream/config";
+
 export const PrimitiveTypeMidnightGeneric = "Midnight:Generic" as const;
-export const PrimitiveTypeMidnightNullifier = "Midnight:Nullifier" as const;
+export const PrimitiveTypeMidnightNullifierAndCommitment = "Midnight:NullifierAndCommitment" as const;
 export const PrimitiveTypeMidnightUnshieldedSpend = "Midnight:UnshieldedSpend" as const;
 export const PrimitiveTypeMidnightUnshieldedCreate = "Midnight:UnshieldedCreate" as const;
 export const PrimitiveTypeMidnightZswapRoot = "Midnight:ZswapRoot" as const;
@@ -33,12 +39,21 @@ export const PrimitiveTypeNEARIntent = "NEAR:Intent" as const;
 export const PrimitiveTypeNEARGeneric = "NEAR:Generic" as const;
 export const PrimitiveTypeNEARAccountWatch = "NEAR:AccountWatch" as const;
 
-export const PrimitiveTypeSolanaProgramLog = "SOLANA:ProgramLog" as const;
-export const PrimitiveTypeSolanaAccountBalance = "SOLANA:AccountBalance" as const;
+// Solana's discriminators are defined in @effectstream/config, beside the
+// `SolanaPrimitive` type they discriminate, because the sync fetcher dispatches on
+// them and @effectstream/sync does not depend on @effectstream/sm. Re-exported here
+// under the PrimitiveType* names so consumers keep importing them from
+// @effectstream/sm/builtin like every other primitive.
+// Aliased through local consts rather than `export { X as Y } from`, because the
+// `BuiltInPrimitives` union below needs `typeof PrimitiveTypeSolana*` in scope and a
+// bare re-export does not bind the name locally.
+export const PrimitiveTypeSolanaProgramLog = SOLANA_PRIMITIVE_PROGRAM_LOG;
+export const PrimitiveTypeSolanaAccountBalance = SOLANA_PRIMITIVE_ACCOUNT_BALANCE;
+export const PrimitiveTypeSolanaTokenAccount = SOLANA_PRIMITIVE_TOKEN_ACCOUNT;
 
 type BuiltInPrimitives =
     typeof PrimitiveTypeMidnightGeneric |
-    typeof PrimitiveTypeMidnightNullifier |
+    typeof PrimitiveTypeMidnightNullifierAndCommitment |
     typeof PrimitiveTypeMidnightUnshieldedSpend |
     typeof PrimitiveTypeMidnightUnshieldedCreate |
     typeof PrimitiveTypeMidnightZswapRoot |
@@ -63,7 +78,8 @@ type BuiltInPrimitives =
     typeof PrimitiveTypeNEARGeneric |
     typeof PrimitiveTypeNEARAccountWatch |
     typeof PrimitiveTypeSolanaProgramLog |
-    typeof PrimitiveTypeSolanaAccountBalance // |
+    typeof PrimitiveTypeSolanaAccountBalance |
+    typeof PrimitiveTypeSolanaTokenAccount // |
     // typeof PrimitiveTypeEVMGeneric
 ;
 

package/primitives/src/grammar.ts

@@ -17,6 +17,7 @@ import { nearGenericGrammar } from "./near-generic/near-generic-grammar.ts";
 import { nearAccountWatchGrammar } from "./near-account-watch/near-account-watch-grammar.ts";
 import { solanaProgramLogGrammar } from "./solana-program-log/solana-program-log-grammar.ts";
 import { solanaAccountBalanceGrammar } from "./solana-account-balance/solana-account-balance-grammar.ts";
+import { solanaTokenAccountGrammar } from "./solana-token-account/solana-token-account-grammar.ts";
 import { mintBurnGrammar } from "./cardano-mint-burn/mint-burn-grammar.ts";
 import { transferGrammar } from "./cardano-transfer/transfer-grammar.ts";
 import { poolDelegationGrammar } from "./cardano-pool-delegation/pool-delegation-grammar.ts";
@@ -42,6 +43,7 @@ export const builtinGrammars = {
   nearAccountWatch: nearAccountWatchGrammar,
   solanaProgramLog: solanaProgramLogGrammar,
   solanaAccountBalance: solanaAccountBalanceGrammar,
+  solanaTokenAccount: solanaTokenAccountGrammar,
   cardanoMintBurn: mintBurnGrammar,
   cardanoTransfer: transferGrammar,
   cardanoPoolDelegation: poolDelegationGrammar,

package/primitives/src/midnight-nullifier-and-commitment/midnight-nullifier-and-commitment-grammar.ts

@@ -0,0 +1,37 @@
+import { Type } from "@sinclair/typebox";
+
+export const midnightNullifierAndCommitmentGrammar = [
+  [
+    "payload",
+    Type.Union([
+      Type.Object({
+        kind: Type.Literal("nullifier"),
+        /** 32-byte nullifier, hex (no 0x prefix) */
+        nullifier: Type.String(),
+        /** 32-byte transaction hash, hex (no 0x prefix) */
+        txHash: Type.String(),
+        /** Indexer-assigned zswap ledger event id */
+        eventId: Type.Number(),
+        /** Logical segment the event was emitted in */
+        logicalSegment: Type.Number(),
+        /** Contract address that spent the coin, hex — absent for user coins */
+        contract: Type.Optional(Type.String()),
+      }),
+      Type.Object({
+        kind: Type.Literal("commitment"),
+        /** 32-byte coin commitment, hex (no 0x prefix) */
+        commitment: Type.String(),
+        /** Index of the commitment in the zswap Merkle tree (u64 as decimal string) */
+        mtIndex: Type.String(),
+        /** 32-byte transaction hash, hex (no 0x prefix) */
+        txHash: Type.String(),
+        /** Indexer-assigned zswap ledger event id */
+        eventId: Type.Number(),
+        /** Logical segment the event was emitted in */
+        logicalSegment: Type.Number(),
+        /** Contract address that received the coin, hex — absent for user coins */
+        contract: Type.Optional(Type.String()),
+      }),
+    ]),
+  ],
+] as const;

package/primitives/src/{midnight-nullifier/midnight-nullifier.ts → midnight-nullifier-and-commitment/midnight-nullifier-and-commitment.ts}

@@ -16,28 +16,40 @@ import type {
   ProtocolPrimitiveMap,
 } from "@effectstream/config";
 import type { SyncStateUpdateStream } from "@effectstream/coroutine";
-import { PrimitiveTypeMidnightNullifier } from "../builtin.ts";
-import { midnightNullifierGrammar } from "./midnight-nullifier-grammar.ts";
+import { PrimitiveTypeMidnightNullifierAndCommitment } from "../builtin.ts";
+import { midnightNullifierAndCommitmentGrammar } from "./midnight-nullifier-and-commitment-grammar.ts";
+
+/** Which zswap ledger event kinds the primitive emits. */
+export type MidnightZswapCapture = "nullifiers" | "commitments" | "both";
 
 /**
- * MidnightNullifierPrimitive
+ * MidnightNullifierAndCommitmentPrimitive
  *
- * Watches all ZswapInput (nullifier-spend) events on the Midnight shielded
- * ledger.  One state-machine input is emitted per nullifier event observed in
- * a block, regardless of which contract produced it.
+ * Watches ZswapInput (nullifier-spend) and ZswapOutput (commitment-create)
+ * events on the Midnight shielded ledger.  Both event kinds arrive in the
+ * same indexer field (`zswapLedgerEvents`), so tracking both costs no extra
+ * indexer queries.  One state-machine input is emitted per event observed in
+ * a block, regardless of which contract produced it.  The `capture` option
+ * selects which kinds are emitted (default: both).
  *
  * Usage:
  *   stm.addStateTransition("myPrefix", function* (data) {
  *     const { payload } = data.parsedInput;
- *     // payload = { nullifier, txHash, eventId, logicalSegment }
+ *     if (payload.kind === "nullifier") {
+ *       // { kind, nullifier, txHash, eventId, logicalSegment, contract? }
+ *     } else {
+ *       // { kind, commitment, mtIndex, txHash, eventId, logicalSegment, contract? }
+ *     }
  *   });
  */
-export class MidnightNullifierPrimitive extends Primitive<
+export class MidnightNullifierAndCommitmentPrimitive extends Primitive<
   ConfigSyncProtocolType.MIDNIGHT_PARALLEL,
-  typeof midnightNullifierGrammar
+  typeof midnightNullifierAndCommitmentGrammar
 > {
-  readonly internalTypeName = PrimitiveTypeMidnightNullifier;
-  override readonly grammar = midnightNullifierGrammar;
+  readonly internalTypeName = PrimitiveTypeMidnightNullifierAndCommitment;
+  override readonly grammar = midnightNullifierAndCommitmentGrammar;
+
+  readonly capture: MidnightZswapCapture;
 
   override dynamicTables = undefined;
   override getIntermediatePrefix(): string[] {
@@ -51,8 +63,11 @@ export class MidnightNullifierPrimitive extends Primitive<
     instanceName: string;
     startBlockHeight: number;
     stateMachinePrefix: string;
+    /** Which zswap event kinds to emit. Default: "both". */
+    capture?: MidnightZswapCapture;
   }) {
     super(config);
+    this.capture = config.capture ?? "both";
   }
 
   override *getPayload(
@@ -65,12 +80,19 @@ export class MidnightNullifierPrimitive extends Primitive<
     data: {
       fromAddressAndType: AddressAndType;
       stateMachinePayload:
-        | StaticDecode<CommandTuple<string, typeof midnightNullifierGrammar>>
+        | StaticDecode<
+          CommandTuple<string, typeof midnightNullifierAndCommitmentGrammar>
+        >
         | null;
-      accountingPayload: ParamToData<typeof midnightNullifierGrammar>;
+      accountingPayload: ParamToData<
+        typeof midnightNullifierAndCommitmentGrammar
+      >;
     }[];
   }> {
-    const payload = primitiveTransactionData.output.payload;
+    // The sync-protocol payload map types Midnight payloads as Record<string, any>;
+    // the fetcher's fetchZswapEvents builds exactly the grammar's payload shape.
+    const payload = primitiveTransactionData.output
+      .payload as ParamToData<typeof this.grammar>["payload"];
 
     const accountingPayload: ParamToData<typeof this.grammar> = {
       payload,
@@ -109,6 +131,7 @@ export class MidnightNullifierPrimitive extends Primitive<
       type: this.internalTypeName,
       startBlockHeight: this.startBlockHeight,
       scheduledPrefix: this.stateMachinePrefix ?? "",
+      capture: this.capture,
     } as const;
   }
 }

package/primitives/src/midnight-unshielded-create/midnight-unshielded-create-grammar.ts

@@ -3,6 +3,19 @@ import { Type } from "@sinclair/typebox";
 export const midnightUnshieldedCreateGrammar = [
   [
     "payload",
-    Type.Any(),
+    Type.Object({
+      /** Bech32m owner address of the created UTXO */
+      owner: Type.String(),
+      /** Hex-encoded hash of the creating intent */
+      intentHash: Type.String(),
+      /** Output index within the creating intent's offer */
+      outputIndex: Type.Number(),
+      /** u128 value as a decimal string */
+      value: Type.String(),
+      /** Hex-encoded serialized token type */
+      tokenType: Type.String(),
+      /** Hash of the creating transaction */
+      txHash: Type.String(),
+    }),
   ],
 ] as const;

package/primitives/src/midnight-unshielded-create/midnight-unshielded-create.ts

@@ -77,7 +77,10 @@ export class MidnightUnshieldedCreatePrimitive extends Primitive<
       accountingPayload: ParamToData<typeof midnightUnshieldedCreateGrammar>;
     }[];
   }> {
-    const payload = primitiveTransactionData.output.payload;
+    // The sync-protocol payload map types Midnight payloads as Record<string, any>;
+    // the fetcher's fetchUnshieldedCreates builds exactly the grammar's payload shape.
+    const payload = primitiveTransactionData.output
+      .payload as ParamToData<typeof this.grammar>["payload"];
 
     const accountingPayload: ParamToData<typeof this.grammar> = {
       payload,

package/primitives/src/midnight-unshielded-spend/midnight-unshielded-spend-grammar.ts

@@ -3,6 +3,19 @@ import { Type } from "@sinclair/typebox";
 export const midnightUnshieldedSpendGrammar = [
   [
     "payload",
-    Type.Any(),
+    Type.Object({
+      /** Bech32m owner address of the spent UTXO */
+      owner: Type.String(),
+      /** Hex-encoded hash of the intent that CREATED the spent UTXO */
+      intentHash: Type.String(),
+      /** Output index within the creating intent's offer */
+      outputIndex: Type.Number(),
+      /** u128 value as a decimal string */
+      value: Type.String(),
+      /** Hex-encoded serialized token type */
+      tokenType: Type.String(),
+      /** Hash of the spending transaction */
+      txHash: Type.String(),
+    }),
   ],
 ] as const;

package/primitives/src/midnight-unshielded-spend/midnight-unshielded-spend.ts

@@ -71,7 +71,10 @@ export class MidnightUnshieldedSpendPrimitive extends Primitive<
       accountingPayload: ParamToData<typeof midnightUnshieldedSpendGrammar>;
     }[];
   }> {
-    const payload = primitiveTransactionData.output.payload;
+    // The sync-protocol payload map types Midnight payloads as Record<string, any>;
+    // the fetcher's fetchUnshieldedSpends builds exactly the grammar's payload shape.
+    const payload = primitiveTransactionData.output
+      .payload as ParamToData<typeof this.grammar>["payload"];
 
     const accountingPayload: ParamToData<typeof this.grammar> = {
       payload,

package/primitives/src/mod.ts

@@ -1,6 +1,6 @@
 import {
   PrimitiveTypeMidnightGeneric,
-  PrimitiveTypeMidnightNullifier,
+  PrimitiveTypeMidnightNullifierAndCommitment,
   PrimitiveTypeMidnightUnshieldedSpend,
   PrimitiveTypeMidnightUnshieldedCreate,
   PrimitiveTypeMidnightZswapRoot,
@@ -21,6 +21,7 @@ import {
   PrimitiveTypeNEARAccountWatch,
   PrimitiveTypeSolanaProgramLog,
   PrimitiveTypeSolanaAccountBalance,
+  PrimitiveTypeSolanaTokenAccount,
   PrimitiveTypeCardanoMintBurn,
   PrimitiveTypeCardanoTransfer,
   PrimitiveTypeCardanoPoolDelegation,
@@ -30,7 +31,8 @@ import {
 } from "./builtin.ts";
 
 import { MidnightGenericPrimitive } from "./midnight-generic/midnight-genetic.ts";
-import { MidnightNullifierPrimitive } from "./midnight-nullifier/midnight-nullifier.ts";
+import { MidnightNullifierAndCommitmentPrimitive } from "./midnight-nullifier-and-commitment/midnight-nullifier-and-commitment.ts";
+export type { MidnightZswapCapture } from "./midnight-nullifier-and-commitment/midnight-nullifier-and-commitment.ts";
 import { MidnightUnshieldedSpendPrimitive } from "./midnight-unshielded-spend/midnight-unshielded-spend.ts";
 import { MidnightUnshieldedCreatePrimitive } from "./midnight-unshielded-create/midnight-unshielded-create.ts";
 import { MidnightZswapRootPrimitive } from "./midnight-zswap-root/midnight-zswap-root.ts";
@@ -51,6 +53,7 @@ import { NearGenericPrimitive } from "./near-generic/near-generic-primitive.ts";
 import { NearAccountWatchPrimitive } from "./near-account-watch/near-account-watch-primitive.ts";
 import { SolanaProgramLogPrimitive } from "./solana-program-log/solana-program-log-primitive.ts";
 import { SolanaAccountBalancePrimitive } from "./solana-account-balance/solana-account-balance-primitive.ts";
+import { SolanaTokenAccountPrimitive } from "./solana-token-account/solana-token-account-primitive.ts";
 import { CardanoMintBurnPrimitive } from "./cardano-mint-burn/mint-burn-primitive.ts";
 import { CardanoTransferPrimitive } from "./cardano-transfer/transfer-primitive.ts";
 import { CardanoPoolDelegationPrimitive } from "./cardano-pool-delegation/pool-delegation-primitive.ts";
@@ -60,7 +63,7 @@ import { CardanoProjectedNftPrimitive } from "./cardano-projected-nft/projected-
 
 const builtInPrimitivesMap = {
   [PrimitiveTypeMidnightGeneric]: MidnightGenericPrimitive,
-  [PrimitiveTypeMidnightNullifier]: MidnightNullifierPrimitive,
+  [PrimitiveTypeMidnightNullifierAndCommitment]: MidnightNullifierAndCommitmentPrimitive,
   [PrimitiveTypeMidnightUnshieldedSpend]: MidnightUnshieldedSpendPrimitive,
   [PrimitiveTypeMidnightUnshieldedCreate]: MidnightUnshieldedCreatePrimitive,
   [PrimitiveTypeMidnightZswapRoot]: MidnightZswapRootPrimitive,
@@ -81,6 +84,7 @@ const builtInPrimitivesMap = {
   [PrimitiveTypeNEARAccountWatch]: NearAccountWatchPrimitive,
   [PrimitiveTypeSolanaProgramLog]: SolanaProgramLogPrimitive,
   [PrimitiveTypeSolanaAccountBalance]: SolanaAccountBalancePrimitive,
+  [PrimitiveTypeSolanaTokenAccount]: SolanaTokenAccountPrimitive,
   [PrimitiveTypeCardanoMintBurn]: CardanoMintBurnPrimitive,
   [PrimitiveTypeCardanoTransfer]: CardanoTransferPrimitive,
   [PrimitiveTypeCardanoPoolDelegation]: CardanoPoolDelegationPrimitive,
@@ -95,7 +99,7 @@ export {
 
   // Built-in Primitives
   MidnightGenericPrimitive,
-  MidnightNullifierPrimitive,
+  MidnightNullifierAndCommitmentPrimitive,
   MidnightUnshieldedSpendPrimitive,
   MidnightUnshieldedCreatePrimitive,
   MidnightZswapRootPrimitive,
@@ -116,6 +120,7 @@ export {
   NearAccountWatchPrimitive,
   SolanaProgramLogPrimitive,
   SolanaAccountBalancePrimitive,
+  SolanaTokenAccountPrimitive,
   CardanoMintBurnPrimitive,
   CardanoTransferPrimitive,
   CardanoPoolDelegationPrimitive,

package/primitives/src/solana-token-account/solana-token-account-grammar.ts

@@ -0,0 +1,13 @@
+import { Type } from "@sinclair/typebox";
+
+export const solanaTokenAccountGrammar = [
+  ["tokenAccount", Type.String()],
+  ["mint", Type.String()],
+  ["owner", Type.String()],
+  // SPL amounts are u64 and do not survive a JS number. Carried as the raw base
+  // unit string, matching nep141Grammar's `amount` and erc20Grammar's `value`;
+  // `decimals` is what turns it into a display value.
+  ["amount", Type.String()],
+  ["decimals", Type.Number()],
+  ["slot", Type.Number()],
+] as const;

package/primitives/src/solana-token-account/solana-token-account-primitive.test.ts

@@ -0,0 +1,117 @@
+import { expect, test } from "bun:test";
+// Via the barrel, not the file directly: mod.ts registers every primitive class, so
+// importing the file first hits a TDZ error on the map entry. Same as
+// solana-program-log-primitive.test.ts.
+import { SolanaTokenAccountPrimitive } from "./../mod.ts";
+import { PrimitiveRegistry } from "../../PrimitiveRegistry.ts";
+
+/**
+ * Unit coverage for the primitive half of SOLANA:TokenAccount — the config guard and
+ * the payload the state machine actually receives. The fetcher half (which balance
+ * records match, and lookup-table resolution) is covered in
+ * `sync/src/sync-protocols/solana/read-primitives.test.ts`.
+ *
+ * `getPayload` is a generator that never yields, so one `.next()` drives it to done.
+ */
+
+const MINT = "Mint111111111111111111111111111111111111111";
+const OWNER = "0wner11111111111111111111111111111111111111";
+const TOKEN_ACCOUNT = "Tok111111111111111111111111111111111111111";
+
+function makePrimitive(overrides: Record<string, unknown> = {}) {
+  // The Primitive constructor self-registers and PrimitiveRegistry.addPrimitive
+  // throws on a duplicate instanceName, so the singleton has to be cleared between
+  // constructions.
+  PrimitiveRegistry.primitives = {};
+  return new SolanaTokenAccountPrimitive({
+    instanceName: "WatchedToken",
+    startBlockHeight: 0,
+    mint: MINT,
+    stateMachinePrefix: "solana-token-account",
+    ...overrides,
+  } as any);
+}
+
+function payloadOf(primitive: SolanaTokenAccountPrimitive, payload: unknown) {
+  const it = primitive.getPayload(0 as any, { output: { payload } } as any) as any;
+  const step = it.next();
+  expect(step.done).toBe(true);
+  return step.value;
+}
+
+const balancePayload = {
+  tokenAccount: TOKEN_ACCOUNT,
+  mint: MINT,
+  owner: OWNER,
+  amount: "1500000000",
+  decimals: 9,
+  slot: 11,
+};
+
+test("rejects a config with no mint, owner or tokenAccount", () => {
+  // Without a filter it would match every token balance on chain, which is never
+  // what was meant — so this fails at construction rather than flooding the STM.
+  expect(() =>
+    makePrimitive({ mint: undefined })
+  ).toThrow(/needs at least one of/);
+});
+
+test("accepts a config filtered by owner alone", () => {
+  expect(() => makePrimitive({ mint: undefined, owner: OWNER })).not.toThrow();
+});
+
+test("accepts a config filtered by tokenAccount alone", () => {
+  expect(() =>
+    makePrimitive({ mint: undefined, tokenAccount: TOKEN_ACCOUNT })
+  ).not.toThrow();
+});
+
+test("carries the raw u64 amount through as a string", () => {
+  // 2^63 - 1: a value that silently loses precision as a JS number, which is why
+  // the grammar types `amount` as a string.
+  const huge = "9223372036854775807";
+  const out = payloadOf(makePrimitive(), { ...balancePayload, amount: huge });
+  expect(out.data[0].accountingPayload.amount).toBe(huge);
+  expect(out.data[0].accountingPayload.decimals).toBe(9);
+});
+
+test("attributes the event to the owner", () => {
+  const out = payloadOf(makePrimitive(), balancePayload);
+  expect(out.data[0].fromAddressAndType.address).toBe(OWNER);
+});
+
+test("falls back to the token account when the RPC omitted the owner", () => {
+  // `owner` is optional in the RPC's token balance record. The balance is still
+  // valid state, so it is reported against the token account rather than dropped.
+  const out = payloadOf(makePrimitive(), { ...balancePayload, owner: undefined });
+  expect(out.data[0].fromAddressAndType.address).toBe(TOKEN_ACCOUNT);
+  expect(out.data[0].accountingPayload.owner).toBe("");
+});
+
+test("builds a state machine payload prefixed by stateMachinePrefix", () => {
+  const out = payloadOf(makePrimitive(), balancePayload);
+  expect(out.data[0].stateMachinePayload).not.toBeNull();
+  expect(out.data[0].stateMachinePayload[0]).toBe("solana-token-account");
+});
+
+test("emits no state machine payload when no prefix is configured", () => {
+  // The accounting row is still written; only STM delivery is skipped. This is the
+  // documented meaning of omitting the prefix.
+  const out = payloadOf(
+    makePrimitive({ stateMachinePrefix: undefined }),
+    balancePayload,
+  );
+  expect(out.data[0].stateMachinePayload).toBeNull();
+  expect(out.data[0].accountingPayload.mint).toBe(MINT);
+});
+
+test("getConfig round-trips the state machine prefix under both names", () => {
+  // Every other builtin emits only `scheduledPrefix`, which the Primitive
+  // constructor does not read — so a config round-tripped through getConfig() loses
+  // its STM routing. Emitting both makes this primitive survive that trip.
+  const config = makePrimitive().getConfig() as Record<string, unknown>;
+  expect(config.stateMachinePrefix).toBe("solana-token-account");
+  expect(config.scheduledPrefix).toBe("solana-token-account");
+  expect(config.type).toBe("SOLANA:TokenAccount");
+  expect(config.mint).toBe(MINT);
+});

package/primitives/src/solana-token-account/solana-token-account-primitive.ts

@@ -0,0 +1,156 @@
+import type { StaticDecode } from "@sinclair/typebox";
+import type {
+  ConfigSyncProtocolType,
+  FlattenSyncProtocolIOFor,
+  ProtocolPrimitiveMap,
+} from "@effectstream/config";
+import {
+  type AddressAndType,
+  AddressType,
+  type EffectstreamBlockNumber,
+} from "@effectstream/utils";
+import { type JsonObject, Primitive } from "@effectstream/sm";
+import {
+  type CommandTuple,
+  generateRawStmInput,
+  type ParamToData,
+} from "@effectstream/concise";
+import type { StateUpdateStream } from "@effectstream/coroutine";
+import { solanaTokenAccountGrammar } from "./solana-token-account-grammar.ts";
+import { PrimitiveTypeSolanaTokenAccount } from "../builtin.ts";
+
+/**
+ * Built-in primitive: tracks the SPL token balance of a watched token account per
+ * slot, derived from a transaction's `meta.postTokenBalances` by
+ * `SolanaFetcher.readPrimitives`.
+ *
+ * Narrowed by any combination of `mint`, `owner` and `tokenAccount`; at least one
+ * must be set. `tokenProgramId` optionally pins it to classic SPL Token or to
+ * Token-2022 rather than accepting both.
+ *
+ * KNOWN LIMITATION — this reports post-state balances only, matching
+ * SOLANA:AccountBalance. A token account that is *closed* appears in
+ * `preTokenBalances` and is absent from `postTokenBalances`, so closure produces no
+ * event rather than a zero one. Emitting a pre/post delta would cover it and is a
+ * deliberate non-goal here; see the Solana chain docs.
+ */
+export class SolanaTokenAccountPrimitive extends Primitive<
+  ConfigSyncProtocolType.SOLANA_RPC_PARALLEL,
+  typeof solanaTokenAccountGrammar
+> {
+  readonly internalTypeName = PrimitiveTypeSolanaTokenAccount;
+  override grammar = solanaTokenAccountGrammar;
+  readonly mint: string | undefined;
+  readonly owner: string | undefined;
+  readonly tokenAccount: string | undefined;
+  readonly tokenProgramId: string | undefined;
+
+  constructor(config: {
+    instanceName: string;
+    startBlockHeight: number;
+    mint?: string;
+    owner?: string;
+    tokenAccount?: string;
+    tokenProgramId?: string;
+    stateMachinePrefix: string | undefined;
+  }) {
+    super(config);
+    // Rejected here rather than in the fetcher because this is the earliest point
+    // it can be caught: an entry with no filter at all would match every token
+    // balance in every transaction, which is never what was meant.
+    if (
+      config.mint == null && config.owner == null && config.tokenAccount == null
+    ) {
+      throw new Error(
+        `[${PrimitiveTypeSolanaTokenAccount}] "${config.instanceName}" needs at least one of ` +
+          `mint, owner or tokenAccount. Without a filter it would match every token balance on chain.`,
+      );
+    }
+    this.mint = config.mint;
+    this.owner = config.owner;
+    this.tokenAccount = config.tokenAccount;
+    this.tokenProgramId = config.tokenProgramId;
+  }
+
+  override *getPayload(
+    _: EffectstreamBlockNumber,
+    primitiveTransactionData: FlattenSyncProtocolIOFor<
+      ConfigSyncProtocolType.SOLANA_RPC_PARALLEL
+    >,
+  ): StateUpdateStream<{
+    isBatched: boolean;
+    data: {
+      fromAddressAndType: AddressAndType;
+      stateMachinePayload:
+        | StaticDecode<CommandTuple<string, typeof solanaTokenAccountGrammar>>
+        | null;
+      accountingPayload: JsonObject;
+    }[];
+  }> {
+    const payload = primitiveTransactionData.output.payload as {
+      tokenAccount?: string;
+      mint?: string;
+      owner?: string;
+      amount?: string;
+      decimals?: number;
+      slot?: number;
+    };
+
+    const accountingPayload: ParamToData<typeof solanaTokenAccountGrammar> = {
+      tokenAccount: String(payload.tokenAccount ?? ""),
+      mint: String(payload.mint ?? this.mint ?? ""),
+      // `owner` is optional in the RPC's token balance record, so it can genuinely
+      // be absent. Empty string rather than a thrown error: the balance itself is
+      // still valid state, and the grammar requires a string.
+      owner: String(payload.owner ?? this.owner ?? ""),
+      amount: String(payload.amount ?? "0"),
+      decimals: Number(payload.decimals ?? 0),
+      slot: Number(payload.slot ?? 0),
+    };
+
+    const stateMachinePayload = this.stateMachinePrefix
+      ? generateRawStmInput(
+        this.grammar,
+        this.stateMachinePrefix,
+        accountingPayload,
+      )
+      : null;
+
+    return {
+      isBatched: false,
+      data: [
+        {
+          // The owner is the party whose holdings changed, so it is the meaningful
+          // actor. Falls back to the token account when the RPC omitted the owner.
+          fromAddressAndType: {
+            type: AddressType.SOLANA,
+            address: accountingPayload.owner || accountingPayload.tokenAccount,
+          },
+          accountingPayload,
+          stateMachinePayload,
+        },
+      ],
+    };
+  }
+
+  override getConfig(): ProtocolPrimitiveMap[
+    ConfigSyncProtocolType.SOLANA_RPC_PARALLEL
+  ] {
+    return {
+      name: this.instanceName,
+      type: this.internalTypeName,
+      startBlockHeight: this.startBlockHeight,
+      mint: this.mint,
+      owner: this.owner,
+      tokenAccount: this.tokenAccount,
+      tokenProgramId: this.tokenProgramId,
+      // Both names on purpose. Every other builtin emits only `scheduledPrefix`,
+      // which the `Primitive` constructor does not read — so a config round-tripped
+      // through getConfig() silently loses its state-machine routing. Emitting
+      // `stateMachinePrefix` too makes this primitive survive that trip, and
+      // `scheduledPrefix` stays for anything still reading the deprecated name.
+      stateMachinePrefix: this.stateMachinePrefix,
+      scheduledPrefix: this.stateMachinePrefix,
+    } as ProtocolPrimitiveMap[ConfigSyncProtocolType.SOLANA_RPC_PARALLEL];
+  }
+}

package/primitives/src/midnight-nullifier/midnight-nullifier-grammar.ts

@@ -1,8 +0,0 @@
-import { Type } from "@sinclair/typebox";
-
-export const midnightNullifierGrammar = [
-  [
-    "payload",
-    Type.Any(),
-  ],
-] as const;