@effectstream/sm 0.100.14 → 0.100.15

package/README.md

@@ -0,0 +1,90 @@
+# @effectstream/sm
+
+The state-machine DSL inside an EffectStream node. Define a typed grammar
+of commands, register one generator per command, and `Stm` parses each
+incoming batcher input, dispatches it to the right handler, and yields
+SQL updates through the runtime.
+
+## Install
+
+```bash
+bun add @effectstream/sm
+# or
+npm install @effectstream/sm
+```
+
+## Usage
+
+This package pairs with [`@effectstream/runtime`](https://www.npmjs.com/package/@effectstream/runtime),
+which drives a per-block loop that calls `stm.processInput(...)` for every
+batcher subunit, collects the SQL yielded by your generators, and commits
+it inside a per-block postgres transaction. You author the DSL here;
+the runtime executes it.
+
+The DSL is also directly testable in a pure-TS unit test (parse + dispatch
+without a database) — see
+[`primitives/src/evm-erc20/erc20-primitive.test.ts`](https://github.com/PaimaStudios/paima-engine/blob/main/packages/node-sdk/sm/primitives/src/evm-erc20/erc20-primitive.test.ts).
+
+```typescript
+import { Stm } from "@effectstream/sm";
+import { World } from "@effectstream/coroutine";
+import { Type } from "@sinclair/typebox";
+import { join, leave } from "./queries.ts"; // pgtyped queries
+
+const grammar = {
+  join: [["user", Type.String()]] as const,
+  leave: [["user", Type.String()]] as const,
+} as const;
+
+const stm = new Stm(grammar);
+
+stm.addStateTransition("join", function* ({ parsedInput, msTimestamp }) {
+  yield* World.resolve(join, { user: parsedInput.user, ts: msTimestamp });
+});
+
+stm.addStateTransition("leave", function* ({ parsedInput }) {
+  yield* World.resolve(leave, { user: parsedInput.user });
+});
+```
+
+The runtime calls `stm.processInput(input)` for every batcher subunit; the
+DSL parses against `grammar`, finds the right handler, and the generator
+yields `World.resolve(...)` so the runtime can execute the pgtyped queries.
+
+## Inside EffectStream
+
+`Stm` is the central piece a node author writes. The runtime's per-block
+loop wires each user input through the corresponding `Stm` instance,
+collects yielded SQL, and commits it inside the per-block transaction.
+The built-in primitives package (`@effectstream/sm/builtin`) covers
+common on-chain events — ERC-20/721/1155 transfers, Cardano transfers,
+Midnight events, etc. — so you don't re-implement them.
+
+## Key exports
+
+- `Stm<Grammar, Events>` — the state machine. `.addStateTransition(prefix, handler)`, `.processInput(input)`, `.grammar`, `.fullJsonGrammar`, `.keyedJsonGrammar`.
+- `ParamToData<Params>` — derives the typed argument shape from a grammar entry.
+- `BaseStfInput` — the input shape passed to every handler (includes `msTimestamp`, `blockHeight`, etc.).
+- `delegate-wallet` helpers — account delegation primitives reused by built-ins.
+
+`MessageListener<Events, Params>` is exported as the handler type but is
+inferred at call sites rather than imported directly.
+
+Subpath exports:
+
+- `@effectstream/sm/builtin` — `PrimitiveTypeERC20`, `PrimitiveTypeERC721`, `PrimitiveTypeERC1155`, `PrimitiveTypeCardanoTransfer`, `PrimitiveTypeMidnightGeneric`, and many more (20+ chain-specific event tags).
+- `@effectstream/sm/grammar` — the underlying grammar/parsing utilities (also re-exported from `@effectstream/concise`).
+
+## Examples
+
+- [`primitives/src/evm-erc20/erc20-primitive.test.ts`](https://github.com/PaimaStudios/paima-engine/blob/main/packages/node-sdk/sm/primitives/src/evm-erc20/erc20-primitive.test.ts) — a real primitive's behavior unit-tested.
+- Game logic in
+  [`templates/dice/packages/node/`](https://github.com/PaimaStudios/paima-engine/tree/main/templates/dice/packages/node)
+  shows the full `new Stm(...).addStateTransition(...)` pattern.
+
+Runnable: [`test/examples.test.ts`](./test/examples.test.ts).
+
+## Links
+
+- Docs: https://effectstream.github.io/docs/packages/node/sm
+- Source: https://github.com/PaimaStudios/paima-engine/tree/main/packages/node-sdk/sm

package/package.json

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

package/primitives/src/evm-effectstream-l2/effectstream-l2-primitive.ts

@@ -1,4 +1,5 @@
-import { getEvmEvent } from "@effectstream/config";
+import { getEvmEvent, getReadNamespaces } from "@effectstream/config";
+import type { SecurityNamespace } from "@effectstream/config";
 import {
   type AddressAndType,
   AddressType,
@@ -60,12 +61,14 @@ export class EffectstreamL2Primitive extends Primitive<
   readonly contractAddress: EvmAddress;
   override grammar = [];
   readonly effectstreamL2Grammar: GrammarDefinition;
+  readonly securityNamespace: SecurityNamespace | undefined;
 
   constructor(config: {
     instanceName: string;
     startBlockHeight: number;
     contractAddress: EvmAddress;
     effectstreamL2Grammar: GrammarDefinition;
+    securityNamespace: SecurityNamespace | undefined;
   }) {
     super({ ...config, stateMachinePrefix: undefined });
     this.contractAddress = Value.Decode(
@@ -73,6 +76,7 @@ export class EffectstreamL2Primitive extends Primitive<
       config.contractAddress,
     );
     this.effectstreamL2Grammar = config.effectstreamL2Grammar;
+    this.securityNamespace = config.securityNamespace;
   }
 
   override *getPayload(
@@ -370,23 +374,34 @@ export class EffectstreamL2Primitive extends Primitive<
           input: conciseInput,
           target: batcherTarget,
         } = parsed;
-        // TODO: We need to setup & configure the namespace.
-        const message = createMessageForBatcher(
-          null,
-          millisecondTimestamp,
-          userAddress,
-          addressType,
-          conciseInput,
-          batcherTarget,
-        );
-        // We yield the promise to the generator caller.
-        // Sync Generators cannot resolve promises.
-        const validSignature = yield* verifySignature(
-          addressType,
-          userAddress,
-          message,
-          userSignature,
+        // Re-verify the batched signature against each acceptable namespace
+        // (matches what the batcher checked when admitting the input). The
+        // frontend signs with the game's configured security namespace; if we
+        // don't try it here, every batched input is silently dropped.
+        // Namespace is injected at construction by the runtime — see
+        // processPrimitives in @effectstream/runtime.
+        const acceptableNamespaces = getReadNamespaces(
+          this.securityNamespace,
+          effectstream_block_height,
         );
+        let validSignature = false;
+        for (const ns of acceptableNamespaces) {
+          const message = createMessageForBatcher(
+            ns,
+            millisecondTimestamp,
+            userAddress,
+            addressType,
+            conciseInput,
+            batcherTarget,
+          );
+          validSignature = yield* verifySignature(
+            addressType,
+            userAddress,
+            message,
+            userSignature,
+          );
+          if (validSignature) break;
+        }
 
         const cryptoManager = CryptoManager.getCryptoManager(addressType);
         const signerAddress = cryptoManager.decodeAddress(userAddress);

package/test/examples.test.ts

@@ -0,0 +1,46 @@
+// Examples for the README. We exercise Stm in isolation — define a
+// grammar, register handlers, and check `.processInput` dispatches to
+// the right one. The runtime side (executing yielded SQL) is the job of
+// @effectstream/runtime, not this package.
+
+import { test, expect } from "bun:test";
+import { Type } from "@sinclair/typebox";
+import { Stm } from "../Stm.ts";
+
+test("README: Stm dispatches inputs to the registered handler", () => {
+  const grammar = {
+    join: [["user", Type.String()]] as const,
+    leave: [["user", Type.String()]] as const,
+  } as const;
+
+  const stm = new Stm(grammar);
+  const calls: string[] = [];
+
+  stm.addStateTransition("join", function* ({ parsedInput }) {
+    calls.push(`join:${parsedInput.user}`);
+    // Empty generator — no DB writes.
+  });
+  stm.addStateTransition("leave", function* ({ parsedInput }) {
+    calls.push(`leave:${parsedInput.user}`);
+  });
+
+  // Build the on-wire concise input.
+  const input = JSON.stringify(["join", "alice"]);
+  const gen = stm.processInput({
+    conciseInput: input,
+    blockHeight: 1,
+    msTimestamp: 0,
+  } as any);
+
+  // Drain the generator.
+  while (!gen.next().done) {}
+
+  expect(calls).toEqual(["join:alice"]);
+});
+
+test("README: duplicate prefix registration throws", () => {
+  const grammar = { join: [["user", Type.String()]] as const } as const;
+  const stm = new Stm(grammar);
+  stm.addStateTransition("join", function* () {});
+  expect(() => stm.addStateTransition("join", function* () {})).toThrow();
+});