@ottochain/sdk 2.6.0 → 2.7.0

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;

package/dist/types/schema/guard-lint.d.ts

@@ -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`.
@@ -58,6 +63,7 @@ export declare const LINT_CODES: {
     readonly WITNESS_IN_TRANSITION: "witness-in-transition";
     readonly DROPPED_DIRECTIVE: "dropped-directive";
     readonly LEADING_DOT_VAR: "leading-dot-var";
+    readonly SPAWN_OWNERS: "spawn-owners";
 };
 /**
  * The ONLY `$`-prefixed keys the engine injects (`ReservedKeys`). Anything else

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ottochain/sdk",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "TypeScript SDK for ottochain metagraph operations - signing, encoding, and network interactions",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -148,12 +148,12 @@
   },
   "devDependencies": {
     "@babel/preset-env": "^7.29.7",
-    "@commitlint/cli": "^21.1.0",
-    "@commitlint/config-conventional": "^21.1.0",
+    "@commitlint/cli": "^21.2.0",
+    "@commitlint/config-conventional": "^21.2.0",
     "@eslint/js": "^10.0.1",
     "@jest/globals": "^30.3.0",
     "@types/jest": "^30.0.0",
-    "@types/node": "^26.0.1",
+    "@types/node": "^26.1.0",
     "@typescript-eslint/eslint-plugin": "^8.62.0",
     "@typescript-eslint/parser": "^8.62.0",
     "eslint": "^10.6.0",
@@ -161,8 +161,8 @@
     "openapi-typescript": "^7.13.0",
     "prettier": "^3.9.1",
     "ts-jest": "29.4.9",
-    "ts-proto": "^2.11.9",
-    "typedoc": "^0.28.19",
+    "ts-proto": "^2.12.0",
+    "typedoc": "^0.28.20",
     "typescript": "^6.0.3"
   },
   "peerDependencies": {