@midnight-ntwrk/midnight-js-protocol 5.0.0-beta.8 → 5.0.0-rc.1

package/dist/engine.js

@@ -1,6 +1,15 @@
 import * as ledgerV9 from '@midnightntwrk/ledger-v9';
-import { ComposeOptionError, Ledger8RuntimeInvalidError, DownConvertFailedError, MerkleNotRehashedError, UnknownLedger8AxisError, Ledger8InstanceMismatchError } from './errors.js';
-import { a as assembleCallPrototype, e as executeConstructor } from './shared/deploy-D6yyn9P7.js';
+import { ComposeOptionError, PROTOCOL_ERROR_CODES, ComposeFailedError, DownConvertFailedError } from './errors.js';
+import { a as assembleCallPrototype, i as isContractBalance, d as describeValue } from './shared/assemble-call-BB1yZMS6.js';
+import * as Contract from '@midnight-ntwrk/compact-js/effect/Contract';
+import * as ContractConfigurationError from '@midnight-ntwrk/compact-js/effect/ContractConfigurationError';
+import { ContractExecutable, CompiledContract, ZKConfiguration, ZKConfigurationReadError } from '@midnight-ntwrk/compact-js/v8/effect';
+import * as CoinPublicKey from '@midnight-ntwrk/platform-js/effect/CoinPublicKey';
+import * as Configuration from '@midnight-ntwrk/platform-js/effect/Configuration';
+import * as PlatformContractAddress from '@midnight-ntwrk/platform-js/effect/ContractAddress';
+import * as SigningKey from '@midnight-ntwrk/platform-js/effect/SigningKey';
+import * as glue from 'compact-runtime-ledger8';
+import { Effect, Layer, Exit, Cause, Option, Clock } from 'effect';
 import '@midnight-ntwrk/compact-js';
 
 /*
@@ -20,31 +29,16 @@ import '@midnight-ntwrk/compact-js';
 /**
  * Re-expresses a retained-era contract's entry points as a CURRENT-era contract state.
  *
- * WHY THIS EXISTS. The fork does not rewrite a contract's stored state: a contract deployed before
- * it and dormant across it is served, indefinitely, carrying its retained-era envelope. The current
- * ledger's composer cannot deserialize those bytes — it accepts only its own envelope — so a
- * keep-state call had nothing to hand it and could not be composed at all.
- *
- * WHAT THE COMPOSER ACTUALLY WANTS. The `contractState` a composition takes is NOT the state being
- * proven. `assembleCallPrototype` uses it for exactly one thing: looking up the `ContractOperation`
- * for the circuit, to read its verifier key. The state the call is bound to travels separately, as
- * the transcript's `preState`. So what has to cross the era boundary here is the OPERATION
- * REGISTRY, not the state.
- *
- * WHY THIS IS FAITHFUL, NOT A SUBSTITUTION. The verifier keys come from the chain's own state, read
- * through the retained decoder, and the caller has already checked its local artifact against them.
- * The current ledger models retained-era operations natively — `ContractOperationVersion` carries a
- * `'v3'` arm precisely for them — so a key preserved across the fork is a value this ledger is built
- * to hold. Nothing is minted here: every key written out is one the chain already holds.
- *
- * The primary state is deliberately left at its default. A caller that needed the state itself would
- * be reading it from {@link ContractStatePojo.state}, not from this registry.
+ * What crosses the era boundary here is the OPERATION REGISTRY, not the state. The primary state is
+ * deliberately left at its default: a caller that needs the state itself reads it from
+ * {@link ContractStatePojo.state}.
  *
  * @param entryPoints The entry points a retained-era contract state declared, as the retained
  * decoder read them.
  * @returns The serialized current-era contract state, carrying those entry points and their keys.
- * @throws ComposeOptionError if no entry point carries a key, since the registry would then answer
- * for nothing and the composer's own refusal would name a circuit rather than the empty state.
+ * @throws ComposeOptionError if no entry point carries a key.
+ * @see {@link CrossEraOperationRegistry} for why re-expressing the operations is faithful rather
+ * than a substitution, and why the empty registry is refused here rather than one layer down.
  */
 const reexpressOperationsForCurrentEra = (entryPoints) => {
     const state = new ledgerV9.ContractState();
@@ -83,8 +77,8 @@ const reexpressOperationsForCurrentEra = (entryPoints) => {
  * limitations under the License.
  */
 /**
- * Wraps a {@link TranscriptPojo} — the output of {@link executeCircuit}
- * (`./execute.ts`) — into a v9-native `ContractCallPrototype`, ready for
+ * Wraps a {@link TranscriptPojo} — the output of {@link runRetainedCircuit}
+ * (`../v8/executable.ts`) — into a v9-native `ContractCallPrototype`, ready for
  * `Intent.new(ttl).addCall(...)`, via {@link assembleCallPrototype}
  * (`./assemble-call.ts`) against the ledger-v9 module.
  *
@@ -104,14 +98,14 @@ const reexpressOperationsForCurrentEra = (entryPoints) => {
  */
 const wrapKeepStateCall = (options) => {
     const { transcript, contractAddress, contractState, ledgerParameters } = options;
-    return assembleCallPrototype(ledgerV9, {
+    const { prototype } = assembleCallPrototype(ledgerV9, {
         circuitId: transcript.circuitId,
         contractAddress,
         // The retained execution leg partitions nothing: it always submits the raw
         // op sequence as `'unpartitioned'` -- see RetainedEraExecution.
         transcript: {
             kind: 'unpartitioned',
-            preState: transcript.preContractState.data.state.encode(),
+            preState: transcript.preContractState.encode(),
             publicTranscript: transcript.publicTranscript,
             partitionContext: transcript.partitionContext
         },
@@ -123,6 +117,7 @@ const wrapKeepStateCall = (options) => {
         stage: 'wrap-call',
         version: 'v9'
     });
+    return prototype;
 };
 
 /*
@@ -140,16 +135,190 @@ const wrapKeepStateCall = (options) => {
  * limitations under the License.
  */
 /**
- * Structural equality over the `EncodedStateValue` algebra — plain objects,
+ * Retained-era (ledger 8) execution, on compact-js's own era-pinned entries.
+ *
+ * This module replaced a hand-maintained execution layer — `execute.ts`, which
+ * drove `compact-runtime@0.16` directly, and `down-convert.ts`, which built the
+ * state it ran against. Both are gone; see
+ * `docs/adr/0015-retained-era-execution-on-compact-js.md` for why.
+ *
+ * Everything crossing this module's surface is PLAIN DATA or an era-tagged
+ * handle the caller already holds. No `Effect` value leaves it: the effects
+ * compact-js returns are discharged here with `Effect.runPromise`, which is
+ * also why every entry point is asynchronous — `ContractExecutable` builds its
+ * work on `Effect.tryPromise`, so `runSync` cannot discharge it.
+ *
+ * @see {@link RetainedEraExecution}
+ */
+/**
+ * The shape the retained runtime reads a signing key in: 32 bytes written in
+ * hex, either case.
+ *
+ * MEASURED against the pinned runtime rather than guessed. `sampleSigningKey()`
+ * answers 64 lowercase hex characters; an uppercase key of the same length is
+ * accepted, a shorter or longer one fails with `failed to fill whole buffer`
+ * and a non-hex one with `Invalid character 'z' at position 0`. The value being
+ * a valid Schnorr scalar is a cryptographic property this cannot check, and the
+ * runtime's own `Malformed Schnorr signing key` already names it.
+ */
+const LEDGER8_SIGNING_KEY_PATTERN = /^[0-9a-fA-F]{64}$/;
+/**
+ * The signature kind this era's maintenance authority accepts.
+ *
+ * MEASURED, not chosen: the era reports `supportsCmaSignatureKind` as
+ * `schnorr=true, ecdsa=false`, and `Ledger.fromPlatformSigningKey` answers
+ * `Left(ContractConfigurationError)` for an ecdsa key. Naming it here keeps the
+ * bare hex string this era's callers hold assignable to platform-js's tagged
+ * `SigningKey`, which is what `Configuration.Keys` serves.
+ */
+const LEDGER8_SIGNATURE_KIND = 'schnorr';
+/**
+ * The tag compact-js reports a retained contract under.
+ *
+ * It reaches nothing but error messages: the container's tag is chosen by
+ * whoever builds it, and this era's callers pass an instance that carries no
+ * name of its own.
+ */
+const RETAINED_CONTRACT_TAG = 'retained-era-contract';
+/**
+ * Wraps a constructed retained contract in the container compact-js executes.
+ *
+ * `ContractExecutable` resolves the contract through `new ctor(witnesses)`, so
+ * it needs a constructor. The caller has an instance, and its witnesses are
+ * already bound to it — so the constructor hands that same instance back and
+ * the witnesses arrive with it. Returning an object from a constructor is
+ * ordinary JavaScript; the assertion is needed only because TypeScript types a
+ * class expression by its declaration rather than by what it returns.
+ *
+ * Reusing one instance across calls is what this era already did before
+ * compact-js served it, so this is the existing lifetime, not a new one.
+ *
+ * The compiled-assets path is a placeholder: it is read only by compact-js's
+ * own `ZKConfiguration` reader, and {@link zkConfigurationLayer} replaces that
+ * service outright, so nothing ever resolves it.
+ */
+const containerFor = (contract) => CompiledContract.make(RETAINED_CONTRACT_TAG, 
+// The single assertion this seam needs, and it is here rather than at any
+// caller. A retained artifact satisfies compact-js's `Contract` structurally
+// -- same four circuit maps, and a synchronous `initialState` satisfies its
+// `Awaitable` return -- but the two declare their members over different
+// private-state parameters, so TypeScript will not see it. Narrowing what
+// this module ASKS for (see `RetainedContract`) is what keeps the assertion
+// to one line instead of pushing a cast onto every consumer.
+class {
+    constructor() {
+        return contract;
+    }
+}).pipe(CompiledContract.withVacantWitnesses, CompiledContract.withCompiledFileAssets('.'));
+/**
+ * Serves the coin public key and signing key compact-js reads off
+ * `Configuration.Keys`.
+ *
+ * Built with `Layer.succeed` over the values the caller already holds, rather
+ * than through platform-js's own `Configuration.layer`, which sources them from
+ * a `ConfigProvider`. The service is a plain `Context.Tag` with two members, so
+ * there is nothing a config round trip would add except a second place for the
+ * values to disagree.
+ */
+const keysLayer = (coinPk, signingKey) => Layer.succeed(Configuration.Keys, Configuration.Keys.of({
+    coinPublicKey: CoinPublicKey.make(coinPk),
+    getSigningKey: () => signingKey === undefined
+        ? Option.none()
+        : Option.some(SigningKey.make(signingKey, LEDGER8_SIGNATURE_KIND))
+}));
+/**
+ * Pins the execution clock, or leaves the ambient one in place.
+ *
+ * `Effect.withClock`, NOT a `Layer` over `Clock.Clock`. The clock is one of
+ * Effect's DEFAULT services: it lives on the fiber rather than in the context,
+ * so providing a layer for it type-checks, runs, and is silently ignored — the
+ * wall clock still wins. That was measured here, by a test that asserted a
+ * pinned second and got `Date.now()`.
+ *
+ * Only `currentTimeMillis` and its unsafe twin reach an execution — compact-js
+ * converts to seconds at the call site — but the whole interface is pinned so a
+ * future read cannot quietly fall back to the wall clock.
+ */
+const pinnedClock = (nowSeconds) => {
+    // BEFORE the rounding, because `Math.round` carries `NaN` and both infinities
+    // straight through to `BigInt(millis)`, which refuses them with a bare
+    // `RangeError` naming neither the option nor the era. `nowSeconds` is a plain
+    // `number` on the published option, and `Number(process.env.X)` with the
+    // variable unset is the obvious way to produce one.
+    if (!Number.isFinite(nowSeconds)) {
+        throw new Error(`the retained era cannot pin its execution clock to '${String(nowSeconds)}'. ` +
+            '`nowSeconds` must be a finite number of seconds since the epoch.');
+    }
+    // ROUNDED, not used raw. `nowSeconds` is a plain `number` on the published
+    // option and `Date.now() / 1000` -- the expression a consumer reaches for --
+    // is fractional, which makes `BigInt(millis)` throw `RangeError: ... not an
+    // integer` from inside the clock builder, naming neither the option nor the
+    // era. The millisecond is the finest unit this interface carries and
+    // compact-js divides it back down to seconds, so rounding loses nothing an
+    // execution can observe.
+    const millis = Math.round(nowSeconds * 1_000);
+    const nanos = BigInt(millis) * 1000000n;
+    // `Object.assign` onto the real clock, NOT a spread of it. `Clock.make()`
+    // returns a class instance whose `sleep` and `scheduler` live on the
+    // prototype; a spread copies own enumerable properties only and silently
+    // drops both, leaving a `Clock` that throws `clock.sleep is not a function`
+    // the first time anything schedules work. TypeScript cannot see it, because a
+    // spread type keeps the declared members.
+    return Object.assign(Clock.make(), {
+        unsafeCurrentTimeMillis: () => millis,
+        currentTimeMillis: Effect.succeed(millis),
+        unsafeCurrentTimeNanos: () => nanos,
+        currentTimeNanos: Effect.succeed(nanos)
+    });
+};
+const withPinnedClock = (nowSeconds, effect) => nowSeconds === undefined ? effect : Effect.withClock(pinnedClock(nowSeconds))(effect);
+/**
+ * Adapts a {@link VerifierKeyReader} into the service compact-js's
+ * `initialize` reads keys through.
+ *
+ * A key the reader does not answer for becomes `Option.none()`, and compact-js
+ * REFUSES it: `initialize` fails with a `ContractConfigurationError` naming the
+ * circuit. That is measured, not assumed, and it is stricter than the leg this
+ * replaced — a retained-era constructor used to leave every slot blank and the
+ * deploy composition was the only thing that checked coverage. It now fails
+ * before a state is built at all.
+ */
+const zkConfigurationLayer = (read) => Layer.succeed(ZKConfiguration.ZKConfiguration, ZKConfiguration.ZKConfiguration.of({
+    createReader: (compiledContract) => Effect.sync(() => {
+        const getVerifierKey = (provableCircuitId) => Effect.tryPromise({
+            try: () => read(provableCircuitId).then((key) => key === undefined ? Option.none() : Option.some(Contract.VerifierKey(key))),
+            catch: (cause) => ZKConfigurationReadError.make(compiledContract.tag, provableCircuitId, 'verifier-key', cause)
+        });
+        return {
+            getVerifierKey,
+            getVerifierKeys: (provableCircuitIds) => Effect.forEach(provableCircuitIds, (provableCircuitId) => getVerifierKey(provableCircuitId).pipe(Effect.map((verifierKey) => [provableCircuitId, verifierKey])), { concurrency: 'unbounded', discard: false })
+        };
+    })
+}));
+/**
+ * The verifier-key reader a CIRCUIT call is given.
+ *
+ * `ContractExecutable` declares `ZKConfiguration` in its context for every
+ * method, but only `initialize` and the maintenance operations read a key — a
+ * circuit call needs none, which is measured, not assumed. Providing a reader
+ * that refuses keeps that fact enforced: were a future version to read a key
+ * during a circuit call, this fails by name instead of silently serving
+ * `Option.none()` and composing a call with a blank key slot.
+ */
+const refuseVerifierKeyRead = (provableCircuitId) => Promise.reject(new Error(`a retained-era circuit call read the verifier key for '${provableCircuitId}'. Circuit calls are ` +
+    'not supposed to read ZK configuration; only deployment and maintenance are.'));
+/**
+ * Structural equality over the `EncodedStateValue` algebra -- plain objects,
  * arrays, `Map`s, `Uint8Array`s and primitives.
  *
  * `Map`s are compared pairwise in iteration order, deliberately, and that order
- * is not ascending by key — do not reason about it as sorted.
+ * is not ascending by key -- do not reason about it as sorted. The
+ * order-sensitivity is what makes {@link decodeExecutableStateValue}'s
+ * comparison exact; a `get()`-based rewrite would silently drop it.
  *
  * @param a One value in the algebra.
  * @param b The value to compare it against.
  * @returns `true` when the two are structurally equal.
- * @see {@link RetainedEraExecution}
  */
 const structurallyEqual = (a, b) => {
     if (a === b) {
@@ -172,280 +341,347 @@ const structurallyEqual = (a, b) => {
         });
     }
     if (Array.isArray(a) || Array.isArray(b)) {
-        return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((item, i) => structurallyEqual(item, b[i]));
+        return (Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((item, i) => structurallyEqual(item, b[i])));
     }
     const aRecord = { ...a };
     const bRecord = { ...b };
     const aKeys = Object.keys(aRecord);
-    // `key in bRecord`, not just a matching key count, and a partial guard only --
-    // see RetainedEraExecution and SharedTableDiscipline.
+    // `key in bRecord`, not just a matching key count: looking each of a's keys
+    // up in b without checking it exists reads `undefined` on both sides and
+    // short-circuits to equal.
     return (aKeys.length === Object.keys(bRecord).length &&
         aKeys.every((key) => key in bRecord && structurallyEqual(aRecord[key], bRecord[key])));
 };
 /**
- * Reads a bounded Merkle tree's root, failing with
- * {@link MerkleNotRehashedError} when the tree has not been rehashed.
+ * Decodes the primary state a circuit executes against, refusing a value that
+ * does not re-encode to the bytes it came from.
+ *
+ * The comparison is CROSS-CODEC in production, which is what it is for. A
+ * contract an earlier post-fork call migrated carries a current-era envelope,
+ * so the pipeline reads it with the HEAD era's reader
+ * (`readLedger8Snapshot`) -- the state is then encoded by ledger-v9 and
+ * decoded here by the retained runtime. A retained-era envelope is encoded by
+ * ledger-v8 and decoded by the same retained runtime, which is still a
+ * different physical copy. Either way a shape one side writes and the other
+ * merely tolerates would decode without complaint and execute a circuit
+ * against a state that is not the chain's, with every guard green.
  *
- * Three shapes of "no root" are treated alike: `undefined`, `null`, and a
- * throw out of the wasm-bindgen shim for `root()`.
+ * Reachable with the REAL decoder, not only an injected one: the seam takes a
+ * bare {@link EncodedStateValue} a caller can assemble by hand, and the
+ * retained runtime canonicalises map order and drops members it does not
+ * declare. Both are refused here rather than executed on.
  *
- * @param tree The bounded Merkle tree to read.
- * @returns The tree's root.
- * @throws MerkleNotRehashedError If the tree has no readable root, in any of
- *   those three shapes.
+ * @param state The era-neutral encoded primary state.
+ * @returns The decoded state value.
+ * @throws DownConvertFailedError at stage `'state down-convert'` when the
+ *   decoded value does not re-encode to its source, with the mismatch on
+ *   `cause`.
  * @see {@link RetainedEraExecution}
+ * @see {@link FailClosedDecoding}
  */
-const checkRoot = (tree) => {
-    let root;
+const decodeExecutableStateValue = (state) => {
     try {
-        root = tree.root();
+        const decoded = glue.StateValue.decode(state);
+        if (!structurallyEqual(decoded.encode(), state)) {
+            throw new DownConvertFailedError('state down-convert', new Error(`decoded StateValue did not re-encode to its source (source tag '${state.tag}')`));
+        }
+        return decoded;
     }
     catch (cause) {
-        throw new MerkleNotRehashedError(cause);
+        // The decoder and the re-encoder both raise BARE vendor errors -- `missing
+        // field \`tag\``, `unknown variant \`x\`` -- carrying neither `code` nor
+        // `stage`. Coding them here is what the retired `downConvertForExecution`
+        // did, and what `fail-closed-decoding.md` still promises a caller.
+        throw cause instanceof DownConvertFailedError ? cause : new DownConvertFailedError('state down-convert', cause);
     }
-    if (root == null) {
-        throw new MerkleNotRehashedError();
+};
+/**
+ * Builds the retained-era `ContractState` a circuit executes against, from the
+ * era-neutral state the envelope's own reader produced.
+ *
+ * `StateValue` and `ChargedState` come from the retained glue rather than from
+ * compact-js: its `CompactRuntime` binding re-exports neither as a VALUE
+ * (midnightntwrk/midnight-sdk, spec finding E9), and building them through
+ * ledger-v8's own same-named classes instead would be the dual instantiation
+ * this era must not perform. `ContractState` is the glue's as well, so all
+ * three come from one module.
+ *
+ * A WHOLE `ContractState` rather than the bare `ChargedState` its predecessor
+ * built: the runtime reads `block.balance` off a contract state and substitutes
+ * an empty map for anything less, so writing the balance here is what makes it
+ * reach the circuit at all. It used to be injected into the query context after
+ * the fact, which is what #1345 was.
+ *
+ * @param contractState The decoded state and the balances beside it.
+ * @returns The state the retained runtime executes against.
+ */
+const executableStateFrom = (contractState) => {
+    // Read ONCE, then guarded. Not defaulted and not trusted: `new Map(...)`
+    // turns an absent balance, a `null`, an empty array and an empty `Set` alike
+    // into an EMPTY map, which is indistinguishable from a contract that holds
+    // nothing -- the circuit then reads zero where the chain says otherwise and
+    // the node refuses the resulting transcript, with every guard green. That is
+    // #1345. `tsc` reaches neither an untyped JavaScript caller nor an options
+    // object assembled dynamically, and both `RunRetainedCircuitOptions` and
+    // `ContractStatePojo` are on the published surface.
+    // @see FailClosedDecoding
+    const { balance } = contractState;
+    if (!isContractBalance(balance)) {
+        throw new DownConvertFailedError('state down-convert', new Error(`a contract state carries no usable balance (received ${describeValue(balance)}), so it cannot be ` +
+            'executed against. Read it from a contract-state snapshot rather than assembling one; a contract ' +
+            'that holds nothing declares an empty Map.'));
+    }
+    try {
+        const state = new glue.ContractState();
+        state.data = new glue.ChargedState(decodeExecutableStateValue(contractState.state));
+        // Copied rather than shared, so an entry the caller adds or removes afterwards
+        // cannot reach a running circuit.
+        state.balance = new Map(balance);
+        return state;
+    }
+    catch (cause) {
+        // Both setters are WASM, and both raise bare errors: `balance` refuses a
+        // colour `isContractBalance` admits by name but the runtime cannot read,
+        // and `data` refuses a `ChargedState` from another physical copy. Neither
+        // carries a `code` a caller can branch on.
+        throw cause instanceof DownConvertFailedError ? cause : new DownConvertFailedError('state down-convert', cause);
     }
-    return root;
 };
 /**
- * Asserts that every bounded Merkle tree in a `StateValue` tree already has
- * its node hashes computed, recursing through the only two container variants
- * in the algebra (`array` and `map`) and ignoring the leaf variants (`cell`,
- * `null`, and `boundedMerkleTree`'s own contents).
- *
- * Does not mutate or rebuild the state: a rootless tree is refused, never
- * repaired.
- *
- * @param sv The `StateValue` tree to walk.
- * @throws MerkleNotRehashedError On the first tree without a readable root,
- *   via {@link checkRoot}.
- * @throws DownConvertFailedError If the walk meets a `StateValue` variant the
- *   pinned typings do not declare.
- * @see {@link RetainedEraExecution}
+ * Every message in a failure's cause chain, outermost first.
+ *
+ * compact-js reports an execution failure as `Error executing circuit 'x'` and
+ * hangs the runtime's own diagnostic -- `Block time is <= time`, an out-of-gas,
+ * a failed assertion -- on `cause`. Only the outer message reaches a caller who
+ * reads `error.message`, so the reason the circuit ACTUALLY failed is lost at
+ * exactly the moment someone needs it.
  */
-const assertMerkleTreesRehashed = (sv) => {
-    const variant = sv.type();
-    switch (variant) {
-        case 'boundedMerkleTree':
-            checkRoot(sv.asBoundedMerkleTree());
-            return;
-        case 'array':
-            sv.asArray().forEach((element) => assertMerkleTreesRehashed(element));
-            return;
-        case 'map': {
-            const map = sv.asMap();
-            map.keys().forEach((key) => assertMerkleTreesRehashed(map.get(key)));
-            return;
-        }
-        case 'cell':
-        case 'null':
-            return;
-        default: {
-            // Compile-time exhaustiveness plus a runtime throw; neither is redundant
-            // with the other -- see SharedTableDiscipline.
-            const unhandled = variant;
-            throw new DownConvertFailedError('state down-convert', new Error(`unhandled StateValue variant '${String(unhandled)}' in the Merkle rehash walk`));
-        }
+const causeChain = (error, seen = new Set()) => {
+    if (typeof error !== 'object' || error === null || seen.has(error)) {
+        return typeof error === 'string' ? [error] : [];
     }
+    seen.add(error);
+    const message = 'message' in error && typeof error.message === 'string' ? [error.message] : [];
+    return 'cause' in error ? [...message, ...causeChain(error.cause, seen)] : message;
 };
 /**
- * Down-converts an already-extracted (post-fork) {@link EncodedStateValue}
- * into the pre-fork {@link DownConvertedState} a v8-era circuit executes
- * against, decoding it through `ledger8Runtime` and asserting (via
- * {@link assertMerkleTreesRehashed}) that every bounded Merkle tree it
- * contains already has its hashes computed.
- *
- * Never returns a silently empty or partial state: every failure leaves as a
- * coded error. Structural integrity is checked by re-encoding the decoded value
- * and comparing it to the input, which costs one extra encode plus a deep
- * comparison per call.
- *
- * `ledger8Runtime` is checked before anything is decoded. Only the two members
- * this function actually calls are checked; `ContractState` is on
- * {@link Ledger8CompactRuntime} to pin the era, and is never dereferenced here.
- *
- * @param state The already-extracted post-fork encoded state value.
- * @param ledger8Runtime The injected pre-fork runtime slice.
- * @returns The pre-fork state a v8-era circuit executes against.
- * @throws Ledger8RuntimeInvalidError If `ledger8Runtime` is missing
- *   `StateValue.decode` or `ChargedState`.
- * @throws DownConvertFailedError If the state cannot be decoded, does not
- *   re-encode to its source, or the Merkle walk meets an undeclared variant —
- *   carrying the underlying failure on `cause`.
- * @throws MerkleNotRehashedError If any bounded Merkle tree in the state has no
- *   readable root.
- * @see {@link RetainedEraExecution}
- * @see {@link FailClosedDecoding}
+ * Runs an effect and rethrows its failure with the whole cause chain in the
+ * message.
+ *
+ * `Effect.runPromise` alone rejects with a `FiberFailure`, which carries neither
+ * the failure's class nor its `cause` — so a caller loses both the error it
+ * could have discriminated on and the diagnostic it needed. `runPromiseExit`
+ * plus `Cause.squash` recovers the real error, which is then rethrown with the
+ * underlying reason spelled out and the original on `cause`.
+ */
+const PROTOCOL_ERROR_CODE_VALUES = new Set(Object.values(PROTOCOL_ERROR_CODES));
+/**
+ * Whether a value is one of this package's own coded errors.
+ *
+ * The registry is the test rather than `instanceof` against a list: every class
+ * in `errors.ts` carries a `code` drawn from {@link PROTOCOL_ERROR_CODES}, so a
+ * class added later is recognised without this predicate being touched.
+ *
+ * @param error The value to test.
+ * @returns `true` when the value carries a registered protocol error code.
  */
-const downConvertForExecution = (state, ledger8Runtime) => {
-    if (typeof ledger8Runtime?.StateValue?.decode !== 'function') {
-        throw new Ledger8RuntimeInvalidError('StateValue.decode');
+const isCodedProtocolError = (error) => {
+    if (!(error instanceof Error) || !('code' in error)) {
+        return false;
     }
-    if (typeof ledger8Runtime.ChargedState !== 'function') {
-        throw new Ledger8RuntimeInvalidError('ChargedState');
+    const { code } = error;
+    return typeof code === 'string' && PROTOCOL_ERROR_CODE_VALUES.has(code);
+};
+const runOrRethrow = async (effect) => {
+    const exit = await Effect.runPromiseExit(effect);
+    if (Exit.isSuccess(exit)) {
+        return exit.value;
     }
-    try {
-        const decoded = ledger8Runtime.StateValue.decode(state);
-        if (!structurallyEqual(decoded.encode(), state)) {
-            throw new DownConvertFailedError('state down-convert', new Error(`decoded StateValue did not re-encode to its source (source tag '${state.tag}')`));
-        }
-        assertMerkleTreesRehashed(decoded);
-        return { data: new ledger8Runtime.ChargedState(decoded) };
+    // EVERY failure, not just the squashed first one. Verifier keys are read with
+    // `concurrency: 'unbounded'`, so a deploy missing three circuits' artifacts
+    // fails three times at once and `Cause.squash` answers with one -- sending the
+    // caller round the fix-and-rerun loop once per missing key.
+    const failures = Array.from(Cause.failures(exit.cause));
+    const error = failures.length > 0 ? failures[0] : Cause.squash(exit.cause);
+    // A coded error leaves with its CLASS intact, however many failures arrived
+    // beside it. Flattening one erases the `code` and `stage` a caller
+    // discriminates on, and this boundary sees errors this package raised itself
+    // on the way through, not only compact-js's. When several fail at once the
+    // coded one wins: a caller can branch on a code but not on a joined message,
+    // and the rest stay readable on the cause chain.
+    const coded = failures.find(isCodedProtocolError);
+    if (coded !== undefined) {
+        throw coded;
     }
-    catch (cause) {
-        if (cause instanceof DownConvertFailedError || cause instanceof MerkleNotRehashedError) {
-            throw cause;
-        }
-        throw new DownConvertFailedError('state down-convert', cause);
+    const describe = (failure) => {
+        const chain = causeChain(failure);
+        return chain.length > 0 ? chain.join(': ') : String(failure);
+    };
+    throw new Error(failures.length > 1 ? failures.map(describe).join('; ') : describe(error), { cause: error });
+};
+/**
+ * Reads the ONE contract call a retained-era circuit produces.
+ *
+ * The retained era has no `crossContractCall`, so its execution adapter
+ * synthesises a single-entry trace and a one-element list is complete by
+ * construction. The list is still typed as a list, so the emptiness this era
+ * cannot produce is refused by name rather than read as `undefined` and carried
+ * into a composition.
+ *
+ * @param calls The calls the execution reported.
+ * @param circuitId The circuit they were produced for, for the message.
+ * @returns The sole call.
+ * @throws Error If the list is empty.
+ */
+const soleCall = (calls, circuitId) => {
+    const [only] = calls;
+    if (only === undefined) {
+        throw new Error(`circuit '${circuitId}' produced no contract call. The retained era cannot make a ` +
+            'cross-contract call, so exactly one is expected.');
     }
+    return only;
 };
-
-/*
- * This file is part of midnight-js.
- * Copyright (C) Midnight Foundation
- * SPDX-License-Identifier: Apache-2.0
- * Licensed under the Apache License, Version 2.0 (the "License");
- * You may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- * http://www.apache.org/licenses/LICENSE-2.0
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
+/**
+ * Refuses a circuit id the contract does not declare, before compact-js
+ * dispatches on it.
+ *
+ * `Object.hasOwn`, NOT a bare truthiness check. A 0.16 artifact assigns
+ * `provableCircuits` a plain object literal, so its prototype is live, and
+ * compact-js resolves a circuit with `contract.provableCircuits[id]` guarded
+ * only by `if (!circuit)`. `'toString'`, `'valueOf'` and `'constructor'` all
+ * satisfy that guard: the prototype member is CALLED with the runtime context
+ * and its return value fed to `readExecution`. The id reaches here from the
+ * caller, so it is refused by name, the way the retired `executeCircuit` did.
+ *
+ * @param contract The contract the call names.
+ * @param circuitId The circuit the caller asked for.
+ * @throws Error If the contract declares no such circuit.
  */
+const assertDeclaredCircuit = (contract, circuitId) => {
+    const circuit = Object.hasOwn(contract.provableCircuits, circuitId)
+        ? contract.provableCircuits[circuitId]
+        : undefined;
+    if (typeof circuit !== 'function') {
+        throw new Error(`No circuit named '${circuitId}' on this retained-era contract instance. ` +
+            `Available circuits: ${Object.keys(contract.provableCircuits).sort().join(', ')}.`);
+    }
+};
 /**
- * Runs one impure circuit on a pre-fork (`compact-runtime@0.16`) contract
- * instance and packages every artifact {@link wrapKeepStateCall} needs into a
- * {@link TranscriptPojo}.
+ * Runs one circuit on a retained-era contract and packages every artifact a
+ * v9-native call prototype needs.
  *
- * A circuit that moved coins runs like any other: its post-call Zswap local
- * state leaves on {@link TranscriptPojo}, decoded through the injected runtime,
- * for the caller to turn into the transaction's Zswap offer.
+ * The balances the contract holds travel on the state it is given — see
+ * {@link RunRetainedCircuitOptions.contractState}.
  *
- * @param options The contract module, circuit id, arguments, down-converted
- *   state, contract address, coin public key and private state.
- * @param ledger8Runtime The injected pre-fork glue slice.
+ * @param options The retained contract, circuit id, arguments, decoded state,
+ *   address, coin public key, private state and optional pinned clock.
  * @returns Every artifact a v9-native call prototype needs.
- * @throws Error A plain `Error` — not a {@link PROTOCOL_ERROR_CODES}-carrying
- *   class — when `circuitId` names no entry point on
- *   `contract.impureCircuits`.
  * @see {@link RetainedEraExecution}
  */
-const executeCircuit = (options, ledger8Runtime) => {
-    const { contract, circuitId, args, state, address, coinPk, privateState } = options;
-    const circuit = Object.hasOwn(contract.impureCircuits, circuitId) ? contract.impureCircuits[circuitId] : undefined;
-    if (typeof circuit !== 'function') {
-        throw new Error(`No impure circuit named '${circuitId}' on this pre-fork contract instance. ` +
-            `Available circuits: ${Object.keys(contract.impureCircuits).join(', ') || '(none)'}.`);
-    }
-    const ctx = ledger8Runtime.createCircuitContext(address, coinPk, state.data, privateState, undefined, ledger8Runtime.CostModel.initialCostModel());
-    // Read BEFORE the circuit runs. The glue swaps `currentQueryContext` for a
-    // new context on every coin it registers, so after the call this object no
-    // longer answers for the context the call started from.
-    const preCallBlock = ctx.currentQueryContext.block;
-    const preCallEffects = ctx.currentQueryContext.effects;
-    const res = circuit(ctx, ...args);
+const runRetainedCircuit = async (options) => {
+    assertDeclaredCircuit(options.contract, options.circuitId);
+    const executable = ContractExecutable.make(containerFor(options.contract));
+    const contractState = executableStateFrom(options.contractState);
+    const program = Effect.gen(function* () {
+        return yield* executable.circuit(Contract.ProvableCircuitId(options.circuitId), {
+            address: PlatformContractAddress.ContractAddress(options.address),
+            contractState,
+            privateState: options.privateState
+        }, 
+        // Asserted for the same reason `createCallTxOptions` asserts it in
+        // `packages/contracts/src/tx-interfaces.ts`: resolved through a GENERIC
+        // `C`, `CircuitParameters` degrades to `unknown[]` because TypeScript
+        // indexes `provableCircuits` against the constraint rather than the
+        // instantiated contract. The tuple is checked where `C` is concrete, at
+        // the caller's own call site.
+        ...options.args);
+    });
+    const call = await runOrRethrow(withPinnedClock(options.nowSeconds, program.pipe(Effect.provide(Layer.mergeAll(keysLayer(options.coinPk, undefined), zkConfigurationLayer(refuseVerifierKeyRead))))));
+    const only = soleCall(call.calls, options.circuitId);
     return {
-        circuitId,
-        result: res.result,
-        input: res.proofData.input,
-        output: res.proofData.output,
-        publicTranscript: res.proofData.publicTranscript,
-        privateTranscriptOutputs: res.proofData.privateTranscriptOutputs,
-        preContractState: state,
-        postContractState: { data: res.context.currentQueryContext.state },
-        // Encoded HERE, where the retained runtime is in scope, rather than by the
-        // caller: `.encode()` is on the pre-fork `StateValue` this module already
-        // holds, and a caller reaching for it would be reaching through a handle
-        // whose type it cannot name.
-        postContractStateEncoded: res.context.currentQueryContext.state.state.encode(),
-        privateStateAfter: res.context.currentPrivateState,
+        circuitId: only.circuitId,
+        result: call.result,
+        input: only.private.input,
+        output: only.private.output,
+        publicTranscript: only.public.publicTranscript,
+        privateTranscriptOutputs: only.private.privateTranscriptOutputs,
+        preContractState: only.public.partitionInputs.state,
+        postContractState: only.public.contractState,
+        postContractStateEncoded: only.public.contractState.encode(),
+        privateStateAfter: call.privateState,
         partitionContext: {
-            block: preCallBlock,
-            effects: preCallEffects,
-            comIndices: res.context.currentQueryContext.comIndices
+            block: only.public.partitionInputs.block,
+            effects: only.public.partitionInputs.effects,
+            comIndices: only.public.partitionInputs.comIndices
         },
-        zswapLocalState: ledger8Runtime.decodeZswapLocalState(res.context.currentZswapLocalState)
+        zswapLocalState: call.zswapLocalState
     };
 };
-
-/*
- * This file is part of midnight-js.
- * Copyright (C) Midnight Foundation
- * SPDX-License-Identifier: Apache-2.0
- * Licensed under the Apache License, Version 2.0 (the "License");
- * You may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- * http://www.apache.org/licenses/LICENSE-2.0
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
 /**
- * The closed set of axes this guard will run on, as a lookup rather than a
- * comparison chain.
+ * Re-codes compact-js's refusal of a verifier-key blob as this package's own
+ * {@link ComposeFailedError}.
+ *
+ * compact-js writes the keys itself inside `initialize`, so it is the first
+ * thing to touch the bytes and the retained composer -- which raised the coded
+ * refusal before this move -- is never reached. Without this the same fault is
+ * reported as a coded error on the current era and an uncoded one on the
+ * retained era.
  *
- * Kept here rather than exported from `errors.ts`, which is a build entry:
- * nothing outside this module needs to test an axis, and the engine's whole
- * design is to stay off the public surface.
+ * The `cause` is what separates a rejected blob from the other configuration
+ * refusals: compact-js attaches the ledger's own error only when a key it was
+ * handed was refused, and leaves it absent for a key that was never served.
  *
- * @see {@link SharedTableDiscipline}
+ * @param error The failure compact-js reported.
+ * @returns A {@link ComposeFailedError} for a rejected blob; the error
+ *   unchanged for anything else.
  */
-const KNOWN_AXES = Object.freeze(Object.assign(Object.create(null), {
-    'onchain-runtime-v3': true
-}));
-const isKnownAxis = (axis) => KNOWN_AXES[axis] === true;
+const recodeVerifierKeyBlobFailure = (error) => {
+    if (!ContractConfigurationError.isConfigurationError(error) || error.cause === undefined) {
+        return error;
+    }
+    const circuitId = /verifier key for circuit '([^']+)'/.exec(error.message)?.[1];
+    return circuitId === undefined
+        ? error
+        : new ComposeFailedError('v8', 'deploy-verifier-key-blob', circuitId, error.cause);
+};
 /**
- * Fails fast on a dual-instantiation of a WASM package the down-convert
- * engine depends on, along one named `axis`.
- *
- * Pass a **shared binding** — a class the package exports, such as
- * `ChargedState` or `StateValue` — never a module namespace object.
- *
- * The two probes are compared symmetrically, so they are interchangeable, but
- * they must be obtained from **two different acquisition paths** (two distinct
- * import specifiers, or an import versus a caller-supplied module). Passing the
- * same binding twice satisfies the check trivially and proves nothing; the
- * caller owns that, because nothing in the signature can enforce it.
- *
- * @param axis The physical-copy axis to check, validated against
- *   {@link Ledger8InstanceAxis} before either probe is looked at.
- * @param probeA A shared binding, obtained through one acquisition path.
- * @param probeB The same binding, obtained through a different acquisition
- *   path.
- * @throws UnknownLedger8AxisError If `axis` is not a member of
- *   {@link Ledger8InstanceAxis}.
- * @throws Ledger8RuntimeInvalidError If either probe is `null` or `undefined`.
- *   A missing probe is a binding the caller did not hand over, so it is not
- *   reported as a mismatch.
- * @throws Ledger8InstanceMismatchError If the two probes are not
- *   reference-equal, i.e. the package resolved to two physically distinct
- *   copies in this process.
- * @example
- * ```typescript
- * const [glue, ocrt3] = await Promise.all([
- *   import('compact-runtime-ledger8'),
- *   import('@midnight-ntwrk/onchain-runtime-v3')
- * ]);
- * // Two acquisition paths to the same binding, never a namespace object.
- * assertSharedLedger8Instance('onchain-runtime-v3', ocrt3.ChargedState, glue.ChargedState);
- * ```
- * @see {@link DualInstantiationGuard}
+ * Runs a retained-era contract's constructor and packages the result.
+ *
+ * compact-js's `initialize` also writes the maintenance authority and registers
+ * each entry point's verifier key onto the state, both of which this era's
+ * deploy leg previously did for itself. The authority matters: the retained
+ * constructor leaves an EMPTY committee with a threshold of one — one signature
+ * from a set of zero keys, which nothing can satisfy — so a deployment left on
+ * it could never have a verifier key inserted, removed or replaced.
+ *
+ * @param options The compiled contract, constructor arguments, private state,
+ *   coin public key, optional signing key and verifier-key reader.
+ * @throws ComposeOptionError naming option `'signingKey'` when a supplied key
+ *   is not the 32 bytes of hex the retained runtime reads, raised before the
+ *   constructor runs.
+ * @returns The freshly built state, the resulting private state, the Zswap
+ *   local state the constructor ended on and the signing key the authority was
+ *   built from.
+ * @see {@link RetainedEraExecution}
  */
-const assertSharedLedger8Instance = (axis, probeA, probeB) => {
-    if (!isKnownAxis(axis)) {
-        throw new UnknownLedger8AxisError(String(axis));
-    }
-    if (probeA == null || probeB == null) {
-        throw new Ledger8RuntimeInvalidError(`${axis} instance probe`);
-    }
-    if (probeA !== probeB) {
-        throw new Ledger8InstanceMismatchError(axis);
+const runRetainedConstructor = async (options) => {
+    // BEFORE the constructor runs, so nothing is executed against a key the
+    // maintenance authority could never have been built from, and the refusal
+    // names the option rather than leaving the runtime's own buffer message to
+    // stand for it.
+    if (options.signingKey !== undefined && !LEDGER8_SIGNING_KEY_PATTERN.test(options.signingKey)) {
+        throw new ComposeOptionError('v8', 'signingKey');
     }
+    const executable = ContractExecutable.make(containerFor(options.contract));
+    const deployed = await runOrRethrow(executable
+        .initialize(options.privateState, ...options.args)
+        .pipe(Effect.mapError(recodeVerifierKeyBlobFailure), Effect.provide(Layer.mergeAll(keysLayer(options.coinPk, options.signingKey), zkConfigurationLayer(options.verifierKeys)))));
+    return {
+        contractState: deployed.public.contractState,
+        privateState: deployed.private.privateState,
+        zswapLocalState: deployed.private.zswapLocalState,
+        signingKey: deployed.private.signingKey.value
+    };
 };
 
 /*
@@ -463,57 +699,33 @@ const assertSharedLedger8Instance = (axis, probeA, probeB) => {
  * limitations under the License.
  */
 /**
- * Acquires the retained pre-fork toolchain — the `compact-runtime@0.16` glue
- * and `@midnight-ntwrk/onchain-runtime-v3` — and builds a {@link Ledger8Engine}
- * bound to it.
- *
- * Runs {@link assertSharedLedger8Instance} exactly once, on the
- * `onchain-runtime-v3` axis. Any acquisition failure surfaces through the
- * facade (`lib/v8/load-engine.ts`) as `Ledger8RuntimeMissingError`
- * (`../../errors.ts`).
- *
- * Does NOT acquire the v8 ledger module: a consumer that only executes
- * circuits and binds them onto v9 never instantiates the multi-megabyte v8
- * WASM, and never hard-depends on ledger-v8 resolving.
- *
- * @returns The engine surface, with the acquired runtime captured in closure.
- * @throws Ledger8InstanceMismatchError If `onchain-runtime-v3` resolved to two
- *   physically distinct copies in this process.
+ * Builds a {@link Ledger8Engine}.
+ *
+ * The retained toolchain is no longer acquired here: compact-js's era-pinned
+ * ledger-8 entries own it, and `lib/v8/executable.ts` reaches them. What this
+ * function still does is sit behind the dynamic `import('../../engine.js')` in
+ * `lib/v8/load-engine.ts`, so importing the package root never pulls the
+ * multi-megabyte retained WASM onto the module graph.
+ *
+ * It no longer runs a dual-instantiation guard either. That guard compared
+ * `onchain-runtime-v3` against the 0.16 glue at construction time. Both
+ * acquisition paths are still live — `lib/v8/executable.ts` imports the glue
+ * directly, and compact-js resolves the same specifier for itself — so the axis
+ * did not go away; only the runtime check did. The invariant is held at install
+ * time instead, by `src/test/single-instance.test.ts`, which pins one resolved
+ * copy of `onchain-runtime-v3` and of each compact-runtime era line. That is a
+ * check on THIS repo's lockfile, not on a consumer's process.
+ *
+ * @returns The engine surface.
  * @see {@link EraSeam}
- * @see {@link DualInstantiationGuard}
  * @see {@link ModuleGraphAndLazyLoading}
  */
-const createLedger8Engine = async () => {
-    const [glue, ocrt3] = await Promise.all([
-        import('compact-runtime-ledger8'),
-        import('@midnight-ntwrk/onchain-runtime-v3')
-    ]);
-    assertSharedLedger8Instance('onchain-runtime-v3', ocrt3.ChargedState, glue.ChargedState);
-    // `ContractState` from ocrt3, the other two from the glue: sound only because
-    // of the assertion above -- see DualInstantiationGuard. The member is what
-    // pins this object to the pre-fork era -- see `Ledger8CompactRuntime`.
-    const ledger8CompactRuntime = {
-        ContractState: ocrt3.ContractState,
-        StateValue: glue.StateValue,
-        ChargedState: glue.ChargedState
-    };
-    const ledger8ExecutionRuntime = {
-        decodeZswapLocalState: glue.decodeZswapLocalState,
-        createCircuitContext: glue.createCircuitContext,
-        CostModel: glue.CostModel
-    };
-    const ledger8ConstructorRuntime = {
-        createConstructorContext: glue.createConstructorContext,
-        decodeZswapLocalState: glue.decodeZswapLocalState
-    };
-    return {
-        downConvertForExecution: (state) => downConvertForExecution(state, ledger8CompactRuntime),
-        executeCircuit: (options) => executeCircuit(options, ledger8ExecutionRuntime),
-        wrapKeepStateCall,
-        reexpressOperationsForCurrentEra,
-        executeConstructor: (options) => executeConstructor(options, ledger8ConstructorRuntime)
-    };
-};
+const createLedger8Engine = async () => Promise.resolve({
+    executeCircuit: runRetainedCircuit,
+    executeConstructor: runRetainedConstructor,
+    wrapKeepStateCall,
+    reexpressOperationsForCurrentEra
+});
 
 export { createLedger8Engine };
 //# sourceMappingURL=engine.js.map