@ottochain/sdk 2.3.0 → 2.5.0

package/dist/cjs/ottochain/transaction.js

@@ -6,11 +6,33 @@
  * self-signed mode, where clients sign their own transactions.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getPublicKeyForRegistration = exports.addTransactionSignature = exports.createDataTransactionRequest = exports.signTransaction = exports.createInvokeScriptPayload = exports.createScriptPayload = exports.createArchivePayload = exports.createTransitionPayload = exports.createStateMachinePayload = void 0;
+exports.createStateMachinePayload = createStateMachinePayload;
+exports.createTransitionPayload = createTransitionPayload;
+exports.createArchivePayload = createArchivePayload;
+exports.createScriptPayload = createScriptPayload;
+exports.createInvokeScriptPayload = createInvokeScriptPayload;
+exports.createAssetPolicyPayload = createAssetPolicyPayload;
+exports.createMintAssetPayload = createMintAssetPayload;
+exports.createApplyMorphismPayload = createApplyMorphismPayload;
+exports.createAuthorizeComposePayload = createAuthorizeComposePayload;
+exports.createPublishMachineVersionPayload = createPublishMachineVersionPayload;
+exports.createUpgradeFiberPayload = createUpgradeFiberPayload;
+exports.signTransaction = signTransaction;
+exports.createDataTransactionRequest = createDataTransactionRequest;
+exports.addTransactionSignature = addTransactionSignature;
+exports.getPublicKeyForRegistration = getPublicKeyForRegistration;
 const metagraph_sdk_1 = require("@constellation-network/metagraph-sdk");
+const signing_js_1 = require("../signing.js");
 /**
  * Create a new state machine fiber payload.
  *
+ * @remarks
+ * `params.definition` is signed VERBATIM. Pass the output of `toProtoDefinition(def)` (the
+ * allowlisted wire shape) — NOT a raw `FiberAppDefinition`: extra authoring fields
+ * (`createSchema` / `stateSchema` / `eventSchemas` / per-transition `emits`) would be signed
+ * but re-encoded away by the chain, diverging the canonical → opaque `InvalidSignature`.
+ * See `tests/ottochain/signing-parity.test.ts`.
+ *
  * @param params - State machine creation parameters
  * @returns A CreateStateMachine message ready for signing
  *
@@ -37,7 +59,6 @@ function createStateMachinePayload(params) {
         },
     };
 }
-exports.createStateMachinePayload = createStateMachinePayload;
 /**
  * Create a transition payload ready for signing.
  *
@@ -66,7 +87,6 @@ function createTransitionPayload(params) {
         },
     };
 }
-exports.createTransitionPayload = createTransitionPayload;
 /**
  * Create an archive payload ready for signing.
  *
@@ -81,7 +101,6 @@ function createArchivePayload(params) {
         },
     };
 }
-exports.createArchivePayload = createArchivePayload;
 /**
  * Create a new script fiber payload.
  *
@@ -100,7 +119,7 @@ exports.createArchivePayload = createArchivePayload;
  *     },
  *   },
  *   initialState: { value: 0 },
- *   accessControl: { type: 'open' },
+ *   accessControl: { Public: {} },
  * });
  * const signed = await signTransaction(script, privateKey);
  * ```
@@ -111,11 +130,10 @@ function createScriptPayload(params) {
             fiberId: params.fiberId,
             scriptProgram: params.scriptProgram,
             initialState: params.initialState ?? null,
-            accessControl: params.accessControl ?? { type: 'open' },
+            accessControl: params.accessControl ?? { Public: {} },
         },
     };
 }
-exports.createScriptPayload = createScriptPayload;
 /**
  * Create an invoke script payload ready for signing.
  *
@@ -132,13 +150,49 @@ function createInvokeScriptPayload(params) {
         },
     };
 }
-exports.createInvokeScriptPayload = createInvokeScriptPayload;
+// ============================================================================
+// Asset Operations (asset-model.md §7)
+// ============================================================================
+//
+// Thin typed wrappers: the chain message types ({@link CreateAssetPolicy}, etc.) already model
+// every field (required vs `Option`), so these builders just apply the `{ MessageName: ... }`
+// envelope, for API parity with the state-machine/script `create*Payload` helpers. Sign the result
+// with {@link signTransaction} (the canonical `JCS(dropNulls)` path drops any omitted optionals).
+/** Wrap a {@link CreateAssetPolicy} (publish an asset-policy package version). */
+function createAssetPolicyPayload(params) {
+    return { CreateAssetPolicy: params };
+}
+/** Wrap a {@link MintAsset} (mint a new asset instance against a resolved policy version). */
+function createMintAssetPayload(params) {
+    return { MintAsset: params };
+}
+/** Wrap an {@link ApplyMorphism} (apply a typed morphism to an asset instance). */
+function createApplyMorphismPayload(params) {
+    return { ApplyMorphism: params };
+}
+/** Wrap an {@link AuthorizeCompose} (commit half of the symmetric-compose handshake). */
+function createAuthorizeComposePayload(params) {
+    return { AuthorizeCompose: params };
+}
+/** Wrap a {@link PublishMachineVersion} (create-or-append a STATE-MACHINE registry version). */
+function createPublishMachineVersionPayload(params) {
+    return { PublishMachineVersion: params };
+}
+/** Wrap an {@link UpgradeFiber} (re-pin a fiber to another registered version of the SAME package). */
+function createUpgradeFiberPayload(params) {
+    return { UpgradeFiber: params };
+}
 /**
  * Sign a transaction payload for self-signed mode.
  *
  * This creates a Signed<T> object with the exact format expected by the bridge's
  * `/agent/transition` endpoint when using self-signed mode.
  *
+ * The signature is computed over the null-dropped canonical bytes (null
+ * object fields removed recursively, array nulls preserved, then RFC 8785),
+ * matching metakit's content-hash rule. Explicit-null and absent optional
+ * fields therefore produce identical signatures.
+ *
  * @param message - The message to sign (e.g., from createTransitionPayload)
  * @param privateKey - The private key in hex format (64 characters)
  * @returns A signed object ready for submission to the bridge
@@ -171,13 +225,12 @@ exports.createInvokeScriptPayload = createInvokeScriptPayload;
  * ```
  */
 async function signTransaction(message, privateKey) {
-    const proof = await (0, metagraph_sdk_1.signDataUpdate)(message, privateKey);
+    const proof = await (0, signing_js_1.signDataUpdate)(message, privateKey);
     return {
         value: message,
         proofs: [proof],
     };
 }
-exports.signTransaction = signTransaction;
 /**
  * Wrap a signed transaction in the DataTransactionRequest format
  * expected by tessellation's DL1 `/data` endpoint.
@@ -202,25 +255,26 @@ exports.signTransaction = signTransaction;
 function createDataTransactionRequest(signed) {
     return { data: signed, fee: null };
 }
-exports.createDataTransactionRequest = createDataTransactionRequest;
 /**
  * Add an additional signature to a signed transaction.
  *
  * Use this for multi-signature scenarios where multiple parties
  * need to sign the same transaction.
  *
+ * The new signature is computed over the null-dropped canonical bytes,
+ * matching metakit's content-hash rule (see {@link signTransaction}).
+ *
  * @param signed - The already-signed transaction
  * @param privateKey - Additional signer's private key
  * @returns Transaction with additional signature
  */
 async function addTransactionSignature(signed, privateKey) {
-    const newProof = await (0, metagraph_sdk_1.signDataUpdate)(signed.value, privateKey);
+    const newProof = await (0, signing_js_1.signDataUpdate)(signed.value, privateKey);
     return {
         value: signed.value,
         proofs: [...signed.proofs, newProof],
     };
 }
-exports.addTransactionSignature = addTransactionSignature;
 /**
  * Get the public key ID from a private key in the format expected by registration.
  *
@@ -248,4 +302,3 @@ exports.addTransactionSignature = addTransactionSignature;
 function getPublicKeyForRegistration(privateKey) {
     return (0, metagraph_sdk_1.getPublicKeyId)(privateKey);
 }
-exports.getPublicKeyForRegistration = getPublicKeyForRegistration;

package/dist/cjs/ottochain/types.js

@@ -9,7 +9,15 @@
  * @packageDocumentation
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OTTOCHAIN_MESSAGE_TYPES = void 0;
+exports.OTTOCHAIN_MESSAGE_TYPES = exports.TOKEN_BEHAVIOR_BITS = void 0;
+/** Bit weights for {@link TokenBehavior} (T=16, S=8, C=4, E=2, G=1). */
+exports.TOKEN_BEHAVIOR_BITS = {
+    transferable: 16,
+    splittable: 8,
+    combinable: 4,
+    expirable: 2,
+    governable: 1,
+};
 /**
  * Names of all valid OttochainMessage types.
  * Use this for runtime validation (e.g., in API routes).
@@ -21,7 +29,13 @@ exports.OTTOCHAIN_MESSAGE_TYPES = [
     'UpgradeFiber',
     'CreateScript',
     'InvokeScript',
-    'PublishVersion',
+    'UpgradeScript',
+    'PublishMachineVersion',
+    'PublishScriptVersion',
     'SetVersionStatus',
     'RegisterAlias',
+    'CreateAssetPolicy',
+    'MintAsset',
+    'ApplyMorphism',
+    'AuthorizeCompose',
 ];

package/dist/cjs/privacy/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vickreyAuctionDef = exports.shieldedSealedBidDef = exports.sealedBidAccountDef = exports.SHIELDED_POOL_STATE = exports.shieldApp = void 0;
+/**
+ * Privacy: shield any fiber app into a zk-jlvm-shielded private-state pool.
+ * See docs/design/zk-private-contract-state-rfc.md.
+ */
+var shield_app_js_1 = require("./shield-app.js");
+Object.defineProperty(exports, "shieldApp", { enumerable: true, get: function () { return shield_app_js_1.shieldApp; } });
+Object.defineProperty(exports, "SHIELDED_POOL_STATE", { enumerable: true, get: function () { return shield_app_js_1.SHIELDED_POOL_STATE; } });
+var sealed_bid_js_1 = require("./sealed-bid.js");
+Object.defineProperty(exports, "sealedBidAccountDef", { enumerable: true, get: function () { return sealed_bid_js_1.sealedBidAccountDef; } });
+Object.defineProperty(exports, "shieldedSealedBidDef", { enumerable: true, get: function () { return sealed_bid_js_1.shieldedSealedBidDef; } });
+Object.defineProperty(exports, "vickreyAuctionDef", { enumerable: true, get: function () { return sealed_bid_js_1.vickreyAuctionDef; } });

package/dist/cjs/privacy/sealed-bid.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * Sealed-bid (Vickrey) auction — the worked example for the privacy stack.
+ *
+ * Two pieces (RFC §4):
+ *  1. `sealedBidAccountDef` — the PRIVATE per-bidder bid. `shieldApp` turns it into a shielded
+ *     pool (`shieldedSealedBidDef`): a bidder commits a bid note and proves it well-formed with a
+ *     zk-jlvm-shielded Groth16 proof, so the amount stays sealed *until the deadline*. This is the
+ *     mechanical per-instance / single-owner case.
+ *  2. `vickreyAuctionDef` — the PUBLIC settlement (reveal-then-tally). After the deadline bidders
+ *     open their notes; the combine computes winner = argmax and clearingPrice = second-highest
+ *     (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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vickreyAuctionDef = exports.sealedBidAccountDef = void 0;
+exports.shieldedSealedBidDef = shieldedSealedBidDef;
+const fiber_app_js_1 = require("../schema/fiber-app.js");
+const shield_app_js_1 = require("./shield-app.js");
+// ── 1. The private bid (base app, shielded by shieldApp) ──────────────────────
+/** The per-bidder PRIVATE state: a bid note `{ amount, bidder, nonce }`. */
+exports.sealedBidAccountDef = (0, fiber_app_js_1.defineFiberApp)({
+    metadata: {
+        name: 'SealedBidAccount',
+        app: 'markets',
+        type: 'sealed-bid-account',
+        version: '1.0.0',
+        description: "A single bidder's sealed bid (private amount). Shielded via shieldApp.",
+    },
+    stateSchema: {
+        properties: {
+            amount: { type: 'number', description: 'the (private) bid amount' },
+            bidder: { type: 'address' },
+            nonce: { type: 'number', description: 'per-note randomness; keeps the commitment hiding' },
+        },
+    },
+    eventSchemas: {
+        place_bid: {
+            description: 'Set the sealed bid amount',
+            required: ['amount'],
+            properties: { amount: { type: 'number', minimum: 1 } },
+        },
+    },
+    states: {
+        OPEN: { id: 'OPEN', isFinal: false, metadata: { label: 'Open', description: 'No bid yet', category: 'initial' } },
+        BID: { id: 'BID', isFinal: false, metadata: { label: 'Bid', description: 'Bid committed', category: 'active' } },
+    },
+    initialState: 'OPEN',
+    transitions: [
+        {
+            // This effect is what the zk-jlvm-shielded circuit runs in-zkVM; `exprHash` pins it.
+            from: 'OPEN',
+            to: 'BID',
+            eventName: 'place_bid',
+            guard: { '>': [{ var: 'event.amount' }, 0] },
+            effect: { merge: [{ var: 'state' }, { amount: { var: 'event.amount' } }] },
+            dependencies: [],
+        },
+    ],
+});
+/**
+ * The shielded sealed-bid pool. `vkey`/`exprHash` come from the built zk-jlvm-shielded circuit
+ * (these are placeholders until the circuit's program vkey + the keccak of the `place_bid` effect
+ * are wired in by the genesis/build step).
+ */
+function shieldedSealedBidDef(opts) {
+    return (0, shield_app_js_1.shieldApp)(exports.sealedBidAccountDef, opts);
+}
+// ── 2. The public Vickrey settlement ──────────────────────────────────────────
+/**
+ * Public reveal-then-tally settlement. `reveal` appends an opened bid (in a full build the opening
+ * is checked against the recorded commitment in the shielded pool); `settle` computes the winner
+ * and the Vickrey (second-price) clearing price over the revealed bids in one reduce.
+ */
+exports.vickreyAuctionDef = (0, fiber_app_js_1.defineFiberApp)({
+    metadata: {
+        name: 'VickreyAuction',
+        app: 'markets',
+        type: 'vickrey-auction',
+        version: '1.0.0',
+        description: 'Sealed-bid second-price auction: public reveal-then-tally over shielded bids.',
+        crossReferences: { bidPool: 'the ShieldedSealedBidAccount pool holding the sealed bids' },
+    },
+    createSchema: {
+        required: ['seller', 'deadline'],
+        properties: {
+            seller: { type: 'address', immutable: true },
+            deadline: { type: 'timestamp', immutable: true },
+        },
+    },
+    stateSchema: {
+        properties: {
+            seller: { type: 'address', immutable: true },
+            deadline: { type: 'timestamp', immutable: true },
+            status: { type: 'string', computed: true },
+            revealed: { type: 'array', computed: true, description: 'opened bids [{bidder, amount}]' },
+            winner: { type: 'address', computed: true },
+            clearingPrice: { type: 'number', computed: true, description: 'second-highest bid (Vickrey)' },
+        },
+    },
+    eventSchemas: {
+        reveal: {
+            description: 'Open a sealed bid after the deadline',
+            required: ['bidder', 'amount'],
+            properties: { bidder: { type: 'address' }, amount: { type: 'number', minimum: 1 } },
+        },
+        settle: { description: 'Tally the revealed bids (winner + second price)' },
+    },
+    states: {
+        OPEN: {
+            id: 'OPEN',
+            isFinal: false,
+            metadata: { label: 'Open', description: 'Bidding (sealed)', category: 'initial' },
+        },
+        REVEAL: {
+            id: 'REVEAL',
+            isFinal: false,
+            metadata: { label: 'Reveal', description: 'Opening bids', category: 'active' },
+        },
+        SETTLED: {
+            id: 'SETTLED',
+            isFinal: true,
+            metadata: { label: 'Settled', description: 'Winner + price set', category: 'terminal' },
+        },
+    },
+    initialState: 'OPEN',
+    transitions: [
+        {
+            from: 'OPEN',
+            to: 'REVEAL',
+            eventName: 'reveal',
+            guard: { '>=': [{ var: '$timestamp' }, { var: 'state.deadline' }] },
+            effect: {
+                merge: [
+                    { var: 'state' },
+                    {
+                        status: 'REVEAL',
+                        revealed: {
+                            cat: [{ var: 'state.revealed' }, [{ bidder: { var: 'event.bidder' }, amount: { var: 'event.amount' } }]],
+                        },
+                    },
+                ],
+            },
+            dependencies: [],
+        },
+        {
+            from: 'REVEAL',
+            to: 'REVEAL',
+            eventName: 'reveal',
+            guard: { '>=': [{ var: '$timestamp' }, { var: 'state.deadline' }] },
+            effect: {
+                merge: [
+                    { var: 'state' },
+                    {
+                        revealed: {
+                            cat: [{ var: 'state.revealed' }, [{ bidder: { var: 'event.bidder' }, amount: { var: 'event.amount' } }]],
+                        },
+                    },
+                ],
+            },
+            dependencies: [],
+        },
+        {
+            // Vickrey tally: fold the revealed bids tracking (max, second, winner).
+            from: 'REVEAL',
+            to: 'SETTLED',
+            eventName: 'settle',
+            guard: { '>': [{ reduce: [{ var: 'state.revealed' }, { '+': [{ var: 'accumulator' }, 1] }, 0] }, 0] },
+            effect: {
+                merge: [
+                    { var: 'state' },
+                    {
+                        status: 'SETTLED',
+                        settledAt: { var: '$timestamp' },
+                        winner: {
+                            var: ['tally.winner', null],
+                        },
+                        clearingPrice: { var: ['tally.second', 0] },
+                        // compute the tally once and expose it for the two fields above
+                        tally: {
+                            reduce: [
+                                { var: 'state.revealed' },
+                                {
+                                    if: [
+                                        { '>': [{ var: 'current.amount' }, { var: 'accumulator.max' }] },
+                                        {
+                                            max: { var: 'current.amount' },
+                                            second: { var: 'accumulator.max' },
+                                            winner: { var: 'current.bidder' },
+                                        },
+                                        {
+                                            if: [
+                                                { '>': [{ var: 'current.amount' }, { var: 'accumulator.second' }] },
+                                                {
+                                                    max: { var: 'accumulator.max' },
+                                                    second: { var: 'current.amount' },
+                                                    winner: { var: 'accumulator.winner' },
+                                                },
+                                                { var: 'accumulator' },
+                                            ],
+                                        },
+                                    ],
+                                },
+                                { max: 0, second: 0, winner: null },
+                            ],
+                        },
+                    },
+                ],
+            },
+            dependencies: [],
+        },
+    ],
+});

package/dist/cjs/privacy/shield-app.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * shieldApp — turn a fiber app into a PRIVATE-state pool.
+ *
+ * Given a base {@link FiberAppDefinition} (the app whose state + transition you want to keep
+ * private), `shieldApp` returns a new `FiberAppDefinition` for a "shielded pool" Machine fiber.
+ * The pool's state is PUBLIC scaffolding only — the spent-nullifier set, the commitment log, and
+ * the set of valid anchors — while the app's real state lives off-chain in a note committed to
+ * the tree. Each app transition is carried out off-chain and attested by a single
+ * `zk-jlvm-shielded` Groth16 proof; the on-chain combine just verifies the proof, rejects an
+ * already-spent nullifier, and records the new commitment.
+ *
+ * Division of labour (see ottochain-sdk RFC docs/design/zk-private-contract-state-rfc.md):
+ *  - the CIRCUIT proves membership ∧ authorization ∧ `jlvm-core` effect ∧ new commitment;
+ *  - this GUARD (combine) verifies the proof, pins which app logic ran (`exprHash`), checks the
+ *    anchor is recent, and checks the nullifier is fresh — all combiner-only (CLAUDE.md);
+ *  - block-validity stays structural (proof / publicValues present + hex).
+ *
+ * It uses NO new metakit opcode: `groth16_verify` verifies the proof, and the four-`bytes32`
+ * public values (`anchor`, `nullifier`, `newCommitment`, `exprHash`) are extracted from the
+ * VERIFIED `publicValues` string with fixed-offset `substr` — slicing the verified bytes IS the
+ * binding (§8.1).
+ *
+ * NOTE on cost: the note model rehashes the whole state each transition, so proving cost is
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SHIELDED_POOL_STATE = void 0;
+exports.shieldApp = shieldApp;
+const fiber_app_js_1 = require("../schema/fiber-app.js");
+/**
+ * Field extractors over the abi-encoded `JlvmTransitionPublicValues` — four static `bytes32`
+ * `[anchor | nullifier | newCommitment | exprHash]`, a fixed 128-byte (256 hex char) layout with
+ * NO dynamic arrays. `publicValues` is the 0x-prefixed hex from the prover, so each field is 64
+ * hex chars starting at: anchor=2, nullifier=66, newCommitment=130, exprHash=194.
+ */
+const pvField = (publicValues, hexOffset) => ({
+    substr: [publicValues, hexOffset, 64],
+});
+/** Standard public state every shielded pool carries (the rest of the app state is private/off-chain). */
+exports.SHIELDED_POOL_STATE = {
+    vkey: { type: 'hash', immutable: true },
+    exprHash: { type: 'hash', immutable: true },
+    rootWindow: { type: 'integer', immutable: true },
+    currentRoot: { type: 'hash', computed: true },
+    knownRoots: { type: 'array', computed: true, description: 'rolling window of valid anchors (hex)' },
+    nullifiers: { type: 'array', computed: true, description: 'spent set (hex); monotonic — see RFC §5.3' },
+    commitments: { type: 'array', computed: true, description: 'append-only log of output commitments (hex)' },
+    leafCount: { type: 'integer', computed: true, default: 0 },
+    transitions: { type: 'integer', computed: true, default: 0 },
+};
+/**
+ * Build the shielded-pool variant of `base`.
+ *
+ * @param base  the app being shielded (used for naming + to document the pinned logic).
+ * @param opts  the circuit vkey + the pinned `exprHash` + the anchor window.
+ */
+function shieldApp(base, opts) {
+    const publicValues = { var: 'event.publicValues' };
+    const anchor = pvField(publicValues, 2);
+    const nullifier = pvField(publicValues, 66);
+    const newCommitment = pvField(publicValues, 130);
+    const exprHash = pvField(publicValues, 194);
+    // GUARD (combine): all stateful, combiner-only.
+    const guard = {
+        and: [
+            // 1. the proof verifies against the pool's pinned vkey over EXACTLY these public bytes
+            { groth16_verify: [{ var: 'state.vkey' }, publicValues, { var: 'event.proof' }] },
+            // 2. it ran the app logic this pool pins (binds which effect produced the transition)
+            { '===': [exprHash, { var: 'state.exprHash' }] },
+            // 3. the spent note was proven under an anchor we still honor
+            { in: [anchor, { var: 'state.knownRoots' }] },
+            // 4. inter-transfer double-spend guard: the nullifier is not already spent
+            { none: [{ var: 'state.nullifiers' }, { '===': [{ var: '' }, nullifier] }] },
+        ],
+    };
+    // EFFECT (combine): spend the nullifier, record the new commitment, advance counters.
+    // Root advancement (turning the appended commitment into the next anchor) is wallet/Bridge-side
+    // per RFC §6.2 / §10; the chain records the commitment + nullifier here.
+    const effect = {
+        merge: [
+            { var: 'state' },
+            {
+                nullifiers: { cat: [{ var: 'state.nullifiers' }, [nullifier]] },
+                commitments: { cat: [{ var: 'state.commitments' }, [newCommitment]] },
+                leafCount: { '+': [{ var: 'state.leafCount' }, 1] },
+                transitions: { '+': [{ var: 'state.transitions' }, 1] },
+                lastTransitionAt: { var: '$ordinal' },
+            },
+        ],
+    };
+    return (0, fiber_app_js_1.defineFiberApp)({
+        metadata: {
+            name: `Shielded${base.metadata.name}`,
+            app: 'privacy',
+            type: `shielded-${base.metadata.type}`,
+            version: base.metadata.version,
+            description: `Shielded (zk-jlvm-shielded) variant of ${base.metadata.name}: private state transitions ` +
+                `verified by a Groth16 proof; the nullifier set + anchors are public pool state.`,
+        },
+        createSchema: {
+            required: ['vkey', 'exprHash'],
+            properties: {
+                vkey: { type: 'hash', immutable: true, default: opts.vkey },
+                exprHash: { type: 'hash', immutable: true, default: opts.exprHash },
+                rootWindow: { type: 'integer', immutable: true, default: opts.rootWindow ?? 64 },
+            },
+        },
+        stateSchema: { properties: { ...exports.SHIELDED_POOL_STATE } },
+        eventSchemas: {
+            transition: {
+                description: `A private state transition of ${base.metadata.name}, attested by a zk-jlvm-shielded Groth16 proof.`,
+                required: ['proof', 'publicValues'],
+                properties: {
+                    proof: { type: 'string', description: 'Groth16 proof bytes (0x hex)' },
+                    publicValues: { type: 'string', description: 'abi-encoded JlvmTransitionPublicValues (4×bytes32, 0x hex)' },
+                },
+            },
+        },
+        states: {
+            ACTIVE: {
+                id: 'ACTIVE',
+                isFinal: false,
+                metadata: { label: 'Active', description: 'Pool accepts shielded transitions', category: 'active' },
+            },
+        },
+        initialState: 'ACTIVE',
+        transitions: [{ from: 'ACTIVE', to: 'ACTIVE', eventName: 'transition', guard, effect, dependencies: [] }],
+    });
+}