@ottochain/sdk 2.4.0 → 2.6.0

package/dist/types/ottochain/metagraph-client.d.ts

@@ -10,6 +10,8 @@
  */
 import type { Signed } from '@constellation-network/metagraph-sdk';
 import type { OnChain, CalculatedState, StateMachineFiberRecord, ScriptFiberRecord, EventReceipt, ScriptInvocation, FiberStatus, RegistryEntry } from './types.js';
+import type { VersionInfo, TransitionFeeEstimate, ScriptFeeEstimate, SubscribeRequest, SubscribeResponse, SubscriberList } from '../openapi.js';
+export type { VersionInfo, TransitionFeeEstimate, ScriptFeeEstimate, SubscribeRequest, SubscribeResponse, SubscriberList, } from '../openapi.js';
 /**
  * Checkpoint response from the metagraph (ordinal + calculated state).
  */
@@ -23,22 +25,39 @@ export interface Checkpoint {
  * endpoints.
  */
 export interface StateProof {
-    /** The record (or projected field) the proof attests to. */
-    record: unknown;
+    /**
+     * The trie key the proof is keyed on — the fiber/asset id (optionally suffixed with the requested
+     * field). Chain: `StateProofResponse.key: String` (required).
+     */
+    key: string;
+    ordinal: number;
     /** The committed-state combined root (= the snapshot's `calculatedStateProof`). */
     committedRoot: string;
     /** The Merkle-Patricia trie root. */
     mptRoot: string;
-    ordinal: number;
+    /** The record (or projected field) the proof attests to. */
+    record: unknown;
     /** The Merkle-Patricia inclusion proof. */
     proof: unknown;
+    /**
+     * The `stateData` field name that was projected, present ONLY when a `?field=` was requested
+     * (chain `field: Option[String]`, `dropNullValues`-stripped otherwise).
+     */
+    field?: string;
+    /**
+     * The value of the projected `field`, present ONLY when a `?field=` was requested
+     * (chain `fieldValue: Option[Json]`, `dropNullValues`-stripped otherwise).
+     */
+    fieldValue?: unknown;
 }
-/** A fee/gas estimate for a transition or script invocation (shape is advisory / may evolve). */
-export interface FeeEstimate {
-    gas?: number;
-    fee?: number;
-    [key: string]: unknown;
-}
+/**
+ * A static fee/gas estimate. The wire is one of two per-endpoint shapes — {@link TransitionFeeEstimate}
+ * (state-machine transition) or {@link ScriptFeeEstimate} (script invocation) — that mirror the chain's
+ * `FeeEstimates.scala` case classes byte-for-byte. Prefer the per-endpoint types on
+ * {@link MetagraphClient.estimateTransitionFee} / {@link MetagraphClient.estimateScriptFee}; this union is
+ * a convenience for code that handles either.
+ */
+export type FeeEstimate = TransitionFeeEstimate | ScriptFeeEstimate;
 /**
  * Options for subscribeFiberState polling behaviour.
  */
@@ -151,8 +170,12 @@ export declare class MetagraphClient {
      * Get script invocations from the current ordinal's logs.
      */
     getScriptInvocations(scriptId: string): Promise<ScriptInvocation[]>;
-    /** Get the metagraph version string. */
-    getVersion(): Promise<string>;
+    /**
+     * Get the node's service identity + build metadata. The chain's `GET …/version` returns a
+     * `VersionInfo` OBJECT (`{ service, version, name, scalaVersion, sbtVersion, gitCommit, buildTime,
+     * tessellationVersion }`) — chain `ServiceMeta.scala` — NOT a bare string.
+     */
+    getVersion(): Promise<VersionInfo>;
     /** Get the full registry namespace, keyed by full registry name `labels.tld`. */
     getRegistry(): Promise<Record<string, RegistryEntry>>;
     /** Resolve a single registry entry by full name (`labels.tld`), or null if unregistered. */
@@ -167,10 +190,41 @@ export declare class MetagraphClient {
     getScriptStateProof(fiberId: string, field: string): Promise<StateProof>;
     /** Light-client state proof for a field of an asset instance. */
     getAssetStateProof(assetId: string, field: string): Promise<StateProof>;
-    /** Estimate the fee/gas for a transition event on a state-machine fiber. */
-    estimateTransitionFee(fiberId: string, eventName: string): Promise<FeeEstimate>;
-    /** Estimate the fee/gas for invoking a script fiber. */
-    estimateScriptFee(fiberId: string): Promise<FeeEstimate>;
+    /**
+     * Estimate the fee/gas for a transition event on a state-machine fiber. Returns a
+     * {@link TransitionFeeEstimate} (`{ fiberId, currentState, event, gasEstimate, opCount, maxDepth,
+     * candidateTransitions, note }`) — chain `FeeEstimates.scala`.
+     */
+    estimateTransitionFee(fiberId: string, eventName: string): Promise<TransitionFeeEstimate>;
+    /**
+     * Estimate the fee/gas for invoking a script fiber. Returns a {@link ScriptFeeEstimate}
+     * (`{ scriptId, gasEstimate, opCount, maxDepth, note }`) — chain `FeeEstimates.scala`.
+     */
+    estimateScriptFee(fiberId: string): Promise<ScriptFeeEstimate>;
+    /**
+     * Subscribe a callback URL to snapshot-notification webhooks.
+     *
+     * `POST …/webhooks/subscribe` with `SubscribeRequest { callbackUrl, secret? }`; the chain replies
+     * `201 Created` with `SubscribeResponse { id, callbackUrl, createdAt }`. Chain: `ML0Routes.scala`
+     * (`webhook.subscribe`) + `webhooks/Subscriber.scala`.
+     */
+    subscribeWebhook(request: SubscribeRequest): Promise<SubscribeResponse>;
+    /**
+     * Unsubscribe a webhook by its subscriber id.
+     *
+     * `DELETE …/webhooks/subscribe/{id}` → `204 No Content` (empty body) on success, or `404` if the id is
+     * unknown. Chain: `ML0Routes.scala` (`webhook.unsubscribe`). The vendored `HttpClient` exposes only
+     * `get`/`post`, so this reuses its shared private `request` helper — same `NetworkError`/timeout
+     * handling as every other call — to issue the DELETE.
+     */
+    unsubscribeWebhook(id: string): Promise<void>;
+    /**
+     * List the current webhook subscribers (secrets are redacted server-side).
+     *
+     * `GET …/webhooks/subscribers` → `SubscriberList { subscribers: Subscriber[] }`. Chain:
+     * `ML0Routes.scala` (`webhook.list`) + `webhooks/Subscriber.scala`.
+     */
+    listWebhookSubscribers(): Promise<SubscriberList>;
     /**
      * Get the latest snapshot and decode its on-chain state.
      */

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

@@ -5,7 +5,7 @@
  * self-signed mode, where clients sign their own transactions.
  */
 import type { Signed } from '@constellation-network/metagraph-sdk';
-import type { CreateAssetPolicy, MintAsset, ApplyMorphism, AuthorizeCompose } from './types.js';
+import type { CreateAssetPolicy, MintAsset, ApplyMorphism, AuthorizeCompose, PublishMachineVersion, UpgradeFiber } from './types.js';
 /**
  * Parameters for creating a new state machine fiber
  */
@@ -202,6 +202,14 @@ export declare function createApplyMorphismPayload(params: ApplyMorphism): {
 export declare function createAuthorizeComposePayload(params: AuthorizeCompose): {
     AuthorizeCompose: AuthorizeCompose;
 };
+/** Wrap a {@link PublishMachineVersion} (create-or-append a STATE-MACHINE registry version). */
+export declare function createPublishMachineVersionPayload(params: PublishMachineVersion): {
+    PublishMachineVersion: PublishMachineVersion;
+};
+/** Wrap an {@link UpgradeFiber} (re-pin a fiber to another registered version of the SAME package). */
+export declare function createUpgradeFiberPayload(params: UpgradeFiber): {
+    UpgradeFiber: UpgradeFiber;
+};
 /**
  * Sign a transaction payload for self-signed mode.
  *

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

@@ -7,7 +7,7 @@
  * @see modules/models/src/main/scala/xyz/kd5ujc/schema/
  * @packageDocumentation
  */
-export type { Address, FiberId, StateId, HashValue, FiberOrdinal, SnapshotOrdinal, Timestamp, } from '../types.js';
+export type { Address, FiberId, StateId, HashValue, FiberOrdinal, SnapshotOrdinal, Timestamp } from '../types.js';
 /**
  * JSON logic value - arbitrary JSON data used for state data and payloads.
  */

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

@@ -2,5 +2,5 @@
  * Privacy: shield any fiber app into a zk-jlvm-shielded private-state pool.
  * See docs/design/zk-private-contract-state-rfc.md.
  */
-export { shieldApp, SHIELDED_POOL_STATE, type ShieldOptions } from "./shield-app.js";
-export { sealedBidAccountDef, shieldedSealedBidDef, vickreyAuctionDef } from "./sealed-bid.js";
+export { shieldApp, SHIELDED_POOL_STATE, type ShieldOptions } from './shield-app.js';
+export { sealedBidAccountDef, shieldedSealedBidDef, vickreyAuctionDef } from './sealed-bid.js';

package/dist/types/privacy/sealed-bid.d.ts

@@ -11,8 +11,8 @@
  *     (the Vickrey price). This is the one shared-state step, kept simple for v1; a zk settlement
  *     proof that seals losers' amounts forever is the deferred upgrade (RFC §10).
  */
-import { type FiberAppDefinition } from "../schema/fiber-app.js";
-import { type ShieldOptions } from "./shield-app.js";
+import { type FiberAppDefinition } from '../schema/fiber-app.js';
+import { type ShieldOptions } from './shield-app.js';
 /** The per-bidder PRIVATE state: a bid note `{ amount, bidder, nonce }`. */
 export declare const sealedBidAccountDef: {
     readonly metadata: {
@@ -75,7 +75,7 @@ export declare const sealedBidAccountDef: {
         readonly to: "BID";
         readonly eventName: "place_bid";
         readonly guard: {
-            readonly ">": readonly [{
+            readonly '>': readonly [{
                 readonly var: "event.amount";
             }, 0];
         };
@@ -209,7 +209,7 @@ export declare const vickreyAuctionDef: {
         readonly to: "REVEAL";
         readonly eventName: "reveal";
         readonly guard: {
-            readonly ">=": readonly [{
+            readonly '>=': readonly [{
                 readonly var: "$timestamp";
             }, {
                 readonly var: "state.deadline";
@@ -240,7 +240,7 @@ export declare const vickreyAuctionDef: {
         readonly to: "REVEAL";
         readonly eventName: "reveal";
         readonly guard: {
-            readonly ">=": readonly [{
+            readonly '>=': readonly [{
                 readonly var: "$timestamp";
             }, {
                 readonly var: "state.deadline";
@@ -270,11 +270,11 @@ export declare const vickreyAuctionDef: {
         readonly to: "SETTLED";
         readonly eventName: "settle";
         readonly guard: {
-            readonly ">": readonly [{
+            readonly '>': readonly [{
                 readonly reduce: readonly [{
                     readonly var: "state.revealed";
                 }, {
-                    readonly "+": readonly [{
+                    readonly '+': readonly [{
                         readonly var: "accumulator";
                     }, 1];
                 }, 0];
@@ -299,7 +299,7 @@ export declare const vickreyAuctionDef: {
                         readonly var: "state.revealed";
                     }, {
                         readonly if: readonly [{
-                            readonly ">": readonly [{
+                            readonly '>': readonly [{
                                 readonly var: "current.amount";
                             }, {
                                 readonly var: "accumulator.max";
@@ -316,7 +316,7 @@ export declare const vickreyAuctionDef: {
                             };
                         }, {
                             readonly if: readonly [{
-                                readonly ">": readonly [{
+                                readonly '>': readonly [{
                                     readonly var: "current.amount";
                                 }, {
                                     readonly var: "accumulator.second";

package/dist/types/privacy/shield-app.d.ts

@@ -24,7 +24,7 @@
  * O(state size) (RFC §8). Keep shielded note state small (a few KB); for large keyed state use
  * the auth-DB variant (RFC §3.1.1).
  */
-import { type FiberAppDefinition, type SchemaField } from "../schema/fiber-app.js";
+import { type FiberAppDefinition, type SchemaField } from '../schema/fiber-app.js';
 export interface ShieldOptions {
     /** SP1 program vkey for the zk-jlvm-shielded circuit (0x-prefixed bytes32 hex). Pinned at creation. */
     vkey: string;

package/dist/types/schema/effects.d.ts

@@ -14,6 +14,7 @@
  * }
  * ```
  */
+import type { ProtoStateMachineDefinition } from './fiber-app.js';
 /** A JSON-Logic value: a literal (string/number/bool) or a `{var}`/operator expression. */
 type JsonLogicValue = unknown;
 /**
@@ -31,4 +32,135 @@ export declare const addDependency: (fiberId: JsonLogicValue) => Record<string,
  * may be a literal or an expression.
  */
 export declare const setDependencyActive: (fiberId: JsonLogicValue, active: boolean) => Record<string, unknown>;
+/**
+ * `_transferAsset`: move one or more WHOLE asset instances the emitting fiber holds, each to a single
+ * recipient. The directive rides INSIDE a `merge` effect map (the engine extracts `_`-prefixed keys
+ * before merging into state); a transition-level `emits` block is silently stripped by
+ * `toProtoDefinition`, which would strand the asset.
+ *
+ * Each directive is `{ assetId, recipient }` ONLY — there is NO `amount` field. The combiner reassigns
+ * `holder := recipient` on the WHOLE asset record (`AssetCombiner.applyFiberTransfer`); value is moved
+ * one whole instance at a time, never split. `recipient` must resolve to the canonical `AssetHolder`
+ * OBJECT form — `{"Fiber":{"fiberId":..}}` / `{"Wallet":{"address":..}}` — built with {@link toFiber} /
+ * {@link toWallet}; the chain raises a graceful `CombineRejected` on a bare string or malformed object
+ * (`EffectExtractor.parseAssetTransfer`). `assetId` is a UUID; the holder id may be a literal or an
+ * expression (e.g. `{ var: "event.agent" }`).
+ *
+ * Combiner-side holder defense (R1) independently re-validates every directive: the asset must resolve,
+ * be held by `Fiber(self)`, be `behavior.transferable`, and (Fiber recipient) the recipient fiber must be
+ * live — else the whole transition is `CombineRejected`. There is a hard cap of 32 asset mutations per
+ * transition (all-or-nothing); keep emitting fibers at ≤1 transfer per transition for claim/withdraw/slash.
+ *
+ * @example
+ * effect: { merge: [ { var: "state" }, {
+ *   status: "SETTLED",
+ *   ...transferAsset([{ assetId: { var: "event.rewardAssetId" }, recipient: toWallet({ var: "event.agent" }) }]),
+ * } ] }
+ */
+export declare const transferAsset: (transfers: {
+    assetId: JsonLogicValue;
+    recipient: JsonLogicValue;
+}[]) => Record<string, unknown>;
+/**
+ * Build a `_transferAsset` `recipient` as the canonical `AssetHolder` OBJECT form. The chain requires the
+ * object form ONLY — `{"Fiber":{"fiberId":..}}` / `{"Wallet":{"address":..}}` — and raises a graceful
+ * `CombineRejected` on a bare string or a malformed object (`EffectExtractor.parseAssetTransfer`); the
+ * legacy bare-string UUID/DAG-address disambiguation has been removed. These mirror the typed
+ * {@link fiberHolder} / {@link walletHolder} `AssetHolder` builders (used for `MintAsset.holder` /
+ * `ApplyMorphism.recipient`) but accept a `JsonLogicValue`, so the id can be a runtime expression:
+ *
+ * ```ts
+ * transferAsset([{ assetId, recipient: toFiber({ var: "event.retailerId" }) }]);  // → {"Fiber":{"fiberId":..}}
+ * transferAsset([{ assetId, recipient: toWallet({ var: "event.agent" }) }]);       // → {"Wallet":{"address":..}}
+ * ```
+ */
+export declare const toFiber: (fiberId: JsonLogicValue) => JsonLogicValue;
+/** See {@link toFiber}: a `transferAsset` recipient held by a wallet — `{"Wallet":{"address":..}}`. */
+export declare const toWallet: (address: JsonLogicValue) => JsonLogicValue;
+/**
+ * `_triggers` (F4): fire one or more CROSS-FIBER events. Each entry is projected to
+ * `{ targetMachineId, eventName, payload }` — the exact shape the chain's `EffectExtractor` reads
+ * (`ReservedKeys.scala`, `EffectExtractor.scala`). `target` is the recipient fiber id (a literal UUID
+ * or an expression, e.g. `{ var: "event.retailerId" }`); `event` is the event NAME to enqueue on it;
+ * `payload` is the event body — omit it and the builder emits `{}` (never `null`).
+ *
+ * Authoring this as a builder makes a typo'd `_trigger` / `triggres` a TypeScript error rather than a
+ * silently-merged state field (the F4 foot-gun). Place the fragment INSIDE the effect's state-update
+ * map so it rides in the evaluated result the extractor reads.
+ *
+ * @example
+ * effect: { merge: [ { var: "state" }, {
+ *   status: "debt_current",
+ *   ...triggers([{ target: { var: "event.retailerId" }, event: "process_sale",
+ *     payload: { buyerId: { var: "machineId" }, quantity: { var: "event.quantity" } } }]),
+ * } ] }
+ */
+export declare const triggers: (ts: {
+    target: JsonLogicValue;
+    event: string;
+    payload?: Record<string, unknown>;
+}[]) => Record<string, unknown>;
+/**
+ * `_spawn`: create one or more CHILD fibers, each from a literal machine `definition`. Each entry is
+ * `{ childId, definition, initialData, owners }` (`ReservedKeys.scala`, `EffectExtractor.scala`).
+ *
+ * The chain extracts `_spawn` from the effect EXPRESSION, not the evaluated result, so `definition`
+ * MUST be a literal {@link ProtoStateMachineDefinition} (e.g. a nested `machine().wireDefinition()` /
+ * `toProtoDefinition(child)` output) — NOT an expression the engine would evaluate at runtime.
+ *
+ * F8 gotcha — `owners` is load-bearing. A spawned child's transitions are gated by
+ * `owners ∪ authorizedSigners` (`riverdale-economy/README.md`), so EVERY party that will later drive
+ * the child (e.g. every bidder on a spawned auction) MUST be listed in `owners`, or their events are
+ * rejected. `owners` may be a literal id array or an expression (e.g. `{ var: "event.auctionOwners" }`);
+ * `childId` / `initialData` likewise accept literals or expressions.
+ */
+export declare const spawn: (ds: {
+    childId: JsonLogicValue;
+    definition: ProtoStateMachineDefinition;
+    initialData: Record<string, unknown>;
+    owners: JsonLogicValue;
+}[]) => Record<string, unknown>;
+/**
+ * `_emit`: emit one or more domain events to the fiber's outbox. Each entry is
+ * `{ name, data, destination? }` (`ReservedKeys.scala`, `EffectExtractor.scala`). `name` is the event
+ * name, `data` the body (a literal or an expression), and `destination` an OPTIONAL routing target —
+ * omit it when absent (callers never pass `null`, so it is simply absent on the wire).
+ */
+export declare const emit: (es: {
+    name: string;
+    data: JsonLogicValue;
+    destination?: string;
+}[]) => Record<string, unknown>;
+/**
+ * `_scriptCall`: invoke a SCRIPT fiber's `method` from an effect. Unlike the array-valued directives,
+ * `_scriptCall` is a SINGLE object `{ fiberId, method, args }` (chain `ReservedKeys.scala` `SCRIPT_CALL` /
+ * `EffectExtractor.extractScriptCall`). `fiberId` is the target script's UUID (a literal or an expression,
+ * e.g. `{ var: "state.resolverId" }`); `method` is the script method NAME; `args` is the argument body —
+ * a JSON-Logic value the chain EVALUATES against the transition context before dispatch.
+ *
+ * The chain's extractor requires ALL THREE fields — if `args` is absent the whole call is silently DROPPED
+ * (fail-silent, like the other extractors). So the builder ALWAYS emits `args`, defaulting an omitted one
+ * to `{}` (no-args), mirroring how {@link triggers} defaults an absent `payload`. Authoring this as a
+ * builder makes a typo'd `_scriptcall` / wrong field a TypeScript error rather than a silently-merged
+ * state field. Place the fragment INSIDE the effect's state-update map so it rides in the evaluated result.
+ *
+ * @example
+ * effect: { merge: [ { var: "state" }, {
+ *   status: "resolving",
+ *   ...scriptCall({ fiberId: { var: "state.resolverId" }, method: "resolve",
+ *     args: { marketId: { var: "machineId" } } }),
+ * } ] }
+ */
+export declare const scriptCall: (call: {
+    fiberId: JsonLogicValue;
+    method: string;
+    args?: JsonLogicValue;
+}) => Record<string, unknown>;
+/**
+ * The complete set of `_`-prefixed RESERVED effect keys the chain's `EffectExtractor` consumes and
+ * `StateMerger` strips from state (`ReservedKeys.scala:12-49`). Exported so a validator (Proposal 01)
+ * can reject an unknown `_`-prefixed key (a typo'd directive) instead of letting it silently leak into
+ * persisted state.
+ */
+export declare const RESERVED_EFFECT_KEYS: readonly ["_triggers", "_spawn", "_emit", "_transferAsset", "_scriptCall", "_addDependency", "_setDependencyActive"];
 export {};