@effectstream/sm 0.101.1 → 0.103.0

package/primitives/src/solana-program-log/solana-program-log-primitive.test.ts

@@ -0,0 +1,128 @@
+import { test, expect } from "bun:test";
+import { run } from "effection";
+import type { ConfigSyncProtocolType, FlattenSyncProtocolIOFor } from "@effectstream/config";
+import { SolanaProgramLogPrimitive } from "./../mod.ts";
+import { PrimitiveRegistry } from "../../PrimitiveRegistry.ts";
+
+const PROGRAM_ID = "11111111111111111111111111111111";
+const PrimitiveTypeSolanaProgramLog = "SOLANA:ProgramLog";
+
+function cleanup() {
+  PrimitiveRegistry.primitives = {};
+}
+
+test("SolanaProgramLogPrimitive - initializes correctly", () => {
+  cleanup();
+  const primitive = new SolanaProgramLogPrimitive({
+    instanceName: "spl",
+    startBlockHeight: 0,
+    programId: PROGRAM_ID,
+    stateMachinePrefix: "solana-program-log",
+  });
+
+  expect(primitive.instanceName).toEqual("spl");
+  expect(primitive.startBlockHeight).toEqual(0);
+  expect(primitive.programId).toEqual(PROGRAM_ID);
+  expect(primitive.internalTypeName).toEqual(PrimitiveTypeSolanaProgramLog);
+
+  const config = primitive.getConfig();
+  expect(config.name).toEqual("spl");
+  expect(config.type).toEqual(PrimitiveTypeSolanaProgramLog);
+  expect(config.programId).toEqual(PROGRAM_ID);
+  expect(config.scheduledPrefix).toEqual("solana-program-log");
+});
+
+test("SolanaProgramLogPrimitive - getPayload generates correct state update", async () => {
+  cleanup();
+  const primitive = new SolanaProgramLogPrimitive({
+    instanceName: "spl",
+    startBlockHeight: 0,
+    programId: PROGRAM_ID,
+    stateMachinePrefix: "solana-program-log",
+  });
+
+  const mockTxData = {
+    syncProtocol: {
+      name: "parallelSolanaRPC",
+      blockNumber: 42,
+      transactionHash: "5x…signature",
+      contractAddress: PROGRAM_ID,
+    },
+    output: {
+      payloadType: "solana:transaction",
+      payload: {
+        programId: PROGRAM_ID,
+        slot: 42,
+        logMessages: ["Program log: hi", "Program log: bye"],
+      },
+    },
+  } as unknown as FlattenSyncProtocolIOFor<
+    ConfigSyncProtocolType.SOLANA_RPC_PARALLEL
+  >;
+
+  await run(function* () {
+    const generator = primitive.getPayload(123, mockTxData);
+    const result = generator.next().value;
+
+    if (!result) throw new Error("No payload generated");
+    if (!("isBatched" in result)) {
+      throw new Error("Result is not a SyncStateUpdate");
+    }
+
+    expect(result.isBatched).toEqual(false);
+    expect(result.data.length).toEqual(1);
+
+    const item = result.data[0];
+    expect(item.accountingPayload.slot).toEqual(42);
+    expect(item.accountingPayload.programId).toEqual(PROGRAM_ID);
+    expect(item.accountingPayload.logMessages).toEqual([
+      "Program log: hi",
+      "Program log: bye",
+    ]);
+
+    expect(Array.isArray(item.stateMachinePayload)).toEqual(true);
+    // @ts-ignore: safe to access
+    expect(item.stateMachinePayload?.[0]).toEqual("solana-program-log");
+  });
+});
+
+test("SolanaProgramLogPrimitive - getPayload skips state machine payload if no prefix", async () => {
+  cleanup();
+  const primitive = new SolanaProgramLogPrimitive({
+    instanceName: "spl",
+    startBlockHeight: 0,
+    programId: PROGRAM_ID,
+    stateMachinePrefix: undefined,
+  });
+
+  const mockTxData = {
+    syncProtocol: {
+      name: "parallelSolanaRPC",
+      blockNumber: 7,
+      transactionHash: "sig",
+      contractAddress: PROGRAM_ID,
+    },
+    output: {
+      payload: {
+        programId: PROGRAM_ID,
+        slot: 7,
+        logMessages: ["Program log: x"],
+      },
+    },
+  } as unknown as FlattenSyncProtocolIOFor<
+    ConfigSyncProtocolType.SOLANA_RPC_PARALLEL
+  >;
+
+  await run(function* () {
+    const generator = primitive.getPayload(123, mockTxData);
+    const result = generator.next().value;
+
+    if (!result) throw new Error("No payload generated");
+    if (!("isBatched" in result)) {
+      throw new Error("Result is not a SyncStateUpdate");
+    }
+
+    const item = result.data[0];
+    expect(item.stateMachinePayload).toEqual(null);
+  });
+});

package/primitives/src/solana-program-log/solana-program-log-primitive.ts

@@ -0,0 +1,108 @@
+import type { StaticDecode } from "@sinclair/typebox";
+import {
+  type ConfigSyncProtocolType,
+  type FlattenSyncProtocolIOFor,
+  type 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 { solanaProgramLogGrammar } from "./solana-program-log-grammar.ts";
+import { PrimitiveTypeSolanaProgramLog } from "../builtin.ts";
+
+export class SolanaProgramLogPrimitive extends Primitive<
+  ConfigSyncProtocolType.SOLANA_RPC_PARALLEL,
+  typeof solanaProgramLogGrammar
+> {
+  readonly internalTypeName = PrimitiveTypeSolanaProgramLog;
+  override grammar = solanaProgramLogGrammar;
+  readonly programId: string;
+  readonly eventType: string | undefined;
+
+  constructor(config: {
+    instanceName: string;
+    startBlockHeight: number;
+    programId: string;
+    eventType?: string;
+    stateMachinePrefix: string | undefined;
+  }) {
+    super(config);
+    this.programId = config.programId;
+    this.eventType = config.eventType;
+  }
+
+  override *getPayload(
+    _: EffectstreamBlockNumber,
+    primitiveTransactionData: FlattenSyncProtocolIOFor<
+      ConfigSyncProtocolType.SOLANA_RPC_PARALLEL
+    >,
+  ): StateUpdateStream<{
+    isBatched: boolean;
+    data: {
+      fromAddressAndType: AddressAndType;
+      stateMachinePayload:
+        | StaticDecode<CommandTuple<string, typeof solanaProgramLogGrammar>>
+        | null;
+      accountingPayload: JsonObject;
+    }[];
+  }> {
+    const { programId, slot, logMessages } =
+      primitiveTransactionData.output.payload as {
+        programId: string;
+        slot: number;
+        logMessages: string[];
+      };
+
+    const accountingPayload: ParamToData<typeof solanaProgramLogGrammar> = {
+      slot,
+      programId,
+      logMessages,
+    };
+
+    const stateMachinePayload = this.stateMachinePrefix
+      ? generateRawStmInput(
+        this.grammar,
+        this.stateMachinePrefix,
+        accountingPayload,
+      )
+      : null;
+
+    return {
+      isBatched: false,
+      data: [
+        {
+          fromAddressAndType: {
+            type: AddressType.SOLANA,
+            address: String(
+              primitiveTransactionData.syncProtocol.contractAddress ?? "",
+            ),
+          },
+          accountingPayload,
+          stateMachinePayload,
+        },
+      ],
+    };
+  }
+
+  override getConfig(): ProtocolPrimitiveMap[
+    ConfigSyncProtocolType.SOLANA_RPC_PARALLEL
+  ] {
+    return {
+      name: this.instanceName,
+      type: this.internalTypeName,
+      startBlockHeight: this.startBlockHeight,
+      programId: this.programId,
+      eventType: this.eventType,
+      scheduledPrefix: this.stateMachinePrefix,
+    };
+  }
+}

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;