@ottochain/sdk 2.2.5 → 2.3.0

package/dist/types/ottochain/types.d.ts

@@ -46,6 +46,183 @@ export interface StateMachineDefinition {
     transitions: unknown[];
     metadata?: JsonLogicValue;
 }
+/**
+ * Semantic version `MAJOR.MINOR.PATCH`.
+ * Wire format: plain string (e.g. "1.0.0"). Also used as a JSON map key.
+ *
+ * @see modules/models/.../schema/registry/SemVer.scala
+ */
+export type SemVer = string;
+/**
+ * Lifecycle status of a registered version (npm/Cargo-style).
+ * Wire format: uppercase string (enumeratum `Uppercase`).
+ *
+ *  - `ACTIVE`     — selectable + recommended.
+ *  - `DEPRECATED` — still resolvable/runnable, flagged, discouraged for new instances.
+ *  - `YANKED`     — excluded from NEW resolutions; existing pinned fibers keep running.
+ *
+ * @see modules/models/.../schema/registry/RegistryStatus.scala
+ */
+export type RegistryStatus = 'ACTIVE' | 'DEPRECATED' | 'YANKED';
+/**
+ * A caller's version requirement, resolved against a {@link VersionLineage} (Cargo/npm-style).
+ * Wire format: single-key wrapper object (sealed-trait encoding).
+ *
+ *  - `Exact`      — exactly this version: `{"Exact":{"version":"1.0.0"}}`.
+ *  - `Caret`      — same MAJOR and `>= v` (`^1.2.0`).
+ *  - `Tilde`      — same MAJOR.MINOR and `>= v` (`~1.2.0`).
+ *  - `Latest`     — highest selectable version: `{"Latest":{}}`.
+ *  - `PinnedHash` — the exact artifact by schema hash, version-agnostic.
+ *
+ * @see modules/models/.../schema/registry/VersionReq.scala
+ */
+export type VersionReq = {
+    Exact: {
+        version: SemVer;
+    };
+} | {
+    Caret: {
+        version: SemVer;
+    };
+} | {
+    Tilde: {
+        version: SemVer;
+    };
+} | {
+    Latest: Record<string, never>;
+} | {
+    PinnedHash: {
+        schemaHash: string;
+    };
+};
+/**
+ * A caller's reference to a registered schema/program version, supplied at fiber creation
+ * (`CreateStateMachine.schemaRef`). The chain resolves `version` against the registry at create time.
+ * Wire format: `{"name":"counter.package","version":{"Exact":{"version":"1.0.0"}}}`.
+ *
+ * @see modules/models/.../schema/registry/SchemaRef.scala
+ */
+export interface SchemaRef {
+    /** Full registry name `labels.tld` (e.g. "counter.package"). */
+    name: string;
+    version: VersionReq;
+}
+/**
+ * One field of a {@link MessageShape} — mirrors a protobuf `FieldDescriptorProto`
+ * at the field level (name + field number + type).
+ * Wire format: `repeated`/`optional` default to `false` and are omittable.
+ *
+ * @see modules/models/.../schema/registry/SchemaShape.scala
+ */
+export interface FieldShape {
+    name: string;
+    number: number;
+    typeName: string;
+    repeated?: boolean;
+    optional?: boolean;
+}
+/**
+ * A single protobuf message shape: its type name plus its fields.
+ *
+ * @see modules/models/.../schema/registry/SchemaShape.scala
+ */
+export interface MessageShape {
+    typeName: string;
+    fields: FieldShape[];
+}
+/**
+ * The on-chain projection of a version's proto schema: the State message plus one
+ * message per command/event (keyed by event name). Publisher-claimed and advisory.
+ *
+ * @see modules/models/.../schema/registry/SchemaShape.scala
+ */
+export interface SchemaShape {
+    stateMessage: MessageShape;
+    /** One message per command/event, keyed by event name. */
+    commands: Record<string, MessageShape>;
+}
+/**
+ * The resolved, pinned binding recorded on a fiber: which registry (name, version) it
+ * instantiates, with the committed hashes. Resolved once at create, then immutable.
+ *
+ * @see modules/models/.../schema/registry/SchemaBinding.scala
+ */
+export interface SchemaBinding {
+    /** Full registry name `labels.tld`. */
+    name: string;
+    version: SemVer;
+    /** Commitment to the protobuf FileDescriptorSet (descriptor bytes; off-chain). */
+    schemaHash: string;
+    /** The verified-binding anchor: `StateMachineDefinition.computeDigest` of the logic. */
+    logicHash: string;
+}
+/**
+ * One immutable version of a registry entry. The chain commits only the hashes + the
+ * typed {@link SchemaShape} projection (never the descriptor or definition bytes).
+ * Wire format: `strict` defaults to `false` and is omittable.
+ *
+ * @see modules/models/.../schema/registry/RegisteredVersion.scala
+ */
+export interface RegisteredVersion {
+    version: SemVer;
+    /** Commitment to the protobuf FileDescriptorSet (descriptor bytes; off-chain). */
+    schemaHash: string;
+    /** The verified-binding anchor: `StateMachineDefinition.computeDigest` of the logic. */
+    logicHash: string;
+    schemaShape: SchemaShape;
+    status: RegistryStatus;
+    /** Snapshot ordinal at which this version was registered. */
+    registeredAt: number;
+    /** Opt-in runtime conformance gate (#33); defaults to `false`. */
+    strict?: boolean;
+}
+/**
+ * The append-only, monotonic version lineage of a single registry entry.
+ * Wire format: `versions` is a SemVer-string-keyed map of {@link RegisteredVersion}.
+ *
+ * @see modules/models/.../schema/registry/VersionLineage.scala
+ */
+export interface VersionLineage {
+    /** SemVer-string keyed map of registered versions. */
+    versions: Record<string, RegisteredVersion>;
+}
+/**
+ * What a registry entry resolves to, discriminated by the name's TLD.
+ * Wire format: single-key wrapper object (sealed-trait encoding).
+ *
+ *  - `SchemaPackage` (`.package`) — a versioned schema/program type (its {@link VersionLineage}).
+ *    Note the double-nesting: `SchemaPackage.versions` is a {@link VersionLineage} whose
+ *    own `.versions` is the SemVer-keyed map, e.g.
+ *    `{"SchemaPackage":{"versions":{"versions":{"1.0.0":{...}}}}}`.
+ *  - `InstanceAlias` (`.machine` / `.script`) — a nickname for an existing fiber (#29).
+ *
+ * @see modules/models/.../schema/registry/RegistryTarget.scala
+ */
+export type RegistryTarget = {
+    SchemaPackage: {
+        versions: VersionLineage;
+    };
+} | {
+    InstanceAlias: {
+        fiberId: string;
+    };
+};
+/**
+ * A single owned entry in the registry namespace: a name -> a discriminated
+ * {@link RegistryTarget}, with the owning addresses and an optional off-chain metadata grab-bag.
+ * Wire format: `metadata` defaults to `{}` and is omittable.
+ *
+ * @see modules/models/.../schema/registry/RegistryEntry.scala
+ */
+export interface RegistryEntry {
+    /** Full registry name `labels.tld`. */
+    name: string;
+    /** Owning DAG addresses (who may publish versions / change status / transfer). */
+    owner: string[];
+    target: RegistryTarget;
+    /** Optional off-chain links grab-bag (e.g. "repo"/"homepage" -> URL). */
+    metadata?: Record<string, string>;
+}
 /**
  * Event emitted by a state machine transition trigger.
  */
@@ -84,10 +261,40 @@ export interface OracleInvocation {
     invokedAt: number;
     invokedBy: string;
 }
+/**
+ * Birth record for a fiber, emitted once at creation. Records the resolved registry
+ * binding (name@version + committed hashes) when instantiated from a registered version
+ * (#26), or omits it for an ad-hoc fiber. Seeds the audit-trail rendering (#30).
+ *
+ * @see modules/models/.../schema/fiber/FiberLogEntry.scala
+ */
+export interface CreationReceipt {
+    fiberId: string;
+    ordinal: number;
+    initialState: string;
+    owners: string[];
+    schemaBinding?: SchemaBinding;
+    parentFiberId?: string;
+}
+/**
+ * Emitted when a fiber is upgraded to a different registered version (#27). Records the
+ * binding change (from -> to) and whether a state migration ran.
+ *
+ * @see modules/models/.../schema/fiber/FiberLogEntry.scala
+ */
+export interface UpgradeReceipt {
+    fiberId: string;
+    ordinal: number;
+    /** Prior binding; absent for a fiber that had no registry binding before the upgrade. */
+    fromBinding?: SchemaBinding;
+    toBinding: SchemaBinding;
+    gasUsed: number;
+    migrated: boolean;
+}
 /**
  * Union type for all fiber log entries.
  */
-export type FiberLogEntry = EventReceipt | OracleInvocation;
+export type FiberLogEntry = EventReceipt | OracleInvocation | CreationReceipt | UpgradeReceipt;
 /**
  * On-chain record for a state machine fiber.
  * Wire format: all ordinals/states/hashes are plain primitives.
@@ -107,6 +314,8 @@ export interface StateMachineFiberRecord {
     lastReceipt?: EventReceipt;
     parentFiberId?: string;
     childFiberIds: string[];
+    /** The resolved, pinned registry binding (#26), present when created from a registered version. */
+    schemaBinding?: SchemaBinding;
 }
 /**
  * On-chain record for a script oracle fiber.
@@ -142,6 +351,8 @@ export interface FiberCommit {
 export interface OnChain {
     fiberCommits: Record<string, FiberCommit>;
     latestLogs: Record<string, FiberLogEntry[]>;
+    /** Per-registry-entry commitment hash, keyed by full registry name `labels.tld`. */
+    registryCommits: Record<string, string>;
 }
 /**
  * Full calculated state (served by ML0 /v1/ endpoints).
@@ -149,6 +360,10 @@ export interface OnChain {
 export interface CalculatedState {
     stateMachines: Record<string, StateMachineFiberRecord>;
     scripts: Record<string, ScriptFiberRecord>;
+    /** Registry namespace, keyed by full registry name `labels.tld`. */
+    registry: Record<string, RegistryEntry>;
+    /** Reverse records (#29): fiber UUID -> its canonical registered name. */
+    reverseNames: Record<string, string>;
 }
 /**
  * Create a new state machine fiber.
@@ -160,6 +375,11 @@ export interface CreateStateMachine {
     parentFiberId?: string | null;
     /** Optional set of DAG addresses authorized to sign transitions (multi-party signing). */
     participants?: string[] | null;
+    /**
+     * Optional reference to a registered schema/program version (#26). When present, the chain
+     * resolves it against the registry at create time and records the verified {@link SchemaBinding}.
+     */
+    schemaRef?: SchemaRef | null;
 }
 /**
  * Trigger a state machine transition.
@@ -195,6 +415,64 @@ export interface InvokeScript {
     args: JsonLogicValue;
     targetSequenceNumber: number;
 }
+/**
+ * Upgrade an existing fiber to a different registered version of the SAME package (#27).
+ * The chain verifies `newDefinition` hashes to the target version's `logicHash`, applies the
+ * optional `migration` (a JSON-Logic transform of the prior state data), preserves the current
+ * state id, and re-pins the binding.
+ */
+export interface UpgradeFiber {
+    fiberId: string;
+    targetRef: SchemaRef;
+    newDefinition: StateMachineDefinition;
+    /** Optional JSON-Logic transform applied to the prior state data during upgrade. */
+    migration?: JsonLogicExpression;
+    targetSequenceNumber: number;
+}
+/**
+ * Create-or-append a registry schema-package version (npm-publish semantics): the first publish
+ * for a name claims it and makes the signer the owner; later publishes require an existing owner.
+ *
+ * Note: `fiberId` is NOT on the wire — the chain derives the routing id from `name`.
+ */
+export interface PublishVersion {
+    /** Full registry name `labels.tld` (e.g. "order.package"). */
+    name: string;
+    version: SemVer;
+    /** Base64 of the proto FileDescriptorSet; the chain base64-validates + hashes it, then drops the bytes. */
+    schemaB64: string;
+    /** The typed proto projection the chain stores for discovery (advisory). */
+    schemaShape: SchemaShape;
+    /** The typed JSON-Logic state machine; hashed into `logicHash` for verified binding (#37). */
+    definition: StateMachineDefinition;
+    /** Opt-in runtime conformance gate (#33); defaults to `false`, omittable. */
+    strict?: boolean;
+    /** Optional off-chain links grab-bag set on the entry at first publish; defaults to `{}`, omittable. */
+    metadata?: Record<string, string>;
+}
+/**
+ * Change a registered version's lifecycle status (Active <-> Deprecated -> Yanked). Owner-gated.
+ */
+export interface SetVersionStatus {
+    /** Full registry name `labels.tld`. */
+    name: string;
+    version: SemVer;
+    status: RegistryStatus;
+}
+/**
+ * Register a human-readable nickname for an existing fiber (#29). The name's TLD must be
+ * `.machine` or `.script` and match the target fiber's kind; the signer must own the target.
+ *
+ * Note: `fiberId` is NOT on the wire — the chain derives the routing id from `name`.
+ */
+export interface RegisterAlias {
+    /** Full registry name `labels.tld` (e.g. "my-escrow.machine"). */
+    name: string;
+    /** The existing fiber UUID this alias points at. */
+    targetFiberId: string;
+    /** Optional off-chain links grab-bag; defaults to `{}`, omittable. */
+    metadata?: Record<string, string>;
+}
 /**
  * Union type for all ottochain messages.
  * JSON is wrapped as `{ MessageName: { ...fields } }`.
@@ -205,16 +483,24 @@ export type OttochainMessage = {
     TransitionStateMachine: TransitionStateMachine;
 } | {
     ArchiveStateMachine: ArchiveStateMachine;
+} | {
+    UpgradeFiber: UpgradeFiber;
 } | {
     CreateScript: CreateScript;
 } | {
     InvokeScript: InvokeScript;
+} | {
+    PublishVersion: PublishVersion;
+} | {
+    SetVersionStatus: SetVersionStatus;
+} | {
+    RegisterAlias: RegisterAlias;
 };
 /**
  * Names of all valid OttochainMessage types.
  * Use this for runtime validation (e.g., in API routes).
  */
-export declare const OTTOCHAIN_MESSAGE_TYPES: readonly ["CreateStateMachine", "TransitionStateMachine", "ArchiveStateMachine", "CreateScript", "InvokeScript"];
+export declare const OTTOCHAIN_MESSAGE_TYPES: readonly ["CreateStateMachine", "TransitionStateMachine", "ArchiveStateMachine", "UpgradeFiber", "CreateScript", "InvokeScript", "PublishVersion", "SetVersionStatus", "RegisterAlias"];
 /**
  * Type representing valid message type names.
  */

package/dist/types/schema/fiber-app.d.ts

@@ -40,11 +40,50 @@ export interface EventSchema {
     required?: readonly string[];
     properties?: Record<string, SchemaField>;
 }
+/**
+ * Lifecycle category for a state — a small fixed vocabulary that lets UIs group
+ * and color states and lets analytics bucket fibers without app-specific logic.
+ *
+ * - `initial`  — the machine's `initialState` (entry point)
+ * - `active`   — a normal, operational, non-terminal state
+ * - `pending`  — a transient state awaiting an action/condition/timeout
+ * - `terminal` — a final state (`isFinal: true`); the machine ends here
+ */
+export type StateCategory = 'initial' | 'active' | 'pending' | 'terminal';
+/**
+ * Standard per-state metadata convention for OttoChain std apps.
+ *
+ * This is the minimal, high-value block we attach to every standard state
+ * definition (instead of `metadata: null`). It is plain JSON, so it survives
+ * the client/server null-dropping canonicalization (only NULL fields are
+ * dropped; a populated object is kept and signed/verified identically on both
+ * sides). Custom apps may extend `StateDefinition.metadata` with extra keys.
+ *
+ * Fields:
+ * - `label`       — short human-readable title for the state (e.g. "Active")
+ * - `description` — one-line explanation of what the state means
+ * - `category`    — optional lifecycle hint (see {@link StateCategory})
+ */
+export interface StdStateMetadata {
+    /** Short human-readable title, e.g. "Voting". */
+    label: string;
+    /** One-line description of what this state represents. */
+    description: string;
+    /** Optional lifecycle category hint for UIs / analytics. */
+    category?: StateCategory;
+}
 export interface StateDefinition {
     id: string;
     isFinal: boolean;
     description?: string;
-    metadata?: Record<string, unknown> | null;
+    /**
+     * Optional per-state metadata. Std apps populate the {@link StdStateMetadata}
+     * convention (`label` / `description` / `category`); custom apps may use any
+     * JSON object or `null`. NOTE: a `null` here is stripped from the signed wire
+     * form (the chain drops null object-fields), so prefer populated metadata or
+     * omit the field entirely.
+     */
+    metadata?: StdStateMetadata | Record<string, unknown> | null;
 }
 export type JsonLogicRule = Record<string, unknown>;
 export interface EmitSpec {

package/dist/types/validation.d.ts

@@ -142,11 +142,11 @@ export declare const TransactionReferenceSchema: z.ZodObject<{
     ordinal: z.ZodNumber;
     hash: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    ordinal: number;
     hash: string;
-}, {
     ordinal: number;
+}, {
     hash: string;
+    ordinal: number;
 }>;
 /**
  * Schema for CurrencyTransactionValue
@@ -157,13 +157,13 @@ export declare const CurrencyTransactionValueSchema: z.ZodObject<{
     amount: z.ZodNumber;
     fee: z.ZodDefault<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    destination: string;
     amount: number;
+    destination: string;
     source: string;
     fee: number;
 }, {
-    destination: string;
     amount: number;
+    destination: string;
     source: string;
     fee?: number | undefined;
 }>;
@@ -177,13 +177,13 @@ export declare const CurrencyTransactionSchema: z.ZodObject<{
         amount: z.ZodNumber;
         fee: z.ZodDefault<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
-        destination: string;
         amount: number;
+        destination: string;
         source: string;
         fee: number;
     }, {
-        destination: string;
         amount: number;
+        destination: string;
         source: string;
         fee?: number | undefined;
     }>;
@@ -191,33 +191,33 @@ export declare const CurrencyTransactionSchema: z.ZodObject<{
         ordinal: z.ZodNumber;
         hash: z.ZodString;
     }, "strip", z.ZodTypeAny, {
-        ordinal: number;
         hash: string;
-    }, {
         ordinal: number;
+    }, {
         hash: string;
+        ordinal: number;
     }>;
 }, "strip", z.ZodTypeAny, {
     value: {
-        destination: string;
         amount: number;
+        destination: string;
         source: string;
         fee: number;
     };
     parent: {
-        ordinal: number;
         hash: string;
+        ordinal: number;
     };
 }, {
     value: {
-        destination: string;
         amount: number;
+        destination: string;
         source: string;
         fee?: number | undefined;
     };
     parent: {
-        ordinal: number;
         hash: string;
+        ordinal: number;
     };
 }>;
 /**
@@ -258,9 +258,9 @@ export declare const AgentIdentityRegistrationSchema: z.ZodObject<{
     /** Initial reputation (default: 10) */
     reputation: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
 }, "strip", z.ZodTypeAny, {
+    reputation: number;
     publicKey: string;
     displayName: string;
-    reputation: number;
 }, {
     publicKey: string;
     displayName: string;
@@ -310,15 +310,15 @@ export declare const ProposeContractRequestSchema: z.ZodObject<{
     /** Human-readable description */
     description: z.ZodString;
 }, "strip", z.ZodTypeAny, {
+    description: string;
     proposer: string;
-    counterparty: string;
     terms: Record<string, unknown>;
-    description: string;
+    counterparty: string;
 }, {
+    description: string;
     proposer: string;
-    counterparty: string;
     terms: Record<string, unknown>;
-    description: string;
+    counterparty: string;
 }>;
 /**
  * Type for validated ProposeContractRequest

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ottochain/sdk",
-  "version": "2.2.5",
+  "version": "2.3.0",
   "description": "TypeScript SDK for ottochain metagraph operations - signing, encoding, and network interactions",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -66,6 +66,24 @@
     "dist",
     "README.md"
   ],
+  "scripts": {
+    "build": "npm run prebuild && npm run build:cjs && npm run build:esm && npm run build:types && npm run build:fixup",
+    "build:fixup": "echo '{\"type\":\"module\"}' > dist/esm/package.json && echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:types": "tsc -p tsconfig.types.json",
+    "test": "jest",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint src tests",
+    "format": "prettier --write src tests",
+    "generate": "buf generate",
+    "lint:proto": "buf lint",
+    "docs": "typedoc",
+    "docs:watch": "typedoc --watch",
+    "genesis:manifest": "npm run build && node scripts/emit-genesis-manifest.mjs genesis/std-manifest.json",
+    "prepare": "npm run build",
+    "prebuild": "node scripts/inline-json.mjs"
+  },
   "keywords": [
     "ottochain",
     "constellation",
@@ -88,31 +106,31 @@
     "url": "https://github.com/ottobot-ai/ottochain-sdk/issues"
   },
   "dependencies": {
-    "@bufbuild/protobuf": "^2.11.0",
+    "@bufbuild/protobuf": "^2.12.0",
     "@constellation-network/metagraph-sdk": "^0.2.0",
     "@stardust-collective/dag4": "^2.6.0",
     "@stardust-collective/dag4-keystore": "^2.6.0",
-    "canonicalize": "^2.1.0",
+    "canonicalize": "^3.0.0",
     "js-sha256": "^0.11.1",
     "js-sha512": "^0.9.0",
     "zod": "^3.22.0"
   },
   "devDependencies": {
     "@babel/preset-env": "^7.29.0",
-    "@commitlint/cli": "^20.4.4",
+    "@commitlint/cli": "^20.5.2",
     "@commitlint/config-conventional": "^20.5.0",
     "@eslint/js": "^9.39.4",
     "@jest/globals": "^30.3.0",
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.6.0",
     "@typescript-eslint/eslint-plugin": "^8.56.1",
-    "@typescript-eslint/parser": "^8.57.1",
+    "@typescript-eslint/parser": "^8.59.0",
     "eslint": "^9.39.3",
     "jest": "^30.3.0",
-    "prettier": "^3.0.0",
-    "ts-jest": "^29.0.0",
-    "ts-proto": "^2.11.5",
-    "typedoc": "^0.28.17",
+    "prettier": "^3.8.3",
+    "ts-jest": "29.4.9",
+    "ts-proto": "^2.11.6",
+    "typedoc": "^0.28.19",
     "typescript": "^5.0.0"
   },
   "peerDependencies": {
@@ -124,20 +142,5 @@
   "publishConfig": {
     "registry": "https://registry.npmjs.org"
   },
-  "scripts": {
-    "build": "npm run prebuild && npm run build:cjs && npm run build:esm && npm run build:types && npm run build:fixup",
-    "build:fixup": "echo '{\"type\":\"module\"}' > dist/esm/package.json && echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",
-    "build:cjs": "tsc -p tsconfig.cjs.json",
-    "build:esm": "tsc -p tsconfig.esm.json",
-    "build:types": "tsc -p tsconfig.types.json",
-    "test": "jest",
-    "test:coverage": "jest --coverage",
-    "lint": "eslint src tests",
-    "format": "prettier --write src tests",
-    "generate": "buf generate",
-    "lint:proto": "buf lint",
-    "docs": "typedoc",
-    "docs:watch": "typedoc --watch",
-    "prebuild": "node scripts/inline-json.mjs"
-  }
-}
+  "packageManager": "pnpm@10.30.0"
+}