@midnightntwrk/midnight-js-protocol 0.0.0-stage → 5.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +291 -2
- package/dist/compact-js-v8-effect.d.ts +1 -0
- package/dist/compact-js-v8-effect.js +2 -0
- package/dist/compact-js-v8-effect.js.map +1 -0
- package/dist/engine.d.ts +420 -0
- package/dist/engine.js +832 -0
- package/dist/engine.js.map +1 -0
- package/dist/errors.d.ts +601 -0
- package/dist/errors.js +810 -0
- package/dist/errors.js.map +1 -0
- package/dist/index.d.ts +1471 -0
- package/dist/index.js +799 -0
- package/dist/index.js.map +1 -0
- package/dist/platform-effect-configuration.d.ts +1 -0
- package/dist/platform-effect-configuration.js +2 -0
- package/dist/platform-effect-configuration.js.map +1 -0
- package/dist/platform-effect-contract-address.d.ts +1 -0
- package/dist/platform-effect-contract-address.js +2 -0
- package/dist/platform-effect-contract-address.js.map +1 -0
- package/dist/platform.d.ts +1 -0
- package/dist/platform.js +2 -0
- package/dist/platform.js.map +1 -0
- package/dist/prove.d.ts +45 -0
- package/dist/prove.js +61 -0
- package/dist/prove.js.map +1 -0
- package/dist/shared/compose-options-BFA09u9q.js +468 -0
- package/dist/shared/compose-options-BFA09u9q.js.map +1 -0
- package/dist/shared/ledger-transaction-DQP8J8tv.js +134 -0
- package/dist/shared/ledger-transaction-DQP8J8tv.js.map +1 -0
- package/dist/shared/load-BMVWoBo6.js +49 -0
- package/dist/shared/load-BMVWoBo6.js.map +1 -0
- package/dist/shared/transaction-tags-I3J_Hh8r.js +82 -0
- package/dist/shared/transaction-tags-I3J_Hh8r.js.map +1 -0
- package/dist/transaction.d.ts +92 -0
- package/dist/transaction.js +6 -0
- package/dist/transaction.js.map +1 -0
- package/dist/v8.d.ts +1 -0
- package/dist/v8.js +3 -0
- package/dist/v8.js.map +1 -0
- package/dist/v9-compact-js-effect-contract.d.ts +1 -0
- package/dist/v9-compact-js-effect-contract.js +2 -0
- package/dist/v9-compact-js-effect-contract.js.map +1 -0
- package/dist/v9-compact-js-effect.d.ts +1 -0
- package/dist/v9-compact-js-effect.js +2 -0
- package/dist/v9-compact-js-effect.js.map +1 -0
- package/dist/v9-compact-js.d.ts +1 -0
- package/dist/v9-compact-js.js +2 -0
- package/dist/v9-compact-js.js.map +1 -0
- package/dist/v9-compact-runtime.d.ts +1 -0
- package/dist/v9-compact-runtime.js +2 -0
- package/dist/v9-compact-runtime.js.map +1 -0
- package/dist/v9-onchain-runtime.d.ts +1 -0
- package/dist/v9-onchain-runtime.js +2 -0
- package/dist/v9-onchain-runtime.js.map +1 -0
- package/dist/v9.d.ts +1 -0
- package/dist/v9.js +2 -0
- package/dist/v9.js.map +1 -0
- package/dist/version.d.ts +173 -0
- package/dist/version.js +125 -0
- package/dist/version.js.map +1 -0
- package/package.json +122 -3
package/dist/engine.d.ts
ADDED
|
@@ -0,0 +1,420 @@
|
|
|
1
|
+
import * as ledgerV9 from '@midnightntwrk/ledger-v9';
|
|
2
|
+
import { TokenType, EncodedStateValue, CallContext, Effects, CoinCommitment, ContractCallPrototype } from '@midnightntwrk/ledger-v9';
|
|
3
|
+
export { EncodedStateValue } from '@midnightntwrk/ledger-v9';
|
|
4
|
+
import { ContractExecutable } from '@midnight-ntwrk/compact-js/v8/effect';
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* The public balances a contract holds, keyed by token type.
|
|
8
|
+
*
|
|
9
|
+
* Derived from the vendor's own `TokenType` rather than restated, so a rename
|
|
10
|
+
* fails this build instead of leaving a mirror describing a shape neither
|
|
11
|
+
* runtime has.
|
|
12
|
+
*
|
|
13
|
+
* `shared-contract-state.test.ts` pins all three `TokenType` declarations —
|
|
14
|
+
* both eras' and the execution runtime's, which is where the map actually
|
|
15
|
+
* lands — mutually assignable. That pin is STRUCTURAL and can be no more:
|
|
16
|
+
* `raw` is an opaque `string` everywhere, so assignability says the handoff
|
|
17
|
+
* type-checks and says nothing about two eras reading a given key as the same
|
|
18
|
+
* colour.
|
|
19
|
+
*
|
|
20
|
+
* Plain data end to end — string-tagged objects and `bigint`s — so it crosses
|
|
21
|
+
* an era boundary like every other member of {@link ContractStatePojo}. That is
|
|
22
|
+
* a statement about `structuredClone`, which carries a `Map`; a JSON round trip
|
|
23
|
+
* does NOT, and leaves the plain object the balance guards refuse.
|
|
24
|
+
*/
|
|
25
|
+
type ContractBalance = ReadonlyMap<TokenType, bigint>;
|
|
26
|
+
/**
|
|
27
|
+
* One entry point a contract state declares, with the verifier key registered
|
|
28
|
+
* against it if there is one.
|
|
29
|
+
*
|
|
30
|
+
* `verifierKey` and `verifierKeyHash` are both absent for a blank slot — the
|
|
31
|
+
* shape a constructor-built state has before a deploy fills it in.
|
|
32
|
+
*
|
|
33
|
+
* @see {@link FailClosedDecoding} for why they are absent rather than
|
|
34
|
+
* zero-length or a hash of nothing.
|
|
35
|
+
*/
|
|
36
|
+
interface ContractEntryPointPojo {
|
|
37
|
+
readonly circuitId: string;
|
|
38
|
+
readonly verifierKey: Uint8Array | undefined;
|
|
39
|
+
readonly verifierKeyHash: string | undefined;
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* A contract state as plain data: the primary state in its encoded form, the
|
|
43
|
+
* balances the contract holds, and the entry points the state declares.
|
|
44
|
+
*
|
|
45
|
+
* `entryPoints` is an ARRAY, not a map keyed by circuit id: two distinct byte
|
|
46
|
+
* entry points can decode to the same name, and a caller has to reconcile
|
|
47
|
+
* them.
|
|
48
|
+
*
|
|
49
|
+
* @see {@link FailClosedDecoding}
|
|
50
|
+
*/
|
|
51
|
+
interface ContractStatePojo {
|
|
52
|
+
readonly state: EncodedStateValue;
|
|
53
|
+
/**
|
|
54
|
+
* The balances the contract holds, which are NOT part of the primary state:
|
|
55
|
+
* the ledger keeps them beside it, so a caller reading only `state` cannot
|
|
56
|
+
* reach them. A retained-era call that executes without them runs every
|
|
57
|
+
* circuit against an empty balance — see {@link RetainedEraExecution}.
|
|
58
|
+
*/
|
|
59
|
+
readonly balance: ContractBalance;
|
|
60
|
+
readonly entryPoints: readonly ContractEntryPointPojo[];
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* The query-context state a call recorded while it ran, which its pre-call
|
|
65
|
+
* state bytes do not carry.
|
|
66
|
+
*
|
|
67
|
+
* `block` and `effects` are the PRE-call values; `comIndices` is the POST-call
|
|
68
|
+
* map. Plain data on every member.
|
|
69
|
+
*
|
|
70
|
+
* @see {@link ComposeRefusalOrder} for why partitioning needs the context the
|
|
71
|
+
* circuit actually ran on, and why `CallContext` and `Effects` are declared
|
|
72
|
+
* once against ledger-v9.
|
|
73
|
+
* @see {@link RetainedEraExecution} for why each member is read off the
|
|
74
|
+
* context it is.
|
|
75
|
+
* @see {@link EraBoundary}
|
|
76
|
+
*/
|
|
77
|
+
interface PartitionContext {
|
|
78
|
+
readonly block: CallContext;
|
|
79
|
+
readonly effects: Effects;
|
|
80
|
+
/** Commitment -> the index the runtime recorded it at. Empty for a call that received no coin. */
|
|
81
|
+
readonly comIndices: ReadonlyMap<CoinCommitment, bigint>;
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* The sentinel that asks for the ledger's own INITIAL cost model instead of the chain's.
|
|
85
|
+
*
|
|
86
|
+
* Spelled out as a value a caller has to name, because the thing it selects is wrong for any chain
|
|
87
|
+
* that has been running: the initial parameters are the model the chain started with, and prices
|
|
88
|
+
* adjust per block. Partitioning against them draws the guaranteed/fallible boundary in the wrong
|
|
89
|
+
* place and the node then refuses the guaranteed segment with `Transcript(Execution(OutOfGas))` --
|
|
90
|
+
* after the caller has already paid to prove it.
|
|
91
|
+
*/
|
|
92
|
+
declare const INITIAL_LEDGER_PARAMETERS = "initial";
|
|
93
|
+
/**
|
|
94
|
+
* What a composer accepts for the block's ledger parameters: the chain's own serialized parameters,
|
|
95
|
+
* or {@link INITIAL_LEDGER_PARAMETERS}.
|
|
96
|
+
*
|
|
97
|
+
* There is deliberately no third option. This used to be optional, and omitting it fell back to the
|
|
98
|
+
* initial parameters silently -- so a caller that simply forgot got the wrong cost model with no
|
|
99
|
+
* signal, and a `PublicDataProvider` that does not serve `ledgerParameters` (the field is optional)
|
|
100
|
+
* degraded every call built through it. Requiring the option keeps the compatibility path reachable
|
|
101
|
+
* only as a decision, never as an oversight.
|
|
102
|
+
*
|
|
103
|
+
* A caller that reads the chain must pass the bytes from the SAME read as the contract state: the
|
|
104
|
+
* parameters are era-tagged and dated per block, so a second read could answer for another block.
|
|
105
|
+
*
|
|
106
|
+
* @see {@link EraBoundary}
|
|
107
|
+
*/
|
|
108
|
+
type LedgerParametersOption = Uint8Array | typeof INITIAL_LEDGER_PARAMETERS;
|
|
109
|
+
|
|
110
|
+
/**
|
|
111
|
+
* Retained-era (ledger 8) execution, on compact-js's own era-pinned entries.
|
|
112
|
+
*
|
|
113
|
+
* This module replaced a hand-maintained execution layer — `execute.ts`, which
|
|
114
|
+
* drove `compact-runtime@0.16` directly, and `down-convert.ts`, which built the
|
|
115
|
+
* state it ran against. Both are gone; see
|
|
116
|
+
* `docs/adr/0015-retained-era-execution-on-compact-js.md` for why.
|
|
117
|
+
*
|
|
118
|
+
* Everything crossing this module's surface is PLAIN DATA or an era-tagged
|
|
119
|
+
* handle the caller already holds. No `Effect` value leaves it: the effects
|
|
120
|
+
* compact-js returns are discharged here with `Effect.runPromise`, which is
|
|
121
|
+
* also why every entry point is asynchronous — `ContractExecutable` builds its
|
|
122
|
+
* work on `Effect.tryPromise`, so `runSync` cannot discharge it.
|
|
123
|
+
*
|
|
124
|
+
* @see {@link RetainedEraExecution}
|
|
125
|
+
*/
|
|
126
|
+
|
|
127
|
+
/** A retained-era signing key: 32 bytes of hex. @see {@link LEDGER8_SIGNING_KEY_PATTERN} */
|
|
128
|
+
type Ledger8SigningKey = string;
|
|
129
|
+
/**
|
|
130
|
+
* A retained-era contract, as the caller holds it: the CONSTRUCTED artifact the
|
|
131
|
+
* previous toolchain generates.
|
|
132
|
+
*
|
|
133
|
+
* Deliberately not compact-js's `CompiledContract` container. That container is
|
|
134
|
+
* a recipe — a class plus witnesses, instantiated fresh per operation — and the
|
|
135
|
+
* retained era's callers hold an instance whose witnesses are already bound.
|
|
136
|
+
* {@link containerFor} adapts one to the other here, which keeps the
|
|
137
|
+
* adaptation in one place instead of on every consumer.
|
|
138
|
+
*/
|
|
139
|
+
interface Ledger8EngineContract {
|
|
140
|
+
/** The map compact-js indexes to find the circuit to run. */
|
|
141
|
+
readonly provableCircuits: Readonly<Record<string, unknown>>;
|
|
142
|
+
/** The constructor a deployment runs. */
|
|
143
|
+
initialState(...args: never[]): unknown;
|
|
144
|
+
}
|
|
145
|
+
/**
|
|
146
|
+
* The result of one retained-era circuit call: every artifact
|
|
147
|
+
* {@link wrapKeepStateCall} (`../v9/wrap.ts`) needs to assemble a v9-native
|
|
148
|
+
* `ContractCallPrototype`.
|
|
149
|
+
*
|
|
150
|
+
* `preContractState` and `postContractState` are LIVE HANDLES from the retained
|
|
151
|
+
* runtime; every other member is plain data. `postContractStateEncoded` is the
|
|
152
|
+
* post-state's encoded form, carried beside the handle so a caller has a value
|
|
153
|
+
* that outlives the runtime instance.
|
|
154
|
+
*
|
|
155
|
+
* @see {@link RetainedEraExecution}
|
|
156
|
+
*/
|
|
157
|
+
interface TranscriptPojo {
|
|
158
|
+
readonly circuitId: string;
|
|
159
|
+
readonly result: unknown;
|
|
160
|
+
readonly input: ContractExecutable.ContractExecutable.ContractCallPrivate['input'];
|
|
161
|
+
readonly output: ContractExecutable.ContractExecutable.ContractCallPrivate['output'];
|
|
162
|
+
readonly publicTranscript: ContractExecutable.ContractExecutable.ContractCallPublic['publicTranscript'];
|
|
163
|
+
readonly privateTranscriptOutputs: ContractExecutable.ContractExecutable.ContractCallPrivate['privateTranscriptOutputs'];
|
|
164
|
+
/**
|
|
165
|
+
* The state the call BOUND to, i.e. `partitionInputs.state`.
|
|
166
|
+
*
|
|
167
|
+
* Indistinguishable from {@link TranscriptPojo.postContractState} BY TYPE:
|
|
168
|
+
* compact-js resolves both to the same declaration, so swapping the two is
|
|
169
|
+
* not a compile error. Partitioning against the wrong one rejects a state the
|
|
170
|
+
* transcript's reads do not fit, or silently mis-charges one that merely
|
|
171
|
+
* differs in value, so the distinction rests on the member name alone.
|
|
172
|
+
*/
|
|
173
|
+
readonly preContractState: ContractExecutable.ContractExecutable.CallPartitionInputs['state'];
|
|
174
|
+
/**
|
|
175
|
+
* The state the call LEFT, i.e. compact-js's own `contractState`.
|
|
176
|
+
*
|
|
177
|
+
* See {@link TranscriptPojo.preContractState}: the two are the same type.
|
|
178
|
+
*/
|
|
179
|
+
readonly postContractState: ContractExecutable.ContractExecutable.ContractCallPublic['contractState'];
|
|
180
|
+
/**
|
|
181
|
+
* The post-call state as an {@link EncodedStateValue}: the same value
|
|
182
|
+
* {@link postContractState} holds, in the form that survives this process.
|
|
183
|
+
*
|
|
184
|
+
* `EncodedStateValue` is pinned identical across the retained and current
|
|
185
|
+
* runtimes, so this is the member era-agnostic code reads, and the one that
|
|
186
|
+
* can be persisted, cloned or sent to a worker.
|
|
187
|
+
*/
|
|
188
|
+
readonly postContractStateEncoded: EncodedStateValue;
|
|
189
|
+
readonly privateStateAfter: unknown;
|
|
190
|
+
readonly partitionContext: PartitionContext;
|
|
191
|
+
readonly zswapLocalState: ContractExecutable.ContractExecutable.DeployResultPrivate<unknown>['zswapLocalState'];
|
|
192
|
+
}
|
|
193
|
+
/** The freshly built state a retained-era constructor produced. */
|
|
194
|
+
interface ConstructorResultPojo {
|
|
195
|
+
readonly contractState: ContractExecutable.ContractExecutable.DeployResultPublic['contractState'];
|
|
196
|
+
readonly privateState: unknown;
|
|
197
|
+
readonly zswapLocalState: ContractExecutable.ContractExecutable.DeployResultPrivate<unknown>['zswapLocalState'];
|
|
198
|
+
/**
|
|
199
|
+
* The key the state's maintenance authority was built from: the caller's own
|
|
200
|
+
* when one was named, otherwise the one compact-js sampled.
|
|
201
|
+
*
|
|
202
|
+
* REQUIRED, unlike the request's, and that asymmetry is the point — a sampled
|
|
203
|
+
* key exists nowhere else, so a result that did not report it would leave the
|
|
204
|
+
* deployment as unmaintainable as the empty committee the retained
|
|
205
|
+
* constructor writes on its own.
|
|
206
|
+
*/
|
|
207
|
+
readonly signingKey: Ledger8SigningKey;
|
|
208
|
+
}
|
|
209
|
+
/**
|
|
210
|
+
* Reads verifier keys for the entry points a contract declares.
|
|
211
|
+
*
|
|
212
|
+
* A plain function rather than compact-js's `ZKConfiguration` service, so no
|
|
213
|
+
* Effect type reaches this package's callers; {@link zkConfigurationLayer}
|
|
214
|
+
* adapts it where the service is needed.
|
|
215
|
+
*/
|
|
216
|
+
type VerifierKeyReader = (provableCircuitId: string) => Promise<Uint8Array | undefined>;
|
|
217
|
+
/** Everything {@link runLedger8Circuit} needs to run one circuit. */
|
|
218
|
+
interface Ledger8CircuitOptions<C extends Ledger8EngineContract, PS> {
|
|
219
|
+
readonly contract: C;
|
|
220
|
+
readonly circuitId: string;
|
|
221
|
+
readonly args: readonly unknown[];
|
|
222
|
+
/**
|
|
223
|
+
* The contract state the call runs against, DECODED — the primary state in
|
|
224
|
+
* its era-neutral encoded form, with the balances the contract holds beside
|
|
225
|
+
* it.
|
|
226
|
+
*
|
|
227
|
+
* Era-neutral rather than one era's serialized bytes, because a contract that
|
|
228
|
+
* an earlier post-fork call has already migrated carries a CURRENT-era
|
|
229
|
+
* envelope while still executing on the retained runtime. Chain bytes would
|
|
230
|
+
* have to be decoded by the era that wrote them; this shape is what both
|
|
231
|
+
* envelopes' readers produce, so one path serves a pre-fork contract and a
|
|
232
|
+
* migrated one alike.
|
|
233
|
+
*
|
|
234
|
+
* The balance travels on the same value, so the two halves cannot come off
|
|
235
|
+
* different reads. {@link executableStateFrom} writes it onto a whole
|
|
236
|
+
* `ContractState`, which is the only form the retained runtime reads a
|
|
237
|
+
* balance from — handed a bare state value it substitutes an empty map, and a
|
|
238
|
+
* circuit reading a balance then executes against nothing with every guard
|
|
239
|
+
* green. That substitution is what #1345 was.
|
|
240
|
+
*/
|
|
241
|
+
readonly contractState: ContractStatePojo;
|
|
242
|
+
readonly address: string;
|
|
243
|
+
readonly coinPk: string;
|
|
244
|
+
readonly privateState: PS;
|
|
245
|
+
/**
|
|
246
|
+
* The execution clock, in SECONDS since the epoch. Omitted, the wall clock is
|
|
247
|
+
* used.
|
|
248
|
+
*
|
|
249
|
+
* Lands on the query context's `block.secondsSinceEpoch`, which
|
|
250
|
+
* {@link TranscriptPojo.partitionContext} reports — so without pinning it a
|
|
251
|
+
* recorded fixture differs on every run
|
|
252
|
+
* (midnightntwrk/midnight-sdk#403).
|
|
253
|
+
*/
|
|
254
|
+
readonly nowSeconds?: number;
|
|
255
|
+
}
|
|
256
|
+
/** Everything {@link runLedger8Constructor} needs to run one constructor. */
|
|
257
|
+
interface Ledger8ConstructorOptions<C extends Ledger8EngineContract, PS> {
|
|
258
|
+
readonly contract: C;
|
|
259
|
+
readonly args: readonly unknown[];
|
|
260
|
+
readonly privateState: PS;
|
|
261
|
+
readonly coinPk: string;
|
|
262
|
+
/**
|
|
263
|
+
* The key the contract's maintenance authority is built from. Optional:
|
|
264
|
+
* compact-js samples one when it is absent, and the result reports whichever
|
|
265
|
+
* was used.
|
|
266
|
+
*/
|
|
267
|
+
readonly signingKey?: Ledger8SigningKey;
|
|
268
|
+
/** Reads the verifier key for each entry point the constructor registers. */
|
|
269
|
+
readonly verifierKeys: VerifierKeyReader;
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
/**
|
|
273
|
+
* Everything {@link wrapKeepStateCall} needs to wrap one keep-state call.
|
|
274
|
+
* `contractState` is the migrated, post-fork v9 `ContractState` — read from
|
|
275
|
+
* chain, or otherwise carrying the contract's real registered operations —
|
|
276
|
+
* used only to look up the `ContractOperation` for `transcript.circuitId`
|
|
277
|
+
* (mirrors `ComposeLedger8CallOptions`'s `contractState` parameter in
|
|
278
|
+
* `../v8/compose.ts`).
|
|
279
|
+
*/
|
|
280
|
+
interface WrapKeepStateCallOptions {
|
|
281
|
+
readonly transcript: TranscriptPojo;
|
|
282
|
+
readonly contractAddress: string;
|
|
283
|
+
readonly contractState: ledgerV9.ContractState;
|
|
284
|
+
/**
|
|
285
|
+
* The ledger parameters of the block this call is built against, or
|
|
286
|
+
* {@link INITIAL_LEDGER_PARAMETERS} to accept the initial cost model.
|
|
287
|
+
*
|
|
288
|
+
* Required rather than defaulted, and not hard-coded to the initial parameters here: the
|
|
289
|
+
* transcript crosses as `'unpartitioned'`, so the partitioner DOES run and the cost model it uses
|
|
290
|
+
* is whatever this supplies. Defaulting it would make this function the silent
|
|
291
|
+
* wrong-cost-model path the option exists to close. See {@link LedgerParametersOption}.
|
|
292
|
+
*/
|
|
293
|
+
readonly ledgerParametersBytes: LedgerParametersOption;
|
|
294
|
+
}
|
|
295
|
+
|
|
296
|
+
/** The one change a maintenance transaction carries. */
|
|
297
|
+
type Ledger8MaintenanceUpdateRequest = {
|
|
298
|
+
readonly kind: 'insert-verifier-key';
|
|
299
|
+
readonly circuitId: string;
|
|
300
|
+
readonly verifierKey: Uint8Array;
|
|
301
|
+
} | {
|
|
302
|
+
readonly kind: 'remove-verifier-key';
|
|
303
|
+
readonly circuitId: string;
|
|
304
|
+
} | {
|
|
305
|
+
readonly kind: 'replace-authority';
|
|
306
|
+
readonly newSigningKey: Ledger8SigningKey;
|
|
307
|
+
};
|
|
308
|
+
/**
|
|
309
|
+
* Everything {@link composeLedger8MaintenanceTx} needs.
|
|
310
|
+
*
|
|
311
|
+
* `contractStateBytes` is the contract's FULL serialized state as the chain
|
|
312
|
+
* holds it: the update is valid only against its maintenance authority's
|
|
313
|
+
* counter, and only a key in that authority's committee may sign it.
|
|
314
|
+
*/
|
|
315
|
+
interface Ledger8MaintenanceRequest {
|
|
316
|
+
readonly contract: Ledger8EngineContract;
|
|
317
|
+
readonly contractAddress: string;
|
|
318
|
+
readonly contractStateBytes: Uint8Array;
|
|
319
|
+
readonly coinPublicKey: string;
|
|
320
|
+
readonly signingKey: Ledger8SigningKey;
|
|
321
|
+
readonly networkId: string;
|
|
322
|
+
readonly ttl: Date;
|
|
323
|
+
readonly update: Ledger8MaintenanceUpdateRequest;
|
|
324
|
+
}
|
|
325
|
+
|
|
326
|
+
/**
|
|
327
|
+
* The public surface {@link createLedger8Engine} builds: the retained pre-fork
|
|
328
|
+
* EXECUTION capabilities.
|
|
329
|
+
*
|
|
330
|
+
* The two execution members are ASYNCHRONOUS. They used to be synchronous, and
|
|
331
|
+
* the docblock here used to promise it: compact-js builds a circuit call on
|
|
332
|
+
* `Effect.tryPromise`, so `runSync` cannot discharge it and the promise is not
|
|
333
|
+
* satisfiable. Nothing else about the surface changed shape -- every value
|
|
334
|
+
* crossing it is still plain data or an era handle, and no `Effect` reaches a
|
|
335
|
+
* caller.
|
|
336
|
+
*
|
|
337
|
+
* @see {@link EraBoundary}
|
|
338
|
+
*/
|
|
339
|
+
interface Ledger8Engine {
|
|
340
|
+
/**
|
|
341
|
+
* Runs one circuit against the decoded contract state the chain serves.
|
|
342
|
+
*
|
|
343
|
+
* Takes the state and the balances beside it as ONE value -- see
|
|
344
|
+
* {@link Ledger8CircuitOptions.contractState} -- because the balances a
|
|
345
|
+
* circuit reads do not live inside the primary state, and two separate
|
|
346
|
+
* options could describe two different blocks.
|
|
347
|
+
*
|
|
348
|
+
* @throws StateConversionFailedError At stage `'state conversion'` when the
|
|
349
|
+
* state cannot be decoded, does not re-encode to its source, or carries a
|
|
350
|
+
* balance the retained runtime cannot read.
|
|
351
|
+
* @throws InvalidArgumentError When the contract declares no circuit of that name.
|
|
352
|
+
*/
|
|
353
|
+
executeCircuit<C extends Ledger8EngineContract, PS>(options: Ledger8CircuitOptions<C, PS>): Promise<TranscriptPojo>;
|
|
354
|
+
/**
|
|
355
|
+
* Runs one retained-era constructor and returns the state it built.
|
|
356
|
+
*
|
|
357
|
+
* ASYNCHRONOUS for the same reason {@link Ledger8Engine.executeCircuit} is.
|
|
358
|
+
* Stricter than the leg it replaced: compact-js registers a verifier key
|
|
359
|
+
* against every declared entry point and refuses a missing one, where the
|
|
360
|
+
* hand-written constructor left every slot blank.
|
|
361
|
+
*
|
|
362
|
+
* @throws ComposeOptionError Naming option `'signingKey'` when a supplied key
|
|
363
|
+
* is not the 32 bytes of hex the retained runtime reads.
|
|
364
|
+
* @throws ComposeFailedError At stage `'deploy-verifier-key-blob'` when the
|
|
365
|
+
* ledger refuses the bytes served for a circuit.
|
|
366
|
+
*/
|
|
367
|
+
executeConstructor<C extends Ledger8EngineContract, PS>(options: Ledger8ConstructorOptions<C, PS>): Promise<ConstructorResultPojo>;
|
|
368
|
+
wrapKeepStateCall(options: WrapKeepStateCallOptions): ContractCallPrototype;
|
|
369
|
+
/**
|
|
370
|
+
* Composes an UNPROVEN v8 transaction carrying one maintenance update --
|
|
371
|
+
* insert a verifier key, remove one, or replace the maintenance authority --
|
|
372
|
+
* built and signed by compact-js's ledger 8 `ContractExecutable`.
|
|
373
|
+
*
|
|
374
|
+
* ASYNCHRONOUS for the same reason {@link Ledger8Engine.executeCircuit} is.
|
|
375
|
+
* Reads the FULL state off the bytes the chain holds, and refuses a signing
|
|
376
|
+
* key other than the committee's first member before anything is signed.
|
|
377
|
+
*
|
|
378
|
+
* @throws ComposeOptionError Naming `'networkId'`, `'ttl'`, `'signingKey'`,
|
|
379
|
+
* `'newSigningKey'` or `'contractStateBytes'` when that option is unusable.
|
|
380
|
+
* @throws MaintenanceAuthorityMismatchError When the signing key is not the
|
|
381
|
+
* committee's first member.
|
|
382
|
+
* @throws ComposeFailedError At stage `'maintenance-update'` when compact-js
|
|
383
|
+
* refuses to build or sign the update.
|
|
384
|
+
*/
|
|
385
|
+
composeMaintenanceTx(request: Ledger8MaintenanceRequest): Promise<Uint8Array>;
|
|
386
|
+
/**
|
|
387
|
+
* Re-expresses a ledger 8 contract's entry points as a ledger 9 contract state, so a
|
|
388
|
+
* keep-state call has an operation registry the ledger 9 composer can read.
|
|
389
|
+
*
|
|
390
|
+
* Fork-crossing work, which is why it sits here rather than on either era facade: the input is
|
|
391
|
+
* what the ledger 8 decoder read off the chain, and the output is for ledger 9.
|
|
392
|
+
*/
|
|
393
|
+
reexpressOperationsForLedger9(entryPoints: readonly ContractEntryPointPojo[]): Uint8Array;
|
|
394
|
+
}
|
|
395
|
+
/**
|
|
396
|
+
* Builds a {@link Ledger8Engine}.
|
|
397
|
+
*
|
|
398
|
+
* The retained toolchain is no longer acquired here: compact-js's era-pinned
|
|
399
|
+
* ledger-8 entries own it, and `lib/v8/executable.ts` reaches them. What this
|
|
400
|
+
* function still does is sit behind the dynamic `import('../../engine.js')` in
|
|
401
|
+
* `lib/v8/load-engine.ts`, so importing the package root never pulls the
|
|
402
|
+
* multi-megabyte retained WASM onto the module graph.
|
|
403
|
+
*
|
|
404
|
+
* It no longer runs a dual-instantiation guard either. That guard compared
|
|
405
|
+
* `onchain-runtime-v3` against the 0.16 glue at construction time. Both
|
|
406
|
+
* acquisition paths are still live — `lib/v8/executable.ts` imports the glue
|
|
407
|
+
* directly, and compact-js resolves the same specifier for itself — so the axis
|
|
408
|
+
* did not go away; only the runtime check did. The invariant is held at install
|
|
409
|
+
* time instead, by `src/test/single-instance.test.ts`, which pins one resolved
|
|
410
|
+
* copy of `onchain-runtime-v3` and of each compact-runtime era line. That is a
|
|
411
|
+
* check on THIS repo's lockfile, not on a consumer's process.
|
|
412
|
+
*
|
|
413
|
+
* @returns The engine surface.
|
|
414
|
+
* @see {@link EraBoundary}
|
|
415
|
+
* @see {@link ModuleGraphAndLazyLoading}
|
|
416
|
+
*/
|
|
417
|
+
declare const createLedger8Engine: () => Promise<Ledger8Engine>;
|
|
418
|
+
|
|
419
|
+
export { createLedger8Engine };
|
|
420
|
+
export type { ConstructorResultPojo, ContractBalance, ContractEntryPointPojo, ContractStatePojo, Ledger8CircuitOptions, Ledger8ConstructorOptions, Ledger8Engine, Ledger8EngineContract, Ledger8MaintenanceRequest, Ledger8MaintenanceUpdateRequest, Ledger8SigningKey, TranscriptPojo, VerifierKeyReader, WrapKeepStateCallOptions };
|