@ottochain/sdk 2.5.0 → 2.7.0

package/dist/esm/schema/guard-lint.js

@@ -32,6 +32,11 @@
  *
  *   leading-dot — `{"var":".foo"}` resolves to null on chain.
  *
+ *   H1 — a `_spawn` whose child `owners` are not provably a SUBSET of the spawning
+ *        parent's owners. The chain now fails-closed (aborts the transition) under
+ *        every spawnOwnerPolicy when child owners ⊄ parent owners; this advisory
+ *        flags the strong not-subset signals (hardcoded / `event.*`-derived owners).
+ *
  * This is a STANDALONE validator. It is deliberately NOT wired into
  * `defineFiberApp` / `toProtoDefinition`: doing so would break the build until
  * every app is remediated. Run it via `scripts/lint-apps.mjs`.
@@ -50,6 +55,7 @@ export const LINT_CODES = {
     WITNESS_IN_TRANSITION: 'witness-in-transition', // rule 3
     DROPPED_DIRECTIVE: 'dropped-directive', // rule 4 (A3)
     LEADING_DOT_VAR: 'leading-dot-var', // rule 5
+    SPAWN_OWNERS: 'spawn-owners', // rule 6 (H1) — child owners not provably ⊆ parent
 };
 // =============================================================================
 // Rule data
@@ -287,6 +293,101 @@ function lintTransitionStructure(t, app, transition, path) {
     return out;
 }
 // =============================================================================
+// _spawn owner-subset rule (rule 6 / H1)
+// =============================================================================
+/** Collect every string `var` reference (path or `[path, default]` head) at or below `node`. */
+function collectVarRefs(node, acc) {
+    if (Array.isArray(node)) {
+        node.forEach((child) => collectVarRefs(child, acc));
+        return;
+    }
+    if (node === null || typeof node !== 'object')
+        return;
+    const obj = node;
+    const keys = Object.keys(obj);
+    if (keys.length === 1 && keys[0] === 'var') {
+        const ref = obj.var;
+        if (typeof ref === 'string')
+            acc.push(ref);
+        else if (Array.isArray(ref)) {
+            if (typeof ref[0] === 'string')
+                acc.push(ref[0]);
+            if (ref.length > 1)
+                collectVarRefs(ref[1], acc);
+        }
+        return;
+    }
+    for (const k of keys)
+        collectVarRefs(obj[k], acc);
+}
+/**
+ * Classify a `_spawn` child `owners` expression for the H1 subset risk. Returns a short reason string when
+ * the owners are NOT provably ⊆ the parent's owners from the definition alone, else `undefined`.
+ *
+ * The linter cannot see the parent fiber's runtime `owners` (they are set at `create()` time, not in the
+ * definition), so it flags only the two STRONG "not-subset" signals — keeping false positives low:
+ *   - a literal array carrying ≥1 concrete address string (a hardcoded external owner list); and
+ *   - any `event.*` reference (caller-supplied — the exact H1 owner-forgery vector).
+ * Owners derived purely from the parent's own `state.*` / `machineId` / `$`-context are assumed in-set and
+ * are NOT flagged.
+ */
+function spawnOwnersRisk(owners) {
+    if (Array.isArray(owners) && owners.some((o) => typeof o === 'string' && o.length > 0)) {
+        return 'a literal array with hardcoded owner address(es)';
+    }
+    const refs = [];
+    collectVarRefs(owners, refs);
+    if (refs.some((r) => r === 'event' || r.startsWith('event.'))) {
+        return "an 'event' reference (caller-supplied owners)";
+    }
+    return undefined;
+}
+/**
+ * rule 6 (H1) — scan a transition effect for `_spawn` directives whose child `owners` are not provably a
+ * SUBSET of the spawning parent's owners. The chain now fails-closed (aborts the transition) under every
+ * `spawnOwnerPolicy` when a child's resolved owners are not ⊆ the parent's. Advisory (warn): the linter
+ * cannot prove the subset statically, so it flags only the strong not-subset signals (see
+ * {@link spawnOwnersRisk}).
+ */
+function lintSpawnOwners(node, app, transition, path) {
+    const out = [];
+    if (Array.isArray(node)) {
+        node.forEach((child, i) => out.push(...lintSpawnOwners(child, app, transition, `${path}[${i}]`)));
+        return out;
+    }
+    if (node === null || typeof node !== 'object')
+        return out;
+    const obj = node;
+    for (const [k, v] of Object.entries(obj)) {
+        if (k === '_spawn' && Array.isArray(v)) {
+            v.forEach((entry, i) => {
+                if (entry && typeof entry === 'object' && !Array.isArray(entry) && 'owners' in entry) {
+                    const reason = spawnOwnersRisk(entry.owners);
+                    if (reason) {
+                        out.push({
+                            app,
+                            transition,
+                            severity: 'warn',
+                            code: LINT_CODES.SPAWN_OWNERS,
+                            message: `_spawn child 'owners' must be a SUBSET of the spawning parent fiber's owners — the chain ` +
+                                `now FAILS-CLOSED (aborts the transition) under every spawnOwnerPolicy if they are not ⊆ the ` +
+                                `parent's (audit H1). This 'owners' is ${reason} and cannot be proven ⊆ the parent. Admit ` +
+                                `later participants via the child's own transitions / authorizedSigners / acceptedCallers ` +
+                                `instead of listing non-parent owners.`,
+                            path: `${path}.${k}[${i}].owners`,
+                        });
+                    }
+                }
+            });
+            // Do not descend into the spawn entry (its nested child definition's owners are relative to that
+            // child, not to this parent).
+            continue;
+        }
+        out.push(...lintSpawnOwners(v, app, transition, `${path}.${k}`));
+    }
+    return out;
+}
+// =============================================================================
 // Top-level entry point
 // =============================================================================
 function appLabel(def) {
@@ -317,6 +418,7 @@ export function lintFiberApp(def) {
         }
         if (t.effect !== undefined) {
             out.push(...lintGuardExpression(t.effect, ctx, `${tPath}.effect`));
+            out.push(...lintSpawnOwners(t.effect, app, transition, `${tPath}.effect`));
         }
         out.push(...lintTransitionStructure(t, app, transition, tPath));
     });

package/dist/types/apps/lending/assets.d.ts

@@ -180,6 +180,11 @@ export interface ApplyMorphismMessage {
 /**
  * Apply a typed morphism (Transfer / Burn / Compose / ...). asset-model.md §7.
  * Transfer = `{ kind: "Transfer", recipient }`; Burn (repay) = `{ kind: "Burn" }`.
+ *
+ * C2 — a `Compose`/`Pool` that folds in a counter-party the signer does NOT own is now rejected on-chain
+ * unless a live `AuthorizeCompose` nonce authorizes it: pass that nonce here (`nonce`) and build the commit
+ * half with {@link createAuthorizeComposePayload}. A same-holder compose (all parts signer-owned) needs no
+ * nonce. `otherAssets` must be duplicate-free and must not include `assetId`.
  */
 export declare function createApplyMorphismPayload(params: ApplyMorphismParams): ApplyMorphismMessage;
 export interface AuthorizeComposeParams {
@@ -198,7 +203,12 @@ export interface AuthorizeComposeMessage {
         targetSequenceNumber: number;
     };
 }
-/** Commit half of a two-party compose. asset-model.md §7/§8. */
+/**
+ * Commit half of a two-party (cross-holder) compose. asset-model.md §7/§8. As of chain finding C2 this
+ * handshake is MANDATORY: a cross-holder `Compose`/`Pool` is rejected unless a matching, unexpired nonce
+ * from this call is live for the counter-party. The composing party then echoes `nonce` in its
+ * `ApplyMorphism`. A same-holder compose (all parts owned by the signer) does not need this.
+ */
 export declare function createAuthorizeComposePayload(params: AuthorizeComposeParams): AuthorizeComposeMessage;
 /**
  * The collateral vault policy: an NFT-like custodial holding (no fungible split) whose

package/dist/types/index.d.ts

@@ -24,6 +24,8 @@ export type { RequestOptions, TransactionStatus, PendingTransaction, PostTransac
 export * from './types.js';
 export * from './ottochain/transaction.js';
 export { dropNulls } from './ottochain/drop-nulls.js';
+export { lintApplyMorphism, MORPHISM_LINT_CODES } from './ottochain/morphism-lint.js';
+export type { LintViolation, LintSeverity } from './ottochain/morphism-lint.js';
 export { buildGenesisManifest, GENESIS_MANIFEST_VERSION } from './ottochain/genesis-manifest.js';
 export type { GenesisManifest, GenesisPackage, GenesisMachineShape, GenesisMessageShape, GenesisFieldShape, GenesisStateMachineDefinition, } from './ottochain/index.js';
 export * from './generated/index.js';
@@ -31,8 +33,10 @@ export { OttoChainError, NetworkError, ValidationError, SigningError, Transactio
 export { DagAddressSchema, PrivateKeySchema, PublicKeySchema, KeyPairSchema, SignatureProofSchema, SignedSchema, TransactionReferenceSchema, CurrencyTransactionValueSchema, CurrencyTransactionSchema, TransferParamsSchema, AgentIdentityRegistrationSchema, PlatformLinkSchema, ContractTermsSchema, ProposeContractRequestSchema, AcceptContractRequestSchema, CompleteContractRequestSchema, validate, validatePrivateKey, validatePublicKey, validateAddress, validateKeyPair, safeParse, assert, type ValidatedKeyPair, type ValidatedSignatureProof, type ValidatedCurrencyTransaction, type ValidatedTransferParams, type ValidatedAgentIdentityRegistration, type ValidatedPlatformLink, type ValidatedProposeContractRequest, type ValidatedAcceptContractRequest, type ValidatedCompleteContractRequest, } from './validation.js';
 export { MetagraphClient as OttoMetagraphClient } from './ottochain/metagraph-client.js';
 export type { MetagraphClientConfig, Checkpoint, SubscribeOptions, FiberStateCallback, Unsubscribe, } from './ottochain/metagraph-client.js';
+export type { SnapshotNotification, NotificationStats, SnapshotRejection } from './ottochain/webhook-notifications.js';
+export { SNAPSHOT_FINALIZED_EVENT } from './ottochain/webhook-notifications.js';
 export { toProtoDefinition, defineFiberApp, constrained, unconstrained, immutable, IMMUTABLE_POLICY, projectFiberPolicy, type ProtoStateMachineDefinition, type FiberAppDefinition, type FiberAppMetadata, type FiberPolicy, type FiberPolicyDials, type ImmutablePolicy, type EffectKind, type SpawnOwnerPolicy, type DependencyMode, type TransferPolicy, type DependencyPolicy, type MigrationAuthority, type UpgradePolicy, type VersionRange, type StateDefinition, type StdStateMetadata, type StateCategory, type Transition, } from './schema/fiber-app.js';
 export { type GuardRule, signerIsParty, signerIsAnyParty, signerInSet, signerIsNotParty, signerHasEntry, assetSignerIs, actorIsSigner, actorInSet, actorHasEntry, signerHasReputation, signerHasRole, signerHasReputationVia, signerHasRoleVia, depInState, actorNotInArray, } from './schema/guards.js';
-export { addDependency, setDependencyActive, transferAsset, triggers, spawn, emit, toFiber, toWallet, RESERVED_EFFECT_KEYS, } from './schema/effects.js';
+export { addDependency, setDependencyActive, transferAsset, triggers, spawn, emit, scriptCall, toFiber, toWallet, RESERVED_EFFECT_KEYS, } from './schema/effects.js';
 export { shieldApp, SHIELDED_POOL_STATE, type ShieldOptions } from './privacy/shield-app.js';
 export type { paths as ApiPaths, operations as ApiOperations, components as ApiComponents, VersionInfo, TransitionFeeEstimate, ScriptFeeEstimate, SubscribeRequest, SubscribeResponse, Subscriber, SubscriberList, } from './openapi.js';

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

@@ -10,10 +10,16 @@ export type { Address, FiberId, StateId, HashValue, FiberOrdinal, SnapshotOrdina
 export { OTTOCHAIN_MESSAGE_TYPES, TOKEN_BEHAVIOR_BITS } from './types.js';
 export type { CurrencySnapshotResponse } from './snapshot.js';
 export { decodeOnChainState, getSnapshotOnChainState, getLatestOnChainState, getLogsForFiber, getEventReceipts, getScriptInvocations, extractOnChainState, } from './snapshot.js';
-export type { Checkpoint, StateProof, FeeEstimate, MetagraphClientConfig, SubscribeOptions, FiberStateCallback, Unsubscribe, } from './metagraph-client.js';
+export type { Checkpoint, StateProof, FeeEstimate, TransitionFeeEstimate, ScriptFeeEstimate, VersionInfo, SubscribeRequest, SubscribeResponse, SubscriberList, MetagraphClientConfig, SubscribeOptions, FiberStateCallback, Unsubscribe, } from './metagraph-client.js';
 export { MetagraphClient } from './metagraph-client.js';
+export type { MptWitnessNode, MptInclusionProof, StateProofVerification } from './state-proof.js';
+export { verifyStateProof, verifyMptInclusion, commitKeyPath } from './state-proof.js';
+export type { SnapshotNotification, NotificationStats, SnapshotRejection } from './webhook-notifications.js';
+export { SNAPSHOT_FINALIZED_EVENT } from './webhook-notifications.js';
 export { createTransitionPayload, createArchivePayload, createInvokeScriptPayload, signTransaction, addTransactionSignature, getPublicKeyForRegistration, createStateMachinePayload, createScriptPayload, createDataTransactionRequest, createAssetPolicyPayload, createMintAssetPayload, createApplyMorphismPayload, createAuthorizeComposePayload, } from './transaction.js';
 export type { CreateStateMachineParams, CreateStateMachineMessage, CreateScriptParams, CreateScriptMessage, DataTransactionRequest, TransitionParams, TransitionStateMachineMessage, ArchiveParams, ArchiveStateMachineMessage, InvokeScriptParams, InvokeScriptMessage, } from './transaction.js';
+export { lintApplyMorphism, MORPHISM_LINT_CODES } from './morphism-lint.js';
+export type { LintViolation, LintSeverity } from './morphism-lint.js';
 export { dropNulls } from './drop-nulls.js';
 export { buildGenesisManifest, GENESIS_MANIFEST_VERSION } from './genesis-manifest.js';
 export type { GenesisManifest, GenesisPackage, MachineShape as GenesisMachineShape, MessageShape as GenesisMessageShape, FieldShape as GenesisFieldShape, StateMachineDefinition as GenesisStateMachineDefinition, } from './genesis-manifest.js';

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/morphism-lint.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Message-layer advisory lint for an {@link ApplyMorphism} transaction (asset-model.md §7; chain
+ * audit finding C2, enforced in `AssetCombiner`).
+ *
+ * Purpose
+ * -------
+ * The definition-scoped {@link ../schema/guard-lint.ts | guard-lint} walks fiber-app DEFINITIONS; it
+ * never sees an `ApplyMorphism` MESSAGE, so a malformed / no-consent `Compose` slips past it. This
+ * linter closes that gap at the transaction-builder layer: hand it the `ApplyMorphism` you are about
+ * to sign and it flags the two classes of C2 mistake the chain rejects.
+ *
+ * The chain rule being mirrored (C2, `Compose`/`Pool` only):
+ *   - `otherAssetIds` must be free of duplicates and must NOT include the source `assetId`
+ *     (the old self/duplicate-inflation path — rejected unconditionally, holder-independent).
+ *   - every counter-party the signer does NOT hold requires a live {@link AuthorizeCompose} `nonce`;
+ *     a same-holder / all-signer-owned compose needs none.
+ *
+ * ERRORS are statically certain (the chain rejects regardless of who holds what). WARNINGS are
+ * heuristic — the signer's holdings/ownership are unknown at build time, so a missing consent nonce
+ * cannot be proven fatal (a same-holder compose is legitimately nonce-less).
+ *
+ * This is a PURE, non-throwing advisory. It is deliberately NOT wired into
+ * {@link createApplyMorphismPayload} (which must stay non-breaking and side-effect-free); call it
+ * explicitly before signing, or in your app's own pre-flight checks.
+ */
+import type { ApplyMorphism } from './types.js';
+import type { LintViolation } from '../schema/guard-lint.js';
+export type { LintViolation, LintSeverity } from '../schema/guard-lint.js';
+/** Stable rule codes for {@link lintApplyMorphism} — referenced by tests and report tooling. */
+export declare const MORPHISM_LINT_CODES: {
+    /** `otherAssetIds` contains a duplicate id (chain rejects — inflation path). */
+    readonly DUPLICATE_OTHER_ID: "morphism-duplicate-other-id";
+    /** `otherAssetIds` includes the source `assetId` (self-composition — chain rejects). */
+    readonly SELF_COMPOSE: "morphism-self-compose";
+    /** `otherAssetIds` is non-empty but `kind` ignores it (not Compose/Pool — likely a mistake). */
+    readonly OTHER_IDS_IGNORED: "morphism-other-ids-ignored";
+    /** Compose/Pool with counter-parties and no consent `nonce` (rejected IF any part is not signer-owned). */
+    readonly COMPOSE_NO_NONCE: "morphism-compose-no-nonce";
+};
+/**
+ * Lint a single {@link ApplyMorphism} message. Pure and non-throwing. Returns every finding
+ * (`error` + `warn`); callers decide the policy (e.g. block on any `error`, surface `warn`s).
+ *
+ * ERRORS (statically certain — the chain rejects unconditionally, holder-independent):
+ *   - {@link MORPHISM_LINT_CODES.DUPLICATE_OTHER_ID} — `otherAssetIds` contains a duplicate id.
+ *   - {@link MORPHISM_LINT_CODES.SELF_COMPOSE} — `otherAssetIds` includes the source `assetId`.
+ *   - {@link MORPHISM_LINT_CODES.OTHER_IDS_IGNORED} — `otherAssetIds` is non-empty but `kind` is not
+ *     `COMPOSE`/`POOL` (the field is ignored for other kinds — a likely authoring mistake).
+ *
+ * WARNINGS (heuristic — holder/ownership unknown at build time):
+ *   - {@link MORPHISM_LINT_CODES.COMPOSE_NO_NONCE} — a `COMPOSE`/`POOL` with a non-empty
+ *     `otherAssetIds` and NO `nonce`. IF any counter-party is not signer-owned the chain rejects it
+ *     (C2); attach the reveal half of an {@link AuthorizeCompose} handshake as `nonce`. A same-holder
+ *     compose (all parts signer-owned) is legitimately nonce-less — hence a warning, not an error.
+ */
+export declare function lintApplyMorphism(msg: ApplyMorphism): LintViolation[];

package/dist/types/ottochain/state-proof.d.ts

@@ -0,0 +1,51 @@
+import type { StateProof } from './metagraph-client.js';
+/** One commitment node of a Merkle-Patricia inclusion witness (wire form, leaf-first). */
+export interface MptWitnessNode {
+    type: 'Leaf' | 'Branch' | 'Extension';
+    contents: {
+        /** Leaf: the path nibbles left below the last branch. */
+        remaining?: string;
+        /** Leaf: sha256(JCS(dropNulls(value))) of the committed record. */
+        dataDigest?: string;
+        /** Branch: nibble → child node digest. */
+        pathsDigest?: Record<string, string>;
+        /** Extension: the shared nibble run. */
+        shared?: string;
+        /** Extension: digest of the child branch. */
+        childDigest?: string;
+    };
+}
+/** The `proof` field of a {@link StateProof}, typed. */
+export interface MptInclusionProof {
+    /** Trie path = hex(utf8(committed key)). */
+    path: string;
+    witness: MptWitnessNode[];
+}
+/** Verification outcome: `ok`, or the first failed binding with a human-readable reason. */
+export type StateProofVerification = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/** The MPT trie path of a committed key — `hex(utf8(key))` (metakit `CommitKey.toHex`). */
+export declare function commitKeyPath(key: string): string;
+/**
+ * Verify a Merkle-Patricia inclusion proof: `record` is committed at `key` under `mptRoot`.
+ *
+ * Pure and side-effect free; never throws on malformed input (returns `{ ok: false }`).
+ */
+export declare function verifyMptInclusion(mptRoot: string, key: string, record: unknown, proof: MptInclusionProof): StateProofVerification;
+/**
+ * Verify a whole {@link StateProof} response for a committed key.
+ *
+ * Checks the trie inclusion of `record` at `key` under the response's `mptRoot` (see
+ * {@link verifyMptInclusion}). The caller supplies the key it EXPECTS (`fiber/<id>`,
+ * `script/<id>`, `asset/<id>`, …) so a proof for some other record cannot be substituted;
+ * the response's own `key` field must agree.
+ *
+ * Trust anchor: `committedRoot` (= `sha256(mptRoot ++ catalogRoot)`) rides in the
+ * consensus-signed snapshot as `calculatedStateProof`; binding `mptRoot` to a snapshot is
+ * the caller's (or a snapshot-following light client's) responsibility.
+ */
+export declare function verifyStateProof(resp: StateProof, expectedKey: string): StateProofVerification;

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

@@ -194,7 +194,13 @@ export declare function createAssetPolicyPayload(params: CreateAssetPolicy): {
 export declare function createMintAssetPayload(params: MintAsset): {
     MintAsset: MintAsset;
 };
-/** Wrap an {@link ApplyMorphism} (apply a typed morphism to an asset instance). */
+/**
+ * Wrap an {@link ApplyMorphism} (apply a typed morphism to an asset instance).
+ *
+ * @see lintApplyMorphism (`./morphism-lint.ts`) — pure, non-throwing advisory that flags the
+ * Compose/Pool mistakes the chain rejects (duplicate / self-referential `otherAssetIds`; a
+ * cross-holder compose with no consent `nonce`). Run it on `params` before signing.
+ */
 export declare function createApplyMorphismPayload(params: ApplyMorphism): {
     ApplyMorphism: ApplyMorphism;
 };

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

@@ -741,15 +741,32 @@ export interface MintAsset {
  * Optional fields carry per-kind directives (recipient for Transfer/Wrap; otherAssetIds + compositeId
  * for Compose; shardIds for Fractionalize; nonce for a commit-reveal symmetric Compose;
  * priorComponents is the Decompose reveal witness).
+ *
+ * C2 — cross-holder Compose/Pool consent is MANDATORY. As of the fiber-engine permissionless-hardening
+ * (chain branch `fix/fiber-engine-permissionless-hardening`, audit finding C2) a `Compose`/`Pool` that
+ * folds in a counter-party the signer does NOT hold is REJECTED (graceful `CombineRejected`) UNLESS a
+ * live {@link AuthorizeCompose} nonce authorizes that counter-party. A SAME-holder compose (every part in
+ * `otherAssetIds` is signer-owned) still needs no nonce. `otherAssetIds` may no longer contain duplicates
+ * or the `assetId` itself (the old self/duplicate-inflation path is rejected).
  */
 export interface ApplyMorphism {
     assetId: string;
     kind: MorphismKind;
     targetSequenceNumber: number;
     recipient?: AssetHolder;
+    /**
+     * Compose/Pool counter-party asset ids folded into the composite. Each id the signer does NOT hold is a
+     * CROSS-HOLDER part and now REQUIRES a live {@link AuthorizeCompose} nonce (see `nonce`) authorizing it
+     * — else the whole morphism is rejected (C2). Must be free of duplicates and must not include `assetId`.
+     */
     otherAssetIds?: string[];
     compositeId?: string;
     shardIds?: string[];
+    /**
+     * The cross-holder Compose consent nonce: the reveal half of the {@link AuthorizeCompose} handshake.
+     * REQUIRED whenever any `otherAssetIds` entry is not signer-owned (C2); omit it only for a same-holder
+     * compose. A nonce-less cross-holder compose is no longer accepted.
+     */
     nonce?: number;
     priorComponents?: ComponentWitness[];
     /** ZkVerify-gated morphism: optional witness a `Governed` morphism's guard reads (see {@link MorphismSpec}). */
@@ -758,6 +775,11 @@ export interface ApplyMorphism {
 /**
  * Authorize a counter-party policy to Compose with this asset (the commit half of the commit-reveal
  * symmetric-compose handshake). `nonce` and `expiresAt` are REQUIRED (no sentinel defaults).
+ *
+ * C2 — this consent is now MANDATORY, not opt-in. A `Compose`/`Pool` ({@link ApplyMorphism}) that consumes
+ * a counter-party the signer does not own is rejected unless a matching, unexpired `AuthorizeCompose` nonce
+ * is live for that counter-party (chain branch `fix/fiber-engine-permissionless-hardening`, finding C2).
+ * The composing party echoes this `nonce` in `ApplyMorphism.nonce`. A same-holder compose needs none.
  */
 export interface AuthorizeCompose {
     assetId: string;

package/dist/types/ottochain/webhook-notifications.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Webhook notification PAYLOAD types — the server-initiated push the chain POSTs to a subscribed
+ * callback, NOT part of the client's request surface.
+ *
+ * These are hand-authored (not generated from the OpenAPI contract) because the push is an OUTBOUND
+ * POST from the metagraph to the subscriber's callback URL — it is not an endpoint the chain's tapir
+ * `ApiEndpoints` serves, so it never appears in `openapi/ottochain-openapi-ml0.json`. They mirror the
+ * chain's shared network DTOs byte-for-byte:
+ *
+ *   chain: modules/models/src/main/scala/xyz/kd5ujc/schema/api/webhooks/Subscriber.scala
+ *          (SnapshotNotification / NotificationStats / SnapshotRejection)
+ *   emit:  modules/l0/.../webhooks/WebhookDispatcher.scala — `notification.asJson.noSpaces`
+ *
+ * Field-shape notes tied to the chain source:
+ * - The dispatcher serializes with a plain derived encoder (`.asJson`, NO `dropNullValues`), so an
+ *   `Option[Long]` that is `None` is emitted as an explicit `null` — the KEY is always present, the
+ *   VALUE is nullable. Hence `number | null` (a required key), not `number | undefined` (an optional
+ *   key). Consumers must handle `null`.
+ * - `Long` → JSON number; `Instant` → ISO-8601 string; `UUID` → string.
+ * - The dispatcher only ever emits `"snapshot.finalized"` today (there is a dead, never-dispatched
+ *   `RejectionNotification`/`transaction.rejected` type in the chain models — deliberately NOT mirrored
+ *   here, because the SDK should model only what is actually sent). Rejections now ride the finalized
+ *   snapshot's `rejections[]`, drained from its committed `RejectionReceipt`s.
+ *
+ * @see modules/models/.../schema/api/webhooks/Subscriber.scala
+ * @see modules/l0/.../webhooks/WebhookDispatcher.scala
+ * @packageDocumentation
+ */
+/** The only event the chain's `WebhookDispatcher` currently emits. */
+export declare const SNAPSHOT_FINALIZED_EVENT: "snapshot.finalized";
+/**
+ * Aggregate counters for the finalized snapshot, mirrors chain `NotificationStats`.
+ */
+export interface NotificationStats {
+    /** Number of data updates processed into this snapshot. */
+    updatesProcessed: number;
+    /** Count of active state-machine fibers after this snapshot. */
+    stateMachinesActive: number;
+    /** Count of active script fibers after this snapshot. */
+    scriptsActive: number;
+    /** Number of updates rejected while combining this snapshot (== `rejections.length`). */
+    rejectedCount: number;
+}
+/**
+ * A single post-finalization rejection, batched onto the `snapshot.finalized` notification. Drained
+ * from the committed snapshot's `RejectionReceipt`s, so it reflects committed state (not a pre-combine
+ * guess). Mirrors chain `SnapshotRejection`.
+ */
+export interface SnapshotRejection {
+    /** The rejected update's type, e.g. `"TransitionStateMachine"`, `"CreateStateMachine"`. */
+    updateType: string;
+    /** UUID of the target fiber. */
+    fiberId: string;
+    /**
+     * The transition's target sequence number, or `null` for non-sequenced updates. Chain
+     * `Option[Long]`, emitted as an explicit `null` when absent (dispatcher does not drop nulls).
+     */
+    targetSequenceNumber: number | null;
+    /**
+     * The fiber's actual sequence number at rejection time (for a sequence mismatch), or `null`. Chain
+     * `Option[Long]`, emitted as an explicit `null` when absent.
+     */
+    actualSequenceNumber: number | null;
+    /** Human-readable rejection reason (the combiner's `CombineRejected` code/message). */
+    reason: string;
+    /** Hash of the signed update, for correlation with a submitted transaction. */
+    updateHash: string;
+}
+/**
+ * The payload POSTed to a subscribed webhook callback when a snapshot finalizes — the confirm TICK.
+ * Mirrors chain `SnapshotNotification`.
+ *
+ * There is NO per-update "accepted" event: an update is accepted iff its `updateHash` lands in a
+ * finalized snapshot AND is absent from every `rejections[]` of the snapshots up to that ordinal.
+ */
+export interface SnapshotNotification {
+    /** Always `"snapshot.finalized"`. */
+    event: typeof SNAPSHOT_FINALIZED_EVENT;
+    /** The finalized snapshot ordinal. Chain `Long`. */
+    ordinal: number;
+    /** The finalized snapshot hash. */
+    hash: string;
+    /** ISO-8601 dispatch timestamp. Chain `Instant`. */
+    timestamp: string;
+    /** The metagraph token identifier this notification is for. */
+    metagraphId: string;
+    /** Aggregate counters for the snapshot. */
+    stats: NotificationStats;
+    /** Updates rejected while combining this snapshot (empty if none). */
+    rejections: SnapshotRejection[];
+}

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

@@ -108,11 +108,20 @@ export declare const triggers: (ts: {
  * 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.
+ * H1 constraint — child `owners` MUST be a SUBSET of the SPAWNING PARENT fiber's `owners`. As of the
+ * fiber-engine permissionless-hardening (chain branch `fix/fiber-engine-permissionless-hardening`, audit
+ * finding H1) the chain FAILS-CLOSED — it aborts the whole transition under EVERY `spawnOwnerPolicy` — if
+ * a `_spawn`'s resolved child `owners` are not ⊆ the parent's owners. Assigning arbitrary, unsigned owners
+ * (the old "auction owned by all its bidders" pattern, where the bidders are NOT parent owners) is no
+ * longer valid: those events are not silently rejected, the spawn itself is rejected.
+ *
+ * So DO NOT try to enroll later participants by listing them here. A spawned child's transitions are gated
+ * by `owners ∪ authorizedSigners` for the DIRECT (wallet-signed) path; admit additional drivers through
+ * the child's OWN transitions (`authorizedSigners`), or drive it via the cascade (`_triggers`) subject to
+ * its `acceptedCallers` — never by widening `owners` beyond the parent's set. `owners` may be a literal id
+ * array or an expression (e.g. `{ var: "state.owners" }` — resolve it WITHIN the parent's owners), but a
+ * value the parent does not own (e.g. `{ var: "event.auctionOwners" }` supplied by the caller) will be
+ * rejected on-chain. `childId` / `initialData` likewise accept literals or expressions.
  */
 export declare const spawn: (ds: {
     childId: JsonLogicValue;
@@ -131,6 +140,31 @@ export declare const emit: (es: {
     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)