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

package/README.md

@@ -52,7 +52,7 @@ Nothing under `src/lib/` is a build entry, so this layout is internal and no con
 
 | Directory | Holds | Ledger reference |
 |---|---|---|
-| `lib/v8/` | the retained pre-fork era: `load.ts`, `engine.ts`, `load-engine.ts`, `instance-guard.ts`, `down-convert.ts`, `execute.ts`, `compose.ts`, `deploy.ts`, `adapt.ts` | acquires `ledger-v8`, `onchain-runtime-v3` and the 0.16 glue, always through a dynamic import |
+| `lib/v8/` | the retained pre-fork era: `load.ts`, `engine.ts`, `load-engine.ts`, `executable.ts`, `compose.ts`, `deploy.ts`, `prove.ts`, `adapt.ts` | acquires `ledger-v8`, `onchain-runtime-v3` and the 0.16 glue, always through a dynamic import |
 | `lib/v9/` | the current era's composition arms: `compose.ts`, `wrap.ts` | links `ledger-v9` statically |
 | `lib/shared/` | what both arms run: `ledger-version.ts`, `verifier-keys.ts`, `compose-options.ts`, `assemble-call.ts`, `compose-types.ts`, `unshielded.ts`, `contract-state.ts` | era passed in as a `LedgerVersion` parameter, never chosen here |
 | `lib/era/` | the facade and the dispatch: `load-era.ts`, `era.ts`, `envelope.ts` | reaches both, which is the point of the layer |
@@ -61,9 +61,9 @@ The directory names say what a module is **about**, not what it links. Three con
 
 - **`lib/v8/compose.ts`, `deploy.ts` and `adapt.ts` link no v8 at all.** They take the acquired module as a `ProtocolV8` parameter, which is a type. That injection is what keeps the v8 WASM out of the eager graph, and the guarantee is enforced by `dist-laziness.test.ts` and `v8-surface.test.ts` — not by this layout. Read the tests, not the directory, for the bundle boundary.
 - **`lib/shared/` is not free of vendors.** `assemble-call.ts` links `@midnight-ntwrk/compact-js`, a post-fork package, for `hashVerifierKey` and `encodeContractKeyLocation`; `contract-state.ts` links it for `hashVerifierKey`. Both are called by both arms, so their subject is shared even though their linkage is not. This is safe in one direction only: v9 is the eagerly-linked baseline, so a shared module reaching for it never wakes v8, while the reverse would.
-- **`lib/v9/wrap.ts` type-imports `lib/v8/execute.ts`.** `TranscriptPojo` is the v8 engine's output and `wrapKeepStateCall` binds it onto v9. The cross-era edge is the operation's whole purpose, and it is type-only.
+- **`lib/v9/wrap.ts` type-imports `lib/v8/executable.ts`.** `TranscriptPojo` is the v8 engine's output and `wrapKeepStateCall` binds it onto v9. The cross-era edge is the operation's whole purpose, and it is type-only.
 
-`compose-types.ts` and `era.ts` name their shared types through `@midnightntwrk/ledger-v9` because some vendor has to name them. `EncodedStateValue`, `Op`, `AlignedValue` and `Transcript` are pinned identical across `onchain-runtime-v3`, `ledger-v8` and `ledger-v9` by the compile-time assertions in `v8-down-convert.test.ts`; the import names one era, the type belongs to neither. Those assertions are evaluated by `yarn typecheck:tests` on the pre-push hook, not by CI — vitest transpiles test files without type-checking, so treat a failure there as the only signal you will get.
+`compose-types.ts` and `era.ts` name their shared types through `@midnightntwrk/ledger-v9` because some vendor has to name them. `EncodedStateValue`, `Op`, `AlignedValue`, `Transcript`, `CallContext` and `Effects` are pinned identical across `onchain-runtime-v3`, `ledger-v8` and `ledger-v9` by the compile-time assertions at the bottom of `v8-executable.test.ts`; the import names one era, the type belongs to neither. Those assertions are evaluated by `yarn typecheck:tests` — run by the pre-push hook AND by CI's `typecheck:tests:core` job. The test run itself does not evaluate them, because vitest transpiles test files without type-checking.
 
 ## Architecture Documents
 
@@ -82,6 +82,7 @@ docstring resolves to it.
 | [Verifier keys](./docs/verifier-keys.md) | Registration rules, the refusals that stop a deploy landing at an address the caller's artifacts do not describe, and why the address cannot be recomputed |
 | [Module graph and lazy loading](./docs/module-graph-and-lazy-loading.md) | Build entries, the `./v8` and `./engine` chunks, the import cycle avoided by a leaf module, and why a vendor's types are named with `import type` |
 | [Injected vendor slices](./docs/injected-vendor-slices.md) | How a seam names the vendor class it takes by injection — derived from the vendor's own class, declared structurally, or narrowed — and what each choice buys |
+| [Cross-era operation registry](./docs/cross-era-operation-registry.md) | What actually crosses the fork boundary when a dormant retained-era contract is called, why re-expressing its operations is faithful rather than a substitution, and why the primary state is left at its default |
 | [Shared table discipline](./docs/shared-table-discipline.md) | Why the shared tables are frozen and null-prototyped, and why exhaustiveness is enforced at compile time as well as at run time |
 
 Docstrings in `src/` carry the API contract: what a symbol does, its
@@ -117,12 +118,16 @@ import { loadLedger8Engine, loadLedgerEra, versionOfRecord } from '@midnight-ntw
 const engine = await loadLedger8Engine();
 const era = await loadLedgerEra(versionOfRecord(indexerRecord));
 
-const state = engine.downConvertForExecution(era.extractState(rawContractState));
-const transcript = engine.executeCircuit({
+// The DECODED state, not the extracted one: the balances a circuit reads are
+// not part of the primary state, and this value carries them alongside it.
+// One read in, one value out -- there is no second argument that could
+// describe a different block.
+const contractState = era.decodeContractState(rawContractState);
+const transcript = await engine.executeCircuit({
   contract,
   circuitId: 'increment',
   args: [],
-  state,
+  contractState,
   address: contractAddress,
   coinPk: coinPublicKey,
   privateState
@@ -130,11 +135,17 @@ const transcript = engine.executeCircuit({
 const prototype = engine.wrapKeepStateCall({ transcript, contractAddress, contractState: migratedV9ContractState });
 ```
 
-The engine exposes `downConvertForExecution`, `executeCircuit`, `executeConstructor` and `wrapKeepStateCall`, and they form a pipeline, each result being the next call's input. Reading a contract state and composing a call or a deploy are **not** here: both eras do those, so they live on the [ledger-era facade](#ledger-era-facade) instead.
+`executeCircuit` and `executeConstructor` are **asynchronous** — `await` them. There is no separate down-convert step: pass the decoded contract state straight in, and the engine builds the state the retained runtime executes against.
+
+Read it with the era the state's own envelope names, not with a fixed one. A contract an earlier post-fork call has MIGRATED carries a current-era envelope while its artifacts stay the retained toolchain's, so `era` above is the head's era for that contract and the retained era for one that has not migrated. Handing the retained reader a current-era envelope is refused on the tag.
+
+`contractState` must carry a usable `balance`. It is required rather than defaulted, because an empty balance is a legitimate value — a contract holding nothing has one — and defaulting would make "holds nothing" indistinguishable from "the caller forgot", which is a circuit reading zero where the chain says otherwise. `decodeContractState` produces both halves for you; assembling the value by hand is what the refusal is there for.
+
+The engine exposes `executeCircuit`, `executeConstructor` and `wrapKeepStateCall`, and they form a pipeline, each result being the next call's input. Reading a contract state and composing a call or a deploy are **not** here: both eras do those, so they live on the [ledger-era facade](#ledger-era-facade) instead.
 
 `migratedV9ContractState` passed to `wrapKeepStateCall` must be the migrated v9 state **as read from chain**, which is not `rawContractState` above: it is where the deployed operation and its verifier key come from, and the key location the prototype carries is derived from that key. A blank or constructor-built state throws `ComposeFailedError` (code `MIDNIGHT_JS_P_COMPOSE_FAILED`) with `stage` naming which lookup failed and `version` naming the ledger era it was composing for.
 
-Circuits with Zswap coin effects run on this leg like any other. The transcript carries `zswapLocalState` — the post-call Zswap local state, decoded into the runtime's public shape — which is what you turn into the transaction's segmented Zswap offer (`zswapStateToSegmentedOffer` in `@midnight-ntwrk/midnight-js-contracts`) and pass to `composeCallTx` as `guaranteedZswapOffer` / `fallibleZswapOffer`. Dropping it is what would leave you composing a transaction missing the coin movements the circuit recorded.
+Circuits with Zswap coin effects run on this leg like any other. The transcript carries `zswapLocalState` — the post-call Zswap local state, decoded into the runtime's public shape — which is what you turn into the transaction's segmented Zswap offer (`zswapStateToSegmentedOffer` in `@midnight-ntwrk/midnight-js-contracts`). You do not hand that offer to `composeCallTx` as ready-made bytes: you hand it a `zswapOffer` factory, which the composer calls back with each call's guaranteed/fallible split once it has drawn it. That split is the fourth argument `zswapStateToSegmentedOffer` routes by — without it every movement lands in the guaranteed segment, and a circuit whose transcript is wholly fallible produces an offer the wallet cannot balance. Omitting the factory altogether leaves you composing a transaction missing the coin movements the circuit recorded.
 
 The transcript also carries `partitionContext` — the block, the starting effects and the commitment indices the pre-fork query context recorded while the circuit ran. Pass it on unchanged: a transcript composed without it is partitioned against a context the circuit never ran on, and a circuit that RECEIVED a coin in-contract cannot be partitioned at all, because the index its commitment was registered at lives only in that context. `wrapKeepStateCall` carries it for you; a hand-built call entry has to supply it. A context the target era cannot read throws `ComposeFailedError` with `stage: 'call-partition-context'`.
 
@@ -151,7 +162,17 @@ const era = await loadLedgerEra(versionOfRecord(indexerRecord));
 
 const state = era.extractState(rawContractState);
 const decoded = era.decodeContractState(rawContractState);
-const callTx = era.composeCallTx({ calls, networkId, ttl });
+const { transaction, partitions } = era.composeCallTx({
+  calls,
+  networkId,
+  ttl,
+  // Called back ONCE, with one `[guaranteed, fallible]` pair per call, in
+  // `calls` order -- cross-contract callees first, the root call last. Route
+  // against all of them: a transaction carries one offer per segment, so
+  // destructuring the first pair alone would route the whole transaction
+  // against a callee's split and drop the root call's.
+  zswapOffer: (partitions) => buildSegmentedOfferBytes(partitions)
+});
 const deploy = era.composeDeployTx({ contractState, verifierKeys, networkId, ttl });
 ```
 
@@ -160,7 +181,7 @@ const deploy = era.composeDeployTx({ contractState, verifierKeys, networkId, ttl
 | `version` | The era this object is bound to — the value that was passed in |
 | `extractState` | Reads the primary state out of a raw contract-state envelope |
 | `decodeContractState` | Reads an envelope into its state plus the entry points it declares, each with its verifier key and that key's hash |
-| `composeCallTx` | Composes an UNPROVEN call transaction and serializes it |
+| `composeCallTx` | Composes an UNPROVEN call transaction and answers with its bytes plus each call's guaranteed/fallible split |
 | `composeDeployTx` | Composes an UNPROVEN deploy and returns it with the address it will have and the initial state that address came from |
 
 Derive the era with `versionOfRecord` or `networkHeadVersion` (see [Version Module](#version-module)) rather than writing the string by hand. An era string that is not `'v8'` or `'v9'` rejects with `UnknownLedgerVersionError`; the offending value is on the error's `requestedVersion` field, not in its message.
@@ -179,7 +200,7 @@ The same method names mostly mean the same capabilities. One thing the v8 arm re
 
 - **A call tree.** The v8 arm composes exactly one call. A cross-contract call is a ledger-9-only feature a pre-fork contract cannot emit, so that era has no call tree to express: a `calls` list longer than one throws `ComposeOptionError` with `option: 'calls'` rather than composing the first entry and dropping the rest.
 
-**A Zswap offer is not one of them.** Both eras read `guaranteedZswapOffer` / `fallibleZswapOffer` and carry the resulting offer into the transaction; both throw `ComposeOptionError` with `option: 'zswapOffer'` for bytes their own decoder rejects, with the decoder's failure on `cause`. A coin-moving call composes on either era.
+**A Zswap offer is not one of them.** Both eras call the `zswapOffer` factory back with the split they resolved and carry the offer it answers with into the transaction; both throw `ComposeOptionError` with `option: 'zswapOffer'` for bytes their own decoder rejects, with the decoder's failure on `cause`. Both read that offer LAST, after the call's unshielded payout has been aggregated, so a call with two faults is refused the same way on either era. A coin-moving call composes on either era.
 
 The v8 arm also *requires* `verifierKeys` on `composeDeployTx`, where the v9 arm accepts its omission in one case. The retained deploy leg registers the compiled contract's keys onto the initial state itself, so it always needs the map; omitting it throws `ComposeOptionError` with `option: 'verifierKeys'`. The v9 arm allows the omission only for a state that ALREADY carries its keys, and checks rather than assumes it: a state still declaring a blank-keyed entry point throws the same `ComposeOptionError` with the same `option`. So the two arms agree on every input except one — a pre-keyed state, which deploys as-is on v9 and needs its keys supplied again on v8.
 

package/dist/compact-js-v8-effect.d.ts

@@ -0,0 +1 @@
+export * from '@midnight-ntwrk/compact-js/v8/effect';

package/dist/compact-js-v8-effect.js

@@ -0,0 +1,2 @@
+export * from '@midnight-ntwrk/compact-js/v8/effect';
+//# sourceMappingURL=compact-js-v8-effect.js.map

package/dist/compact-js-v8-effect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compact-js-v8-effect.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/dist/engine.d.ts

@@ -1,9 +1,28 @@
 import * as ledgerV9 from '@midnightntwrk/ledger-v9';
-import { CallContext, Effects, CoinCommitment, EncodedStateValue, ContractCallPrototype } from '@midnightntwrk/ledger-v9';
+import { TokenType, EncodedStateValue, CallContext, Effects, CoinCommitment, ContractCallPrototype } from '@midnightntwrk/ledger-v9';
 export { EncodedStateValue } from '@midnightntwrk/ledger-v9';
-import * as OnchainRuntimeV3 from '@midnight-ntwrk/onchain-runtime-v3';
-import { EncodedZswapLocalState, ProofData, ZswapLocalState } from 'compact-runtime-ledger8';
+import { ContractExecutable } from '@midnight-ntwrk/compact-js/v8/effect';
 
+/**
+ * The public balances a contract holds, keyed by token type.
+ *
+ * Derived from the vendor's own `TokenType` rather than restated, so a rename
+ * fails this build instead of leaving a mirror describing a shape neither
+ * runtime has.
+ *
+ * `shared-contract-state.test.ts` pins all three `TokenType` declarations —
+ * both eras' and the execution runtime's, which is where the map actually
+ * lands — mutually assignable. That pin is STRUCTURAL and can be no more:
+ * `raw` is an opaque `string` everywhere, so assignability says the handoff
+ * type-checks and says nothing about two eras reading a given key as the same
+ * colour.
+ *
+ * Plain data end to end — string-tagged objects and `bigint`s — so it crosses
+ * an era boundary like every other member of {@link ContractStatePojo}. That is
+ * a statement about `structuredClone`, which carries a `Map`; a JSON round trip
+ * does NOT, and leaves the plain object the balance guards refuse.
+ */
+type ContractBalance = ReadonlyMap<TokenType, bigint>;
 /**
  * One entry point a contract state declares, with the verifier key registered
  * against it if there is one.
@@ -19,6 +38,27 @@ interface ContractEntryPointPojo {
     readonly verifierKey: Uint8Array | undefined;
     readonly verifierKeyHash: string | undefined;
 }
+/**
+ * A contract state as plain data: the primary state in its encoded form, the
+ * balances the contract holds, and the entry points the state declares.
+ *
+ * `entryPoints` is an ARRAY, not a map keyed by circuit id: two distinct byte
+ * entry points can decode to the same name, and a caller has to reconcile
+ * them.
+ *
+ * @see {@link FailClosedDecoding}
+ */
+interface ContractStatePojo {
+    readonly state: EncodedStateValue;
+    /**
+     * The balances the contract holds, which are NOT part of the primary state:
+     * the ledger keeps them beside it, so a caller reading only `state` cannot
+     * reach them. A retained-era call that executes without them runs every
+     * circuit against an empty balance — see {@link RetainedEraExecution}.
+     */
+    readonly balance: ContractBalance;
+    readonly entryPoints: readonly ContractEntryPointPojo[];
+}
 
 /**
  * The query-context state a call recorded while it ran, which its pre-call
@@ -67,174 +107,150 @@ declare const INITIAL_LEDGER_PARAMETERS = "initial";
  */
 type LedgerParametersOption = Uint8Array | typeof INITIAL_LEDGER_PARAMETERS;
 
-type ChargedState = OnchainRuntimeV3.ChargedState;
-type StateValue = OnchainRuntimeV3.StateValue;
+/** A retained-era signing key: 32 bytes of hex. @see {@link LEDGER8_SIGNING_KEY_PATTERN} */
+type Ledger8SigningKey = string;
 /**
- * The retained runtime's state handle types, under names a consumer can write.
- *
- * `DownConvertedState.data` is an `onchain-runtime-v3` `ChargedState` and
- * `.data.state` a `StateValue`, and neither was nameable outside this package:
- * the aliases above are local, and the vendor package publishes no subpath to
- * import them from. Published because results now carry these handles.
- *
- * TYPE-ONLY, deliberately. `import type` is erased at compile time, so nothing
- * here puts a second copy of the retained runtime on any module graph — the
- * loaders remain the only runtime path to it.
+ * A retained-era contract, as the caller holds it: the CONSTRUCTED artifact the
+ * previous toolchain generates.
+ *
+ * Deliberately not compact-js's `CompiledContract` container. That container is
+ * a recipe — a class plus witnesses, instantiated fresh per operation — and the
+ * retained era's callers hold an instance whose witnesses are already bound.
+ * {@link containerFor} adapts one to the other at this seam, which keeps the
+ * adaptation in one place instead of on every consumer.
  */
-type Ledger8ChargedState = ChargedState;
-/** See {@link Ledger8ChargedState}. */
-type Ledger8StateValue = StateValue;
-
-/**
- * The result of a down-convert: only the primary state data a pre-fork
- * circuit reads during execution.
- *
- * Deliberately not a full pre-fork `ContractState`: it carries no
- * `.operations`, `.maintenanceAuthority` or `.balance`, which remain the
- * caller's to carry.
- *
- * @see {@link RetainedEraExecution}
- */
-interface DownConvertedState {
-    readonly data: ChargedState;
+interface RetainedContract {
+    /** The map compact-js indexes to find the circuit to run. */
+    readonly provableCircuits: Readonly<Record<string, unknown>>;
+    /** The constructor a deployment runs. */
+    initialState(...args: never[]): unknown;
 }
 
-type AlignedValue = OnchainRuntimeV3.AlignedValue;
-type Op<T> = OnchainRuntimeV3.Op<T>;
-
 /**
- * The `QueryContext` slice {@link executeCircuit} reads off a circuit's
- * context: the primary state, ready to be wrapped back into a
- * {@link DownConvertedState}, plus the three members a composition leg needs to
- * partition the call's public transcript against the context it really ran on
- * (see {@link PartitionContext}).
+ * The result of one retained-era circuit call: every artifact
+ * {@link wrapKeepStateCall} (`../v9/wrap.ts`) needs to assemble a v9-native
+ * `ContractCallPrototype`.
  *
- * A `Pick` of the vendor's own class, not a restatement of it: the member names
- * and their types come from onchain-runtime-v3, so a rename there fails this
- * build instead of leaving a mirror that describes a property the runtime no
- * longer has. It stays a narrowing rather than the whole class because
- * `QueryContext` is a WASM class with dozens of members, and this seam reads
- * four — the narrowing is what lets the execution tests hand `executeCircuit` a
- * plain object double instead of standing up real WASM.
- *
- * @see {@link RetainedEraExecution}
- */
-type Ledger8QueryContext = Pick<OnchainRuntimeV3.QueryContext, 'state' | 'block' | 'effects' | 'comIndices'>;
-/**
- * The circuit-context slice {@link executeCircuit} needs from a pre-fork
- * (`compact-runtime@0.16`) `createCircuitContext` call and a circuit's
- * updated context after it runs.
- *
- * Not the glue's `CircuitContext` itself: that one carries a real
- * `QueryContext`, a WASM class no test double can satisfy, and this seam reads
- * a handful of properties off it. The narrowing is the difference between
- * execution tests that check plumbing with a literal and tests that must stand
- * up WASM to do it — see {@link Ledger8QueryContext}, which derives those
- * properties from the vendor's class so the narrowing cannot drift from it.
- *
- * @see {@link RetainedEraExecution}
- */
-interface Ledger8CircuitContext {
-    readonly currentQueryContext: Ledger8QueryContext;
-    readonly currentPrivateState: unknown;
-    readonly currentZswapLocalState: EncodedZswapLocalState;
-}
-/**
- * The proof-data slice of a pre-fork {@link Ledger8CircuitResult}.
- *
- * The vendor's own `ProofData`, not a copy of its four members: it is already
- * plain data with no WASM handle in it, so there was nothing for a mirror to
- * narrow — only a shape to drift out of sync. `Readonly` is this package's own
- * addition, and the only one.
- *
- * @see {@link EraSeam}
- */
-type Ledger8ProofData = Readonly<ProofData>;
-/**
- * What a pre-fork `impureCircuits[id](ctx, ...args)` call returns.
- *
- * Tracks the glue's `CircuitResults` but is not derived from it: `context` is
- * the narrowed {@link Ledger8CircuitContext} for the reason given there, and
- * `proofData` IS the vendor's own type — see {@link Ledger8ProofData}.
- *
- * @see {@link RetainedEraExecution}
- */
-interface Ledger8CircuitResult {
-    readonly result: unknown;
-    readonly proofData: Ledger8ProofData;
-    readonly context: Ledger8CircuitContext;
-}
-/** One callable entry point on a compiled pre-fork contract's `impureCircuits` map. */
-type Ledger8ImpureCircuit = (ctx: Ledger8CircuitContext, ...args: readonly unknown[]) => Ledger8CircuitResult;
-/**
- * The subset of a compiled pre-fork (`compact-runtime@0.16`) contract module
- * {@link executeCircuit} needs: only `impureCircuits`, the map every
- * generated contract exposes its callable entry points under.
- *
- * @see {@link RetainedEraExecution}
- */
-interface Ledger8ContractLike {
-    readonly impureCircuits: Readonly<Record<string, Ledger8ImpureCircuit>>;
-}
-/**
- * The result of one impure circuit's invocation on a pre-fork
- * (`compact-runtime@0.16`) contract instance: the primary result plus every
- * artifact {@link wrapKeepStateCall} (`../v9/wrap.ts`) needs to assemble a
- * v9-native `ContractCallPrototype`.
- *
- * `preContractState`/`postContractState` are {@link DownConvertedState}s, not
- * full pre-fork `ContractState`s: they carry only `.data`. They are also the
- * only members here that are LIVE HANDLES -- every other member of this type is
- * plain data. `postContractStateEncoded` is the post-state's encoded form,
- * carried beside the handle so a caller has a value that outlives the runtime
- * instance; the pre-state's encoded form is the caller's own input, which
- * `downConvertForExecution` already proves round-trips to it.
- *
- * `partitionContext` is the query-context state the call ran with, which the
- * carried state bytes do not hold — see {@link PartitionContext}. A composition
- * leg needs it to partition the call's transcript.
- *
- * `zswapLocalState` is the post-call Zswap local state, DECODED into the
- * runtime's public shape: the coins the circuit spent and produced. A caller
- * turns it into the transaction's segmented Zswap offer
- * (`zswapStateToSegmentedOffer`, `packages/contracts/src/internal/utils/zswap-utils.ts`)
- * and hands that offer to whichever composition leg it targets.
+ * `preContractState` and `postContractState` are LIVE HANDLES from the retained
+ * runtime; every other member is plain data. `postContractStateEncoded` is the
+ * post-state's encoded form, carried beside the handle so a caller has a value
+ * that outlives the runtime instance.
  *
  * @see {@link RetainedEraExecution}
  */
 interface TranscriptPojo {
     readonly circuitId: string;
     readonly result: unknown;
-    readonly input: AlignedValue;
-    readonly output: AlignedValue;
-    readonly publicTranscript: Op<AlignedValue>[];
-    readonly privateTranscriptOutputs: AlignedValue[];
-    readonly preContractState: DownConvertedState;
-    readonly postContractState: DownConvertedState;
+    readonly input: ContractExecutable.ContractExecutable.ContractCallPrivate['input'];
+    readonly output: ContractExecutable.ContractExecutable.ContractCallPrivate['output'];
+    readonly publicTranscript: ContractExecutable.ContractExecutable.ContractCallPublic['publicTranscript'];
+    readonly privateTranscriptOutputs: ContractExecutable.ContractExecutable.ContractCallPrivate['privateTranscriptOutputs'];
+    /**
+     * The state the call BOUND to, i.e. `partitionInputs.state`.
+     *
+     * Indistinguishable from {@link TranscriptPojo.postContractState} BY TYPE:
+     * compact-js resolves both to the same declaration, so swapping the two is
+     * not a compile error. Partitioning against the wrong one rejects a state the
+     * transcript's reads do not fit, or silently mis-charges one that merely
+     * differs in value, so the distinction rests on the member name alone.
+     */
+    readonly preContractState: ContractExecutable.ContractExecutable.CallPartitionInputs['state'];
+    /**
+     * The state the call LEFT, i.e. compact-js's own `contractState`.
+     *
+     * See {@link TranscriptPojo.preContractState}: the two are the same type.
+     */
+    readonly postContractState: ContractExecutable.ContractExecutable.ContractCallPublic['contractState'];
     /**
      * The post-call state as an {@link EncodedStateValue}: the same value
      * {@link postContractState} holds, in the form that survives this process.
      *
-     * `EncodedStateValue` is pinned identical across `onchain-runtime-v3`,
-     * `ledger-v8` and `ledger-v9` -- see this package's README and the
-     * cross-runtime assertions in `src/test/v8-down-convert.test.ts` -- so this is
-     * the member era-agnostic code reads, and the one that can be persisted,
-     * cloned or sent to a worker.
+     * `EncodedStateValue` is pinned identical across the retained and current
+     * runtimes, so this is the member era-agnostic code reads, and the one that
+     * can be persisted, cloned or sent to a worker.
      */
     readonly postContractStateEncoded: EncodedStateValue;
     readonly privateStateAfter: unknown;
     readonly partitionContext: PartitionContext;
-    readonly zswapLocalState: ZswapLocalState;
+    readonly zswapLocalState: ContractExecutable.ContractExecutable.DeployResultPrivate<unknown>['zswapLocalState'];
+}
+/** The freshly built state a retained-era constructor produced. */
+interface ConstructorResultPojo {
+    readonly contractState: ContractExecutable.ContractExecutable.DeployResultPublic['contractState'];
+    readonly privateState: unknown;
+    readonly zswapLocalState: ContractExecutable.ContractExecutable.DeployResultPrivate<unknown>['zswapLocalState'];
+    /**
+     * The key the state's maintenance authority was built from: the caller's own
+     * when one was named, otherwise the one compact-js sampled.
+     *
+     * REQUIRED, unlike the request's, and that asymmetry is the point — a sampled
+     * key exists nowhere else, so a result that did not report it would leave the
+     * deployment as unmaintainable as the empty committee the retained
+     * constructor writes on its own.
+     */
+    readonly signingKey: Ledger8SigningKey;
 }
-/** Everything {@link executeCircuit} needs to run one impure circuit call. */
-interface ExecuteCircuitOptions {
-    readonly contract: Ledger8ContractLike;
+/**
+ * Reads verifier keys for the entry points a contract declares.
+ *
+ * A plain function rather than compact-js's `ZKConfiguration` service, so no
+ * Effect type reaches this package's callers; {@link zkConfigurationLayer}
+ * adapts it at the seam.
+ */
+type VerifierKeyReader = (provableCircuitId: string) => Promise<Uint8Array | undefined>;
+/** Everything {@link runRetainedCircuit} needs to run one circuit. */
+interface RunRetainedCircuitOptions<C extends RetainedContract, PS> {
+    readonly contract: C;
     readonly circuitId: string;
     readonly args: readonly unknown[];
-    readonly state: DownConvertedState;
+    /**
+     * The contract state the call runs against, DECODED — the primary state in
+     * its era-neutral encoded form, with the balances the contract holds beside
+     * it.
+     *
+     * Era-neutral rather than one era's serialized bytes, because a contract that
+     * an earlier post-fork call has already migrated carries a CURRENT-era
+     * envelope while still executing on the retained runtime. Chain bytes would
+     * have to be decoded by the era that wrote them; this shape is what both
+     * envelopes' readers produce, so one path serves a pre-fork contract and a
+     * migrated one alike.
+     *
+     * The balance travels on the same value, so the two halves cannot come off
+     * different reads. {@link executableStateFrom} writes it onto a whole
+     * `ContractState`, which is the only form the retained runtime reads a
+     * balance from — handed a bare state value it substitutes an empty map, and a
+     * circuit reading a balance then executes against nothing with every guard
+     * green. That substitution is what #1345 was.
+     */
+    readonly contractState: ContractStatePojo;
     readonly address: string;
     readonly coinPk: string;
-    readonly privateState: unknown;
+    readonly privateState: PS;
+    /**
+     * The execution clock, in SECONDS since the epoch. Omitted, the wall clock is
+     * used.
+     *
+     * Lands on the query context's `block.secondsSinceEpoch`, which
+     * {@link TranscriptPojo.partitionContext} reports — so without pinning it a
+     * recorded fixture differs on every run
+     * (midnightntwrk/midnight-sdk#403).
+     */
+    readonly nowSeconds?: number;
+}
+/** Everything {@link runRetainedConstructor} needs to run one constructor. */
+interface RunRetainedConstructorOptions<C extends RetainedContract, PS> {
+    readonly contract: C;
+    readonly args: readonly unknown[];
+    readonly privateState: PS;
+    readonly coinPk: string;
+    /**
+     * The key the contract's maintenance authority is built from. Optional:
+     * compact-js samples one when it is absent, and the result reports whichever
+     * was used.
+     */
+    readonly signingKey?: Ledger8SigningKey;
+    /** Reads the verifier key for each entry point the constructor registers. */
+    readonly verifierKeys: VerifierKeyReader;
 }
 
 /**
@@ -262,75 +278,48 @@ interface WrapKeepStateCallOptions {
 }
 
 /**
- * The minimal shape a pre-fork (`compact-runtime@0.16`) `ContractState` is used
- * through here: just `.serialize()`. It is what {@link executeConstructor}
- * returns on its result, and `.serialize()` is how a caller turns that handle
- * into the bytes every deploy leg takes.
+ * The public surface {@link createLedger8Engine} builds: the retained pre-fork
+ * EXECUTION capabilities.
  *
- * Crosses the era boundary by bytes, not by handle.
+ * The two execution members are ASYNCHRONOUS. They used to be synchronous, and
+ * the docblock here used to promise it: compact-js builds a circuit call on
+ * `Effect.tryPromise`, so `runSync` cannot discharge it and the promise is not
+ * satisfiable. Nothing else about the surface changed shape -- every value
+ * crossing it is still plain data or an era handle, and no `Effect` reaches a
+ * caller.
  *
- * @see {@link DualInstantiationGuard} for why that crossing is the one a
- *      duplicate install cannot affect
  * @see {@link EraSeam}
  */
-type Ledger8DeployableContractState = Pick<OnchainRuntimeV3.ContractState, 'serialize'>;
-/** What a pre-fork `contract.initialState(constructorContext, ...args)` call returns. */
-interface Ledger8ConstructorResult {
-    readonly currentContractState: Ledger8DeployableContractState;
-    readonly currentPrivateState: unknown;
+interface Ledger8Engine {
     /**
-     * The Zswap local state the constructor ended on, still ENCODED. A
-     * constructor that mints a coin records it here, and a deploy that drops it
-     * composes a transaction the ledger cannot balance.
+     * Runs one circuit against the decoded contract state the chain serves.
+     *
+     * Takes the state and the balances beside it as ONE value -- see
+     * {@link RunRetainedCircuitOptions.contractState} -- because the balances a
+     * circuit reads do not live inside the primary state, and two separate
+     * options could describe two different blocks.
+     *
+     * @throws DownConvertFailedError At stage `'state down-convert'` when the
+     *   state cannot be decoded, does not re-encode to its source, or carries a
+     *   balance the retained runtime cannot read.
+     * @throws Error When the contract declares no circuit of that name.
      */
-    readonly currentZswapLocalState: EncodedZswapLocalState;
-}
-/**
- * The subset of a compiled pre-fork (`compact-runtime@0.16`) contract module
- * {@link executeConstructor} needs: only `initialState`, the constructor
- * every generated contract exposes to build its initial ledger state.
- */
-interface Ledger8ConstructorContractLike {
-    readonly initialState: (constructorContext: unknown, ...args: readonly unknown[]) => Ledger8ConstructorResult;
-}
-/** Everything {@link executeConstructor} needs to run one contract constructor. */
-interface ExecuteConstructorOptions {
-    readonly contract: Ledger8ConstructorContractLike;
-    readonly args: readonly unknown[];
-    readonly privateState: unknown;
-    readonly coinPk: string;
-}
-/**
- * The result of running a pre-fork constructor: the freshly built contract
- * state (still carrying blank verifier keys on every operation slot — see
- * {@link composeV8DeployTx}) and the resulting private state.
- */
-interface ConstructorResultPojo {
-    readonly contractState: Ledger8DeployableContractState;
-    readonly privateState: unknown;
+    executeCircuit<C extends RetainedContract, PS>(options: RunRetainedCircuitOptions<C, PS>): Promise<TranscriptPojo>;
     /**
-     * The constructor's own Zswap local state, DECODED — plain data in both
-     * runtimes. Empty for the ordinary constructor that mints nothing; carries
-     * the outputs for one that does, which is what lets the deploy be balanced.
+     * Runs one retained-era constructor and returns the state it built.
+     *
+     * ASYNCHRONOUS for the same reason {@link Ledger8Engine.executeCircuit} is.
+     * Stricter than the leg it replaced: compact-js registers a verifier key
+     * against every declared entry point and refuses a missing one, where the
+     * hand-written constructor left every slot blank.
+     *
+     * @throws ComposeOptionError Naming option `'signingKey'` when a supplied key
+     *   is not the 32 bytes of hex the retained runtime reads.
+     * @throws ComposeFailedError At stage `'deploy-verifier-key-blob'` when the
+     *   ledger refuses the bytes served for a circuit.
      */
-    readonly zswapLocalState: ZswapLocalState;
-}
-
-/**
- * The public surface {@link createLedger8Engine} builds: the retained pre-fork
- * EXECUTION capabilities, with the 0.16 runtime instance already captured in
- * closure — no method here takes a runtime or module parameter.
- *
- * Every method is synchronous: this object is handed over only after the
- * retained toolchain has been acquired.
- *
- * @see {@link EraSeam}
- */
-interface Ledger8Engine {
-    downConvertForExecution(state: EncodedStateValue): DownConvertedState;
-    executeCircuit(options: ExecuteCircuitOptions): TranscriptPojo;
+    executeConstructor<C extends RetainedContract, PS>(options: RunRetainedConstructorOptions<C, PS>): Promise<ConstructorResultPojo>;
     wrapKeepStateCall(options: WrapKeepStateCallOptions): ContractCallPrototype;
-    executeConstructor(options: ExecuteConstructorOptions): ConstructorResultPojo;
     /**
      * Re-expresses a retained-era contract's entry points as a current-era contract state, so a
      * keep-state call has an operation registry the current composer can read.
@@ -341,27 +330,28 @@ interface Ledger8Engine {
     reexpressOperationsForCurrentEra(entryPoints: readonly ContractEntryPointPojo[]): Uint8Array;
 }
 /**
- * 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}
  */
 declare const createLedger8Engine: () => Promise<Ledger8Engine>;
 
 export { createLedger8Engine };
-export type { ConstructorResultPojo, ContractEntryPointPojo, DownConvertedState, ExecuteCircuitOptions, ExecuteConstructorOptions, Ledger8ChargedState, Ledger8DeployableContractState, Ledger8Engine, Ledger8StateValue, TranscriptPojo, WrapKeepStateCallOptions };
+export type { ConstructorResultPojo, ContractBalance, ContractEntryPointPojo, ContractStatePojo, Ledger8Engine, Ledger8SigningKey, RetainedContract, RunRetainedCircuitOptions, RunRetainedConstructorOptions, TranscriptPojo, VerifierKeyReader, WrapKeepStateCallOptions };