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

package/dist/index.js

@@ -1,11 +1,796 @@
+import { StateDecodeFailedError, ComposeFailedError, ComposeOptionError, NO_CIRCUIT, DownConvertFailedError, UnknownLedgerVersionError, Ledger8RuntimeInvalidError, Ledger8RuntimeMissingError, Ledger8InstanceMismatchError } from './errors.js';
+export { MerkleNotRehashedError, PROTOCOL_ERROR_CODES, PayloadNotATransactionError, TRANSACTION_TAG_PREFIX, UnknownLedger8AxisError, UnknownProtocolVersionError } from './errors.js';
+import * as ledgerV9 from '@midnightntwrk/ledger-v9';
+import { ContractState } from '@midnightntwrk/ledger-v9';
+export { ledgerV9 as ledger };
+import { b as entryPointName, c as assertComposeEnvelope, a as assembleCallPrototype, d as composeV8DeployTx, r as resolveVerifierKeyRegistrations, p as partitionCallTranscript } from './shared/deploy-D6yyn9P7.js';
+export { I as INITIAL_LEDGER_PARAMETERS } from './shared/deploy-D6yyn9P7.js';
+import { hashVerifierKey } from '@midnight-ntwrk/compact-js';
 import * as compactJs from '@midnight-ntwrk/compact-js';
 export { compactJs };
+import { l as loadLedger8 } from './shared/load-C0TZnEd2.js';
+export { CURRENT_LEDGER_VERSION, LEDGER_VERSIONS, RETAINED_LEDGER_VERSIONS, networkHeadVersion, protocolVersionToLedger, versionOfRecord } from './version.js';
 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 };
+
+/*
+ * This file is part of midnight-js.
+ * Copyright (C) Midnight Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Reads the primary state out of a raw envelope with the given era's extractor,
+ * reporting every failure as {@link StateDecodeFailedError} naming `version`.
+ *
+ * @param raw The serialized contract-state envelope.
+ * @param version The era whose extractor is used, and which every failure
+ * raised here names.
+ * @param extract The era's own envelope extractor.
+ * @returns The primary state read out of the envelope.
+ * @throws StateDecodeFailedError for every failure, carrying the extractor's
+ * own diagnosis on `cause`.
+ * @see {@link FailClosedDecoding}
+ */
+const extractStateWith = (raw, version, extract) => {
+    try {
+        return extract(raw);
+    }
+    catch (cause) {
+        throw new StateDecodeFailedError(version, cause);
+    }
+};
+/**
+ * Reads a raw, serialized contract-state envelope into a
+ * {@link ContractStatePojo} using the given era's own `ContractState`.
+ *
+ * Nothing that crosses back is a live WASM handle: the primary state leaves as
+ * an `EncodedStateValue` (plain objects, arrays, `Map`s, `Uint8Array`s and
+ * primitives) and each entry point as a plain record.
+ *
+ * @param raw The serialized contract-state envelope.
+ * @param version The era whose decoder is used, and which every failure raised
+ * here names.
+ * @param ledger The era module slice carrying its own `ContractState`.
+ * @returns The state and the entry points it declares, as plain data.
+ * @throws StateDecodeFailedError for every failure — the whole read is
+ * covered, not just the deserialization — with the decoder's own diagnosis on
+ * `cause`.
+ * @see {@link FailClosedDecoding}
+ * @see {@link EraSeam}
+ */
+const decodeContractStateWith = (raw, version, ledger) => {
+    try {
+        const decoded = ledger.ContractState.deserialize(raw);
+        const entryPoints = decoded.operations().map((entryPoint) => {
+            // Deliberately not optional-chained: an unresolvable entry point is an
+            // inconsistent state, not a blank slot -- see FailClosedDecoding.
+            const operation = decoded.operation(entryPoint);
+            if (operation === undefined) {
+                throw new Error(`contract state declares entry point '${entryPointName(entryPoint)}' but resolves no operation for it.`);
+            }
+            const { verifierKey } = operation;
+            return {
+                circuitId: entryPointName(entryPoint),
+                verifierKey,
+                verifierKeyHash: verifierKey === undefined ? undefined : hashVerifierKey(verifierKey)
+            };
+        });
+        return { state: decoded.data.state.encode(), entryPoints };
+    }
+    catch (cause) {
+        throw new StateDecodeFailedError(version, cause);
+    }
+};
+
+/*
+ * This file is part of midnight-js.
+ * Copyright (C) Midnight Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Reads the UTXO outputs a call's transcript claims on behalf of USERS.
+ *
+ * @param transcript One half of a call's transcript pair. Absent is the normal
+ * shape of a call with no fallible half, and yields no outputs.
+ * @param version The era every failure raised here names.
+ * @param circuitId The entry point every failure raised here names.
+ * @returns One `UtxoOutput` per user-addressed unshielded spend the transcript
+ * claims. Contract-addressed spends are skipped.
+ * @throws ComposeFailedError at stage `'call-dust-payout'` for a user-addressed
+ * dust spend.
+ * @throws ComposeFailedError at stage `'call-unsupported-payout'` for a
+ * user-addressed spend of any token type other than unshielded.
+ * @see {@link ComposeRefusalOrder}
+ */
+const extractUserAddressedOutputs = (transcript, version, circuitId) => {
+    if (transcript === undefined) {
+        return [];
+    }
+    const outputs = [];
+    for (const [[tokenType, publicAddress], value] of transcript.effects.claimedUnshieldedSpends) {
+        if (publicAddress.tag !== 'user') {
+            continue;
+        }
+        if (tokenType.tag === 'dust') {
+            throw new ComposeFailedError(version, 'call-dust-payout', circuitId);
+        }
+        if (tokenType.tag !== 'unshielded') {
+            throw new ComposeFailedError(version, 'call-unsupported-payout', circuitId);
+        }
+        outputs.push({ value, owner: publicAddress.address, type: tokenType.raw });
+    }
+    return outputs;
+};
+/**
+ * Builds the one unshielded offer each segment of a transaction carries, from
+ * EVERY call in the tree.
+ *
+ * @typeParam TOffer The offer type `ledger.UnshieldedOffer.new` returns.
+ * @param calls Every call in the transaction's tree — cross-contract callees
+ * as well as the root call, since any of them can produce a payout.
+ * @param ledger The era module slice carrying `UnshieldedOffer`.
+ * @param version The era every failure raised here names.
+ * @returns The guaranteed and fallible offers. A segment with nothing to pay
+ * out gets no offer at all rather than an empty one.
+ * @throws ComposeFailedError from {@link extractUserAddressedOutputs} for a
+ * user-addressed spend this seam cannot pay out.
+ * @see {@link ComposeRefusalOrder}
+ */
+const aggregateUnshieldedOffers = (calls, ledger, version) => {
+    const guaranteedOutputs = calls.flatMap((call) => extractUserAddressedOutputs(call.guaranteed, version, call.circuitId));
+    const fallibleOutputs = calls.flatMap((call) => extractUserAddressedOutputs(call.fallible, version, call.circuitId));
+    return {
+        guaranteed: guaranteedOutputs.length > 0 ? ledger.UnshieldedOffer.new([], guaranteedOutputs, []) : undefined,
+        fallible: fallibleOutputs.length > 0 ? ledger.UnshieldedOffer.new([], fallibleOutputs, []) : undefined
+    };
+};
+
+/*
+ * This file is part of midnight-js.
+ * Copyright (C) Midnight Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Composes a v8-native call transaction from one call's inputs and immediately
+ * serializes it. The call prototype comes from {@link assembleCallPrototype}
+ * against the injected v8 module.
+ *
+ * Never proves the transaction: the returned bytes are an UNPROVEN,
+ * tag-prefixed serialization, exactly what `Transaction.serialize()` produces
+ * before `.prove()` is ever called.
+ *
+ * @param options The call's inputs, offers and envelope options.
+ * @param v8 The v8 ledger module, as handed over by `loadLedger8`
+ *   (`./load.ts`).
+ * @returns The UNPROVEN, serialized call transaction.
+ * @throws ComposeOptionError If `networkId` is empty or `ttl` is not a valid
+ *   instant.
+ * @throws ComposeFailedError If `contractState` has no registered operation for
+ *   `circuitId` (stage `'call-operation'`), or the operation it does have
+ *   carries no verifier key (stage `'call-verifier-key'`), plus every stage
+ *   {@link assembleCallPrototype} and {@link aggregateUnshieldedOffers} raise.
+ * @see {@link ComposeRefusalOrder}
+ */
+const composeV8CallTx = (options, v8) => {
+    const { contractAddress, contractState, networkId, ttl, guaranteedZswapOffer, fallibleZswapOffer } = options;
+    assertComposeEnvelope(options, 'v8');
+    const prototype = assembleCallPrototype(v8, {
+        circuitId: options.circuitId,
+        contractAddress,
+        transcript: options.transcript,
+        privateTranscriptOutputs: options.privateTranscriptOutputs,
+        input: options.input,
+        output: options.output,
+        communicationCommitmentRandomness: options.communicationCommitmentRandomness,
+        ledgerParameters: options.ledgerParameters,
+        operations: contractState,
+        stage: 'call-operation',
+        version: 'v8'
+    });
+    const intent = v8.Intent.new(ttl).addCall(prototype);
+    // Read the partitioned pair back off the intent rather than re-deriving it,
+    // and attach the payout on this era too -- see ComposeRefusalOrder.
+    const unshielded = aggregateUnshieldedOffers(intent.actions
+        .filter((action) => action instanceof v8.ContractCall)
+        .map((call) => ({
+        circuitId: entryPointName(call.entryPoint),
+        guaranteed: call.guaranteedTranscript,
+        fallible: call.fallibleTranscript
+    })), v8, 'v8');
+    if (unshielded.guaranteed !== undefined) {
+        intent.guaranteedUnshieldedOffer = unshielded.guaranteed;
+    }
+    if (unshielded.fallible !== undefined) {
+        intent.fallibleUnshieldedOffer = unshielded.fallible;
+    }
+    return v8.Transaction.fromPartsRandomized(networkId, guaranteedZswapOffer, fallibleZswapOffer, intent).serialize();
+};
+
+/*
+ * This file is part of midnight-js.
+ * Copyright (C) Midnight Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Bridges a raw, serialized contract state into the v8 era, reporting a
+ * rejected envelope as {@link ComposeOptionError} rather than letting a raw
+ * decoder failure escape.
+ */
+const readContractState$1 = (raw, v8) => {
+    try {
+        return v8.ContractState.deserialize(raw);
+    }
+    catch (cause) {
+        throw new ComposeOptionError('v8', 'contractState', cause);
+    }
+};
+/**
+ * Reads a serialized Zswap offer into the v8 era, reporting bytes this era
+ * cannot decode as {@link ComposeOptionError}. An absent offer is the normal
+ * shape of a call that moved no shielded coins, and stays absent.
+ *
+ * @see {@link ComposeRefusalOrder}
+ */
+const readZswapOffer$1 = (raw, v8) => {
+    if (raw === undefined) {
+        return undefined;
+    }
+    try {
+        return v8.ZswapOffer.deserialize('pre-proof', raw);
+    }
+    catch (cause) {
+        throw new ComposeOptionError('v8', 'zswapOffer', cause);
+    }
+};
+/**
+ * Maps the era-facade's call options onto the v8-native composition leg
+ * (`./compose.ts`).
+ *
+ * This era composes exactly one call: a `calls` tree with more than one entry
+ * is refused rather than silently narrowed. A Zswap offer is NOT refused.
+ *
+ * @param options The era-facade call options.
+ * @param v8 The v8 ledger module, as handed over by `loadLedger8`
+ *   (`./load.ts`).
+ * @returns The UNPROVEN, serialized call transaction.
+ * @throws ComposeOptionError If an option cannot be used: a malformed envelope
+ *   option, unreadable offer or contract-state bytes, or more than one entry in
+ *   `calls`.
+ * @throws ComposeFailedError If `calls` is empty (stage `'call-empty'`), and
+ *   for every stage the composition leg this delegates to can raise.
+ * @see {@link ComposeRefusalOrder}
+ * @see {@link EraSeam}
+ */
+const composeEraV8CallTx = (options, v8) => {
+    const { calls, networkId, ttl, guaranteedZswapOffer, fallibleZswapOffer } = options;
+    // Checked here, not left to the inner leg, so both arms refuse in the same
+    // order; the re-check in the leg is idempotent -- see ComposeRefusalOrder.
+    assertComposeEnvelope(options, 'v8');
+    if (calls.length === 0) {
+        throw new ComposeFailedError('v8', 'call-empty', NO_CIRCUIT);
+    }
+    // Both offers are read before anything is composed -- see
+    // ComposeRefusalOrder.
+    const guaranteedOffer = readZswapOffer$1(guaranteedZswapOffer, v8);
+    const fallibleOffer = readZswapOffer$1(fallibleZswapOffer, v8);
+    if (calls.length > 1) {
+        throw new ComposeOptionError('v8', 'calls');
+    }
+    const [call] = calls;
+    return composeV8CallTx({
+        circuitId: call.circuitId,
+        contractAddress: call.contractAddress,
+        contractState: readContractState$1(call.contractState, v8),
+        transcript: call.transcript,
+        privateTranscriptOutputs: call.privateTranscriptOutputs,
+        input: call.input,
+        output: call.output,
+        communicationCommitmentRandomness: call.communicationCommitmentRandomness,
+        // Carried across the adapter, not dropped. Without this the retained-native arm silently
+        // partitions against this era's INITIAL parameters while the caller believed it had supplied
+        // the chain's -- the same defect this option exists to close, one layer down.
+        ledgerParameters: call.ledgerParameters,
+        networkId,
+        ttl,
+        guaranteedZswapOffer: guaranteedOffer,
+        fallibleZswapOffer: fallibleOffer
+    }, v8);
+};
+/**
+ * Maps the era-facade's deploy options onto the v8-native deploy leg
+ * (`./deploy.ts`).
+ *
+ * `verifierKeys` is optional on the facade but required here: this era's deploy
+ * leg registers the compiled contract's keys onto the initial state itself, so
+ * the omission is reported as {@link ComposeOptionError}.
+ *
+ * The contract state crosses into the leg by BYTES, which is what that leg
+ * takes: it deserializes into its own era rather than accepting a handle.
+ *
+ * @param options The era-facade deploy options.
+ * @param v8 The v8 ledger module, as handed over by `loadLedger8`
+ *   (`./load.ts`).
+ * @returns The UNPROVEN, serialized deploy transaction, the address it deploys
+ *   at, and the registered initial state.
+ * @throws ComposeOptionError If an option cannot be used: a malformed envelope
+ *   option, unreadable offer bytes, or an omitted `verifierKeys` map.
+ * @throws ComposeFailedError For every stage the deploy leg this delegates to
+ *   can raise.
+ * @see {@link VerifierKeys}
+ * @see {@link ComposeRefusalOrder}
+ * @see {@link EraSeam}
+ */
+const composeEraV8DeployTx = (options, v8) => {
+    const { contractState, verifierKeys, networkId, ttl, guaranteedZswapOffer } = options;
+    // See `composeEraV8CallTx` — hoisted so both arms refuse the envelope first.
+    assertComposeEnvelope(options, 'v8');
+    const guaranteedOffer = readZswapOffer$1(guaranteedZswapOffer, v8);
+    if (verifierKeys === undefined) {
+        throw new ComposeOptionError('v8', 'verifierKeys');
+    }
+    return composeV8DeployTx({ contractState, verifierKeys, networkId, ttl, guaranteedZswapOffer: guaranteedOffer }, v8);
+};
+
+/*
+ * This file is part of midnight-js.
+ * Copyright (C) Midnight Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Bridges a raw, serialized contract state into the v9 era, reporting a
+ * rejected envelope as {@link ComposeOptionError} -- see ComposeRefusalOrder.
+ */
+const readContractState = (raw) => {
+    try {
+        return ledgerV9.ContractState.deserialize(raw);
+    }
+    catch (cause) {
+        throw new ComposeOptionError('v9', 'contractState', cause);
+    }
+};
+/**
+ * Reads a serialized Zswap offer, reporting bytes this era cannot decode as
+ * {@link ComposeOptionError}. An absent offer is the normal shape of a call
+ * that moved no shielded coins, and stays absent.
+ */
+const readZswapOffer = (raw) => {
+    if (raw === undefined) {
+        return undefined;
+    }
+    try {
+        return ledgerV9.ZswapOffer.deserialize('pre-proof', raw);
+    }
+    catch (cause) {
+        throw new ComposeOptionError('v9', 'zswapOffer', cause);
+    }
+};
+/**
+ * Composes a v9-native call transaction from one or more contract calls and
+ * immediately serializes it.
+ *
+ * Never proves the transaction: the returned bytes are an UNPROVEN,
+ * tag-prefixed serialization, exactly what `Transaction.serialize()` produces
+ * before `.prove()` is ever called.
+ *
+ * @param options The calls to compose and the transaction-wide envelope.
+ * @returns The serialized UNPROVEN transaction.
+ * @throws ComposeFailedError if the call list is empty (stage `'call-empty'`)
+ * or a call cannot be assembled; `stage` names which step refused it.
+ * @throws ComposeOptionError if the network id, the ttl, a Zswap offer or a
+ * call's contract state is unusable.
+ * @see {@link ComposeRefusalOrder}
+ */
+const composeV9CallTx = (options) => {
+    const { calls, networkId, ttl, guaranteedZswapOffer, fallibleZswapOffer } = options;
+    assertComposeEnvelope(options, 'v9');
+    if (calls.length === 0) {
+        throw new ComposeFailedError('v9', 'call-empty', NO_CIRCUIT);
+    }
+    // Read both offers before composing anything -- see ComposeRefusalOrder.
+    const guaranteedOffer = readZswapOffer(guaranteedZswapOffer);
+    const fallibleOffer = readZswapOffer(fallibleZswapOffer);
+    let intent = ledgerV9.Intent.new(ttl);
+    for (const call of calls) {
+        intent = intent.addCall(assembleCallPrototype(ledgerV9, {
+            circuitId: call.circuitId,
+            contractAddress: call.contractAddress,
+            transcript: call.transcript,
+            privateTranscriptOutputs: call.privateTranscriptOutputs,
+            input: call.input,
+            output: call.output,
+            communicationCommitmentRandomness: call.communicationCommitmentRandomness,
+            ledgerParameters: call.ledgerParameters,
+            operations: readContractState(call.contractState),
+            stage: 'call-operation',
+            version: 'v9'
+        }));
+    }
+    // Read the partitioned pairs back off the intent rather than re-deriving
+    // them -- see ComposeRefusalOrder.
+    const unshielded = aggregateUnshieldedOffers(intent.actions
+        .filter((action) => action instanceof ledgerV9.ContractCall)
+        .map((call) => ({
+        circuitId: entryPointName(call.entryPoint),
+        guaranteed: call.guaranteedTranscript,
+        fallible: call.fallibleTranscript
+    })), ledgerV9, 'v9');
+    if (unshielded.guaranteed !== undefined) {
+        intent.guaranteedUnshieldedOffer = unshielded.guaranteed;
+    }
+    if (unshielded.fallible !== undefined) {
+        intent.fallibleUnshieldedOffer = unshielded.fallible;
+    }
+    return ledgerV9.Transaction.fromPartsRandomized(networkId, guaranteedOffer, fallibleOffer, intent).serialize();
+};
+/**
+ * Registers a verifier key for every entry point the state declares, against
+ * the map validated by {@link resolveVerifierKeyRegistrations} -- see
+ * VerifierKeys.
+ */
+const registerVerifierKeys = (contractState, verifierKeys) => {
+    for (const { entryPoint, circuitId, verifierKey } of resolveVerifierKeyRegistrations(contractState.operations(), verifierKeys, 'v9')) {
+        const operation = new ledgerV9.ContractOperation();
+        try {
+            operation.verifierKey = verifierKey;
+        }
+        catch (cause) {
+            throw new ComposeFailedError('v9', 'deploy-verifier-key-blob', circuitId, cause);
+        }
+        contractState.setOperation(entryPoint, operation);
+    }
+};
+/**
+ * Refuses a state that still declares an entry point with a blank verifier key
+ * when no key map was supplied -- see VerifierKeys.
+ */
+const assertStateCarriesKeys = (contractState) => {
+    for (const entryPoint of contractState.operations()) {
+        // `?.` is deliberate here, unlike in `../shared/contract-state.ts`, and so
+        // is raising the OPTION error rather than the `'deploy-verifier-key'` stage
+        // -- see VerifierKeys.
+        if (contractState.operation(entryPoint)?.verifierKey === undefined) {
+            throw new ComposeOptionError('v9', 'verifierKeys');
+        }
+    }
+};
+/**
+ * Composes a v9-native deploy transaction from a serialized initial contract
+ * state and immediately serializes it, returning the transaction together with
+ * the address the deployment will have and the initial state that address is
+ * derived from.
+ *
+ * Never proves the transaction: the returned bytes are an UNPROVEN,
+ * tag-prefixed serialization, exactly what `Transaction.serialize()` produces
+ * before `.prove()` is ever called.
+ *
+ * With `verifierKeys` supplied, every declared entry point is registered before
+ * the address is derived. Without it, the state is deployed exactly as given —
+ * which is checked rather than assumed, see {@link assertStateCarriesKeys}.
+ *
+ * @param options The serialized 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 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.
+ * @throws ComposeOptionError if the network id, the ttl, the Zswap offer or
+ * the state bytes are unusable, or if `verifierKeys` was omitted for a state
+ * that still declares a blank key.
+ * @see {@link VerifierKeys}
+ * @see {@link ComposeRefusalOrder}
+ */
+const composeV9DeployTx = (options) => {
+    const { contractState, verifierKeys, networkId, ttl, guaranteedZswapOffer } = options;
+    assertComposeEnvelope(options, 'v9');
+    const guaranteedOffer = readZswapOffer(guaranteedZswapOffer);
+    const state = readContractState(contractState);
+    if (verifierKeys === undefined) {
+        assertStateCarriesKeys(state);
+    }
+    else {
+        registerVerifierKeys(state, verifierKeys);
+    }
+    const deploy = new ledgerV9.ContractDeploy(state);
+    const intent = ledgerV9.Intent.new(ttl).addDeploy(deploy);
+    return {
+        transaction: ledgerV9.Transaction.fromParts(networkId, guaranteedOffer, undefined, intent).serialize(),
+        contractAddress: deploy.address,
+        initialState: deploy.initialState.serialize()
+    };
+};
+
+/*
+ * This file is part of midnight-js.
+ * Copyright (C) Midnight Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Reads the primary {@link EncodedStateValue} out of a raw, serialized
+ * post-fork `contract-state[v8]` envelope.
+ *
+ * Reachable without a pre-fork runtime, unlike {@link extractEncodedStateValue},
+ * which requires one for every era.
+ *
+ * @param raw The serialized `contract-state[v8]` envelope.
+ * @returns The primary state read out of the envelope.
+ * @throws DownConvertFailedError at stage `'v9 envelope extraction'` if the
+ * envelope is malformed, truncated, over-long, or tagged for the other era,
+ * carrying the runtime's own diagnosis on `cause`.
+ * @see {@link FailClosedDecoding}
+ */
+const extractV9EncodedStateValue = (raw) => {
+    try {
+        return ContractState.deserialize(raw).data.state.encode();
+    }
+    catch (cause) {
+        throw new DownConvertFailedError('v9 envelope extraction', cause);
+    }
+};
+/**
+ * One decoder per {@link LedgerVersion}:
+ *
+ * - `v9` — a post-fork `contract-state[v8]`-tagged envelope, read via
+ *   `@midnightntwrk/ledger-v9`.
+ * - `v8` — a pre-fork `contract-state[v6]`-tagged envelope, read via
+ *   onchain-runtime-v3, the same codec that produced it.
+ *
+ * A total `Record`, built on a null prototype and frozen -- see the
+ * SharedTableDiscipline document.
+ */
+const ENVELOPE_DECODERS = Object.freeze(Object.assign(Object.create(null), {
+    v8: (raw, ledger8ContractState) => ledger8ContractState.deserialize(raw).data.state.encode(),
+    // A reference to the standalone decoder, not a second copy of the same
+    // read -- see FailClosedDecoding.
+    v9: extractV9EncodedStateValue
+}));
+/**
+ * Extracts the primary {@link EncodedStateValue} out of a raw, serialized
+ * `ContractState` envelope, using the decoder that matches `version`.
+ *
+ * @param raw The serialized envelope.
+ * @param version The era whose decoder reads `raw`. Validated at runtime, not
+ * merely type-checked.
+ * @param ledger8ContractState The pre-fork `ContractState` statics. Required
+ * for every `version`, not just `'v8'`, and checked before any decoding
+ * happens.
+ * @returns The primary state read out of the envelope — never a silently
+ * empty or partial one.
+ * @throws UnknownLedgerVersionError if `version` is not a member of
+ * `LEDGER_VERSIONS`.
+ * @throws Ledger8RuntimeInvalidError if `ledger8ContractState` does not carry
+ * `deserialize`.
+ * @throws DownConvertFailedError at stage `'v8 envelope extraction'` or
+ * `'v9 envelope extraction'` if the envelope cannot be read, carrying the
+ * runtime's own diagnosis on `cause`.
+ * @see {@link FailClosedDecoding}
+ * @see {@link SharedTableDiscipline}
+ */
+const extractEncodedStateValue = (raw, version, ledger8ContractState) => {
+    const decoder = ENVELOPE_DECODERS[version];
+    if (typeof decoder !== 'function') {
+        throw new UnknownLedgerVersionError(String(version));
+    }
+    if (typeof ledger8ContractState?.deserialize !== 'function') {
+        throw new Ledger8RuntimeInvalidError('ContractState.deserialize');
+    }
+    try {
+        return decoder(raw, ledger8ContractState);
+    }
+    catch (cause) {
+        // THE STAGE IS CHECKED, not just the class: a decoder is injectable, so one
+        // that wrapped at a different stage must not pass through -- see
+        // FailClosedDecoding.
+        const stage = `${version} envelope extraction`;
+        throw cause instanceof DownConvertFailedError && cause.stage === stage
+            ? cause
+            : new DownConvertFailedError(stage, cause);
+    }
+};
+
+/*
+ * This file is part of midnight-js.
+ * Copyright (C) Midnight Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+// One memo slot per era, never one shared slot, and both arms are frozen --
+// see SharedTableDiscipline and EraSeam.
+let v8EraPromise;
+let v9EraPromise;
+/** The v9 arm. Wholly synchronous -- see the EraSeam document. */
+const createV9Era = () => {
+    const era = {
+        version: 'v9',
+        extractState: (raw) => extractStateWith(raw, 'v9', extractV9EncodedStateValue),
+        decodeContractState: (raw) => decodeContractStateWith(raw, 'v9', ledgerV9),
+        composeCallTx: composeV9CallTx,
+        composeDeployTx: composeV9DeployTx,
+        partitionCallTranscript: (options) => {
+            // See the v8 arm: the assembler's tuple is readonly, the ledger's is not.
+            const [guaranteed, fallible] = partitionCallTranscript(ledgerV9, { ...options, version: 'v9' });
+            return [guaranteed, fallible];
+        }
+    };
+    return Object.freeze(era);
+};
+/**
+ * The v8 arm. Acquires the retained pre-fork ledger and binds it into closure,
+ * so the era's own methods stay synchronous -- see the EraSeam document for why
+ * the acquisition is hoisted here.
+ */
+const createV8Era = async () => {
+    const v8 = await loadLedger8();
+    const era = {
+        version: 'v8',
+        extractState: (raw) => extractStateWith(raw, 'v8', (bytes) => extractEncodedStateValue(bytes, 'v8', v8.ContractState)),
+        decodeContractState: (raw) => decodeContractStateWith(raw, 'v8', v8),
+        composeCallTx: (options) => composeEraV8CallTx(options, v8),
+        composeDeployTx: (options) => composeEraV8DeployTx(options, v8),
+        partitionCallTranscript: (options) => {
+            // Copied into a mutable pair rather than handed on: the assembler answers
+            // with a readonly tuple, and the ledger's own `PartitionedTranscript` --
+            // which is what every consumer of this pair is typed against -- is not.
+            const [guaranteed, fallible] = partitionCallTranscript(v8, { ...options, version: 'v8' });
+            return [guaranteed, fallible];
+        }
+    };
+    return Object.freeze(era);
+};
+/**
+ * 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}
+ */
+const loadLedgerEra = (version) => {
+    switch (version) {
+        case 'v9':
+            return (v9EraPromise ??= Promise.resolve(createV9Era()));
+        case 'v8':
+            return (v8EraPromise ??= createV8Era().catch((error) => {
+                v8EraPromise = undefined;
+                throw error;
+            }));
+        default: {
+            // `const unhandled: never` is a compile-time exhaustiveness gate, and the
+            // runtime rejection is not redundant with it -- see SharedTableDiscipline.
+            const unhandled = version;
+            return Promise.reject(new UnknownLedgerVersionError(String(unhandled)));
+        }
+    }
+};
+
+/*
+ * This file is part of midnight-js.
+ * Copyright (C) Midnight Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+let enginePromise;
+/**
+ * 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}
+ */
+const loadLedger8Engine = () => (enginePromise ??= import('./engine.js')
+    .then((engineModule) => engineModule.createLedger8Engine())
+    .catch((error) => {
+    enginePromise = undefined;
+    throw error instanceof Ledger8RuntimeMissingError || error instanceof Ledger8InstanceMismatchError
+        ? error
+        : new Ledger8RuntimeMissingError('/engine', error);
+}));
+
+export { ComposeFailedError, ComposeOptionError, DownConvertFailedError, Ledger8InstanceMismatchError, Ledger8RuntimeInvalidError, Ledger8RuntimeMissingError, NO_CIRCUIT, StateDecodeFailedError, UnknownLedgerVersionError, loadLedger8, loadLedger8Engine, loadLedgerEra };
 //# sourceMappingURL=index.js.map