@effectstream/runtime 0.100.14 → 0.100.15

package/README.md

@@ -0,0 +1,89 @@
+# @effectstream/runtime
+
+The state-machine runtime — the loop that ties sync, state machine,
+database, events, and HTTP API together inside an EffectStream node.
+Boot it with `init()` then drive it with `start(config)` and your node
+is up.
+
+## Install
+
+```bash
+bun add @effectstream/runtime
+# or
+npm install @effectstream/runtime
+```
+
+`@effectstream/runtime` is the canonical import for `init` and `start`,
+used directly by every template. The same surface is also reachable
+through `@effectstream/node-sdk/runtime` if you prefer the umbrella.
+
+## Standalone usage
+
+This package **owns the node's process model**. You don't pick parts of
+it; you call `init()` once at boot and then `start(config)`. The config
+brings together everything else:
+
+```typescript
+import { init, start } from "@effectstream/runtime";
+import { Stm } from "@effectstream/sm";
+import { config } from "./config.dev.ts";
+
+await init();
+
+const gameStm = new Stm(grammar);
+gameStm.addStateTransition("join", function* () { /* ... */ });
+
+await start({
+  config,
+  gameStateTransitions: [gameStm],
+  apiRouter: undefined,           // optional Fastify route plugin
+  dbMigrations: [],               // SQL migrations
+});
+```
+
+While running, the runtime:
+
+- Reads finalized blocks via `@effectstream/sync`.
+- Routes batcher inputs through your registered `Stm`s.
+- Commits all yielded SQL inside a per-block transaction.
+- Publishes lifecycle and app events via `@effectstream/event-server`.
+- Serves the optional Fastify API.
+- Emits OpenTelemetry traces and logs through `@effectstream/log`.
+
+## Inside EffectStream
+
+`@effectstream/runtime` is the conductor: it doesn't define any chain
+integrations or queries itself, but every other node package only gets
+exercised when this loop is running. The `StartConfig` shape determines
+which DB migrations apply, which state machines fire, and whether the
+runtime exposes a Fastify router.
+
+## Key exports
+
+- `init()` — `Operation<void>`. One-shot setup: OpenTelemetry, config validation, version pinning. Call before `start`.
+- `start(config: StartConfig)` — `Operation<void>`. Run the node loop until cancelled.
+
+Types and helpers re-exported alongside `init` / `start`:
+
+- `DBMigrations` — versioned SQL migrations passed into `start`.
+- `StartConfig`, `StartConfigGameStateTransitions`, `StartConfigApiRouter` — `start`'s config types. Templates type-check against these implicitly but don't usually import them by name.
+- `PrimitiveConstructor<T>` — extension point for new primitives.
+- `VERSION` — `${number}.${number}.${number}` literal type for version pinning.
+- Pagination helpers re-exported from `./api/pagination.ts`.
+
+## Examples
+
+The templates under
+[`templates/`](https://github.com/PaimaStudios/paima-engine/tree/main/templates)
+are full working `init()` + `start()` examples. The simplest is
+[`templates/minimal/`](https://github.com/PaimaStudios/paima-engine/tree/main/templates/minimal).
+
+End-to-end EVM sync test:
+[`e2e/evm/sync/`](https://github.com/PaimaStudios/paima-engine/tree/main/e2e/evm/sync).
+
+Runnable: [`test/examples.test.ts`](./test/examples.test.ts).
+
+## Links
+
+- Docs: https://effectstream.github.io/docs/packages/node/runtime
+- Source: https://github.com/PaimaStudios/paima-engine/tree/main/packages/node-sdk/runtime

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effectstream/runtime",
-  "version": "0.100.14",
+  "version": "0.100.15",
   "license": "MIT",
   "homepage": "https://effectstream.github.io/docs/",
   "repository": {
@@ -13,17 +13,17 @@
   },
   "exports": "./src/mod.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/event-server": "0.100.14",
-    "@effectstream/log": "0.100.14",
-    "@effectstream/sm": "0.100.14",
-    "@effectstream/sync": "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/event-server": "0.100.15",
+    "@effectstream/log": "0.100.15",
+    "@effectstream/sm": "0.100.15",
+    "@effectstream/sync": "0.100.15",
+    "@effectstream/utils": "0.100.15",
     "@fastify/cors": "^11.0.1",
     "@metamask/json-rpc-engine": "^10.0.3",
     "pg": "8.17.2",

package/src/api/http-server.ts

@@ -46,7 +46,7 @@ import {
   type TypePaginationQuerySchema,
 } from "./pagination.ts";
 import { PrimitiveRegistry } from "@effectstream/sm";
-import { ConfigNetworkType } from "@effectstream/config";
+import { ConfigNetworkType, getWriteNamespace, usePaimaStaticConfig } from "@effectstream/config";
 
 function tableListContains(
   list: Array<{ table_name: string | null }>,
@@ -470,26 +470,36 @@ export const startHttpServer = function* (
       return cleanedProtocols;
     });
 
+    const staticConfigForRoute = yield* usePaimaStaticConfig();
+    const securityNamespaceForRoute = getWriteNamespace(
+      staticConfigForRoute.securityNamespace,
+    );
+
     server.get("/config", {
       schema: {
         tags: ["developer"],
         response: {
-          200: Type.Array(Type.Object({
-            networkType: Type.String(),
-            syncProtocolType: Type.String(),
-            syncProtocol: Type.Object({}, { additionalProperties: true }),
-            network: Type.Object({}, { additionalProperties: true }),
-            primitives: Type.Array(
-              Type.Object({}, { additionalProperties: true }),
-            ),
-          }, { additionalProperties: true })),
+          200: Type.Object({
+            securityNamespace: Type.Union([Type.String(), Type.Null()]),
+            syncProtocols: Type.Array(Type.Object({
+              networkType: Type.String(),
+              syncProtocolType: Type.String(),
+              syncProtocol: Type.Object({}, { additionalProperties: true }),
+              network: Type.Object({}, { additionalProperties: true }),
+              primitives: Type.Array(
+                Type.Object({}, { additionalProperties: true }),
+              ),
+            }, { additionalProperties: true })),
+          }),
         },
       },
     }, () => {
       const config = syncProtocols.map((syncProtocol) => syncProtocol.config)
         .flat();
-      const cleanedConfig = clearBigInts(config);
-      return cleanedConfig;
+      return {
+        securityNamespace: securityNamespaceForRoute,
+        syncProtocols: clearBigInts(config),
+      };
     });
   }
 

package/src/main.ts

@@ -36,7 +36,8 @@ import type { Client } from "pg";
 import type { EffectstreamBlockHash } from "@effectstream/utils";
 import { applySystemMigrations } from "./version-migrations.ts";
 import { getLastBlockHeight, getVersionInfo } from "@effectstream/db/version";
-import { type SyncProtocolWithNetwork, ConfigNetworkType } from "@effectstream/config";
+import { ConfigNetworkType, usePaimaStaticConfig } from "@effectstream/config";
+import type { SecurityNamespace, SyncProtocolWithNetwork } from "@effectstream/config";
 import { builtInPrimitivesMap } from "@effectstream/sm";
 import { validateAndSnapshotConfig } from "./config-snapshot.ts";
 
@@ -275,12 +276,16 @@ function* startup(
 ): Operation<AllSyncProtocols[]> {
   const versionInfo = yield* getVersionInfo(dbConn);
   const lastBlockHeight = yield* getLastBlockHeight(versionInfo, dbConn);
+  // Pull the security namespace from the static config so primitives that
+  // re-verify batched signatures can access it synchronously.
+  const staticConfig = yield* usePaimaStaticConfig();
   // Create Runtime Primitives Instances
   syncInfo.forEach((syncProtocol) => {
     syncProtocol.primitives.forEach((primitive, primitiveIndex) => {
       processPrimitives(
         syncProtocol.primitives,
         primitiveIndex,
+        staticConfig.securityNamespace,
         config.userDefinedPrimitives
       );
     });
@@ -327,6 +332,7 @@ function* startup(
 const processPrimitives = (
   primitives: {primitive: any, id: string}[],
   primitiveIndex: number,
+  securityNamespace: SecurityNamespace | undefined,
   userDefinedPrimitives?: Record<string, any>,
 ) => {
     const primitiveType = primitives[primitiveIndex].primitive.type;
@@ -349,6 +355,7 @@ const processPrimitives = (
     const classConfig = {
       ...primitiveConfig,
       instanceName: primitiveUniqueName,
+      securityNamespace,
     }
     if (isBuiltInPrimitive) {
       p = new builtInPrimitivesMap[primitiveType as keyof typeof builtInPrimitivesMap](classConfig as any) ;

package/test/examples.test.ts

@@ -0,0 +1,14 @@
+// Examples for the README — verify the public surface resolves.
+
+import { test, expect } from "bun:test";
+import * as runtime from "../src/mod.ts";
+
+test("README: init and start are exported as generator functions", () => {
+  expect(typeof runtime.init).toBe("function");
+  expect(typeof runtime.start).toBe("function");
+});
+
+test("README: pagination helpers are re-exported", async () => {
+  const pagination = await import("../src/api/pagination.ts");
+  expect(Object.keys(pagination).length).toBeGreaterThan(0);
+});