@ottochain/sdk 2.4.0 → 2.5.0

package/dist/types/templates/machine.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Versioned-machine skeleton + `transition()` / `effect()` composition (handoff §1.2).
+ *
+ * Two moves:
+ *   1. `transition()` / `effect()` build the wire `Transition` + its flat effect map from typed
+ *      fragments instead of a hand-rolled JSON blob.
+ *   2. `machine()` is a versioned-package SKELETON that OWNS exactly ONE canonical wire definition
+ *      (`toProtoDefinition(app)`, computed once) and hands the SAME object to BOTH `publishVersion()`
+ *      and `create()`. That is the verified-binding invariant (F9): because publish and create cannot
+ *      drift, the chain's `definition.computeDigest` equals the registered `logicHash` and the bind
+ *      admits the fiber. The skeleton REUSES `toProtoDefinition` (the one canonicalization path) — it
+ *      never re-derives the wire shape.
+ *
+ * Guardrail (CLAUDE.md #1): every builder here is a pure function emitting the exact wire shape the
+ * chain re-derives. Absent optionals (`metadata`/`participants`/`parentFiberId`/`migration`) are
+ * OMITTED, never `null`; required-no-default fields (`strict` on publish, `dependencies: []` per
+ * transition) are ALWAYS present.
+ */
+import { type Transition, type JsonLogicRule, type DependencySpec, type FiberAppDefinition, type ProtoStateMachineDefinition } from '../schema/fiber-app.js';
+import type { MachineShape, PublishMachineVersion, CreateStateMachine, UpgradeFiber, SemVer, JsonLogicValue, JsonLogicExpression } from '../ottochain/types.js';
+/** Authoring shape for {@link transition} — `on` is the event name (mapped to the wire `eventName`). */
+export interface TransitionSpec<TState extends string = string, TEvent extends string = string> {
+    from: TState;
+    to: TState;
+    /** Event that fires this transition. Mapped to the wire key `eventName`. */
+    on: TEvent;
+    /** JSON-Logic predicate; defaults to the always-true `{ "==": [1, 1] }` when omitted. */
+    guard?: JsonLogicRule;
+    /** The flat effect map (build it with {@link effect}). Passed through verbatim. */
+    effect?: JsonLogicRule;
+    /**
+     * Dependencies for this transition. Defaults to `[]` (ALWAYS present — the chain
+     * `Transition.dependencies: Set[UUID]` has no default; omitting it diverges the canonical).
+     * `toProtoDefinition` later drops any non-string {@link DependencySpec} authoring entries.
+     */
+    dependencies?: readonly (string | DependencySpec)[];
+}
+/**
+ * Build a wire {@link Transition} from a typed spec.
+ *
+ *   - `on` → `eventName` (the wire key);
+ *   - `guard` defaults to `{ "==": [1, 1] }`;
+ *   - `dependencies` defaults to `[]` and is ALWAYS present;
+ *   - `effect` is passed through (build it with {@link effect}).
+ *
+ * @example
+ * ```ts
+ * transition({
+ *   from: 'debt_current', to: 'debt_current', on: 'buy',
+ *   effect: effect(
+ *     { status: 'debt_current', purchaseCount: { '+': [{ var: 'state.purchaseCount' }, 1] } },
+ *     triggers([...]), transferAsset([...]),
+ *   ),
+ * });
+ * ```
+ */
+export declare function transition<TState extends string = string, TEvent extends string = string>(t: TransitionSpec<TState, TEvent>): Transition<TState, TEvent>;
+/**
+ * Compose an effect into ONE FLAT map: the state-update fields PLUS any `_`-directive fragments,
+ * all in a single object (`Object.assign({}, stateUpdate, ...directives)`).
+ *
+ * Riverdale effects are flat maps that mix `_`-reserved directives (`_triggers`, `_transferAsset`,
+ * `_spawn`, …) with plain state-update fields — they are NOT `merge`-wrapped. Each directive fragment
+ * is a `Record` (e.g. the output of `transferAsset(...)` / `triggers(...)`), spread in here. Later
+ * fragments override earlier keys (`Object.assign` semantics).
+ *
+ * @example
+ * ```ts
+ * effect(
+ *   { status: 'debt_current', purchaseCount: { '+': [{ var: 'state.purchaseCount' }, 1] } },
+ *   { _triggers: [...] },
+ *   transferAsset([{ assetId: { var: 'event.payAssetId' }, recipient: toFiber({ var: 'event.retailerId' }) }]),
+ * );
+ * // => { status, purchaseCount, _triggers, _transferAsset }
+ * ```
+ */
+export declare function effect(stateUpdate: Record<string, unknown>, ...directives: Record<string, unknown>[]): Record<string, unknown>;
+/** The machine package spec: identity (`name`@`version`) + the one canonical `app` + its schema shape. */
+export interface MachineSpec<TState extends string = string, TEvent extends string = string> {
+    /** Full registry name `labels.tld` (e.g. `"consumer.package"`). */
+    name: string;
+    /** SemVer string (e.g. `"1.0.0"`). */
+    version: SemVer;
+    /** The typed fiber app; projected ONCE to the canonical wire definition via `toProtoDefinition`. */
+    app: FiberAppDefinition<TState, TEvent>;
+    /** The advisory proto projection the chain stores for discovery (carried onto `PublishMachineVersion.machineShape`). */
+    schemaShape: MachineShape;
+}
+/** Options for {@link Machine.publishVersion}. */
+export interface PublishVersionOptions {
+    /** Opt-in runtime conformance gate (#33). Defaults to `false` (REQUIRED on the wire — never omitted). */
+    strict?: boolean;
+    /** Optional off-chain links grab-bag; OMITTED when absent (never `null`). */
+    metadata?: Record<string, string>;
+    /**
+     * Base64 of the proto FileDescriptorSet. REQUIRED on the wire `PublishMachineVersion` (the chain
+     * base64-validates + hashes it, then drops the bytes), so it is ALWAYS present; defaults to the empty
+     * string `''` (valid empty base64) when the skeleton has no descriptor set bound. The verified binding
+     * hangs on `definition.computeDigest`, NOT on this field.
+     */
+    schemaB64?: string;
+}
+/** Options for {@link Machine.create}. */
+export interface CreateOptions {
+    fiberId: string;
+    /** Seeded fiber state (e.g. from `seedState(...)`); pre-seed accumulators so no field reads `null`. */
+    initialData: JsonLogicValue;
+    /** Optional DAG addresses authorized to sign transitions; OMITTED when absent (never `null`). */
+    participants?: string[];
+    /** Optional parent fiber UUID; OMITTED when absent (never `null`). */
+    parentFiberId?: string;
+}
+/** Options for {@link Machine.upgradeFrom}. */
+export interface UpgradeOptions {
+    fiberId: string;
+    targetSequenceNumber: number;
+    /** Optional JSON-Logic migration transform of the prior state; OMITTED when absent (never `null`). */
+    migration?: JsonLogicExpression;
+}
+/** The versioned-machine skeleton returned by {@link machine}. */
+export interface Machine {
+    /** The ONE canonical wire definition (`toProtoDefinition(app)`), shared by publish + create. */
+    wireDefinition(): ProtoStateMachineDefinition;
+    /** The `PublishMachineVersion` body — its `definition` is the SAME object as `wireDefinition()`. */
+    publishVersion(o?: PublishVersionOptions): PublishMachineVersion;
+    /** The `CreateStateMachine` body — references `name@version` via `schemaRef` + the SAME `definition`. */
+    create(o: CreateOptions): CreateStateMachine;
+    /** The `UpgradeFiber` body — re-pins to `name@version` with the SAME `newDefinition`. */
+    upgradeFrom(o: UpgradeOptions): UpgradeFiber;
+}
+/**
+ * Build a versioned-machine skeleton that binds publish + create to ONE canonical definition.
+ *
+ * The definition is projected ONCE here (`toProtoDefinition(spec.app)`) and the SAME reference is handed
+ * to `wireDefinition()`, `publishVersion().definition`, `create().definition`, and
+ * `upgradeFrom().newDefinition` — so they cannot drift and the chain's verified binding admits the fiber
+ * (F9). REUSES `toProtoDefinition` (the single canonicalization path); never re-derives the wire shape.
+ */
+export declare function machine<TState extends string = string, TEvent extends string = string>(spec: MachineSpec<TState, TEvent>): Machine;

package/dist/types/templates/migration.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Migration builders — the `UpgradeFiber.migration` JSON-Logic transform applied on a version upgrade.
+ *
+ * THE FOOT-GUN (F9): a migration's evaluation root is the BARE prior state, not `state.x`.
+ * The chain evaluates the migration expression against `sm.stateData` directly
+ * (`MeteredEvaluator.eval(expr, sm.stateData, Migration)`, FiberEngine.scala:300), so:
+ *   - `{ var: '' }`            => the WHOLE prior state object
+ *   - `{ var: 'loyaltyPoints' }` => the top-level `loyaltyPoints` field
+ * This is UNLIKE an effect, where the root is the transition context and you read `{ var: 'state.x' }`.
+ * Writing `state.loyaltyPoints` in a migration silently reads `undefined`. These helpers hide that
+ * asymmetry by pinning the bare-state root for you.
+ *
+ * `migration` is `Option` on `UpgradeFiber` — when there is no transform, OMIT the key (never send `null`).
+ */
+/**
+ * Seed / overwrite top-level state fields on a version upgrade.
+ * Emits `{ merge: [{ var: '' }, fields] }` — merges `fields` onto the bare prior state, so existing
+ * fields are preserved and the named fields are added or overwritten.
+ *
+ * The `{ var: '' }` root is the BARE prior state (NOT `state.x` like an effect) — that asymmetry is
+ * exactly the F9 foot-gun this helper hides.
+ *
+ * @example seedFields({ loyaltyPoints: 0 }) // => { merge: [{ var: '' }, { loyaltyPoints: 0 }] }
+ */
+export declare const seedFields: (fields: Record<string, unknown>) => unknown;
+/**
+ * General migration transform with the bare-state root made explicit. `build` receives `{ var: '' }`
+ * (the whole prior state) and returns the migration JSON-Logic.
+ *
+ * @example migration((s) => ({ merge: [s, { x: 1 }] })) // => { merge: [{ var: '' }, { x: 1 }] }
+ */
+export declare const migration: (build: (priorState: {
+    var: "";
+}) => unknown) => unknown;

package/dist/types/templates/state-shape.d.ts

@@ -0,0 +1,30 @@
+/**
+ * State-shape-with-defaults — the SDK half of Proposal 01's "declared state shape" (removes F5).
+ *
+ * A declared shape carries a `default` (and optional `type`) per field. It seeds `initialData` so every
+ * accumulator starts at a concrete value — a counter read via `{ '+': [{ var: 'state.x' }, ...] }` never
+ * resolves `null` because `x` was never written. It also yields the set of declared field names for
+ * Proposal 01's var-path checks.
+ */
+import type { SchemaFieldType } from '../schema/fiber-app.js';
+export interface StateShape {
+    fields: Record<string, {
+        default: unknown;
+        type?: SchemaFieldType;
+    }>;
+}
+/**
+ * Build `initialData` by overlaying `overrides` onto each field's declared `default`.
+ * Every declared field gets a concrete value, so no field reads `null` at runtime. An override for a
+ * field replaces that field's default; overrides for undeclared fields are ignored (only declared fields
+ * are emitted). Determinism: pure function of its inputs, stable key order (declared order).
+ *
+ * @example seedState({ fields: { purchaseCount: { default: 0 }, status: { default: 'ACTIVE' } } })
+ *          // => { purchaseCount: 0, status: 'ACTIVE' }
+ */
+export declare function seedState(shape: StateShape, overrides?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * The set of declared state-field names — the fields the effects may read.
+ * Feeds Proposal 01's var-path checks (a `{ var: 'state.foo' }` whose `foo` is not declared is suspect).
+ */
+export declare function declaredFields(shape: StateShape): Set<string>;

package/dist/types/zk/index.d.ts

@@ -10,10 +10,10 @@
  * `canonicalForSigning(data)`, so a proof's `exprHash` word equals {@link exprHash}`(rule)` equals a
  * policy's `logicHash` — see {@link proverPreimage} and docs/design/client-side-private-data.md §3.0.
  */
-export { canonicalForSigning, proverPreimage, exprHash, dataHash, KECCAK_TRUE, } from './preimage';
+export { canonicalForSigning, proverPreimage, exprHash, dataHash, KECCAK_TRUE } from './preimage';
 export { type FrHex, R, toFr, frToHex, randomSalt, poseidonCommit, poseidonCommitN, type Commitment, openCommitment, } from './commit';
-export { type DecodedPublicValues, type Groth16Bundle, decodeJlvmPublicValues, } from './types';
-export { type Groth16WitnessMap, type Groth16Witness, groth16Witness, type PmtWitnessMap, pmtWitness, } from './witness';
-export { type RegisteredRule, ExprRegistry, type Comparator, boundRule, atLeast, atMost, } from './registry';
+export { type DecodedPublicValues, type Groth16Bundle, decodeJlvmPublicValues } from './types';
+export { type Groth16WitnessMap, type Groth16Witness, groth16Witness, type PmtWitnessMap, pmtWitness } from './witness';
+export { type RegisteredRule, ExprRegistry, type Comparator, boundRule, atLeast, atMost } from './registry';
 export { type SemiPrivateGuardOptions, wordOffset, semiPrivateGuard, type BindingResult, verifyGroth16Bundle, checkSemiPrivateBinding, verifySemiPrivate, } from './guard';
 export { type ZkProver, type Groth16ProveRequest, SubprocessProver, type SubprocessProverOptions, parseGroth16Stdout, } from './prover';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ottochain/sdk",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "TypeScript SDK for ottochain metagraph operations - signing, encoding, and network interactions",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -26,6 +26,11 @@
       "require": "./dist/cjs/zk/index.js",
       "types": "./dist/types/zk/index.d.ts"
     },
+    "./templates": {
+      "import": "./dist/esm/templates/index.js",
+      "require": "./dist/cjs/templates/index.js",
+      "types": "./dist/types/templates/index.d.ts"
+    },
     "./apps/identity": {
       "import": "./dist/esm/apps/identity/index.js",
       "require": "./dist/cjs/apps/identity/index.js",
@@ -61,6 +66,16 @@
       "require": "./dist/cjs/apps/corporate/index.js",
       "types": "./dist/types/apps/corporate/index.d.ts"
     },
+    "./apps/compute": {
+      "import": "./dist/esm/apps/compute/index.js",
+      "require": "./dist/cjs/apps/compute/index.js",
+      "types": "./dist/types/apps/compute/index.d.ts"
+    },
+    "./apps/staked-pool": {
+      "import": "./dist/esm/apps/staked-pool/index.js",
+      "require": "./dist/cjs/apps/staked-pool/index.js",
+      "types": "./dist/types/apps/staked-pool/index.d.ts"
+    },
     "./apps": {
       "import": "./dist/esm/apps/index.js",
       "require": "./dist/cjs/apps/index.js",
@@ -86,8 +101,11 @@
     "test:coverage": "jest --coverage",
     "lint": "eslint src tests",
     "format": "prettier --write src tests",
+    "format:check": "prettier --check src tests",
     "generate": "buf generate",
-    "gen:openapi": "openapi-typescript openapi/ottochain-openapi.json -o src/generated/openapi.ts",
+    "fetch:openapi": "node scripts/fetch-openapi.mjs",
+    "gen:openapi": "openapi-typescript openapi/ottochain-openapi-ml0.json -o src/generated/openapi.ts",
+    "sync:openapi": "npm run fetch:openapi && npm run gen:openapi",
     "lint:proto": "buf lint",
     "docs": "typedoc",
     "docs:watch": "typedoc --watch",
@@ -117,9 +135,9 @@
     "url": "https://github.com/ottobot-ai/ottochain-sdk/issues"
   },
   "dependencies": {
-    "@bufbuild/protobuf": "^2.12.0",
-    "@constellation-network/metagraph-sdk": "1.8.0-rc.5",
-    "@constellation-network/metagraph-sdk-jlvm": "1.8.0-rc.5",
+    "@bufbuild/protobuf": "^2.12.1",
+    "@constellation-network/metagraph-sdk": "1.8.0-rc.7",
+    "@constellation-network/metagraph-sdk-jlvm": "1.8.0-rc.7",
     "@noble/hashes": "^1.8.0",
     "@stardust-collective/dag4": "^2.6.0",
     "@stardust-collective/dag4-keystore": "^2.6.0",
@@ -130,20 +148,20 @@
   },
   "devDependencies": {
     "@babel/preset-env": "^7.29.7",
-    "@commitlint/cli": "^21.0.2",
-    "@commitlint/config-conventional": "^21.0.2",
+    "@commitlint/cli": "^21.1.0",
+    "@commitlint/config-conventional": "^21.1.0",
     "@eslint/js": "^10.0.1",
     "@jest/globals": "^30.3.0",
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.9.3",
-    "@typescript-eslint/eslint-plugin": "^8.61.0",
-    "@typescript-eslint/parser": "^8.61.0",
-    "eslint": "^10.5.0",
+    "@types/node": "^26.0.1",
+    "@typescript-eslint/eslint-plugin": "^8.62.0",
+    "@typescript-eslint/parser": "^8.62.0",
+    "eslint": "^10.6.0",
     "jest": "^30.3.0",
     "openapi-typescript": "^7.13.0",
-    "prettier": "^3.8.4",
+    "prettier": "^3.9.1",
     "ts-jest": "29.4.9",
-    "ts-proto": "^2.11.6",
+    "ts-proto": "^2.11.9",
     "typedoc": "^0.28.19",
     "typescript": "^6.0.3"
   },