@midnight-ntwrk/midnight-js-protocol 5.0.0-beta.7 → 5.0.0-beta.8-pre.765ca083

package/README.md

@@ -32,7 +32,11 @@ import { createPlatform } from '@midnight-ntwrk/midnight-js-protocol/platform-js
 
 | Sub-path | Re-exports | Description |
 | -------- | ---------- | ----------- |
+| `./errors` | (own) | `PROTOCOL_ERROR_CODES` and every error class and error type this package raises — without pulling in the ledger/compact-js/onchain-runtime/platform namespaces. `protocol-acl.test.ts` pins the exact list |
+| `./version` | (own) | `LEDGER_VERSIONS`, `protocolVersionToLedger`, `versionOfRecord`, `networkHeadVersion` and the types `LedgerVersion`, `ProtocolVersionSource`, `VersionedRecord` — same lightweight guarantee as `./errors` |
 | `./ledger` | `@midnightntwrk/ledger-v9` | Ledger types and transaction primitives |
+| `./v8` | `@midnightntwrk/ledger-v8` | Previous-era (v8) ledger — do not import at runtime; use `loadLedger8()` |
+| `./engine` | (own) | Retained pre-fork execution engine — do not import at runtime; use `loadLedger8Engine()` |
 | `./compact-runtime` | `@midnight-ntwrk/compact-runtime` | Compact contract runtime utilities |
 | `./compact-js` | `@midnight-ntwrk/compact-js` | Compact JS bindings |
 | `./compact-js/effect` | `@midnight-ntwrk/compact-js/effect` | Effect-based Compact bindings |
@@ -42,13 +46,208 @@ import { createPlatform } from '@midnight-ntwrk/midnight-js-protocol/platform-js
 | `./platform-js/effect/Configuration` | `@midnight-ntwrk/platform-js/effect/Configuration` | Effect-based configuration |
 | `./platform-js/effect/ContractAddress` | `@midnight-ntwrk/platform-js/effect/ContractAddress` | Effect-based contract address resolution |
 
+## Source Layout
+
+Nothing under `src/lib/` is a build entry, so this layout is internal and no consumer import path depends on it. Its job is to make one question answerable from a path alone: *which ledger does this touch?*
+
+| 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/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 |
+
+The directory names say what a module is **about**, not what it links. Three consequences a reader should not have to derive:
+
+- **`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.
+
+`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.
+
+## Architecture Documents
+
+The reasoning behind this package's shape lives in `docs/`, not in the source
+docstrings. Each file is registered with TypeDoc through `projectDocuments`, so
+it is a page in the generated API reference and `@see {@link Title}` in a
+docstring resolves to it.
+
+| Document | What it explains |
+|---|---|
+| [Era seam](./docs/era-seam.md) | Why only bytes and plain objects cross between the eras, how the eight operations are split between `LedgerEra` and `Ledger8Engine`, and the memoisation rules |
+| [Retained-era execution](./docs/retained-era-execution.md) | The down-conversion stages, the Merkle rehash requirement, the era pin, and what a `TranscriptPojo` carries |
+| [Dual-instantiation guard](./docs/dual-instantiation-guard.md) | What a duplicate WASM install does in the argument position versus the receiver position, and why the guard is a correctness requirement rather than a diagnostic |
+| [Fail-closed decoding](./docs/fail-closed-decoding.md) | Why the envelope is the only authority over the bytes, and the division of labour between the three decode failures |
+| [Compose refusal order](./docs/compose-refusal-order.md) | The order in which both era arms refuse compose options, and the one deliberate difference between them |
+| [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 |
+| [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
+parameters, what it returns and what it throws. Anything that answers "why is
+it built this way" belongs in a document above, stated once.
+
+## Accessing the v8 Ledger Era
+
+The `./v8` subpath re-exports the previous-era ledger (`@midnightntwrk/ledger-v8`), which carries its own WASM. To keep that WASM out of eagerly-loaded module graphs, runtime imports of `@midnight-ntwrk/midnight-js-protocol/v8` are blocked by ESLint everywhere outside this package. Use the lazy accessor instead:
+
+```typescript
+import { loadLedger8 } from '@midnight-ntwrk/midnight-js-protocol';
+
+const v8 = await loadLedger8();
+const transaction = v8.Transaction.deserialize(rawTransaction);
+```
+
+Type-only imports of the subpath are allowed:
+
+```typescript
+import type { Transaction } from '@midnight-ntwrk/midnight-js-protocol/v8';
+```
+
+If the v8 module cannot be loaded (usually a broken or partial install), `loadLedger8()` rejects with `Ledger8RuntimeMissingError` (code `MIDNIGHT_JS_P_LEDGER8_RUNTIME_MISSING`) carrying the original error as `cause`. Its `subpath` field is `'/v8'`, naming which chunk failed. The failed load is not memoised — the next call retries.
+
+## Running Contracts on the Retained Pre-Fork Engine
+
+Contracts compiled against the pre-fork toolchain keep executing on `compact-runtime@0.16` after the fork. That toolchain and its `onchain-runtime-v3` WASM live behind the `./engine` subpath, gated the same way as `./v8` and for the same reason. `loadLedger8Engine()` is the only sanctioned runtime path to it:
+
+```typescript
+import { loadLedger8Engine, loadLedgerEra, versionOfRecord } from '@midnight-ntwrk/midnight-js-protocol';
+
+const engine = await loadLedger8Engine();
+const era = await loadLedgerEra(versionOfRecord(indexerRecord));
+
+const state = engine.downConvertForExecution(era.extractState(rawContractState));
+const transcript = engine.executeCircuit({
+  contract,
+  circuitId: 'increment',
+  args: [],
+  state,
+  address: contractAddress,
+  coinPk: coinPublicKey,
+  privateState
+});
+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.
+
+`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.
+
+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'`.
+
+A failure to load the chunk itself rejects with `Ledger8RuntimeMissingError` whose `subpath` is `'/engine'`; read `cause` for which module actually failed to resolve.
+
+## Ledger-Era Facade
+
+Two ledger eras are live at once: `v8` backs the node 1.x line and `v9` the 2.x line. `loadLedgerEra` hands you one of them as a single object with the same methods on both, so code that has resolved which era a record belongs to does not then have to branch on it.
+
+```typescript
+import { loadLedgerEra, versionOfRecord } from '@midnight-ntwrk/midnight-js-protocol';
+
+const era = await loadLedgerEra(versionOfRecord(indexerRecord));
+
+const state = era.extractState(rawContractState);
+const decoded = era.decodeContractState(rawContractState);
+const callTx = era.composeCallTx({ calls, networkId, ttl });
+const deploy = era.composeDeployTx({ contractState, verifierKeys, networkId, ttl });
+```
+
+| Method | What it does |
+| ------ | ------------ |
+| `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 |
+| `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.
+
+Each era is memoised, so the retained pre-fork WASM is instantiated at most once per process. Asking for `'v8'` is what acquires it — a consumer that only ever asks for `'v9'` never loads it at all, which is gated by `dist-laziness.test.ts`. A **failed** v8 acquisition is not memoised: the rejection propagates unchanged as `Ledger8RuntimeMissingError` and the next call retries.
+
+### Only bytes and plain objects cross this boundary
+
+Every value going in or coming out is plain data — `Uint8Array`s and plain objects — never a live WASM handle. A contract state goes in as the bytes it was serialized to and comes back as an `EncodedStateValue` plus plain entry-point records; a composed transaction comes back as bytes. So a result can be stored, compared across eras, or sent through a `structuredClone` or a worker boundary without the module that produced it. `era-parity.test.ts` asserts exactly that, on every method, for both eras.
+
+Because the methods are synchronous, all the awaiting happens once, at `loadLedgerEra`.
+
+### Where the two eras differ
+
+The same method names mostly mean the same capabilities. One thing the v8 arm refuses that the v9 arm accepts:
+
+- **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.
+
+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.
+
+What is *not* asymmetric: a call's user-addressed unshielded payouts are aggregated onto the transaction's guaranteed and fallible offers on **both** eras. Attaching them on one era only would leave the other composing an unbalanced transaction the node rejects on submission, with nothing having reported a problem at composition time — so `era-parity.test.ts` asserts the payout each segment carries, per era.
+
+### Errors
+
+| Error | Code | Raised when |
+| ----- | ---- | ----------- |
+| `StateDecodeFailedError` | `MIDNIGHT_JS_P_STATE_DECODE_FAILED` | A contract-state envelope could not be read by the era it was requested for — most often a state written by the other era |
+| `ComposeFailedError` | `MIDNIGHT_JS_P_COMPOSE_FAILED` | Something about a CALL or a DEPLOY could not be composed: an operation that is missing, unkeyed, or names a circuit the contract does not declare; an empty call list; a pre-call state or a recorded query context the era cannot bridge; a supplied transcript with neither half; a public transcript or a set of call inputs the ledger itself rejected; or a claimed payout the transaction cannot settle (dust, or a shielded token type). `stage` is a closed union naming which of those it was — see its own docs for the full list; `version` names the era |
+| `ComposeOptionError` | `MIDNIGHT_JS_P_COMPOSE_OPTION_INVALID` | A transaction-wide OPTION cannot be used at all — an empty network id, an invalid ttl, a contract state whose envelope the era rejected, an offer the era's decoder rejected, a missing verifier-key map, or a call list longer than the era can compose. `option` names the field, `version` names the era |
+| `UnknownLedgerVersionError` | `MIDNIGHT_JS_P_UNKNOWN_LEDGER_VERSION` | The requested era is not `'v8'` or `'v9'` |
+
+Each names the era it was raised for — `version` on the first three, `requestedVersion` on `UnknownLedgerVersionError`, which also takes no `cause`. None renders hex or a byte dump of its own, and the first three preserve the underlying runtime failure on `cause` where there was one.
+
+### Planned follow-ups
+
+Recorded here so the reasoning is not lost, and deliberately NOT done in the change that introduced this facade:
+
+- **Collapse the version dispatch in `lib/era/envelope.ts`.** `extractEncodedStateValue` has one production caller, which passes the literal `'v8'`; the v9 arm calls `extractV9EncodedStateValue` directly. The decoder table, the unknown-version guard and the null-prototype defence are therefore only reachable from tests, and the per-file 100% floor keeps the tests that reach them alive. Collapsing it to a `extractV8EncodedStateValue` beside the v9 one deletes real tests, which belongs in its own change.
+- **Give `StateDecodeFailedError` a `stage`.** `decodeContractStateWith` wraps the whole read, so a state that decoded fine but declares an entry point resolving to no operation is reported with the same code and the same "resolve the era and check the bytes" remediation as an envelope written by the other era. A discriminator would separate them; it is a public error-shape change.
+- **Give `ComposeOptionError` a `circuitId`.** The v9 blank-key refusal knows which entry point was blank and cannot say so, because the field does not exist. Adding it would let that refusal name the slot without breaking the class parity the two arms currently have.
+
+## Version Module
+
+Mapping a raw `protocolVersion` integer onto the ledger runtime it corresponds to. Reachable from the root barrel and, without loading the ledger/compact-js/onchain-runtime/platform namespaces, from the `./version` subpath. The error it throws is reachable from `./errors` on the same terms.
+
+The `protocolVersion` integer encodes the **node** version as `major * 1_000_000 + minor * 1_000 + patch`, so a whole node major occupies a 1_000_000-wide range:
+
+| protocolVersion range | node version | ledger |
+| --------------------- | ------------ | ------ |
+| 1_000_000 – 1_999_999 | 1.x          | v8     |
+| 2_000_000 – 2_999_999 | 2.x          | v9     |
+
+Anything outside those ranges throws rather than guessing. Node 0.x is deliberately absent: the indexer's own table does map it, but midnight-js meets only node 1.x or 2.x, so a 0.x `protocolVersion` is reported as unknown rather than silently resolved.
+
+```typescript
+import {
+  LEDGER_VERSIONS,          // readonly ['v8', 'v9']
+  protocolVersionToLedger,  // (protocolVersion: number, path?: 'read' | 'construct') => 'v8' | 'v9'   (path defaults to 'construct')
+  versionOfRecord,          // (record: { protocolVersion: number }) => 'v8' | 'v9'
+  networkHeadVersion        // (source: { queryLatestProtocolVersion(): Promise<number> }) => Promise<'v8' | 'v9'>
+} from '@midnight-ntwrk/midnight-js-protocol/version';
+import { UnknownProtocolVersionError } from '@midnight-ntwrk/midnight-js-protocol/errors';
+```
+
+Prefer `versionOfRecord` for a `protocolVersion` already read off an indexer/node record, and `networkHeadVersion` for the network's current head version — both tag any error with the correct path automatically. `UnknownProtocolVersionError` carries a `reason` of `'malformed'` (the input was not a non-negative integer) or `'unknown'` (a well-formed integer outside every mapped range), so callers can distinguish "bad input" from "genuinely unsupported protocol version".
+
 ## ESLint Enforcement
 
-An ESLint `no-restricted-imports` rule prevents direct imports of the underlying protocol packages outside of this package. If you see an error like:
+Three rules in the repo's `eslint.config.mjs` govern how other packages reach protocol internals.
+
+**1. The protocol ACL** — a `no-restricted-imports` rule prevents direct imports of the underlying protocol packages outside of this package. If you see an error like:
 
 > Import from `@midnight-ntwrk/midnight-js-protocol/ledger` instead.
 
-Replace the direct protocol import with the corresponding subpath from this package.
+Replace the direct protocol import with the corresponding subpath from this package. For the v8 era specifically, the error
+
+> Runtime v8 access only via loadLedger8() from @midnight-ntwrk/midnight-js-protocol.
+
+means: replace the direct `./v8` runtime import with `loadLedger8()` (type-only imports stay as they are).
+
+**2. The v8 static-import gate** — `@typescript-eslint/no-restricted-imports` blocks runtime imports of `@midnight-ntwrk/midnight-js-protocol/v8` outside `packages/protocol/src/`. Type-only imports (`import type`) are allowed.
+
+**3. The v8 dynamic-import gate** — `no-restricted-syntax` selectors block `import('@midnight-ntwrk/midnight-js-protocol/v8')` in the same scopes. An interpolated template literal cannot be matched statically and is not covered.
+
+Both v8 gates point at `loadLedger8()`, the accessor on the root barrel — the only sanctioned runtime path to the v8 era.
 
 ## Resources
 

package/dist/engine.d.ts

@@ -0,0 +1,367 @@
+import * as ledgerV9 from '@midnightntwrk/ledger-v9';
+import { CallContext, Effects, CoinCommitment, EncodedStateValue, 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';
+
+/**
+ * One entry point a contract state declares, with the verifier key registered
+ * against it if there is one.
+ *
+ * `verifierKey` and `verifierKeyHash` are both absent for a blank slot — the
+ * shape a constructor-built state has before a deploy fills it in.
+ *
+ * @see {@link FailClosedDecoding} for why they are absent rather than
+ * zero-length or a hash of nothing.
+ */
+interface ContractEntryPointPojo {
+    readonly circuitId: string;
+    readonly verifierKey: Uint8Array | undefined;
+    readonly verifierKeyHash: string | undefined;
+}
+
+/**
+ * The query-context state a call recorded while it ran, which its pre-call
+ * state bytes do not carry.
+ *
+ * `block` and `effects` are the PRE-call values; `comIndices` is the POST-call
+ * map. Plain data on every member.
+ *
+ * @see {@link ComposeRefusalOrder} for why partitioning needs the context the
+ * circuit actually ran on, and why `CallContext` and `Effects` are declared
+ * once against ledger-v9.
+ * @see {@link RetainedEraExecution} for why each member is read off the
+ * context it is.
+ * @see {@link EraSeam}
+ */
+interface PartitionContext {
+    readonly block: CallContext;
+    readonly effects: Effects;
+    /** Commitment -> the index the runtime recorded it at. Empty for a call that received no coin. */
+    readonly comIndices: ReadonlyMap<CoinCommitment, bigint>;
+}
+/**
+ * The sentinel that asks for the ledger's own INITIAL cost model instead of the chain's.
+ *
+ * Spelled out as a value a caller has to name, because the thing it selects is wrong for any chain
+ * that has been running: the initial parameters are the model the chain started with, and prices
+ * adjust per block. Partitioning against them draws the guaranteed/fallible boundary in the wrong
+ * place and the node then refuses the guaranteed segment with `Transcript(Execution(OutOfGas))` --
+ * after the caller has already paid to prove it.
+ */
+declare const INITIAL_LEDGER_PARAMETERS = "initial";
+/**
+ * What a composer accepts for the block's ledger parameters: the chain's own serialized parameters,
+ * or {@link INITIAL_LEDGER_PARAMETERS}.
+ *
+ * There is deliberately no third option. This used to be optional, and omitting it fell back to the
+ * initial parameters silently -- so a caller that simply forgot got the wrong cost model with no
+ * signal, and a `PublicDataProvider` that does not serve `ledgerParameters` (the field is optional)
+ * degraded every call built through it. Requiring the option keeps the compatibility path reachable
+ * only as a decision, never as an oversight.
+ *
+ * A caller that reads the chain must pass the bytes from the SAME read as the contract state: the
+ * parameters are era-tagged and dated per block, so a second read could answer for another block.
+ *
+ * @see {@link EraSeam}
+ */
+type LedgerParametersOption = Uint8Array | typeof INITIAL_LEDGER_PARAMETERS;
+
+type ChargedState = OnchainRuntimeV3.ChargedState;
+type StateValue = OnchainRuntimeV3.StateValue;
+/**
+ * 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.
+ */
+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;
+}
+
+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}).
+ *
+ * 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.
+ *
+ * @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;
+    /**
+     * 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.
+     */
+    readonly postContractStateEncoded: EncodedStateValue;
+    readonly privateStateAfter: unknown;
+    readonly partitionContext: PartitionContext;
+    readonly zswapLocalState: ZswapLocalState;
+}
+/** Everything {@link executeCircuit} needs to run one impure circuit call. */
+interface ExecuteCircuitOptions {
+    readonly contract: Ledger8ContractLike;
+    readonly circuitId: string;
+    readonly args: readonly unknown[];
+    readonly state: DownConvertedState;
+    readonly address: string;
+    readonly coinPk: string;
+    readonly privateState: unknown;
+}
+
+/**
+ * Everything {@link wrapKeepStateCall} needs to wrap one keep-state call.
+ * `contractState` is the migrated, post-fork v9 `ContractState` — read from
+ * chain, or otherwise carrying the contract's real registered operations —
+ * used only to look up the `ContractOperation` for `transcript.circuitId`
+ * (mirrors `ComposeV8CallOptions`'s `contractState` parameter in
+ * `../v8/compose.ts`).
+ */
+interface WrapKeepStateCallOptions {
+    readonly transcript: TranscriptPojo;
+    readonly contractAddress: string;
+    readonly contractState: ledgerV9.ContractState;
+    /**
+     * The ledger parameters of the block this call is built against, or
+     * {@link INITIAL_LEDGER_PARAMETERS} to accept the initial cost model.
+     *
+     * Required rather than defaulted, and not hard-coded to the initial parameters here: the
+     * transcript crosses as `'unpartitioned'`, so the partitioner DOES run and the cost model it uses
+     * is whatever this supplies. Defaulting it would make this function the silent
+     * wrong-cost-model path the option exists to close. See {@link LedgerParametersOption}.
+     */
+    readonly ledgerParameters: LedgerParametersOption;
+}
+
+/**
+ * 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.
+ *
+ * Crosses the era boundary by bytes, not by handle.
+ *
+ * @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;
+    /**
+     * 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.
+     */
+    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;
+    /**
+     * 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.
+     */
+    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;
+    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.
+     *
+     * Fork-crossing work, which is why it sits here rather than on either era facade: the input is
+     * what the retained decoder read off the chain, and the output is for the current ledger.
+     */
+    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.
+ * @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 };