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

package/dist/index.d.ts

@@ -1,10 +1,1286 @@
+import * as ledgerV9 from '@midnightntwrk/ledger-v9';
+import { EncodedStateValue, Op as Op$1, AlignedValue as AlignedValue$1, CallContext, Effects, CoinCommitment, Transcript, ContractCallPrototype } from '@midnightntwrk/ledger-v9';
+export { ledgerV9 as ledger };
+export { EncodedStateValue } from '@midnightntwrk/ledger-v9';
+import * as ledgerV8 from '@midnightntwrk/ledger-v8';
+import * as OnchainRuntimeV3 from '@midnight-ntwrk/onchain-runtime-v3';
+import { EncodedZswapLocalState, ProofData, ZswapLocalState } from 'compact-runtime-ledger8';
 import * as compactJs from '@midnight-ntwrk/compact-js';
 export { compactJs };
 import * as compactRuntime from '@midnight-ntwrk/compact-runtime';
 export { compactRuntime };
 import * as platformJs from '@midnight-ntwrk/platform-js';
 export { platformJs as platform };
-import * as ledgerV9 from '@midnightntwrk/ledger-v9';
-export { ledgerV9 as ledger };
 import * as onchainRuntimeV4 from '@midnightntwrk/onchain-runtime-v4';
 export { onchainRuntimeV4 as onchainRuntime };
+
+function _mergeNamespaces(n, m) {
+  m.forEach(function (e) {
+    e && typeof e !== 'string' && !Array.isArray(e) && Object.keys(e).forEach(function (k) {
+      if (k !== 'default' && !(k in n)) {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  });
+  return Object.freeze(n);
+}
+
+/**
+ * The two ledger runtimes midnight-js can talk to. `v8` backs the node 1.x
+ * line; `v9` backs the 2.x line. This is a closed, exhaustive set — see
+ * `protocolVersionToLedger` (`../version.ts`) for how a raw `protocolVersion`
+ * integer maps onto it.
+ *
+ * @see {@link SharedTableDiscipline} for why the array is frozen.
+ * @see {@link ModuleGraphAndLazyLoading} for why the constant is declared in
+ * this leaf module and re-exported by `../version.ts`.
+ */
+declare const LEDGER_VERSIONS: readonly ["v8", "v9"];
+type LedgerVersion = (typeof LEDGER_VERSIONS)[number];
+/**
+ * The era whose objects this build hands out live, through `./ledger`.
+ *
+ * A protocol fact rather than a consumer's choice: it is decided by which
+ * ledger the package links eagerly, and every other era is reached lazily and
+ * crosses package boundaries as bytes. Declared here so that no package
+ * downstream restates "which era is now" as a literal of its own.
+ *
+ * The type is the single literal, not {@link LedgerVersion}, so a value typed
+ * by it DISCRIMINATES — the same discipline `CurrentPipelineEra` follows in
+ * `midnight-js-contracts`.
+ */
+declare const CURRENT_LEDGER_VERSION: "v9";
+type CurrentLedgerVersion = typeof CURRENT_LEDGER_VERSION;
+/**
+ * Every era this build still speaks but does not run live — the eras that
+ * cross a package boundary as serialized bytes.
+ *
+ * Defined as the complement of {@link CURRENT_LEDGER_VERSION}, so a further
+ * era joins this set by being added to {@link LEDGER_VERSIONS} and nothing
+ * else. The value list below is checked against that complement at build time.
+ */
+type RetainedLedgerVersion = Exclude<LedgerVersion, CurrentLedgerVersion>;
+declare const RETAINED_LEDGER_VERSIONS: readonly ["v8"];
+
+/**
+ * Stable error-code strings for this package. Every error class in this module
+ * carries one of these on its `code` field, which is the field a consumer
+ * switches on to tell one failure from another.
+ *
+ * @see {@link SharedTableDiscipline}
+ */
+declare const PROTOCOL_ERROR_CODES: Readonly<{
+    readonly UNKNOWN_PROTOCOL_VERSION_READ: "MIDNIGHT_JS_P_UNKNOWN_PROTOCOL_VERSION_READ";
+    readonly UNKNOWN_PROTOCOL_VERSION_CONSTRUCT: "MIDNIGHT_JS_P_UNKNOWN_PROTOCOL_VERSION_CONSTRUCT";
+    readonly LEDGER8_INSTANCE_MISMATCH: "MIDNIGHT_JS_P_LEDGER8_INSTANCE_MISMATCH";
+    readonly LEDGER8_RUNTIME_MISSING: "MIDNIGHT_JS_P_LEDGER8_RUNTIME_MISSING";
+    readonly DOWN_CONVERT_FAILED: "MIDNIGHT_JS_P_DOWN_CONVERT_FAILED";
+    readonly MERKLE_NOT_REHASHED: "MIDNIGHT_JS_P_MERKLE_NOT_REHASHED";
+    readonly COMPOSE_FAILED: "MIDNIGHT_JS_P_COMPOSE_FAILED";
+    readonly COMPOSE_OPTION_INVALID: "MIDNIGHT_JS_P_COMPOSE_OPTION_INVALID";
+    readonly STATE_DECODE_FAILED: "MIDNIGHT_JS_P_STATE_DECODE_FAILED";
+    readonly UNKNOWN_LEDGER_VERSION: "MIDNIGHT_JS_P_UNKNOWN_LEDGER_VERSION";
+    readonly LEDGER8_RUNTIME_INVALID: "MIDNIGHT_JS_P_LEDGER8_RUNTIME_INVALID";
+    readonly UNKNOWN_LEDGER8_AXIS: "MIDNIGHT_JS_P_UNKNOWN_LEDGER8_AXIS";
+    readonly PAYLOAD_NOT_A_TRANSACTION: "MIDNIGHT_JS_P_PAYLOAD_NOT_A_TRANSACTION";
+}>;
+/** The union of every value in {@link PROTOCOL_ERROR_CODES}; the type of every error class's `code` field. */
+type ProtocolErrorCode = (typeof PROTOCOL_ERROR_CODES)[keyof typeof PROTOCOL_ERROR_CODES];
+/**
+ * Which call path asked for a ledger version:
+ * - `'read'` — the version was taken off an existing record.
+ * - `'construct'` — the version was chosen to build something new against the
+ *   network's current head.
+ */
+type VersionResolutionPath = 'read' | 'construct';
+/**
+ * Why `protocolVersionToLedger` could not resolve a ledger version:
+ * - `'malformed'` — the input was not even a well-formed protocolVersion
+ *   value (not a non-negative integer).
+ * - `'unknown'` — the input was a well-formed integer, but outside every
+ *   range this framework version knows how to map.
+ */
+type ProtocolVersionUnknownReason = 'unknown' | 'malformed';
+/**
+ * Thrown by `protocolVersionToLedger` (and, transitively, `versionOfRecord` /
+ * `networkHeadVersion`) when a raw `protocolVersion` integer cannot be
+ * resolved to a `LedgerVersion`. Those live in `./version`, which imports this
+ * module -- the dependency stays one-way, so they are named here rather than
+ * linked.
+ *
+ * `code` is the field to switch on to tell all four cases apart: it splits
+ * `reason` by the `path` that produced it.
+ *
+ * @param protocolVersion The raw `protocolVersion` value that could not be
+ *   resolved. Carried for programmatic use, and rendered in the message.
+ * @param path Which call path asked for the version — see
+ *   {@link VersionResolutionPath}.
+ * @param reason A malformed input (wrong shape or type, not a
+ *   protocol-version problem at all) or a well-formed but genuinely unknown
+ *   version (a real protocol version this framework build does not support
+ *   yet) — see {@link ProtocolVersionUnknownReason}.
+ */
+declare class UnknownProtocolVersionError extends Error {
+    readonly protocolVersion: number;
+    readonly path: VersionResolutionPath;
+    readonly reason: ProtocolVersionUnknownReason;
+    readonly code: typeof PROTOCOL_ERROR_CODES.UNKNOWN_PROTOCOL_VERSION_READ | typeof PROTOCOL_ERROR_CODES.UNKNOWN_PROTOCOL_VERSION_CONSTRUCT;
+    constructor(protocolVersion: number, path: VersionResolutionPath, reason: ProtocolVersionUnknownReason);
+}
+/**
+ * Which lazily-loaded subpath export {@link Ledger8RuntimeMissingError} failed
+ * to acquire. Each chunk pulls a different set of retained-era dependencies, so
+ * naming the wrong one sends an operator to an entry point that loaded fine.
+ *
+ * @see {@link ModuleGraphAndLazyLoading}
+ */
+type RetainedEraSubpath = '/v8' | '/engine';
+/**
+ * Thrown when a lazily-loaded subpath export carrying the retained pre-fork
+ * runtime could not be acquired at all. Raised by `loadLedger8`
+ * (`lib/v8/load.ts`) and `loadLedger8Engine` (`lib/v8/load-engine.ts`), and
+ * surfaced through `createLedger8Engine` and `loadLedgerEra('v8')`.
+ *
+ * A failed acquisition is not memoised: the next call retries the import.
+ * Distinct from {@link Ledger8RuntimeInvalidError}, which reports a runtime
+ * that WAS acquired and then handed over incomplete.
+ *
+ * @param subpath Which chunk failed to load — see {@link RetainedEraSubpath}.
+ * @param cause The underlying module-resolution or initialisation failure,
+ *   preserved unchanged. Read it for which module actually failed.
+ * @see {@link ModuleGraphAndLazyLoading}
+ * @see {@link EraSeam}
+ */
+declare class Ledger8RuntimeMissingError extends Error {
+    readonly subpath: RetainedEraSubpath;
+    readonly code: "MIDNIGHT_JS_P_LEDGER8_RUNTIME_MISSING";
+    constructor(subpath: RetainedEraSubpath, cause: unknown);
+}
+/**
+ * Which physical-copy axis `assertSharedLedger8Instance`
+ * (`lib/v8/instance-guard.ts`) detected two distinct instances on.
+ *
+ * `'onchain-runtime-v3'` is the only member this framework version checks.
+ *
+ * @see {@link DualInstantiationGuard}
+ */
+type Ledger8InstanceAxis = 'onchain-runtime-v3';
+/**
+ * Thrown by `assertSharedLedger8Instance` (`lib/v8/instance-guard.ts`)
+ * when the same-named WASM package resolved to two physically distinct copies
+ * in this process (a dual-instantiation).
+ *
+ * Carries no `cause`: this is a direct reference-equality assertion failure,
+ * not a wrapped lower-level exception.
+ *
+ * @param axis Which physical-copy axis the check ran on — see
+ *   {@link Ledger8InstanceAxis}. It also selects the package names the
+ *   message tells the reader to trace.
+ * @see {@link DualInstantiationGuard}
+ */
+declare class Ledger8InstanceMismatchError extends Error {
+    readonly axis: Ledger8InstanceAxis;
+    readonly code: "MIDNIGHT_JS_P_LEDGER8_INSTANCE_MISMATCH";
+    constructor(axis: Ledger8InstanceAxis);
+}
+/**
+ * Which step of the down-convert pipeline a {@link DownConvertFailedError}
+ * came from. A closed union, so a consumer can `switch` on `stage`
+ * exhaustively.
+ *
+ * @see {@link FailClosedDecoding}
+ */
+type DownConvertStage = 'v8 envelope extraction' | 'v9 envelope extraction' | 'state down-convert';
+/**
+ * Thrown by the down-convert engine (`lib/era/envelope.ts`,
+ * `lib/v8/down-convert.ts`) when it cannot turn a raw contract-state
+ * envelope, or an already-extracted `EncodedStateValue`, into an executable
+ * pre-fork state. Raised by `extractV9EncodedStateValue` (`lib/era/envelope.ts`)
+ * and `downConvertForExecution` (`lib/v8/down-convert.ts`).
+ *
+ * Renders no raw hex and no decoded state contents — only the stage name and
+ * the wrapped `cause`.
+ *
+ * @param stage Which step failed — see {@link DownConvertStage}.
+ * @param cause The runtime's own failure, preserved unchanged. It is what
+ *   distinguishes a tag mismatch from truncated, trailing, or empty input.
+ * @see {@link FailClosedDecoding}
+ */
+declare class DownConvertFailedError extends Error {
+    readonly stage: DownConvertStage;
+    readonly code: "MIDNIGHT_JS_P_DOWN_CONVERT_FAILED";
+    constructor(stage: DownConvertStage, cause: unknown);
+}
+/**
+ * Thrown by `checkRoot` (`lib/v8/down-convert.ts`) when a bounded Merkle
+ * tree's root is read before the tree has been rehashed. Reaches a caller
+ * through `assertMerkleTreesRehashed` and `downConvertForExecution`, which
+ * assert it on every tree they decode.
+ *
+ * The remediation is always the caller's: call `rehash()` on the tree before
+ * executing against it. Nothing here repairs the tree.
+ *
+ * @param cause The runtime's own failure, when reading the root threw. Absent
+ *   when `root()` returned nothing instead of throwing.
+ * @see {@link FailClosedDecoding}
+ * @see {@link RetainedEraExecution}
+ */
+declare class MerkleNotRehashedError extends Error {
+    readonly code: "MIDNIGHT_JS_P_MERKLE_NOT_REHASHED";
+    constructor(cause?: unknown);
+}
+/**
+ * What `circuitId` a {@link ComposeFailedError} names when the failure happened
+ * before any circuit was looked up — only `'call-empty'` reaches this today.
+ *
+ * Exported, and one literal rather than a per-module copy, so a consumer
+ * reading `circuitId` off a caught error can compare against it instead of
+ * matching a string this package could change, and so it can never be mistaken
+ * for a real entry point a caller might try to resolve.
+ *
+ * @see {@link ComposeRefusalOrder}
+ */
+declare const NO_CIRCUIT = "(none)";
+/**
+ * Which composition step {@link ComposeFailedError} failed at.
+ *
+ * Call stages:
+ * - `'call-empty'` — a call transaction was requested with no calls in it.
+ *   The one stage that names no circuit: it is raised before any circuit is
+ *   looked up, so it names {@link NO_CIRCUIT}.
+ * - `'call-operation'` — a call leg could not resolve a registered operation
+ *   for the call's circuit on the given contract state.
+ * - `'call-verifier-key'` — a call leg resolved a registered operation for the
+ *   call's circuit, but that operation carries no verifier key, so no ledger
+ *   could verify a call against it.
+ * - `'call-contract-state'` — the call's pre-call state could not be bridged
+ *   into the target era's own state algebra. Carries the decoder's failure on
+ *   `cause`.
+ * - `'call-transcript-empty'` — a caller-supplied partitioned transcript
+ *   carried neither a guaranteed nor a fallible half, so the call would record
+ *   no operations at all.
+ * - `'call-partition-context'` — the era rejected the query-context state the
+ *   call recorded (its block, its starting effects, or one of the commitment
+ *   indices it registered for a coin received in-contract) while bridging it
+ *   onto the context the transcript is partitioned against. Carries the
+ *   runtime's own failure on `cause`.
+ * - `'call-partition'` — the ledger rejected the public transcript supplied
+ *   for a call while splitting it into its guaranteed and fallible halves.
+ *   Carries the runtime's own failure on `cause`.
+ * - `'call-prototype'` — the ledger rejected the call's own inputs while
+ *   constructing the call prototype. Carries the runtime's failure on `cause`.
+ * - `'call-dust-payout'` — a transcript claimed an unshielded spend to a user
+ *   address in DUST, which has no raw token type to be paid out in.
+ * - `'call-unsupported-payout'` — a transcript claimed an unshielded spend to
+ *   a user address in a token type that cannot be paid out as an unshielded
+ *   UTXO at all (a shielded token type today).
+ *
+ * Deploy stages:
+ * - `'deploy-verifier-key'` — a deploy leg was given no verifier key for a
+ *   circuit the contract state declares.
+ * - `'deploy-unknown-circuit'` — the verifier-key map handed to a deploy leg
+ *   names a circuit the contract state does not declare. Registering it would
+ *   add an entry point the compiled contract never had, and silently change
+ *   the deployed contract's address.
+ * - `'deploy-ambiguous-circuit'` — two entry points the contract state
+ *   declares resolve to the same name, so the verifier-key map (keyed by
+ *   name) cannot address them apart. Registering under the shared name would
+ *   key one slot and leave the other blank.
+ * - `'deploy-verifier-key-blob'` — the ledger rejected the verifier-key bytes
+ *   supplied for a circuit.
+ *
+ * Keep-state stage:
+ * - `'wrap-call'` — the keep-state leg could not resolve a registered
+ *   operation for the transcript's circuit on the given contract state.
+ *
+ * Which ledger era the failure happened on is carried separately, on the
+ * error's `version` field. Every stage but `'wrap-call'` is reachable on both
+ * eras; `'wrap-call'` is only ever raised for `'v9'`.
+ *
+ * @see {@link ComposeRefusalOrder}
+ * @see {@link VerifierKeys}
+ */
+type ComposeStage = 'wrap-call' | 'call-empty' | 'call-transcript-empty' | 'call-partition-context' | 'call-partition' | 'call-prototype' | 'call-dust-payout' | 'call-unsupported-payout' | 'call-operation' | 'call-contract-state' | 'call-verifier-key' | 'deploy-verifier-key' | 'deploy-unknown-circuit' | 'deploy-ambiguous-circuit' | 'deploy-verifier-key-blob';
+/**
+ * Thrown when a transaction cannot be composed because a circuit's operation
+ * is missing, under-registered, or names a circuit the contract does not have.
+ * `stage` (see {@link ComposeStage}) names which composition step failed and is
+ * a closed union, so a consumer can `switch` on it exhaustively; `version`
+ * names the ledger era the composition was running against.
+ *
+ * Most stages are direct assertion failures (a missing lookup, not a wrapped
+ * lower-level exception) and carry no `cause`, like
+ * {@link Ledger8InstanceMismatchError}. The exceptions are the stages where
+ * the ledger itself rejected caller-supplied bytes — enumerated under `cause`
+ * below: that failure is preserved on `cause`, the same way
+ * {@link DownConvertFailedError} preserves its runtime's own message.
+ *
+ * `circuitId` names the entry point, never its raw contents: this class
+ * renders no hex and no byte-array dump. `'call-empty'` is the one stage with
+ * no circuit to name, and its message names none.
+ *
+ * @param version The ledger era the composition was running against.
+ * @param stage Which composition step failed — see {@link ComposeStage}. A
+ *   closed union, so a consumer can `switch` on it exhaustively.
+ * @param circuitId The entry-point name, already decoded. {@link NO_CIRCUIT}
+ *   for `'call-empty'`, the one stage raised before any circuit is looked up.
+ * @param cause The runtime's own failure, present only for the stages where
+ *   the ledger itself rejected caller-supplied bytes: `'call-contract-state'`,
+ *   `'call-partition-context'`, `'call-partition'`, `'call-prototype'` and
+ *   `'deploy-verifier-key-blob'`.
+ * @see {@link ComposeRefusalOrder}
+ * @see {@link VerifierKeys}
+ */
+declare class ComposeFailedError extends Error {
+    readonly version: LedgerVersion;
+    readonly stage: ComposeStage;
+    readonly circuitId: string;
+    readonly code: "MIDNIGHT_JS_P_COMPOSE_FAILED";
+    constructor(version: LedgerVersion, stage: ComposeStage, circuitId: string, cause?: unknown);
+    private static readonly MESSAGES;
+}
+/**
+ * Which option handed to a composition leg was unusable:
+ * - `'contractState'` — the state could not be bridged into the target
+ *   ledger era (its serialized envelope was rejected by the era's decoder).
+ * - `'networkId'` — the network id was empty. The ledger accepts an empty
+ *   string and bakes it into the transaction, so a caller that forgot to
+ *   resolve one would only find out at submission.
+ * - `'ttl'` — the time-to-live was not a valid instant. `new Date('...')` on
+ *   an unparseable value yields an Invalid Date, which the ledger silently
+ *   records as the Unix epoch: a transaction that is already expired when it
+ *   is composed.
+ * - `'calls'` — the call list is not one the target era can compose. The
+ *   retained pre-fork era composes exactly one call: a cross-contract call is a
+ *   ledger-9-only feature that a pre-fork contract cannot emit, so that era has
+ *   no call tree to express.
+ * - `'verifierKeys'` — a deploy was requested with no verifier-key map, and the
+ *   state it was given needs one. Raised on BOTH eras, for two different
+ *   reasons: the retained era's deploy leg has to register the compiled
+ *   contract's keys itself and so always needs the map, while the current era
+ *   accepts its omission for a state that already carries its keys and refuses
+ *   it only for a state still declaring a blank-keyed entry point.
+ * - `'zswapOffer'` — the supplied offer bytes were rejected by the target era's
+ *   decoder. Raised on BOTH eras, for the same reason and with the same
+ *   remediation: pass the bytes that era's own offer serialization produced.
+ *
+ * @see {@link ComposeRefusalOrder}
+ * @see {@link VerifierKeys}
+ */
+type ComposeOption = 'calls' | 'contractState' | 'ledgerParameters' | 'networkId' | 'ttl' | 'verifierKeys' | 'zswapOffer';
+/**
+ * Thrown by the composition legs when one of their options cannot be used at
+ * all, as opposed to {@link ComposeFailedError}, which reports a circuit whose
+ * operation is missing or under-registered.
+ *
+ * These are the well-formedness checks the ledger itself does not make.
+ *
+ * Like {@link DownConvertFailedError}, this class renders no input contents of
+ * its own.
+ *
+ * @param version The ledger era the option was being used against.
+ * @param option Which option was unusable — see {@link ComposeOption}. A
+ *   closed union, so a consumer can `switch` on it exhaustively.
+ * @param cause The decoder's own failure, present only for `'contractState'`
+ *   and `'zswapOffer'`, where caller-supplied bytes were rejected.
+ * @see {@link ComposeRefusalOrder}
+ * @see {@link VerifierKeys}
+ */
+declare class ComposeOptionError extends Error {
+    readonly version: LedgerVersion;
+    readonly option: ComposeOption;
+    readonly code: "MIDNIGHT_JS_P_COMPOSE_OPTION_INVALID";
+    constructor(version: LedgerVersion, option: ComposeOption, cause?: unknown);
+    private static readonly MESSAGES;
+}
+/**
+ * Thrown when a raw, serialized contract-state envelope could not be read by
+ * the ledger era it was requested for. Raised by both of the facade's read
+ * paths, `extractState` and `decodeContractState`
+ * (`lib/shared/contract-state.ts`), so a caller writes one handler for both.
+ *
+ * Renders no hex and no byte dump of its own.
+ *
+ * @param version The era whose decoder rejected the envelope.
+ * @param cause The decoder's own diagnosis, preserved unchanged. It is what
+ *   distinguishes a tag mismatch from truncated, trailing or empty input.
+ * @see {@link FailClosedDecoding}
+ */
+declare class StateDecodeFailedError extends Error {
+    readonly version: LedgerVersion;
+    readonly code: "MIDNIGHT_JS_P_STATE_DECODE_FAILED";
+    constructor(version: LedgerVersion, cause: unknown);
+}
+/**
+ * Thrown by `extractEncodedStateValue` (`lib/era/envelope.ts`) when the
+ * injected pre-fork runtime cannot be used — it was not passed at all, or the
+ * binding the decoder needs is absent from it. Also raised by
+ * `downConvertForExecution` (`lib/v8/down-convert.ts`) and
+ * `assertSharedLedger8Instance` (`lib/v8/instance-guard.ts`), the latter for a
+ * nullish instance probe.
+ *
+ * Nothing is wrong with the caller's input here. Distinct from
+ * {@link Ledger8RuntimeMissingError}, which reports the v8 chunk failing to
+ * load at all, and from {@link DownConvertFailedError}, which reports an
+ * envelope or state that could not be turned into an executable pre-fork
+ * state.
+ *
+ * @param missingMember Which binding was absent. One of this module's own
+ *   literals, never caller-supplied text, so it is safe to log.
+ * @see {@link FailClosedDecoding}
+ * @see {@link DualInstantiationGuard}
+ */
+declare class Ledger8RuntimeInvalidError extends Error {
+    readonly missingMember: string;
+    readonly code: "MIDNIGHT_JS_P_LEDGER8_RUNTIME_INVALID";
+    constructor(missingMember: string);
+}
+/**
+ * Thrown by `assertSharedLedger8Instance` (`lib/v8/instance-guard.ts`)
+ * when the `axis` it was handed is not a member of {@link Ledger8InstanceAxis}.
+ *
+ * A TypeScript caller cannot produce this — `axis` is typed as
+ * {@link Ledger8InstanceAxis}. It exists for the untyped JavaScript consumers
+ * this package also serves.
+ *
+ * @param requestedAxis The offending value that was passed. Carried for
+ *   programmatic use only; it is deliberately kept out of the message.
+ * @see {@link DualInstantiationGuard}
+ */
+declare class UnknownLedger8AxisError extends Error {
+    readonly requestedAxis: string;
+    readonly code: "MIDNIGHT_JS_P_UNKNOWN_LEDGER8_AXIS";
+    constructor(requestedAxis: string);
+}
+/**
+ * Thrown when a ledger era was requested by a value that is not a member of
+ * `LEDGER_VERSIONS`. Raised by `loadLedgerEra` (`lib/era/load-era.ts`) and by
+ * `extractEncodedStateValue` (`lib/era/envelope.ts`).
+ *
+ * A TypeScript caller cannot produce this: `version` is typed as
+ * `LedgerVersion`. It exists for the untyped JavaScript consumers this package
+ * also serves.
+ *
+ * Carries no `version` field, unlike every other era-aware error here — there
+ * is no valid era to name.
+ *
+ * @param requestedVersion The offending value that was passed. Carried for
+ *   programmatic use only; it is deliberately kept out of the message.
+ * @see {@link SharedTableDiscipline}
+ * @see {@link FailClosedDecoding}
+ */
+declare class UnknownLedgerVersionError extends Error {
+    readonly requestedVersion: string;
+    readonly code: "MIDNIGHT_JS_P_UNKNOWN_LEDGER_VERSION";
+    constructor(requestedVersion: string);
+}
+/**
+ * The opening of the tag every serialized ledger transaction carries, on both
+ * eras.
+ *
+ * Stops before the bracketed version deliberately: a `[vN]` is the wire-schema
+ * version of the serialized OBJECT and never a ledger era — the retained era's
+ * transactions are tagged `transaction[v9]`.
+ *
+ * @see packages/contracts/docs/verification-path.md for the same rule stated
+ *      about verifier-key tags.
+ */
+declare const TRANSACTION_TAG_PREFIX = "midnight:transaction[";
+/**
+ * Thrown when a payload handed to a proving seam is not a serialized
+ * transaction at all.
+ *
+ * Distinct from a decode failure inside the ledger runtime: this is raised
+ * before any runtime is asked to read the bytes, so it says the caller sent the
+ * wrong KIND of payload rather than a damaged one. It covers three ways that
+ * can happen — a `txBytes` field that is not a byte string, a byte string
+ * shorter than the tag prefix, and one that does not open with the prefix.
+ *
+ * @remarks Raised by `proveV8Transaction`, so it reaches application code as a
+ * `proveTx` rejection. Match it with `hasErrorCode` against
+ * `PROTOCOL_ERROR_CODES.PAYLOAD_NOT_A_TRANSACTION` rather than constructing it.
+ */
+declare class PayloadNotATransactionError extends Error {
+    readonly code: "MIDNIGHT_JS_P_PAYLOAD_NOT_A_TRANSACTION";
+    private constructor();
+    /**
+     * The `txBytes` field of a `v8` payload was not a `Uint8Array`. Reachable
+     * from JavaScript, from a consumer built against a pre-5.0.0
+     * `midnight-js-types`, or across an untyped boundary — so it is refused with
+     * a code rather than left to become a bare `TypeError`.
+     */
+    static notBytes(received: unknown): PayloadNotATransactionError;
+    /** The payload is a byte string, but does not open with a transaction's tag. */
+    static wrongTag(byteLength: number): PayloadNotATransactionError;
+}
+
+/**
+ * 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>;
+}
+/**
+ * Where a call's public transcript comes from. Two shapes, because neither
+ * production leg subsumes the other:
+ *
+ * - `'unpartitioned'` — the raw op sequence a circuit emitted on the retained
+ *   pre-fork execution leg, the state it ran against, and the
+ *   {@link PartitionContext} that leg recorded.
+ * - `'partitioned'` — a guaranteed/fallible pair already split by compact-js,
+ *   which is the current production path.
+ *
+ * Every member is plain data in the ledger's own declared algebra — no live
+ * WASM handle.
+ *
+ * @see {@link RetainedEraExecution} for the leg that submits the unpartitioned
+ * shape.
+ * @see {@link ComposeRefusalOrder} for why an already-partitioned pair is
+ * passed through rather than re-derived.
+ * @see {@link EraSeam}
+ */
+type CallTranscriptSource = {
+    readonly kind: 'unpartitioned';
+    readonly preState: EncodedStateValue;
+    readonly publicTranscript: Op$1<AlignedValue$1>[];
+    readonly partitionContext: PartitionContext;
+} | {
+    readonly kind: 'partitioned';
+    readonly guaranteed?: Transcript<AlignedValue$1>;
+    readonly fallible?: Transcript<AlignedValue$1>;
+};
+/**
+ * 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;
+/**
+ * A call's guaranteed/fallible transcript pair, as the ledger's partitioner
+ * answers it. Either member is absent when that segment carries nothing.
+ */
+type PartitionedCallTranscript = [
+    Transcript<AlignedValue$1> | undefined,
+    Transcript<AlignedValue$1> | undefined
+];
+/**
+ * What an era needs to partition one call's transcript, which is strictly less
+ * than composing the call: no operation registry, no private outputs, no
+ * transaction envelope. The era supplies its own version.
+ */
+interface EraPartitionCallOptions {
+    readonly circuitId: string;
+    readonly contractAddress: string;
+    readonly transcript: CallTranscriptSource;
+    /**
+     * The chain's own serialized ledger parameters at the block this call is
+     * built against, or {@link INITIAL_LEDGER_PARAMETERS} to partition against
+     * the era's initial cost model instead.
+     *
+     * Required, exactly as on `ComposeCallEntry`. The partitioner runs on this
+     * path too, so an optional field here would reopen the silent
+     * wrong-cost-model fallback that {@link LedgerParametersOption} exists to
+     * close.
+     */
+    readonly ledgerParameters: LedgerParametersOption;
+}
+/**
+ * One contract call in a call transaction.
+ *
+ * `contractState` is the raw, serialized state the call is dispatched against,
+ * as read from chain. It supplies the registered operation for `circuitId`,
+ * including its verifier key, which the call's key location hashes; a
+ * constructor-built state will not do, because it declares its entry points
+ * with blank keys.
+ *
+ * `communicationCommitmentRandomness` is the randomness the runtime bound a
+ * cross-contract callee to its caller with. The root call — being no one's
+ * callee — omits it and gets fresh randomness.
+ *
+ * @see {@link EraSeam}
+ */
+interface ComposeCallEntry {
+    readonly contractAddress: string;
+    readonly circuitId: string;
+    readonly contractState: Uint8Array;
+    /**
+     * The ledger parameters the chain held at the block this call is built against, serialized —
+     * `RawContractState.ledgerParameters`, passed through untouched — or
+     * {@link INITIAL_LEDGER_PARAMETERS} to partition against the ledger's initial cost model instead.
+     *
+     * Required, and deliberately so. See {@link LedgerParametersOption}.
+     */
+    readonly ledgerParameters: LedgerParametersOption;
+    readonly transcript: CallTranscriptSource;
+    readonly privateTranscriptOutputs: AlignedValue$1[];
+    readonly input: AlignedValue$1;
+    readonly output: AlignedValue$1;
+    readonly communicationCommitmentRandomness?: string;
+}
+/**
+ * Everything a call transaction needs.
+ *
+ * `calls` is in execution-trace order: cross-contract callees first, the root
+ * call last. A circuit with no cross-contract calls has a single entry.
+ *
+ * The two Zswap offers are serialized offer bytes. `networkId` and `ttl` carry
+ * the caller's policy decisions — which network, how long the transaction
+ * lives.
+ *
+ * @see {@link ComposeRefusalOrder} for when the envelope options are checked.
+ * @see {@link EraSeam}
+ */
+interface ComposeCallOptions {
+    readonly calls: readonly ComposeCallEntry[];
+    readonly networkId: string;
+    readonly ttl: Date;
+    readonly guaranteedZswapOffer?: Uint8Array;
+    readonly fallibleZswapOffer?: Uint8Array;
+}
+/**
+ * Everything a deploy transaction needs.
+ *
+ * `contractState` is the raw, serialized initial state the contract's
+ * constructor produced.
+ *
+ * `verifierKeys` maps entry-point name -> raw, tagged verifier key bytes
+ * (`keys/<id>.verifier`). When supplied, the map must name exactly the entry
+ * points the state declares — no more, no fewer. Omit it only for a state that
+ * ALREADY carries its keys.
+ *
+ * @see {@link VerifierKeys}
+ * @see {@link EraSeam}
+ */
+interface ComposeDeployOptions {
+    readonly contractState: Uint8Array;
+    readonly verifierKeys?: ReadonlyMap<string, Uint8Array>;
+    readonly networkId: string;
+    readonly ttl: Date;
+    readonly guaranteedZswapOffer?: Uint8Array;
+}
+/**
+ * What a composed deploy hands back.
+ *
+ * `contractAddress` cannot be recomputed from the state a caller passed in, so
+ * it is handed back here rather than derived. `initialState` is the state that
+ * address was derived from — what a caller stores and later hands to a call.
+ *
+ * All three are plain data.
+ *
+ * @see {@link VerifierKeys} for why the address cannot be recomputed.
+ * @see {@link EraSeam}
+ */
+interface DeployResultPojo {
+    readonly transaction: Uint8Array;
+    readonly contractAddress: string;
+    readonly initialState: Uint8Array;
+}
+
+/**
+ * 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;
+}
+/**
+ * A contract state as plain data: the primary state in its encoded form, 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;
+    readonly entryPoints: readonly ContractEntryPointPojo[];
+}
+
+/**
+ * One ledger era, as a single object a caller holds and calls.
+ *
+ * Both eras expose the SAME methods with the same signatures. Which era an
+ * object is bound to is readable from {@link LedgerEra.version} and nowhere
+ * else — a caller that has resolved the era for a record (see
+ * `protocolVersionToLedger` in `../../version.ts`) hands that value to
+ * `loadLedgerEra` once and then writes era-agnostic code.
+ *
+ * Every value crossing this boundary is plain data: `Uint8Array`s and plain
+ * objects, never a live WASM handle, so a result outlives the module that
+ * produced it and survives a `structuredClone` or a worker boundary.
+ *
+ * The methods are synchronous. Asking for an era is the point at which its
+ * runtime is acquired, so by the time a caller holds one of these there is
+ * nothing left to await.
+ *
+ * @see {@link EraSeam}
+ */
+interface LedgerEra {
+    /** The era this object is bound to — the value that was passed to `loadLedgerEra`. */
+    readonly version: LedgerVersion;
+    /**
+     * Reads the primary state out of a raw, serialized contract-state envelope
+     * written by this era.
+     *
+     * Fails closed on an envelope this era cannot read — including one written
+     * by the other era — rather than returning a partial or empty state. The
+     * failure is a `StateDecodeFailedError` naming this era, the same class
+     * {@link LedgerEra.decodeContractState} raises, with the decoder's own
+     * diagnosis on `cause`.
+     *
+     * @param raw The serialized contract-state envelope.
+     * @returns The primary state read out of the envelope.
+     * @throws StateDecodeFailedError if this era's decoder rejects `raw`.
+     * @see {@link FailClosedDecoding}
+     */
+    extractState(raw: Uint8Array): EncodedStateValue;
+    /**
+     * Reads a raw, serialized contract-state envelope written by this era into
+     * plain data: its primary state, and the entry points it declares with the
+     * verifier key registered against each.
+     *
+     * @param raw The serialized contract-state envelope.
+     * @returns The decoded state. A `verifierKey` absent on an entry point means
+     * that slot was never deployed, not that the key is empty.
+     * @throws StateDecodeFailedError if this era's decoder rejects `raw`, or if
+     * the state cannot resolve an entry point it declares itself.
+     * @see {@link FailClosedDecoding}
+     */
+    decodeContractState(raw: Uint8Array): ContractStatePojo;
+    /**
+     * Composes an UNPROVEN call transaction and serializes it.
+     *
+     * The returned bytes are what `Transaction.serialize()` produces before
+     * `.prove()` is ever called; proving needs a proving provider and a running
+     * proof server, neither of which this seam has.
+     *
+     * The two eras are not equivalent here, and the difference is deliberate
+     * rather than hidden: the retained pre-fork era composes exactly one call,
+     * because a cross-contract call is a ledger-9-only feature a pre-fork
+     * contract cannot emit. The refusal is raised, never worked around. A Zswap
+     * offer is NOT refused on either era.
+     *
+     * @param options The calls to compose and the transaction-wide envelope.
+     * @returns The serialized UNPROVEN transaction.
+     * @throws ComposeOptionError if an option is unusable on this era — an
+     * empty `networkId`, an invalid `ttl`, undecodable offer or state bytes, or
+     * a call tree with more than one entry on the retained pre-fork era.
+     * @throws ComposeFailedError if a call cannot be assembled; `stage` names
+     * which step refused it.
+     * @see {@link ComposeRefusalOrder}
+     * @see {@link EraSeam}
+     */
+    composeCallTx(options: ComposeCallOptions): Uint8Array;
+    /**
+     * Composes an UNPROVEN deploy transaction and returns it together with the
+     * address the deployment will have and the initial state that address was
+     * derived from.
+     *
+     * The address cannot be recomputed from the state a caller passed in — a
+     * deploy mints a fresh nonce — which is why it is returned rather than left
+     * to the caller to derive.
+     *
+     * @param options The initial state, its verifier keys, and the
+     * transaction-wide envelope.
+     * @returns The serialized UNPROVEN transaction, the address the deployment
+     * will have, and the initial state that address was derived from.
+     * @throws ComposeOptionError if an option is unusable on this era — an
+     * empty `networkId`, an invalid `ttl`, undecodable state bytes, or an
+     * omitted `verifierKeys` for a state that still declares a blank key.
+     * @throws ComposeFailedError if the supplied keys do not match the state's
+     * declared entry points, or if the ledger rejects a key blob; `stage` names
+     * which check refused it.
+     * @see {@link VerifierKeys}
+     * @see {@link ComposeRefusalOrder}
+     */
+    composeDeployTx(options: ComposeDeployOptions): DeployResultPojo;
+    /**
+     * Resolves one call's guaranteed/fallible transcript pair, without composing
+     * a transaction.
+     *
+     * PROTOTYPE SEAM. A caller that has to route a Zswap coin into the right
+     * segment needs the partition BEFORE it builds the offer, and `composeCallTx`
+     * computes the partition only after the offer has been handed to it as an
+     * option. Without this the retained-era pipeline places every coin movement
+     * in the guaranteed segment and the wallet cannot balance the result.
+     *
+     * @param options The call's transcript source, address, circuit and the
+     * chain's own serialized ledger parameters.
+     * @returns The `[guaranteed, fallible]` pair, either member possibly absent.
+     * @throws ComposeFailedError, ComposeOptionError as `composeCallTx` does for
+     * the same inputs.
+     */
+    partitionCallTranscript(options: EraPartitionCallOptions): PartitionedCallTranscript;
+}
+
+/**
+ * Resolves one ledger era to a {@link LedgerEra} bound to it.
+ *
+ * This is the only sanctioned way to reach either era's operations. Pass the
+ * version resolved from a record or from the network head (see
+ * `protocolVersionToLedger` in `../../version.ts`) rather than a string chosen
+ * by hand.
+ *
+ * Memoised per era, so the retained pre-fork WASM is instantiated at most once
+ * per process. A FAILED v8 acquisition is not memoised: the next call retries.
+ *
+ * @param version The era to resolve.
+ * @returns The era facade bound to `version`. The same object on every call
+ * for that era, and frozen.
+ * @throws UnknownLedgerVersionError — as a rejection — if `version` is not a
+ * member of `LEDGER_VERSIONS`.
+ * @throws Ledger8RuntimeMissingError — as a rejection — if the retained
+ * pre-fork runtime cannot be acquired. It propagates unchanged, carrying the
+ * underlying cause.
+ * @see {@link EraSeam}
+ * @see {@link SharedTableDiscipline}
+ */
+declare const loadLedgerEra: (version: LedgerVersion) => Promise<LedgerEra>;
+
+var V8 = /*#__PURE__*/_mergeNamespaces({
+  __proto__: null
+}, [ledgerV8]);
+
+type ProtocolV8 = typeof V8;
+/**
+ * The only sanctioned runtime path to the v8 ledger era.
+ *
+ * The v8 WASM loads on the first call and not before.
+ *
+ * A failed load is not memoised: the rejection propagates as
+ * {@link Ledger8RuntimeMissingError} and the next call retries the import.
+ *
+ * @returns The v8 ledger module, memoised after the first successful load.
+ * @throws Ledger8RuntimeMissingError If the `./v8` chunk cannot be imported.
+ *   The returned promise rejects with it, carrying the underlying failure on
+ *   `cause`.
+ * @see {@link ModuleGraphAndLazyLoading}
+ * @see {@link EraSeam}
+ */
+declare const loadLedger8: () => Promise<ProtocolV8>;
+
+/**
+ * Anything that can report the network's current head protocol version —
+ * typically an indexer or node client. Consumed by {@link networkHeadVersion}.
+ */
+interface ProtocolVersionSource {
+    /**
+     * @returns The network's current head `protocolVersion` integer.
+     */
+    queryLatestProtocolVersion(): Promise<number>;
+}
+/**
+ * Any record carrying a raw `protocolVersion` integer field, e.g. a
+ * transaction or block already read from the indexer. Consumed by
+ * {@link versionOfRecord}.
+ */
+interface VersionedRecord {
+    readonly protocolVersion: number;
+}
+/**
+ * Maps a raw `protocolVersion` integer (as returned by the indexer or node)
+ * onto the ledger runtime it corresponds to.
+ *
+ * | protocolVersion range | node version | ledger |
+ * | --------------------- | ------------ | ------ |
+ * | 1_000_000 – 1_999_999 | 1.x          | v8     |
+ * | 2_000_000 – 2_999_999 | 2.x          | v9     |
+ *
+ * Most call sites should not call this directly. Prefer
+ * {@link versionOfRecord} for a `protocolVersion` read off an existing
+ * indexer/node record, or {@link networkHeadVersion} for the network's
+ * current head version — both tag the resulting error with the correct
+ * `path` automatically. Pass `path` explicitly here only when neither helper
+ * fits the call site.
+ *
+ * @param protocolVersion The raw integer read from an indexer or node record.
+ * @param path Which resolution path a failure is attributed to. Defaults to
+ * `'construct'`, and decides which of the two error codes a failure carries.
+ * @returns The {@link LedgerVersion} that `protocolVersion`'s node major maps
+ * onto.
+ * @throws {@link UnknownProtocolVersionError} with `reason: 'malformed'` when
+ * `protocolVersion` is not a non-negative integer, and with `reason: 'unknown'`
+ * when it is a well-formed integer outside every range above.
+ * @see {@link SharedTableDiscipline}
+ */
+declare const protocolVersionToLedger: (protocolVersion: number, path?: VersionResolutionPath) => LedgerVersion;
+/**
+ * Resolves the ledger version for a record's `protocolVersion` field (e.g. a
+ * transaction or block already read from the indexer).
+ *
+ * @param record Any object carrying a raw `protocolVersion` integer field.
+ * @returns The {@link LedgerVersion} that record was written under.
+ * @throws {@link UnknownProtocolVersionError} tagged with the `read` path, on
+ * the same two conditions as {@link protocolVersionToLedger}.
+ */
+declare const versionOfRecord: (record: VersionedRecord) => LedgerVersion;
+/**
+ * Queries `source` for the network's current head protocol version and
+ * resolves it to a {@link LedgerVersion}.
+ *
+ * The source is expected to read the network on every call. This is the
+ * construct path: the era being resolved is the one a transaction built now
+ * will land in, and a stale reading is wrong exactly at the fork boundary,
+ * where that question matters. `PublicDataProvider.queryLatestProtocolVersion`
+ * states the same prohibition as a requirement on its implementations; this
+ * parameter is a structural type, so nothing here can enforce it. See ADR 0007.
+ *
+ * @param source The indexer or node client to ask for the head version.
+ * @returns A promise for the {@link LedgerVersion} at the network head.
+ * @throws {@link UnknownProtocolVersionError} tagged with the `construct`
+ * path, on the same two conditions as {@link protocolVersionToLedger}. A
+ * rejection from `source.queryLatestProtocolVersion()` propagates unchanged.
+ */
+declare const networkHeadVersion: (source: ProtocolVersionSource) => Promise<LedgerVersion>;
+
+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;
+}
+
+/**
+ * The only sanctioned runtime path to the engine's public surface.
+ *
+ * The retained `compact-runtime@0.16` glue and
+ * `@midnight-ntwrk/onchain-runtime-v3` WASM load only on the first call — never
+ * as a side effect of importing the package root.
+ *
+ * A failed load is not memoised: the next call retries the import. Exactly two
+ * rejections propagate unchanged — {@link Ledger8RuntimeMissingError} from the
+ * retained-runtime acquisition, and {@link Ledger8InstanceMismatchError} from
+ * the construction-time instance guard — keeping their class, code and
+ * discriminants intact for callers. Every other failure is wrapped in
+ * {@link Ledger8RuntimeMissingError}, including the coded
+ * `Ledger8RuntimeInvalidError` that same guard raises for an incomplete
+ * runtime, and a raw module-resolution error on the engine chunk itself.
+ *
+ * @returns The engine's public surface, memoised after the first successful
+ *   load.
+ * @throws Ledger8RuntimeMissingError If the retained runtime, or the `./engine`
+ *   chunk itself, cannot be acquired.
+ * @throws Ledger8InstanceMismatchError If the construction-time instance guard
+ *   found `onchain-runtime-v3` resolved to two physically distinct copies.
+ * @see {@link ModuleGraphAndLazyLoading}
+ * @see {@link EraSeam}
+ */
+declare const loadLedger8Engine: () => Promise<Ledger8Engine>;
+
+export { CURRENT_LEDGER_VERSION, ComposeFailedError, ComposeOptionError, DownConvertFailedError, INITIAL_LEDGER_PARAMETERS, LEDGER_VERSIONS, Ledger8InstanceMismatchError, Ledger8RuntimeInvalidError, Ledger8RuntimeMissingError, MerkleNotRehashedError, NO_CIRCUIT, PROTOCOL_ERROR_CODES, PayloadNotATransactionError, RETAINED_LEDGER_VERSIONS, StateDecodeFailedError, TRANSACTION_TAG_PREFIX, UnknownLedger8AxisError, UnknownLedgerVersionError, UnknownProtocolVersionError, loadLedger8, loadLedger8Engine, loadLedgerEra, networkHeadVersion, protocolVersionToLedger, versionOfRecord };
+export type { CallTranscriptSource, ComposeCallEntry, ComposeCallOptions, ComposeDeployOptions, ComposeOption, ComposeStage, ConstructorResultPojo, ContractEntryPointPojo, ContractStatePojo, CurrentLedgerVersion, DeployResultPojo, DownConvertStage, DownConvertedState, EraPartitionCallOptions, ExecuteCircuitOptions, ExecuteConstructorOptions, Ledger8ChargedState, Ledger8DeployableContractState, Ledger8Engine, Ledger8InstanceAxis, Ledger8StateValue, LedgerEra, LedgerParametersOption, LedgerVersion, PartitionContext, PartitionedCallTranscript, ProtocolErrorCode, ProtocolV8, ProtocolVersionSource, ProtocolVersionUnknownReason, RetainedEraSubpath, RetainedLedgerVersion, TranscriptPojo, VersionResolutionPath, VersionedRecord, WrapKeepStateCallOptions };