@midnightntwrk/midnight-js-protocol 0.0.0-stage → 5.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/README.md +291 -2
  2. package/dist/compact-js-v8-effect.d.ts +1 -0
  3. package/dist/compact-js-v8-effect.js +2 -0
  4. package/dist/compact-js-v8-effect.js.map +1 -0
  5. package/dist/engine.d.ts +420 -0
  6. package/dist/engine.js +832 -0
  7. package/dist/engine.js.map +1 -0
  8. package/dist/errors.d.ts +601 -0
  9. package/dist/errors.js +810 -0
  10. package/dist/errors.js.map +1 -0
  11. package/dist/index.d.ts +1471 -0
  12. package/dist/index.js +799 -0
  13. package/dist/index.js.map +1 -0
  14. package/dist/platform-effect-configuration.d.ts +1 -0
  15. package/dist/platform-effect-configuration.js +2 -0
  16. package/dist/platform-effect-configuration.js.map +1 -0
  17. package/dist/platform-effect-contract-address.d.ts +1 -0
  18. package/dist/platform-effect-contract-address.js +2 -0
  19. package/dist/platform-effect-contract-address.js.map +1 -0
  20. package/dist/platform.d.ts +1 -0
  21. package/dist/platform.js +2 -0
  22. package/dist/platform.js.map +1 -0
  23. package/dist/prove.d.ts +45 -0
  24. package/dist/prove.js +61 -0
  25. package/dist/prove.js.map +1 -0
  26. package/dist/shared/compose-options-BFA09u9q.js +468 -0
  27. package/dist/shared/compose-options-BFA09u9q.js.map +1 -0
  28. package/dist/shared/ledger-transaction-DQP8J8tv.js +134 -0
  29. package/dist/shared/ledger-transaction-DQP8J8tv.js.map +1 -0
  30. package/dist/shared/load-BMVWoBo6.js +49 -0
  31. package/dist/shared/load-BMVWoBo6.js.map +1 -0
  32. package/dist/shared/transaction-tags-I3J_Hh8r.js +82 -0
  33. package/dist/shared/transaction-tags-I3J_Hh8r.js.map +1 -0
  34. package/dist/transaction.d.ts +92 -0
  35. package/dist/transaction.js +6 -0
  36. package/dist/transaction.js.map +1 -0
  37. package/dist/v8.d.ts +1 -0
  38. package/dist/v8.js +3 -0
  39. package/dist/v8.js.map +1 -0
  40. package/dist/v9-compact-js-effect-contract.d.ts +1 -0
  41. package/dist/v9-compact-js-effect-contract.js +2 -0
  42. package/dist/v9-compact-js-effect-contract.js.map +1 -0
  43. package/dist/v9-compact-js-effect.d.ts +1 -0
  44. package/dist/v9-compact-js-effect.js +2 -0
  45. package/dist/v9-compact-js-effect.js.map +1 -0
  46. package/dist/v9-compact-js.d.ts +1 -0
  47. package/dist/v9-compact-js.js +2 -0
  48. package/dist/v9-compact-js.js.map +1 -0
  49. package/dist/v9-compact-runtime.d.ts +1 -0
  50. package/dist/v9-compact-runtime.js +2 -0
  51. package/dist/v9-compact-runtime.js.map +1 -0
  52. package/dist/v9-onchain-runtime.d.ts +1 -0
  53. package/dist/v9-onchain-runtime.js +2 -0
  54. package/dist/v9-onchain-runtime.js.map +1 -0
  55. package/dist/v9.d.ts +1 -0
  56. package/dist/v9.js +2 -0
  57. package/dist/v9.js.map +1 -0
  58. package/dist/version.d.ts +173 -0
  59. package/dist/version.js +125 -0
  60. package/dist/version.js.map +1 -0
  61. package/package.json +122 -3
@@ -0,0 +1,1471 @@
1
+ import * as ledgerV9 from '@midnightntwrk/ledger-v9';
2
+ import { EncodedStateValue, Op, AlignedValue, CallContext, Effects, CoinCommitment, Transcript, TokenType, ContractCallPrototype } from '@midnightntwrk/ledger-v9';
3
+ export { EncodedStateValue } from '@midnightntwrk/ledger-v9';
4
+ import * as V8 from '@midnightntwrk/ledger-v8';
5
+ import { ContractExecutable } from '@midnight-ntwrk/compact-js/v8/effect';
6
+ import * as platformJs from '@midnight-ntwrk/platform-js';
7
+ export { platformJs as platform };
8
+
9
+ /**
10
+ * The two ledger runtimes midnight-js can talk to. `v8` backs the node 1.x
11
+ * line; `v9` backs the 2.x line. This is a closed, exhaustive set — see
12
+ * `protocolVersionToLedger` (`../version.ts`) for how a raw `protocolVersion`
13
+ * integer maps onto it.
14
+ *
15
+ * compact-js names the same era by number: its `Ledger.Era['ledger']` (for
16
+ * example `executable.era.ledger`) is `8` for `'v8'` and `9` for `'v9'`.
17
+ *
18
+ * @see {@link SharedTableDiscipline} for why the array is frozen.
19
+ * @see {@link ModuleGraphAndLazyLoading} for why the constant is declared in
20
+ * this leaf module and re-exported by `../version.ts`.
21
+ */
22
+ declare const LEDGER_ERAS: readonly ["v8", "v9"];
23
+ type LedgerEra = (typeof LEDGER_ERAS)[number];
24
+ /**
25
+ * The era whose objects this build links eagerly, today through `./v9`.
26
+ *
27
+ * "Current" is relative: today it is ledger 9 (`'v9'`). At the next hard fork it
28
+ * moves to the new ledger and ledger 9 joins {@link RetainedLedgerEra}. Code
29
+ * bound to one ledger is named after that ledger (`Ledger9*`) instead.
30
+ *
31
+ * A protocol fact rather than a consumer's choice: it is decided by which
32
+ * ledger the package links eagerly, and every other era is reached lazily and
33
+ * crosses package boundaries as bytes. Declared here so that no package
34
+ * downstream restates "which era is now" as a literal of its own.
35
+ *
36
+ * The type is the single literal, not {@link LedgerEra}, so a value typed
37
+ * by it DISCRIMINATES: `midnight-js-contracts` types a current-era result's
38
+ * `era` with it, so a union of both eras' results narrows on `era`.
39
+ */
40
+ declare const CURRENT_LEDGER_ERA: "v9";
41
+ type CurrentLedgerEra = typeof CURRENT_LEDGER_ERA;
42
+ /**
43
+ * Every era this build still speaks but does not run live: its runtime is
44
+ * loaded only on demand, through `loadLedger8Protocol`.
45
+ *
46
+ * "Retained" is relative: today the set is ledger 8 (`'v8'`). At the next hard
47
+ * fork the then-current ledger joins it. Code bound to one ledger is named
48
+ * after that ledger (`Ledger8*`) instead.
49
+ *
50
+ * Defined as the complement of {@link CURRENT_LEDGER_ERA}, so a further
51
+ * era joins this set by being added to {@link LEDGER_ERAS} and nothing
52
+ * else. The value list below is checked against that complement at build time.
53
+ */
54
+ type RetainedLedgerEra = Exclude<LedgerEra, CurrentLedgerEra>;
55
+ declare const RETAINED_LEDGER_ERAS: readonly ["v8"];
56
+
57
+ /** Every transaction stage, in the order a transaction goes through them. */
58
+ declare const TRANSACTION_STAGES: readonly ["Unproven", "Unbound", "Finalized"];
59
+ /** The point in its life a transaction has reached: before proving, after proving, after binding. */
60
+ type TransactionStage = (typeof TRANSACTION_STAGES)[number];
61
+ /**
62
+ * The full header each ledger era writes in front of a transaction at each stage: the schema
63
+ * version, then the signature, proof and binding markers.
64
+ */
65
+ declare const LEDGER_TRANSACTION_TAGS: Readonly<{
66
+ readonly v8: Readonly<{
67
+ Unproven: "midnight:transaction[v9](signature[v1],proof-preimage,embedded-fr[v1])";
68
+ Unbound: "midnight:transaction[v9](signature[v1],proof,embedded-fr[v1])";
69
+ Finalized: "midnight:transaction[v9](signature[v1],proof,pedersen-schnorr[v1])";
70
+ }>;
71
+ readonly v9: Readonly<{
72
+ Unproven: "midnight:transaction[v12](signature[v2],proof-preimage,embedded-fr[v1])";
73
+ Unbound: "midnight:transaction[v12](signature[v2],proof,embedded-fr[v1])";
74
+ Finalized: "midnight:transaction[v12](signature[v2],proof,pedersen-schnorr[v1])";
75
+ }>;
76
+ }>;
77
+
78
+ /**
79
+ * Stable error-code strings for this package. Every error class in this module
80
+ * carries one of these on its `code` field, which is the field a consumer
81
+ * switches on to tell one failure from another.
82
+ *
83
+ * @see {@link SharedTableDiscipline}
84
+ */
85
+ declare const PROTOCOL_ERROR_CODES: Readonly<{
86
+ readonly UNKNOWN_PROTOCOL_VERSION_READ: "MIDNIGHT_JS_P_UNKNOWN_PROTOCOL_VERSION_READ";
87
+ readonly UNKNOWN_PROTOCOL_VERSION_CONSTRUCT: "MIDNIGHT_JS_P_UNKNOWN_PROTOCOL_VERSION_CONSTRUCT";
88
+ readonly LEDGER8_RUNTIME_MISSING: "MIDNIGHT_JS_P_LEDGER8_RUNTIME_MISSING";
89
+ readonly STATE_CONVERSION_FAILED: "MIDNIGHT_JS_P_STATE_CONVERSION_FAILED";
90
+ readonly COMPOSE_FAILED: "MIDNIGHT_JS_P_COMPOSE_FAILED";
91
+ readonly COMPOSE_OPTION_INVALID: "MIDNIGHT_JS_P_COMPOSE_OPTION_INVALID";
92
+ readonly STATE_DECODE_FAILED: "MIDNIGHT_JS_P_STATE_DECODE_FAILED";
93
+ readonly STATE_INCONSISTENT: "MIDNIGHT_JS_P_STATE_INCONSISTENT";
94
+ readonly UNKNOWN_LEDGER_ERA: "MIDNIGHT_JS_P_UNKNOWN_LEDGER_ERA";
95
+ readonly LEDGER8_RUNTIME_INVALID: "MIDNIGHT_JS_P_LEDGER8_RUNTIME_INVALID";
96
+ readonly PAYLOAD_NOT_A_TRANSACTION: "MIDNIGHT_JS_P_PAYLOAD_NOT_A_TRANSACTION";
97
+ readonly CONTRACT_EXECUTION_FAILED: "MIDNIGHT_JS_P_CONTRACT_EXECUTION_FAILED";
98
+ readonly MAINTENANCE_AUTHORITY_MISMATCH: "MIDNIGHT_JS_P_MAINTENANCE_AUTHORITY_MISMATCH";
99
+ }>;
100
+ /** The union of every value in {@link PROTOCOL_ERROR_CODES}; the type of every error class's `code` field. */
101
+ type ProtocolErrorCode = (typeof PROTOCOL_ERROR_CODES)[keyof typeof PROTOCOL_ERROR_CODES];
102
+ declare const MIDNIGHT_JS_ERROR_CATEGORIES: Readonly<{
103
+ readonly USAGE: "USAGE";
104
+ readonly ENVIRONMENT: "ENVIRONMENT";
105
+ readonly TRANSIENT: "TRANSIENT";
106
+ readonly REJECTED: "REJECTED";
107
+ readonly UNCERTAIN: "UNCERTAIN";
108
+ readonly INTEGRITY: "INTEGRITY";
109
+ readonly INTERNAL: "INTERNAL";
110
+ }>;
111
+ /**
112
+ * What the caller should do about an error: fix its own code (`USAGE`), fix the installation or
113
+ * infrastructure (`ENVIRONMENT`), retry (`TRANSIENT`), handle a refusal by contract or network rules
114
+ * (`REJECTED`), check on chain whether a submitted transaction landed before doing anything else
115
+ * (`UNCERTAIN`), stop and alert on bad data (`INTEGRITY`), or report a midnight-js bug (`INTERNAL`).
116
+ */
117
+ type MidnightJsErrorCategory = (typeof MIDNIGHT_JS_ERROR_CATEGORIES)[keyof typeof MIDNIGHT_JS_ERROR_CATEGORIES];
118
+ type MidnightJsErrorCodeFormat = `MIDNIGHT_JS_${string}`;
119
+ /**
120
+ * Base class of every error midnight-js raises itself. An error without a registered code came from a
121
+ * dependency, the platform or user code, and midnight-js passed it through unchanged. Recognise one with
122
+ * `hasErrorCode`, `isMidnightJsError` or `errorCategory` from the `midnight-js-utils` package: they read
123
+ * `code`, so they also work when two copies of a package are installed, where `instanceof` does not.
124
+ */
125
+ declare abstract class MidnightJsError extends Error {
126
+ abstract readonly code: MidnightJsErrorCodeFormat;
127
+ abstract readonly category: MidnightJsErrorCategory;
128
+ }
129
+ declare const PROTOCOL_ERROR_CATEGORIES: Readonly<Record<ProtocolErrorCode, MidnightJsErrorCategory>>;
130
+ declare const COMMON_ERROR_CODES: Readonly<{
131
+ readonly INVALID_ARGUMENT: "MIDNIGHT_JS_G_INVALID_ARGUMENT";
132
+ readonly CONFIGURATION_MISSING: "MIDNIGHT_JS_G_CONFIGURATION_MISSING";
133
+ readonly ENVIRONMENT_UNSUPPORTED: "MIDNIGHT_JS_G_ENVIRONMENT_UNSUPPORTED";
134
+ readonly INVARIANT_VIOLATED: "MIDNIGHT_JS_G_INVARIANT_VIOLATED";
135
+ }>;
136
+ type CommonErrorCode = (typeof COMMON_ERROR_CODES)[keyof typeof COMMON_ERROR_CODES];
137
+ declare const COMMON_ERROR_CATEGORIES: Readonly<Record<CommonErrorCode, MidnightJsErrorCategory>>;
138
+ /** A value passed to a midnight-js function is not acceptable. Fix the call. */
139
+ declare class InvalidArgumentError extends MidnightJsError {
140
+ readonly code: "MIDNIGHT_JS_G_INVALID_ARGUMENT";
141
+ readonly category: MidnightJsErrorCategory;
142
+ constructor(message: string, options?: ErrorOptions);
143
+ }
144
+ /** Required setup is missing or was done in the wrong order. */
145
+ declare class ConfigurationError extends MidnightJsError {
146
+ readonly code: "MIDNIGHT_JS_G_CONFIGURATION_MISSING";
147
+ readonly category: MidnightJsErrorCategory;
148
+ constructor(message: string, options?: ErrorOptions);
149
+ }
150
+ /** The JavaScript runtime lacks an API midnight-js needs. */
151
+ declare class EnvironmentUnsupportedError extends MidnightJsError {
152
+ readonly code: "MIDNIGHT_JS_G_ENVIRONMENT_UNSUPPORTED";
153
+ readonly category: MidnightJsErrorCategory;
154
+ constructor(message: string, options?: ErrorOptions);
155
+ }
156
+ /** A condition midnight-js guarantees did not hold. This is a midnight-js bug; report it. */
157
+ declare class InvariantViolationError extends MidnightJsError {
158
+ readonly code: "MIDNIGHT_JS_G_INVARIANT_VIOLATED";
159
+ readonly category: MidnightJsErrorCategory;
160
+ constructor(message: string, options?: ErrorOptions);
161
+ }
162
+ /**
163
+ * Which call path asked for a ledger era:
164
+ * - `'read'` — the version was taken off an existing record.
165
+ * - `'construct'` — the version was chosen to build something new against the
166
+ * network's latest block.
167
+ */
168
+ type VersionResolutionPath = 'read' | 'construct';
169
+ /**
170
+ * Why `protocolVersionToLedger` could not resolve a ledger era:
171
+ * - `'malformed'` — the input was not even a well-formed protocolVersion
172
+ * value (not a non-negative integer).
173
+ * - `'unknown'` — the input was a well-formed integer, but outside every
174
+ * range this framework version knows how to map.
175
+ */
176
+ type ProtocolVersionUnknownReason = 'unknown' | 'malformed';
177
+ /**
178
+ * Thrown by `protocolVersionToLedger` (and, transitively, `versionOfRecord` /
179
+ * `latestNetworkLedgerVersion`) when a raw `protocolVersion` integer cannot be
180
+ * resolved to a `LedgerEra`. Those live in `./version`, which imports this
181
+ * module -- the dependency stays one-way, so they are named here rather than
182
+ * linked.
183
+ *
184
+ * `code` is the field to switch on to tell all four cases apart: it splits
185
+ * `reason` by the `path` that produced it.
186
+ *
187
+ * @param protocolVersion The raw `protocolVersion` value that could not be
188
+ * resolved. Carried for programmatic use, and rendered in the message.
189
+ * @param path Which call path asked for the version — see
190
+ * {@link VersionResolutionPath}.
191
+ * @param reason A malformed input (wrong shape or type, not a
192
+ * protocol-version problem at all) or a well-formed but genuinely unknown
193
+ * version (a real protocol version this framework build does not support
194
+ * yet) — see {@link ProtocolVersionUnknownReason}.
195
+ */
196
+ declare class UnknownProtocolVersionError extends MidnightJsError {
197
+ readonly protocolVersion: number;
198
+ readonly path: VersionResolutionPath;
199
+ readonly reason: ProtocolVersionUnknownReason;
200
+ readonly code: typeof PROTOCOL_ERROR_CODES.UNKNOWN_PROTOCOL_VERSION_READ | typeof PROTOCOL_ERROR_CODES.UNKNOWN_PROTOCOL_VERSION_CONSTRUCT;
201
+ readonly category: MidnightJsErrorCategory;
202
+ constructor(protocolVersion: number, path: VersionResolutionPath, reason: ProtocolVersionUnknownReason);
203
+ }
204
+ /**
205
+ * Which lazily-loaded subpath export {@link Ledger8RuntimeMissingError} failed
206
+ * to acquire. Each chunk pulls a different set of ledger 8 dependencies, so
207
+ * naming the wrong one sends an operator to an entry point that loaded fine.
208
+ *
209
+ * @see {@link ModuleGraphAndLazyLoading}
210
+ */
211
+ type Ledger8Subpath = '/v8' | '/v8/engine';
212
+ /**
213
+ * Thrown when a lazily-loaded subpath export carrying the retained pre-fork
214
+ * runtime could not be acquired at all. Raised by `loadLedger8Protocol`
215
+ * (`lib/v8/load.ts`) and `loadLedger8Engine` (`lib/v8/load-engine.ts`), and
216
+ * surfaced through `createLedger8Engine` and `loadLedgerEra('v8')`.
217
+ *
218
+ * A failed acquisition is not memoised: the next call retries the import.
219
+ * Distinct from {@link Ledger8RuntimeInvalidError}, which reports a runtime
220
+ * that WAS acquired and then handed over incomplete.
221
+ *
222
+ * @param subpath Which chunk failed to load — see {@link Ledger8Subpath}.
223
+ * @param cause The underlying module-resolution or initialisation failure,
224
+ * preserved unchanged. Read it for which module actually failed.
225
+ * @see {@link ModuleGraphAndLazyLoading}
226
+ * @see {@link EraBoundary}
227
+ */
228
+ declare class Ledger8RuntimeMissingError extends MidnightJsError {
229
+ readonly subpath: Ledger8Subpath;
230
+ readonly code: "MIDNIGHT_JS_P_LEDGER8_RUNTIME_MISSING";
231
+ readonly category: MidnightJsErrorCategory;
232
+ constructor(subpath: Ledger8Subpath, cause: unknown);
233
+ }
234
+ /**
235
+ * Which step a {@link StateConversionFailedError} came from. A closed union,
236
+ * so a consumer can `switch` on `stage` exhaustively.
237
+ *
238
+ * `'state conversion'` is the structural round trip `lib/v8/executable.ts`
239
+ * runs before a circuit executes; the other two decode a serialized contract state
240
+ * written by that ledger era, in `lib/era/envelope.ts`.
241
+ *
242
+ * @see {@link FailClosedDecoding}
243
+ */
244
+ type StateConversionStage = 'v8 state read' | 'v9 state read' | 'state conversion';
245
+ /**
246
+ * Thrown when a serialized contract state, or an already-extracted
247
+ * `EncodedStateValue`, cannot be turned into a state a circuit can execute
248
+ * against. Raised by `extractLedger9EncodedStateValue` (`lib/era/envelope.ts`)
249
+ * and by `decodeExecutableStateValue` (`lib/v8/executable.ts`), which refuses a
250
+ * state that decodes but does not re-encode to the bytes it came from.
251
+ *
252
+ * Renders no raw hex and no decoded state contents — only the stage name and
253
+ * the wrapped `cause`.
254
+ *
255
+ * @param stage Which step failed — see {@link StateConversionStage}.
256
+ * @param cause The runtime's own failure, preserved unchanged. It is what
257
+ * distinguishes a tag mismatch from truncated, trailing, or empty input.
258
+ * @see {@link FailClosedDecoding}
259
+ */
260
+ declare class StateConversionFailedError extends MidnightJsError {
261
+ readonly stage: StateConversionStage;
262
+ readonly code: "MIDNIGHT_JS_P_STATE_CONVERSION_FAILED";
263
+ readonly category: MidnightJsErrorCategory;
264
+ constructor(stage: StateConversionStage, cause: unknown);
265
+ }
266
+ /**
267
+ * What `circuitId` a {@link ComposeFailedError} names when the failure happened
268
+ * before any circuit was looked up — only `'call-empty'` reaches this today.
269
+ *
270
+ * Exported, and one literal rather than a per-module copy, so a consumer
271
+ * reading `circuitId` off a caught error can compare against it instead of
272
+ * matching a string this package could change, and so it can never be mistaken
273
+ * for a real entry point a caller might try to resolve.
274
+ *
275
+ * @see {@link ComposeRefusalOrder}
276
+ */
277
+ declare const NO_CIRCUIT = "(none)";
278
+ /**
279
+ * Which composition step {@link ComposeFailedError} failed at.
280
+ *
281
+ * Call stages:
282
+ * - `'call-empty'` — a call transaction was requested with no calls in it.
283
+ * The one stage that names no circuit: it is raised before any circuit is
284
+ * looked up, so it names {@link NO_CIRCUIT}.
285
+ * - `'call-operation'` — a call leg could not resolve a registered operation
286
+ * for the call's circuit on the given contract state.
287
+ * - `'call-verifier-key'` — a call leg resolved a registered operation for the
288
+ * call's circuit, but that operation carries no verifier key, so no ledger
289
+ * could verify a call against it.
290
+ * - `'call-contract-state'` — the call's pre-call state could not be bridged
291
+ * into the target era's own state algebra. Carries the decoder's failure on
292
+ * `cause`.
293
+ * - `'call-transcript-empty'` — a caller-supplied partitioned transcript
294
+ * carried neither a guaranteed nor a fallible half, so the call would record
295
+ * no operations at all.
296
+ * - `'call-partition-context'` — the era rejected the query-context state the
297
+ * call recorded (its block, its starting effects, or one of the commitment
298
+ * indices it registered for a coin received in-contract) while bridging it
299
+ * onto the context the transcript is partitioned against. Carries the
300
+ * runtime's own failure on `cause`.
301
+ * - `'call-partition'` — the ledger rejected the public transcript supplied
302
+ * for a call while splitting it into its guaranteed and fallible halves.
303
+ * Carries the runtime's own failure on `cause`.
304
+ * - `'call-prototype'` — the ledger rejected the call's own inputs while
305
+ * constructing the call prototype. Carries the runtime's failure on `cause`.
306
+ * - `'call-dust-payout'` — a transcript claimed an unshielded spend to a user
307
+ * address in DUST, which has no raw token type to be paid out in.
308
+ * - `'call-unsupported-payout'` — a transcript claimed an unshielded spend to
309
+ * a user address in a token type that cannot be paid out as an unshielded
310
+ * UTXO at all (a shielded token type today).
311
+ *
312
+ * Deploy stages:
313
+ * - `'deploy-verifier-key'` — a deploy leg was given no verifier key for a
314
+ * circuit the contract state declares.
315
+ * - `'deploy-unknown-circuit'` — the verifier-key map handed to a deploy leg
316
+ * names a circuit the contract state does not declare. Registering it would
317
+ * add an entry point the compiled contract never had, and silently change
318
+ * the deployed contract's address.
319
+ * - `'deploy-ambiguous-circuit'` — two entry points the contract state
320
+ * declares resolve to the same name, so the verifier-key map (keyed by
321
+ * name) cannot address them apart. Registering under the shared name would
322
+ * key one slot and leave the other blank.
323
+ * - `'deploy-verifier-key-blob'` — the ledger rejected the verifier-key bytes
324
+ * supplied for a circuit.
325
+ *
326
+ * Maintenance stage:
327
+ * - `'maintenance-update'` — the maintenance update could not be built,
328
+ * signed, or wrapped into a transaction: platform-js refused the contract
329
+ * address, compact-js refused one of its own steps (building the update,
330
+ * creating it with the address and counter, reading the data to sign,
331
+ * signing, attaching the signature), or the ledger refused the signed update
332
+ * when it was wrapped into the transaction. Names the circuit for a
333
+ * verifier-key update and {@link NO_CIRCUIT} for an authority replacement.
334
+ * Carries the refusing library's own failure on `cause`.
335
+ *
336
+ * Keep-state stage:
337
+ * - `'wrap-call'` — the keep-state leg could not resolve a registered
338
+ * operation for the transcript's circuit on the given contract state.
339
+ *
340
+ * Which ledger era the failure happened on is carried separately, on the
341
+ * error's `version` field. Every stage but `'wrap-call'` and
342
+ * `'maintenance-update'` is reachable on both eras; `'wrap-call'` is only ever
343
+ * raised for `'v9'`, and `'maintenance-update'` only for `'v8'`.
344
+ *
345
+ * @see {@link ComposeRefusalOrder}
346
+ * @see {@link VerifierKeys}
347
+ */
348
+ 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' | 'maintenance-update';
349
+ /**
350
+ * Thrown when a transaction cannot be composed because a circuit's operation
351
+ * is missing, under-registered, or names a circuit the contract does not have.
352
+ * `stage` (see {@link ComposeStage}) names which composition step failed and is
353
+ * a closed union, so a consumer can `switch` on it exhaustively; `version`
354
+ * names the ledger era the composition was running against.
355
+ *
356
+ * Most stages carry no `cause`. The exceptions are the stages where a runtime
357
+ * library rejected what it was handed, enumerated under `cause` below.
358
+ *
359
+ * `circuitId` names the entry point, never its raw contents: this class renders
360
+ * no hex and no byte-array dump.
361
+ *
362
+ * @param version The ledger era the composition was running against.
363
+ * @param stage Which composition step failed — see {@link ComposeStage}. A
364
+ * closed union, so a consumer can `switch` on it exhaustively.
365
+ * @param circuitId The entry-point name, already decoded. {@link NO_CIRCUIT}
366
+ * for `'call-empty'`, the one stage raised before any circuit is looked up.
367
+ * @param cause The runtime's own failure, present only for the stages where
368
+ * the ledger rejected caller-supplied bytes — `'call-contract-state'`,
369
+ * `'call-partition-context'`, `'call-partition'`, `'call-prototype'`,
370
+ * `'deploy-verifier-key-blob'` — and for `'maintenance-update'`, where it is
371
+ * the failure of platform-js, compact-js or the ledger, whichever refused.
372
+ * @see {@link ComposeRefusalOrder}
373
+ * @see {@link VerifierKeys}
374
+ */
375
+ declare class ComposeFailedError extends MidnightJsError {
376
+ readonly version: LedgerEra;
377
+ readonly stage: ComposeStage;
378
+ readonly circuitId: string;
379
+ readonly code: "MIDNIGHT_JS_P_COMPOSE_FAILED";
380
+ readonly category: MidnightJsErrorCategory;
381
+ constructor(version: LedgerEra, stage: ComposeStage, circuitId: string, cause?: unknown);
382
+ private static readonly MESSAGES;
383
+ }
384
+ /**
385
+ * Which option handed to a composition leg was unusable:
386
+ * - `'contractStateBytes'` — the state could not be bridged into the target
387
+ * ledger era (the era's decoder rejected its bytes).
388
+ * - `'guaranteedZswapOfferBytes'` — the offer bytes supplied to a deploy were
389
+ * rejected by the target era's decoder.
390
+ * - `'ledgerParametersBytes'` — the supplied ledger parameters could not be
391
+ * read by the target era.
392
+ * - `'networkId'` — the network id was empty. The ledger accepts an empty
393
+ * string and bakes it into the transaction, so a caller that forgot to
394
+ * resolve one would only find out at submission.
395
+ * - `'ttl'` — the time-to-live was not a valid instant. `new Date('...')` on
396
+ * an unparseable value yields an Invalid Date, which the ledger silently
397
+ * records as the Unix epoch: a transaction that is already expired when it
398
+ * is composed.
399
+ * - `'calls'` — the call list is not one the target era can compose. The
400
+ * retained pre-fork era composes exactly one call: a cross-contract call is a
401
+ * ledger-9-only feature that a pre-fork contract cannot emit, so that era has
402
+ * no call tree to express.
403
+ * - `'verifierKeys'` — a deploy was requested with no verifier-key map, and the
404
+ * state it was given needs one. Raised on BOTH eras, for two different
405
+ * reasons: the retained era's deploy leg has to register the compiled
406
+ * contract's keys itself and so always needs the map, while the current era
407
+ * accepts its omission for a state that already carries its keys and refuses
408
+ * it only for a state still declaring a blank-keyed entry point.
409
+ * - `'signingKey'` — a signing key is not the 32 bytes of hex the era's runtime
410
+ * reads: the key a constructor builds the maintenance authority from, or the
411
+ * key a maintenance update is signed with.
412
+ * - `'newSigningKey'` — the key a maintenance update would make the new
413
+ * authority is not the 32 bytes of hex the era's runtime reads.
414
+ * - `'zswapOffer'` — the offer bytes a call's offer factory returned were
415
+ * rejected by the target era's decoder. Raised on BOTH eras, for the same reason and with the same
416
+ * remediation: pass the bytes that era's own offer serialization produced.
417
+ *
418
+ * @see {@link ComposeRefusalOrder}
419
+ * @see {@link VerifierKeys}
420
+ */
421
+ type ComposeOption = 'calls' | 'contractStateBytes' | 'guaranteedZswapOfferBytes' | 'ledgerParametersBytes' | 'networkId' | 'newSigningKey' | 'signingKey' | 'ttl' | 'verifierKeys' | 'zswapOffer';
422
+ /**
423
+ * Thrown by the composition legs when one of their options cannot be used at
424
+ * all, as opposed to {@link ComposeFailedError}, which reports a circuit whose
425
+ * operation is missing or under-registered.
426
+ *
427
+ * These are the well-formedness checks the ledger itself does not make.
428
+ *
429
+ * Like {@link StateConversionFailedError}, this class renders no input contents of
430
+ * its own.
431
+ *
432
+ * @param version The ledger era the option was being used against.
433
+ * @param option Which option was unusable — see {@link ComposeOption}. A
434
+ * closed union, so a consumer can `switch` on it exhaustively.
435
+ * @param cause The decoder's own failure, present where caller-supplied bytes
436
+ * were rejected.
437
+ * @see {@link ComposeRefusalOrder}
438
+ * @see {@link VerifierKeys}
439
+ */
440
+ declare class ComposeOptionError extends MidnightJsError {
441
+ readonly version: LedgerEra;
442
+ readonly option: ComposeOption;
443
+ readonly code: "MIDNIGHT_JS_P_COMPOSE_OPTION_INVALID";
444
+ readonly category: MidnightJsErrorCategory;
445
+ constructor(version: LedgerEra, option: ComposeOption, cause?: unknown);
446
+ private static readonly MESSAGES;
447
+ }
448
+ /**
449
+ * Why a maintenance update cannot be signed by the key held for a contract:
450
+ * - `'not-first-member'` — the key's verifying key is not the first member of
451
+ * the contract's maintenance authority committee, the member every update is
452
+ * signed for.
453
+ * - `'empty-committee'` — the authority has no committee, so no key can sign
454
+ * for it.
455
+ * - `'threshold-above-one'` — the authority needs more signatures than the one
456
+ * every update carries.
457
+ */
458
+ type MaintenanceAuthorityMismatchReason = 'not-first-member' | 'empty-committee' | 'threshold-above-one';
459
+ /**
460
+ * Thrown when a maintenance update cannot be signed so that the ledger accepts
461
+ * it with the key held for the contract — see
462
+ * {@link MaintenanceAuthorityMismatchReason} for the three ways.
463
+ *
464
+ * Raised BEFORE anything is signed or proven: the ledger would accept the
465
+ * signature into the transaction and refuse the update only at submission,
466
+ * after a proof has been paid for.
467
+ *
468
+ * Renders the contract address and no key material: neither the signing key
469
+ * nor any verifying key appears in the message.
470
+ *
471
+ * @param version The ledger era the update was being composed on.
472
+ * @param contractAddress The contract whose authority was checked.
473
+ * @param reason Which check refused it.
474
+ * @see {@link RetainedEraExecution}
475
+ */
476
+ declare class MaintenanceAuthorityMismatchError extends MidnightJsError {
477
+ readonly version: LedgerEra;
478
+ readonly contractAddress: string;
479
+ readonly reason: MaintenanceAuthorityMismatchReason;
480
+ readonly code: "MIDNIGHT_JS_P_MAINTENANCE_AUTHORITY_MISMATCH";
481
+ readonly category: MidnightJsErrorCategory;
482
+ constructor(version: LedgerEra, contractAddress: string, reason: MaintenanceAuthorityMismatchReason);
483
+ }
484
+ /**
485
+ * Thrown when a raw, serialized contract state could not be read by
486
+ * the ledger era it was requested for. Raised by both of the facade's read
487
+ * paths, `extractState` and `decodeContractState`
488
+ * (`lib/shared/contract-state.ts`), so a caller writes one handler for both.
489
+ *
490
+ * Renders no hex and no byte dump of its own.
491
+ *
492
+ * @param version The era whose decoder rejected the bytes.
493
+ * @param cause The decoder's own diagnosis, preserved unchanged. It is what
494
+ * distinguishes a tag mismatch from truncated, trailing or empty input.
495
+ * @see {@link FailClosedDecoding}
496
+ */
497
+ declare class StateDecodeFailedError extends MidnightJsError {
498
+ readonly version: LedgerEra;
499
+ readonly code: "MIDNIGHT_JS_P_STATE_DECODE_FAILED";
500
+ readonly category: MidnightJsErrorCategory;
501
+ constructor(version: LedgerEra, cause: unknown);
502
+ }
503
+ /**
504
+ * Thrown by `decodeContractState` (`lib/shared/contract-state.ts`) when the
505
+ * era's decoder read the bytes but the state it produced is internally
506
+ * inconsistent: it declares an entry point it resolves no operation for, holds
507
+ * a verifier key that will not hash, or resolves no usable balance.
508
+ *
509
+ * Distinct from {@link StateDecodeFailedError}: the bytes were readable by the
510
+ * requested era, so decoding them as the other era cannot help. A caller that
511
+ * retries on `STATE_DECODE_FAILED` must not retry on this one.
512
+ *
513
+ * Renders no hex and no decoded state contents of its own.
514
+ *
515
+ * @param version The era whose decoder produced the state.
516
+ * @param cause The diagnosis of what was inconsistent, preserved unchanged.
517
+ * @see {@link FailClosedDecoding}
518
+ */
519
+ declare class StateInconsistentError extends MidnightJsError {
520
+ readonly version: LedgerEra;
521
+ readonly code: "MIDNIGHT_JS_P_STATE_INCONSISTENT";
522
+ readonly category: MidnightJsErrorCategory;
523
+ constructor(version: LedgerEra, cause: unknown);
524
+ }
525
+ /**
526
+ * Thrown by `extractEncodedStateValue` (`lib/era/envelope.ts`) when the
527
+ * injected pre-fork runtime cannot be used — it was not passed at all, or the
528
+ * binding the decoder needs is absent from it.
529
+ *
530
+ * `downConvertForExecution` and the shared-instance guard used to raise it too;
531
+ * both are gone with the hand-maintained execution layer, so the contract-state
532
+ * decoder is now its only source.
533
+ *
534
+ * Nothing is wrong with the caller's input here. Distinct from
535
+ * {@link Ledger8RuntimeMissingError}, which reports the v8 chunk failing to
536
+ * load at all, and from {@link StateConversionFailedError}, which reports a
537
+ * serialized state that could not be turned into an executable pre-fork
538
+ * state.
539
+ *
540
+ * @param missingMember Which binding was absent. One of this module's own
541
+ * literals, never caller-supplied text, so it is safe to log.
542
+ * @see {@link FailClosedDecoding}
543
+ * @see {@link DualInstantiationGuard}
544
+ */
545
+ declare class Ledger8RuntimeInvalidError extends MidnightJsError {
546
+ readonly missingMember: string;
547
+ readonly code: "MIDNIGHT_JS_P_LEDGER8_RUNTIME_INVALID";
548
+ readonly category: MidnightJsErrorCategory;
549
+ constructor(missingMember: string);
550
+ }
551
+ /**
552
+ * Thrown when a ledger era was requested by a value that is not a member of
553
+ * `LEDGER_ERAS`. Raised by `loadLedgerEra` (`lib/era/load-era.ts`) and by
554
+ * `extractEncodedStateValue` (`lib/era/envelope.ts`).
555
+ *
556
+ * Two sources: an untyped JavaScript caller passing a value that is not a
557
+ * `LedgerEra`, and a provider returning a value with no era or an unknown
558
+ * one. The second is named by `context`.
559
+ *
560
+ * Carries no `version` field, unlike every other era-aware error here — there
561
+ * is no valid era to name.
562
+ *
563
+ * @param requestedVersion The offending value. Kept as `undefined` when the
564
+ * value carried no era, as the kind (`'object'`, `'function'`) for a value
565
+ * that is not a scalar, and as its string form otherwise. Carried for
566
+ * programmatic use only; it is deliberately kept out of the message.
567
+ * @param context The call that read the era off a value it was handed,
568
+ * for example the provider method that returned a record. Named in the
569
+ * message, so a caller can tell which provider produced the value.
570
+ * @see {@link SharedTableDiscipline}
571
+ * @see {@link FailClosedDecoding}
572
+ */
573
+ declare class UnknownLedgerEraError extends MidnightJsError {
574
+ readonly context?: string | undefined;
575
+ readonly code: "MIDNIGHT_JS_P_UNKNOWN_LEDGER_ERA";
576
+ readonly category: MidnightJsErrorCategory;
577
+ readonly requestedVersion: string | undefined;
578
+ constructor(requestedVersion: unknown, context?: string | undefined);
579
+ }
580
+ /**
581
+ * The opening of the tag every serialized ledger transaction carries, on both
582
+ * eras.
583
+ *
584
+ * Stops before the bracketed version deliberately: a `[vN]` is the wire-schema
585
+ * version of the serialized OBJECT and never a ledger era — the retained era's
586
+ * transactions are tagged `transaction[v9]`.
587
+ *
588
+ * @see packages/contracts/docs/verification-path.md for the same rule stated
589
+ * about verifier-key tags.
590
+ */
591
+ declare const TRANSACTION_TAG_PREFIX = "midnight:transaction[";
592
+ /**
593
+ * Thrown when a payload handed to `deserializeTransactionAtStage` is not a
594
+ * serialized transaction of the requested era and stage.
595
+ *
596
+ * It covers four ways that can happen: a value that is not a byte string, a
597
+ * byte string shorter than the tag prefix, one that does not open with the
598
+ * prefix, and one the era's runtime refuses to read at the requested stage.
599
+ * The first three are refused before any runtime reads the bytes. The last
600
+ * carries the runtime's refusal on `cause`.
601
+ *
602
+ * @remarks Match it with `hasErrorCode` against
603
+ * `PROTOCOL_ERROR_CODES.PAYLOAD_NOT_A_TRANSACTION` rather than constructing it.
604
+ */
605
+ declare class PayloadNotATransactionError extends MidnightJsError {
606
+ readonly code: "MIDNIGHT_JS_P_PAYLOAD_NOT_A_TRANSACTION";
607
+ readonly category: MidnightJsErrorCategory;
608
+ private constructor();
609
+ /**
610
+ * The payload was not a `Uint8Array`. Reachable from JavaScript or across an
611
+ * untyped boundary, so it is refused with a code rather than left to become
612
+ * a bare `TypeError`.
613
+ */
614
+ static notBytes(received: unknown): PayloadNotATransactionError;
615
+ /** The payload is a byte string, but does not open with a transaction's tag. */
616
+ static wrongTag(byteLength: number): PayloadNotATransactionError;
617
+ /** The era's runtime refused to read the payload at the requested stage; its refusal is on `cause`. */
618
+ static undecodable(version: LedgerEra, stage: TransactionStage, byteLength: number, cause: unknown): PayloadNotATransactionError;
619
+ }
620
+ /** A midnight-js error recognised by its fields, which also matches one built by another installed copy. */
621
+ type CodedMidnightJsError = Error & {
622
+ readonly code: MidnightJsErrorCodeFormat;
623
+ readonly category: MidnightJsErrorCategory;
624
+ };
625
+ /**
626
+ * The midnight-js error a failure is or carries: the failure itself when it is one, otherwise the first
627
+ * one on its `cause` chain, at most eight links down. Use it when a dependency wraps a midnight-js error
628
+ * and hides its `code` and `category`.
629
+ */
630
+ declare const findCodedCause: (failure: unknown) => CodedMidnightJsError | undefined;
631
+ /**
632
+ * What a retained-era circuit or constructor execution fails with. A Compact `assert` refusal is the usual
633
+ * cause, but a key or config read failure or a runtime fault can also arrive this way, so `cause` is the
634
+ * source of truth. A failure that is, or carries on its `cause` chain, a midnight-js coded error is not
635
+ * wrapped in this class: that coded error surfaces directly.
636
+ */
637
+ declare class ContractExecutionError extends MidnightJsError {
638
+ readonly code: "MIDNIGHT_JS_P_CONTRACT_EXECUTION_FAILED";
639
+ readonly category: MidnightJsErrorCategory;
640
+ /**
641
+ * Every failure the execution reported, as the original objects, in the order they arrived. Filled by
642
+ * {@link ContractExecutionError.fromFailures}; empty when the error was built without a list.
643
+ */
644
+ readonly errors: readonly unknown[];
645
+ constructor(message: string, options?: ErrorOptions & {
646
+ readonly errors?: readonly unknown[];
647
+ });
648
+ /**
649
+ * Reports every failure of an execution, each with its whole cause chain, separated by `; `.
650
+ * `cause` is the first coded error found on any failure's chain, or the first failure when none is coded.
651
+ * `errors` holds every failure as the original object, so no stack is lost.
652
+ */
653
+ static fromFailures(failures: readonly unknown[]): ContractExecutionError;
654
+ }
655
+
656
+ /**
657
+ * The query-context state a call recorded while it ran, which its pre-call
658
+ * state bytes do not carry.
659
+ *
660
+ * `block` and `effects` are the PRE-call values; `comIndices` is the POST-call
661
+ * map. Plain data on every member.
662
+ *
663
+ * @see {@link ComposeRefusalOrder} for why partitioning needs the context the
664
+ * circuit actually ran on, and why `CallContext` and `Effects` are declared
665
+ * once against ledger-v9.
666
+ * @see {@link RetainedEraExecution} for why each member is read off the
667
+ * context it is.
668
+ * @see {@link EraBoundary}
669
+ */
670
+ interface PartitionContext {
671
+ readonly block: CallContext;
672
+ readonly effects: Effects;
673
+ /** Commitment -> the index the runtime recorded it at. Empty for a call that received no coin. */
674
+ readonly comIndices: ReadonlyMap<CoinCommitment, bigint>;
675
+ }
676
+ /**
677
+ * Where a call's public transcript comes from. Two shapes, because neither
678
+ * production leg subsumes the other:
679
+ *
680
+ * - `'unpartitioned'` — the raw op sequence a circuit emitted on the retained
681
+ * pre-fork execution leg, the state it ran against, and the
682
+ * {@link PartitionContext} that leg recorded.
683
+ * - `'partitioned'` — a guaranteed/fallible pair already split by compact-js,
684
+ * which is the current production path.
685
+ *
686
+ * Every member is plain data in the ledger's own declared algebra — no live
687
+ * WASM handle.
688
+ *
689
+ * @see {@link RetainedEraExecution} for the leg that submits the unpartitioned
690
+ * shape.
691
+ * @see {@link ComposeRefusalOrder} for why an already-partitioned pair is
692
+ * passed through rather than re-derived.
693
+ * @see {@link EraBoundary}
694
+ */
695
+ type CallTranscriptSource = {
696
+ readonly kind: 'unpartitioned';
697
+ readonly preState: EncodedStateValue;
698
+ readonly publicTranscript: Op<AlignedValue>[];
699
+ readonly partitionContext: PartitionContext;
700
+ } | {
701
+ readonly kind: 'partitioned';
702
+ readonly guaranteed?: Transcript<AlignedValue>;
703
+ readonly fallible?: Transcript<AlignedValue>;
704
+ };
705
+ /**
706
+ * The sentinel that asks for the ledger's own INITIAL cost model instead of the chain's.
707
+ *
708
+ * Spelled out as a value a caller has to name, because the thing it selects is wrong for any chain
709
+ * that has been running: the initial parameters are the model the chain started with, and prices
710
+ * adjust per block. Partitioning against them draws the guaranteed/fallible boundary in the wrong
711
+ * place and the node then refuses the guaranteed segment with `Transcript(Execution(OutOfGas))` --
712
+ * after the caller has already paid to prove it.
713
+ */
714
+ declare const INITIAL_LEDGER_PARAMETERS = "initial";
715
+ /**
716
+ * What a composer accepts for the block's ledger parameters: the chain's own serialized parameters,
717
+ * or {@link INITIAL_LEDGER_PARAMETERS}.
718
+ *
719
+ * There is deliberately no third option. This used to be optional, and omitting it fell back to the
720
+ * initial parameters silently -- so a caller that simply forgot got the wrong cost model with no
721
+ * signal, and a `PublicDataProvider` that does not serve `ledgerParameters` (the field is optional)
722
+ * degraded every call built through it. Requiring the option keeps the compatibility path reachable
723
+ * only as a decision, never as an oversight.
724
+ *
725
+ * A caller that reads the chain must pass the bytes from the SAME read as the contract state: the
726
+ * parameters are era-tagged and dated per block, so a second read could answer for another block.
727
+ *
728
+ * @see {@link EraBoundary}
729
+ */
730
+ type LedgerParametersOption = Uint8Array | typeof INITIAL_LEDGER_PARAMETERS;
731
+ /**
732
+ * A call's guaranteed/fallible transcript pair, as the ledger's partitioner
733
+ * answers it. Either member is absent when that segment carries nothing.
734
+ */
735
+ type PartitionedCallTranscript = [
736
+ Transcript<AlignedValue> | undefined,
737
+ Transcript<AlignedValue> | undefined
738
+ ];
739
+ /**
740
+ * Builds the transaction's Zswap offers once the composer holds every call's
741
+ * partition, in `calls` order. Returns serialized offer bytes per segment; an
742
+ * absent member is the normal shape of a segment that moves no shielded coin.
743
+ *
744
+ * A function rather than ready-made bytes: there is deliberately no way to
745
+ * supply an offer without being handed the partition it must be routed against.
746
+ *
747
+ * @see {@link ComposeRefusalOrder} for why the boundary is not known until the
748
+ * composer has split the transcripts.
749
+ */
750
+ type ZswapOfferFactory = (partitions: readonly PartitionedCallTranscript[]) => {
751
+ readonly guaranteedBytes?: Uint8Array;
752
+ readonly fallibleBytes?: Uint8Array;
753
+ };
754
+ /**
755
+ * One contract call in a call transaction.
756
+ *
757
+ * `contractStateBytes` is the raw, serialized state the call is dispatched against,
758
+ * as read from chain. It supplies the registered operation for `circuitId`,
759
+ * including its verifier key, which the call's key location hashes; a
760
+ * constructor-built state will not do, because it declares its entry points
761
+ * with blank keys.
762
+ *
763
+ * `communicationCommitmentRandomness` is the randomness the runtime bound a
764
+ * cross-contract callee to its caller with. The root call — being no one's
765
+ * callee — omits it and gets fresh randomness.
766
+ *
767
+ * @see {@link EraBoundary}
768
+ */
769
+ interface ComposeCallEntry {
770
+ readonly contractAddress: string;
771
+ readonly circuitId: string;
772
+ readonly contractStateBytes: Uint8Array;
773
+ /**
774
+ * The ledger parameters the chain held at the block this call is built against, serialized —
775
+ * `ContractStateAndParametersRead.ledgerParameters`, serialized and passed through untouched — or
776
+ * {@link INITIAL_LEDGER_PARAMETERS} to partition against the ledger's initial cost model instead.
777
+ *
778
+ * Required, and deliberately so. See {@link LedgerParametersOption}.
779
+ */
780
+ readonly ledgerParametersBytes: LedgerParametersOption;
781
+ readonly transcript: CallTranscriptSource;
782
+ readonly privateTranscriptOutputs: AlignedValue[];
783
+ readonly input: AlignedValue;
784
+ readonly output: AlignedValue;
785
+ readonly communicationCommitmentRandomness?: string;
786
+ }
787
+ /**
788
+ * Everything a call transaction needs.
789
+ *
790
+ * `calls` is in execution-trace order: cross-contract callees first, the root
791
+ * call last. A circuit with no cross-contract calls has a single entry.
792
+ *
793
+ * `zswapOffer` is called back once every call has been assembled, with the
794
+ * partitions to route against; omitting it composes a transaction with no
795
+ * shielded offer. `networkId` and `ttl` carry the caller's policy decisions —
796
+ * which network, how long the transaction lives.
797
+ *
798
+ * @see {@link ZswapOfferFactory}
799
+ * @see {@link ComposeRefusalOrder} for when the envelope options are checked.
800
+ * @see {@link EraBoundary}
801
+ */
802
+ interface ComposeCallOptions {
803
+ readonly calls: readonly ComposeCallEntry[];
804
+ readonly networkId: string;
805
+ readonly ttl: Date;
806
+ readonly zswapOffer?: ZswapOfferFactory;
807
+ }
808
+ /**
809
+ * What a composed call transaction answers with: the serialized UNPROVEN
810
+ * transaction, and the partition each call was split into, in `calls` order.
811
+ *
812
+ * The partitions are returned rather than left inside the composer because a
813
+ * caller that has to report what a call recorded per segment would otherwise
814
+ * have to split the same transcript a second time, and nothing would notice if
815
+ * the two answers stopped agreeing.
816
+ *
817
+ * @see {@link EraBoundary}
818
+ */
819
+ interface ComposeCallResultPojo {
820
+ readonly txBytes: Uint8Array;
821
+ readonly partitions: readonly PartitionedCallTranscript[];
822
+ }
823
+ /**
824
+ * Everything a deploy transaction needs.
825
+ *
826
+ * `contractStateBytes` is the raw, serialized initial state the contract's
827
+ * constructor produced.
828
+ *
829
+ * `verifierKeys` maps entry-point name -> raw, tagged verifier key bytes
830
+ * (`keys/<id>.verifier`). When supplied, the map must name exactly the entry
831
+ * points the state declares — no more, no fewer. Omit it only for a state that
832
+ * ALREADY carries its keys.
833
+ *
834
+ * @see {@link VerifierKeys}
835
+ * @see {@link EraBoundary}
836
+ */
837
+ interface ComposeDeployOptions {
838
+ readonly contractStateBytes: Uint8Array;
839
+ readonly verifierKeys?: ReadonlyMap<string, Uint8Array>;
840
+ readonly networkId: string;
841
+ readonly ttl: Date;
842
+ readonly guaranteedZswapOfferBytes?: Uint8Array;
843
+ }
844
+ /**
845
+ * What a composed deploy hands back.
846
+ *
847
+ * `contractAddress` cannot be recomputed from the state a caller passed in, so
848
+ * it is handed back here rather than derived. `initialContractStateBytes` is the state that
849
+ * address was derived from — what a caller stores and later hands to a call.
850
+ *
851
+ * All three are plain data.
852
+ *
853
+ * @see {@link VerifierKeys} for why the address cannot be recomputed.
854
+ * @see {@link EraBoundary}
855
+ */
856
+ interface DeployResultPojo {
857
+ readonly txBytes: Uint8Array;
858
+ readonly contractAddress: string;
859
+ readonly initialContractStateBytes: Uint8Array;
860
+ }
861
+
862
+ /**
863
+ * The public balances a contract holds, keyed by token type.
864
+ *
865
+ * Derived from the vendor's own `TokenType` rather than restated, so a rename
866
+ * fails this build instead of leaving a mirror describing a shape neither
867
+ * runtime has.
868
+ *
869
+ * `shared-contract-state.test.ts` pins all three `TokenType` declarations —
870
+ * both eras' and the execution runtime's, which is where the map actually
871
+ * lands — mutually assignable. That pin is STRUCTURAL and can be no more:
872
+ * `raw` is an opaque `string` everywhere, so assignability says the handoff
873
+ * type-checks and says nothing about two eras reading a given key as the same
874
+ * colour.
875
+ *
876
+ * Plain data end to end — string-tagged objects and `bigint`s — so it crosses
877
+ * an era boundary like every other member of {@link ContractStatePojo}. That is
878
+ * a statement about `structuredClone`, which carries a `Map`; a JSON round trip
879
+ * does NOT, and leaves the plain object the balance guards refuse.
880
+ */
881
+ type ContractBalance = ReadonlyMap<TokenType, bigint>;
882
+ /**
883
+ * One entry point a contract state declares, with the verifier key registered
884
+ * against it if there is one.
885
+ *
886
+ * `verifierKey` and `verifierKeyHash` are both absent for a blank slot — the
887
+ * shape a constructor-built state has before a deploy fills it in.
888
+ *
889
+ * @see {@link FailClosedDecoding} for why they are absent rather than
890
+ * zero-length or a hash of nothing.
891
+ */
892
+ interface ContractEntryPointPojo {
893
+ readonly circuitId: string;
894
+ readonly verifierKey: Uint8Array | undefined;
895
+ readonly verifierKeyHash: string | undefined;
896
+ }
897
+ /**
898
+ * A contract state as plain data: the primary state in its encoded form, the
899
+ * balances the contract holds, and the entry points the state declares.
900
+ *
901
+ * `entryPoints` is an ARRAY, not a map keyed by circuit id: two distinct byte
902
+ * entry points can decode to the same name, and a caller has to reconcile
903
+ * them.
904
+ *
905
+ * @see {@link FailClosedDecoding}
906
+ */
907
+ interface ContractStatePojo {
908
+ readonly state: EncodedStateValue;
909
+ /**
910
+ * The balances the contract holds, which are NOT part of the primary state:
911
+ * the ledger keeps them beside it, so a caller reading only `state` cannot
912
+ * reach them. A retained-era call that executes without them runs every
913
+ * circuit against an empty balance — see {@link RetainedEraExecution}.
914
+ */
915
+ readonly balance: ContractBalance;
916
+ readonly entryPoints: readonly ContractEntryPointPojo[];
917
+ }
918
+
919
+ /**
920
+ * The facade of one ledger era: an object bound to that one era, obtained
921
+ * from `loadLedgerEra`. It hides the era's ledger package (WASM,
922
+ * `ContractState`, `Transaction`, serialization) behind methods that take
923
+ * and return plain data only. There is one facade per era.
924
+ *
925
+ * Both eras expose the SAME methods with the same signatures. Which era an
926
+ * object is bound to is readable from {@link LedgerEraFacade.version} and nowhere
927
+ * else — a caller that has resolved the era for a record (see
928
+ * `protocolVersionToLedger` in `../../version.ts`) hands that value to
929
+ * `loadLedgerEra` once and then writes era-agnostic code.
930
+ *
931
+ * Every value crossing this boundary is plain data: `Uint8Array`s and plain
932
+ * objects, never a live WASM handle, so a result outlives the module that
933
+ * produced it and survives a `structuredClone` or a worker boundary.
934
+ *
935
+ * The methods are synchronous. Asking for an era is the point at which its
936
+ * runtime is acquired, so by the time a caller holds one of these there is
937
+ * nothing left to await.
938
+ *
939
+ * @see {@link EraBoundary}
940
+ */
941
+ interface LedgerEraFacade {
942
+ /** The era this object is bound to — the value that was passed to `loadLedgerEra`. */
943
+ readonly version: LedgerEra;
944
+ /**
945
+ * Reads the primary state out of a raw, serialized contract-state envelope
946
+ * written by this era.
947
+ *
948
+ * Fails closed on an envelope this era cannot read — including one written
949
+ * by the other era — rather than returning a partial or empty state. The
950
+ * failure is a `StateDecodeFailedError` naming this era, the same class
951
+ * {@link LedgerEraFacade.decodeContractState} raises, with the decoder's own
952
+ * diagnosis on `cause`.
953
+ *
954
+ * @param raw The serialized contract-state envelope.
955
+ * @returns The primary state read out of the envelope.
956
+ * @throws StateDecodeFailedError if this era's decoder rejects `raw`.
957
+ * @see {@link FailClosedDecoding}
958
+ */
959
+ extractState(raw: Uint8Array): EncodedStateValue;
960
+ /**
961
+ * Reads a raw, serialized contract-state envelope written by this era into
962
+ * plain data: its primary state, and the entry points it declares with the
963
+ * verifier key registered against each.
964
+ *
965
+ * @param raw The serialized contract-state envelope.
966
+ * @returns The decoded state. A `verifierKey` absent on an entry point means
967
+ * that slot was never deployed, not that the key is empty.
968
+ * @throws StateDecodeFailedError if this era's decoder rejects `raw`.
969
+ * @throws StateInconsistentError if the decoded state is internally
970
+ * inconsistent — an entry point it cannot resolve, a verifier key that will
971
+ * not hash, or no usable balance.
972
+ * @see {@link FailClosedDecoding}
973
+ */
974
+ decodeContractState(raw: Uint8Array): ContractStatePojo;
975
+ /**
976
+ * Composes an UNPROVEN call transaction and serializes it.
977
+ *
978
+ * The returned bytes are what `Transaction.serialize()` produces before
979
+ * `.prove()` is ever called; proving needs a proving provider and a running
980
+ * proof server, neither of which this method has.
981
+ *
982
+ * The retained pre-fork era composes exactly ONE call and refuses a longer
983
+ * list. A Zswap offer is NOT refused on either era.
984
+ *
985
+ * A call's Zswap offer is supplied as a FACTORY rather than as ready-made
986
+ * bytes. It is handed the transcript split this method resolves, and the same
987
+ * split comes back on the result.
988
+ *
989
+ * @param options The calls to compose and the transaction-wide envelope.
990
+ * @returns The serialized UNPROVEN transaction and each call's partition.
991
+ * @throws ComposeOptionError if an option is unusable on this era — an
992
+ * empty `networkId`, an invalid `ttl`, undecodable offer or state bytes, or
993
+ * a call tree with more than one entry on the retained pre-fork era.
994
+ * @throws ComposeFailedError if a call cannot be assembled; `stage` names
995
+ * which step refused it.
996
+ * @see {@link ComposeRefusalOrder}
997
+ * @see {@link EraBoundary}
998
+ */
999
+ composeCallTx(options: ComposeCallOptions): ComposeCallResultPojo;
1000
+ /**
1001
+ * Composes an UNPROVEN deploy transaction and returns it together with the
1002
+ * address the deployment will have and the initial state that address was
1003
+ * derived from.
1004
+ *
1005
+ * The address cannot be recomputed from the state a caller passed in — a
1006
+ * deploy mints a fresh nonce — which is why it is returned rather than left
1007
+ * to the caller to derive.
1008
+ *
1009
+ * @param options The initial state, its verifier keys, and the
1010
+ * transaction-wide envelope.
1011
+ * @returns The serialized UNPROVEN transaction, the address the deployment
1012
+ * will have, and the initial state that address was derived from.
1013
+ * @throws ComposeOptionError if an option is unusable on this era — an
1014
+ * empty `networkId`, an invalid `ttl`, undecodable state bytes, or an
1015
+ * omitted `verifierKeys` for a state that still declares a blank key.
1016
+ * @throws ComposeFailedError if the supplied keys do not match the state's
1017
+ * declared entry points, or if the ledger rejects a key blob; `stage` names
1018
+ * which check refused it.
1019
+ * @see {@link VerifierKeys}
1020
+ * @see {@link ComposeRefusalOrder}
1021
+ */
1022
+ composeDeployTx(options: ComposeDeployOptions): DeployResultPojo;
1023
+ }
1024
+
1025
+ /**
1026
+ * Resolves one ledger era to a {@link LedgerEraFacade} bound to it.
1027
+ *
1028
+ * This is the only sanctioned way to reach either era's operations. Pass the
1029
+ * version resolved from a record or from the network's latest block (see
1030
+ * `protocolVersionToLedger` in `../../version.ts`) rather than a string chosen
1031
+ * by hand.
1032
+ *
1033
+ * Memoised per era, so the retained pre-fork WASM is instantiated at most once
1034
+ * per process. A FAILED v8 acquisition is not memoised: the next call retries.
1035
+ *
1036
+ * @param version The era to resolve.
1037
+ * @returns The era facade bound to `version`. The same object on every call
1038
+ * for that era, and frozen.
1039
+ * @throws UnknownLedgerEraError — as a rejection — if `version` is not a
1040
+ * member of `LEDGER_ERAS`.
1041
+ * @throws Ledger8RuntimeMissingError — as a rejection — if the retained
1042
+ * pre-fork runtime cannot be acquired. It propagates unchanged, carrying the
1043
+ * underlying cause.
1044
+ * @see {@link EraBoundary}
1045
+ * @see {@link SharedTableDiscipline}
1046
+ */
1047
+ declare const loadLedgerEra: (version: LedgerEra) => Promise<LedgerEraFacade>;
1048
+
1049
+ type Ledger8Protocol = typeof V8;
1050
+ /**
1051
+ * The only sanctioned runtime path to the v8 ledger era.
1052
+ *
1053
+ * The v8 WASM loads on the first call and not before.
1054
+ *
1055
+ * A failed load is not memoised: the rejection propagates as
1056
+ * {@link Ledger8RuntimeMissingError} and the next call retries the import.
1057
+ *
1058
+ * @returns The v8 ledger module, memoised after the first successful load.
1059
+ * @throws Ledger8RuntimeMissingError If the `./v8` chunk cannot be imported.
1060
+ * The returned promise rejects with it, carrying the underlying failure on
1061
+ * `cause`.
1062
+ * @see {@link ModuleGraphAndLazyLoading}
1063
+ * @see {@link EraBoundary}
1064
+ */
1065
+ declare const loadLedger8Protocol: () => Promise<Ledger8Protocol>;
1066
+
1067
+ declare const LEDGER_STATE_KINDS: readonly ["ContractState", "LedgerParameters", "ZswapChainState"];
1068
+ /**
1069
+ * A kind of value the ledger writes and the indexer serves as bytes.
1070
+ */
1071
+ type StateKind = (typeof LEDGER_STATE_KINDS)[number];
1072
+ declare const LEDGER_STATE_TAGS: Readonly<{
1073
+ readonly ContractState: Readonly<{
1074
+ v8: "midnight:contract-state[v6]";
1075
+ v9: "midnight:contract-state[v8]";
1076
+ }>;
1077
+ readonly LedgerParameters: Readonly<{
1078
+ v8: "midnight:ledger-parameters[v5]";
1079
+ v9: "midnight:ledger-parameters[v8]";
1080
+ }>;
1081
+ readonly ZswapChainState: Readonly<{
1082
+ v8: "midnight:zswap-ledger-state[v5]";
1083
+ v9: "midnight:zswap-ledger-state[v5]";
1084
+ }>;
1085
+ }>;
1086
+
1087
+ /**
1088
+ * Anything that can report the network's latest protocol version —
1089
+ * typically an indexer or node client. Consumed by {@link latestNetworkLedgerVersion}.
1090
+ */
1091
+ interface ProtocolVersionSource {
1092
+ /**
1093
+ * @returns The network's latest `protocolVersion` integer.
1094
+ */
1095
+ queryLatestProtocolVersion(): Promise<number>;
1096
+ }
1097
+ /**
1098
+ * Any record carrying a raw `protocolVersion` integer field, e.g. a
1099
+ * transaction or block already read from the indexer. Consumed by
1100
+ * {@link versionOfRecord}.
1101
+ */
1102
+ interface VersionedRecord {
1103
+ readonly protocolVersion: number;
1104
+ }
1105
+ /**
1106
+ * Maps a raw `protocolVersion` integer (as returned by the indexer or node)
1107
+ * onto the ledger runtime it corresponds to.
1108
+ *
1109
+ * | protocolVersion range | node version | ledger |
1110
+ * | --------------------- | ------------ | ------ |
1111
+ * | 1_000_000 – 1_999_999 | 1.x | v8 |
1112
+ * | 2_000_000 – 2_999_999 | 2.x | v9 |
1113
+ *
1114
+ * Most call sites should not call this directly. Prefer
1115
+ * {@link versionOfRecord} for a `protocolVersion` read off an existing
1116
+ * indexer/node record, or {@link latestNetworkLedgerVersion} for the network's
1117
+ * latest ledger era — both tag the resulting error with the correct
1118
+ * `path` automatically. Pass `path` explicitly here only when neither helper
1119
+ * fits the call site.
1120
+ *
1121
+ * @param protocolVersion The raw integer read from an indexer or node record.
1122
+ * @param path Which resolution path a failure is attributed to. Defaults to
1123
+ * `'construct'`, and decides which of the two error codes a failure carries.
1124
+ * @returns The {@link LedgerEra} that `protocolVersion`'s node major maps
1125
+ * onto.
1126
+ * @throws {@link UnknownProtocolVersionError} with `reason: 'malformed'` when
1127
+ * `protocolVersion` is not a non-negative integer, and with `reason: 'unknown'`
1128
+ * when it is a well-formed integer outside every range above.
1129
+ * @see {@link SharedTableDiscipline}
1130
+ */
1131
+ declare const protocolVersionToLedger: (protocolVersion: number, path?: VersionResolutionPath) => LedgerEra;
1132
+ /**
1133
+ * Resolves the ledger era for a record's `protocolVersion` field (e.g. a
1134
+ * transaction or block already read from the indexer).
1135
+ *
1136
+ * @param record Any object carrying a raw `protocolVersion` integer field.
1137
+ * @returns The {@link LedgerEra} that record was written under.
1138
+ * @throws {@link UnknownProtocolVersionError} tagged with the `read` path, on
1139
+ * the same two conditions as {@link protocolVersionToLedger}.
1140
+ */
1141
+ declare const versionOfRecord: (record: VersionedRecord) => LedgerEra;
1142
+ /**
1143
+ * Queries `source` for the network's latest protocol version and
1144
+ * resolves it to a {@link LedgerEra}.
1145
+ *
1146
+ * The source is expected to read the network on every call. This is the
1147
+ * construct path: the era being resolved is the one a transaction built now
1148
+ * will land in, and a stale reading is wrong exactly at the fork boundary,
1149
+ * where that question matters. `PublicDataProvider.queryLatestProtocolVersion`
1150
+ * states the same prohibition as a requirement on its implementations; this
1151
+ * parameter is a structural type, so nothing here can enforce it. See ADR 0007.
1152
+ *
1153
+ * @param source The indexer or node client to ask for the latest version.
1154
+ * @returns A promise for the {@link LedgerEra} of the network's latest block.
1155
+ * @throws {@link UnknownProtocolVersionError} tagged with the `construct`
1156
+ * path, on the same two conditions as {@link protocolVersionToLedger}. A
1157
+ * rejection from `source.queryLatestProtocolVersion()` propagates unchanged.
1158
+ */
1159
+ declare const latestNetworkLedgerVersion: (source: ProtocolVersionSource) => Promise<LedgerEra>;
1160
+
1161
+ /**
1162
+ * Retained-era (ledger 8) execution, on compact-js's own era-pinned entries.
1163
+ *
1164
+ * This module replaced a hand-maintained execution layer — `execute.ts`, which
1165
+ * drove `compact-runtime@0.16` directly, and `down-convert.ts`, which built the
1166
+ * state it ran against. Both are gone; see
1167
+ * `docs/adr/0015-retained-era-execution-on-compact-js.md` for why.
1168
+ *
1169
+ * Everything crossing this module's surface is PLAIN DATA or an era-tagged
1170
+ * handle the caller already holds. No `Effect` value leaves it: the effects
1171
+ * compact-js returns are discharged here with `Effect.runPromise`, which is
1172
+ * also why every entry point is asynchronous — `ContractExecutable` builds its
1173
+ * work on `Effect.tryPromise`, so `runSync` cannot discharge it.
1174
+ *
1175
+ * @see {@link RetainedEraExecution}
1176
+ */
1177
+
1178
+ /** A retained-era signing key: 32 bytes of hex. @see {@link LEDGER8_SIGNING_KEY_PATTERN} */
1179
+ type Ledger8SigningKey = string;
1180
+ /**
1181
+ * A retained-era contract, as the caller holds it: the CONSTRUCTED artifact the
1182
+ * previous toolchain generates.
1183
+ *
1184
+ * Deliberately not compact-js's `CompiledContract` container. That container is
1185
+ * a recipe — a class plus witnesses, instantiated fresh per operation — and the
1186
+ * retained era's callers hold an instance whose witnesses are already bound.
1187
+ * {@link containerFor} adapts one to the other here, which keeps the
1188
+ * adaptation in one place instead of on every consumer.
1189
+ */
1190
+ interface Ledger8EngineContract {
1191
+ /** The map compact-js indexes to find the circuit to run. */
1192
+ readonly provableCircuits: Readonly<Record<string, unknown>>;
1193
+ /** The constructor a deployment runs. */
1194
+ initialState(...args: never[]): unknown;
1195
+ }
1196
+ /**
1197
+ * The result of one retained-era circuit call: every artifact
1198
+ * {@link wrapKeepStateCall} (`../v9/wrap.ts`) needs to assemble a v9-native
1199
+ * `ContractCallPrototype`.
1200
+ *
1201
+ * `preContractState` and `postContractState` are LIVE HANDLES from the retained
1202
+ * runtime; every other member is plain data. `postContractStateEncoded` is the
1203
+ * post-state's encoded form, carried beside the handle so a caller has a value
1204
+ * that outlives the runtime instance.
1205
+ *
1206
+ * @see {@link RetainedEraExecution}
1207
+ */
1208
+ interface TranscriptPojo {
1209
+ readonly circuitId: string;
1210
+ readonly result: unknown;
1211
+ readonly input: ContractExecutable.ContractExecutable.ContractCallPrivate['input'];
1212
+ readonly output: ContractExecutable.ContractExecutable.ContractCallPrivate['output'];
1213
+ readonly publicTranscript: ContractExecutable.ContractExecutable.ContractCallPublic['publicTranscript'];
1214
+ readonly privateTranscriptOutputs: ContractExecutable.ContractExecutable.ContractCallPrivate['privateTranscriptOutputs'];
1215
+ /**
1216
+ * The state the call BOUND to, i.e. `partitionInputs.state`.
1217
+ *
1218
+ * Indistinguishable from {@link TranscriptPojo.postContractState} BY TYPE:
1219
+ * compact-js resolves both to the same declaration, so swapping the two is
1220
+ * not a compile error. Partitioning against the wrong one rejects a state the
1221
+ * transcript's reads do not fit, or silently mis-charges one that merely
1222
+ * differs in value, so the distinction rests on the member name alone.
1223
+ */
1224
+ readonly preContractState: ContractExecutable.ContractExecutable.CallPartitionInputs['state'];
1225
+ /**
1226
+ * The state the call LEFT, i.e. compact-js's own `contractState`.
1227
+ *
1228
+ * See {@link TranscriptPojo.preContractState}: the two are the same type.
1229
+ */
1230
+ readonly postContractState: ContractExecutable.ContractExecutable.ContractCallPublic['contractState'];
1231
+ /**
1232
+ * The post-call state as an {@link EncodedStateValue}: the same value
1233
+ * {@link postContractState} holds, in the form that survives this process.
1234
+ *
1235
+ * `EncodedStateValue` is pinned identical across the retained and current
1236
+ * runtimes, so this is the member era-agnostic code reads, and the one that
1237
+ * can be persisted, cloned or sent to a worker.
1238
+ */
1239
+ readonly postContractStateEncoded: EncodedStateValue;
1240
+ readonly privateStateAfter: unknown;
1241
+ readonly partitionContext: PartitionContext;
1242
+ readonly zswapLocalState: ContractExecutable.ContractExecutable.DeployResultPrivate<unknown>['zswapLocalState'];
1243
+ }
1244
+ /** The freshly built state a retained-era constructor produced. */
1245
+ interface ConstructorResultPojo {
1246
+ readonly contractState: ContractExecutable.ContractExecutable.DeployResultPublic['contractState'];
1247
+ readonly privateState: unknown;
1248
+ readonly zswapLocalState: ContractExecutable.ContractExecutable.DeployResultPrivate<unknown>['zswapLocalState'];
1249
+ /**
1250
+ * The key the state's maintenance authority was built from: the caller's own
1251
+ * when one was named, otherwise the one compact-js sampled.
1252
+ *
1253
+ * REQUIRED, unlike the request's, and that asymmetry is the point — a sampled
1254
+ * key exists nowhere else, so a result that did not report it would leave the
1255
+ * deployment as unmaintainable as the empty committee the retained
1256
+ * constructor writes on its own.
1257
+ */
1258
+ readonly signingKey: Ledger8SigningKey;
1259
+ }
1260
+ /**
1261
+ * Reads verifier keys for the entry points a contract declares.
1262
+ *
1263
+ * A plain function rather than compact-js's `ZKConfiguration` service, so no
1264
+ * Effect type reaches this package's callers; {@link zkConfigurationLayer}
1265
+ * adapts it where the service is needed.
1266
+ */
1267
+ type VerifierKeyReader = (provableCircuitId: string) => Promise<Uint8Array | undefined>;
1268
+ /** Everything {@link runLedger8Circuit} needs to run one circuit. */
1269
+ interface Ledger8CircuitOptions<C extends Ledger8EngineContract, PS> {
1270
+ readonly contract: C;
1271
+ readonly circuitId: string;
1272
+ readonly args: readonly unknown[];
1273
+ /**
1274
+ * The contract state the call runs against, DECODED — the primary state in
1275
+ * its era-neutral encoded form, with the balances the contract holds beside
1276
+ * it.
1277
+ *
1278
+ * Era-neutral rather than one era's serialized bytes, because a contract that
1279
+ * an earlier post-fork call has already migrated carries a CURRENT-era
1280
+ * envelope while still executing on the retained runtime. Chain bytes would
1281
+ * have to be decoded by the era that wrote them; this shape is what both
1282
+ * envelopes' readers produce, so one path serves a pre-fork contract and a
1283
+ * migrated one alike.
1284
+ *
1285
+ * The balance travels on the same value, so the two halves cannot come off
1286
+ * different reads. {@link executableStateFrom} writes it onto a whole
1287
+ * `ContractState`, which is the only form the retained runtime reads a
1288
+ * balance from — handed a bare state value it substitutes an empty map, and a
1289
+ * circuit reading a balance then executes against nothing with every guard
1290
+ * green. That substitution is what #1345 was.
1291
+ */
1292
+ readonly contractState: ContractStatePojo;
1293
+ readonly address: string;
1294
+ readonly coinPk: string;
1295
+ readonly privateState: PS;
1296
+ /**
1297
+ * The execution clock, in SECONDS since the epoch. Omitted, the wall clock is
1298
+ * used.
1299
+ *
1300
+ * Lands on the query context's `block.secondsSinceEpoch`, which
1301
+ * {@link TranscriptPojo.partitionContext} reports — so without pinning it a
1302
+ * recorded fixture differs on every run
1303
+ * (midnightntwrk/midnight-sdk#403).
1304
+ */
1305
+ readonly nowSeconds?: number;
1306
+ }
1307
+ /** Everything {@link runLedger8Constructor} needs to run one constructor. */
1308
+ interface Ledger8ConstructorOptions<C extends Ledger8EngineContract, PS> {
1309
+ readonly contract: C;
1310
+ readonly args: readonly unknown[];
1311
+ readonly privateState: PS;
1312
+ readonly coinPk: string;
1313
+ /**
1314
+ * The key the contract's maintenance authority is built from. Optional:
1315
+ * compact-js samples one when it is absent, and the result reports whichever
1316
+ * was used.
1317
+ */
1318
+ readonly signingKey?: Ledger8SigningKey;
1319
+ /** Reads the verifier key for each entry point the constructor registers. */
1320
+ readonly verifierKeys: VerifierKeyReader;
1321
+ }
1322
+
1323
+ /**
1324
+ * Everything {@link wrapKeepStateCall} needs to wrap one keep-state call.
1325
+ * `contractState` is the migrated, post-fork v9 `ContractState` — read from
1326
+ * chain, or otherwise carrying the contract's real registered operations —
1327
+ * used only to look up the `ContractOperation` for `transcript.circuitId`
1328
+ * (mirrors `ComposeLedger8CallOptions`'s `contractState` parameter in
1329
+ * `../v8/compose.ts`).
1330
+ */
1331
+ interface WrapKeepStateCallOptions {
1332
+ readonly transcript: TranscriptPojo;
1333
+ readonly contractAddress: string;
1334
+ readonly contractState: ledgerV9.ContractState;
1335
+ /**
1336
+ * The ledger parameters of the block this call is built against, or
1337
+ * {@link INITIAL_LEDGER_PARAMETERS} to accept the initial cost model.
1338
+ *
1339
+ * Required rather than defaulted, and not hard-coded to the initial parameters here: the
1340
+ * transcript crosses as `'unpartitioned'`, so the partitioner DOES run and the cost model it uses
1341
+ * is whatever this supplies. Defaulting it would make this function the silent
1342
+ * wrong-cost-model path the option exists to close. See {@link LedgerParametersOption}.
1343
+ */
1344
+ readonly ledgerParametersBytes: LedgerParametersOption;
1345
+ }
1346
+
1347
+ /** The one change a maintenance transaction carries. */
1348
+ type Ledger8MaintenanceUpdateRequest = {
1349
+ readonly kind: 'insert-verifier-key';
1350
+ readonly circuitId: string;
1351
+ readonly verifierKey: Uint8Array;
1352
+ } | {
1353
+ readonly kind: 'remove-verifier-key';
1354
+ readonly circuitId: string;
1355
+ } | {
1356
+ readonly kind: 'replace-authority';
1357
+ readonly newSigningKey: Ledger8SigningKey;
1358
+ };
1359
+ /**
1360
+ * Everything {@link composeLedger8MaintenanceTx} needs.
1361
+ *
1362
+ * `contractStateBytes` is the contract's FULL serialized state as the chain
1363
+ * holds it: the update is valid only against its maintenance authority's
1364
+ * counter, and only a key in that authority's committee may sign it.
1365
+ */
1366
+ interface Ledger8MaintenanceRequest {
1367
+ readonly contract: Ledger8EngineContract;
1368
+ readonly contractAddress: string;
1369
+ readonly contractStateBytes: Uint8Array;
1370
+ readonly coinPublicKey: string;
1371
+ readonly signingKey: Ledger8SigningKey;
1372
+ readonly networkId: string;
1373
+ readonly ttl: Date;
1374
+ readonly update: Ledger8MaintenanceUpdateRequest;
1375
+ }
1376
+
1377
+ /**
1378
+ * The public surface {@link createLedger8Engine} builds: the retained pre-fork
1379
+ * EXECUTION capabilities.
1380
+ *
1381
+ * The two execution members are ASYNCHRONOUS. They used to be synchronous, and
1382
+ * the docblock here used to promise it: compact-js builds a circuit call on
1383
+ * `Effect.tryPromise`, so `runSync` cannot discharge it and the promise is not
1384
+ * satisfiable. Nothing else about the surface changed shape -- every value
1385
+ * crossing it is still plain data or an era handle, and no `Effect` reaches a
1386
+ * caller.
1387
+ *
1388
+ * @see {@link EraBoundary}
1389
+ */
1390
+ interface Ledger8Engine {
1391
+ /**
1392
+ * Runs one circuit against the decoded contract state the chain serves.
1393
+ *
1394
+ * Takes the state and the balances beside it as ONE value -- see
1395
+ * {@link Ledger8CircuitOptions.contractState} -- because the balances a
1396
+ * circuit reads do not live inside the primary state, and two separate
1397
+ * options could describe two different blocks.
1398
+ *
1399
+ * @throws StateConversionFailedError At stage `'state conversion'` when the
1400
+ * state cannot be decoded, does not re-encode to its source, or carries a
1401
+ * balance the retained runtime cannot read.
1402
+ * @throws InvalidArgumentError When the contract declares no circuit of that name.
1403
+ */
1404
+ executeCircuit<C extends Ledger8EngineContract, PS>(options: Ledger8CircuitOptions<C, PS>): Promise<TranscriptPojo>;
1405
+ /**
1406
+ * Runs one retained-era constructor and returns the state it built.
1407
+ *
1408
+ * ASYNCHRONOUS for the same reason {@link Ledger8Engine.executeCircuit} is.
1409
+ * Stricter than the leg it replaced: compact-js registers a verifier key
1410
+ * against every declared entry point and refuses a missing one, where the
1411
+ * hand-written constructor left every slot blank.
1412
+ *
1413
+ * @throws ComposeOptionError Naming option `'signingKey'` when a supplied key
1414
+ * is not the 32 bytes of hex the retained runtime reads.
1415
+ * @throws ComposeFailedError At stage `'deploy-verifier-key-blob'` when the
1416
+ * ledger refuses the bytes served for a circuit.
1417
+ */
1418
+ executeConstructor<C extends Ledger8EngineContract, PS>(options: Ledger8ConstructorOptions<C, PS>): Promise<ConstructorResultPojo>;
1419
+ wrapKeepStateCall(options: WrapKeepStateCallOptions): ContractCallPrototype;
1420
+ /**
1421
+ * Composes an UNPROVEN v8 transaction carrying one maintenance update --
1422
+ * insert a verifier key, remove one, or replace the maintenance authority --
1423
+ * built and signed by compact-js's ledger 8 `ContractExecutable`.
1424
+ *
1425
+ * ASYNCHRONOUS for the same reason {@link Ledger8Engine.executeCircuit} is.
1426
+ * Reads the FULL state off the bytes the chain holds, and refuses a signing
1427
+ * key other than the committee's first member before anything is signed.
1428
+ *
1429
+ * @throws ComposeOptionError Naming `'networkId'`, `'ttl'`, `'signingKey'`,
1430
+ * `'newSigningKey'` or `'contractStateBytes'` when that option is unusable.
1431
+ * @throws MaintenanceAuthorityMismatchError When the signing key is not the
1432
+ * committee's first member.
1433
+ * @throws ComposeFailedError At stage `'maintenance-update'` when compact-js
1434
+ * refuses to build or sign the update.
1435
+ */
1436
+ composeMaintenanceTx(request: Ledger8MaintenanceRequest): Promise<Uint8Array>;
1437
+ /**
1438
+ * Re-expresses a ledger 8 contract's entry points as a ledger 9 contract state, so a
1439
+ * keep-state call has an operation registry the ledger 9 composer can read.
1440
+ *
1441
+ * Fork-crossing work, which is why it sits here rather than on either era facade: the input is
1442
+ * what the ledger 8 decoder read off the chain, and the output is for ledger 9.
1443
+ */
1444
+ reexpressOperationsForLedger9(entryPoints: readonly ContractEntryPointPojo[]): Uint8Array;
1445
+ }
1446
+
1447
+ /**
1448
+ * The only sanctioned runtime path to the engine's public surface.
1449
+ *
1450
+ * The retained `compact-runtime@0.16` glue and
1451
+ * `@midnight-ntwrk/onchain-runtime-v3` WASM load only on the first call — never
1452
+ * as a side effect of importing the package root.
1453
+ *
1454
+ * A failed load is not memoised: the next call retries the import. A
1455
+ * {@link Ledger8RuntimeMissingError} from the retained-runtime acquisition
1456
+ * propagates unchanged. Every other failure is wrapped in
1457
+ * {@link Ledger8RuntimeMissingError}, including the coded
1458
+ * `Ledger8RuntimeInvalidError` the envelope decoder raises for an incomplete
1459
+ * runtime, and a raw module-resolution error on the engine chunk itself.
1460
+ *
1461
+ * @returns The engine's public surface, memoised after the first successful
1462
+ * load.
1463
+ * @throws Ledger8RuntimeMissingError If the retained runtime, or the `./v8/engine`
1464
+ * chunk itself, cannot be acquired.
1465
+ * @see {@link ModuleGraphAndLazyLoading}
1466
+ * @see {@link EraBoundary}
1467
+ */
1468
+ declare const loadLedger8Engine: () => Promise<Ledger8Engine>;
1469
+
1470
+ export { COMMON_ERROR_CATEGORIES, COMMON_ERROR_CODES, CURRENT_LEDGER_ERA, ComposeFailedError, ComposeOptionError, ConfigurationError, ContractExecutionError, EnvironmentUnsupportedError, INITIAL_LEDGER_PARAMETERS, InvalidArgumentError, InvariantViolationError, LEDGER_ERAS, LEDGER_STATE_KINDS, LEDGER_STATE_TAGS, LEDGER_TRANSACTION_TAGS, Ledger8RuntimeInvalidError, Ledger8RuntimeMissingError, MIDNIGHT_JS_ERROR_CATEGORIES, MaintenanceAuthorityMismatchError, MidnightJsError, NO_CIRCUIT, PROTOCOL_ERROR_CATEGORIES, PROTOCOL_ERROR_CODES, PayloadNotATransactionError, RETAINED_LEDGER_ERAS, StateConversionFailedError, StateDecodeFailedError, StateInconsistentError, TRANSACTION_STAGES, TRANSACTION_TAG_PREFIX, UnknownLedgerEraError, UnknownProtocolVersionError, findCodedCause, latestNetworkLedgerVersion, loadLedger8Engine, loadLedger8Protocol, loadLedgerEra, protocolVersionToLedger, versionOfRecord };
1471
+ export type { CallTranscriptSource, CodedMidnightJsError, CommonErrorCode, ComposeCallEntry, ComposeCallOptions, ComposeCallResultPojo, ComposeDeployOptions, ComposeOption, ComposeStage, ConstructorResultPojo, ContractBalance, ContractEntryPointPojo, ContractStatePojo, CurrentLedgerEra, DeployResultPojo, Ledger8CircuitOptions, Ledger8ConstructorOptions, Ledger8Engine, Ledger8EngineContract, Ledger8Protocol, Ledger8SigningKey, Ledger8Subpath, LedgerEra, LedgerEraFacade, LedgerParametersOption, MaintenanceAuthorityMismatchReason, MidnightJsErrorCategory, MidnightJsErrorCodeFormat, PartitionContext, PartitionedCallTranscript, ProtocolErrorCode, ProtocolVersionSource, ProtocolVersionUnknownReason, RetainedLedgerEra, StateConversionStage, StateKind, TransactionStage, TranscriptPojo, VerifierKeyReader, VersionResolutionPath, VersionedRecord, WrapKeepStateCallOptions, ZswapOfferFactory };