@midnightntwrk/midnight-js-contracts 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.
@@ -0,0 +1,3804 @@
1
+ import { EncodedStateValue, EncPublicKey, ContractAddress as ContractAddress$1, CoinPublicKey as CoinPublicKey$1, SigningKey as SigningKey$1 } from '@midnightntwrk/midnight-js-protocol/v9';
2
+ import { ContractExecutable, CompiledContract, Contract as Contract$1 } from '@midnightntwrk/midnight-js-protocol/v9/compact-js';
3
+ export { ContractLog as Ledger9ContractLog } from '@midnightntwrk/midnight-js-protocol/v9/compact-js';
4
+ import { Contract } from '@midnightntwrk/midnight-js-protocol/v9/compact-js/effect/Contract';
5
+ import { StateValue, LogEvent, CoinPublicKey, ContractAddress, ContractState, ZswapLocalState, SigningKey, CommunicationCommitmentData, ContractModuleProvider } from '@midnightntwrk/midnight-js-protocol/v9/compact-runtime';
6
+ export { LogEvent as Ledger9LogEvent } from '@midnightntwrk/midnight-js-protocol/v9/compact-runtime';
7
+ import { CallResultPublicBase, CallResultPrivateBase, SerializedContractState, SerializedZswapChainState, SerializedLedgerParameters, MidnightConfig, MidnightProviders, PrivateStateId, AnyProvableCircuitId, ProviderMethod, FinalizedTxRead, UnprovenTx, UnsubmittedTxDataBase, LedgerTransaction, Ledger9FinalizedTxData, SubmittedCallTxBase, Ledger8FinalizedTxData, PublicStatesRead, ContractCallPrivateBase, VerifierKey, PublicDataProvider, ZKConfigProvider, PrivateStateProvider, UnshieldedBalances } from '@midnightntwrk/midnight-js-types';
8
+ import { LedgerEra, TranscriptPojo, EncodedStateValue as EncodedStateValue$1 } from '@midnightntwrk/midnight-js-protocol';
9
+ import { Option } from 'effect';
10
+ import * as _midnightntwrk_midnight_js_utils from '@midnightntwrk/midnight-js-utils';
11
+ import { MidnightJsError } from '@midnightntwrk/midnight-js-protocol/errors';
12
+ import { LedgerEra as LedgerEra$1 } from '@midnightntwrk/midnight-js-protocol/version';
13
+
14
+ /**
15
+ * Describes the target of a circuit invocation.
16
+ */
17
+ interface Ledger9CallOptionsBase<C extends Contract.Any, PCK extends Contract.ProvableCircuitId<C>> {
18
+ /**
19
+ * An optional mapping of {@link CoinPublicKey} to {@link EncPublicKey} that can be used to resolve encryption
20
+ * keys for coins created during circuit execution.
21
+ */
22
+ readonly additionalCoinEncPublicKeyMappings?: ReadonlyMap<CoinPublicKey, EncPublicKey>;
23
+ /**
24
+ * The contract defining the circuit to call.
25
+ */
26
+ readonly compiledContract: CompiledContract.CompiledContract<C, any>;
27
+ /**
28
+ * The identifier of the circuit to call.
29
+ */
30
+ readonly circuitId: PCK;
31
+ /**
32
+ * The address of the contract being executed.
33
+ */
34
+ readonly contractAddress: ContractAddress;
35
+ }
36
+ /**
37
+ * Conditional type that optionally adds the inferred circuit argument types to
38
+ * the options for a circuit call.
39
+ */
40
+ type Ledger9CallOptionsWithArguments<C extends Contract.Any, PCK extends Contract.ProvableCircuitId<C>> = Contract.CircuitParameters<C, PCK> extends [] ? Ledger9CallOptionsBase<C, PCK> : Ledger9CallOptionsBase<C, PCK> & {
41
+ /**
42
+ * Arguments to pass to the circuit being called.
43
+ */
44
+ readonly args: Contract.CircuitParameters<C, PCK>;
45
+ };
46
+ /**
47
+ * Data retrieved via providers that should be included in the call options.
48
+ */
49
+ interface Ledger9CallOptionsProviderDataDependencies {
50
+ /**
51
+ * The Zswap public key of the current user.
52
+ */
53
+ readonly coinPublicKey: CoinPublicKey;
54
+ /**
55
+ * The initial public state of the contract to run the circuit against, as read: pass
56
+ * `read.contractState` of a `PublicDataProvider` read. It must be written by the v9 ledger.
57
+ */
58
+ readonly initialContractState: SerializedContractState;
59
+ /**
60
+ * The initial public Zswap state of the contract to run the circuit against, as read: pass
61
+ * `read.zswapChainState`. It must be written by the v9 ledger.
62
+ */
63
+ readonly initialZswapChainState: SerializedZswapChainState;
64
+ /**
65
+ * The ledger parameters to use when executing the circuit, as read: pass `read.ledgerParameters`.
66
+ * They must be written by the v9 ledger.
67
+ */
68
+ readonly ledgerParameters: SerializedLedgerParameters;
69
+ /**
70
+ * Network and transaction settings, normally `providers.config`.
71
+ */
72
+ readonly config: MidnightConfig;
73
+ }
74
+ /**
75
+ * Call options with circuit arguments and data
76
+ */
77
+ type Ledger9CallOptionsWithProviderDataDependencies<C extends Contract.Any, PCK extends Contract.ProvableCircuitId<C>> = Ledger9CallOptionsWithArguments<C, PCK> & Ledger9CallOptionsProviderDataDependencies;
78
+ /**
79
+ * Call options for contracts with private state.
80
+ */
81
+ type Ledger9CallOptionsWithPrivateState<C extends Contract.Any, PCK extends Contract.ProvableCircuitId<C>> = Ledger9CallOptionsWithProviderDataDependencies<C, PCK> & {
82
+ /**
83
+ * The private state to run the circuit against.
84
+ */
85
+ readonly initialPrivateState: Contract.PrivateState<C>;
86
+ };
87
+ /**
88
+ * Call options for a given contract and circuit.
89
+ */
90
+ type Ledger9CallOptions<C extends Contract.Any, PCK extends Contract.ProvableCircuitId<C>> = Ledger9CallOptionsWithProviderDataDependencies<C, PCK> | Ledger9CallOptionsWithPrivateState<C, PCK>;
91
+ /**
92
+ * The private (sensitive) portions of the call result.
93
+ *
94
+ * @remarks
95
+ * **Privacy-sensitive type.** Every field on this type carries data the
96
+ * zero-knowledge proofs were designed to keep confidential: the ZK-aligned
97
+ * circuit input/output, the private transcript outputs from witness calls,
98
+ * the JS-typed circuit result, the next private state, and the next Zswap
99
+ * local state.
100
+ *
101
+ * Application code must not log, serialize, or transmit instances of this
102
+ * type. If a non-sensitive subset of the call result is needed (for example,
103
+ * the JS `result` value alone), extract that field explicitly rather than
104
+ * passing the whole object across a trust boundary.
105
+ */
106
+ type Ledger9CallResultPrivate<C extends Contract.Any, PCK extends Contract.ProvableCircuitId<C>> = CallResultPrivateBase<Contract.CircuitReturnType<C, PCK>, Contract.PrivateState<C>>;
107
+ /**
108
+ * The public portions of the call result.
109
+ */
110
+ interface Ledger9CallResultPublic extends CallResultPublicBase {
111
+ /**
112
+ * The public state resulting from executing the circuit.
113
+ */
114
+ readonly nextContractState: StateValue;
115
+ /**
116
+ * The same state as an {@link EncodedStateValue}: the form that survives this
117
+ * process, a `structuredClone`, a worker transfer and storage.
118
+ *
119
+ * The handle above is valid only while the runtime instance that produced it
120
+ * is loaded -- anything that walks it sees `__wbg_ptr`, an integer that means
121
+ * nothing outside its module. `EncodedStateValue` is pinned identical across
122
+ * `onchain-runtime-v3`, `ledger-v8` and `ledger-v9`, so this is the member
123
+ * era-agnostic code reads and the one to persist, in either era.
124
+ *
125
+ * Derived from the handle rather than fetched again, so the two cannot
126
+ * describe different states. It costs one encode per call; read
127
+ * {@link Ledger9CallResultPublic.nextContractState} instead when the value never
128
+ * leaves the process that produced it.
129
+ *
130
+ * @see ADR-0010 for the decision to publish the handle AND the bytes.
131
+ */
132
+ readonly nextContractStateEncoded: EncodedStateValue;
133
+ /**
134
+ * The MIP-0002 contract log events emitted during circuit execution. Surfaced on the `compact-js`
135
+ * executor result and typed by `compact-runtime`'s `LogEvent`, published here as `Ledger9LogEvent`. This is the single
136
+ * execution-wide list across the whole call tree (not just the root call), in emission order; each
137
+ * event is tagged with its emitting contract's address, so a per-contract view is a filter over
138
+ * that address.
139
+ *
140
+ * Events are carried **raw** — decode on demand with `Ledger9ContractLog.decodeAll` (re-exported from
141
+ * this package). The decoder degrades gracefully and never throws, but it is `@experimental`: a
142
+ * successful decode can still yield a silently-wrong payload, so treat decoded values with care.
143
+ * Empty when the circuit emits no logs.
144
+ */
145
+ readonly logEvents: readonly LogEvent[];
146
+ }
147
+ /**
148
+ * Contains all information resulting from circuit execution.
149
+ *
150
+ * @remarks
151
+ * **Privacy-sensitive type.** The `private` field is a
152
+ * {@link Ledger9CallResultPrivate} carrying ZK-confidential data. Treat the whole
153
+ * object as confidential when logging, serializing, or transmitting — read
154
+ * only the `public` field or destructure specific non-sensitive fields rather
155
+ * than spreading or stringifying the whole object.
156
+ */
157
+ interface Ledger9CallResult<C extends Contract.Any, PCK extends Contract.ProvableCircuitId<C>> {
158
+ /**
159
+ * The public/non-sensitive data produced by the circuit execution.
160
+ *
161
+ * @remarks Describes the **root** contract call (the circuit that was invoked). It is the
162
+ * application-facing view; equivalent to the last entry of {@link calls}.
163
+ */
164
+ readonly public: Ledger9CallResultPublic;
165
+ /**
166
+ * The private/sensitive data produced by the circuit execution.
167
+ *
168
+ * @remarks Describes the **root** contract call. Equivalent to the last entry of {@link calls}.
169
+ */
170
+ readonly private: Ledger9CallResultPrivate<C, PCK>;
171
+ /**
172
+ * Proof data for every contract call made while executing the circuit, in execution-trace order:
173
+ * cross-contract callees first, the root call last. For a circuit that performs no cross-contract
174
+ * calls this contains a single entry (the root). Consistent with `compact-js`'s
175
+ * `ContractExecutable.CallResult.calls`.
176
+ *
177
+ * @remarks **Privacy-sensitive.** Each entry carries ZK input/output and private transcript data
178
+ * for a call in the tree. Treat as confidential alongside {@link private}.
179
+ */
180
+ readonly calls: readonly ContractExecutable.ContractExecutable.ContractCall[];
181
+ /**
182
+ * The pipeline that produced this result: always ledger 9 here.
183
+ *
184
+ * Read off the compiled artifact, NEVER off a transaction record — the two
185
+ * facts disagree after the fork, and only this one says which module the
186
+ * objects in this result came from.
187
+ */
188
+ readonly era: 'v9';
189
+ }
190
+
191
+ /**
192
+ * Describes the target of a circuit invocation.
193
+ */
194
+ interface Ledger9ContractConstructorOptionsBase<C extends Contract$1.Any> {
195
+ /**
196
+ * The compiled contract defining the circuit to call.
197
+ */
198
+ readonly compiledContract: CompiledContract.CompiledContract<C, any>;
199
+ }
200
+ /**
201
+ * Conditional type that optionally adds the inferred contract constructor argument types
202
+ * to the constructor options.
203
+ */
204
+ type Ledger9ContractConstructorOptionsWithArguments<C extends Contract$1.Any> = Contract$1.InitializeParameters<C> extends [] ? Ledger9ContractConstructorOptionsBase<C> : Ledger9ContractConstructorOptionsBase<C> & {
205
+ /**
206
+ * Arguments to pass to the circuit being called.
207
+ */
208
+ readonly args: Contract$1.InitializeParameters<C>;
209
+ };
210
+ /**
211
+ * Data retrieved via providers that should be included in the constructor call options.
212
+ */
213
+ interface ContractConstructorOptionsProviderDataDependencies {
214
+ /**
215
+ * The current user's ZSwap public key.
216
+ */
217
+ readonly coinPublicKey: CoinPublicKey;
218
+ }
219
+ /**
220
+ * Contract constructor options including arguments and provider data.
221
+ */
222
+ type Ledger9ContractConstructorOptionsWithProviderDataDependencies<C extends Contract$1.Any> = Ledger9ContractConstructorOptionsWithArguments<C> & ContractConstructorOptionsProviderDataDependencies;
223
+ /**
224
+ * Conditional type that optionally adds the inferred circuit argument types to
225
+ * the target of a circuit invocation.
226
+ */
227
+ type Ledger9ContractConstructorOptionsWithPrivateState<C extends Contract$1.Any> = Ledger9ContractConstructorOptionsWithProviderDataDependencies<C> & {
228
+ /**
229
+ * The private state to run the circuit against.
230
+ */
231
+ readonly initialPrivateState: Contract$1.PrivateState<C>;
232
+ };
233
+ /**
234
+ * Conditional type that optionally adds the inferred circuit argument types to
235
+ * the target of a circuit invocation.
236
+ */
237
+ type Ledger9ContractConstructorOptions<C extends Contract$1.Any> = Ledger9ContractConstructorOptionsWithProviderDataDependencies<C> | Ledger9ContractConstructorOptionsWithPrivateState<C>;
238
+ /**
239
+ * The updated states resulting from executing a contract constructor.
240
+ */
241
+ interface Ledger9ContractConstructorResult<C extends Contract$1.Any> {
242
+ /**
243
+ * The public state resulting from executing the contract constructor.
244
+ */
245
+ readonly nextContractState: ContractState;
246
+ /**
247
+ * The private state resulting from executing the contract constructor.
248
+ */
249
+ readonly nextPrivateState: Contract$1.PrivateState<C>;
250
+ /**
251
+ * The Zswap local state resulting from executing the contract constructor.
252
+ */
253
+ readonly nextZswapLocalState: ZswapLocalState;
254
+ /**
255
+ * The pipeline that produced this result: always ledger 9 here.
256
+ *
257
+ * Read off the compiled artifact, NEVER off a transaction record — the two
258
+ * facts disagree after the fork, and only this one says which module the
259
+ * objects in this result came from.
260
+ */
261
+ readonly era: 'v9';
262
+ }
263
+
264
+ /**
265
+ * Convenience type for representing the set of providers necessary to use
266
+ * a given contract.
267
+ */
268
+ type Ledger9ContractProviders<C extends Contract.Any = Contract.Any, PCK extends Contract.ProvableCircuitId<C> = Contract.ProvableCircuitId<C>, PS = Contract.PrivateState<C>> = MidnightProviders<PCK, PrivateStateId, PS>;
269
+
270
+ /**
271
+ * An error indicating that a provider, or the read surface, answered in a
272
+ * different ledger era from the one the flow submitted.
273
+ *
274
+ * The transaction methods and the read methods both carry two eras, but any ONE
275
+ * flow through this package hands every provider a transaction handle of a
276
+ * single era and cannot submit or report anything else. An answer in the other
277
+ * era therefore means the provider answered with a handle of an era it was not
278
+ * handed, or that the flow is pointed at a network whose records belong to the
279
+ * other era.
280
+ *
281
+ * {@link EraInvariantViolationError.expected} names the only era this flow can
282
+ * accept back, and so which direction the violation went. For the current
283
+ * era's flows that is the era they submit, which is always `'v9'` — the
284
+ * default, so call sites that predate the retained-era pipelines read exactly
285
+ * as they did before it existed. The retained era's finalizing path passes the
286
+ * network's ledger version instead: it composes retained-era transactions but is
287
+ * recorded by whichever ledger the network is on, so the network, not the pipeline, is what
288
+ * the record has to agree with.
289
+ *
290
+ * {@link EraInvariantViolationError.received} names the era that actually came
291
+ * back. An answer that is not a transaction handle at all is a different
292
+ * fault and raises `InvalidTransactionHandleError` instead; a read-surface
293
+ * record whose `era` is missing or unrecognised raises
294
+ * `UnknownLedgerEraError`.
295
+ */
296
+ declare class EraInvariantViolationError extends MidnightJsError {
297
+ readonly method: ProviderMethod;
298
+ readonly circuitId?: (string | readonly string[]) | undefined;
299
+ readonly expected: LedgerEra;
300
+ readonly received?: LedgerEra | undefined;
301
+ readonly contractAddress?: string | undefined;
302
+ readonly txId?: string | undefined;
303
+ readonly code: "MIDNIGHT_JS_C_ERA_INVARIANT_VIOLATION";
304
+ readonly category: _midnightntwrk_midnight_js_utils.MidnightJsErrorCategory;
305
+ /**
306
+ * @param method The provider method that returned the payload.
307
+ * @param circuitId The circuit, or circuits, whose flow this happened on,
308
+ * when known. A dApp firing many circuits needs this to
309
+ * tell which call broke.
310
+ * @param expected The only era this flow can accept back. Defaults to
311
+ * `'v9'`. See the class comment for which fact this names
312
+ * on each path.
313
+ * @param received The era the payload actually carried, when it carried a
314
+ * readable one. Named in the message: a refusal that states
315
+ * only what it wanted leaves the reader to find out what it
316
+ * got.
317
+ * @param contractAddress The contract the payload was read for, when the
318
+ * flow reads one contract's records.
319
+ * @param txId The transaction the payload belongs to, when it is already on
320
+ * chain. A caller needs it to reconcile a transaction it cannot
321
+ * take back.
322
+ */
323
+ constructor(method: ProviderMethod, circuitId?: (string | readonly string[]) | undefined, expected?: LedgerEra, received?: LedgerEra | undefined, contractAddress?: string | undefined, txId?: string | undefined);
324
+ }
325
+ /**
326
+ * Why an object was refused as belonging to the wrong era, or to neither.
327
+ *
328
+ * One error class over every reason rather than a class per reason: a caller catches "this operation
329
+ * cannot be placed on a ledger era" as one condition, and the reason is what tells it which mistake
330
+ * it made. Some reasons are about the CALLER's contract object, some about the artifact set its ZK
331
+ * config provider serves, and two about a transaction handed to `submitTx`. From the caller's side
332
+ * that is one condition: something it passed does not belong to the era it is being run against.
333
+ */
334
+ type EraMismatchReason =
335
+ /** A raw ledger 9 contract instance, passed where its `CompiledContract` container belongs. */
336
+ 'unwrapped-ledger9-contract'
337
+ /** An object matching no era's shape at all. */
338
+ | 'unrecognised-contract-shape'
339
+ /** A ledger 9 artifact, on a network that is still on ledger 8. */
340
+ | 'ledger9-artifact-on-ledger8-network'
341
+ /** A v9 transaction handed to `submitTx`, on a network that is still pre-fork. */
342
+ | 'ledger9-transaction-on-ledger8-network'
343
+ /** A v8 transaction handed to `submitTx`, on a network that has crossed the fork. */
344
+ | 'ledger8-transaction-on-ledger9-network'
345
+ /** An artifact set that does not declare which `compact-runtime` produced it. */
346
+ | 'artifact-era-undeclared'
347
+ /** A ZK config provider that cannot report a declared runtime version at all. */
348
+ | 'provider-cannot-declare-era'
349
+ /** An artifact set declaring a `compact-runtime` this framework places on no ledger era. */
350
+ | 'unknown-artifact-runtime-version'
351
+ /** A ledger 9 `CompiledContract` container whose artifacts declare the ledger 8 toolchain. `detail` carries the declared version. */
352
+ | 'ledger8-artifacts-in-ledger9-container'
353
+ /** A ledger 8 (pre-fork) contract submitted for deployment to a network that has crossed the fork. */
354
+ | 'ledger8-deploy-on-ledger9-network'
355
+ /** A ledger 8 (pre-fork) contract given to a maintenance update on a network that has crossed the fork. */
356
+ | 'ledger8-maintenance-on-ledger9-network'
357
+ /** Ledger 8 artifacts given for a contract held on chain in a ledger 9 state they do not describe. `detail` carries the contract address; `cause` the key mismatch. */
358
+ | 'ledger8-artifact-on-ledger9-contract'
359
+ /** A read that handles only ledger 9 states met a state the v8 ledger wrote. `detail` carries the contract address and the operation. */
360
+ | 'ledger8-contract-state-unsupported'
361
+ /** A contract-scoped transaction function bound to one ledger, run on a network of another ledger. `detail` carries the function and the network version. */
362
+ | 'scope-era-mismatch'
363
+ /** A call against a ledger 8 (pre-fork) contract given a ledger 9 contract-scoped transaction to join. `detail` carries the circuit id. */
364
+ | 'ledger8-call-in-scope'
365
+ /** A contract whose artifacts declare an era the low-level function does not serve. `detail` carries the function name and that era. */
366
+ | 'contract-era-unsupported'
367
+ /** A result whose `era` tag names neither pipeline. `detail` carries the value received. */
368
+ | 'unrecognised-result-era';
369
+ /** Options for {@link EraMismatchError}. */
370
+ interface EraMismatchOptions extends ErrorOptions {
371
+ /**
372
+ * A sentence appended to the settled wording for this reason, naming the value that was actually
373
+ * seen. Kept OUT of the reason's own message so every instance of a reason reads identically up to
374
+ * the fact that varies.
375
+ */
376
+ readonly detail?: string;
377
+ /** The contract the refused value belongs to. Set for `'ledger8-artifact-on-ledger9-contract'` and `'ledger8-contract-state-unsupported'`. */
378
+ readonly contractAddress?: ContractAddress;
379
+ /** The circuit the refused call names. Set for `'ledger8-call-in-scope'`, and for `'ledger9-artifact-on-ledger8-network'` raised for a call given a ledger 8 scope. */
380
+ readonly circuitId?: string;
381
+ }
382
+ /**
383
+ * An error indicating that a value the caller passed does not belong to the era the operation can
384
+ * execute — or to either era. The value is a contract, an artifact set, a transaction, a scope, a
385
+ * result, or a contract state read from the chain.
386
+ *
387
+ * Raised before anything is proved or submitted, except `'unrecognised-result-era'`, which is raised
388
+ * when a result that came back from the chain is read.
389
+ *
390
+ * @see {@link EraDispatch} for how the era is established and which pairings are refused.
391
+ */
392
+ declare class EraMismatchError extends MidnightJsError {
393
+ readonly reason: EraMismatchReason;
394
+ readonly code: "MIDNIGHT_JS_C_ERA_MISMATCH";
395
+ readonly category: _midnightntwrk_midnight_js_utils.MidnightJsErrorCategory;
396
+ /** The sentence appended to the reason's wording, naming the value that was seen. */
397
+ readonly detail?: string;
398
+ /** The contract the refused value belongs to, for the reasons that have one. */
399
+ readonly contractAddress?: ContractAddress;
400
+ /** The circuit the refused call names, for the reasons {@link EraMismatchOptions.circuitId} lists. */
401
+ readonly circuitId?: string;
402
+ /**
403
+ * @param reason Which era mismatch this is. Also the discriminant a caller branches on, so it is
404
+ * retained on the error rather than only rendered.
405
+ * @param options Carries the originating failure on `cause` -- a provider that could not serve the
406
+ * artifact description reports WHY there -- and an optional `detail` naming the
407
+ * value that was seen.
408
+ */
409
+ constructor(reason: EraMismatchReason, options?: EraMismatchOptions);
410
+ }
411
+ /**
412
+ * An error indicating that the ledger version this operation read from the network is a different ledger era from
413
+ * the one the contract state it fetched was written by, and that a fresh read of the network's ledger version
414
+ * confirms the first reading was the stale half.
415
+ *
416
+ * The two are read at separate moments, so during the fork window an operation can start from a
417
+ * network version reading that is already behind the state it goes on to fetch.
418
+ *
419
+ * The message deliberately does NOT claim which of the two readings moved: the check establishes
420
+ * that they disagree and that a fresh read agrees with the state, never a direction. Do not add
421
+ * one.
422
+ *
423
+ * @see {@link EraDispatch} for the five-step check that produces this error.
424
+ */
425
+ declare class NetworkVersionStateMismatchError extends MidnightJsError {
426
+ readonly networkVersion: LedgerEra;
427
+ readonly stateEra: LedgerEra;
428
+ readonly code: "MIDNIGHT_JS_C_NETWORK_VERSION_STATE_MISMATCH";
429
+ readonly category: _midnightntwrk_midnight_js_utils.MidnightJsErrorCategory;
430
+ /**
431
+ * @param networkVersion The ledger version the network reported when the operation started.
432
+ * @param stateEra The ledger era that wrote the fetched state.
433
+ */
434
+ constructor(networkVersion: LedgerEra, stateEra: LedgerEra);
435
+ }
436
+ /**
437
+ * An error indicating that the read surface reported a network ledger version and a contract state whose eras
438
+ * disagree, and that the disagreement survived a fresh read of the network's ledger version.
439
+ *
440
+ * Distinct from {@link NetworkVersionStateMismatchError}, and the distinction is the point: there the network
441
+ * version reading was merely stale and re-running fixes it. Here the network version is confirmed, so the served
442
+ * state and the served network version cannot both describe one chain — which is a fault in the data served, not a
443
+ * timing artefact the caller can correct. Deliberately NOT reported as a fork in progress: nothing
444
+ * observed here establishes that one is under way, and telling a caller to wait out a fork that is
445
+ * not happening is worse than telling it to retry.
446
+ */
447
+ declare class IndexerInconsistencyError extends MidnightJsError {
448
+ readonly networkVersion: LedgerEra;
449
+ readonly stateEra: LedgerEra;
450
+ readonly code: "MIDNIGHT_JS_C_INDEXER_INCONSISTENCY";
451
+ readonly category: _midnightntwrk_midnight_js_utils.MidnightJsErrorCategory;
452
+ /**
453
+ * @param networkVersion The ledger version the network reported, confirmed by a second read.
454
+ * @param stateEra The ledger era that wrote the fetched state.
455
+ */
456
+ constructor(networkVersion: LedgerEra, stateEra: LedgerEra);
457
+ }
458
+ /**
459
+ * An error indicating that the read surface served the ledger parameters or the zswap chain state of
460
+ * a contract written by another ledger era than the one the call is built on, or did not serve them.
461
+ * One read carries the states of one era, so the states cannot be combined into a call.
462
+ */
463
+ declare class PublicStatesEraMismatchError extends MidnightJsError {
464
+ readonly contractAddress: string;
465
+ readonly field: 'ledgerParameters' | 'zswapChainState';
466
+ readonly expected: LedgerEra;
467
+ readonly received: LedgerEra | undefined;
468
+ readonly code: "MIDNIGHT_JS_C_PUBLIC_STATES_ERA_MISMATCH";
469
+ readonly category: _midnightntwrk_midnight_js_utils.MidnightJsErrorCategory;
470
+ /**
471
+ * @param contractAddress The contract whose public states were read.
472
+ * @param field The state that does not match the call.
473
+ * @param expected The ledger era the call is built on.
474
+ * @param received The era of that state, or `undefined` when it was missing.
475
+ */
476
+ constructor(contractAddress: string, field: 'ledgerParameters' | 'zswapChainState', expected: LedgerEra, received: LedgerEra | undefined);
477
+ }
478
+ /**
479
+ * An error indicating that the read surface served a contract state without the block's ledger
480
+ * parameters, so a call cannot be composed against the cost model the chain is running.
481
+ *
482
+ * A caller that genuinely cannot read the chain selects the compatibility path by name — see
483
+ * `INITIAL_LEDGER_PARAMETERS` in `midnight-js-protocol`.
484
+ *
485
+ * @see {@link ErrorTaxonomy} for why this refuses rather than substituting the ledger's initial
486
+ * parameters.
487
+ */
488
+ declare class LedgerParametersUnservedError extends MidnightJsError {
489
+ readonly contractAddress: string;
490
+ readonly code: "MIDNIGHT_JS_C_LEDGER_PARAMETERS_UNSERVED";
491
+ readonly category: _midnightntwrk_midnight_js_utils.MidnightJsErrorCategory;
492
+ /**
493
+ * @param contractAddress The contract whose state was read without its block's parameters.
494
+ */
495
+ constructor(contractAddress: string);
496
+ }
497
+ /**
498
+ * An error indicating that a provider rejected a transaction at one of the
499
+ * three transaction methods, with the provider's own failure SANITIZED onto
500
+ * `cause`. Raised on every submit path, whatever era the transaction belongs to.
501
+ *
502
+ * ## Why the external failure does not travel as-is
503
+ *
504
+ * A proof-server HTTP failure and a node submit rejection both routinely carry
505
+ * payload material: a response body echoing the request, a message quoting the
506
+ * serialized transaction, or vendor-specific own properties holding either.
507
+ * Propagating such an error unchanged puts that material into whatever the
508
+ * caller logs it with. So the cause is rebuilt here as a plain {@link Error}
509
+ * carrying the original's CLASS NAME and a redacted message, and nothing else:
510
+ * no own properties, and no further `cause` chain.
511
+ *
512
+ * This package's own coded errors are NOT wrapped: they carry no external
513
+ * payload, and a caller narrowing on `ProviderEraUnsupportedError`,
514
+ * `InvalidTransactionHandleError` or {@link EraInvariantViolationError} must keep seeing them.
515
+ *
516
+ * @see {@link KeepStatePipeline} for what redaction removes and what is dropped.
517
+ */
518
+ declare class ProviderFailedError extends MidnightJsError {
519
+ readonly method: ProviderMethod;
520
+ readonly circuitId: string | readonly string[] | undefined;
521
+ readonly code: "MIDNIGHT_JS_C_PROVIDER_FAILED";
522
+ readonly category: _midnightntwrk_midnight_js_utils.MidnightJsErrorCategory;
523
+ /**
524
+ * @param method The provider method that rejected.
525
+ * @param circuitId The circuit, or circuits, the transaction runs, when known.
526
+ * @param cause The provider's failure, already sanitized by the caller.
527
+ */
528
+ constructor(method: ProviderMethod, circuitId: string | readonly string[] | undefined, cause: Error);
529
+ }
530
+ /**
531
+ * Whether a contract operation was deploying a contract, calling one already deployed, or
532
+ * maintaining one. A {@link ForkCrossedDuringOperationError} can also carry `'transaction'`, for a
533
+ * transaction submitted with `submitTx` / `submitTxAsync`; see {@link SubmittedOperation}.
534
+ *
535
+ * The same discriminant the era pairing table takes, kept as its own type here
536
+ * because it decides which of the genuinely different remediations the error
537
+ * carries.
538
+ */
539
+ type SubmittedOperationKind = 'call' | 'deploy' | 'maintenance';
540
+ /**
541
+ * WHICH operation a submit rejection belongs to: the identity every refusal
542
+ * below has to name so its remediation can actually be followed.
543
+ *
544
+ * A dApp with several calls in flight shares one error handler, so an error
545
+ * telling it to "check whether this finalized" is unfollowable unless it says
546
+ * which contract and which entry point. Contract addresses and circuit ids are
547
+ * identifiers, which messages may carry; decoded state and key bytes are what
548
+ * they may not.
549
+ */
550
+ interface SubmittedContractOperation {
551
+ /**
552
+ * The ledger version the network was on when this operation started.
553
+ *
554
+ * One field, two uses, and they are the same fact: it is the era of the
555
+ * transaction carried across the provider methods, and it is the `startEra` a
556
+ * fork diagnosis compares a fresh reading against.
557
+ */
558
+ readonly networkVersion: LedgerEra;
559
+ /** Whether this operation deploys a contract, calls one already deployed, or maintains one. */
560
+ readonly kind: SubmittedOperationKind;
561
+ /**
562
+ * The entry point this operation ran. A deploy has no circuit of its own and
563
+ * reports the constructor's own name, `'initialState'`; a maintenance
564
+ * authority replacement reports {@link NO_CIRCUIT}.
565
+ */
566
+ readonly circuitId: string;
567
+ /**
568
+ * The contract this operation targets. For a deploy this is the address the
569
+ * composition MINTED, which is the address a caller has to check before
570
+ * deploying again — a deploy mints a fresh nonce, so a second attempt lands
571
+ * at a different address and would not overwrite the first.
572
+ */
573
+ readonly contractAddress: string;
574
+ }
575
+ /**
576
+ * A transaction submitted with `submitTx` or `submitTxAsync`: the caller built it, so neither the
577
+ * contract nor, unless the caller named it, the circuit is known.
578
+ */
579
+ interface SubmittedTransaction {
580
+ /** The ledger version the network was on when `submitTx` read it. */
581
+ readonly networkVersion: LedgerEra;
582
+ readonly kind: 'transaction';
583
+ /** The circuits the caller named on the submit options, joined by `', '`, or `undefined`. */
584
+ readonly circuitId: string | undefined;
585
+ readonly contractAddress?: undefined;
586
+ }
587
+ /** {@link SubmittedContractOperation} or {@link SubmittedTransaction}. */
588
+ type SubmittedOperation = SubmittedContractOperation | SubmittedTransaction;
589
+ /**
590
+ * An error indicating that the network crossed the ledger fork between an
591
+ * operation reading the network's ledger version and its transaction being submitted, and
592
+ * that a fresh read confirms the move.
593
+ *
594
+ * Carries a two-step remediation, and the order matters: verify the transaction
595
+ * did not finalize BEFORE acting, because a submission rejected while the network
596
+ * was crossing the fork can still have been recorded.
597
+ *
598
+ * The provider's own rejection travels on `cause`, already sanitized of
599
+ * anything that could carry transaction or witness material — see
600
+ * {@link ProviderFailedError}, which is the form it arrives in.
601
+ *
602
+ * @see {@link ForkCrossedRemediation} for why a submit rejection is diagnosed
603
+ * rather than propagated, and why a deploy's remediation differs.
604
+ */
605
+ declare class ForkCrossedDuringOperationError extends MidnightJsError {
606
+ readonly freshEra: LedgerEra;
607
+ readonly code: "MIDNIGHT_JS_C_FORK_CROSSED_DURING_OPERATION";
608
+ readonly category: _midnightntwrk_midnight_js_utils.MidnightJsErrorCategory;
609
+ /** The era the operation resolved when it started. */
610
+ readonly startEra: LedgerEra;
611
+ /**
612
+ * Whether the refused operation was a call, a deploy, a maintenance update or a transaction
613
+ * submitted with `submitTx` / `submitTxAsync` — the discriminant a caller branches on, and which
614
+ * remediation the message carries.
615
+ */
616
+ readonly kind: SubmittedOperation['kind'];
617
+ /**
618
+ * The entry point that was run, so a caller with several in flight knows which. `undefined` only for
619
+ * a `'transaction'` whose caller named no circuit.
620
+ */
621
+ readonly circuitId: string | undefined;
622
+ /**
623
+ * The contract to reconcile, which is the first remediation step's subject. `undefined` only for a
624
+ * `'transaction'`, whose contract `submitTx` does not know.
625
+ */
626
+ readonly contractAddress: string | undefined;
627
+ /**
628
+ * @param operation Which operation was rejected. Flattened onto the error
629
+ * rather than nested, so a caller reads `error.circuitId`
630
+ * without knowing this type exists.
631
+ * @param freshEra The era a fresh read of the network reports now. Retained on the
632
+ * error because it is what a caller re-runs against.
633
+ * @param cause The submit rejection, already sanitized.
634
+ */
635
+ constructor(operation: SubmittedOperation, freshEra: LedgerEra, cause: unknown);
636
+ }
637
+ /**
638
+ * Why a submit rejection could NOT be diagnosed as a fork crossing or ruled out
639
+ * as one.
640
+ *
641
+ * A discriminated union rather than two error classes, because a caller's
642
+ * decision is the same for both — do not blindly retry, find out whether the
643
+ * transaction landed, then look at the read surface — and the reason is what
644
+ * tells it which of the two happened.
645
+ */
646
+ type SubmitRejectionUndiagnosedCause =
647
+ /** Reading the network's ledger version again itself failed, so no reading is available to compare. */
648
+ {
649
+ readonly reason: 'network-version-read-failed';
650
+ readonly networkVersionReadFailure: unknown;
651
+ }
652
+ /**
653
+ * The fresh read reported an EARLIER era than the operation started against.
654
+ * A ledger era only ever moves forward, so the two readings cannot both
655
+ * describe one chain.
656
+ */
657
+ | {
658
+ readonly reason: 'network-version-went-backwards';
659
+ readonly freshEra: LedgerEra;
660
+ };
661
+ /**
662
+ * An error indicating that a submission was rejected and that whether the
663
+ * network crossed the ledger fork under it could not be established.
664
+ *
665
+ * The submission rejection is what happened to the transaction and is always
666
+ * the FIRST entry of `errors`, {@link reason} is why
667
+ * no diagnosis could be made, and `cause` names the proximate failure.
668
+ *
669
+ * DO NOT COPY THE CARRIED REJECTION'S CODE ONTO THIS ERROR. It has its own.
670
+ *
671
+ * @see {@link ErrorTaxonomy} for why the two codes name different things.
672
+ * @see {@link ForkCrossedRemediation} for the two reasons.
673
+ */
674
+ declare class SubmitRejectionUndiagnosedError extends MidnightJsError {
675
+ readonly code: "MIDNIGHT_JS_C_SUBMIT_REJECTION_UNDIAGNOSED";
676
+ readonly category: _midnightntwrk_midnight_js_utils.MidnightJsErrorCategory;
677
+ /** The submission rejection first, then the failure to read the network's ledger version again, when there was one. */
678
+ readonly errors: readonly unknown[];
679
+ /** Which of the two undiagnosable conditions this is. */
680
+ readonly reason: SubmitRejectionUndiagnosedCause['reason'];
681
+ /** The era the operation resolved when it started. */
682
+ readonly startEra: LedgerEra;
683
+ readonly kind: SubmittedOperation['kind'];
684
+ /** See {@link ForkCrossedDuringOperationError.circuitId}. */
685
+ readonly circuitId: string | undefined;
686
+ /** See {@link ForkCrossedDuringOperationError.contractAddress}. */
687
+ readonly contractAddress: string | undefined;
688
+ /**
689
+ * @param operation Which operation was rejected.
690
+ * @param rejection The submit rejection, already sanitized. Always the FIRST
691
+ * entry of `errors`.
692
+ * @param undiagnosed Why no diagnosis could be made.
693
+ */
694
+ constructor(operation: SubmittedOperation, rejection: unknown, undiagnosed: SubmitRejectionUndiagnosedCause);
695
+ }
696
+ /**
697
+ * The network's ledger version could not be read: either re-reading it while checking an era disagreement failed,
698
+ * or the public data provider returned no latest block to pin a call to. Retry when the read surface is
699
+ * reachable; a transport failure, when there is one, is on `cause`.
700
+ */
701
+ declare class NetworkVersionReadFailedError extends MidnightJsError {
702
+ readonly code: "MIDNIGHT_JS_C_NETWORK_VERSION_READ_FAILED";
703
+ readonly category: _midnightntwrk_midnight_js_utils.MidnightJsErrorCategory;
704
+ constructor(message: string, options?: ErrorOptions);
705
+ }
706
+ /** A Zswap output or its recipient's encryption key could not be resolved for this transaction. */
707
+ declare class ZswapOutputResolutionError extends MidnightJsError {
708
+ readonly code: "MIDNIGHT_JS_C_ZSWAP_OUTPUT_UNRESOLVED";
709
+ readonly category: _midnightntwrk_midnight_js_utils.MidnightJsErrorCategory;
710
+ constructor(message: string, options?: ErrorOptions);
711
+ }
712
+ /** No contract is deployed at the given address on the network the providers point to. */
713
+ declare class ContractNotFoundError extends MidnightJsError {
714
+ readonly code: "MIDNIGHT_JS_C_CONTRACT_NOT_FOUND";
715
+ readonly category: _midnightntwrk_midnight_js_utils.MidnightJsErrorCategory;
716
+ constructor(message: string, options?: ErrorOptions);
717
+ }
718
+ /** No private state is stored under the private state id the caller named. */
719
+ declare class PrivateStateNotFoundError extends MidnightJsError {
720
+ readonly code: "MIDNIGHT_JS_C_PRIVATE_STATE_NOT_FOUND";
721
+ readonly category: _midnightntwrk_midnight_js_utils.MidnightJsErrorCategory;
722
+ constructor(message: string, options?: ErrorOptions);
723
+ }
724
+ /**
725
+ * The operations whose transaction the chain can record as failed.
726
+ */
727
+ type TxFailedOperation = 'call' | 'deploy' | 'insert-verifier-key' | 'remove-verifier-key' | 'replace-authority';
728
+ /**
729
+ * What a failed transaction was about, beyond its record.
730
+ */
731
+ interface TxFailedDetails {
732
+ /** Set by a ledger 8 call, a deploy and the three maintenance operations. Not set by a ledger 9 call. */
733
+ readonly contractAddress?: ContractAddress;
734
+ /** A call, or an insert or removal of a verifier key. A list when a scope made several calls. */
735
+ readonly circuitId?: string | readonly string[];
736
+ /** A deploy (the authority the contract was built with) or a replacement (the new authority). */
737
+ readonly signingKey?: SigningKey;
738
+ }
739
+ /**
740
+ * A transaction this framework submitted that the chain recorded with a
741
+ * non-success status, in either ledger era. The one class to catch.
742
+ *
743
+ * Read {@link TxFailedError.operation} for which operation failed, and
744
+ * {@link TxFailedError.record} for what the chain recorded. `record.tx` is a
745
+ * `FinalizedTx` in the era `record.era` names; after narrowing on `era`, read it
746
+ * with your own ledger copy: `record.tx.deserialize({ v9: Transaction })`.
747
+ *
748
+ * {@link TxFailedError.signingKey} is NAMED in the message but never rendered
749
+ * into it: after a failed deploy or replacement it may be the only copy of the
750
+ * authority over a contract that landed. It is not enumerable, so a logger that
751
+ * serializes an error's properties does not write it out.
752
+ *
753
+ * Branch on the registered code rather than `instanceof` where more than one
754
+ * copy of this package may be loaded.
755
+ */
756
+ declare class TxFailedError extends MidnightJsError {
757
+ readonly operation: TxFailedOperation;
758
+ readonly record: FinalizedTxRead;
759
+ readonly code: "MIDNIGHT_JS_C_TX_FAILED";
760
+ readonly category: _midnightntwrk_midnight_js_utils.MidnightJsErrorCategory;
761
+ readonly contractAddress?: ContractAddress;
762
+ readonly circuitId?: string | readonly string[];
763
+ readonly signingKey?: SigningKey;
764
+ /**
765
+ * @param operation The operation whose transaction failed.
766
+ * @param record The finalized record the chain reported, tagged with its era.
767
+ * @param details What the operation was about. Each operation requires the members it always has.
768
+ */
769
+ constructor(operation: 'deploy' | 'replace-authority', record: FinalizedTxRead, details: {
770
+ readonly contractAddress: ContractAddress;
771
+ readonly signingKey: SigningKey;
772
+ });
773
+ constructor(operation: 'insert-verifier-key' | 'remove-verifier-key', record: FinalizedTxRead, details: {
774
+ readonly contractAddress: ContractAddress;
775
+ readonly circuitId: string;
776
+ });
777
+ constructor(operation: 'call', record: FinalizedTxRead, details: {
778
+ readonly circuitId: string | readonly string[];
779
+ readonly contractAddress?: ContractAddress;
780
+ });
781
+ }
782
+ /**
783
+ * The ways in which a circuit the client holds a verifier key for can fail to line up with the
784
+ * contract state deployed on chain. Each circuit falls into exactly one of these.
785
+ */
786
+ interface ContractTypeMismatch {
787
+ /**
788
+ * Circuits for which the deployed state registers no operation at all.
789
+ */
790
+ readonly missing: AnyProvableCircuitId[];
791
+ /**
792
+ * Circuits whose operation is registered on the deployed state but carries no verifier key.
793
+ */
794
+ readonly keyless: AnyProvableCircuitId[];
795
+ /**
796
+ * Circuits whose deployed verifier key differs from the one the client holds.
797
+ */
798
+ readonly mismatched: AnyProvableCircuitId[];
799
+ }
800
+ /**
801
+ * The error that is thrown when there is a contract type mismatch between a given contract type,
802
+ * and the initial state that is deployed at a given contract address.
803
+ *
804
+ * @remarks
805
+ * This error is typically thrown during calls to {@link findDeployedContract} where the supplied contract
806
+ * address represents a different type of contract to the contract type given.
807
+ *
808
+ * The three conditions are reported separately because they call for different responses: a
809
+ * mismatched key means the local artifacts are wrong, while a keyless slot means the deployed state
810
+ * itself is incomplete and rebuilding locally cannot help.
811
+ */
812
+ declare class ContractTypeError extends MidnightJsError {
813
+ readonly contractState: SerializedContractState;
814
+ readonly contractAddress?: ContractAddress | undefined;
815
+ readonly code: "MIDNIGHT_JS_C_CONTRACT_TYPE_MISMATCH";
816
+ readonly category: _midnightntwrk_midnight_js_utils.MidnightJsErrorCategory;
817
+ /**
818
+ * The circuits that the deployed state registers no operation for.
819
+ */
820
+ readonly missingCircuitIds: AnyProvableCircuitId[];
821
+ /**
822
+ * The circuits whose deployed operation carries no verifier key.
823
+ */
824
+ readonly keylessCircuitIds: AnyProvableCircuitId[];
825
+ /**
826
+ * The circuits whose deployed verifier key differs from the local one.
827
+ */
828
+ readonly mismatchedCircuitIds: AnyProvableCircuitId[];
829
+ /**
830
+ * Every circuit that failed to match, whatever the reason, grouped by condition: missing first,
831
+ * then keyless, then mismatched.
832
+ */
833
+ readonly circuitIds: AnyProvableCircuitId[];
834
+ /**
835
+ * Initializes a new {@link ContractTypeError}.
836
+ *
837
+ * @param contractState The deployed contract state that was checked, as bytes, of either era.
838
+ * Decode it with your own runtime of `error.contractState.era` to inspect it, for example
839
+ * `error.contractState.deserialize({ v9: ContractState })`.
840
+ * @param mismatch The circuits that failed to match, grouped by the condition that applied.
841
+ * @param contractAddress The address the state was read from, when known.
842
+ */
843
+ constructor(contractState: SerializedContractState, mismatch: ContractTypeMismatch, contractAddress?: ContractAddress | undefined);
844
+ }
845
+ /**
846
+ * An error indicating that a private state ID was specified for a call transaction while a private
847
+ * state provider was not. We want to let the user know so that they aren't under the impression the
848
+ * private state of a contract was updated when it wasn't.
849
+ */
850
+ declare class IncompleteCallTxPrivateStateConfig extends MidnightJsError {
851
+ readonly code: "MIDNIGHT_JS_C_INCOMPLETE_CALL_TX_PRIVATE_STATE_CONFIG";
852
+ readonly category: _midnightntwrk_midnight_js_utils.MidnightJsErrorCategory;
853
+ constructor();
854
+ }
855
+ /**
856
+ * An error indicating that a contract deploy named only one half of the private-state pairing:
857
+ * an initial private state with no private state ID to store it under, or a private state ID with
858
+ * no initial private state to store. The message names the missing half.
859
+ *
860
+ * Raised by `deployContract` (both eras) and `submitDeployTx`, before any provider is touched.
861
+ * It is the deploy member of the three-refusal family `IncompleteCallTxPrivateStateConfig` and
862
+ * {@link IncompleteFindContractPrivateStateConfig} belong to — one client-side rule per entry
863
+ * point, and client-side storage is era-independent.
864
+ */
865
+ declare class IncompleteDeployContractPrivateStateConfig extends MidnightJsError {
866
+ readonly code: "MIDNIGHT_JS_C_INCOMPLETE_DEPLOY_PRIVATE_STATE_CONFIG";
867
+ readonly category: _midnightntwrk_midnight_js_utils.MidnightJsErrorCategory;
868
+ constructor(missing?: 'privateStateId' | 'initialPrivateState');
869
+ }
870
+ /**
871
+ * An error indicating that an initial private state was specified for a contract find while a
872
+ * private state ID was not. We can't store the initial private state if we don't have a private state ID,
873
+ * and we need to let the user know that.
874
+ */
875
+ declare class IncompleteFindContractPrivateStateConfig extends MidnightJsError {
876
+ readonly code: "MIDNIGHT_JS_C_INCOMPLETE_FIND_PRIVATE_STATE_CONFIG";
877
+ readonly category: _midnightntwrk_midnight_js_utils.MidnightJsErrorCategory;
878
+ constructor();
879
+ }
880
+ /**
881
+ * An error indicating that a scoped transaction attempted to use cached states
882
+ * with a different contract address or private state ID than the one originally cached.
883
+ * This prevents silent state mismatches when batching calls to different contracts.
884
+ */
885
+ declare class ScopedTransactionIdentityMismatchError extends MidnightJsError {
886
+ readonly cached: {
887
+ contractAddress: string;
888
+ privateStateId?: PrivateStateId;
889
+ };
890
+ readonly requested: {
891
+ contractAddress: string;
892
+ privateStateId?: PrivateStateId;
893
+ };
894
+ readonly code: "MIDNIGHT_JS_C_SCOPED_TRANSACTION_IDENTITY_MISMATCH";
895
+ readonly category: _midnightntwrk_midnight_js_utils.MidnightJsErrorCategory;
896
+ constructor(cached: {
897
+ contractAddress: string;
898
+ privateStateId?: PrivateStateId;
899
+ }, requested: {
900
+ contractAddress: string;
901
+ privateStateId?: PrivateStateId;
902
+ });
903
+ }
904
+ /**
905
+ * An error indicating that a contract's on-chain entry point declares no verifier key at all.
906
+ *
907
+ * An absent key means that entry point was never deployed — the shape a constructor-built state
908
+ * has before a deploy fills it in — rather than a key that happens to be empty
909
+ * (`packages/protocol/docs/fail-closed-decoding.md`). There is nothing for a proof to be verified
910
+ * against, so the call is refused before any proving happens.
911
+ */
912
+ declare class BlankVerifierKeySlotError extends MidnightJsError {
913
+ readonly circuitId: string;
914
+ readonly code: "MIDNIGHT_JS_C_BLANK_VERIFIER_KEY_SLOT";
915
+ readonly category: _midnightntwrk_midnight_js_utils.MidnightJsErrorCategory;
916
+ /**
917
+ * @param circuitId The entry point whose slot is blank.
918
+ */
919
+ constructor(circuitId: string);
920
+ }
921
+ /**
922
+ * An error indicating that the verifier key compiled locally for a circuit does not byte-match the
923
+ * key registered on chain for that entry point.
924
+ *
925
+ * Raised BEFORE proving, which is the whole value of the check: a proof generated against a key the
926
+ * chain does not hold is rejected on submission, after the cost of generating it has been paid.
927
+ *
928
+ * This is also what catches a mis-dispatched operation — the wrong pipeline, or the wrong contract
929
+ * address — because either one shows up here as a key that does not match the slot.
930
+ *
931
+ * @see {@link VerificationPath} for what this check buys and what it cannot classify.
932
+ */
933
+ declare class VerifierKeyMismatchError extends MidnightJsError {
934
+ readonly circuitId: string;
935
+ readonly code: "MIDNIGHT_JS_C_VERIFIER_KEY_MISMATCH";
936
+ readonly category: _midnightntwrk_midnight_js_utils.MidnightJsErrorCategory;
937
+ /**
938
+ * @param circuitId The entry point whose key did not match.
939
+ */
940
+ constructor(circuitId: string);
941
+ }
942
+ /**
943
+ * An error indicating that the fetched contract state declares the same entry
944
+ * point NAME more than once, so which slot a call would dispatch on is
945
+ * ambiguous.
946
+ *
947
+ * Two byte entry points can decode to the same name. Picking the first match
948
+ * would let the pre-proving key check pass against one slot while the chain
949
+ * dispatches the proof on another, which is a paid-for proof rejected at
950
+ * submission — the exact late failure that check exists to prevent.
951
+ *
952
+ * It reports a chain state this package cannot act on, and there is no remediation a caller can apply
953
+ * beyond reporting it.
954
+ */
955
+ declare class Ledger8AmbiguousEntryPointError extends MidnightJsError {
956
+ readonly contractAddress: string;
957
+ readonly circuitId: string;
958
+ readonly matchCount: number;
959
+ readonly code: "MIDNIGHT_JS_C_LEDGER8_AMBIGUOUS_ENTRY_POINT";
960
+ readonly category: _midnightntwrk_midnight_js_utils.MidnightJsErrorCategory;
961
+ constructor(contractAddress: string, circuitId: string, matchCount: number);
962
+ }
963
+ /** Why a retained-era signing key could not be used. */
964
+ type Ledger8SigningKeyReason =
965
+ /** A key the caller supplied in this call is not one the retained era can sign with. */
966
+ 'unusable'
967
+ /** A maintenance update found no usable key held for the contract it targets. */
968
+ | 'unavailable';
969
+ /**
970
+ * An error indicating that a signing key is not usable by the retained era.
971
+ *
972
+ * `reason` is `'unusable'` when a key the caller supplied in this call - on a retained-era deploy, an
973
+ * attach, or an authority replacement - is not one the retained era can sign with. It is refused
974
+ * BEFORE anything is composed or stored. Stored unchecked, a key the read rejects is reported on the
975
+ * attach that supplied it and read as ABSENT on every later one, and the bad entry has by then
976
+ * already replaced whatever was held there. The caller can correct it, because the value came from
977
+ * the caller, in this call.
978
+ *
979
+ * `reason` is `'unavailable'` when a retained-era maintenance update found no signing key it can
980
+ * sign with for the contract it targets: nothing is stored for the address, the stored entry is not
981
+ * a retained-era key, or the store could not be read, in which case the read failure is on `cause`.
982
+ * Raised before anything is composed or proven. Unlike an attach, which reports an unusable entry as
983
+ * absent, a maintenance update cannot proceed without the key.
984
+ *
985
+ * The key is never rendered, and is not carried as a member: the caller already holds it, or has none.
986
+ */
987
+ declare class Ledger8SigningKeyError extends MidnightJsError {
988
+ readonly reason: Ledger8SigningKeyReason;
989
+ readonly contractAddress?: string | undefined;
990
+ readonly code: "MIDNIGHT_JS_C_LEDGER8_SIGNING_KEY";
991
+ readonly category: _midnightntwrk_midnight_js_utils.MidnightJsErrorCategory;
992
+ /**
993
+ * @param reason Which way the key could not be used. Also the discriminant a caller branches on.
994
+ * @param contractAddress The address the key was supplied for or looked up under. `undefined` for a
995
+ * deploy, which has no address until it is composed.
996
+ * @param options Carries the store's own failure on `cause`, when the entry could not be read at all.
997
+ */
998
+ constructor(reason: 'unusable', contractAddress?: string);
999
+ constructor(reason: 'unavailable', contractAddress: string, options?: ErrorOptions);
1000
+ }
1001
+ /** The retained-era operation a submitted transaction belongs to. */
1002
+ type Ledger8KeyedOperation = 'deploy' | 'replace-authority';
1003
+ /**
1004
+ * An error indicating that a retained-era transaction carrying a signing key was submitted, but what
1005
+ * the chain did with it could not be confirmed.
1006
+ *
1007
+ * `operation` `'deploy'`: covers the read surface rejecting, a record whose version tag is missing or
1008
+ * unrecognised, and a record arriving from an era the network this deployment composed on cannot have
1009
+ * recorded. DO NOT DEPLOY AGAIN on seeing this. The transaction may still finalize, this error holds
1010
+ * the only copy of the signing key, and the address has to be checked first. Reachable only AFTER
1011
+ * submission: every refusal ahead of it is raised with no key having been sampled.
1012
+ *
1013
+ * `operation` `'replace-authority'`: covers a submission rejected while the network was crossing the
1014
+ * fork (a {@link ForkCrossedDuringOperationError} or {@link SubmitRejectionUndiagnosedError} on
1015
+ * `cause`), the read surface rejecting, a record with no era tag, or a record from an era the network
1016
+ * cannot have recorded. The new key is NOT stored, because the replacement may not have landed - and
1017
+ * it may have, so this error carries it.
1018
+ *
1019
+ * Branch on `cause` for the underlying failure. It is wrapped rather than replaced, so a
1020
+ * `cause instanceof EraInvariantViolationError`, its method and its registered code stay reachable.
1021
+ *
1022
+ * {@link Ledger8UnconfirmedError.signingKey} is NAMED but never rendered into the message, and is
1023
+ * not enumerable.
1024
+ *
1025
+ * @see {@link ErrorTaxonomy} for why one class covers the whole window.
1026
+ */
1027
+ declare class Ledger8UnconfirmedError extends MidnightJsError {
1028
+ readonly operation: Ledger8KeyedOperation;
1029
+ readonly contractAddress: string;
1030
+ readonly code: "MIDNIGHT_JS_C_LEDGER8_UNCONFIRMED";
1031
+ readonly category: _midnightntwrk_midnight_js_utils.MidnightJsErrorCategory;
1032
+ readonly signingKey: SigningKey;
1033
+ /**
1034
+ * @param operation Which submitted operation could not be confirmed.
1035
+ * @param contractAddress The address the submitted deployment composed, or the contract whose
1036
+ * authority the replacement targets.
1037
+ * @param signingKey The key that deployment's maintenance authority was built from, or the key the
1038
+ * replacement would install. Sampled when the caller named none, and then this is its only copy.
1039
+ * @param cause Why the operation could not be confirmed.
1040
+ */
1041
+ constructor(operation: Ledger8KeyedOperation, contractAddress: string, signingKey: SigningKey, cause: unknown);
1042
+ }
1043
+ /** Which write the private-state provider refused. */
1044
+ type Ledger8NotStoredStage = 'signing-key' | 'private-state';
1045
+ /**
1046
+ * An error indicating that a retained-era operation was CONFIRMED on chain, but the private-state
1047
+ * provider refused to record it locally.
1048
+ *
1049
+ * `operation` `'deploy'`: distinct from {@link Ledger8UnconfirmedError}, which covers the window where
1050
+ * the chain's answer is unknown. Here the answer arrived and it was success, so the contract EXISTS
1051
+ * and its maintenance authority is built from this error's key. DO NOT DEPLOY AGAIN. `stage` says
1052
+ * which of the two writes the store refused.
1053
+ *
1054
+ * `operation` `'replace-authority'`: a maintenance authority REPLACEMENT was confirmed, and the store
1055
+ * refused the new key (`stage` is `'signing-key'`). The key held before no longer authorizes anything
1056
+ * on the contract, so this is the only copy of the one that does.
1057
+ *
1058
+ * {@link Ledger8NotStoredError.signingKey} is NAMED but never rendered into the message, and is
1059
+ * not enumerable.
1060
+ *
1061
+ * @see {@link ErrorTaxonomy} for the after-submission region this closes and why the key rides along
1062
+ * even where only one write can strand it.
1063
+ */
1064
+ declare class Ledger8NotStoredError extends MidnightJsError {
1065
+ readonly operation: Ledger8KeyedOperation;
1066
+ readonly contractAddress: string;
1067
+ readonly stage: Ledger8NotStoredStage;
1068
+ readonly code: "MIDNIGHT_JS_C_LEDGER8_NOT_STORED";
1069
+ readonly category: _midnightntwrk_midnight_js_utils.MidnightJsErrorCategory;
1070
+ readonly signingKey: SigningKey;
1071
+ /**
1072
+ * @param operation Which confirmed operation the store refused to record.
1073
+ * @param contractAddress The address the confirmed deployment created, or the contract whose
1074
+ * authority was replaced.
1075
+ * @param signingKey The key the contract's maintenance authority was built from, or the new
1076
+ * authority's key.
1077
+ * @param stage Which write the store refused. `'signing-key'` means this error holds the only copy
1078
+ * of the key; `'private-state'` means the key was already stored and the local state is what is
1079
+ * missing.
1080
+ * @param cause What the private-state provider rejected with.
1081
+ */
1082
+ constructor(operation: 'deploy', contractAddress: string, signingKey: SigningKey, stage: Ledger8NotStoredStage, cause: unknown);
1083
+ constructor(operation: 'replace-authority', contractAddress: string, signingKey: SigningKey, stage: 'signing-key', cause: unknown);
1084
+ }
1085
+ /** Why a retained-era call cannot be composed. */
1086
+ type Ledger8CallUnsupportedReason =
1087
+ /** The call would spend a shielded coin the contract already holds on chain. */
1088
+ 'shielded-spend'
1089
+ /** The call would pay a shielded coin to a recipient whose encryption public key cannot be resolved. */
1090
+ | 'unmappable-recipient';
1091
+ /**
1092
+ * An error indicating that a retained-era call cannot be composed, refused BEFORE the offer is built.
1093
+ *
1094
+ * `reason` `'shielded-spend'`: the call would spend a shielded coin the contract already holds on
1095
+ * chain, which this pipeline structurally cannot compose. A coin the same call produced is NOT
1096
+ * refused: it is paired with its own output as a transient and needs no chain state. Only spends of
1097
+ * previously held coins are.
1098
+ *
1099
+ * `reason` `'unmappable-recipient'`: the call would pay a shielded coin to a user-owned recipient
1100
+ * whose encryption public key it cannot resolve: not the calling wallet, not the burn address, and
1101
+ * not a key in the caller's `additionalCoinEncPublicKeyMappings`. Raised by a retained-era deploy
1102
+ * too, whose options carry no mappings, with `circuitId` set to `'initialState'`; the message then
1103
+ * names the constructor and gives the deploy-specific advice. Refusal rather than a best effort is the
1104
+ * only answer that cannot lose a coin: encrypting the output to the caller's own key would compose,
1105
+ * prove, balance and submit, and leave the recipient owning a coin it could never discover.
1106
+ *
1107
+ * @see {@link ErrorTaxonomy} for what the retained-era path is missing and why this refuses before
1108
+ * the offer is built.
1109
+ * @see {@link KeepStatePipeline} for how the retained-era path resolves each recipient's encryption key.
1110
+ */
1111
+ declare class Ledger8CallUnsupportedError extends MidnightJsError {
1112
+ readonly reason: Ledger8CallUnsupportedReason;
1113
+ readonly circuitId: string;
1114
+ readonly recipientCoinPublicKey?: string | undefined;
1115
+ readonly code: "MIDNIGHT_JS_C_LEDGER8_CALL_UNSUPPORTED";
1116
+ readonly category: _midnightntwrk_midnight_js_utils.MidnightJsErrorCategory;
1117
+ /**
1118
+ * @param reason Why the call was refused. Also the discriminant a caller branches on.
1119
+ * @param circuitId The circuit whose call was refused, or `'initialState'` for a deploy.
1120
+ * @param recipientCoinPublicKey The recipient that could not be resolved. Set for
1121
+ * `'unmappable-recipient'`.
1122
+ */
1123
+ constructor(reason: 'shielded-spend', circuitId: string);
1124
+ constructor(reason: 'unmappable-recipient', circuitId: string, recipientCoinPublicKey: string);
1125
+ }
1126
+
1127
+ /**
1128
+ * Configuration for {@link submitTx}.
1129
+ */
1130
+ interface SubmitTxOptions<PCK extends AnyProvableCircuitId> {
1131
+ /**
1132
+ * The transaction to prove, balance, and submit. The handle carries the ledger era that wrote
1133
+ * it; make one with `LedgerTransaction.seal`.
1134
+ */
1135
+ readonly unprovenTx: UnprovenTx;
1136
+ /**
1137
+ * A circuit identifier to use to fetch the ZK artifacts needed to prove the
1138
+ * transaction. Only defined if a call transaction is being submitted.
1139
+ *
1140
+ * @remarks
1141
+ * Where a transaction involves multiple circuits (e.g., when circuit calls are scoped to a transaction
1142
+ * context), this may be an array of circuit IDs.
1143
+ */
1144
+ readonly circuitId?: PCK | PCK[];
1145
+ }
1146
+ /**
1147
+ * Providers required to submit a ledger 9 transaction. Submission doesn't manipulate private state,
1148
+ * so the private state provider can be omitted.
1149
+ */
1150
+ type Ledger9SubmitTxProviders<C extends Contract.Any, PCK extends Contract.ProvableCircuitId<C>> = Omit<Ledger9ContractProviders<C, PCK>, 'privateStateProvider'>;
1151
+ /**
1152
+ * Proves, balances, and submits an unproven deployment or call transaction using
1153
+ * the given providers, according to the given options.
1154
+ *
1155
+ * ## Which era it runs on
1156
+ *
1157
+ * It reads the network's ledger version once and runs on that era. The handle's `era` must match it:
1158
+ *
1159
+ * | input | network | what happens |
1160
+ * |---|---|---|
1161
+ * | v9 | v9 | proved, balanced and submitted as v9 handles |
1162
+ * | v8 | v8 | proved, balanced and submitted as v8 handles |
1163
+ * | v8 | v9 | refused with `EraMismatchError` before proving: the v9 ledger cannot read a v8 transaction |
1164
+ * | v9 | v8 | refused with `EraMismatchError` before proving |
1165
+ *
1166
+ * The head is read before proving. If the node rejects the submission, the head is read once more:
1167
+ * when the network crossed the hard fork in between, the rejection arrives as
1168
+ * `ForkCrossedDuringOperationError` (kind `'transaction'`); verify the transaction did not finalize,
1169
+ * then build it again for the new era. A failure while proving or balancing reads nothing again.
1170
+ *
1171
+ * ## Blocking Behavior
1172
+ *
1173
+ * This method **waits indefinitely** for the transaction to appear on the blockchain via
1174
+ * `providers.publicDataProvider.watchForTxData(txId)`. It will not return until:
1175
+ * - The transaction is successfully included in the blockchain, OR
1176
+ * - An error occurs during proving, balancing, or submission
1177
+ *
1178
+ * ## Conditions When Transaction May Not Appear
1179
+ *
1180
+ * A submitted transaction may fail to appear on-chain if:
1181
+ * - Transaction is invalid in ways not detected during local validation
1182
+ * - Network issues prevent propagation to validators
1183
+ * - Transaction is rejected by validator consensus
1184
+ * - Insufficient fees or resources
1185
+ * - Contract state has changed making the transaction invalid
1186
+ *
1187
+ * ## Implications of Aborting This Method
1188
+ *
1189
+ * If the application terminates this method before it returns:
1190
+ * - Transaction may still be pending/processing on-chain
1191
+ * - **Private state updates are NOT stored** (even if transaction later succeeds on-chain)
1192
+ * - **Signing keys are NOT updated** (for deploy/replace authority transactions)
1193
+ * - Application state will be out of sync with blockchain state
1194
+ * - Manual recovery may be required to reconcile state
1195
+ *
1196
+ * **Recommendation**: Use {@link submitTxAsync} for non-blocking submission with manual
1197
+ * finalization handling and timeout control.
1198
+ *
1199
+ * @param providers The providers used to manage the transaction lifecycle.
1200
+ * @param options Configuration.
1201
+ *
1202
+ * @returns A promise that resolves with the finalized transaction data, tagged with the era of
1203
+ * the head it ran on, or rejects if an error occurs along the way.
1204
+ * @throws InvalidTransactionHandleError if `unprovenTx` is not an unproven handle of this package,
1205
+ * before the head is read.
1206
+ * @throws EraMismatchError for a transaction whose era is not the head's.
1207
+ * @throws ProviderFailedError if a provider rejects, with its failure sanitized onto `cause`. A
1208
+ * rejected submission arrives as this error only when the head has not moved.
1209
+ * @throws ForkCrossedDuringOperationError if the node rejects the submission and the head now
1210
+ * reports a later era.
1211
+ * @throws SubmitRejectionUndiagnosedError if the node rejects the submission and the head cannot be
1212
+ * read again, or reports an earlier era.
1213
+ * @throws EraInvariantViolationError if a provider answers in the other era, or the record's era
1214
+ * differs from the head's. In the record's case the
1215
+ * transaction is already on chain; its id is on `txId`.
1216
+ */
1217
+ declare function submitTx<PCK extends AnyProvableCircuitId>(providers: Omit<MidnightProviders<PCK>, 'privateStateProvider'>, options: SubmitTxOptions<PCK>): Promise<FinalizedTxRead>;
1218
+ /**
1219
+ * Proves, balances, and submits an unproven deployment or call transaction using
1220
+ * the given providers, according to the given options. Unlike {@link submitTx},
1221
+ * this function returns immediately after submission without waiting for finalization.
1222
+ * It reads the head and routes on it exactly as {@link submitTx} does.
1223
+ *
1224
+ * @param providers The providers used to manage the transaction lifecycle.
1225
+ * @param options Configuration.
1226
+ *
1227
+ * @returns A promise that resolves with the transaction ID immediately after submission,
1228
+ * or rejects if an error occurs during preparation or submission.
1229
+ * To watch for finalization, use providers.publicDataProvider.watchForTxData(txId).
1230
+ * @throws InvalidTransactionHandleError if `unprovenTx` is not an unproven handle of this package,
1231
+ * before the head is read.
1232
+ * @throws EraMismatchError for a transaction whose era is not the head's.
1233
+ * @throws ProviderFailedError if a provider rejects, with its failure sanitized onto `cause`. A
1234
+ * rejected submission arrives as this error only when the head has not moved.
1235
+ * @throws ForkCrossedDuringOperationError if the node rejects the submission and the head now
1236
+ * reports a later era.
1237
+ * @throws SubmitRejectionUndiagnosedError if the node rejects the submission and the head cannot be
1238
+ * read again, or reports an earlier era.
1239
+ */
1240
+ declare function submitTxAsync<PCK extends AnyProvableCircuitId>(providers: Omit<MidnightProviders<PCK>, 'privateStateProvider'>, options: SubmitTxOptions<PCK>): Promise<string>;
1241
+
1242
+ /**
1243
+ * Data relevant to any unsubmitted transaction.
1244
+ *
1245
+ * @remarks
1246
+ * **Privacy-sensitive type.** Every field on this type is private: the
1247
+ * `unprovenTx` field carries the unproven transaction that the underlying
1248
+ * zero-knowledge proofs were designed to keep confidential, and `newCoins`
1249
+ * includes shielded coin material that must not leak.
1250
+ *
1251
+ * Application code must not log, serialize, or transmit instances of this
1252
+ * type. The framework deliberately exposes these references to support
1253
+ * retry, replay, debug, and redacted-telemetry workflows that require
1254
+ * access to the underlying transaction structure — raw transmission to
1255
+ * observability platforms (log shippers, error reporters, analytics) is
1256
+ * not an intended use.
1257
+ */
1258
+ interface Ledger9UnsubmittedTxData extends UnsubmittedTxDataBase {
1259
+ /**
1260
+ * The unproven transaction produced, as a v9 handle. Read it with your own
1261
+ * ledger copy: `unprovenTx.deserialize({ v9: Transaction })`.
1262
+ */
1263
+ readonly unprovenTx: LedgerTransaction<'Unproven', 'v9'>;
1264
+ }
1265
+ /**
1266
+ * Base type for public data relevant to an unsubmitted deployment transaction.
1267
+ */
1268
+ interface Ledger9UnsubmittedDeployTxPublicData {
1269
+ /**
1270
+ * The ledger address of the contract that was deployed.
1271
+ */
1272
+ readonly contractAddress: ContractAddress;
1273
+ /**
1274
+ * The initial public state of the contract deployed to the blockchain, as bytes. Decode it with
1275
+ * your own runtime: `initialContractState.deserialize({ v9: ContractState })`.
1276
+ */
1277
+ readonly initialContractState: SerializedContractState<'v9'>;
1278
+ }
1279
+ /**
1280
+ * Base type for private data relevant to an unsubmitted deployment transaction.
1281
+ *
1282
+ * @remarks
1283
+ * **Privacy-sensitive type.** The `signingKey` field carries the contract's
1284
+ * maintenance authority, and `initialPrivateState` carries application-defined
1285
+ * private state that the zero-knowledge proofs were designed to keep
1286
+ * confidential. Every field on this type is private.
1287
+ *
1288
+ * Application code must not log, serialize, or transmit instances of this
1289
+ * type. If a non-sensitive identifier derived from the deployment is needed,
1290
+ * compute it explicitly outside this type rather than passing the whole
1291
+ * object across a trust boundary.
1292
+ */
1293
+ interface Ledger9UnsubmittedDeployTxPrivateData<C extends Contract$1.Any> {
1294
+ /**
1295
+ * The signing key that was added as the deployed contract's maintenance authority.
1296
+ */
1297
+ readonly signingKey: SigningKey;
1298
+ /**
1299
+ * The initial private state of the contract deployed to the blockchain. This
1300
+ * value is persisted if the transaction succeeds.
1301
+ */
1302
+ readonly initialPrivateState: Contract$1.PrivateState<C>;
1303
+ }
1304
+ /**
1305
+ * Base type for data relevant to an unsubmitted deployment transaction.
1306
+ *
1307
+ * @remarks
1308
+ * **Privacy-sensitive type.** Transitively contains
1309
+ * {@link Ledger9UnsubmittedDeployTxPrivateData} via the `private` field (signing key
1310
+ * and initial private state). When logging, serializing, or transmitting,
1311
+ * read only the `public` field or destructure specific non-sensitive fields
1312
+ * — never spread or stringify the whole object.
1313
+ */
1314
+ interface Ledger9UnsubmittedDeployTxDataBase<C extends Contract$1.Any> {
1315
+ /**
1316
+ * The pipeline that produced this result: always ledger 9 here.
1317
+ *
1318
+ * Read off the compiled artifact, NEVER off a transaction record — the two
1319
+ * facts disagree after the fork, and only this one says which module the
1320
+ * objects in this result came from.
1321
+ */
1322
+ readonly era: 'v9';
1323
+ /**
1324
+ * The public data (data that will be revealed upon tx submission) relevant to the deployment transaction.
1325
+ */
1326
+ readonly public: Ledger9UnsubmittedDeployTxPublicData;
1327
+ /**
1328
+ * The private data (data that will not be revealed upon tx submission) relevant to the deployment transaction.
1329
+ */
1330
+ readonly private: Ledger9UnsubmittedDeployTxPrivateData<C>;
1331
+ }
1332
+ /**
1333
+ * Data for an unsubmitted deployment transaction.
1334
+ *
1335
+ * @remarks
1336
+ * **Privacy-sensitive type.** Extends {@link Ledger9UnsubmittedDeployTxDataBase} and
1337
+ * further embeds {@link Ledger9UnsubmittedTxData} (carrying the
1338
+ * unproven transaction) plus the contract constructor's
1339
+ * `initialZswapState` under the `private` field. When logging, serializing,
1340
+ * or transmitting, read only the `public` field or destructure specific
1341
+ * non-sensitive fields — never spread or stringify the whole object.
1342
+ */
1343
+ /**
1344
+ * The private data of an unsubmitted deployment transaction: the deploy-specific
1345
+ * private data ({@link Ledger9UnsubmittedDeployTxPrivateData}) combined with the
1346
+ * unproven transaction data ({@link Ledger9UnsubmittedTxData}) and the Zswap state
1347
+ * produced by running the contract constructor.
1348
+ */
1349
+ interface Ledger9UnsubmittedDeployTxPrivateDataFull<C extends Contract$1.Any> extends Ledger9UnsubmittedDeployTxPrivateData<C>, Ledger9UnsubmittedTxData {
1350
+ /**
1351
+ * The Zswap state produced as a result of running the contract constructor. Useful for when
1352
+ * inputs or outputs are created in the contract constructor.
1353
+ */
1354
+ readonly initialZswapState: ZswapLocalState;
1355
+ }
1356
+ interface Ledger9UnsubmittedDeployTxData<C extends Contract$1.Any> extends Ledger9UnsubmittedDeployTxDataBase<C> {
1357
+ /**
1358
+ * The data of this transaction that is only visible on the user device.
1359
+ */
1360
+ readonly private: Ledger9UnsubmittedDeployTxPrivateDataFull<C>;
1361
+ }
1362
+ /**
1363
+ * Data for a finalized deploy transaction submitted in this process.
1364
+ *
1365
+ * @remarks
1366
+ * **Privacy-sensitive type.** Inherits {@link Ledger9UnsubmittedDeployTxDataBase}'s
1367
+ * `private` field (signing key, initial private state). Treat as confidential
1368
+ * when logging, serializing, or transmitting — destructure only the
1369
+ * non-sensitive fields (`public.txId`, `public.blockHeight`, etc.) rather
1370
+ * than spreading or stringifying the whole object.
1371
+ */
1372
+ /**
1373
+ * The public data of a finalized deployment transaction: the deploy-specific
1374
+ * public data ({@link Ledger9UnsubmittedDeployTxPublicData}) combined with the
1375
+ * finalized transaction data ({@link Ledger9FinalizedTxData}).
1376
+ */
1377
+ interface Ledger9FinalizedDeployTxPublicData extends Ledger9UnsubmittedDeployTxPublicData, Ledger9FinalizedTxData {
1378
+ }
1379
+ interface Ledger9FinalizedDeployTxDataBase<C extends Contract$1.Any> extends Ledger9UnsubmittedDeployTxDataBase<C> {
1380
+ /**
1381
+ * The data of this transaction that is visible on the blockchain.
1382
+ */
1383
+ readonly public: Ledger9FinalizedDeployTxPublicData;
1384
+ }
1385
+ /**
1386
+ * The public data of a deployment found on chain whose deploy transaction was
1387
+ * recorded by the ledger-8 runtime, i.e. a contract deployed before the ledger fork.
1388
+ *
1389
+ * @remarks Unlike the other `Ledger8*` types, it outlives the retained pipeline:
1390
+ * it is part of `Ledger9FoundDeployTxData`.
1391
+ *
1392
+ * @see {@link ErrorTaxonomy} for how the `Ledger8` names are used.
1393
+ */
1394
+ interface Ledger8FoundDeployTxPublicData extends Ledger8FinalizedTxData {
1395
+ /**
1396
+ * The ledger address of the contract that was deployed.
1397
+ */
1398
+ readonly contractAddress: ContractAddress;
1399
+ /**
1400
+ * The deploy-time state of the contract, as `queryDeployContractState` serves it. Its `era` names
1401
+ * the ledger that wrote these bytes, which can differ from the era of the deploy record. Decode it
1402
+ * with your own runtime of that era.
1403
+ */
1404
+ readonly initialContractState: SerializedContractState;
1405
+ }
1406
+ /**
1407
+ * The public data of a deployment found on chain, discriminated by the ledger
1408
+ * era that recorded the deploy transaction. Narrow on `era` before reading
1409
+ * `tx`. `contractAddress` and `initialContractState` are present on both
1410
+ * variants; the era of `initialContractState` is its own, read it from the state.
1411
+ */
1412
+ type FoundDeployTxPublicData = Ledger8FoundDeployTxPublicData | Ledger9FinalizedDeployTxPublicData;
1413
+ /**
1414
+ * What a contract maintenance update -- a verifier key inserted or removed, or the maintenance
1415
+ * authority replaced -- resolves with once the chain has recorded it.
1416
+ *
1417
+ * Nested like every other `contracts` result, so `era` names the pipeline and `public` carries the
1418
+ * record. The retained era's counterpart is `Ledger8FinalizedMaintenanceTxData`; the two together
1419
+ * are `FinalizedMaintenanceTxData`.
1420
+ */
1421
+ interface Ledger9FinalizedMaintenanceTxData {
1422
+ /** The pipeline that produced this result: always ledger 9 here. */
1423
+ readonly era: 'v9';
1424
+ /** The finalized record of the maintenance transaction. */
1425
+ readonly public: Ledger9FinalizedTxData;
1426
+ }
1427
+ /**
1428
+ * Data for a deployment found on chain by `findDeployedContract`.
1429
+ *
1430
+ * @remarks
1431
+ * **Privacy-sensitive type.** The `private` field carries the signing key and
1432
+ * the initial private state. When logging, serializing, or transmitting, read
1433
+ * only the `public` field or destructure specific non-sensitive fields.
1434
+ */
1435
+ interface Ledger9FoundDeployTxData<C extends Contract$1.Any> {
1436
+ /**
1437
+ * The pipeline this handle runs on: always ledger 9 here. The era that
1438
+ * recorded the deploy transaction is `public.era`.
1439
+ */
1440
+ readonly era: 'v9';
1441
+ /**
1442
+ * The data of the deploy transaction that is visible on the blockchain.
1443
+ */
1444
+ readonly public: FoundDeployTxPublicData;
1445
+ /**
1446
+ * The private data stored for this contract on this device.
1447
+ */
1448
+ readonly private: Ledger9UnsubmittedDeployTxPrivateData<C>;
1449
+ }
1450
+ /**
1451
+ * Data for a finalized deploy transaction submitted in this process.
1452
+ *
1453
+ * @remarks
1454
+ * **Privacy-sensitive type.** Inherits {@link Ledger9UnsubmittedDeployTxData}'s
1455
+ * `private` field, which transitively carries the unproven transaction,
1456
+ * `newCoins`, signing key, initial private state, and `initialZswapState`.
1457
+ * Treat as confidential when logging, serializing, or transmitting —
1458
+ * destructure only the non-sensitive fields (`public.txId`,
1459
+ * `public.blockHeight`, etc.) rather than spreading or stringifying the whole
1460
+ * object.
1461
+ *
1462
+ * The framework deliberately exposes these references to support retry,
1463
+ * replay, debug, and redacted-telemetry workflows — raw transmission to
1464
+ * observability platforms (log shippers, error reporters, analytics) is
1465
+ * not an intended use.
1466
+ */
1467
+ interface Ledger9FinalizedDeployTxData<C extends Contract$1.Any> extends Ledger9UnsubmittedDeployTxData<C> {
1468
+ /**
1469
+ * The data of this transaction that is visible on the blockchain.
1470
+ */
1471
+ readonly public: Ledger9FinalizedDeployTxPublicData;
1472
+ }
1473
+ /**
1474
+ * Data for an unsubmitted call transaction.
1475
+ *
1476
+ * @remarks
1477
+ * **Privacy-sensitive type.** Intersects {@link Ledger9CallResult} (whose `private`
1478
+ * field exposes ZK inputs/outputs, the private transcript outputs, and the
1479
+ * next private state) with an additional {@link Ledger9UnsubmittedTxData} under
1480
+ * `private` (carrying the unproven transaction and new shielded
1481
+ * coins). Treat as confidential when logging, serializing, or transmitting —
1482
+ * destructure specific non-sensitive fields rather than spreading or
1483
+ * stringifying the whole object.
1484
+ */
1485
+ /**
1486
+ * The private data of an unsubmitted call transaction: the circuit execution's
1487
+ * private result ({@link Ledger9CallResultPrivate}) combined with the unproven
1488
+ * transaction data ({@link Ledger9UnsubmittedTxData}).
1489
+ */
1490
+ interface Ledger9UnsubmittedCallTxPrivateData<C extends Contract$1.Any, PCK extends Contract$1.ProvableCircuitId<C>> extends Ledger9CallResultPrivate<C, PCK>, Ledger9UnsubmittedTxData {
1491
+ }
1492
+ interface Ledger9UnsubmittedCallTxData<C extends Contract$1.Any, PCK extends Contract$1.ProvableCircuitId<C>> extends Ledger9CallResult<C, PCK> {
1493
+ /**
1494
+ * Private data relevant to this call transaction.
1495
+ */
1496
+ readonly private: Ledger9UnsubmittedCallTxPrivateData<C, PCK>;
1497
+ }
1498
+ /**
1499
+ * Data for a submitted, finalized call transaction.
1500
+ *
1501
+ * @remarks
1502
+ * **Privacy-sensitive type.** Inherits {@link Ledger9UnsubmittedCallTxData}'s
1503
+ * `private` field, which transitively carries the unproven transaction,
1504
+ * new shielded coins, ZK inputs/outputs, the private transcript outputs, and
1505
+ * the next private state. Treat as confidential when logging, serializing, or
1506
+ * transmitting — destructure only the non-sensitive fields (`public.txId`,
1507
+ * `public.blockHeight`, etc.) rather than spreading or stringifying the whole
1508
+ * object.
1509
+ *
1510
+ * The framework deliberately exposes these references to support retry,
1511
+ * replay, debug, and redacted-telemetry workflows — raw transmission to
1512
+ * observability platforms (log shippers, error reporters, analytics) is
1513
+ * not an intended use.
1514
+ */
1515
+ /**
1516
+ * The public data of a finalized call transaction: the circuit execution's
1517
+ * public result ({@link Ledger9CallResultPublic}) combined with the finalized
1518
+ * transaction data ({@link Ledger9FinalizedTxData}).
1519
+ */
1520
+ interface Ledger9FinalizedCallTxPublicData extends Ledger9CallResultPublic, Ledger9FinalizedTxData {
1521
+ }
1522
+ interface Ledger9FinalizedCallTxData<C extends Contract$1.Any, PCK extends Contract$1.ProvableCircuitId<C>> extends Ledger9UnsubmittedCallTxData<C, PCK> {
1523
+ /**
1524
+ * The circuit whose call this result describes.
1525
+ *
1526
+ * On the result itself rather than only in the caller's own variables: a
1527
+ * handler that receives a finalized result -- from a queue, a retry, a
1528
+ * batch -- has the execution data and no way back to the options that
1529
+ * produced it. Both eras carry it.
1530
+ *
1531
+ * In a scope that made several calls this names the LAST one, which is the
1532
+ * call `public`, `private` and `calls` also describe: this type is one
1533
+ * call's result, not the transaction's. The transaction may carry more, and
1534
+ * a failure reports all of them -- `TxFailedError`'s `circuitId` is the
1535
+ * accumulated list. The two are answering different questions, and a caller
1536
+ * routing on this one is routing on the call, not the transaction.
1537
+ *
1538
+ * Typed as the contract's whole circuit-id union, NOT as `PCK`, and that is
1539
+ * load-bearing. This type is reachable through `Ledger9TransactionContext[Submit]`,
1540
+ * so naming `PCK` in a property position makes the context invariant in
1541
+ * `PCK`. A scope is legitimately typed with the union --
1542
+ * `withContractScopedTransaction<C>` defaults it that way -- while the calls
1543
+ * made inside it name one circuit each, and invariance refuses exactly that
1544
+ * pairing. `Ledger9SubmittedCallTx` has no scope on its path and names `PCK`
1545
+ * precisely.
1546
+ *
1547
+ * What catches a regression here is `testkit-js-e2e`'s scoped-transaction
1548
+ * test, through the repo-wide `typecheck:tests`. NOT an assertion in this
1549
+ * package: reproducing the failure needs a contract whose circuits differ in
1550
+ * arity, and every era-9 fixture here declares exactly one no-argument
1551
+ * circuit, so an in-package assertion passes whichever way this member is
1552
+ * typed. Do not add one and take it for a gate.
1553
+ */
1554
+ readonly circuitId: Contract$1.ProvableCircuitId<C>;
1555
+ /**
1556
+ * Public data relevant to this call transaction.
1557
+ */
1558
+ readonly public: Ledger9FinalizedCallTxPublicData;
1559
+ }
1560
+ /**
1561
+ * Data returned from an asynchronous call transaction submission.
1562
+ * Contains the transaction ID and call transaction data without waiting for finalization.
1563
+ *
1564
+ * @remarks
1565
+ * **Privacy-sensitive type.** The `callTxData` field carries
1566
+ * {@link Ledger9UnsubmittedCallTxData} and transitively the unproven transaction
1567
+ * and the call's private state. Treat as confidential when logging,
1568
+ * serializing, or transmitting — read only `txId` or destructure specific
1569
+ * non-sensitive fields rather than spreading or stringifying the whole
1570
+ * object.
1571
+ */
1572
+ interface Ledger9SubmittedCallTx<C extends Contract$1.Any, PCK extends Contract$1.ProvableCircuitId<C>> extends SubmittedCallTxBase<Ledger9UnsubmittedCallTxData<C, PCK>> {
1573
+ /** See {@link Ledger9FinalizedCallTxData.circuitId}. */
1574
+ readonly circuitId: PCK;
1575
+ /**
1576
+ * The pipeline that produced this result: always ledger 9 here.
1577
+ *
1578
+ * Read off the compiled artifact, NEVER off a transaction record — the two
1579
+ * facts disagree after the fork, and only this one says which module the
1580
+ * objects in this result came from.
1581
+ */
1582
+ readonly era: 'v9';
1583
+ }
1584
+
1585
+ /**
1586
+ * What an operator can see about which ledger era a value or an operation
1587
+ * belongs to.
1588
+ *
1589
+ * Four decisions get a breadcrumb, at DEBUG level, as STRUCTURED fields rather
1590
+ * than interpolated prose.
1591
+ *
1592
+ * EVERY head read in this package is breadcrumbed, and there are four. A new
1593
+ * head read has to add a {@link HeadReadingProvenance} member.
1594
+ *
1595
+ * PRIVACY: a breadcrumb may carry version integers, era names, decision names
1596
+ * and a contract address. It must NEVER carry key bytes, decoded contract
1597
+ * state, private state or a raw transaction payload — which is why every field
1598
+ * below is a bounded string literal or a number, and why the emitters take
1599
+ * individual facts rather than an options bag.
1600
+ * `src/test/breadcrumbs.test.ts` asserts it over the serialized breadcrumb.
1601
+ *
1602
+ * @see {@link Breadcrumbs} for the four readings, what each breadcrumb carries,
1603
+ * and what is deliberately not recorded.
1604
+ */
1605
+
1606
+ /**
1607
+ * The fixed message every breadcrumb is written under.
1608
+ *
1609
+ * Nothing is interpolated into it, so the fields stay the only thing an
1610
+ * operator has to read and an aggregator can group the three decisions without
1611
+ * parsing prose.
1612
+ */
1613
+ declare const DISPATCH_BREADCRUMB_MESSAGE = "contract era dispatch decision";
1614
+
1615
+ /**
1616
+ * Where a call's next private state is stored once the call succeeds.
1617
+ *
1618
+ * @internal
1619
+ */
1620
+ interface PrivateStateTarget {
1621
+ readonly contractAddress: ContractAddress$1;
1622
+ readonly privateStateId: PrivateStateId;
1623
+ }
1624
+ /** @internal */
1625
+ declare const Submit: unique symbol;
1626
+ /** @internal */
1627
+ declare const MergeUnsubmittedCallTxData: unique symbol;
1628
+ /** @internal The ledger era a scope context composes for. */
1629
+ declare const ScopeEra: unique symbol;
1630
+
1631
+ declare const TypeId: unique symbol;
1632
+ type TypeId = typeof TypeId;
1633
+ /**
1634
+ * Encapsulates the context for managing a scoped contract transaction.
1635
+ */
1636
+ interface Ledger9TransactionContext<C extends Contract.Any, PCK extends Contract.ProvableCircuitId<C> = Contract.ProvableCircuitId<C>> {
1637
+ readonly [TypeId]: TypeId;
1638
+ readonly [ScopeEra]: 'v9';
1639
+ readonly [Submit]: () => Promise<Ledger9FinalizedCallTxData<C, PCK>>;
1640
+ readonly [MergeUnsubmittedCallTxData]: (circuitId: PCK, callData: Ledger9UnsubmittedCallTxData<C, PCK>, privateStateTarget?: PrivateStateTarget) => void;
1641
+ /**
1642
+ * Gets the additional scoped {@link CoinPublicKey} to {@link EncPublicKey} mappings.
1643
+ *
1644
+ * @return A `ReadonlyMap`<{@link CoinPublicKey}, {@link EncPublicKey}> instance, or `undefined` if no additional
1645
+ * mappings were specified for the current transaction context.
1646
+ */
1647
+ getAdditionalMappings(): ReadonlyMap<CoinPublicKey$1, EncPublicKey> | undefined;
1648
+ /**
1649
+ * Gets the public states of the contract within the transaction context, as bytes. Decode them with
1650
+ * your own runtime, as with `getStates`: `states.contractState.deserialize({ v9: ContractState })`.
1651
+ *
1652
+ * @return The public states, or `undefined` if circuit calls are yet to be made.
1653
+ *
1654
+ * @remarks
1655
+ * The contract state is the unsubmitted _running_ state of the contract within the transaction context,
1656
+ * reflecting any unsubmitted circuit calls made to the contract during the scope of the transaction. The
1657
+ * ledger parameters and the zswap chain state are those of the block the scope was first read at. The
1658
+ * running private state is `getLastUnsubmittedCallTxDataToTransact()?.[0].private.nextPrivateState`.
1659
+ */
1660
+ getCurrentStates(): PublicStatesRead | undefined;
1661
+ /**
1662
+ * Gets the last unsubmitted call transaction data.
1663
+ *
1664
+ * @return A tuple containing an {@link Ledger9UnsubmittedCallTxData} instance, and an optional private state
1665
+ * ID, or `undefined` if circuit calls are yet to be made.
1666
+ */
1667
+ getLastUnsubmittedCallTxDataToTransact(): [Ledger9UnsubmittedCallTxData<C, PCK>, PrivateStateId?] | undefined;
1668
+ }
1669
+ /**
1670
+ * Encapsulates the context of a contract-scoped transaction on a ledger 8 (pre-fork) network.
1671
+ *
1672
+ * Every call added with `submitCallTx` or `callTx.<circuit>` is composed against the states the
1673
+ * scope's last call ended on, and all of them are submitted as one ledger 8 transaction when the
1674
+ * scope's function returns. `createUnprovenCallTx` builds against the same states and adds nothing.
1675
+ */
1676
+ interface Ledger8TransactionContext<C extends Ledger8Contract, PCK extends Ledger8CircuitId<C> = Ledger8CircuitId<C>> {
1677
+ readonly [TypeId]: TypeId;
1678
+ readonly [ScopeEra]: 'v8';
1679
+ /**
1680
+ * Gets the additional scoped {@link CoinPublicKey} to {@link EncPublicKey} mappings.
1681
+ *
1682
+ * @return A `ReadonlyMap`<{@link CoinPublicKey}, {@link EncPublicKey}> instance, or `undefined` if no additional
1683
+ * mappings were specified for the current transaction context.
1684
+ */
1685
+ getAdditionalMappings(): ReadonlyMap<CoinPublicKey$1, EncPublicKey> | undefined;
1686
+ /**
1687
+ * Gets the last unsubmitted call transaction data.
1688
+ *
1689
+ * @return A tuple containing an {@link Ledger8UnsubmittedCallTxData} instance, and an optional private state
1690
+ * ID, or `undefined` if circuit calls are yet to be made. The running private state is
1691
+ * `getLastUnsubmittedCallTxDataToTransact()?.[0].private.nextPrivateState`.
1692
+ */
1693
+ getLastUnsubmittedCallTxDataToTransact(): [Ledger8UnsubmittedCallTxData<C, PCK>, PrivateStateId?] | undefined;
1694
+ }
1695
+ /** A {@link Ledger8TransactionContext} of any ledger 8 contract. */
1696
+ type AnyLedger8TransactionContext = Ledger8TransactionContext<Ledger8Contract, Ledger8CircuitId<Ledger8Contract>>;
1697
+ /**
1698
+ * Options for use when creating scoped transactions.
1699
+ */
1700
+ interface ScopedTransactionOptions {
1701
+ /**
1702
+ * An optional name for the transaction scope.
1703
+ */
1704
+ readonly scopeName?: string;
1705
+ /**
1706
+ * An optional mapping of {@link CoinPublicKey} to {@link EncPublicKey} that can be used to resolve encryption
1707
+ * keys for coins created during circuit execution.
1708
+ */
1709
+ readonly additionalCoinEncPublicKeyMappings?: ReadonlyMap<CoinPublicKey$1, EncPublicKey>;
1710
+ }
1711
+ /**
1712
+ * Type guard to determine if a value is a Ledger9TransactionContext.
1713
+ *
1714
+ * @param u The value to check.
1715
+ * @returns `true` if `u` is a {@link Ledger9TransactionContext}, otherwise `false`.
1716
+ */
1717
+ declare const isLedger9TransactionContext: (u: unknown) => u is Ledger9TransactionContext<Contract.Any>;
1718
+ /**
1719
+ * Type guard to determine if a value is a Ledger8TransactionContext.
1720
+ *
1721
+ * @param u The value to check.
1722
+ * @returns `true` if `u` is a {@link Ledger8TransactionContext}, otherwise `false`.
1723
+ */
1724
+ declare const isLedger8TransactionContext: (u: unknown) => u is AnyLedger8TransactionContext;
1725
+ /**
1726
+ * Executes a function within the context of a contract-scoped transaction, on the ledger era the
1727
+ * network head is on: a ledger 8 head runs {@link withLedger8ContractScopedTransaction}, a ledger 9 head
1728
+ * {@link withLedger9ContractScopedTransaction}.
1729
+ *
1730
+ * @param providers The contract providers to use within the transaction.
1731
+ * @param fn The function to execute within the transaction context.
1732
+ * @param options Optional transaction scope options.
1733
+ * @returns A `Promise` that resolves with the finalized transaction data of the single transaction
1734
+ * created for all circuit calls made within `fn`.
1735
+ *
1736
+ * @remarks
1737
+ * Where `fn` makes circuit calls, these are batched together and submitted as a single transaction when
1738
+ * the function completes successfully. If `fn` throws an error, any unsubmitted circuit calls are discarded.
1739
+ *
1740
+ * The ledger era this scope runs against is read ONCE, before `fn` runs, and every call merged into
1741
+ * the scope shares that one reading. Before the hard fork the scope takes calls against contracts
1742
+ * produced by the ledger 8 Compact toolchain; type `fn`'s parameter as {@link Ledger8TransactionContext}
1743
+ * to call them. After the fork it takes calls against contracts produced by the ledger 9 toolchain, and a
1744
+ * ledger 8 contract's calls are submitted individually with `submitCallTx`.
1745
+ *
1746
+ * A JavaScript caller that passes a running scope's context in place of `options` runs `fn` inside that
1747
+ * scope. Nothing is submitted then, and the result is the execution data of the scope's last call, not
1748
+ * a finalized transaction.
1749
+ */
1750
+ declare function withContractScopedTransaction<C extends Contract.Any, PCK extends Contract.ProvableCircuitId<C> = Contract.ProvableCircuitId<C>>(providers: Ledger9ContractProviders<C, PCK>, fn: (txCtx: Ledger9TransactionContext<C, PCK>) => Promise<void>, options?: ScopedTransactionOptions): Promise<Ledger9FinalizedCallTxData<C, PCK>>;
1751
+ /**
1752
+ * Executes a function within a contract-scoped transaction on a ledger 8 (pre-fork) network. The rules
1753
+ * are those of the overload above.
1754
+ */
1755
+ declare function withContractScopedTransaction<C extends Ledger8Contract, PCK extends Ledger8CircuitId<C>>(providers: Ledger8ContractProviders<C, PCK>, fn: (txCtx: Ledger8TransactionContext<C, PCK>) => Promise<void>, options?: ScopedTransactionOptions): Promise<Ledger8FinalizedCallTxData<C, PCK>>;
1756
+ /**
1757
+ * Executes a function within a contract-scoped transaction on a ledger 8 (pre-fork) head. The rules are
1758
+ * those of {@link withContractScopedTransaction}.
1759
+ *
1760
+ * @throws {EraMismatchError} with reason `'scope-era-mismatch'` when the network is not on ledger 8.
1761
+ * Raised before `fn` runs, and before the ledger 8 runtime is loaded.
1762
+ *
1763
+ * @remarks
1764
+ * A JavaScript caller that passes a running ledger 8 scope's context in place of `options` runs `fn`
1765
+ * inside that scope. Nothing is submitted then, and the result is the execution data of the scope's
1766
+ * last call, not a finalized transaction.
1767
+ */
1768
+ declare function withLedger8ContractScopedTransaction<C extends Ledger8Contract, PCK extends Ledger8CircuitId<C>>(providers: Ledger8ContractProviders<C, PCK>, fn: (txCtx: Ledger8TransactionContext<C, PCK>) => Promise<void>, options?: ScopedTransactionOptions): Promise<Ledger8FinalizedCallTxData<C, PCK>>;
1769
+ /**
1770
+ * Executes a function within a contract-scoped transaction on a ledger 9 head. The rules are those of
1771
+ * {@link withContractScopedTransaction}.
1772
+ *
1773
+ * @throws {EraMismatchError} with reason `'scope-era-mismatch'` when the network is not on ledger 9.
1774
+ * Raised before `fn` runs.
1775
+ */
1776
+ declare const withLedger9ContractScopedTransaction: <C extends Contract.Any, PCK extends Contract.ProvableCircuitId<C> = Contract.ProvableCircuitId<C>>(providers: Ledger9ContractProviders<C, PCK>, fn: (txCtx: Ledger9TransactionContext<C, PCK>) => Promise<void>, options?: ScopedTransactionOptions) => Promise<Ledger9FinalizedCallTxData<C, PCK>>;
1777
+
1778
+ /**
1779
+ * The retained-era contract type family: the shape of a contract produced by
1780
+ * the PREVIOUS Compact toolchain (`compact-runtime@0.16`), which the current
1781
+ * entry points accept through an additive overload alongside the current
1782
+ * (`compact-runtime@0.21`) `CompiledContract` container.
1783
+ *
1784
+ * Every declaration here is hand-written. The retained toolchain DOES emit an
1785
+ * `index.d.ts`, but it describes one contract in terms of
1786
+ * `compact-runtime@0.16` -- a package this one does not depend on and consumers
1787
+ * need not install -- where this family is a top type over the whole era. Three
1788
+ * things separate the eras at the type level: the circuit CONTEXT, which is the
1789
+ * one that fires for a real contract; the fact that retained-era circuits and
1790
+ * `initialState` return plain objects where the current era returns `Promise`s;
1791
+ * and the current era's `CompiledContract` container.
1792
+ *
1793
+ * There is no era decision in this file. The single RUNTIME decision is
1794
+ * `resolveArtifactEra` in `./internal/era`; do not add a second one here.
1795
+ *
1796
+ * @see {@link OverloadTyping} for why the declarations are hand-written and
1797
+ * runtime-pinned, how openness is expressed without `any`, and why the
1798
+ * order of the overloads is load-bearing.
1799
+ * @see {@link EraDispatch} for the runtime decision and what it may not use.
1800
+ */
1801
+
1802
+ /**
1803
+ * The retained era's contract-state handle.
1804
+ *
1805
+ * DERIVED from the engine's own results rather than restated: it is compact-js's
1806
+ * ledger-8 type, and naming it structurally keeps this package free of any
1807
+ * dependency on the retained runtime.
1808
+ */
1809
+ type Ledger8StateValue = TranscriptPojo['postContractState'];
1810
+
1811
+ /**
1812
+ * The context a retained-era circuit receives as its first argument, as a
1813
+ * caller READS it.
1814
+ *
1815
+ * The member list is an invariant, not a description: it must be exactly the
1816
+ * retained runtime's REQUIRED members. `gasLimit`, the one optional member, is
1817
+ * therefore absent -- and naming it, or any future optional member, without
1818
+ * `?` would collapse {@link Ledger8CircuitParameters} to `never[]` for every
1819
+ * retained contract. `costModel` is named for the same reason rather than for
1820
+ * anything this type does on its own: {@link Ledger8CircuitContextArgument}
1821
+ * takes its keys from here.
1822
+ *
1823
+ * The era-internal members are `unknown`: they are live values of the previous
1824
+ * runtime, and nothing outside that runtime may inspect them.
1825
+ *
1826
+ * This is not the type that stands in a circuit's parameter position -- see
1827
+ * {@link Ledger8CircuitContextArgument}.
1828
+ *
1829
+ * @see {@link OverloadTyping} for why the context needs two types.
1830
+ */
1831
+ interface Ledger8CircuitContext<PS = unknown> {
1832
+ readonly currentQueryContext: unknown;
1833
+ readonly currentPrivateState: PS;
1834
+ readonly currentZswapLocalState: unknown;
1835
+ readonly costModel: unknown;
1836
+ }
1837
+ /**
1838
+ * The context in the position where a retained-era circuit ACCEPTS it.
1839
+ *
1840
+ * A parameter position is contravariant, so this type is the one that has to be
1841
+ * assignable INTO the retained runtime's real `CircuitContext` -- the opposite
1842
+ * direction from {@link Ledger8CircuitContext}. Every member is therefore
1843
+ * `never`, and it is derived by a mapped type so the two cannot drift apart on
1844
+ * a member.
1845
+ *
1846
+ * Deliberately NOT exported: it is uninhabited, so no caller can obtain one,
1847
+ * and a type nobody can hold has no place on the surface.
1848
+ *
1849
+ * @see {@link OverloadTyping} for what this buys, and what broke when the
1850
+ * circuit took {@link Ledger8CircuitContext} here instead.
1851
+ * @see {@link ErrorTaxonomy} for how the `Ledger8` names are used.
1852
+ */
1853
+ type Ledger8CircuitContextArgument = {
1854
+ readonly [K in keyof Ledger8CircuitContext]: never;
1855
+ };
1856
+ /**
1857
+ * What a retained-era circuit member returns: a plain object, NOT a `Promise`.
1858
+ *
1859
+ * The absence of `Promise` here is the load-bearing half of the era
1860
+ * discriminator — a current-era circuit's `Promise<CircuitResults<...>>` has
1861
+ * none of these four members, so it is not assignable to this type.
1862
+ */
1863
+ interface Ledger8CircuitResult {
1864
+ readonly result: unknown;
1865
+ readonly context: unknown;
1866
+ readonly proofData: unknown;
1867
+ readonly gasCost: unknown;
1868
+ }
1869
+ /**
1870
+ * A retained-era circuit member.
1871
+ *
1872
+ * Two things here are load-bearing and neither is cosmetic: the leading context is declared
1873
+ * EXPLICITLY, and both it and the argument tail are bottom types rather than `unknown`. Do not
1874
+ * widen either for readability.
1875
+ *
1876
+ * @see {@link OverloadTyping} for what each buys and what breaks without it.
1877
+ */
1878
+ type Ledger8Circuit = (context: Ledger8CircuitContextArgument, ...args: never[]) => Ledger8CircuitResult;
1879
+ /**
1880
+ * A retained-era witness implementation, which returns the next private state
1881
+ * paired with the value the circuit reads.
1882
+ *
1883
+ * `PS` is threaded through the FIRST tuple member so a witness declared over the wrong private
1884
+ * state is refused. It sits in a result position, where `PS` is covariant, so every concrete
1885
+ * contract still satisfies the era top type.
1886
+ */
1887
+ type Ledger8Witness<PS = unknown> = (...args: never[]) => readonly [PS, unknown];
1888
+ /**
1889
+ * What a retained-era artifact's own `initialState` returns: a plain object,
1890
+ * NOT a `Promise`.
1891
+ *
1892
+ * A declaration OF THE ARTIFACT, not a framework result. It is the shape
1893
+ * {@link Ledger8Contract.initialState} is read through, and it is what makes
1894
+ * the era discriminable at the type level -- the current era's `initialState`
1895
+ * answers with a `Promise`.
1896
+ *
1897
+ * Deliberately NOT the retained counterpart of `Ledger9ContractConstructorResult`,
1898
+ * which is a framework result carrying `era` and `next*` members. There is no
1899
+ * retained counterpart of that type: the constructor output a retained deploy
1900
+ * would publish is spread across `Ledger8DeployedContract`'s `initial*`
1901
+ * members, and nothing constructs one today. This type was called
1902
+ * `Ledger8ConstructorResult`, which put a false pairing next to
1903
+ * `Ledger9ContractConstructorResult` on the published surface.
1904
+ */
1905
+ interface Ledger8InitialStateResult<PS = unknown> {
1906
+ readonly currentContractState: unknown;
1907
+ readonly currentPrivateState: PS;
1908
+ readonly currentZswapLocalState: unknown;
1909
+ }
1910
+ /**
1911
+ * A contract instance produced by the retained (`compact-runtime@0.16`)
1912
+ * toolchain, as the real generated artifact declares it: `witnesses`, the three
1913
+ * circuit collections, and a synchronous `initialState`.
1914
+ *
1915
+ * Structurally excludes a current-era contract, whose `initialState` and
1916
+ * circuit members return `Promise`s.
1917
+ */
1918
+ interface Ledger8Contract<PS = unknown> {
1919
+ readonly witnesses: Readonly<Record<string, Ledger8Witness<PS>>>;
1920
+ readonly circuits: Readonly<Record<string, Ledger8Circuit>>;
1921
+ readonly impureCircuits: Readonly<Record<string, Ledger8Circuit>>;
1922
+ readonly provableCircuits: Readonly<Record<string, Ledger8Circuit>>;
1923
+ initialState(...args: never[]): Ledger8InitialStateResult<PS>;
1924
+ }
1925
+ /**
1926
+ * The private state type a retained-era contract carries.
1927
+ */
1928
+ type Ledger8PrivateState<C extends Ledger8Contract> = C extends Ledger8Contract<infer PS> ? PS : never;
1929
+ /**
1930
+ * The name of a callable circuit on a retained-era contract.
1931
+ *
1932
+ * Keyed off `provableCircuits`, NOT `impureCircuits`: `provableCircuits` is the
1933
+ * map compact-js indexes to run a circuit, and the one the deploy pre-check
1934
+ * demands a verifier key for. Naming the other map lets an artifact whose two
1935
+ * maps differ ask for a key the caller cannot name, which is unsatisfiable.
1936
+ */
1937
+ type Ledger8CircuitId<C extends Ledger8Contract> = keyof C['provableCircuits'] & string;
1938
+ /**
1939
+ * The arguments a caller supplies for circuit `PCK` on a retained-era contract.
1940
+ *
1941
+ * The leading {@link Ledger8CircuitContext} is stripped, exactly as the current
1942
+ * era's `Contract.CircuitParameters` strips its own leading `CircuitContext`:
1943
+ * the context is built by the framework from provider data, never passed in by
1944
+ * the caller.
1945
+ *
1946
+ * A circuit whose parameters are not tuple-shaped falls to `never[]`, NOT to `never`: `never`
1947
+ * satisfies `extends []`, so it would make {@link Ledger8CallTxOptionsBase} report that such a
1948
+ * circuit takes no arguments at all. `never[]` is uninhabited but not empty, so the caller is
1949
+ * asked for an `args` it cannot supply and the mismatch surfaces instead of being swallowed.
1950
+ *
1951
+ * @see {@link OverloadTyping} for why a caller may not be handed the raw
1952
+ * `Parameters<...>`.
1953
+ */
1954
+ type Ledger8CircuitParameters<C extends Ledger8Contract, PCK extends Ledger8CircuitId<C>> = Parameters<C['provableCircuits'][PCK]> extends [Ledger8CircuitContext, ...infer A] ? A : never[];
1955
+ /**
1956
+ * The providers a retained-era call transaction needs.
1957
+ *
1958
+ * The same provider set the current era uses, keyed by the retained-era circuit
1959
+ * id.
1960
+ *
1961
+ * @see {@link OverloadTyping} for why there is no separate retained-era provider
1962
+ * surface.
1963
+ */
1964
+ type Ledger8ContractProviders<C extends Ledger8Contract, PCK extends Ledger8CircuitId<C>> = MidnightProviders<PCK, PrivateStateId, Ledger8PrivateState<C>>;
1965
+ /**
1966
+ * The target of a retained-era circuit invocation, without its arguments.
1967
+ */
1968
+ interface Ledger8CallTxTarget<C extends Ledger8Contract, PCK extends Ledger8CircuitId<C>> {
1969
+ /**
1970
+ * The retained-era contract instance, passed raw — there is no
1971
+ * `CompiledContract` container for this era.
1972
+ */
1973
+ readonly compiledContract: C;
1974
+ /**
1975
+ * The address of the contract being called.
1976
+ */
1977
+ readonly contractAddress: ContractAddress;
1978
+ /**
1979
+ * The identifier of the circuit to call.
1980
+ */
1981
+ readonly circuitId: PCK;
1982
+ /**
1983
+ * An optional mapping of {@link CoinPublicKey} to {@link EncPublicKey} used to
1984
+ * encrypt shielded coins the circuit pays to a recipient other than the
1985
+ * calling wallet. A user-owned recipient that is neither the calling wallet,
1986
+ * the burn address, nor a key in this map is refused with
1987
+ * `Ledger8CallUnsupportedError` (reason `'unmappable-recipient'`) before anything is proven.
1988
+ */
1989
+ readonly additionalCoinEncPublicKeyMappings?: ReadonlyMap<CoinPublicKey$1, EncPublicKey>;
1990
+ }
1991
+ /**
1992
+ * Base configuration for a retained-era call transaction.
1993
+ *
1994
+ * `args` is CONDITIONAL, mirroring the current era's `Ledger9CallOptionsWithArguments`: a circuit that
1995
+ * takes no arguments of its own has no `args` member at all, rather than one the caller has to
1996
+ * satisfy with an empty array, so the two eras do not disagree about the same zero-argument
1997
+ * circuit.
1998
+ */
1999
+ type Ledger8CallTxOptionsBase<C extends Ledger8Contract, PCK extends Ledger8CircuitId<C>> = Ledger8CircuitParameters<C, PCK> extends [] ? Ledger8CallTxTarget<C, PCK> : Ledger8CallTxTarget<C, PCK> & {
2000
+ /**
2001
+ * Arguments to pass to the circuit being called.
2002
+ */
2003
+ readonly args: Ledger8CircuitParameters<C, PCK>;
2004
+ };
2005
+ /**
2006
+ * A retained-era call transaction configuration that also names where to store
2007
+ * the private state the call produces.
2008
+ */
2009
+ type Ledger8CallTxOptionsWithPrivateStateId<C extends Ledger8Contract, PCK extends Ledger8CircuitId<C>> = Ledger8CallTxOptionsBase<C, PCK> & {
2010
+ /**
2011
+ * The identifier for the private state of the contract.
2012
+ */
2013
+ readonly privateStateId: PrivateStateId;
2014
+ };
2015
+ /**
2016
+ * Retained-era call transaction configuration.
2017
+ */
2018
+ type Ledger8CallTxOptions<C extends Ledger8Contract, PCK extends Ledger8CircuitId<C>> = Ledger8CallTxOptionsBase<C, PCK> | Ledger8CallTxOptionsWithPrivateStateId<C, PCK>;
2019
+ /**
2020
+ * Configuration for building a retained-era call on states the caller read itself, with
2021
+ * `createLedger8UnprovenCallTxFromInitialStates`. The head era is stated, and each state carries the
2022
+ * era that wrote it, because after the fork a retained-era contract's state may already be a ledger 9
2023
+ * one.
2024
+ */
2025
+ type Ledger8CallOptionsWithInitialStates<C extends Ledger8Contract, PCK extends Ledger8CircuitId<C>> = Ledger8CallTxOptionsBase<C, PCK> & {
2026
+ /** The era of the network head the transaction is built for. */
2027
+ readonly head: LedgerEra;
2028
+ /**
2029
+ * The contract state to run the circuit against, as read: pass `read.contractState`. Its era is
2030
+ * `'v8'` before the fork and `'v9'` after it. An indexer older than 4.4.0-rc.6 may still serve the
2031
+ * pre-fork `'v8'` bytes after the fork.
2032
+ */
2033
+ readonly initialContractState: SerializedContractState;
2034
+ /** The ledger parameters of the block the state was read at, as read: pass `read.ledgerParameters`. */
2035
+ readonly ledgerParameters: SerializedLedgerParameters;
2036
+ /** The Zswap public key of the current user. */
2037
+ readonly coinPublicKey: CoinPublicKey$1;
2038
+ /** Network and transaction settings, normally `providers.config`. */
2039
+ readonly config: MidnightConfig;
2040
+ /**
2041
+ * The private state the circuit runs against.
2042
+ *
2043
+ * @remarks **Privacy-sensitive.**
2044
+ */
2045
+ readonly initialPrivateState?: Ledger8PrivateState<C>;
2046
+ };
2047
+ /**
2048
+ * The finalized data a retained-era call transaction resolves with.
2049
+ *
2050
+ * `txData` is era-tagged rather than single-era: the same retained-era
2051
+ * contract is called as a v8 transaction before the fork and as a v9 keep-state
2052
+ * transaction after it, so the record it finalizes as carries the era that
2053
+ * produced it.
2054
+ *
2055
+ * @see {@link OverloadTyping} for the era-tagged provider methods that rule follows from.
2056
+ */
2057
+ /**
2058
+ * What a retained-era circuit's own return value narrows to.
2059
+ *
2060
+ * Derived through `infer` with a fallback rather than read off
2061
+ * {@link Ledger8CircuitResult}, whose `result` is `unknown` because that type is
2062
+ * the ERA DISCRIMINATOR and has to stay wide enough to match any retained
2063
+ * codegen. A concrete contract type narrows it here; anything that does not
2064
+ * falls to `unknown` rather than to `never`, so a caller is handed a value it
2065
+ * has to check instead of one it cannot use.
2066
+ */
2067
+ type Ledger8CircuitReturnType<C extends Ledger8Contract, PCK extends Ledger8CircuitId<C>> = ReturnType<C['provableCircuits'][PCK]> extends {
2068
+ readonly result: infer R;
2069
+ } ? R : unknown;
2070
+ /**
2071
+ * The public, non-sensitive half of a retained-era circuit execution.
2072
+ *
2073
+ * Carries {@link CallResultPublicBase} plus the post-call state. Against
2074
+ * `Ledger9CallResultPublic` exactly ONE member is missing: `logEvents`,
2075
+ * because the retained toolchain has no log-event concept at any layer, so
2076
+ * there is no value to carry rather than a value being dropped. That absence is
2077
+ * named in the era key-set parity gate's allow-list, which is what keeps a
2078
+ * second absence from joining it unnoticed.
2079
+ */
2080
+ interface Ledger8CallResultPublic extends CallResultPublicBase {
2081
+ /**
2082
+ * The state the execution ENDED on, as a LIVE `onchain-runtime-v3` handle
2083
+ * rather than as bytes.
2084
+ *
2085
+ * Valid only while the retained runtime instance that produced it is loaded.
2086
+ * It does not survive `structuredClone`, a `postMessage` to a worker, or
2087
+ * serialization — anything that walks it sees `__wbg_ptr`, an integer that
2088
+ * means nothing outside its module. Serialize it yourself if you need to
2089
+ * keep it; see ADR-0010.
2090
+ */
2091
+ readonly nextContractState: Ledger8StateValue;
2092
+ /**
2093
+ * The same state as an {@link EncodedStateValue}: the form that survives this
2094
+ * process, a `structuredClone`, a worker transfer and storage.
2095
+ *
2096
+ * `EncodedStateValue` is pinned identical across `onchain-runtime-v3`,
2097
+ * `ledger-v8` and `ledger-v9`, so this is the member era-agnostic code reads
2098
+ * and the one to persist. The handle above is for use in the process that
2099
+ * produced it.
2100
+ */
2101
+ readonly nextContractStateEncoded: EncodedStateValue$1;
2102
+ }
2103
+ /**
2104
+ * The private, ZK-confidential half of a retained-era circuit execution.
2105
+ *
2106
+ * Carries {@link CallResultPrivateBase} and {@link UnsubmittedTxDataBase} — so
2107
+ * the execution members and the caller's new coins come from the same
2108
+ * declarations the current era uses — and adds `unprovenTx`, the transaction
2109
+ * this call composed.
2110
+ *
2111
+ * @remarks **Privacy-sensitive.** Carries the ZK input and output, the private
2112
+ * transcript outputs, the next private state, the post-call Zswap local state
2113
+ * and shielded coin material. Treat as confidential when logging, serializing
2114
+ * or transmitting.
2115
+ */
2116
+ interface Ledger8CallResultPrivate<C extends Ledger8Contract, PCK extends Ledger8CircuitId<C>> extends CallResultPrivateBase<Ledger8CircuitReturnType<C, PCK>, Ledger8PrivateState<C>>, UnsubmittedTxDataBase {
2117
+ /**
2118
+ * The UNPROVEN transaction this call composed, in the era of the network
2119
+ * head it was composed for: a v8 handle before the fork, a v9 handle after
2120
+ * it. Read `unprovenTx.era` before unwrapping it.
2121
+ */
2122
+ readonly unprovenTx: UnprovenTx;
2123
+ }
2124
+ /**
2125
+ * The public data of a finalized retained-era call: the execution's public half
2126
+ * combined with the finalized record.
2127
+ *
2128
+ * The record stays {@link FinalizedTxRead} rather than being narrowed
2129
+ * to `Ledger9FinalizedTxData`. A retained-era call is recorded by
2130
+ * whichever era the network is on, so `era` is a union here where the
2131
+ * current era pins `'v9'` -- narrowing it would refuse the very records this
2132
+ * pipeline exists to produce.
2133
+ */
2134
+ type Ledger8FinalizedCallTxPublicData = Ledger8CallResultPublic & FinalizedTxRead;
2135
+ /**
2136
+ * What a retained-era call transaction resolves with once finalized.
2137
+ *
2138
+ * The SAME two-level structure the current era answers with -- `public` for the
2139
+ * non-sensitive half, `private` for the confidential one -- so a caller reads
2140
+ * `private.result`, `public.txId` and `public.status` identically in both eras.
2141
+ * Both halves are built from the shared bases in `midnight-js-types`, so the
2142
+ * members that differ are only the ones each era adds: see
2143
+ * {@link Ledger8CallResultPublic} and {@link Ledger8CallResultPrivate} for what
2144
+ * they are, what stands in for them, and why.
2145
+ */
2146
+ interface Ledger8FinalizedCallTxData<C extends Ledger8Contract, PCK extends Ledger8CircuitId<C>> {
2147
+ /**
2148
+ * The pipeline that produced this result: always the retained era here, even
2149
+ * when the transaction that recorded it is a keep-state transaction tagged
2150
+ * `'v9'`. Those are different facts, and only this one says which module
2151
+ * produced the objects below.
2152
+ */
2153
+ readonly era: 'v8';
2154
+ readonly circuitId: PCK;
2155
+ readonly public: Ledger8FinalizedCallTxPublicData;
2156
+ readonly private: Ledger8CallResultPrivate<C, PCK>;
2157
+ /** See {@link Ledger8UnsubmittedCallTxData.calls}. */
2158
+ readonly calls: readonly Ledger8ContractCall[];
2159
+ }
2160
+ /**
2161
+ * The public half of ONE retained-era contract call.
2162
+ *
2163
+ * Both state members are LIVE `onchain-runtime-v3` handles, valid only while
2164
+ * the retained runtime instance that produced them is loaded. Neither survives
2165
+ * `structuredClone`, a worker transfer or serialization; both are published
2166
+ * under ADR-0010 for callers that want the object rather than another decode of
2167
+ * the same bytes, and both carry an {@link EncodedStateValue} twin for
2168
+ * everything else.
2169
+ *
2170
+ * @typeParam TState - The retained-era state type; the framework's own
2171
+ * retained runtime fills it with compact-js's ledger-8 state handle.
2172
+ */
2173
+ interface Ledger8ContractCallPublic<TState = Ledger8StateValue> extends CallResultPublicBase {
2174
+ /**
2175
+ * The state this call ENDED on.
2176
+ *
2177
+ * The current era's member of this name is filled from `compact-js`'s FINAL
2178
+ * query context, so the two eras answer the same question here. For the state
2179
+ * the call started from, read {@link Ledger8ContractCallPublic.preContractState}
2180
+ * — a different fact, under a different name.
2181
+ */
2182
+ readonly contractState: TState;
2183
+ /**
2184
+ * The same post-call state as an {@link EncodedStateValue} — see
2185
+ * {@link Ledger8CallResultPublic.nextContractStateEncoded} for which of the
2186
+ * two to reach for.
2187
+ */
2188
+ readonly contractStateEncoded: EncodedStateValue$1;
2189
+ /**
2190
+ * The state this call BOUND to: the retained-era handle the pipeline
2191
+ * executed against, forwarded rather than re-derived.
2192
+ *
2193
+ * Retained-era only. The current era publishes no pre-call state on a call
2194
+ * entry, so era-agnostic code must not reach for this member.
2195
+ *
2196
+ * Indistinguishable from {@link Ledger8ContractCallPublic.postContractState}
2197
+ * BY TYPE: compact-js resolves the pre- and post-execution state to the same
2198
+ * declaration, so swapping the two is not a compile error. Partitioning
2199
+ * against the wrong one rejects a state the transcript's reads do not fit, or
2200
+ * silently mis-charges one that merely differs in value.
2201
+ */
2202
+ readonly preContractState: TState;
2203
+ /**
2204
+ * The same pre-call state as an {@link EncodedStateValue} — this one IS the
2205
+ * snapshot's own primary state, the value the handle was decoded from, so it
2206
+ * is forwarded rather than re-encoded.
2207
+ */
2208
+ readonly preContractStateEncoded: EncodedStateValue$1;
2209
+ }
2210
+ /**
2211
+ * Proof data for ONE retained-era contract call.
2212
+ *
2213
+ * The retained era's counterpart of `compact-js`'s `ContractCall`: it carries
2214
+ * every member that one does, under the same name and meaning, and adds three.
2215
+ * `public.contractState` differs only in TYPE — each era's state handle comes
2216
+ * from its own runtime. The additions are `public.contractStateEncoded` and the
2217
+ * pre-call pair, which the current era has no counterpart for.
2218
+ *
2219
+ * @typeParam TState - See {@link Ledger8ContractCallPublic}.
2220
+ */
2221
+ interface Ledger8ContractCall<TState = Ledger8StateValue> {
2222
+ readonly contractAddress: ContractAddress;
2223
+ readonly circuitId: string;
2224
+ readonly public: Ledger8ContractCallPublic<TState>;
2225
+ readonly private: ContractCallPrivateBase;
2226
+ /**
2227
+ * ALWAYS `Option.none()` on this era: the commitment binds a cross-contract
2228
+ * sub-call to its caller, and a pre-fork contract cannot make one. The member
2229
+ * is carried rather than omitted so a caller reading a call entry does not
2230
+ * have to branch on which era produced it.
2231
+ */
2232
+ readonly communicationCommitment: Option.Option<CommunicationCommitmentData>;
2233
+ }
2234
+ /**
2235
+ * The execution data of a retained-era call, before the chain has recorded it.
2236
+ *
2237
+ * The same two halves {@link Ledger8FinalizedCallTxData} carries, minus the
2238
+ * finalized record — which is the one thing a submission that does not wait
2239
+ * for finalization cannot answer with.
2240
+ */
2241
+ interface Ledger8UnsubmittedCallTxData<C extends Ledger8Contract, PCK extends Ledger8CircuitId<C>> {
2242
+ /**
2243
+ * The pipeline that produced this result: always the retained era here, even
2244
+ * when the transaction that recorded it is a keep-state transaction tagged
2245
+ * `'v9'`. Those are different facts, and only this one says which module
2246
+ * produced the objects below.
2247
+ */
2248
+ readonly era: 'v8';
2249
+ readonly public: Ledger8CallResultPublic;
2250
+ readonly private: Ledger8CallResultPrivate<C, PCK>;
2251
+ /**
2252
+ * Proof data for every contract call this circuit made, as the current era's
2253
+ * `Ledger9CallResult.calls` carries. Always exactly ONE entry, the root call: a
2254
+ * pre-fork contract cannot make a cross-contract call.
2255
+ */
2256
+ readonly calls: readonly Ledger8ContractCall[];
2257
+ }
2258
+ /**
2259
+ * What a retained-era call transaction resolves with when submitted without
2260
+ * waiting for finalization.
2261
+ *
2262
+ * Carries the execution data on `callTxData`, as the current era's
2263
+ * {@link Ledger9SubmittedCallTx} does, and names the same members it does. The next
2264
+ * private state is reachable at `callTxData.private.nextPrivateState`, the one
2265
+ * path both eras publish it on.
2266
+ */
2267
+ interface Ledger8SubmittedCallTx<C extends Ledger8Contract, PCK extends Ledger8CircuitId<C>> extends SubmittedCallTxBase<Ledger8UnsubmittedCallTxData<C, PCK>> {
2268
+ /**
2269
+ * The pipeline that produced this result: always the retained era here, even
2270
+ * when the transaction that recorded it is a keep-state transaction tagged
2271
+ * `'v9'`. Those are different facts, and only this one says which module
2272
+ * produced the objects below.
2273
+ */
2274
+ readonly era: 'v8';
2275
+ readonly circuitId: PCK;
2276
+ }
2277
+ /**
2278
+ * The arguments a retained-era CONSTRUCTOR takes, with the framework-built
2279
+ * context stripped — the constructor counterpart of
2280
+ * {@link Ledger8CircuitParameters}, and it follows the same rule: a constructor
2281
+ * whose parameters are not tuple-shaped falls to `never[]`, not to `never`, so
2282
+ * the caller is asked for an `args` it cannot supply rather than told there is
2283
+ * nothing to supply.
2284
+ */
2285
+ type Ledger8ConstructorParameters<C extends Ledger8Contract> = Parameters<C['initialState']> extends [unknown, ...infer A] ? A : never[];
2286
+ /**
2287
+ * What both retained-era deploy options variants carry, and nothing either variant decides.
2288
+ *
2289
+ * NOT published, and neither variant extends the other. A variant declaring
2290
+ * `privateStateId: PrivateStateId` over a base declaring `privateStateId?:
2291
+ * never` is an illegal extension, and under the `args` intersection below it
2292
+ * collapses the member to `never` — so the pairing rule can only be stated by
2293
+ * making the two variants siblings over this.
2294
+ */
2295
+ interface Ledger8DeployContractOptionsShared<C extends Ledger8Contract> {
2296
+ readonly compiledContract: C;
2297
+ /**
2298
+ * The signing key to register as the deployed contract's maintenance
2299
+ * authority. If undefined, a fresh one is sampled.
2300
+ *
2301
+ * The same `{ tag, value }` shape the current era takes. The retained era
2302
+ * signs with `schnorr` only, so any other key -- or a value that is not
2303
+ * exactly 64 hexadecimal characters -- is refused with
2304
+ * `Ledger8SigningKeyError` (reason `'unusable'`) before anything is composed.
2305
+ */
2306
+ readonly signingKey?: SigningKey;
2307
+ }
2308
+ /**
2309
+ * The deploy options variant for a retained-era contract whose private state is stored
2310
+ * NOWHERE: the constructor runs against `undefined` and nothing is written.
2311
+ *
2312
+ * The other variant is {@link Ledger8DeployContractOptionsWithPrivateState}.
2313
+ */
2314
+ interface Ledger8DeployContractOptionsBase<C extends Ledger8Contract> extends Ledger8DeployContractOptionsShared<C> {
2315
+ /**
2316
+ * DECLARED on this variant, and only ever `undefined`.
2317
+ *
2318
+ * Left off the variant entirely, `{ compiledContract, privateStateId: 'x' }`
2319
+ * compiled: union excess-property checking admits a member declared on the
2320
+ * SIBLING variant as long as one variant is satisfied, and `compiledContract` alone
2321
+ * satisfies this one. The constructor then ran against `undefined`,
2322
+ * `undefined` was stored under the caller's id, and the handle reported an
2323
+ * `initialPrivateState` typed non-optional while actually undefined.
2324
+ */
2325
+ readonly privateStateId?: never;
2326
+ /**
2327
+ * DECLARED on this variant, and only ever `undefined` — see
2328
+ * {@link Ledger8DeployContractOptionsBase.privateStateId} for why the member
2329
+ * is present rather than absent.
2330
+ */
2331
+ readonly initialPrivateState?: never;
2332
+ }
2333
+ /**
2334
+ * Deploy configuration for a retained-era contract that carries private state,
2335
+ * naming where the state the constructor produces is stored.
2336
+ *
2337
+ * Both members together or neither: a state with no id has nowhere to go, and
2338
+ * an id with no state stores `undefined` under a name a later call will read
2339
+ * back. The type refuses either half alone, and
2340
+ * `IncompleteDeployContractPrivateStateConfig` refuses it at run time for a
2341
+ * caller that reached it through an untyped route. The current era's
2342
+ * `Ledger9DeployContractOptionsWithPrivateState` is the same shape for the same reason.
2343
+ */
2344
+ interface Ledger8DeployContractOptionsWithPrivateState<C extends Ledger8Contract> extends Ledger8DeployContractOptionsShared<C> {
2345
+ /** An identifier for the private state of the contract being deployed. */
2346
+ readonly privateStateId: PrivateStateId;
2347
+ /**
2348
+ * The private state the constructor runs against.
2349
+ *
2350
+ * @remarks **Privacy-sensitive.**
2351
+ */
2352
+ readonly initialPrivateState: Ledger8PrivateState<C>;
2353
+ }
2354
+ /**
2355
+ * Configuration for deploying a retained-era contract.
2356
+ *
2357
+ * `args` is CONDITIONAL, exactly as {@link Ledger8CallTxOptionsBase}'s is: a
2358
+ * constructor that takes no arguments of its own has no `args` member at all.
2359
+ * A retained constructor CAN take arguments — `Ledger8Contract.initialState`
2360
+ * says so, and the pipeline under this overload has always passed them through — so
2361
+ * denying them here made a zero-argument constructor the only deployable one.
2362
+ *
2363
+ * The conditional is applied to the WHOLE union, so it reaches both variants: a
2364
+ * constructor with parameters demands `args` whether or not private state is
2365
+ * named, and a nullary one carries the member on neither. Writing the union
2366
+ * inside one branch only would have made the private-state variant the one shape a
2367
+ * caller could not supply arguments on.
2368
+ *
2369
+ * `additionalCoinEncPublicKeyMappings`, which the current era's deploy options
2370
+ * also carry, stays absent by decision; see {@link KeepStatePipeline}.
2371
+ */
2372
+ type Ledger8DeployContractOptions<C extends Ledger8Contract> = Ledger8ConstructorParameters<C> extends [] ? Ledger8DeployContractOptionsBase<C> | Ledger8DeployContractOptionsWithPrivateState<C> : (Ledger8DeployContractOptionsBase<C> | Ledger8DeployContractOptionsWithPrivateState<C>) & {
2373
+ /** Arguments to pass to the contract's constructor. */
2374
+ readonly args: Ledger8ConstructorParameters<C>;
2375
+ };
2376
+ /**
2377
+ * Configuration for building a retained-era deploy without submitting it, with
2378
+ * `createLedger8UnprovenDeployTx` or `createLedger8UnprovenDeployTxFromVerifierKeys`. A builder
2379
+ * stores nothing, so the constructor's private state needs no id to be stored under.
2380
+ */
2381
+ interface Ledger8UnprovenDeployTxOptionsBase<C extends Ledger8Contract> extends Ledger8DeployContractOptionsShared<C> {
2382
+ /**
2383
+ * The private state the constructor runs against.
2384
+ *
2385
+ * @remarks **Privacy-sensitive.**
2386
+ */
2387
+ readonly initialPrivateState?: Ledger8PrivateState<C>;
2388
+ }
2389
+ /** {@link Ledger8UnprovenDeployTxOptionsBase}, with the constructor's arguments when it takes any. */
2390
+ type Ledger8UnprovenDeployTxOptions<C extends Ledger8Contract> = Ledger8ConstructorParameters<C> extends [] ? Ledger8UnprovenDeployTxOptionsBase<C> : Ledger8UnprovenDeployTxOptionsBase<C> & {
2391
+ /** Arguments to pass to the contract's constructor. */
2392
+ readonly args: Ledger8ConstructorParameters<C>;
2393
+ };
2394
+ /**
2395
+ * Configuration for attaching to an already-deployed retained-era contract.
2396
+ */
2397
+ interface Ledger8FindDeployedContractOptions<C extends Ledger8Contract> {
2398
+ readonly compiledContract: C;
2399
+ readonly contractAddress: ContractAddress;
2400
+ /**
2401
+ * Where the calls made through {@link Ledger8FoundContract.callTx} read and
2402
+ * store this contract's private state.
2403
+ *
2404
+ * Optional because a retained-era contract may genuinely carry none: OMITTING
2405
+ * the property means nothing is read and nothing is written. Naming one the
2406
+ * provider holds nothing under is a caller error and is refused, rather than
2407
+ * executing against a default state — and so is writing the property with an
2408
+ * undefined value, which is a caller that believes it named an id.
2409
+ */
2410
+ readonly privateStateId?: PrivateStateId;
2411
+ /**
2412
+ * The private state to store at {@link Ledger8FindDeployedContractOptions.privateStateId},
2413
+ * overwriting whatever is held there.
2414
+ *
2415
+ * Honoured by the same six-case rule the current era's `findDeployedContract`
2416
+ * applies, and it is the same rule rather than a second copy of it. Supplying
2417
+ * this without an id is a caller error: there is nowhere to put the state, and
2418
+ * `IncompleteFindContractPrivateStateConfig` says so rather than the state
2419
+ * being dropped.
2420
+ *
2421
+ * @remarks **Privacy-sensitive.**
2422
+ */
2423
+ readonly initialPrivateState?: Ledger8PrivateState<C>;
2424
+ /**
2425
+ * The key to record as this contract's maintenance authority key, for a
2426
+ * caller that holds one and deployed the contract somewhere else.
2427
+ *
2428
+ * VALIDATED BEFORE IT IS STORED. A retained-era key is a `schnorr` key whose
2429
+ * value is exactly 64 hexadecimal characters, which is what that era's
2430
+ * `sampleSigningKey` produces; this type also admits `ecdsa` and values of any
2431
+ * length, and those are refused with `Ledger8SigningKeyError` (reason `'unusable'`).
2432
+ * Nothing is written when it is refused.
2433
+ *
2434
+ * Stored against {@link Ledger8FindDeployedContractOptions.contractAddress}
2435
+ * in the private-state provider, which is the same storage a deploy writes its
2436
+ * key to -- so a key supplied here REPLACES whatever is held for that
2437
+ * address, and is what `deployTxData.private.signingKey` on the found
2438
+ * handle then reports.
2439
+ *
2440
+ * OMITTING it reports the key already stored, and stores nothing. It does NOT
2441
+ * sample a fresh key when none is stored, where the current era's
2442
+ * `findDeployedContract` does.
2443
+ *
2444
+ * @remarks **Privacy-sensitive.** Signing-key material.
2445
+ * @see {@link KeepStatePipeline} for why this path samples nothing, and why a
2446
+ * supplied key replaces a stored one rather than falling back to it.
2447
+ */
2448
+ readonly signingKey?: SigningKey;
2449
+ }
2450
+ /**
2451
+ * Lifts every circuit a retained-era contract declares to a function that
2452
+ * builds and submits a call transaction against one address.
2453
+ *
2454
+ * Two signatures per circuit, as `Ledger9CircuitCallTxInterface` has: called with a
2455
+ * {@link Ledger8TransactionContext} first, the call joins that scope instead of being submitted on
2456
+ * its own. A scope made after the hard fork is a ledger 9 one, which a retained-era call cannot join
2457
+ * (`EraMismatchError`, reason `'ledger8-call-in-scope'`).
2458
+ */
2459
+ type Ledger8CircuitCallTxInterface<C extends Ledger8Contract> = {
2460
+ [PCK in Ledger8CircuitId<C>]: {
2461
+ (...args: Ledger8CircuitParameters<C, PCK>): Promise<Ledger8FinalizedCallTxData<C, PCK>>;
2462
+ (txCtx: Ledger8TransactionContext<C, PCK>, ...args: Ledger8CircuitParameters<C, PCK>): Promise<Ledger8UnsubmittedCallTxData<C, PCK>>;
2463
+ };
2464
+ };
2465
+ /**
2466
+ * The deploy data of a retained-era contract found on chain: the same
2467
+ * `{ era, public, private }` structure `Ledger9FoundDeployTxData`
2468
+ * has, so a caller reads `deployTxData.public.txId` and
2469
+ * `deployTxData.private.signingKey` identically in both eras.
2470
+ *
2471
+ * @remarks **Privacy-sensitive.** `private` carries signing-key material and
2472
+ * private state. Read only `public` when logging or transmitting.
2473
+ */
2474
+ interface Ledger8FoundDeployTxData<C extends Ledger8Contract> {
2475
+ /**
2476
+ * The pipeline this handle runs on: always the retained era here. The era
2477
+ * that recorded the deploy transaction is `public.era`.
2478
+ */
2479
+ readonly era: 'v8';
2480
+ /**
2481
+ * The record of the transaction that DEPLOYED the contract, and the address
2482
+ * it created. Version-tagged because a retained-era contract was deployed in
2483
+ * whichever era was current at the time — narrow it with
2484
+ * `switch (deployTxData.public.era)`.
2485
+ */
2486
+ readonly public: FinalizedTxRead & {
2487
+ readonly contractAddress: ContractAddress;
2488
+ /**
2489
+ * The deploy-time state of the contract, as `queryDeployContractState` serves it. Its `era`
2490
+ * names the ledger that wrote these bytes. Decode it with your own runtime of that era.
2491
+ */
2492
+ readonly initialContractState: SerializedContractState;
2493
+ };
2494
+ /**
2495
+ * What this device holds for the contract.
2496
+ *
2497
+ * @remarks **Privacy-sensitive.** Signing-key material and private state.
2498
+ */
2499
+ readonly private: {
2500
+ /**
2501
+ * The key this framework holds for the contract's maintenance authority, or
2502
+ * `undefined` when it holds none it can use.
2503
+ *
2504
+ * ALWAYS PRESENT and possibly `undefined`, rather than optional. REQUIRED on
2505
+ * {@link Ledger8FinalizedDeployTxData}: a deploy always has a key, because it built
2506
+ * the authority; an attach has one only if a deploy on this machine stored
2507
+ * it, or the caller supplied one through
2508
+ * {@link Ledger8FindDeployedContractOptions.signingKey}.
2509
+ *
2510
+ * `undefined` COLLAPSES THREE CASES, and a caller that needs to tell them
2511
+ * apart has to look at the logger rather than at this field:
2512
+ *
2513
+ * 1. nothing is stored for this address;
2514
+ * 2. something is stored that this framework did not write -- an entry naming
2515
+ * the other signature kind, which the CURRENT era legitimately stores
2516
+ * under the same address in the same provider, or one whose value is not
2517
+ * the shape a retained-era key has;
2518
+ * 3. the entry could not be READ at all, because `getSigningKey` rejected: a
2519
+ * wrong store password, a rotation-lock timeout, store I/O, or an entry the
2520
+ * provider refuses as not a signing key.
2521
+ *
2522
+ * Neither 2 nor 3 fails the attach. Both are reported to the logger provider
2523
+ * as a DEBUG-level dispatch breadcrumb, which is the only place the three
2524
+ * cases are distinguishable.
2525
+ *
2526
+ * The remedy for case 2, and for a refused entry in case 3, is the caller's
2527
+ * either way: pass the retained-era key on
2528
+ * {@link Ledger8FindDeployedContractOptions.signingKey}, which replaces the
2529
+ * entry, or remove the entry with
2530
+ * `privateStateProvider.removeSigningKey(address)` first.
2531
+ *
2532
+ * @remarks **Privacy-sensitive.** Signing-key material.
2533
+ * @see {@link KeepStatePipeline} for why the member is not optional, and why
2534
+ * an unreadable entry does not fail the attach.
2535
+ */
2536
+ readonly signingKey: SigningKey | undefined;
2537
+ /**
2538
+ * The private state the attach seeded, or the one already stored under the
2539
+ * id it named; `undefined` when it named none.
2540
+ *
2541
+ * @remarks **Privacy-sensitive.**
2542
+ */
2543
+ readonly initialPrivateState: Ledger8PrivateState<C> | undefined;
2544
+ };
2545
+ }
2546
+ /**
2547
+ * What a retained-era deploy builder answers with: everything the constructor produced and the
2548
+ * unproven transaction, before the chain has recorded anything. Nothing is stored yet; storing the
2549
+ * signing key and the private state once the deploy is final is the caller's job.
2550
+ */
2551
+ interface Ledger8UnsubmittedDeployTxData<C extends Ledger8Contract> {
2552
+ /** The pipeline that produced this result. A retained-era deploy runs only before the fork. */
2553
+ readonly era: 'v8';
2554
+ readonly public: {
2555
+ /** The address the composition minted, which no other deployment shares. */
2556
+ readonly contractAddress: ContractAddress;
2557
+ /** See {@link Ledger8FinalizedDeployTxData}. */
2558
+ readonly initialContractState: SerializedContractState<'v8'>;
2559
+ };
2560
+ readonly private: {
2561
+ /**
2562
+ * The key the maintenance authority is built from: the caller's, or a SAMPLED one. A sampled
2563
+ * key exists nowhere else, so a caller that submits this deploy has to store it.
2564
+ *
2565
+ * @remarks **Privacy-sensitive.** Signing-key material.
2566
+ */
2567
+ readonly signingKey: SigningKey;
2568
+ /**
2569
+ * The private state the constructor produced.
2570
+ *
2571
+ * @remarks **Privacy-sensitive.**
2572
+ */
2573
+ readonly initialPrivateState: Ledger8PrivateState<C>;
2574
+ /**
2575
+ * The Zswap local state the constructor ended on.
2576
+ *
2577
+ * @remarks **Privacy-sensitive.** Shielded coin material.
2578
+ */
2579
+ readonly initialZswapState: ZswapLocalState;
2580
+ /** The unproven deploy transaction, a ledger 8 one. */
2581
+ readonly unprovenTx: LedgerTransaction<'Unproven', 'v8'>;
2582
+ };
2583
+ }
2584
+ /**
2585
+ * The deploy data of a retained-era contract deployed by the caller: the
2586
+ * {@link Ledger8FoundDeployTxData} structure, carrying what the constructor
2587
+ * produced as well.
2588
+ *
2589
+ * @remarks **Privacy-sensitive.** `private` carries signing-key material,
2590
+ * private state and shielded coin material.
2591
+ */
2592
+ interface Ledger8FinalizedDeployTxData<C extends Ledger8Contract> extends Ledger8FoundDeployTxData<C> {
2593
+ /**
2594
+ * The record of the deploy transaction, always a ledger 8 one: a retained-era
2595
+ * deploy runs only before the fork.
2596
+ */
2597
+ readonly public: Omit<Ledger8FoundDeployTxPublicData, 'initialContractState'> & {
2598
+ /**
2599
+ * The state the contract was deployed with: the bytes the contract address
2600
+ * was derived from. A deploy mints a fresh nonce, so these bytes and that
2601
+ * address belong to each other and to no other deployment. Decode it with
2602
+ * your own ledger 8 runtime.
2603
+ */
2604
+ readonly initialContractState: SerializedContractState<'v8'>;
2605
+ };
2606
+ readonly private: {
2607
+ /**
2608
+ * The key the deployed contract's maintenance authority was built from: ONE
2609
+ * verifying key at threshold 1, so this single key is the whole authority.
2610
+ *
2611
+ * SAMPLED when the caller named none on the deploy options, and stored
2612
+ * against the contract address in the private-state provider once the chain
2613
+ * has recorded the deployment — the same storage and the same moment the
2614
+ * current era's deploy writes its own key to. Attaching to the same address
2615
+ * through the same provider reports it again.
2616
+ *
2617
+ * The provider is the ONLY copy besides this handle. It is not on chain and
2618
+ * not derivable from anything that is, so a store that is lost, cleared or
2619
+ * never persisted takes the authority with it: no verifier key can then be
2620
+ * inserted, removed or replaced on that contract by anyone.
2621
+ *
2622
+ * @remarks **Privacy-sensitive.** Signing-key material.
2623
+ */
2624
+ readonly signingKey: SigningKey;
2625
+ /**
2626
+ * The private state the constructor produced.
2627
+ *
2628
+ * @remarks **Privacy-sensitive.**
2629
+ */
2630
+ readonly initialPrivateState: Ledger8PrivateState<C>;
2631
+ /**
2632
+ * The Zswap local state the constructor ended on, carrying any coin it
2633
+ * minted. Empty for a constructor that minted none.
2634
+ *
2635
+ * @remarks **Privacy-sensitive.** Shielded coin material.
2636
+ */
2637
+ readonly initialZswapState: ZswapLocalState;
2638
+ };
2639
+ }
2640
+ /**
2641
+ * What a retained-era maintenance update resolves with once the chain has recorded it: the
2642
+ * retained era's counterpart of `Ledger9FinalizedMaintenanceTxData`.
2643
+ *
2644
+ * `public` is always the ledger 8 record. A retained-era artifact maintains a contract only before
2645
+ * the fork, so no other era can record the update.
2646
+ */
2647
+ interface Ledger8FinalizedMaintenanceTxData {
2648
+ /** The pipeline that produced this result: always the retained era here. */
2649
+ readonly era: 'v8';
2650
+ /** The finalized record of the maintenance transaction. */
2651
+ readonly public: Ledger8FinalizedTxData;
2652
+ }
2653
+ /**
2654
+ * Maintenance updates for one circuit of a retained-era contract, bound to one address: the
2655
+ * retained era's counterpart of `Ledger9CircuitMaintenanceTxInterface`.
2656
+ */
2657
+ interface Ledger8CircuitMaintenanceTxInterface {
2658
+ /** Removes the verifier key the contract holds for this circuit. */
2659
+ removeVerifierKey(): Promise<Ledger8FinalizedMaintenanceTxData>;
2660
+ /**
2661
+ * Inserts a verifier key for this circuit into a slot that holds none.
2662
+ *
2663
+ * @param newVk The verifier key to insert.
2664
+ */
2665
+ insertVerifierKey(newVk: VerifierKey): Promise<Ledger8FinalizedMaintenanceTxData>;
2666
+ }
2667
+ /** One {@link Ledger8CircuitMaintenanceTxInterface} per circuit the retained-era contract declares. */
2668
+ type Ledger8CircuitMaintenanceTxInterfaces<C extends Ledger8Contract> = Record<Ledger8CircuitId<C>, Ledger8CircuitMaintenanceTxInterface>;
2669
+ /**
2670
+ * Maintenance updates for a whole retained-era contract, bound to one address: the retained era's
2671
+ * counterpart of `Ledger9ContractMaintenanceTxInterface`.
2672
+ */
2673
+ interface Ledger8ContractMaintenanceTxInterface {
2674
+ /**
2675
+ * Replaces the contract's maintenance authority with one built from `newAuthority`, and stores
2676
+ * that key for the address once the chain has recorded the replacement.
2677
+ *
2678
+ * @param newAuthority The new authority's key: a `schnorr` key, as every ledger 8 key is.
2679
+ */
2680
+ replaceAuthority(newAuthority: SigningKey): Promise<Ledger8FinalizedMaintenanceTxData>;
2681
+ }
2682
+ /**
2683
+ * A retained-era contract found on the blockchain.
2684
+ *
2685
+ * Carries a {@link Ledger8CircuitCallTxInterface} for the same reason
2686
+ * `Ledger9FoundContract` carries one: a caller that has just supplied
2687
+ * the contract and its address should not have to supply them again to call it.
2688
+ *
2689
+ * It carries the maintenance interfaces `Ledger9FoundContract` carries,
2690
+ * for the same reason. They work only before the fork; after it, the same contract
2691
+ * is maintained through a handle built from the recompiled artifact.
2692
+ */
2693
+ interface Ledger8FoundContract<C extends Ledger8Contract> {
2694
+ /**
2695
+ * The pipeline that produced this result: always the retained era here, even
2696
+ * when the transaction that recorded it is a keep-state transaction tagged
2697
+ * `'v9'`. Those are different facts, and only this one says which module
2698
+ * produced the objects below.
2699
+ */
2700
+ readonly era: 'v8';
2701
+ /** The artifact this handle was built from: the caller's own contract instance, unchanged. */
2702
+ readonly compiledContract: C;
2703
+ /** The address on chain every call made through {@link Ledger8FoundContract.callTx} targets. */
2704
+ readonly contractAddress: ContractAddress;
2705
+ /**
2706
+ * The deploy record under `public` and what this device holds for the
2707
+ * contract under `private`, at the same paths as on the current era's
2708
+ * `Ledger9FoundContract.deployTxData`.
2709
+ */
2710
+ readonly deployTxData: Ledger8FoundDeployTxData<C>;
2711
+ /**
2712
+ * One function per circuit the artifact declares, each bound to
2713
+ * {@link Ledger8FoundContract.contractAddress} and to the private state id
2714
+ * the attach or the deploy named — so a call needs only the circuit's own
2715
+ * arguments.
2716
+ */
2717
+ readonly callTx: Ledger8CircuitCallTxInterface<C>;
2718
+ /** One maintenance interface per circuit the artifact declares, bound to this address. */
2719
+ readonly circuitMaintenanceTx: Ledger8CircuitMaintenanceTxInterfaces<C>;
2720
+ /** The contract-wide maintenance interface, bound to this address. */
2721
+ readonly contractMaintenanceTx: Ledger8ContractMaintenanceTxInterface;
2722
+ }
2723
+ /**
2724
+ * A retained-era contract deployed by the caller.
2725
+ *
2726
+ * It differs from {@link Ledger8FoundContract} only in its
2727
+ * {@link Ledger8DeployedContract.deployTxData}, which carries what the
2728
+ * constructor produced and a signing key that is always present.
2729
+ *
2730
+ * Exported flat so a caller that receives one by inference can also NAME it, and
2731
+ * a dApp's declaration emit can write it. This is what `deployContract`'s
2732
+ * retained-era overload answers with.
2733
+ */
2734
+ interface Ledger8DeployedContract<C extends Ledger8Contract> extends Ledger8FoundContract<C> {
2735
+ /** See {@link Ledger8FinalizedDeployTxData}. */
2736
+ readonly deployTxData: Ledger8FinalizedDeployTxData<C>;
2737
+ }
2738
+
2739
+ /**
2740
+ * An interface for creating maintenance transactions for a specific circuit defined in a
2741
+ * given contract.
2742
+ */
2743
+ interface Ledger9CircuitMaintenanceTxInterface {
2744
+ /**
2745
+ * Constructs and submits a transaction that removes the current verifier key stored
2746
+ * on the blockchain for this circuit at this contract's address.
2747
+ */
2748
+ removeVerifierKey(): Promise<Ledger9FinalizedMaintenanceTxData>;
2749
+ /**
2750
+ * Constructs and submits a transaction that adds a new verifier key to the
2751
+ * blockchain for this circuit at this contract's address.
2752
+ *
2753
+ * @param newVk The new verifier key to add for this circuit.
2754
+ */
2755
+ insertVerifierKey(newVk: VerifierKey): Promise<Ledger9FinalizedMaintenanceTxData>;
2756
+ }
2757
+ /**
2758
+ * Creates a {@link Ledger9CircuitMaintenanceTxInterface}, or the retained era's
2759
+ * `Ledger8CircuitMaintenanceTxInterface` for a contract the retained Compact toolchain produced.
2760
+ *
2761
+ * The contract's shape only picks which overload each method calls; the era itself is resolved by
2762
+ * that call, when the method runs.
2763
+ *
2764
+ * @param providers The providers to use to create and submit transactions.
2765
+ * @param circuitId The circuit ID the interface is for.
2766
+ * @param compiledContract The contract the circuit belongs to.
2767
+ * @param contractAddress The address of the deployed contract for which this
2768
+ * interface is being created.
2769
+ * @throws InvalidArgumentError If `contractAddress` is malformed.
2770
+ * @throws EraMismatchError If `compiledContract` has neither toolchain's shape.
2771
+ */
2772
+ declare function createCircuitMaintenanceTxInterface<C extends Ledger8Contract>(providers: Ledger8ContractProviders<C, Ledger8CircuitId<C>>, circuitId: Ledger8CircuitId<C>, compiledContract: C, contractAddress: ContractAddress$1): Ledger8CircuitMaintenanceTxInterface;
2773
+ declare function createCircuitMaintenanceTxInterface<C extends Contract.Any, PCK extends Contract.ProvableCircuitId<C>>(providers: Ledger9ContractProviders<C, PCK>, circuitId: PCK, compiledContract: CompiledContract.CompiledContract<C, any>, // eslint-disable-line @typescript-eslint/no-explicit-any
2774
+ contractAddress: ContractAddress$1): Ledger9CircuitMaintenanceTxInterface;
2775
+ /**
2776
+ * A set of maintenance transaction creation interfaces, one for each circuit defined in
2777
+ * a given contract, keyed by the circuit name.
2778
+ */
2779
+ type Ledger9CircuitMaintenanceTxInterfaces<C extends Contract.Any> = Record<Contract.ProvableCircuitId<C>, Ledger9CircuitMaintenanceTxInterface>;
2780
+ /**
2781
+ * Creates a {@link Ledger9CircuitMaintenanceTxInterfaces}, or the retained era's
2782
+ * `Ledger8CircuitMaintenanceTxInterfaces` for a contract the retained Compact toolchain produced.
2783
+ *
2784
+ * @param providers The providers to use to build transactions.
2785
+ * @param compiledContract The contract to use to execute circuits.
2786
+ * @param contractAddress The ledger address of the contract.
2787
+ * @throws InvalidArgumentError If `contractAddress` is malformed.
2788
+ * @throws EraMismatchError If `compiledContract` has neither toolchain's shape.
2789
+ */
2790
+ declare function createCircuitMaintenanceTxInterfaces<C extends Ledger8Contract>(providers: Ledger8ContractProviders<C, Ledger8CircuitId<C>>, compiledContract: C, contractAddress: ContractAddress$1): Ledger8CircuitMaintenanceTxInterfaces<C>;
2791
+ declare function createCircuitMaintenanceTxInterfaces<C extends Contract.Any>(providers: Ledger9ContractProviders<C>, compiledContract: CompiledContract.CompiledContract<C, any>, // eslint-disable-line @typescript-eslint/no-explicit-any
2792
+ contractAddress: ContractAddress$1): Ledger9CircuitMaintenanceTxInterfaces<C>;
2793
+ /**
2794
+ * Interface for creating maintenance transactions for a contract that was
2795
+ * deployed.
2796
+ */
2797
+ interface Ledger9ContractMaintenanceTxInterface {
2798
+ /**
2799
+ * Constructs and submits a transaction that replaces the maintenance
2800
+ * authority stored on the blockchain for this contract.
2801
+ *
2802
+ * @param newAuthority The new contract maintenance authority for this contract.
2803
+ */
2804
+ replaceAuthority(newAuthority: SigningKey): Promise<Ledger9FinalizedMaintenanceTxData>;
2805
+ }
2806
+ /**
2807
+ * Creates a {@link Ledger9ContractMaintenanceTxInterface}, or the retained era's
2808
+ * `Ledger8ContractMaintenanceTxInterface` for a contract the retained Compact toolchain produced.
2809
+ *
2810
+ * @param providers The providers to use to build transactions.
2811
+ * @param compiledContract The contract the interface is for.
2812
+ * @param contractAddress The ledger address of the contract.
2813
+ * @throws InvalidArgumentError If `contractAddress` is malformed.
2814
+ * @throws EraMismatchError If `compiledContract` has neither toolchain's shape.
2815
+ */
2816
+ declare function createContractMaintenanceTxInterface<C extends Ledger8Contract>(providers: Ledger8ContractProviders<C, Ledger8CircuitId<C>>, compiledContract: C, contractAddress: ContractAddress$1): Ledger8ContractMaintenanceTxInterface;
2817
+ declare function createContractMaintenanceTxInterface<C extends Contract.Any>(providers: Ledger9ContractProviders, compiledContract: CompiledContract.CompiledContract<C, any>, // eslint-disable-line @typescript-eslint/no-explicit-any
2818
+ contractAddress: ContractAddress$1): Ledger9ContractMaintenanceTxInterface;
2819
+
2820
+ /**
2821
+ * Enables cross-contract calls during circuit execution.
2822
+ */
2823
+ interface Ledger9CrossContractConfig {
2824
+ /**
2825
+ * Resolves the states of cross-contract call targets.
2826
+ */
2827
+ readonly publicDataProvider: PublicDataProvider;
2828
+ /**
2829
+ * The block at which all contract states are read; must be the block at which the initial states
2830
+ * given to the call were read.
2831
+ */
2832
+ readonly blockHash: string;
2833
+ /**
2834
+ * Resolves a callee's address to the module implementing it. Absent when the application
2835
+ * registered none, which a circuit that actually makes a call then fails on.
2836
+ */
2837
+ readonly moduleProvider?: ContractModuleProvider;
2838
+ }
2839
+ declare function createLedger9UnprovenCallTxFromInitialStates<C extends Contract<undefined>, PCK extends Contract.ProvableCircuitId<C>>(zkConfigProvider: ZKConfigProvider<string>, options: Ledger9CallOptionsWithProviderDataDependencies<C, PCK>, walletEncryptionPublicKey: EncPublicKey, crossContract?: Ledger9CrossContractConfig): Promise<Ledger9UnsubmittedCallTxData<C, PCK>>;
2840
+ declare function createLedger9UnprovenCallTxFromInitialStates<C extends Contract.Any, PCK extends Contract.ProvableCircuitId<C>>(zkConfigProvider: ZKConfigProvider<string>, options: Ledger9CallOptionsWithPrivateState<C, PCK>, walletEncryptionPublicKey: EncPublicKey, crossContract?: Ledger9CrossContractConfig): Promise<Ledger9UnsubmittedCallTxData<C, PCK>>;
2841
+ /**
2842
+ * Base type for configuration for a call transaction; identical to {@link Ledger9CallOptionsWithArguments}.
2843
+ */
2844
+ type Ledger9CallTxOptionsBase<C extends Contract.Any, PCK extends Contract.ProvableCircuitId<C>> = Ledger9CallOptionsWithArguments<C, PCK>;
2845
+ /**
2846
+ * Call transaction options with the private state ID to use to store the new private
2847
+ * state resulting from the circuit call. Since a private state should already be
2848
+ * stored at the given private state ID, we don't need an 'initialPrivateState' like
2849
+ * in {@link Ledger9DeployTxOptionsWithPrivateState}.
2850
+ */
2851
+ type Ledger9CallTxOptionsWithPrivateStateId<C extends Contract.Any, PCK extends Contract.ProvableCircuitId<C>> = Ledger9CallTxOptionsBase<C, PCK> & {
2852
+ /**
2853
+ * The identifier for the private state of the contract.
2854
+ */
2855
+ readonly privateStateId: PrivateStateId;
2856
+ };
2857
+ /**
2858
+ * Call transaction configuration.
2859
+ */
2860
+ type Ledger9CallTxOptions<C extends Contract.Any, PCK extends Contract.ProvableCircuitId<C>> = Ledger9CallTxOptionsBase<C, PCK> | Ledger9CallTxOptionsWithPrivateStateId<C, PCK>;
2861
+ /**
2862
+ * The minimum set of providers needed to create a call transaction, the ZK
2863
+ * artifact provider and a wallet. By defining this type, users can choose to
2864
+ * omit a private state provider if they're creating a call transaction for a
2865
+ * contract with no private state.
2866
+ */
2867
+ type UnprovenCallTxProvidersBase = Pick<MidnightProviders, 'zkConfigProvider' | 'publicDataProvider' | 'walletProvider' | 'contractModuleProvider' | 'config'>;
2868
+ /**
2869
+ * Same providers as {@link UnprovenCallTxProvidersBase} with an additional private
2870
+ * state provider to store the new private state resulting from the circuit call -
2871
+ * only used when creating a call transaction for a contract with a private state.
2872
+ */
2873
+ type Ledger9UnprovenCallTxProvidersWithPrivateState<C extends Contract.Any> = UnprovenCallTxProvidersBase & Pick<Ledger9ContractProviders<C>, 'privateStateProvider'>;
2874
+ declare function createLedger9UnprovenCallTx<C extends Contract<undefined>, PCK extends Contract.ProvableCircuitId<C>>(providers: UnprovenCallTxProvidersBase, options: Ledger9CallTxOptionsBase<C, PCK>, transactionContext?: Ledger9TransactionContext<C, PCK>): Promise<Ledger9UnsubmittedCallTxData<C, PCK>>;
2875
+ declare function createLedger9UnprovenCallTx<C extends Contract.Any, PCK extends Contract.ProvableCircuitId<C>>(providers: Ledger9UnprovenCallTxProvidersWithPrivateState<C>, options: Ledger9CallTxOptionsWithPrivateStateId<C, PCK>, transactionContext?: Ledger9TransactionContext<C, PCK>): Promise<Ledger9UnsubmittedCallTxData<C, PCK>>;
2876
+ declare function createLedger8UnprovenCallTx<C extends Ledger8Contract, PCK extends Ledger8CircuitId<C>>(providers: Ledger8ContractProviders<C, PCK>, options: Ledger8CallTxOptions<C, PCK>, transactionContext?: Ledger8TransactionContext<C, PCK>): Promise<Ledger8UnsubmittedCallTxData<C, PCK>>;
2877
+ declare function createLedger8UnprovenCallTxFromInitialStates<C extends Ledger8Contract, PCK extends Ledger8CircuitId<C>>(zkConfigProvider: ZKConfigProvider<string>, options: Ledger8CallOptionsWithInitialStates<C, PCK>, walletEncryptionPublicKey: EncPublicKey): Promise<Ledger8UnsubmittedCallTxData<C, PCK>>;
2878
+ declare function createUnprovenCallTxFromInitialStates<C extends Ledger8Contract, PCK extends Ledger8CircuitId<C>>(zkConfigProvider: ZKConfigProvider<string>, options: Ledger8CallOptionsWithInitialStates<C, PCK>, walletEncryptionPublicKey: EncPublicKey): Promise<Ledger8UnsubmittedCallTxData<C, PCK>>;
2879
+ declare function createUnprovenCallTxFromInitialStates<C extends Contract<undefined>, PCK extends Contract.ProvableCircuitId<C>>(zkConfigProvider: ZKConfigProvider<string>, options: Ledger9CallOptionsWithProviderDataDependencies<C, PCK>, walletEncryptionPublicKey: EncPublicKey, crossContract?: Ledger9CrossContractConfig): Promise<Ledger9UnsubmittedCallTxData<C, PCK>>;
2880
+ declare function createUnprovenCallTxFromInitialStates<C extends Contract.Any, PCK extends Contract.ProvableCircuitId<C>>(zkConfigProvider: ZKConfigProvider<string>, options: Ledger9CallOptionsWithPrivateState<C, PCK>, walletEncryptionPublicKey: EncPublicKey, crossContract?: Ledger9CrossContractConfig): Promise<Ledger9UnsubmittedCallTxData<C, PCK>>;
2881
+ declare function createUnprovenCallTx<C extends Ledger8Contract, PCK extends Ledger8CircuitId<C>>(providers: Ledger8ContractProviders<C, PCK>, options: Ledger8CallTxOptions<C, PCK>, transactionContext?: Ledger8TransactionContext<C, PCK>): Promise<Ledger8UnsubmittedCallTxData<C, PCK>>;
2882
+ declare function createUnprovenCallTx<C extends Contract<undefined>, PCK extends Contract.ProvableCircuitId<C>>(providers: UnprovenCallTxProvidersBase, options: Ledger9CallTxOptionsBase<C, PCK>, transactionContext?: Ledger9TransactionContext<C, PCK>): Promise<Ledger9UnsubmittedCallTxData<C, PCK>>;
2883
+ declare function createUnprovenCallTx<C extends Contract.Any, PCK extends Contract.ProvableCircuitId<C>>(providers: Ledger9UnprovenCallTxProvidersWithPrivateState<C>, options: Ledger9CallTxOptionsWithPrivateStateId<C, PCK>, transactionContext?: Ledger9TransactionContext<C, PCK>): Promise<Ledger9UnsubmittedCallTxData<C, PCK>>;
2884
+
2885
+ /**
2886
+ * A type that lifts each circuit defined in a contract to a function that builds
2887
+ * and submits a call transaction.
2888
+ */
2889
+ type Ledger9CircuitCallTxInterface<C extends Contract.Any> = {
2890
+ [PCK in Contract.ProvableCircuitId<C>]: {
2891
+ (...args: Contract.CircuitParameters<C, PCK>): Promise<Ledger9FinalizedCallTxData<C, PCK>>;
2892
+ (txCtx: Ledger9TransactionContext<C, PCK>, ...args: Contract.CircuitParameters<C, PCK>): Promise<Ledger9CallResult<C, PCK>>;
2893
+ };
2894
+ };
2895
+ /**
2896
+ * Creates the options `submitCallTx` takes to call one circuit: a {@link Ledger9CallTxOptions} for a
2897
+ * ledger 9 `CompiledContract`, or a {@link Ledger8CallTxOptions} for a ledger 8 contract.
2898
+ *
2899
+ * `args` is left out for a circuit that takes no arguments, and `privateStateId` when it is
2900
+ * `undefined`. `circuitId` must be a circuit the contract declares; a plain string literal is
2901
+ * accepted.
2902
+ *
2903
+ * @param compiledContract The contract the circuit belongs to.
2904
+ * @param circuitId The circuit to call.
2905
+ * @param contractAddress The ledger address of the contract.
2906
+ * @param privateStateId Where to read and store the contract's private state,
2907
+ * or `undefined` for a contract that carries none.
2908
+ * @param additionalCoinEncPublicKeyMappings Encryption keys for shielded coins the circuit pays
2909
+ * to a recipient other than the calling wallet, or `undefined` for none.
2910
+ * @param args The circuit's own arguments.
2911
+ * @throws EraMismatchError If `compiledContract` has the shape of neither a ledger 8
2912
+ * contract nor a ledger 9 `CompiledContract`.
2913
+ */
2914
+ declare function createCallTxOptions<C extends Ledger8Contract, PCK extends Ledger8CircuitId<C>>(compiledContract: C, circuitId: PCK, contractAddress: ContractAddress$1, privateStateId: PrivateStateId | undefined, additionalCoinEncPublicKeyMappings: ReadonlyMap<CoinPublicKey$1, EncPublicKey> | undefined, args: Ledger8CircuitParameters<C, PCK>): Ledger8CallTxOptions<C, PCK>;
2915
+ declare function createCallTxOptions<C extends Contract.Any, PCK extends Contract.ProvableCircuitId<C>>(compiledContract: CompiledContract.CompiledContract<C, any>, // eslint-disable-line @typescript-eslint/no-explicit-any
2916
+ circuitId: PCK, contractAddress: ContractAddress$1, privateStateId: PrivateStateId | undefined, additionalCoinEncPublicKeyMappings: ReadonlyMap<CoinPublicKey$1, EncPublicKey> | undefined, args: Contract.CircuitParameters<C, PCK>): Ledger9CallTxOptions<C, PCK>;
2917
+ /**
2918
+ * Creates a {@link Ledger9CircuitCallTxInterface}, or the retained era's `Ledger8CircuitCallTxInterface`
2919
+ * for a contract the retained Compact toolchain produced.
2920
+ *
2921
+ * @param providers The providers to use to build transactions.
2922
+ * @param compiledContract The contract to use to execute circuits.
2923
+ * @param contractAddress The ledger address of the contract.
2924
+ * @param privateStateId The identifier of the state of the witnesses of the contract,
2925
+ * or `undefined` for a contract that carries none.
2926
+ * @throws InvalidArgumentError If `contractAddress` is malformed.
2927
+ * @throws EraMismatchError If `compiledContract` has the shape of neither a ledger 8
2928
+ * contract nor a ledger 9 `CompiledContract`.
2929
+ */
2930
+ declare function createCircuitCallTxInterface<C extends Ledger8Contract>(providers: Ledger8ContractProviders<C, Ledger8CircuitId<C>>, compiledContract: C, contractAddress: ContractAddress$1, privateStateId: PrivateStateId | undefined): Ledger8CircuitCallTxInterface<C>;
2931
+ declare function createCircuitCallTxInterface<C extends Contract.Any>(providers: Ledger9ContractProviders<C>, compiledContract: CompiledContract.CompiledContract<C, any>, // eslint-disable-line @typescript-eslint/no-explicit-any
2932
+ contractAddress: ContractAddress$1, privateStateId: PrivateStateId | undefined): Ledger9CircuitCallTxInterface<C>;
2933
+
2934
+ /**
2935
+ * Checks that two verifier keys are equal. Does initial length check match for efficiency.
2936
+ *
2937
+ * @param a First verifier key.
2938
+ * @param b Second verifier key.
2939
+ */
2940
+ declare const verifierKeysEqual: (a: Uint8Array, b: Uint8Array) => boolean;
2941
+ /**
2942
+ * Checks that the given `contractState` contains the given `verifierKeys`.
2943
+ *
2944
+ * A circuit fails the check when the state registers no operation for it, when the registered
2945
+ * operation carries no verifier key at all, or when the deployed key differs from the local one.
2946
+ * The three are reported separately on the thrown error, because only the last one means the local
2947
+ * artifacts are at fault.
2948
+ *
2949
+ * @param verifierKeys The verifier keys the client has for the deployed contract we're checking.
2950
+ * @param contractState The (typically already deployed) contract state containing verifier keys, of
2951
+ * either ledger era, as a read returns it: pass `read.contractState`. A state
2952
+ * written by the v8 ledger loads the ledger 8 runtime to be decoded.
2953
+ * @param contractAddress The address `contractState` was read from, used to identify the contract
2954
+ * in the thrown error.
2955
+ *
2956
+ * @throws UnknownLedgerEraError When `contractState` names an era this build does not know.
2957
+ * @throws InvalidArgumentError When `contractState` is not a `SerializedContractState`.
2958
+ * @throws InvalidSerializedStateError When its bytes are not a contract state of its era, for example
2959
+ * ledger parameters, or a state from another copy of the types
2960
+ * package whose bytes carry another tag.
2961
+ * @throws SerializedStateDecodeFailedError, or the framework decoder's coded error, When the bytes
2962
+ * after the tag do not decode.
2963
+ * @throws Ledger8RuntimeMissingError When a v8 state is passed and the ledger 8 runtime cannot load.
2964
+ * @throws ContractTypeError When any circuit is missing from `contractState`, has no deployed
2965
+ * verifier key, or has a key differing from the local one.
2966
+ */
2967
+ declare const verifyContractState: (verifierKeys: [AnyProvableCircuitId, VerifierKey][], contractState: SerializedContractState, contractAddress?: ContractAddress) => Promise<void>;
2968
+ /**
2969
+ * Base type for the configuration options for {@link findDeployedContract}.
2970
+ */
2971
+ interface Ledger9FindDeployedContractOptionsBase<C extends Contract$1.Any> {
2972
+ /**
2973
+ * The compiled contract to use to execute circuits.
2974
+ */
2975
+ readonly compiledContract: CompiledContract.CompiledContract<C, any>;
2976
+ /**
2977
+ * The address of a previously deployed contract.
2978
+ */
2979
+ readonly contractAddress: ContractAddress;
2980
+ /**
2981
+ * The signing key to use to perform contract maintenance updates. If defined, the given signing
2982
+ * key is stored for this contract address. This is useful when someone has already added the given signing
2983
+ * key to the contract maintenance authority. If undefined, and there is an existing signing key for the
2984
+ * contract address locally, the existing signing key is kept. This is useful when the contract was
2985
+ * deployed locally. If undefined, and there is not an existing signing key for the contract address
2986
+ * locally, a fresh signing key is generated and stored for the contract address locally. This is
2987
+ * useful when you want to give a signing key to someone else to add you as a maintenance authority.
2988
+ */
2989
+ readonly signingKey?: SigningKey;
2990
+ }
2991
+ /**
2992
+ * {@link findDeployedContract} base configuration that includes an initial private
2993
+ * state to store and the private state ID at which to store it. Only used if
2994
+ * the intention is to overwrite the private state currently stored at the given
2995
+ * private state ID.
2996
+ */
2997
+ interface Ledger9FindDeployedContractOptionsExistingPrivateState<C extends Contract$1.Any> extends Ledger9FindDeployedContractOptionsBase<C> {
2998
+ /**
2999
+ * An identifier for the private state of the contract being found.
3000
+ */
3001
+ readonly privateStateId: PrivateStateId;
3002
+ }
3003
+ /**
3004
+ * {@link findDeployedContract} configuration that includes an initial private
3005
+ * state to store and the private state ID at which to store it. Only used if
3006
+ * the intention is to overwrite the private state currently stored at the given
3007
+ * private state ID.
3008
+ */
3009
+ interface Ledger9FindDeployedContractOptionsStorePrivateState<C extends Contract$1.Any> extends Ledger9FindDeployedContractOptionsExistingPrivateState<C> {
3010
+ /**
3011
+ * For types of contract that make no use of private state and or witnesses that operate upon it, this
3012
+ * property may be `undefined`. Otherwise, the value provided via this property should be same initial
3013
+ * state that was used when calling {@link deployContract}.
3014
+ */
3015
+ readonly initialPrivateState: Contract$1.PrivateState<C>;
3016
+ }
3017
+ /**
3018
+ * Configuration for {@link findDeployedContract}.
3019
+ */
3020
+ type Ledger9FindDeployedContractOptions<C extends Contract$1.Any> = Ledger9FindDeployedContractOptionsBase<C> | Ledger9FindDeployedContractOptionsExistingPrivateState<C> | Ledger9FindDeployedContractOptionsStorePrivateState<C>;
3021
+ /**
3022
+ * Base type for a deployed contract that has been found on the blockchain.
3023
+ */
3024
+ interface Ledger9FoundContract<C extends Contract$1.Any> {
3025
+ /**
3026
+ * The pipeline that produced this result: always ledger 9 here.
3027
+ *
3028
+ * Read off the compiled artifact, NEVER off a transaction record — the two
3029
+ * facts disagree after the fork, and only this one says which module the
3030
+ * objects in this result came from.
3031
+ */
3032
+ readonly era: 'v9';
3033
+ /**
3034
+ * The compiled contract this handle executes circuits from, exactly as the
3035
+ * caller supplied it.
3036
+ */
3037
+ readonly compiledContract: CompiledContract.CompiledContract<C, any>;
3038
+ /**
3039
+ * The ledger address this handle is attached to.
3040
+ */
3041
+ readonly contractAddress: ContractAddress;
3042
+ /**
3043
+ * Data for the finalized deploy transaction corresponding to this contract. The deploy record is
3044
+ * tagged with the ledger era that recorded it: narrow on `public.era` before reading `tx` or
3045
+ * `initialContractState`.
3046
+ */
3047
+ readonly deployTxData: Ledger9FoundDeployTxData<C>;
3048
+ /**
3049
+ * Interface for creating call transactions for a contract.
3050
+ */
3051
+ readonly callTx: Ledger9CircuitCallTxInterface<C>;
3052
+ /**
3053
+ * An interface for creating maintenance transactions for circuits defined in the
3054
+ * contract that was deployed.
3055
+ */
3056
+ readonly circuitMaintenanceTx: Ledger9CircuitMaintenanceTxInterfaces<C>;
3057
+ /**
3058
+ * Interface for creating maintenance transactions for the contract that was
3059
+ * deployed.
3060
+ */
3061
+ readonly contractMaintenanceTx: Ledger9ContractMaintenanceTxInterface;
3062
+ }
3063
+ /**
3064
+ * The retained-era overload. Accepts a contract produced by the PREVIOUS Compact toolchain, passed as
3065
+ * the raw contract instance rather than inside a `CompiledContract` container.
3066
+ *
3067
+ * Nothing is COMPOSED and nothing is submitted: no transaction leaves this call. It reads the
3068
+ * network's ledger version, checks the fetched state's version tag against it, and byte-matches every local verifier
3069
+ * key against the slot the chain holds — the checks that make a later call against this contract
3070
+ * safe, done once here so a mis-dispatch is caught at attach time rather than at the first call.
3071
+ *
3072
+ * It does write LOCALLY. Supplying `initialPrivateState` alongside `privateStateId` names the
3073
+ * contract address on the private-state provider and stores that state under the id, so the calls
3074
+ * made through `callTx` read it back. Supplying it with no id is a caller error —
3075
+ * `IncompleteFindContractPrivateStateConfig` — because there is nowhere to put the state, and so
3076
+ * is writing `privateStateId` with an undefined value. Naming an id the provider holds nothing
3077
+ * under is refused too, rather than attaching against a state the contract never had.
3078
+ *
3079
+ * The deploy record is returned ERA-TAGGED rather than narrowed to the current era, so it needs
3080
+ * narrowing on `era` before `tx` is touched.
3081
+ *
3082
+ * @throws IncompleteFindContractPrivateStateConfig if an `initialPrivateState` is supplied with no
3083
+ * `privateStateId` to store it under.
3084
+ *
3085
+ * @see {@link OverloadTyping} for how the two eras are discriminated, and why the record is
3086
+ * era-tagged.
3087
+ */
3088
+ declare function findDeployedContract<C extends Ledger8Contract>(providers: Ledger8ContractProviders<C, Ledger8CircuitId<C>>, options: Ledger8FindDeployedContractOptions<C>): Promise<Ledger8FoundContract<C>>;
3089
+ /**
3090
+ * Attaches to a deployed contract that declares no private state.
3091
+ */
3092
+ declare function findDeployedContract<C extends Contract$1<undefined>>(providers: Ledger9ContractProviders<C, Contract$1.ProvableCircuitId<C>, unknown>, options: Ledger9FindDeployedContractOptionsBase<C>): Promise<Ledger9FoundContract<C>>;
3093
+ /**
3094
+ * Attaches to a deployed contract, reusing the private state already stored at `privateStateId`.
3095
+ */
3096
+ declare function findDeployedContract<C extends Contract$1.Any>(providers: Ledger9ContractProviders<C>, options: Ledger9FindDeployedContractOptionsExistingPrivateState<C>): Promise<Ledger9FoundContract<C>>;
3097
+ /**
3098
+ * Attaches to a deployed contract, storing the given `initialPrivateState` at `privateStateId`.
3099
+ */
3100
+ declare function findDeployedContract<C extends Contract$1.Any>(providers: Ledger9ContractProviders<C>, options: Ledger9FindDeployedContractOptionsStorePrivateState<C>): Promise<Ledger9FoundContract<C>>;
3101
+
3102
+ /**
3103
+ * What both {@link deployContract} option variants carry, and nothing either variant
3104
+ * decides. Identical to {@link Ledger9ContractConstructorOptionsWithArguments} except
3105
+ * the `signingKey` is now optional, since {@link deployContract} will generate a
3106
+ * fresh signing key in the event that `signingKey` is undefined.
3107
+ *
3108
+ * Neither variant extends the other. Written as an intersection alias, a variant
3109
+ * declaring `privateStateId: PrivateStateId` over a base declaring
3110
+ * `privateStateId?: never` collapses that member to `never` and leaves the
3111
+ * private-state variant uninhabitable — so the pairing rule can only be stated by
3112
+ * making the two variants siblings over this.
3113
+ *
3114
+ * {@link Ledger8DeployContractOptionsShared} plays the same role for the
3115
+ * retained era, which arrives there by a different route: its variants are
3116
+ * interfaces, and an interface redeclaring the member is rejected outright as an
3117
+ * incompatible extension. This era cannot use interfaces, because `args` reaches
3118
+ * both variants through the {@link Ledger9ContractConstructorOptionsWithArguments}
3119
+ * conditional and an interface cannot extend a conditional type.
3120
+ *
3121
+ * PUBLISHED, unlike its retained-era counterpart, purely so the two members
3122
+ * below keep a documented page of their own: TypeDoc inlines the members an
3123
+ * interface inherits, but renders an unexported alias as bare text, which would
3124
+ * delete `signingKey` and `additionalCoinEncPublicKeyMappings` from the
3125
+ * reference for both variants.
3126
+ */
3127
+ type Ledger9DeployContractOptionsShared<C extends Contract.Any> = Ledger9ContractConstructorOptionsWithArguments<C> & {
3128
+ /**
3129
+ * An optional mapping of {@link CoinPublicKey} to {@link EncPublicKey} that can be used to resolve encryption
3130
+ * keys for coins created in the contract constructor. This is useful in cases where the constructor creates
3131
+ * outputs to addresses that don't belong to the current user.
3132
+ */
3133
+ readonly additionalCoinEncPublicKeyMappings?: ReadonlyMap<CoinPublicKey$1, EncPublicKey>;
3134
+ /**
3135
+ * The signing key to add as the to-be-deployed contract's maintenance authority.
3136
+ * If undefined, a new signing key is sampled and used as the CMA then stored
3137
+ * in the private state provider under the newly deployed contract's address.
3138
+ * Otherwise, the passed signing key is added as the CMA. The second case is
3139
+ * useful when you want to use the same CMA for two different contracts.
3140
+ */
3141
+ readonly signingKey?: SigningKey;
3142
+ };
3143
+ /**
3144
+ * The {@link deployContract} options variant for a contract whose private state is stored
3145
+ * NOWHERE: the constructor runs against `undefined` and nothing is written.
3146
+ *
3147
+ * The other variant is {@link Ledger9DeployContractOptionsWithPrivateState}.
3148
+ */
3149
+ type Ledger9DeployContractOptionsBase<C extends Contract.Any> = Ledger9DeployContractOptionsShared<C> & {
3150
+ /**
3151
+ * DECLARED on this variant, and only ever `undefined`.
3152
+ *
3153
+ * Left off the variant entirely, `{ compiledContract, privateStateId: 'x' }`
3154
+ * compiled: union excess-property checking admits a member declared on the
3155
+ * SIBLING variant as long as one variant is satisfied, and `compiledContract` alone
3156
+ * satisfies this one. The constructor then ran against `undefined`,
3157
+ * `undefined` was stored under the caller's id, and
3158
+ * `deployTxData.private.initialPrivateState` was typed non-optional while
3159
+ * actually undefined.
3160
+ */
3161
+ readonly privateStateId?: never;
3162
+ /**
3163
+ * DECLARED on this variant, and only ever `undefined` — see
3164
+ * {@link Ledger9DeployContractOptionsBase.privateStateId} for why the member is
3165
+ * present rather than absent.
3166
+ */
3167
+ readonly initialPrivateState?: never;
3168
+ };
3169
+ /**
3170
+ * {@link deployContract} options with information needed to store private states;
3171
+ * only used if the contract being deployed has a private state.
3172
+ *
3173
+ * Both members together or neither: a state with no id has nowhere to go, and
3174
+ * an id with no state stores `undefined` under a name a later call will read
3175
+ * back.
3176
+ */
3177
+ type Ledger9DeployContractOptionsWithPrivateState<C extends Contract.Any> = Ledger9DeployContractOptionsShared<C> & {
3178
+ /**
3179
+ * An identifier for the private state of the contract being deployed.
3180
+ */
3181
+ readonly privateStateId: PrivateStateId;
3182
+ /**
3183
+ * The private state to run the circuit against.
3184
+ */
3185
+ readonly initialPrivateState: Contract.PrivateState<C>;
3186
+ };
3187
+ /**
3188
+ * Configuration for {@link deployContract}.
3189
+ */
3190
+ type Ledger9DeployContractOptions<C extends Contract.Any> = Ledger9DeployContractOptionsBase<C> | Ledger9DeployContractOptionsWithPrivateState<C>;
3191
+ /**
3192
+ * Interface for a contract that has been deployed to the blockchain.
3193
+ */
3194
+ interface Ledger9DeployedContract<C extends Contract.Any> extends Ledger9FoundContract<C> {
3195
+ /**
3196
+ * Data resulting from the deployment transaction that created this contract. The information in a
3197
+ * {@link deployTxData} contains additional private information that does not
3198
+ * exist in {@link Ledger9FoundContract.deployTxData} because certain private data is only available to
3199
+ * the deployer of a contract.
3200
+ */
3201
+ readonly deployTxData: Ledger9FinalizedDeployTxData<C>;
3202
+ }
3203
+ /**
3204
+ * The retained-era overload. Accepts a contract produced by the PREVIOUS Compact toolchain, passed as
3205
+ * the raw contract instance rather than inside a `CompiledContract` container.
3206
+ *
3207
+ * Reachable only BEFORE THE FORK: the retained era has no post-fork deployment, so a retained
3208
+ * artifact after the fork is refused with `EraMismatchError` (reason `'ledger8-deploy-on-ledger9-network'`). Recompile with the
3209
+ * current toolchain and deploy that artifact instead; the retained artifact keeps working for calls
3210
+ * against contracts deployed before the fork.
3211
+ *
3212
+ * A verifier key is registered for every entry point the artifact declares.
3213
+ *
3214
+ * A maintenance authority of one key at threshold 1 is registered, that key being
3215
+ * `options.signingKey` or a freshly sampled one. Once the chain has recorded the deployment the key
3216
+ * is stored against the minted address through `providers.privateStateProvider` and reported at
3217
+ * `deployTxData.private.signingKey`. THAT PROVIDER IS THE ONLY COPY besides the returned handle:
3218
+ * the key is not on chain and not derivable from anything that is, so a store that is lost or
3219
+ * cleared leaves a contract on which no verifier key can ever be inserted, removed or replaced by
3220
+ * anyone.
3221
+ *
3222
+ * @see {@link OverloadTyping} for how the two eras are discriminated.
3223
+ * @see {@link KeepStatePipeline} for why every slot has to be registered here, and for the
3224
+ * maintenance authority this builds.
3225
+ */
3226
+ declare function deployContract<C extends Ledger8Contract>(providers: Ledger8ContractProviders<C, Ledger8CircuitId<C>>, options: Ledger8DeployContractOptions<C>): Promise<Ledger8DeployedContract<C>>;
3227
+ /**
3228
+ * Deploys a contract that declares no private state, so no private state id is required.
3229
+ */
3230
+ declare function deployContract<C extends Contract<undefined>>(providers: Ledger9ContractProviders<C, Contract.ProvableCircuitId<C>, unknown>, options: Ledger9DeployContractOptionsBase<C>): Promise<Ledger9DeployedContract<C>>;
3231
+ /**
3232
+ * Deploys a contract that declares private state, naming where to store the initial state.
3233
+ */
3234
+ declare function deployContract<C extends Contract.Any>(providers: Ledger9ContractProviders<C>, options: Ledger9DeployContractOptionsWithPrivateState<C>): Promise<Ledger9DeployedContract<C>>;
3235
+
3236
+ /**
3237
+ * The publicly visible states of a contract, as bytes, together with the private state of the
3238
+ * contract. Decode a public state with your own runtime, e.g.
3239
+ * `states.contractState.deserialize({ v9: ContractState })`.
3240
+ */
3241
+ type ContractStates<PS> = PublicStatesRead & {
3242
+ /**
3243
+ * The private state of a contract.
3244
+ */
3245
+ readonly privateState: PS;
3246
+ };
3247
+ /**
3248
+ * Fetches only the public visible (Zswap and ledger) states of a contract, as bytes with the
3249
+ * era of the ledger that wrote them.
3250
+ *
3251
+ * @param publicDataProvider The provider to use to fetch the public states (Zswap and ledger)
3252
+ * from the blockchain.
3253
+ * @param contractAddress The ledger address of the contract.
3254
+ * @param blockHash The block to read the states at. If `undefined`, the latest states are read.
3255
+ */
3256
+ declare const getPublicStates: (publicDataProvider: PublicDataProvider, contractAddress: ContractAddress$1, blockHash?: string) => Promise<PublicStatesRead>;
3257
+ /**
3258
+ * Retrieves the Zswap, ledger, and private states of the contract corresponding
3259
+ * to the given identifier using the given providers.
3260
+ *
3261
+ * @param publicDataProvider The provider to use to fetch the public states (Zswap and ledger)
3262
+ * from the blockchain.
3263
+ * @param privateStateProvider The provider to use to fetch the private state.
3264
+ * @param contractAddress The ledger address of the contract.
3265
+ * @param privateStateId The identifier for the private state of the contract.
3266
+ * @param blockHash The block to read the public states at. If `undefined`, the latest states are read.
3267
+ */
3268
+ declare const getStates: <PS>(publicDataProvider: PublicDataProvider, privateStateProvider: PrivateStateProvider<PrivateStateId, PS>, contractAddress: ContractAddress$1, privateStateId: PrivateStateId, blockHash?: string) => Promise<ContractStates<PS>>;
3269
+
3270
+ /**
3271
+ * Fetches the unshielded balances associated with a specific contract address.
3272
+ *
3273
+ * @param publicDataProvider The provider to use to fetch the unshielded balances from the blockchain.
3274
+ * @param contractAddress The ledger address of the contract.
3275
+ */
3276
+ declare const getUnshieldedBalances: (publicDataProvider: PublicDataProvider, contractAddress: ContractAddress$1) => Promise<UnshieldedBalances>;
3277
+
3278
+ /**
3279
+ * Constructs and submits a transaction that adds a new verifier key to the
3280
+ * blockchain for the given circuit ID at the given contract address.
3281
+ *
3282
+ * ## Transaction Execution Phases
3283
+ *
3284
+ * Midnight transactions execute in two phases:
3285
+ * 1. **Guaranteed phase**: If failure occurs, the transaction is NOT included in the blockchain
3286
+ * 2. **Fallible phase**: If failure occurs, the transaction IS recorded on-chain as a partial success
3287
+ *
3288
+ * ## Failure Behavior
3289
+ *
3290
+ * **Guaranteed Phase Failure:**
3291
+ * - Transaction is rejected and not included in the blockchain
3292
+ * - `TxFailedError` is thrown with transaction data
3293
+ * - Verifier key is NOT added to the contract
3294
+ * - No on-chain record of the failed transaction
3295
+ *
3296
+ * **Fallible Phase Failure:**
3297
+ * - Transaction is recorded on-chain with non-`SucceedEntirely` status
3298
+ * - `TxFailedError` is thrown with transaction data
3299
+ * - Verifier key may be partially added but not usable
3300
+ * - Transaction appears in blockchain history as partial success
3301
+ *
3302
+ * @param providers The providers to use to manage the transaction lifecycle.
3303
+ * @param compiledContract The contract the circuit belongs to.
3304
+ * @param contractAddress The address of the contract containing the circuit for which
3305
+ * the verifier key should be inserted.
3306
+ * @param circuitId The circuit for which the verifier key should be inserted.
3307
+ * @param newVk The new verifier key for the circuit.
3308
+ *
3309
+ * @returns A promise that resolves with the finalized transaction data under `public`, tagged
3310
+ * with the pipeline's `era`, or rejects if an error occurs along the way.
3311
+ *
3312
+ * @throws {TxFailedError} When transaction fails in either guaranteed or fallible phase.
3313
+ * The error contains the finalized transaction data for debugging. Raised by both eras;
3314
+ * `record.era` tells which.
3315
+ * @throws {EraMismatchError} with reason `'ledger8-maintenance-on-ledger9-network'` When a retained-era artifact is used after the fork.
3316
+ * @throws {Ledger8SigningKeyError} with reason `'unavailable'` When the retained-era overload finds no usable key.
3317
+ * @throws {MaintenanceAuthorityMismatchError} When the retained-era overload holds a key that is not
3318
+ * the contract's maintenance authority. Raised before anything is proven.
3319
+ * @throws {InvalidArgumentError} When the circuit's verifier key slot already holds a key, or the
3320
+ * retained-era artifact declares no such circuit. Raised before anything is composed.
3321
+ *
3322
+ * TODO: We'll likely want to modify ZKConfigProvider provider so that the verifier keys are
3323
+ * automatically rotated in this function. This likely involves storing key versions
3324
+ * along with keys in ZKConfigProvider. By default, artifacts for the latest version
3325
+ * would be fetched to build transactions.
3326
+ */
3327
+ declare function submitInsertVerifierKeyTx<C extends Ledger8Contract>(providers: Ledger8ContractProviders<C, Ledger8CircuitId<C>>, compiledContract: C, contractAddress: ContractAddress$1, circuitId: Ledger8CircuitId<C>, newVk: VerifierKey): Promise<Ledger8FinalizedMaintenanceTxData>;
3328
+ declare function submitInsertVerifierKeyTx<C extends Contract.Any>(providers: Ledger9ContractProviders, compiledContract: CompiledContract.CompiledContract<C, any>, // eslint-disable-line @typescript-eslint/no-explicit-any
3329
+ contractAddress: ContractAddress$1, circuitId: Contract.ProvableCircuitId<C>, newVk: VerifierKey): Promise<Ledger9FinalizedMaintenanceTxData>;
3330
+
3331
+ /**
3332
+ * Constructs and submits a transaction that removes the current verifier key stored
3333
+ * on the blockchain for the given circuit ID at the given contract address.
3334
+ *
3335
+ * ## Transaction Execution Phases
3336
+ *
3337
+ * Midnight transactions execute in two phases:
3338
+ * 1. **Guaranteed phase**: If failure occurs, the transaction is NOT included in the blockchain
3339
+ * 2. **Fallible phase**: If failure occurs, the transaction IS recorded on-chain as a partial success
3340
+ *
3341
+ * ## Failure Behavior
3342
+ *
3343
+ * **Guaranteed Phase Failure:**
3344
+ * - Transaction is rejected and not included in the blockchain
3345
+ * - `TxFailedError` is thrown with transaction data
3346
+ * - Verifier key remains on the contract (unchanged)
3347
+ * - No on-chain record of the failed transaction
3348
+ *
3349
+ * **Fallible Phase Failure:**
3350
+ * - Transaction is recorded on-chain with non-`SucceedEntirely` status
3351
+ * - `TxFailedError` is thrown with transaction data
3352
+ * - Verifier key may be partially removed but contract state is inconsistent
3353
+ * - Transaction appears in blockchain history as partial success
3354
+ *
3355
+ * @param providers The providers to use to manage the transaction lifecycle.
3356
+ * @param compiledContract The contract the circuit belongs to.
3357
+ * @param contractAddress The address of the contract containing the circuit for which
3358
+ * the verifier key should be removed.
3359
+ * @param circuitId The circuit for which the verifier key should be removed.
3360
+ *
3361
+ * @returns A promise that resolves with the finalized transaction data under `public`, tagged
3362
+ * with the pipeline's `era`, or rejects if an error occurs along the way.
3363
+ *
3364
+ * @throws {TxFailedError} When transaction fails in either guaranteed or fallible phase.
3365
+ * The error contains the finalized transaction data for debugging. Raised by both eras;
3366
+ * `record.era` tells which.
3367
+ * @throws {EraMismatchError} with reason `'ledger8-maintenance-on-ledger9-network'` When a retained-era artifact is used after the fork.
3368
+ * @throws {Ledger8SigningKeyError} with reason `'unavailable'` When the retained-era overload finds no usable key.
3369
+ * @throws {MaintenanceAuthorityMismatchError} When the retained-era overload holds a key that is not
3370
+ * the contract's maintenance authority. Raised before anything is proven.
3371
+ * @throws {InvalidArgumentError} When the contract state, or the retained-era artifact, declares no
3372
+ * such circuit. Raised before anything is composed.
3373
+ * @throws {BlankVerifierKeySlotError} When the circuit's verifier key slot holds no key. Raised before
3374
+ * anything is composed.
3375
+ *
3376
+ * TODO: We'll likely want to modify ZKConfigProvider provider so that the verifier keys are
3377
+ * automatically rotated in this function. This likely involves storing key versions
3378
+ * along with keys in ZKConfigProvider. By default, artifacts for the latest version
3379
+ * would be fetched to build transactions.
3380
+ */
3381
+ declare function submitRemoveVerifierKeyTx<C extends Ledger8Contract>(providers: Ledger8ContractProviders<C, Ledger8CircuitId<C>>, compiledContract: C, contractAddress: ContractAddress$1, circuitId: Ledger8CircuitId<C>): Promise<Ledger8FinalizedMaintenanceTxData>;
3382
+ declare function submitRemoveVerifierKeyTx<C extends Contract.Any>(providers: Ledger9ContractProviders, compiledContract: CompiledContract.CompiledContract<C, any>, // eslint-disable-line @typescript-eslint/no-explicit-any
3383
+ contractAddress: ContractAddress$1, circuitId: Contract.ProvableCircuitId<C>): Promise<Ledger9FinalizedMaintenanceTxData>;
3384
+
3385
+ /**
3386
+ * Constructs and submits a transaction that replaces the maintenance
3387
+ * authority stored on the blockchain for this contract. After the transaction is
3388
+ * finalized, the current signing key stored in the given private state provider
3389
+ * is overwritten with the given new authority key.
3390
+ *
3391
+ * ## Transaction Execution Phases
3392
+ *
3393
+ * Midnight transactions execute in two phases:
3394
+ * 1. **Guaranteed phase**: If failure occurs, the transaction is NOT included in the blockchain
3395
+ * 2. **Fallible phase**: If failure occurs, the transaction IS recorded on-chain as a partial success
3396
+ *
3397
+ * ## Failure Behavior
3398
+ *
3399
+ * **Guaranteed Phase Failure:**
3400
+ * - Transaction is rejected and not included in the blockchain
3401
+ * - `TxFailedError` is thrown with transaction data
3402
+ * - Signing key in private state provider is NOT updated (remains as current authority)
3403
+ * - Contract authority on-chain remains unchanged
3404
+ *
3405
+ * **Fallible Phase Failure:**
3406
+ * - Transaction is recorded on-chain with non-`SucceedEntirely` status
3407
+ * - `TxFailedError` is thrown with transaction data
3408
+ * - Signing key in private state provider is NOT updated (remains as current authority)
3409
+ * - Contract authority on-chain may be partially updated but inconsistent
3410
+ * - Transaction appears in blockchain history as partial success
3411
+ *
3412
+ * @param providers The providers to use to manage the transaction lifecycle.
3413
+ * @param compiledContract The contract whose maintenance authority should be replaced.
3414
+ * @param contractAddress The address of the contract for which the maintenance
3415
+ * authority should be updated.
3416
+ *
3417
+ * @returns A function that takes the signing key of the new contract maintenance authority and
3418
+ * resolves with the finalized transaction data under `public`, tagged with the pipeline's
3419
+ * `era`, or rejects if an error occurs along the way.
3420
+ *
3421
+ * @throws {TxFailedError} When transaction fails in either guaranteed or fallible phase.
3422
+ * The error contains the finalized transaction data for debugging. Raised by both eras;
3423
+ * `record.era` tells which. The error carries the new key as `signingKey`.
3424
+ * @throws {EraMismatchError} with reason `'ledger8-maintenance-on-ledger9-network'` When a retained-era artifact is used after the fork.
3425
+ * @throws {Ledger8SigningKeyError} with reason `'unusable'` When the retained-era overload is given a new key that era
3426
+ * cannot sign with. Raised before anything is composed.
3427
+ * @throws {Ledger8SigningKeyError} with reason `'unavailable'` When the retained-era overload finds no usable current key.
3428
+ * @throws {MaintenanceAuthorityMismatchError} When the retained-era overload holds a key that is not
3429
+ * the contract's maintenance authority. Raised before anything is proven.
3430
+ * @throws {Ledger8NotStoredError} with operation `'replace-authority'` When a retained-era replacement was confirmed and the
3431
+ * store then refused the new key. It carries the key.
3432
+ * @throws {Ledger8UnconfirmedError} with operation `'replace-authority'` When a retained-era replacement was submitted but
3433
+ * whether it landed could not be confirmed. It carries the new key, which was not stored.
3434
+ *
3435
+ * TODO: There are at least three options we should support in the future:
3436
+ * 1. Replace authority and maintain key (current).
3437
+ * 2. Replace authority and do not maintain key.
3438
+ * 3. Add additional authorities and maintain original key.
3439
+ */
3440
+ declare function submitReplaceAuthorityTx<C extends Ledger8Contract>(providers: Ledger8ContractProviders<C, Ledger8CircuitId<C>>, compiledContract: C, contractAddress: ContractAddress$1): (newAuthority: SigningKey$1) => Promise<Ledger8FinalizedMaintenanceTxData>;
3441
+ declare function submitReplaceAuthorityTx<C extends Contract.Any>(providers: Ledger9ContractProviders, compiledContract: CompiledContract.CompiledContract<C, any>, // eslint-disable-line @typescript-eslint/no-explicit-any
3442
+ contractAddress: ContractAddress$1): (newAuthority: SigningKey$1) => Promise<Ledger9FinalizedMaintenanceTxData>;
3443
+
3444
+ /**
3445
+ * The guard that narrows a result of either era.
3446
+ *
3447
+ * The entry-point overloads select ONE era's result type by inference, which is
3448
+ * what a caller making a call wants. A caller RECEIVING a result -- a telemetry
3449
+ * sink, a retry handler, a queue consumer -- declares its parameter with
3450
+ * `AnyFinalizedCallTxData`, `AnySubmittedCallTx` or `FinalizedMaintenanceTxData`,
3451
+ * or with a union of its contracts (`FoundContract<C | L8>`), and narrows it here.
3452
+ */
3453
+
3454
+ /**
3455
+ * What the guard narrows a result to.
3456
+ *
3457
+ * `Extract` for a union, an intersection for a value whose `era` is the whole
3458
+ * `LedgerEra` union. DO NOT REMOVE THE TUPLE WRAPPER: it is what stops the
3459
+ * conditional distributing.
3460
+ *
3461
+ * @see {@link OverloadTyping} for why the fallback branch has to be there.
3462
+ */
3463
+ type NarrowedToLedger8<T> = [Extract<T, {
3464
+ readonly era: 'v8';
3465
+ }>] extends [never] ? T & {
3466
+ readonly era: 'v8';
3467
+ } : Extract<T, {
3468
+ readonly era: 'v8';
3469
+ }>;
3470
+ /**
3471
+ * Whether a result came from the RETAINED pipeline, narrowing it to that era's
3472
+ * variant.
3473
+ *
3474
+ * Reads `era`, which every result carries and which each variant declares as its
3475
+ * own literal -- so this narrows a union of any two result shapes that carry
3476
+ * the tag, not only the flat unions.
3477
+ *
3478
+ * `era` names the PIPELINE that produced the objects in the result, read off
3479
+ * the compiled artifact. It is NOT the era that recorded the transaction:
3480
+ * `public.era` answers that, and the two disagree after the fork, when a
3481
+ * retained-era call is recorded as a keep-state transaction tagged `'v9'`.
3482
+ * Branch on this one to decide which module a result's objects came from, and
3483
+ * on `era` to decide which ledger recorded it.
3484
+ *
3485
+ * @param result Any result carrying an era tag.
3486
+ * @returns `true` when the retained pipeline produced it.
3487
+ */
3488
+ declare const isLedger8Result: <T extends {
3489
+ readonly era: LedgerEra$1;
3490
+ }>(result: T) => result is NarrowedToLedger8<T>;
3491
+
3492
+ /**
3493
+ * A contract compiled with the ledger 9 Compact toolchain.
3494
+ */
3495
+ type Ledger9Contract = Contract.Any;
3496
+ /**
3497
+ * The circuit ids of a contract compiled with the ledger 9 Compact toolchain.
3498
+ */
3499
+ type Ledger9CircuitId<C extends Ledger9Contract> = Contract.ProvableCircuitId<C>;
3500
+ /**
3501
+ * A contract compiled with the toolchain of any ledger era this release serves.
3502
+ *
3503
+ * Use it as a constraint (`C extends AnyContract`). Instantiated with itself, a flat name such
3504
+ * as `FinalizedCallTxData<AnyContract, …>` types the circuit values as `any`; for a call of any
3505
+ * contract use `AnyFinalizedCallTxData`. The flat names tell the eras apart by testing
3506
+ * `Ledger8Contract` first: `Contract.Any` alone accepts a ledger 8 artifact too.
3507
+ */
3508
+ type AnyContract = Ledger8Contract | Ledger9Contract;
3509
+ /**
3510
+ * The circuit ids of `C`, read the way the era that compiled `C` reads them.
3511
+ */
3512
+ type CircuitIdOf<C extends AnyContract> = C extends Ledger8Contract ? Ledger8CircuitId<C> : C extends Ledger9Contract ? Contract.ProvableCircuitId<C> : never;
3513
+ /**
3514
+ * Restates the two members that would otherwise arrive as `any` on the widest ledger 9
3515
+ * instantiation, where `Contract.Any` is `Contract<any>`. A concrete result stays assignable:
3516
+ * every `Result` and `PrivateState` is assignable to `unknown`.
3517
+ */
3518
+ type WithOpaqueCircuitValues<T extends {
3519
+ readonly private: object;
3520
+ }> = Omit<T, 'private'> & {
3521
+ readonly private: Omit<T['private'], 'nextPrivateState' | 'result'> & {
3522
+ readonly nextPrivateState: unknown;
3523
+ readonly result: unknown;
3524
+ };
3525
+ };
3526
+ /**
3527
+ * A finalized circuit call of any contract, in either era. Its `result` and `nextPrivateState` are
3528
+ * `unknown`. Narrow it with `isLedger8Result`; name the contract to get precise types back.
3529
+ */
3530
+ type AnyFinalizedCallTxData = WithOpaqueCircuitValues<Ledger9FinalizedCallTxData<Contract.Any, Contract.ProvableCircuitId<Contract.Any>>> | Ledger8FinalizedCallTxData<Ledger8Contract, Ledger8CircuitId<Ledger8Contract>>;
3531
+ /**
3532
+ * A submitted, not yet finalized circuit call of any contract, in either era. Its `result` and
3533
+ * `nextPrivateState` are `unknown`. Narrow it with `isLedger8Result`.
3534
+ */
3535
+ type AnySubmittedCallTx = (Omit<Ledger9SubmittedCallTx<Contract.Any, Contract.ProvableCircuitId<Contract.Any>>, 'callTxData'> & {
3536
+ readonly callTxData: WithOpaqueCircuitValues<Ledger9SubmittedCallTx<Contract.Any, Contract.ProvableCircuitId<Contract.Any>>['callTxData']>;
3537
+ }) | Ledger8SubmittedCallTx<Ledger8Contract, Ledger8CircuitId<Ledger8Contract>>;
3538
+ /** The contract found at an address. Generic code names an era: `Ledger9FoundContract<C>`. */
3539
+ type FoundContract<C extends AnyContract> = C extends Ledger8Contract ? Ledger8FoundContract<C> : C extends Ledger9Contract ? Ledger9FoundContract<C> : never;
3540
+ /** The contract a deploy created. Generic code names an era: `Ledger9DeployedContract<C>`. */
3541
+ type DeployedContract<C extends AnyContract> = C extends Ledger8Contract ? Ledger8DeployedContract<C> : C extends Ledger9Contract ? Ledger9DeployedContract<C> : never;
3542
+ /**
3543
+ * A finalized circuit call. Generic code names an era: `Ledger9FinalizedCallTxData<C, PCK>`.
3544
+ * A call of any contract, in either era, is {@link AnyFinalizedCallTxData}.
3545
+ */
3546
+ type FinalizedCallTxData<C extends AnyContract, PCK extends CircuitIdOf<C>> = C extends Ledger8Contract ? Ledger8FinalizedCallTxData<C, PCK & Ledger8CircuitId<C>> : C extends Ledger9Contract ? Ledger9FinalizedCallTxData<C, PCK & Contract.ProvableCircuitId<C>> : never;
3547
+ /**
3548
+ * A submitted, not yet finalized circuit call. Generic code names an era: `Ledger9SubmittedCallTx<C, PCK>`.
3549
+ * A submission of any contract, in either era, is {@link AnySubmittedCallTx}.
3550
+ */
3551
+ type SubmittedCallTx<C extends AnyContract, PCK extends CircuitIdOf<C>> = C extends Ledger8Contract ? Ledger8SubmittedCallTx<C, PCK & Ledger8CircuitId<C>> : C extends Ledger9Contract ? Ledger9SubmittedCallTx<C, PCK & Contract.ProvableCircuitId<C>> : never;
3552
+ /** A contract maintenance update recorded on chain, in either era. Narrow it on `era`. */
3553
+ type FinalizedMaintenanceTxData = Ledger9FinalizedMaintenanceTxData | Ledger8FinalizedMaintenanceTxData;
3554
+ /** A proven circuit call, not yet submitted. Generic code names an era: `Ledger9UnsubmittedCallTxData<C, PCK>`. */
3555
+ type UnsubmittedCallTxData<C extends AnyContract, PCK extends CircuitIdOf<C>> = C extends Ledger8Contract ? Ledger8UnsubmittedCallTxData<C, PCK & Ledger8CircuitId<C>> : C extends Ledger9Contract ? Ledger9UnsubmittedCallTxData<C, PCK & Contract.ProvableCircuitId<C>> : never;
3556
+ /** The deploy transaction of a found contract. Generic code names an era: `Ledger9FoundDeployTxData<C>`. */
3557
+ type FoundDeployTxData<C extends AnyContract> = C extends Ledger8Contract ? Ledger8FoundDeployTxData<C> : C extends Ledger9Contract ? Ledger9FoundDeployTxData<C> : never;
3558
+ /** A finalized deploy. Generic code names an era: `Ledger9FinalizedDeployTxData<C>` or `Ledger8FinalizedDeployTxData<C>`. */
3559
+ type FinalizedDeployTxData<C extends AnyContract> = C extends Ledger8Contract ? Ledger8FinalizedDeployTxData<C> : C extends Ledger9Contract ? Ledger9FinalizedDeployTxData<C> : never;
3560
+ /**
3561
+ * The providers that submit a transaction of `C`: the provider set of the era that compiled `C`,
3562
+ * without a private state provider. Generic code names an era: `Ledger9SubmitTxProviders<C, PCK>`.
3563
+ */
3564
+ type SubmitTxProviders<C extends AnyContract, PCK extends CircuitIdOf<C> = CircuitIdOf<C>> = C extends Ledger8Contract ? Omit<Ledger8ContractProviders<C, PCK & Ledger8CircuitId<C>>, 'privateStateProvider'> : C extends Ledger9Contract ? Ledger9SubmitTxProviders<C, PCK & Contract.ProvableCircuitId<C>> : never;
3565
+ /** The private result of a circuit call. Generic code names an era: `Ledger9CallResultPrivate<C, PCK>`. */
3566
+ type CallResultPrivate<C extends AnyContract, PCK extends CircuitIdOf<C>> = C extends Ledger8Contract ? Ledger8CallResultPrivate<C, PCK & Ledger8CircuitId<C>> : C extends Ledger9Contract ? Ledger9CallResultPrivate<C, PCK & Contract.ProvableCircuitId<C>> : never;
3567
+ /** The options of a circuit call. Generic code names an era: `Ledger9CallTxOptions<C, PCK>`. */
3568
+ type CallTxOptions<C extends AnyContract, PCK extends CircuitIdOf<C>> = C extends Ledger8Contract ? Ledger8CallTxOptions<C, PCK & Ledger8CircuitId<C>> : C extends Ledger9Contract ? Ledger9CallTxOptions<C, PCK & Contract.ProvableCircuitId<C>> : never;
3569
+ /** The options of a circuit call without private state. Generic code names an era: `Ledger9CallTxOptionsBase<C, PCK>`. */
3570
+ type CallTxOptionsBase<C extends AnyContract, PCK extends CircuitIdOf<C>> = C extends Ledger8Contract ? Ledger8CallTxOptionsBase<C, PCK & Ledger8CircuitId<C>> : C extends Ledger9Contract ? Ledger9CallTxOptionsBase<C, PCK & Contract.ProvableCircuitId<C>> : never;
3571
+ /** The options of a circuit call with a private state id. Generic code names an era: `Ledger9CallTxOptionsWithPrivateStateId<C, PCK>`. */
3572
+ type CallTxOptionsWithPrivateStateId<C extends AnyContract, PCK extends CircuitIdOf<C>> = C extends Ledger8Contract ? Ledger8CallTxOptionsWithPrivateStateId<C, PCK & Ledger8CircuitId<C>> : C extends Ledger9Contract ? Ledger9CallTxOptionsWithPrivateStateId<C, PCK & Contract.ProvableCircuitId<C>> : never;
3573
+ /** The options of `deployContract`. Generic code names an era: `Ledger9DeployContractOptions<C>`. */
3574
+ type DeployContractOptions<C extends AnyContract> = C extends Ledger8Contract ? Ledger8DeployContractOptions<C> : C extends Ledger9Contract ? Ledger9DeployContractOptions<C> : never;
3575
+ /** The options of `deployContract` without private state. Generic code names an era: `Ledger9DeployContractOptionsBase<C>`. */
3576
+ type DeployContractOptionsBase<C extends AnyContract> = C extends Ledger8Contract ? Ledger8DeployContractOptionsBase<C> : C extends Ledger9Contract ? Ledger9DeployContractOptionsBase<C> : never;
3577
+ /** The options of `deployContract` with private state. Generic code names an era: `Ledger9DeployContractOptionsWithPrivateState<C>`. */
3578
+ type DeployContractOptionsWithPrivateState<C extends AnyContract> = C extends Ledger8Contract ? Ledger8DeployContractOptionsWithPrivateState<C> : C extends Ledger9Contract ? Ledger9DeployContractOptionsWithPrivateState<C> : never;
3579
+ /** The options of `findDeployedContract`. Generic code names an era: `Ledger9FindDeployedContractOptions<C>`. */
3580
+ type FindDeployedContractOptions<C extends AnyContract> = C extends Ledger8Contract ? Ledger8FindDeployedContractOptions<C> : C extends Ledger9Contract ? Ledger9FindDeployedContractOptions<C> : never;
3581
+ /** One call function per circuit. Generic code names an era: `Ledger9CircuitCallTxInterface<C>`. */
3582
+ type CircuitCallTxInterface<C extends AnyContract> = C extends Ledger8Contract ? Ledger8CircuitCallTxInterface<C> : C extends Ledger9Contract ? Ledger9CircuitCallTxInterface<C> : never;
3583
+ /** One maintenance interface per circuit. Generic code names an era: `Ledger9CircuitMaintenanceTxInterfaces<C>`. */
3584
+ type CircuitMaintenanceTxInterfaces<C extends AnyContract> = C extends Ledger8Contract ? Ledger8CircuitMaintenanceTxInterfaces<C> : C extends Ledger9Contract ? Ledger9CircuitMaintenanceTxInterfaces<C> : never;
3585
+ /** The providers a contract needs. Generic code names an era: `Ledger9ContractProviders<C, PCK>`. */
3586
+ type ContractProviders<C extends AnyContract, PCK extends CircuitIdOf<C> = CircuitIdOf<C>> = C extends Ledger8Contract ? Ledger8ContractProviders<C, PCK & Ledger8CircuitId<C>> : C extends Ledger9Contract ? Ledger9ContractProviders<C, PCK & Contract.ProvableCircuitId<C>> : never;
3587
+
3588
+ /**
3589
+ * The provider set a ledger 9 call accepts.
3590
+ *
3591
+ * Two variants, because a call does not always need private state. The variant WITHOUT
3592
+ * `privateStateProvider` is valid only for options that name no
3593
+ * `privateStateId`; naming one without the provider is refused with
3594
+ * {@link IncompleteCallTxPrivateStateConfig} before any provider is touched.
3595
+ *
3596
+ * @see {@link OverloadTyping} for why that run-time refusal is what makes the
3597
+ * narrowing inside these functions sound.
3598
+ */
3599
+ type Ledger9SubmitCallTxProviders<C extends Contract.Any, PCK extends Contract.ProvableCircuitId<C>> = Ledger9ContractProviders<C> | Ledger9SubmitTxProviders<C, PCK>;
3600
+ /**
3601
+ * The retained-era overload. Accepts a contract produced by the PREVIOUS Compact toolchain, passed as
3602
+ * the raw contract instance rather than inside a `CompiledContract` container.
3603
+ *
3604
+ * Which pipeline runs is decided by the NETWORK'S LEDGER VERSION, not by this overload: before the fork the
3605
+ * retained-era-native pipeline runs, after it the keep-state one.
3606
+ *
3607
+ * @see {@link KeepStatePipeline} for the era table, and for why a provider needs to serve v8
3608
+ * handles only while the network is still before the fork.
3609
+ *
3610
+ * @see {@link OverloadTyping} for how the two eras are discriminated.
3611
+ */
3612
+ declare function submitCallTx<C extends Ledger8Contract, PCK extends Ledger8CircuitId<C>>(providers: Ledger8ContractProviders<C, PCK>, options: Ledger8CallTxOptions<C, PCK>): Promise<Ledger8FinalizedCallTxData<C, PCK>>;
3613
+ /**
3614
+ * Calls a circuit of a contract produced by the ledger 8 (pre-fork) Compact toolchain inside a scope
3615
+ * made by `withLedger8ContractScopedTransaction` or `withContractScopedTransaction` before the hard
3616
+ * fork. The call is added to the scope rather than submitted on its own.
3617
+ */
3618
+ declare function submitCallTx<C extends Ledger8Contract, PCK extends Ledger8CircuitId<C>>(providers: Ledger8ContractProviders<C, PCK>, options: Ledger8CallTxOptions<C, PCK>, transactionContext: Ledger8TransactionContext<C, PCK>): Promise<Ledger8UnsubmittedCallTxData<C, PCK>>;
3619
+ /**
3620
+ * Calls a circuit on a contract that declares no private state.
3621
+ */
3622
+ declare function submitCallTx<C extends Contract<undefined>, PCK extends Contract.ProvableCircuitId<C>>(providers: Ledger9SubmitTxProviders<C, PCK>, options: Ledger9CallTxOptionsBase<C, PCK>): Promise<Ledger9FinalizedCallTxData<C, PCK>>;
3623
+ /**
3624
+ * Calls a circuit on a contract that declares private state, naming where that state is stored.
3625
+ */
3626
+ declare function submitCallTx<C extends Contract.Any, PCK extends Contract.ProvableCircuitId<C>>(providers: Ledger9ContractProviders<C>, options: Ledger9CallTxOptionsWithPrivateStateId<C, PCK>): Promise<Ledger9FinalizedCallTxData<C, PCK>>;
3627
+ /**
3628
+ * Calls a circuit inside a scoped transaction, on a contract that declares private state. The
3629
+ * call is added to the scope rather than submitted on its own.
3630
+ */
3631
+ declare function submitCallTx<C extends Contract.Any, PCK extends Contract.ProvableCircuitId<C>>(providers: Ledger9ContractProviders<C>, options: Ledger9CallTxOptionsWithPrivateStateId<C, PCK>, transactionContext: Ledger9TransactionContext<C, PCK>): Promise<Ledger9CallResult<C, PCK>>;
3632
+ /**
3633
+ * Calls a circuit inside a scoped transaction, on a contract that declares no private state.
3634
+ */
3635
+ declare function submitCallTx<C extends Contract<undefined>, PCK extends Contract.ProvableCircuitId<C>>(providers: Ledger9SubmitTxProviders<C, PCK>, options: Ledger9CallTxOptionsBase<C, PCK>, transactionContext: Ledger9TransactionContext<C, PCK>): Promise<Ledger9CallResult<C, PCK>>;
3636
+ /**
3637
+ * The retained-era overload. Accepts a contract produced by the PREVIOUS Compact toolchain, passed as
3638
+ * the raw contract instance rather than inside a `CompiledContract` container.
3639
+ *
3640
+ * Which pipeline runs is decided by the NETWORK'S LEDGER VERSION, not by this overload: before the fork the
3641
+ * retained-era-native pipeline runs, after it the keep-state one.
3642
+ *
3643
+ * @see {@link KeepStatePipeline} for the era table, and for why a provider needs to serve v8
3644
+ * handles only while the network is still before the fork.
3645
+ *
3646
+ * @see {@link OverloadTyping} for how the two eras are discriminated.
3647
+ */
3648
+ declare function submitCallTxAsync<C extends Ledger8Contract, PCK extends Ledger8CircuitId<C>>(providers: Ledger8ContractProviders<C, PCK>, options: Ledger8CallTxOptions<C, PCK>): Promise<Ledger8SubmittedCallTx<C, PCK>>;
3649
+ /**
3650
+ * Creates and submits a transaction for the invocation of a circuit on a given contract,
3651
+ * returning immediately after submission without waiting for finalization.
3652
+ *
3653
+ * Unlike {@link submitCallTx}, this function does not wait for transaction finalization,
3654
+ * check transaction status, or update private state. The caller must handle these steps manually.
3655
+ *
3656
+ * ## Transaction Execution Phases
3657
+ *
3658
+ * Midnight transactions execute in two phases:
3659
+ * 1. **Guaranteed phase**: If failure occurs, the transaction is NOT included in the blockchain
3660
+ * 2. **Fallible phase**: If failure occurs, the transaction IS recorded on-chain as a partial success
3661
+ *
3662
+ * ## Manual Post-Submission Steps
3663
+ *
3664
+ * After calling this function, you must manually:
3665
+ * 1. Watch for transaction finalization using `providers.publicDataProvider.watchForTxData(txId)`
3666
+ * 2. Check transaction status (compare against `SucceedEntirely`)
3667
+ * 3. Handle failures appropriately (throw errors, log, etc.)
3668
+ * 4. Update private state if transaction succeeded and `privateStateId` was provided
3669
+ *
3670
+ * ## Failure Behavior (Manual Handling Required)
3671
+ *
3672
+ * **Guaranteed Phase Failure:**
3673
+ * - Transaction is rejected and not included in the blockchain
3674
+ * - `watchForTxData` may reject or return error status
3675
+ * - You must NOT store private state updates
3676
+ *
3677
+ * **Fallible Phase Failure:**
3678
+ * - Transaction is recorded on-chain with non-`SucceedEntirely` status
3679
+ * - `watchForTxData` returns transaction data with failed status
3680
+ * - You must NOT store private state updates
3681
+ * - Transaction appears in blockchain history as partial success
3682
+ *
3683
+ * @param providers The providers used to manage the invocation lifecycle.
3684
+ * @param options Configuration.
3685
+ *
3686
+ * @returns A `Promise` that resolves with the transaction ID and call transaction data immediately after submission;
3687
+ * or rejects with an error if the submission fails.
3688
+ *
3689
+ * @throws {EraMismatchError} When `options.compiledContract` belongs to neither Compact
3690
+ * era, is a raw current-era contract instance passed instead of its `CompiledContract`
3691
+ * container, or its artifacts declare no toolchain this framework can place or the other
3692
+ * era's toolchain. Raised before
3693
+ * anything is built or submitted; the ZK config provider is asked for the artifacts'
3694
+ * declared runtime version, and no other provider is consulted.
3695
+ *
3696
+ * @remarks
3697
+ * The returned {@link Ledger9SubmittedCallTx} is privacy-sensitive and carries the
3698
+ * unproven transaction and private state via `callTxData`. See that type for
3699
+ * handling guidance before logging, serializing, or transmitting the result.
3700
+ *
3701
+ * @example
3702
+ * ```typescript
3703
+ * // 1. Submit
3704
+ * const { txId, callTxData } = await submitCallTxAsync(providers, options);
3705
+ *
3706
+ * // 2. Watch (when ready). The read surface reports both ledger eras, so the
3707
+ * // record is era-tagged.
3708
+ * const record = await providers.publicDataProvider.watchForTxData(txId);
3709
+ *
3710
+ * // 3. Narrow to the v9 variant. This flow submits v9 transactions only, so a v8
3711
+ * // record means the provider is pointed at the wrong network.
3712
+ * if (record.era !== 'v9') {
3713
+ * throw new EraInvariantViolationError('watchForTxData', options.circuitId);
3714
+ * }
3715
+ *
3716
+ * // 4. Check status
3717
+ * if (record.status !== SucceedEntirely) {
3718
+ * throw new TxFailedError('call', record, { circuitId: options.circuitId });
3719
+ * }
3720
+ *
3721
+ * // 5. Update private state manually if needed
3722
+ * if (options.privateStateId) {
3723
+ * await providers.privateStateProvider
3724
+ * .forContract(options.contractAddress)
3725
+ * .set(options.privateStateId, callTxData.private.nextPrivateState);
3726
+ * }
3727
+ * ```
3728
+ */
3729
+ declare function submitCallTxAsync<C extends Contract.Any, PCK extends Contract.ProvableCircuitId<C>>(providers: Ledger9SubmitCallTxProviders<C, PCK>, options: Ledger9CallTxOptions<C, PCK>): Promise<Ledger9SubmittedCallTx<C, PCK>>;
3730
+
3731
+ /**
3732
+ * Base type for deploy transaction configuration.
3733
+ */
3734
+ type Ledger9DeployTxOptionsBase<C extends Contract.Any> = Ledger9ContractConstructorOptionsWithArguments<C> & {
3735
+ /**
3736
+ * An optional mapping of {@link CoinPublicKey} to {@link EncPublicKey} that can be used to resolve encryption
3737
+ * keys for coins created in the contract constructor. This is useful in cases where the constructor creates
3738
+ * outputs to addresses that don't belong to the current user.
3739
+ */
3740
+ readonly additionalCoinEncPublicKeyMappings?: ReadonlyMap<CoinPublicKey, EncPublicKey>;
3741
+ /**
3742
+ * The signing key to add as the to-be-deployed contract's maintenance authority.
3743
+ */
3744
+ readonly signingKey: SigningKey;
3745
+ };
3746
+ /**
3747
+ * Configuration for creating deploy transactions for contracts with private state. This
3748
+ * configuration used as a base type for the {@link Ledger9DeployTxOptionsWithPrivateStateId} configuration.
3749
+ * It is also used directly as parameter to {@link createUnprovenDeployTx} which doesn't need
3750
+ * to save private state (and therefore doesn't need a private state ID) but does need to supply an
3751
+ * initial private state to run the contract constructor against.
3752
+ */
3753
+ type Ledger9DeployTxOptionsWithPrivateState<C extends Contract.Any> = Ledger9DeployTxOptionsBase<C> & {
3754
+ /**
3755
+ * The private state to run the contract constructor against.
3756
+ */
3757
+ readonly initialPrivateState: Contract.PrivateState<C>;
3758
+ };
3759
+ /**
3760
+ * Configuration for creating deploy transactions for contracts with private state. This
3761
+ * configuration is used when a deployment transaction is created and an initial private
3762
+ * state needs to be stored, as is the case in {@link submitDeployTx}.
3763
+ */
3764
+ type Ledger9DeployTxOptionsWithPrivateStateId<C extends Contract.Any> = Ledger9DeployTxOptionsWithPrivateState<C> & {
3765
+ /**
3766
+ * The identifier for the private state of the contract.
3767
+ */
3768
+ readonly privateStateId: PrivateStateId;
3769
+ };
3770
+ /**
3771
+ * Configuration for creating unproven deploy transactions.
3772
+ */
3773
+ type Ledger9UnprovenDeployTxOptions<C extends Contract.Any> = Ledger9DeployTxOptionsBase<C> | Ledger9DeployTxOptionsWithPrivateState<C>;
3774
+ declare function createLedger9UnprovenDeployTxFromVerifierKeys<C extends Contract<undefined>>(zkConfigProvider: ZKConfigProvider<string>, coinPublicKey: CoinPublicKey, options: Ledger9DeployTxOptionsBase<C>, encryptionPublicKey: EncPublicKey, config: MidnightConfig): Promise<Ledger9UnsubmittedDeployTxData<C>>;
3775
+ declare function createLedger9UnprovenDeployTxFromVerifierKeys<C extends Contract.Any>(zkConfigProvider: ZKConfigProvider<string>, coinPublicKey: CoinPublicKey, options: Ledger9DeployTxOptionsWithPrivateState<C>, encryptionPublicKey: EncPublicKey, config: MidnightConfig): Promise<Ledger9UnsubmittedDeployTxData<C>>;
3776
+ /**
3777
+ * Providers needed to create an unproven deployment transactions, just the ZK artifact
3778
+ * provider and a wallet.
3779
+ */
3780
+ type Ledger9UnprovenDeployTxProviders<C extends Contract.Any> = Pick<Ledger9ContractProviders<C>, 'zkConfigProvider' | 'walletProvider' | 'config'>;
3781
+ declare function createLedger9UnprovenDeployTx<C extends Contract<undefined>>(providers: Ledger9UnprovenDeployTxProviders<C>, options: Ledger9DeployTxOptionsBase<C>): Promise<Ledger9UnsubmittedDeployTxData<C>>;
3782
+ declare function createLedger9UnprovenDeployTx<C extends Contract.Any>(providers: Ledger9UnprovenDeployTxProviders<C>, options: Ledger9DeployTxOptionsWithPrivateState<C>): Promise<Ledger9UnsubmittedDeployTxData<C>>;
3783
+ declare function createLedger8UnprovenDeployTxFromVerifierKeys<C extends Ledger8Contract>(zkConfigProvider: ZKConfigProvider<string>, coinPublicKey: CoinPublicKey, options: Ledger8UnprovenDeployTxOptions<C>, encryptionPublicKey: EncPublicKey, config: MidnightConfig): Promise<Ledger8UnsubmittedDeployTxData<C>>;
3784
+ declare function createLedger8UnprovenDeployTx<C extends Ledger8Contract>(providers: Ledger8ContractProviders<C, Ledger8CircuitId<C>>, options: Ledger8UnprovenDeployTxOptions<C>): Promise<Ledger8UnsubmittedDeployTxData<C>>;
3785
+ declare function createUnprovenDeployTxFromVerifierKeys<C extends Ledger8Contract>(zkConfigProvider: ZKConfigProvider<string>, coinPublicKey: CoinPublicKey, options: Ledger8UnprovenDeployTxOptions<C>, encryptionPublicKey: EncPublicKey, config: MidnightConfig): Promise<Ledger8UnsubmittedDeployTxData<C>>;
3786
+ declare function createUnprovenDeployTxFromVerifierKeys<C extends Contract<undefined>>(zkConfigProvider: ZKConfigProvider<string>, coinPublicKey: CoinPublicKey, options: Ledger9DeployTxOptionsBase<C>, encryptionPublicKey: EncPublicKey, config: MidnightConfig): Promise<Ledger9UnsubmittedDeployTxData<C>>;
3787
+ declare function createUnprovenDeployTxFromVerifierKeys<C extends Contract.Any>(zkConfigProvider: ZKConfigProvider<string>, coinPublicKey: CoinPublicKey, options: Ledger9DeployTxOptionsWithPrivateState<C>, encryptionPublicKey: EncPublicKey, config: MidnightConfig): Promise<Ledger9UnsubmittedDeployTxData<C>>;
3788
+ declare function createUnprovenDeployTx<C extends Ledger8Contract>(providers: Ledger8ContractProviders<C, Ledger8CircuitId<C>>, options: Ledger8UnprovenDeployTxOptions<C>): Promise<Ledger8UnsubmittedDeployTxData<C>>;
3789
+ declare function createUnprovenDeployTx<C extends Contract<undefined>>(providers: Ledger9UnprovenDeployTxProviders<C>, options: Ledger9DeployTxOptionsBase<C>): Promise<Ledger9UnsubmittedDeployTxData<C>>;
3790
+ declare function createUnprovenDeployTx<C extends Contract.Any>(providers: Ledger9UnprovenDeployTxProviders<C>, options: Ledger9DeployTxOptionsWithPrivateState<C>): Promise<Ledger9UnsubmittedDeployTxData<C>>;
3791
+
3792
+ /**
3793
+ * Configuration for creating deploy transactions.
3794
+ */
3795
+ type Ledger9DeployTxOptions<C extends Contract$1.Any> = Ledger9DeployTxOptionsBase<C> | Ledger9DeployTxOptionsWithPrivateStateId<C>;
3796
+ declare function submitLedger9DeployTx<C extends Contract$1<undefined>>(providers: Ledger9ContractProviders<C, Contract$1.ProvableCircuitId<C>, unknown>, options: Ledger9DeployTxOptionsBase<C>): Promise<Ledger9FinalizedDeployTxData<C>>;
3797
+ declare function submitLedger9DeployTx<C extends Contract$1.Any>(providers: Ledger9ContractProviders<C>, options: Ledger9DeployTxOptionsWithPrivateStateId<C>): Promise<Ledger9FinalizedDeployTxData<C>>;
3798
+ declare function submitLedger8DeployTx<C extends Ledger8Contract>(providers: Ledger8ContractProviders<C, Ledger8CircuitId<C>>, options: Ledger8DeployContractOptions<C>): Promise<Ledger8FinalizedDeployTxData<C>>;
3799
+ declare function submitDeployTx<C extends Ledger8Contract>(providers: Ledger8ContractProviders<C, Ledger8CircuitId<C>>, options: Ledger8DeployContractOptions<C>): Promise<Ledger8FinalizedDeployTxData<C>>;
3800
+ declare function submitDeployTx<C extends Contract$1<undefined>>(providers: Ledger9ContractProviders<C, Contract$1.ProvableCircuitId<C>, unknown>, options: Ledger9DeployTxOptionsBase<C>): Promise<Ledger9FinalizedDeployTxData<C>>;
3801
+ declare function submitDeployTx<C extends Contract$1.Any>(providers: Ledger9ContractProviders<C>, options: Ledger9DeployTxOptionsWithPrivateStateId<C>): Promise<Ledger9FinalizedDeployTxData<C>>;
3802
+
3803
+ export { BlankVerifierKeySlotError, ContractNotFoundError, ContractTypeError, DISPATCH_BREADCRUMB_MESSAGE, EraInvariantViolationError, EraMismatchError, ForkCrossedDuringOperationError, IncompleteCallTxPrivateStateConfig, IncompleteDeployContractPrivateStateConfig, IncompleteFindContractPrivateStateConfig, IndexerInconsistencyError, Ledger8AmbiguousEntryPointError, Ledger8CallUnsupportedError, Ledger8NotStoredError, Ledger8SigningKeyError, Ledger8UnconfirmedError, LedgerParametersUnservedError, NetworkVersionReadFailedError, NetworkVersionStateMismatchError, PrivateStateNotFoundError, ProviderFailedError, PublicStatesEraMismatchError, ScopedTransactionIdentityMismatchError, SubmitRejectionUndiagnosedError, TxFailedError, VerifierKeyMismatchError, ZswapOutputResolutionError, createCallTxOptions, createCircuitCallTxInterface, createCircuitMaintenanceTxInterface, createCircuitMaintenanceTxInterfaces, createContractMaintenanceTxInterface, createLedger8UnprovenCallTx, createLedger8UnprovenCallTxFromInitialStates, createLedger8UnprovenDeployTx, createLedger8UnprovenDeployTxFromVerifierKeys, createLedger9UnprovenCallTx, createLedger9UnprovenCallTxFromInitialStates, createLedger9UnprovenDeployTx, createLedger9UnprovenDeployTxFromVerifierKeys, createUnprovenCallTx, createUnprovenCallTxFromInitialStates, createUnprovenDeployTx, createUnprovenDeployTxFromVerifierKeys, deployContract, findDeployedContract, getPublicStates, getStates, getUnshieldedBalances, isLedger8Result, isLedger8TransactionContext, isLedger9TransactionContext, submitCallTx, submitCallTxAsync, submitDeployTx, submitInsertVerifierKeyTx, submitLedger8DeployTx, submitLedger9DeployTx, submitRemoveVerifierKeyTx, submitReplaceAuthorityTx, submitTx, submitTxAsync, verifierKeysEqual, verifyContractState, withContractScopedTransaction, withLedger8ContractScopedTransaction, withLedger9ContractScopedTransaction };
3804
+ export type { AnyContract, AnyFinalizedCallTxData, AnyLedger8TransactionContext, AnySubmittedCallTx, CallResultPrivate, CallTxOptions, CallTxOptionsBase, CallTxOptionsWithPrivateStateId, CircuitCallTxInterface, CircuitIdOf, CircuitMaintenanceTxInterfaces, ContractConstructorOptionsProviderDataDependencies, ContractProviders, ContractStates, ContractTypeMismatch, DeployContractOptions, DeployContractOptionsBase, DeployContractOptionsWithPrivateState, DeployedContract, EraMismatchOptions, EraMismatchReason, FinalizedCallTxData, FinalizedDeployTxData, FinalizedMaintenanceTxData, FindDeployedContractOptions, FoundContract, FoundDeployTxData, FoundDeployTxPublicData, Ledger8CallOptionsWithInitialStates, Ledger8CallResultPrivate, Ledger8CallResultPublic, Ledger8CallTxOptions, Ledger8CallTxOptionsBase, Ledger8CallTxOptionsWithPrivateStateId, Ledger8CallTxTarget, Ledger8CallUnsupportedReason, Ledger8Circuit, Ledger8CircuitCallTxInterface, Ledger8CircuitContext, Ledger8CircuitId, Ledger8CircuitMaintenanceTxInterface, Ledger8CircuitMaintenanceTxInterfaces, Ledger8CircuitParameters, Ledger8CircuitResult, Ledger8CircuitReturnType, Ledger8ConstructorParameters, Ledger8Contract, Ledger8ContractCall, Ledger8ContractCallPublic, Ledger8ContractMaintenanceTxInterface, Ledger8ContractProviders, Ledger8DeployContractOptions, Ledger8DeployContractOptionsBase, Ledger8DeployContractOptionsWithPrivateState, Ledger8DeployedContract, Ledger8FinalizedCallTxData, Ledger8FinalizedCallTxPublicData, Ledger8FinalizedDeployTxData, Ledger8FinalizedMaintenanceTxData, Ledger8FindDeployedContractOptions, Ledger8FoundContract, Ledger8FoundDeployTxData, Ledger8FoundDeployTxPublicData, Ledger8InitialStateResult, Ledger8KeyedOperation, Ledger8NotStoredStage, Ledger8PrivateState, Ledger8SigningKeyReason, Ledger8SubmittedCallTx, Ledger8TransactionContext, Ledger8UnprovenDeployTxOptions, Ledger8UnprovenDeployTxOptionsBase, Ledger8UnsubmittedCallTxData, Ledger8UnsubmittedDeployTxData, Ledger8Witness, Ledger9CallOptions, Ledger9CallOptionsBase, Ledger9CallOptionsProviderDataDependencies, Ledger9CallOptionsWithArguments, Ledger9CallOptionsWithPrivateState, Ledger9CallOptionsWithProviderDataDependencies, Ledger9CallResult, Ledger9CallResultPrivate, Ledger9CallResultPublic, Ledger9CallTxOptions, Ledger9CallTxOptionsBase, Ledger9CallTxOptionsWithPrivateStateId, Ledger9CircuitCallTxInterface, Ledger9CircuitId, Ledger9CircuitMaintenanceTxInterface, Ledger9CircuitMaintenanceTxInterfaces, Ledger9Contract, Ledger9ContractConstructorOptions, Ledger9ContractConstructorOptionsBase, Ledger9ContractConstructorOptionsWithArguments, Ledger9ContractConstructorOptionsWithPrivateState, Ledger9ContractConstructorOptionsWithProviderDataDependencies, Ledger9ContractConstructorResult, Ledger9ContractMaintenanceTxInterface, Ledger9ContractProviders, Ledger9CrossContractConfig, Ledger9DeployContractOptions, Ledger9DeployContractOptionsBase, Ledger9DeployContractOptionsShared, Ledger9DeployContractOptionsWithPrivateState, Ledger9DeployTxOptions, Ledger9DeployTxOptionsBase, Ledger9DeployTxOptionsWithPrivateState, Ledger9DeployTxOptionsWithPrivateStateId, Ledger9DeployedContract, Ledger9FinalizedCallTxData, Ledger9FinalizedCallTxPublicData, Ledger9FinalizedDeployTxData, Ledger9FinalizedDeployTxDataBase, Ledger9FinalizedDeployTxPublicData, Ledger9FinalizedMaintenanceTxData, Ledger9FindDeployedContractOptions, Ledger9FindDeployedContractOptionsBase, Ledger9FindDeployedContractOptionsExistingPrivateState, Ledger9FindDeployedContractOptionsStorePrivateState, Ledger9FoundContract, Ledger9FoundDeployTxData, Ledger9SubmitCallTxProviders, Ledger9SubmitTxProviders, Ledger9SubmittedCallTx, Ledger9TransactionContext, Ledger9UnprovenCallTxProvidersWithPrivateState, Ledger9UnprovenDeployTxOptions, Ledger9UnprovenDeployTxProviders, Ledger9UnsubmittedCallTxData, Ledger9UnsubmittedCallTxPrivateData, Ledger9UnsubmittedDeployTxData, Ledger9UnsubmittedDeployTxDataBase, Ledger9UnsubmittedDeployTxPrivateData, Ledger9UnsubmittedDeployTxPrivateDataFull, Ledger9UnsubmittedDeployTxPublicData, Ledger9UnsubmittedTxData, ScopedTransactionOptions, SubmitRejectionUndiagnosedCause, SubmitTxOptions, SubmitTxProviders, SubmittedCallTx, SubmittedContractOperation, SubmittedOperation, SubmittedOperationKind, SubmittedTransaction, TxFailedDetails, TxFailedOperation, UnprovenCallTxProvidersBase, UnsubmittedCallTxData };