@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/errors.js
ADDED
|
@@ -0,0 +1,810 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* This file is part of midnight-js.
|
|
3
|
+
* Copyright (C) Midnight Foundation
|
|
4
|
+
* SPDX-License-Identifier: Apache-2.0
|
|
5
|
+
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
6
|
+
* You may not use this file except in compliance with the License.
|
|
7
|
+
* You may obtain a copy of the License at
|
|
8
|
+
* http://www.apache.org/licenses/LICENSE-2.0
|
|
9
|
+
* Unless required by applicable law or agreed to in writing, software
|
|
10
|
+
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
11
|
+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
12
|
+
* See the License for the specific language governing permissions and
|
|
13
|
+
* limitations under the License.
|
|
14
|
+
*/
|
|
15
|
+
/**
|
|
16
|
+
* Every message in a failure's cause chain, outermost first.
|
|
17
|
+
*
|
|
18
|
+
* compact-js reports an execution failure as `Error executing circuit 'x'` and
|
|
19
|
+
* hangs the runtime's own diagnostic -- `Block time is <= time`, an out-of-gas,
|
|
20
|
+
* a failed assertion -- on `cause`. Only the outer message reaches a caller who
|
|
21
|
+
* reads `error.message`, so the reason the circuit ACTUALLY failed is lost at
|
|
22
|
+
* exactly the moment someone needs it.
|
|
23
|
+
*/
|
|
24
|
+
const causeChain = (error, seen = new Set()) => {
|
|
25
|
+
if (typeof error !== 'object' || error === null || seen.has(error)) {
|
|
26
|
+
return typeof error === 'string' ? [error] : [];
|
|
27
|
+
}
|
|
28
|
+
seen.add(error);
|
|
29
|
+
const message = 'message' in error && typeof error.message === 'string' ? [error.message] : [];
|
|
30
|
+
return 'cause' in error ? [...message, ...causeChain(error.cause, seen)] : message;
|
|
31
|
+
};
|
|
32
|
+
|
|
33
|
+
/*
|
|
34
|
+
* This file is part of midnight-js.
|
|
35
|
+
* Copyright (C) Midnight Foundation
|
|
36
|
+
* SPDX-License-Identifier: Apache-2.0
|
|
37
|
+
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
38
|
+
* You may not use this file except in compliance with the License.
|
|
39
|
+
* You may obtain a copy of the License at
|
|
40
|
+
* http://www.apache.org/licenses/LICENSE-2.0
|
|
41
|
+
* Unless required by applicable law or agreed to in writing, software
|
|
42
|
+
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
43
|
+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
44
|
+
* See the License for the specific language governing permissions and
|
|
45
|
+
* limitations under the License.
|
|
46
|
+
*/
|
|
47
|
+
/**
|
|
48
|
+
* Stable error-code strings for this package. Every error class in this module
|
|
49
|
+
* carries one of these on its `code` field, which is the field a consumer
|
|
50
|
+
* switches on to tell one failure from another.
|
|
51
|
+
*
|
|
52
|
+
* @see {@link SharedTableDiscipline}
|
|
53
|
+
*/
|
|
54
|
+
const PROTOCOL_ERROR_CODES = Object.freeze({
|
|
55
|
+
UNKNOWN_PROTOCOL_VERSION_READ: 'MIDNIGHT_JS_P_UNKNOWN_PROTOCOL_VERSION_READ',
|
|
56
|
+
UNKNOWN_PROTOCOL_VERSION_CONSTRUCT: 'MIDNIGHT_JS_P_UNKNOWN_PROTOCOL_VERSION_CONSTRUCT',
|
|
57
|
+
LEDGER8_RUNTIME_MISSING: 'MIDNIGHT_JS_P_LEDGER8_RUNTIME_MISSING',
|
|
58
|
+
STATE_CONVERSION_FAILED: 'MIDNIGHT_JS_P_STATE_CONVERSION_FAILED',
|
|
59
|
+
COMPOSE_FAILED: 'MIDNIGHT_JS_P_COMPOSE_FAILED',
|
|
60
|
+
COMPOSE_OPTION_INVALID: 'MIDNIGHT_JS_P_COMPOSE_OPTION_INVALID',
|
|
61
|
+
STATE_DECODE_FAILED: 'MIDNIGHT_JS_P_STATE_DECODE_FAILED',
|
|
62
|
+
STATE_INCONSISTENT: 'MIDNIGHT_JS_P_STATE_INCONSISTENT',
|
|
63
|
+
UNKNOWN_LEDGER_ERA: 'MIDNIGHT_JS_P_UNKNOWN_LEDGER_ERA',
|
|
64
|
+
LEDGER8_RUNTIME_INVALID: 'MIDNIGHT_JS_P_LEDGER8_RUNTIME_INVALID',
|
|
65
|
+
PAYLOAD_NOT_A_TRANSACTION: 'MIDNIGHT_JS_P_PAYLOAD_NOT_A_TRANSACTION',
|
|
66
|
+
CONTRACT_EXECUTION_FAILED: 'MIDNIGHT_JS_P_CONTRACT_EXECUTION_FAILED',
|
|
67
|
+
MAINTENANCE_AUTHORITY_MISMATCH: 'MIDNIGHT_JS_P_MAINTENANCE_AUTHORITY_MISMATCH'
|
|
68
|
+
});
|
|
69
|
+
const MIDNIGHT_JS_ERROR_CATEGORIES = Object.freeze({
|
|
70
|
+
USAGE: 'USAGE',
|
|
71
|
+
ENVIRONMENT: 'ENVIRONMENT',
|
|
72
|
+
TRANSIENT: 'TRANSIENT',
|
|
73
|
+
REJECTED: 'REJECTED',
|
|
74
|
+
UNCERTAIN: 'UNCERTAIN',
|
|
75
|
+
INTEGRITY: 'INTEGRITY',
|
|
76
|
+
INTERNAL: 'INTERNAL'
|
|
77
|
+
});
|
|
78
|
+
/**
|
|
79
|
+
* Base class of every error midnight-js raises itself. An error without a registered code came from a
|
|
80
|
+
* dependency, the platform or user code, and midnight-js passed it through unchanged. Recognise one with
|
|
81
|
+
* `hasErrorCode`, `isMidnightJsError` or `errorCategory` from the `midnight-js-utils` package: they read
|
|
82
|
+
* `code`, so they also work when two copies of a package are installed, where `instanceof` does not.
|
|
83
|
+
*/
|
|
84
|
+
// eslint-disable-next-line no-restricted-syntax -- the one class allowed to extend Error directly
|
|
85
|
+
class MidnightJsError extends Error {
|
|
86
|
+
}
|
|
87
|
+
const { USAGE, ENVIRONMENT, REJECTED, INTEGRITY, INTERNAL } = MIDNIGHT_JS_ERROR_CATEGORIES;
|
|
88
|
+
const PROTOCOL_ERROR_CATEGORIES = Object.freeze({
|
|
89
|
+
[PROTOCOL_ERROR_CODES.UNKNOWN_PROTOCOL_VERSION_READ]: ENVIRONMENT,
|
|
90
|
+
[PROTOCOL_ERROR_CODES.UNKNOWN_PROTOCOL_VERSION_CONSTRUCT]: ENVIRONMENT,
|
|
91
|
+
[PROTOCOL_ERROR_CODES.LEDGER8_RUNTIME_MISSING]: ENVIRONMENT,
|
|
92
|
+
[PROTOCOL_ERROR_CODES.STATE_CONVERSION_FAILED]: INTEGRITY,
|
|
93
|
+
[PROTOCOL_ERROR_CODES.COMPOSE_FAILED]: USAGE,
|
|
94
|
+
[PROTOCOL_ERROR_CODES.COMPOSE_OPTION_INVALID]: USAGE,
|
|
95
|
+
[PROTOCOL_ERROR_CODES.STATE_DECODE_FAILED]: INTEGRITY,
|
|
96
|
+
[PROTOCOL_ERROR_CODES.STATE_INCONSISTENT]: INTEGRITY,
|
|
97
|
+
[PROTOCOL_ERROR_CODES.UNKNOWN_LEDGER_ERA]: ENVIRONMENT,
|
|
98
|
+
[PROTOCOL_ERROR_CODES.LEDGER8_RUNTIME_INVALID]: ENVIRONMENT,
|
|
99
|
+
[PROTOCOL_ERROR_CODES.PAYLOAD_NOT_A_TRANSACTION]: USAGE,
|
|
100
|
+
[PROTOCOL_ERROR_CODES.CONTRACT_EXECUTION_FAILED]: REJECTED,
|
|
101
|
+
[PROTOCOL_ERROR_CODES.MAINTENANCE_AUTHORITY_MISMATCH]: USAGE
|
|
102
|
+
});
|
|
103
|
+
const COMMON_ERROR_CODES = Object.freeze({
|
|
104
|
+
INVALID_ARGUMENT: 'MIDNIGHT_JS_G_INVALID_ARGUMENT',
|
|
105
|
+
CONFIGURATION_MISSING: 'MIDNIGHT_JS_G_CONFIGURATION_MISSING',
|
|
106
|
+
ENVIRONMENT_UNSUPPORTED: 'MIDNIGHT_JS_G_ENVIRONMENT_UNSUPPORTED',
|
|
107
|
+
INVARIANT_VIOLATED: 'MIDNIGHT_JS_G_INVARIANT_VIOLATED'
|
|
108
|
+
});
|
|
109
|
+
const COMMON_ERROR_CATEGORIES = Object.freeze({
|
|
110
|
+
[COMMON_ERROR_CODES.INVALID_ARGUMENT]: USAGE,
|
|
111
|
+
[COMMON_ERROR_CODES.CONFIGURATION_MISSING]: USAGE,
|
|
112
|
+
[COMMON_ERROR_CODES.ENVIRONMENT_UNSUPPORTED]: ENVIRONMENT,
|
|
113
|
+
[COMMON_ERROR_CODES.INVARIANT_VIOLATED]: INTERNAL
|
|
114
|
+
});
|
|
115
|
+
/** A value passed to a midnight-js function is not acceptable. Fix the call. */
|
|
116
|
+
class InvalidArgumentError extends MidnightJsError {
|
|
117
|
+
code = COMMON_ERROR_CODES.INVALID_ARGUMENT;
|
|
118
|
+
category = COMMON_ERROR_CATEGORIES[COMMON_ERROR_CODES.INVALID_ARGUMENT];
|
|
119
|
+
constructor(message, options) {
|
|
120
|
+
super(message, options);
|
|
121
|
+
this.name = 'InvalidArgumentError';
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
/** Required setup is missing or was done in the wrong order. */
|
|
125
|
+
class ConfigurationError extends MidnightJsError {
|
|
126
|
+
code = COMMON_ERROR_CODES.CONFIGURATION_MISSING;
|
|
127
|
+
category = COMMON_ERROR_CATEGORIES[COMMON_ERROR_CODES.CONFIGURATION_MISSING];
|
|
128
|
+
constructor(message, options) {
|
|
129
|
+
super(message, options);
|
|
130
|
+
this.name = 'ConfigurationError';
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
/** The JavaScript runtime lacks an API midnight-js needs. */
|
|
134
|
+
class EnvironmentUnsupportedError extends MidnightJsError {
|
|
135
|
+
code = COMMON_ERROR_CODES.ENVIRONMENT_UNSUPPORTED;
|
|
136
|
+
category = COMMON_ERROR_CATEGORIES[COMMON_ERROR_CODES.ENVIRONMENT_UNSUPPORTED];
|
|
137
|
+
constructor(message, options) {
|
|
138
|
+
super(message, options);
|
|
139
|
+
this.name = 'EnvironmentUnsupportedError';
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
/** A condition midnight-js guarantees did not hold. This is a midnight-js bug; report it. */
|
|
143
|
+
class InvariantViolationError extends MidnightJsError {
|
|
144
|
+
code = COMMON_ERROR_CODES.INVARIANT_VIOLATED;
|
|
145
|
+
category = COMMON_ERROR_CATEGORIES[COMMON_ERROR_CODES.INVARIANT_VIOLATED];
|
|
146
|
+
constructor(message, options) {
|
|
147
|
+
super(message, options);
|
|
148
|
+
this.name = 'InvariantViolationError';
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
/**
|
|
152
|
+
* Thrown by `protocolVersionToLedger` (and, transitively, `versionOfRecord` /
|
|
153
|
+
* `latestNetworkLedgerVersion`) when a raw `protocolVersion` integer cannot be
|
|
154
|
+
* resolved to a `LedgerEra`. Those live in `./version`, which imports this
|
|
155
|
+
* module -- the dependency stays one-way, so they are named here rather than
|
|
156
|
+
* linked.
|
|
157
|
+
*
|
|
158
|
+
* `code` is the field to switch on to tell all four cases apart: it splits
|
|
159
|
+
* `reason` by the `path` that produced it.
|
|
160
|
+
*
|
|
161
|
+
* @param protocolVersion The raw `protocolVersion` value that could not be
|
|
162
|
+
* resolved. Carried for programmatic use, and rendered in the message.
|
|
163
|
+
* @param path Which call path asked for the version — see
|
|
164
|
+
* {@link VersionResolutionPath}.
|
|
165
|
+
* @param reason A malformed input (wrong shape or type, not a
|
|
166
|
+
* protocol-version problem at all) or a well-formed but genuinely unknown
|
|
167
|
+
* version (a real protocol version this framework build does not support
|
|
168
|
+
* yet) — see {@link ProtocolVersionUnknownReason}.
|
|
169
|
+
*/
|
|
170
|
+
class UnknownProtocolVersionError extends MidnightJsError {
|
|
171
|
+
protocolVersion;
|
|
172
|
+
path;
|
|
173
|
+
reason;
|
|
174
|
+
code;
|
|
175
|
+
category;
|
|
176
|
+
constructor(protocolVersion, path, reason) {
|
|
177
|
+
super(reason === 'malformed'
|
|
178
|
+
? `Malformed protocolVersion (expected a non-negative integer, got ${typeof protocolVersion} ` +
|
|
179
|
+
`${String(protocolVersion)}) on the ${path} path. This usually means a non-numeric, fractional, or ` +
|
|
180
|
+
`negative value reached protocolVersionToLedger — check that the source field is actually a raw ` +
|
|
181
|
+
`protocolVersion integer (e.g. from an indexer transaction/block record or ` +
|
|
182
|
+
`queryLatestProtocolVersion()), not a derived or miscoded value.`
|
|
183
|
+
: `Unknown protocolVersion ${protocolVersion} on the ${path} path. ` +
|
|
184
|
+
`Supported eras: v8 (node 1.x) and v9 (node 2.x). ` +
|
|
185
|
+
`An unknown node major usually means this framework major predates a newer fork — upgrade midnight-js.`);
|
|
186
|
+
this.protocolVersion = protocolVersion;
|
|
187
|
+
this.path = path;
|
|
188
|
+
this.reason = reason;
|
|
189
|
+
this.name = 'UnknownProtocolVersionError';
|
|
190
|
+
this.code =
|
|
191
|
+
path === 'read'
|
|
192
|
+
? PROTOCOL_ERROR_CODES.UNKNOWN_PROTOCOL_VERSION_READ
|
|
193
|
+
: PROTOCOL_ERROR_CODES.UNKNOWN_PROTOCOL_VERSION_CONSTRUCT;
|
|
194
|
+
this.category = PROTOCOL_ERROR_CATEGORIES[this.code];
|
|
195
|
+
}
|
|
196
|
+
}
|
|
197
|
+
/**
|
|
198
|
+
* Thrown when a lazily-loaded subpath export carrying the retained pre-fork
|
|
199
|
+
* runtime could not be acquired at all. Raised by `loadLedger8Protocol`
|
|
200
|
+
* (`lib/v8/load.ts`) and `loadLedger8Engine` (`lib/v8/load-engine.ts`), and
|
|
201
|
+
* surfaced through `createLedger8Engine` and `loadLedgerEra('v8')`.
|
|
202
|
+
*
|
|
203
|
+
* A failed acquisition is not memoised: the next call retries the import.
|
|
204
|
+
* Distinct from {@link Ledger8RuntimeInvalidError}, which reports a runtime
|
|
205
|
+
* that WAS acquired and then handed over incomplete.
|
|
206
|
+
*
|
|
207
|
+
* @param subpath Which chunk failed to load — see {@link Ledger8Subpath}.
|
|
208
|
+
* @param cause The underlying module-resolution or initialisation failure,
|
|
209
|
+
* preserved unchanged. Read it for which module actually failed.
|
|
210
|
+
* @see {@link ModuleGraphAndLazyLoading}
|
|
211
|
+
* @see {@link EraBoundary}
|
|
212
|
+
*/
|
|
213
|
+
class Ledger8RuntimeMissingError extends MidnightJsError {
|
|
214
|
+
subpath;
|
|
215
|
+
code = PROTOCOL_ERROR_CODES.LEDGER8_RUNTIME_MISSING;
|
|
216
|
+
category = PROTOCOL_ERROR_CATEGORIES[PROTOCOL_ERROR_CODES.LEDGER8_RUNTIME_MISSING];
|
|
217
|
+
constructor(subpath, cause) {
|
|
218
|
+
super(`Failed to load the ledger 8 (pre-fork) runtime via the midnight-js-protocol${subpath} subpath export. ` +
|
|
219
|
+
'Read the wrapped cause for which module actually failed to resolve or initialise. This usually means ' +
|
|
220
|
+
'a broken or partial install of the protocol package — reinstall dependencies and retry.', { cause });
|
|
221
|
+
this.subpath = subpath;
|
|
222
|
+
this.name = 'Ledger8RuntimeMissingError';
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
/**
|
|
226
|
+
* Thrown when a serialized contract state, or an already-extracted
|
|
227
|
+
* `EncodedStateValue`, cannot be turned into a state a circuit can execute
|
|
228
|
+
* against. Raised by `extractLedger9EncodedStateValue` (`lib/era/envelope.ts`)
|
|
229
|
+
* and by `decodeExecutableStateValue` (`lib/v8/executable.ts`), which refuses a
|
|
230
|
+
* state that decodes but does not re-encode to the bytes it came from.
|
|
231
|
+
*
|
|
232
|
+
* Renders no raw hex and no decoded state contents — only the stage name and
|
|
233
|
+
* the wrapped `cause`.
|
|
234
|
+
*
|
|
235
|
+
* @param stage Which step failed — see {@link StateConversionStage}.
|
|
236
|
+
* @param cause The runtime's own failure, preserved unchanged. It is what
|
|
237
|
+
* distinguishes a tag mismatch from truncated, trailing, or empty input.
|
|
238
|
+
* @see {@link FailClosedDecoding}
|
|
239
|
+
*/
|
|
240
|
+
class StateConversionFailedError extends MidnightJsError {
|
|
241
|
+
stage;
|
|
242
|
+
code = PROTOCOL_ERROR_CODES.STATE_CONVERSION_FAILED;
|
|
243
|
+
category = PROTOCOL_ERROR_CATEGORIES[PROTOCOL_ERROR_CODES.STATE_CONVERSION_FAILED];
|
|
244
|
+
constructor(stage, cause) {
|
|
245
|
+
super(`Failed to convert a contract state into one a circuit can execute against, during ${stage}. Read the ` +
|
|
246
|
+
'wrapped cause for what the runtime actually reported; it distinguishes a version tag for a different ' +
|
|
247
|
+
'ledger era than the one requested from truncated, trailing, or empty input bytes.', { cause });
|
|
248
|
+
this.stage = stage;
|
|
249
|
+
this.name = 'StateConversionFailedError';
|
|
250
|
+
}
|
|
251
|
+
}
|
|
252
|
+
/**
|
|
253
|
+
* What `circuitId` a {@link ComposeFailedError} names when the failure happened
|
|
254
|
+
* before any circuit was looked up — only `'call-empty'` reaches this today.
|
|
255
|
+
*
|
|
256
|
+
* Exported, and one literal rather than a per-module copy, so a consumer
|
|
257
|
+
* reading `circuitId` off a caught error can compare against it instead of
|
|
258
|
+
* matching a string this package could change, and so it can never be mistaken
|
|
259
|
+
* for a real entry point a caller might try to resolve.
|
|
260
|
+
*
|
|
261
|
+
* @see {@link ComposeRefusalOrder}
|
|
262
|
+
*/
|
|
263
|
+
const NO_CIRCUIT = '(none)';
|
|
264
|
+
/**
|
|
265
|
+
* Thrown when a transaction cannot be composed because a circuit's operation
|
|
266
|
+
* is missing, under-registered, or names a circuit the contract does not have.
|
|
267
|
+
* `stage` (see {@link ComposeStage}) names which composition step failed and is
|
|
268
|
+
* a closed union, so a consumer can `switch` on it exhaustively; `version`
|
|
269
|
+
* names the ledger era the composition was running against.
|
|
270
|
+
*
|
|
271
|
+
* Most stages carry no `cause`. The exceptions are the stages where a runtime
|
|
272
|
+
* library rejected what it was handed, enumerated under `cause` below.
|
|
273
|
+
*
|
|
274
|
+
* `circuitId` names the entry point, never its raw contents: this class renders
|
|
275
|
+
* no hex and no byte-array dump.
|
|
276
|
+
*
|
|
277
|
+
* @param version The ledger era the composition was running against.
|
|
278
|
+
* @param stage Which composition step failed — see {@link ComposeStage}. A
|
|
279
|
+
* closed union, so a consumer can `switch` on it exhaustively.
|
|
280
|
+
* @param circuitId The entry-point name, already decoded. {@link NO_CIRCUIT}
|
|
281
|
+
* for `'call-empty'`, the one stage raised before any circuit is looked up.
|
|
282
|
+
* @param cause The runtime's own failure, present only for the stages where
|
|
283
|
+
* the ledger rejected caller-supplied bytes — `'call-contract-state'`,
|
|
284
|
+
* `'call-partition-context'`, `'call-partition'`, `'call-prototype'`,
|
|
285
|
+
* `'deploy-verifier-key-blob'` — and for `'maintenance-update'`, where it is
|
|
286
|
+
* the failure of platform-js, compact-js or the ledger, whichever refused.
|
|
287
|
+
* @see {@link ComposeRefusalOrder}
|
|
288
|
+
* @see {@link VerifierKeys}
|
|
289
|
+
*/
|
|
290
|
+
class ComposeFailedError extends MidnightJsError {
|
|
291
|
+
version;
|
|
292
|
+
stage;
|
|
293
|
+
circuitId;
|
|
294
|
+
code = PROTOCOL_ERROR_CODES.COMPOSE_FAILED;
|
|
295
|
+
category = PROTOCOL_ERROR_CATEGORIES[PROTOCOL_ERROR_CODES.COMPOSE_FAILED];
|
|
296
|
+
constructor(version, stage, circuitId, cause) {
|
|
297
|
+
super(ComposeFailedError.MESSAGES[stage](version, circuitId), { cause });
|
|
298
|
+
this.version = version;
|
|
299
|
+
this.stage = stage;
|
|
300
|
+
this.circuitId = circuitId;
|
|
301
|
+
this.name = 'ComposeFailedError';
|
|
302
|
+
}
|
|
303
|
+
// A total Record, and every entry takes the era rather than naming one --
|
|
304
|
+
// see SharedTableDiscipline. Keep both properties when adding a stage.
|
|
305
|
+
static MESSAGES = {
|
|
306
|
+
'wrap-call': (version, circuitId) => `Failed to compose a ${version}-native keep-state call: no registered operation found for circuit ` +
|
|
307
|
+
`'${circuitId}' on the given contract state. This usually means the contract state passed to ` +
|
|
308
|
+
'wrapKeepStateCall was not read from chain (or produced by a real deploy) — a bare/blank contract ' +
|
|
309
|
+
'state has no operations registered. Resolve the contract state that carries the deployed operation ' +
|
|
310
|
+
'for this circuit and pass that instead.',
|
|
311
|
+
'call-empty': (version) => `Refusing to compose a ${version} call transaction with no calls in it. An empty intent is accepted by ` +
|
|
312
|
+
'the ledger and serializes into a transaction that changes nothing, so the omission would only surface ' +
|
|
313
|
+
'as a call that appeared to succeed and had no effect. Pass at least one call.',
|
|
314
|
+
'call-operation': (version, circuitId) => `Failed to compose a ${version} call transaction: no registered operation found for circuit ` +
|
|
315
|
+
`'${circuitId}' on the given ${version}-native contract state. This usually means the contract state ` +
|
|
316
|
+
'passed to composeCallTx was not read from chain (or produced by a real deploy) — a bare/blank ' +
|
|
317
|
+
'contract state has no operations registered. Resolve the contract state that carries the deployed ' +
|
|
318
|
+
'operation for this circuit and pass that instead.',
|
|
319
|
+
'call-contract-state': (version, circuitId) => `Failed to compose a ${version} call transaction: the pre-call state carried by the transcript for ` +
|
|
320
|
+
`circuit '${circuitId}' could not be bridged into the ${version} ledger era. Read the wrapped cause ` +
|
|
321
|
+
'for what the decoder reported; it distinguishes a state encoded by a different runtime from ' +
|
|
322
|
+
'truncated or empty input. Pass the state the era it targets produced.',
|
|
323
|
+
'call-transcript-empty': (version, circuitId) => `Failed to compose a ${version} call: the transcript supplied for circuit '${circuitId}' carries neither ` +
|
|
324
|
+
'a guaranteed nor a fallible half, so the call would record no operations at all. A transaction built ' +
|
|
325
|
+
'from it serializes, proves and submits, and changes nothing — the same silent no-op an empty call list ' +
|
|
326
|
+
'would produce. Pass the partitioned pair the execution leg produced, at least one half of which is ' +
|
|
327
|
+
'always present for a circuit that ran.',
|
|
328
|
+
'call-dust-payout': (version, circuitId) => `Failed to compose a ${version} call: the transcript for circuit '${circuitId}' claims an unshielded ` +
|
|
329
|
+
'spend to a user address in DUST, which has no raw token type to be paid out in. The transaction ' +
|
|
330
|
+
'cannot carry that payout, and composing it anyway would tell the user they were paid while the ' +
|
|
331
|
+
'transaction paid them nothing. Settle dust through its own mechanism rather than as a claimed ' +
|
|
332
|
+
'unshielded spend.',
|
|
333
|
+
'call-unsupported-payout': (version, circuitId) => `Failed to compose a ${version} call: the transcript for circuit '${circuitId}' claims an unshielded ` +
|
|
334
|
+
'spend to a user address in a token type that cannot be paid out as an unshielded UTXO — a shielded ' +
|
|
335
|
+
'token type today. Shielded value moves through a Zswap offer, not through a claimed unshielded ' +
|
|
336
|
+
'spend, so nothing can settle this claim; composing it anyway would tell the user they were paid ' +
|
|
337
|
+
'while the transaction paid them nothing. Move the shielded value through the guaranteed or fallible ' +
|
|
338
|
+
'Zswap offer instead.',
|
|
339
|
+
'call-partition-context': (version, circuitId) => `Failed to compose a ${version} call: the ${version} era rejected the query-context state recorded ` +
|
|
340
|
+
`for circuit '${circuitId}' — its block, its starting effects, or one of the commitment indices it ` +
|
|
341
|
+
'registered for a coin received in-contract. Read the wrapped cause for the member the runtime could ' +
|
|
342
|
+
'not read. Pass the context the execution leg recorded on the transcript, unmodified.',
|
|
343
|
+
'call-partition': (version, circuitId) => `Failed to compose a ${version} call: the ${version} ledger rejected the public transcript supplied ` +
|
|
344
|
+
`for circuit '${circuitId}' while splitting it into its guaranteed and fallible halves. Read the ` +
|
|
345
|
+
'wrapped cause for what the runtime reported; it names the operation and the operand it could not ' +
|
|
346
|
+
'read. Two causes are common: a hand-built or re-encoded op sequence rather than one an execution ' +
|
|
347
|
+
'leg produced, or a call that received a coin in-contract whose recorded commitment indices never ' +
|
|
348
|
+
'reached the partitioner — a transcript that reads a received coin cannot be split without them.',
|
|
349
|
+
'call-prototype': (version, circuitId) => `Failed to compose a ${version} call: the ${version} ledger rejected the inputs supplied for circuit ` +
|
|
350
|
+
`'${circuitId}' while constructing the call prototype. Read the wrapped cause for what the runtime ` +
|
|
351
|
+
'reported; it distinguishes an out-of-range numeric field from a malformed address or aligned value. ' +
|
|
352
|
+
'Every part of a call is plain data that nothing type-checks into range, so this usually means a ' +
|
|
353
|
+
'hand-built transcript pair, private transcript output, or input/output value.',
|
|
354
|
+
'call-verifier-key': (version, circuitId) => `Failed to compose a ${version} call: the operation registered for circuit '${circuitId}' carries no ` +
|
|
355
|
+
'verifier key, so no ledger could verify a call against it. This usually means the contract state came ' +
|
|
356
|
+
'from a constructor result rather than from chain — a freshly built state declares its entry points ' +
|
|
357
|
+
'with blank keys, which only a deploy transaction fills in. Pass the contract state as read from chain ' +
|
|
358
|
+
'after a successful deploy.',
|
|
359
|
+
'deploy-verifier-key': (version, circuitId) => `Failed to compose a ${version} deploy transaction: no verifier key was supplied for circuit ` +
|
|
360
|
+
`'${circuitId}', which the contract state declares as an entry point. A deploy carrying an ` +
|
|
361
|
+
"unregistered entry point is rejected by a ledger's own well-formedness check. Resolve the compiled " +
|
|
362
|
+
"contract's verifier key for this circuit (from its keys/ artifacts) and include it in the map passed " +
|
|
363
|
+
'to composeDeployTx.',
|
|
364
|
+
'deploy-unknown-circuit': (version, circuitId) => `Failed to compose a ${version} deploy transaction: the verifier-key map names circuit '${circuitId}', ` +
|
|
365
|
+
'which the contract state does not declare as an entry point. Registering it would give the deployed ' +
|
|
366
|
+
"contract an entry point its compiled source never had, and would change the deployed contract's " +
|
|
367
|
+
'address. This usually means a stale or foreign key file was picked up (for example by globbing ' +
|
|
368
|
+
'keys/*.verifier across compiler runs) — supply keys for exactly the circuits this contract declares.',
|
|
369
|
+
'deploy-ambiguous-circuit': (version, circuitId) => `Failed to compose a ${version} deploy transaction: the contract state declares two entry points that ` +
|
|
370
|
+
`both resolve to the name '${circuitId}', so a verifier-key map keyed by name cannot tell them apart. ` +
|
|
371
|
+
'Registering under that name would key one slot and leave the other blank, deploying a contract whose ' +
|
|
372
|
+
"address does not match the caller's artifacts. This is not something a compactc-built contract " +
|
|
373
|
+
'produces — it means the contract state was assembled by hand, or by a tool that set an entry point to ' +
|
|
374
|
+
'bytes that are not valid UTF-8.',
|
|
375
|
+
'deploy-verifier-key-blob': (version, circuitId) => `Failed to compose a ${version} deploy transaction: the ledger rejected the verifier-key bytes supplied ` +
|
|
376
|
+
`for circuit '${circuitId}'. Read the wrapped cause for what the ledger reported; a verifier key must ` +
|
|
377
|
+
'be the tagged blob the compiler emits as keys/<circuit>.verifier, so this usually means a truncated ' +
|
|
378
|
+
'or empty file, or a key emitted for a different ledger era.',
|
|
379
|
+
'maintenance-update': (version, circuitId) => `Failed to compose a ${version} maintenance transaction: the maintenance update could not be built ` +
|
|
380
|
+
(circuitId === NO_CIRCUIT
|
|
381
|
+
? 'to replace the maintenance authority. '
|
|
382
|
+
: `for circuit '${circuitId}'. `) +
|
|
383
|
+
'Read the wrapped cause for the step that refused it: the contract address, building the update, ' +
|
|
384
|
+
'creating it with the address and counter, reading the data to sign, signing, attaching the ' +
|
|
385
|
+
'signature, or wrapping the signed update into the transaction. A verifier key that is not the tagged ' +
|
|
386
|
+
'blob the compiler emits as keys/<circuit>.verifier is refused while building the update. A failure ' +
|
|
387
|
+
'naming an expected instance, or a null pointer, usually means a second copy of the ledger package is ' +
|
|
388
|
+
'installed, not that a key is wrong.'
|
|
389
|
+
};
|
|
390
|
+
}
|
|
391
|
+
/**
|
|
392
|
+
* Thrown by the composition legs when one of their options cannot be used at
|
|
393
|
+
* all, as opposed to {@link ComposeFailedError}, which reports a circuit whose
|
|
394
|
+
* operation is missing or under-registered.
|
|
395
|
+
*
|
|
396
|
+
* These are the well-formedness checks the ledger itself does not make.
|
|
397
|
+
*
|
|
398
|
+
* Like {@link StateConversionFailedError}, this class renders no input contents of
|
|
399
|
+
* its own.
|
|
400
|
+
*
|
|
401
|
+
* @param version The ledger era the option was being used against.
|
|
402
|
+
* @param option Which option was unusable — see {@link ComposeOption}. A
|
|
403
|
+
* closed union, so a consumer can `switch` on it exhaustively.
|
|
404
|
+
* @param cause The decoder's own failure, present where caller-supplied bytes
|
|
405
|
+
* were rejected.
|
|
406
|
+
* @see {@link ComposeRefusalOrder}
|
|
407
|
+
* @see {@link VerifierKeys}
|
|
408
|
+
*/
|
|
409
|
+
class ComposeOptionError extends MidnightJsError {
|
|
410
|
+
version;
|
|
411
|
+
option;
|
|
412
|
+
code = PROTOCOL_ERROR_CODES.COMPOSE_OPTION_INVALID;
|
|
413
|
+
category = PROTOCOL_ERROR_CATEGORIES[PROTOCOL_ERROR_CODES.COMPOSE_OPTION_INVALID];
|
|
414
|
+
constructor(version, option, cause) {
|
|
415
|
+
super(ComposeOptionError.MESSAGES[option](version), { cause });
|
|
416
|
+
this.version = version;
|
|
417
|
+
this.option = option;
|
|
418
|
+
this.name = 'ComposeOptionError';
|
|
419
|
+
}
|
|
420
|
+
// A total Record, for exactly the reason `ComposeFailedError.MESSAGES` above
|
|
421
|
+
// is one -- see SharedTableDiscipline. Never make this an if-chain.
|
|
422
|
+
static MESSAGES = {
|
|
423
|
+
contractStateBytes: (version) => `Failed to compose a ${version} transaction: the given contract state could not be bridged into the ` +
|
|
424
|
+
`${version} ledger era. Read the wrapped cause for what the decoder reported; it distinguishes an ` +
|
|
425
|
+
'version tag for a different ledger era from truncated or empty input bytes. Pass the contract ' +
|
|
426
|
+
'state the era it targets produced, not one already converted to another era or otherwise re-tagged.',
|
|
427
|
+
ledgerParametersBytes: (version) => `Failed to compose a ${version} transaction: the supplied ledger parameters could not be read by the ` +
|
|
428
|
+
`${version} ledger. They are era-tagged, so bytes read from a block of the other era will be refused ` +
|
|
429
|
+
'here — read the wrapped cause for the tag the decoder found. Pass the parameters the block this call ' +
|
|
430
|
+
'is built against served: the bytes of `ContractStateAndParametersRead.ledgerParameters`, from its `serialize()`.',
|
|
431
|
+
networkId: () => 'Refusing to compose a transaction against an empty network id. The ledger would accept it and bake ' +
|
|
432
|
+
'it into the transaction, which the network then rejects at submission. Resolve the network id for ' +
|
|
433
|
+
'the target environment and pass it explicitly.',
|
|
434
|
+
ttl: () => 'Refusing to compose a transaction with an invalid time-to-live. An unparseable Date is recorded by ' +
|
|
435
|
+
'the ledger as the Unix epoch, producing a transaction that has already expired. Pass a valid future ' +
|
|
436
|
+
'instant as `ttl`.',
|
|
437
|
+
signingKey: (version) => `Refusing to use a malformed \`signingKey\` on the ${version} era. The key builds a deployed ` +
|
|
438
|
+
"contract's maintenance authority or signs an update to it, and the runtime reads it as 32 bytes written in hex - so " +
|
|
439
|
+
'pass exactly 64 hexadecimal characters, which is what that era\'s `sampleSigningKey` produces. The ' +
|
|
440
|
+
'runtime itself reports a malformed key as `failed to fill whole buffer` or ' +
|
|
441
|
+
"`Invalid character 'z' at position 0`, naming neither the option nor the era. The key is not " +
|
|
442
|
+
'rendered here: it is a secret, and on the sampled path the only copy that will exist.',
|
|
443
|
+
calls: (version) => `Refusing to compose a ${version} call transaction from this call list: the era can compose exactly ` +
|
|
444
|
+
'one call, and composing only the first would silently drop the rest. A cross-contract call is a ' +
|
|
445
|
+
'ledger-9-only feature a pre-fork contract cannot emit, so this era has no call tree to express — ' +
|
|
446
|
+
'compose each call as its own transaction, or target the era that carries call trees.',
|
|
447
|
+
verifierKeys: (version) => `Refusing to compose a ${version} deploy transaction with no verifier-key map. This era's deploy leg ` +
|
|
448
|
+
"registers the compiled contract's keys onto the initial state itself, and a constructor-built state " +
|
|
449
|
+
'declares every entry point with a blank key — without the map the deploy would carry unregistered ' +
|
|
450
|
+
"entry points and be refused by the ledger's own well-formedness check. Supply keys for exactly the " +
|
|
451
|
+
'circuits the contract declares. An era whose deploy leg accepts the omission still refuses it for a ' +
|
|
452
|
+
'state that declares a blank-keyed entry point, for the same reason.',
|
|
453
|
+
guaranteedZswapOfferBytes: (version) => `Failed to compose a ${version} deploy transaction: the supplied guaranteed Zswap offer bytes could ` +
|
|
454
|
+
`not be read by the ${version} ledger. Read the wrapped cause for what the decoder reported. Pass the ` +
|
|
455
|
+
"bytes that era's own offer serialization produced.",
|
|
456
|
+
newSigningKey: (version) => `Refusing to compose a ${version} maintenance transaction with a malformed \`newSigningKey\`. The key ` +
|
|
457
|
+
'becomes the whole of the replacement maintenance authority, and the runtime reads it as 32 bytes ' +
|
|
458
|
+
"written in hex - so pass exactly 64 hexadecimal characters, which is what that era's " +
|
|
459
|
+
'`sampleSigningKey` produces. The key is not rendered here: it is a secret.',
|
|
460
|
+
zswapOffer: (version) => `Failed to compose a ${version} transaction: the supplied Zswap offer bytes could not be read by ` +
|
|
461
|
+
`the ${version} ledger. Read the wrapped cause for what the decoder reported. Pass the bytes that ` +
|
|
462
|
+
"era's own offer serialization produced."
|
|
463
|
+
};
|
|
464
|
+
}
|
|
465
|
+
const MAINTENANCE_AUTHORITY_MISMATCH_MESSAGES = {
|
|
466
|
+
'not-first-member': "the signing key's verifying key is not the first member of the contract's maintenance authority " +
|
|
467
|
+
'committee, which is the member the update is signed for, so the ledger would refuse it. The key held ' +
|
|
468
|
+
'for this address is not the one the authority was built from - most often a key another deployment or ' +
|
|
469
|
+
'the other ledger era stored under the same address, or a previous authority replacement whose new key ' +
|
|
470
|
+
'was never stored. Supply the key the contract was deployed with, or the key a previous authority ' +
|
|
471
|
+
'replacement installed.',
|
|
472
|
+
'empty-committee': "the contract's maintenance authority has no committee, so no key can sign an update for it and the " +
|
|
473
|
+
'contract cannot be maintained.',
|
|
474
|
+
'threshold-above-one': "the contract's maintenance authority needs more than one signature, and every update this framework " +
|
|
475
|
+
'composes carries exactly one, so the ledger would refuse it.'
|
|
476
|
+
};
|
|
477
|
+
/**
|
|
478
|
+
* Thrown when a maintenance update cannot be signed so that the ledger accepts
|
|
479
|
+
* it with the key held for the contract — see
|
|
480
|
+
* {@link MaintenanceAuthorityMismatchReason} for the three ways.
|
|
481
|
+
*
|
|
482
|
+
* Raised BEFORE anything is signed or proven: the ledger would accept the
|
|
483
|
+
* signature into the transaction and refuse the update only at submission,
|
|
484
|
+
* after a proof has been paid for.
|
|
485
|
+
*
|
|
486
|
+
* Renders the contract address and no key material: neither the signing key
|
|
487
|
+
* nor any verifying key appears in the message.
|
|
488
|
+
*
|
|
489
|
+
* @param version The ledger era the update was being composed on.
|
|
490
|
+
* @param contractAddress The contract whose authority was checked.
|
|
491
|
+
* @param reason Which check refused it.
|
|
492
|
+
* @see {@link RetainedEraExecution}
|
|
493
|
+
*/
|
|
494
|
+
class MaintenanceAuthorityMismatchError extends MidnightJsError {
|
|
495
|
+
version;
|
|
496
|
+
contractAddress;
|
|
497
|
+
reason;
|
|
498
|
+
code = PROTOCOL_ERROR_CODES.MAINTENANCE_AUTHORITY_MISMATCH;
|
|
499
|
+
category = PROTOCOL_ERROR_CATEGORIES[PROTOCOL_ERROR_CODES.MAINTENANCE_AUTHORITY_MISMATCH];
|
|
500
|
+
constructor(version, contractAddress, reason) {
|
|
501
|
+
super(`Refusing to sign a ${version} maintenance update for the contract at '${contractAddress}': ` +
|
|
502
|
+
MAINTENANCE_AUTHORITY_MISMATCH_MESSAGES[reason]);
|
|
503
|
+
this.version = version;
|
|
504
|
+
this.contractAddress = contractAddress;
|
|
505
|
+
this.reason = reason;
|
|
506
|
+
this.name = 'MaintenanceAuthorityMismatchError';
|
|
507
|
+
}
|
|
508
|
+
}
|
|
509
|
+
/**
|
|
510
|
+
* Thrown when a raw, serialized contract state could not be read by
|
|
511
|
+
* the ledger era it was requested for. Raised by both of the facade's read
|
|
512
|
+
* paths, `extractState` and `decodeContractState`
|
|
513
|
+
* (`lib/shared/contract-state.ts`), so a caller writes one handler for both.
|
|
514
|
+
*
|
|
515
|
+
* Renders no hex and no byte dump of its own.
|
|
516
|
+
*
|
|
517
|
+
* @param version The era whose decoder rejected the bytes.
|
|
518
|
+
* @param cause The decoder's own diagnosis, preserved unchanged. It is what
|
|
519
|
+
* distinguishes a tag mismatch from truncated, trailing or empty input.
|
|
520
|
+
* @see {@link FailClosedDecoding}
|
|
521
|
+
*/
|
|
522
|
+
class StateDecodeFailedError extends MidnightJsError {
|
|
523
|
+
version;
|
|
524
|
+
code = PROTOCOL_ERROR_CODES.STATE_DECODE_FAILED;
|
|
525
|
+
category = PROTOCOL_ERROR_CATEGORIES[PROTOCOL_ERROR_CODES.STATE_DECODE_FAILED];
|
|
526
|
+
constructor(version, cause) {
|
|
527
|
+
super(`Failed to decode a contract state for the ${version} ledger era. Read the wrapped cause for what the ` +
|
|
528
|
+
'decoder reported; it distinguishes a version tag for a different ledger era from truncated, ' +
|
|
529
|
+
'trailing, or empty input bytes. Resolve the era the state was written by — protocolVersionToLedger ' +
|
|
530
|
+
'maps a raw protocolVersion integer onto it — and decode it as that era.', { cause });
|
|
531
|
+
this.version = version;
|
|
532
|
+
this.name = 'StateDecodeFailedError';
|
|
533
|
+
}
|
|
534
|
+
}
|
|
535
|
+
/**
|
|
536
|
+
* Thrown by `decodeContractState` (`lib/shared/contract-state.ts`) when the
|
|
537
|
+
* era's decoder read the bytes but the state it produced is internally
|
|
538
|
+
* inconsistent: it declares an entry point it resolves no operation for, holds
|
|
539
|
+
* a verifier key that will not hash, or resolves no usable balance.
|
|
540
|
+
*
|
|
541
|
+
* Distinct from {@link StateDecodeFailedError}: the bytes were readable by the
|
|
542
|
+
* requested era, so decoding them as the other era cannot help. A caller that
|
|
543
|
+
* retries on `STATE_DECODE_FAILED` must not retry on this one.
|
|
544
|
+
*
|
|
545
|
+
* Renders no hex and no decoded state contents of its own.
|
|
546
|
+
*
|
|
547
|
+
* @param version The era whose decoder produced the state.
|
|
548
|
+
* @param cause The diagnosis of what was inconsistent, preserved unchanged.
|
|
549
|
+
* @see {@link FailClosedDecoding}
|
|
550
|
+
*/
|
|
551
|
+
class StateInconsistentError extends MidnightJsError {
|
|
552
|
+
version;
|
|
553
|
+
code = PROTOCOL_ERROR_CODES.STATE_INCONSISTENT;
|
|
554
|
+
category = PROTOCOL_ERROR_CATEGORIES[PROTOCOL_ERROR_CODES.STATE_INCONSISTENT];
|
|
555
|
+
constructor(version, cause) {
|
|
556
|
+
super(`Decoded a contract state for the ${version} ledger era, but the state is internally inconsistent. ` +
|
|
557
|
+
'Read the wrapped cause for what was inconsistent. The bytes were readable by this era, so decoding ' +
|
|
558
|
+
'them as another era will not fix it; check the decoder the era was loaded with and the source of ' +
|
|
559
|
+
'the state.', { cause });
|
|
560
|
+
this.version = version;
|
|
561
|
+
this.name = 'StateInconsistentError';
|
|
562
|
+
}
|
|
563
|
+
}
|
|
564
|
+
/**
|
|
565
|
+
* Thrown by `extractEncodedStateValue` (`lib/era/envelope.ts`) when the
|
|
566
|
+
* injected pre-fork runtime cannot be used — it was not passed at all, or the
|
|
567
|
+
* binding the decoder needs is absent from it.
|
|
568
|
+
*
|
|
569
|
+
* `downConvertForExecution` and the shared-instance guard used to raise it too;
|
|
570
|
+
* both are gone with the hand-maintained execution layer, so the contract-state
|
|
571
|
+
* decoder is now its only source.
|
|
572
|
+
*
|
|
573
|
+
* Nothing is wrong with the caller's input here. Distinct from
|
|
574
|
+
* {@link Ledger8RuntimeMissingError}, which reports the v8 chunk failing to
|
|
575
|
+
* load at all, and from {@link StateConversionFailedError}, which reports a
|
|
576
|
+
* serialized state that could not be turned into an executable pre-fork
|
|
577
|
+
* state.
|
|
578
|
+
*
|
|
579
|
+
* @param missingMember Which binding was absent. One of this module's own
|
|
580
|
+
* literals, never caller-supplied text, so it is safe to log.
|
|
581
|
+
* @see {@link FailClosedDecoding}
|
|
582
|
+
* @see {@link DualInstantiationGuard}
|
|
583
|
+
*/
|
|
584
|
+
class Ledger8RuntimeInvalidError extends MidnightJsError {
|
|
585
|
+
missingMember;
|
|
586
|
+
code = PROTOCOL_ERROR_CODES.LEDGER8_RUNTIME_INVALID;
|
|
587
|
+
category = PROTOCOL_ERROR_CATEGORIES[PROTOCOL_ERROR_CODES.LEDGER8_RUNTIME_INVALID];
|
|
588
|
+
constructor(missingMember) {
|
|
589
|
+
super('The ledger 8 runtime passed in to decode a ledger 8 contract state cannot be used: the binding it ' +
|
|
590
|
+
'needs is missing. ' +
|
|
591
|
+
'Pass the classes of the onchain-runtime-v3 copy your application already loaded, all of them from that ' +
|
|
592
|
+
'one copy, rather than assembling the runtime object by hand. This package exposes no accessor for it — ' +
|
|
593
|
+
'loadLedger8Protocol() resolves the v8 ledger, a different package whose own same-named classes run on a ' +
|
|
594
|
+
'separate WASM instance. Read `missingMember` on this error for the absent member.');
|
|
595
|
+
this.missingMember = missingMember;
|
|
596
|
+
this.name = 'Ledger8RuntimeInvalidError';
|
|
597
|
+
}
|
|
598
|
+
}
|
|
599
|
+
const describeRequestedVersion = (value) => {
|
|
600
|
+
if (value === undefined || value === null) {
|
|
601
|
+
return undefined;
|
|
602
|
+
}
|
|
603
|
+
return typeof value === 'object' || typeof value === 'function' ? typeof value : String(value);
|
|
604
|
+
};
|
|
605
|
+
/**
|
|
606
|
+
* Thrown when a ledger era was requested by a value that is not a member of
|
|
607
|
+
* `LEDGER_ERAS`. Raised by `loadLedgerEra` (`lib/era/load-era.ts`) and by
|
|
608
|
+
* `extractEncodedStateValue` (`lib/era/envelope.ts`).
|
|
609
|
+
*
|
|
610
|
+
* Two sources: an untyped JavaScript caller passing a value that is not a
|
|
611
|
+
* `LedgerEra`, and a provider returning a value with no era or an unknown
|
|
612
|
+
* one. The second is named by `context`.
|
|
613
|
+
*
|
|
614
|
+
* Carries no `version` field, unlike every other era-aware error here — there
|
|
615
|
+
* is no valid era to name.
|
|
616
|
+
*
|
|
617
|
+
* @param requestedVersion The offending value. Kept as `undefined` when the
|
|
618
|
+
* value carried no era, as the kind (`'object'`, `'function'`) for a value
|
|
619
|
+
* that is not a scalar, and as its string form otherwise. Carried for
|
|
620
|
+
* programmatic use only; it is deliberately kept out of the message.
|
|
621
|
+
* @param context The call that read the era off a value it was handed,
|
|
622
|
+
* for example the provider method that returned a record. Named in the
|
|
623
|
+
* message, so a caller can tell which provider produced the value.
|
|
624
|
+
* @see {@link SharedTableDiscipline}
|
|
625
|
+
* @see {@link FailClosedDecoding}
|
|
626
|
+
*/
|
|
627
|
+
class UnknownLedgerEraError extends MidnightJsError {
|
|
628
|
+
context;
|
|
629
|
+
code = PROTOCOL_ERROR_CODES.UNKNOWN_LEDGER_ERA;
|
|
630
|
+
category = PROTOCOL_ERROR_CATEGORIES[PROTOCOL_ERROR_CODES.UNKNOWN_LEDGER_ERA];
|
|
631
|
+
requestedVersion;
|
|
632
|
+
constructor(requestedVersion, context) {
|
|
633
|
+
super(`${context === undefined ? 'Unknown ledger era requested.' : `${context} returned a value with an unknown ledger era.`} ` +
|
|
634
|
+
'Supported eras are v8 (node 1.x) and ' +
|
|
635
|
+
'v9 (node 2.x); read `requestedVersion` on this error for the value that was passed. ' +
|
|
636
|
+
(context === undefined
|
|
637
|
+
? 'Derive it with protocolVersionToLedger rather than constructing the string by hand. '
|
|
638
|
+
: '') +
|
|
639
|
+
'A `requestedVersion` of `undefined` means the value carried no era, which is the shape of a ' +
|
|
640
|
+
'pre-5.0.0 provider: upgrade that provider.');
|
|
641
|
+
this.context = context;
|
|
642
|
+
this.name = 'UnknownLedgerEraError';
|
|
643
|
+
this.requestedVersion = describeRequestedVersion(requestedVersion);
|
|
644
|
+
}
|
|
645
|
+
}
|
|
646
|
+
/**
|
|
647
|
+
* The opening of the tag every serialized ledger transaction carries, on both
|
|
648
|
+
* eras.
|
|
649
|
+
*
|
|
650
|
+
* Stops before the bracketed version deliberately: a `[vN]` is the wire-schema
|
|
651
|
+
* version of the serialized OBJECT and never a ledger era — the retained era's
|
|
652
|
+
* transactions are tagged `transaction[v9]`.
|
|
653
|
+
*
|
|
654
|
+
* @see packages/contracts/docs/verification-path.md for the same rule stated
|
|
655
|
+
* about verifier-key tags.
|
|
656
|
+
*/
|
|
657
|
+
const TRANSACTION_TAG_PREFIX = 'midnight:transaction[';
|
|
658
|
+
/**
|
|
659
|
+
* The bounds on a constructor name reported by {@link describeType}. It is
|
|
660
|
+
* CALLER DATA — `{ constructor: { name: ... } }` sets it to anything at all —
|
|
661
|
+
* so it is bounded in length and restricted to an identifier alphabet before
|
|
662
|
+
* it can reach an error message and from there a logger provider.
|
|
663
|
+
*/
|
|
664
|
+
const MAX_TYPE_NAME_LENGTH = 32;
|
|
665
|
+
const TYPE_NAME_PATTERN = /^[A-Za-z0-9_$]+$/;
|
|
666
|
+
/**
|
|
667
|
+
* Reads a value's constructor name, or `undefined` where it cannot be read.
|
|
668
|
+
*
|
|
669
|
+
* The read is a property access on caller data, so it can throw: an object may
|
|
670
|
+
* define `constructor` as an accessor that throws, or be an exotic object whose
|
|
671
|
+
* trap does. No operation is being attempted here — only a label chosen for a
|
|
672
|
+
* payload that has ALREADY been refused — so letting the throw propagate would
|
|
673
|
+
* replace the coded refusal with the caller's own error.
|
|
674
|
+
*/
|
|
675
|
+
const readConstructorName = (value) => {
|
|
676
|
+
try {
|
|
677
|
+
return value.constructor?.name;
|
|
678
|
+
}
|
|
679
|
+
catch {
|
|
680
|
+
return undefined;
|
|
681
|
+
}
|
|
682
|
+
};
|
|
683
|
+
/**
|
|
684
|
+
* Names the kind of a value without reproducing any of it verbatim.
|
|
685
|
+
*
|
|
686
|
+
* Validated AFTER truncation, and that order is the point: what is checked has
|
|
687
|
+
* to be exactly what is emitted.
|
|
688
|
+
*/
|
|
689
|
+
const describeType = (value) => {
|
|
690
|
+
if (value === null) {
|
|
691
|
+
return 'null';
|
|
692
|
+
}
|
|
693
|
+
if (typeof value !== 'object') {
|
|
694
|
+
return typeof value;
|
|
695
|
+
}
|
|
696
|
+
const constructorName = readConstructorName(value);
|
|
697
|
+
if (typeof constructorName !== 'string') {
|
|
698
|
+
return 'object';
|
|
699
|
+
}
|
|
700
|
+
const bounded = constructorName.slice(0, MAX_TYPE_NAME_LENGTH);
|
|
701
|
+
return TYPE_NAME_PATTERN.test(bounded) ? bounded : 'object';
|
|
702
|
+
};
|
|
703
|
+
const SANCTIONED_SOURCE_HINT = 'Pass the bytes of a transaction produced by a sanctioned composition function; a contract state, a Zswap ' +
|
|
704
|
+
'offer or a proof preimage is not a transaction.';
|
|
705
|
+
/**
|
|
706
|
+
* Thrown when a payload handed to `deserializeTransactionAtStage` is not a
|
|
707
|
+
* serialized transaction of the requested era and stage.
|
|
708
|
+
*
|
|
709
|
+
* It covers four ways that can happen: a value that is not a byte string, a
|
|
710
|
+
* byte string shorter than the tag prefix, one that does not open with the
|
|
711
|
+
* prefix, and one the era's runtime refuses to read at the requested stage.
|
|
712
|
+
* The first three are refused before any runtime reads the bytes. The last
|
|
713
|
+
* carries the runtime's refusal on `cause`.
|
|
714
|
+
*
|
|
715
|
+
* @remarks Match it with `hasErrorCode` against
|
|
716
|
+
* `PROTOCOL_ERROR_CODES.PAYLOAD_NOT_A_TRANSACTION` rather than constructing it.
|
|
717
|
+
*/
|
|
718
|
+
class PayloadNotATransactionError extends MidnightJsError {
|
|
719
|
+
code = PROTOCOL_ERROR_CODES.PAYLOAD_NOT_A_TRANSACTION;
|
|
720
|
+
category = PROTOCOL_ERROR_CATEGORIES[PROTOCOL_ERROR_CODES.PAYLOAD_NOT_A_TRANSACTION];
|
|
721
|
+
constructor(message, options) {
|
|
722
|
+
super(message, options);
|
|
723
|
+
this.name = 'PayloadNotATransactionError';
|
|
724
|
+
}
|
|
725
|
+
/**
|
|
726
|
+
* The payload was not a `Uint8Array`. Reachable from JavaScript or across an
|
|
727
|
+
* untyped boundary, so it is refused with a code rather than left to become
|
|
728
|
+
* a bare `TypeError`.
|
|
729
|
+
*/
|
|
730
|
+
static notBytes(received) {
|
|
731
|
+
return new PayloadNotATransactionError(`Refusing to read a transaction from a payload that is ${describeType(received)} rather than a Uint8Array. ` +
|
|
732
|
+
SANCTIONED_SOURCE_HINT);
|
|
733
|
+
}
|
|
734
|
+
/** The payload is a byte string, but does not open with a transaction's tag. */
|
|
735
|
+
static wrongTag(byteLength) {
|
|
736
|
+
return new PayloadNotATransactionError(`Refusing to read a ${byteLength}-byte payload that does not begin with the ` +
|
|
737
|
+
`'${TRANSACTION_TAG_PREFIX}' tag of a serialized ledger transaction. ${SANCTIONED_SOURCE_HINT}`);
|
|
738
|
+
}
|
|
739
|
+
/** The era's runtime refused to read the payload at the requested stage; its refusal is on `cause`. */
|
|
740
|
+
static undecodable(version, stage, byteLength, cause) {
|
|
741
|
+
return new PayloadNotATransactionError(`Refusing a ${byteLength}-byte payload that the ledger ${version} runtime cannot read as a ${stage} ` +
|
|
742
|
+
`transaction. Check that the bytes were written by the ledger ${version} runtime and serialized at the ` +
|
|
743
|
+
`${stage} stage. Read the wrapped cause for the runtime refusal.`, { cause });
|
|
744
|
+
}
|
|
745
|
+
}
|
|
746
|
+
const MAX_CAUSE_DEPTH = 8;
|
|
747
|
+
const CATEGORY_VALUES = new Set(Object.values(MIDNIGHT_JS_ERROR_CATEGORIES));
|
|
748
|
+
const isCodedMidnightJsError = (value) => value instanceof Error &&
|
|
749
|
+
'code' in value &&
|
|
750
|
+
typeof value.code === 'string' &&
|
|
751
|
+
value.code.startsWith('MIDNIGHT_JS_') &&
|
|
752
|
+
'category' in value &&
|
|
753
|
+
typeof value.category === 'string' &&
|
|
754
|
+
CATEGORY_VALUES.has(value.category);
|
|
755
|
+
/**
|
|
756
|
+
* The midnight-js error a failure is or carries: the failure itself when it is one, otherwise the first
|
|
757
|
+
* one on its `cause` chain, at most eight links down. Use it when a dependency wraps a midnight-js error
|
|
758
|
+
* and hides its `code` and `category`.
|
|
759
|
+
*/
|
|
760
|
+
const findCodedCause = (failure) => {
|
|
761
|
+
const seen = new Set();
|
|
762
|
+
let current = failure;
|
|
763
|
+
for (let depth = 0; depth <= MAX_CAUSE_DEPTH; depth++) {
|
|
764
|
+
if (isCodedMidnightJsError(current)) {
|
|
765
|
+
return current;
|
|
766
|
+
}
|
|
767
|
+
if (typeof current !== 'object' || current === null || seen.has(current) || !('cause' in current)) {
|
|
768
|
+
return undefined;
|
|
769
|
+
}
|
|
770
|
+
seen.add(current);
|
|
771
|
+
current = current.cause;
|
|
772
|
+
}
|
|
773
|
+
return undefined;
|
|
774
|
+
};
|
|
775
|
+
/**
|
|
776
|
+
* What a retained-era circuit or constructor execution fails with. A Compact `assert` refusal is the usual
|
|
777
|
+
* cause, but a key or config read failure or a runtime fault can also arrive this way, so `cause` is the
|
|
778
|
+
* source of truth. A failure that is, or carries on its `cause` chain, a midnight-js coded error is not
|
|
779
|
+
* wrapped in this class: that coded error surfaces directly.
|
|
780
|
+
*/
|
|
781
|
+
class ContractExecutionError extends MidnightJsError {
|
|
782
|
+
code = PROTOCOL_ERROR_CODES.CONTRACT_EXECUTION_FAILED;
|
|
783
|
+
category = PROTOCOL_ERROR_CATEGORIES[PROTOCOL_ERROR_CODES.CONTRACT_EXECUTION_FAILED];
|
|
784
|
+
/**
|
|
785
|
+
* Every failure the execution reported, as the original objects, in the order they arrived. Filled by
|
|
786
|
+
* {@link ContractExecutionError.fromFailures}; empty when the error was built without a list.
|
|
787
|
+
*/
|
|
788
|
+
errors;
|
|
789
|
+
constructor(message, options) {
|
|
790
|
+
super(message, options);
|
|
791
|
+
this.name = 'ContractExecutionError';
|
|
792
|
+
this.errors = options?.errors ?? [];
|
|
793
|
+
}
|
|
794
|
+
/**
|
|
795
|
+
* Reports every failure of an execution, each with its whole cause chain, separated by `; `.
|
|
796
|
+
* `cause` is the first coded error found on any failure's chain, or the first failure when none is coded.
|
|
797
|
+
* `errors` holds every failure as the original object, so no stack is lost.
|
|
798
|
+
*/
|
|
799
|
+
static fromFailures(failures) {
|
|
800
|
+
const describe = (failure) => {
|
|
801
|
+
const chain = causeChain(failure);
|
|
802
|
+
return chain.length > 0 ? chain.join(': ') : String(failure);
|
|
803
|
+
};
|
|
804
|
+
const coded = failures.map(findCodedCause).find((candidate) => candidate !== undefined);
|
|
805
|
+
return new ContractExecutionError(failures.map(describe).join('; '), { cause: coded ?? failures[0], errors: failures });
|
|
806
|
+
}
|
|
807
|
+
}
|
|
808
|
+
|
|
809
|
+
export { COMMON_ERROR_CATEGORIES, COMMON_ERROR_CODES, ComposeFailedError, ComposeOptionError, ConfigurationError, ContractExecutionError, EnvironmentUnsupportedError, InvalidArgumentError, InvariantViolationError, Ledger8RuntimeInvalidError, Ledger8RuntimeMissingError, MIDNIGHT_JS_ERROR_CATEGORIES, MaintenanceAuthorityMismatchError, MidnightJsError, NO_CIRCUIT, PROTOCOL_ERROR_CATEGORIES, PROTOCOL_ERROR_CODES, PayloadNotATransactionError, StateConversionFailedError, StateDecodeFailedError, StateInconsistentError, TRANSACTION_TAG_PREFIX, UnknownLedgerEraError, UnknownProtocolVersionError, findCodedCause };
|
|
810
|
+
//# sourceMappingURL=errors.js.map
|