@midnightntwrk/midnight-js-protocol 0.0.0-stage → 5.0.2-0-pre.91ad9659
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 +123 -3
package/README.md
CHANGED
|
@@ -1,3 +1,292 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Protocol
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Era-named re-exports of the Midnight protocol packages (`./v8`, `./v9`, `./v9/*`). A subpath always serves the same ledger; a new ledger adds a new `./vN` family next to the old one.
|
|
4
|
+
|
|
5
|
+
## Versioning Contract
|
|
6
|
+
|
|
7
|
+
**This package must never include a protocol version number in its name.** The package name `@midnightntwrk/midnight-js-protocol` is permanent. If the package were renamed to `midnight-js-protocol-v2` or similar, every consumer import would need updating, defeating the purpose of this abstraction.
|
|
8
|
+
|
|
9
|
+
Protocol version changes are handled through:
|
|
10
|
+
- **semver** (npm package version): major bump when underlying protocol packages change in a breaking way
|
|
11
|
+
- **era-named subpaths**: a new ledger gets its own `./vN` subpaths; an existing subpath never changes the ledger it serves
|
|
12
|
+
|
|
13
|
+
## Installation
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
yarn add @midnightntwrk/midnight-js-protocol
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Usage
|
|
20
|
+
|
|
21
|
+
Import ledger 9 through the era-named subpaths:
|
|
22
|
+
|
|
23
|
+
```typescript
|
|
24
|
+
import { type ContractAddress, CostModel } from '@midnightntwrk/midnight-js-protocol/v9';
|
|
25
|
+
import { ContractState } from '@midnightntwrk/midnight-js-protocol/v9/compact-runtime';
|
|
26
|
+
import { CompiledContract } from '@midnightntwrk/midnight-js-protocol/v9/compact-js';
|
|
27
|
+
import { entryPointHash } from '@midnightntwrk/midnight-js-protocol/v9/onchain-runtime';
|
|
28
|
+
import { Configuration } from '@midnightntwrk/midnight-js-protocol/platform-js';
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
An era-named subpath always means the same ledger. At the next fork, a new
|
|
32
|
+
`./v10` family is added next to it, and `./v9` keeps meaning ledger 9.
|
|
33
|
+
|
|
34
|
+
5.0.0 removed the unnamed subpaths (`./ledger`, `./compact-runtime`,
|
|
35
|
+
`./compact-js`, `./compact-js/effect`, `./compact-js/effect/Contract`,
|
|
36
|
+
`./onchain-runtime`) and the root namespaces (`ledger`, `compactRuntime`,
|
|
37
|
+
`compactJs`, `onchainRuntime`). Import the `./v9` counterpart instead.
|
|
38
|
+
|
|
39
|
+
## Sub-path Exports
|
|
40
|
+
|
|
41
|
+
| Sub-path | Re-exports | Description |
|
|
42
|
+
| -------- | ---------- | ----------- |
|
|
43
|
+
| `./errors` | (own) | `PROTOCOL_ERROR_CODES` and every error class and error type this package raises — without pulling in the root barrel. `protocol-acl.test.ts` pins the exact list |
|
|
44
|
+
| `./version` | (own) | `LEDGER_ERAS`, `protocolVersionToLedger`, `versionOfRecord`, `latestNetworkLedgerVersion` and the types `LedgerEra`, `ProtocolVersionSource`, `VersionedRecord` — same lightweight guarantee as `./errors` |
|
|
45
|
+
| `./v9` | `@midnightntwrk/ledger-v9` | Ledger 9 types and transaction primitives |
|
|
46
|
+
| `./v8` | `@midnightntwrk/ledger-v8` | Ledger 8 — do not import at runtime; use `loadLedger8Protocol()` |
|
|
47
|
+
| `./v8/engine` | (own) | Retained pre-fork execution engine — do not import at runtime; use `loadLedger8Engine()` |
|
|
48
|
+
| `./v9/compact-runtime` | `@midnight-ntwrk/compact-runtime` | Compact contract runtime utilities for ledger 9 |
|
|
49
|
+
| `./v9/compact-js` | `@midnight-ntwrk/compact-js` | Compact JS bindings for ledger 9 |
|
|
50
|
+
| `./v9/compact-js/effect` | `@midnight-ntwrk/compact-js/effect` | Effect-based Compact bindings for ledger 9 |
|
|
51
|
+
| `./v9/compact-js/effect/Contract` | `@midnight-ntwrk/compact-js/effect/Contract` | Effect-based Contract module for ledger 9 |
|
|
52
|
+
| `./compact-js/v8/effect` | `@midnight-ntwrk/compact-js/v8/effect` | Effect-based Compact bindings for ledger 8 |
|
|
53
|
+
| `./v9/onchain-runtime` | `@midnightntwrk/onchain-runtime-v4` | On-chain runtime (Impact VM) for ledger 9 |
|
|
54
|
+
| `./platform-js` | `@midnight-ntwrk/platform-js` | Platform services |
|
|
55
|
+
| `./platform-js/effect/Configuration` | `@midnight-ntwrk/platform-js/effect/Configuration` | Effect-based configuration |
|
|
56
|
+
| `./platform-js/effect/ContractAddress` | `@midnight-ntwrk/platform-js/effect/ContractAddress` | Effect-based contract address resolution |
|
|
57
|
+
|
|
58
|
+
## Source Layout
|
|
59
|
+
|
|
60
|
+
Nothing under `src/lib/` is a build entry, so this layout is internal and no consumer import path depends on it. Its job is to make one question answerable from a path alone: *which ledger does this touch?*
|
|
61
|
+
|
|
62
|
+
| Directory | Holds | Ledger reference |
|
|
63
|
+
|---|---|---|
|
|
64
|
+
| `lib/v8/` | the retained pre-fork era: `load.ts`, `engine.ts`, `load-engine.ts`, `executable.ts`, `compose.ts`, `deploy.ts`, `prove.ts`, `adapt.ts` | acquires `ledger-v8`, `onchain-runtime-v3` and the 0.16 glue, always through a dynamic import |
|
|
65
|
+
| `lib/v9/` | the current era's composition code: `compose.ts`, `wrap.ts` | links `ledger-v9` statically |
|
|
66
|
+
| `lib/shared/` | what both eras run: `ledger-version.ts`, `verifier-keys.ts`, `compose-options.ts`, `assemble-call.ts`, `compose-types.ts`, `unshielded.ts`, `contract-state.ts` | era passed in as a `LedgerEra` parameter, never chosen here |
|
|
67
|
+
| `lib/era/` | the facade and the dispatch: `load-era.ts`, `era.ts`, `envelope.ts` | reaches both, which is the point of the layer |
|
|
68
|
+
|
|
69
|
+
The directory names say what a module is **about**, not what it links. Three consequences a reader should not have to derive:
|
|
70
|
+
|
|
71
|
+
- **`lib/v8/compose.ts`, `deploy.ts` and `adapt.ts` link no v8 at all.** They take the acquired module as a `Ledger8Protocol` parameter, which is a type. That injection is what keeps the v8 WASM out of the eager graph, and the guarantee is enforced by `dist-laziness.test.ts` and `v8-surface.test.ts` — not by this layout. Read the tests, not the directory, for the bundle boundary.
|
|
72
|
+
- **`lib/shared/` is not free of vendors.** `assemble-call.ts` links `@midnight-ntwrk/compact-js`, a post-fork package, for `hashVerifierKey` and `encodeContractKeyLocation`; `contract-state.ts` links it for `hashVerifierKey`. Both are called by both eras, so their subject is shared even though their linkage is not. This is safe in one direction only: v9 is the eagerly-linked baseline, so a shared module reaching for it never wakes v8, while the reverse would.
|
|
73
|
+
- **`lib/v9/wrap.ts` type-imports `lib/v8/executable.ts`.** `TranscriptPojo` is the v8 engine's output and `wrapKeepStateCall` binds it onto v9. The cross-era edge is the operation's whole purpose, and it is type-only.
|
|
74
|
+
|
|
75
|
+
`compose-types.ts` and `era.ts` name their shared types through `@midnightntwrk/ledger-v9` because some vendor has to name them. `EncodedStateValue`, `Op`, `AlignedValue`, `Transcript`, `CallContext` and `Effects` are pinned identical across `onchain-runtime-v3`, `ledger-v8` and `ledger-v9` by the compile-time assertions at the bottom of `v8-executable.test.ts`; the import names one era, the type belongs to neither. Those assertions are evaluated by `yarn typecheck:tests` — run by the pre-push hook AND by CI's `typecheck:tests:core` job. The test run itself does not evaluate them, because vitest transpiles test files without type-checking.
|
|
76
|
+
|
|
77
|
+
## Architecture Documents
|
|
78
|
+
|
|
79
|
+
The reasoning behind this package's shape lives in `docs/`, not in the source
|
|
80
|
+
docstrings. Each file is registered with TypeDoc through `projectDocuments`, so
|
|
81
|
+
it is a page in the generated API reference and `@see {@link Title}` in a
|
|
82
|
+
docstring resolves to it.
|
|
83
|
+
|
|
84
|
+
| Document | What it explains |
|
|
85
|
+
|---|---|
|
|
86
|
+
| [Era boundary](./docs/era-boundary.md) | Why only bytes and plain objects cross between the eras, how the eight operations are split between `LedgerEraFacade` and `Ledger8Engine`, and the memoisation rules |
|
|
87
|
+
| [Retained-era execution](./docs/retained-era-execution.md) | The state a circuit runs against, why the Merkle walk was removed, the era pin, and what a `TranscriptPojo` carries |
|
|
88
|
+
| [Dual-instantiation guard](./docs/dual-instantiation-guard.md) | What a duplicate WASM install does in the argument position versus the receiver position, and why the guard is a correctness requirement rather than a diagnostic |
|
|
89
|
+
| [Fail-closed decoding](./docs/fail-closed-decoding.md) | Why the version tag is the only authority over the bytes, and the division of labour between the three decode failures |
|
|
90
|
+
| [Compose refusal order](./docs/compose-refusal-order.md) | The order in which both era paths refuse compose options, and the one deliberate difference between them |
|
|
91
|
+
| [Verifier keys](./docs/verifier-keys.md) | Registration rules, the refusals that stop a deploy landing at an address the caller's artifacts do not describe, and why the address cannot be recomputed |
|
|
92
|
+
| [Module graph and lazy loading](./docs/module-graph-and-lazy-loading.md) | Build entries, the `./v8` and `./v8/engine` chunks, the import cycle avoided by a leaf module, and why a vendor's types are named with `import type` |
|
|
93
|
+
| [Injected vendor slices](./docs/injected-vendor-slices.md) | How a function names the vendor class it takes by injection — derived from the vendor's own class, declared structurally, or narrowed — and what each choice buys |
|
|
94
|
+
| [Cross-era operation registry](./docs/cross-era-operation-registry.md) | What actually crosses the fork boundary when a contract served with its retained-era version tag is called, why re-expressing its operations is faithful rather than a substitution, and why the primary state is left at its default |
|
|
95
|
+
| [Shared table discipline](./docs/shared-table-discipline.md) | Why the shared tables are frozen and null-prototyped, and why exhaustiveness is enforced at compile time as well as at run time |
|
|
96
|
+
|
|
97
|
+
Docstrings in `src/` carry the API contract: what a symbol does, its
|
|
98
|
+
parameters, what it returns and what it throws. Anything that answers "why is
|
|
99
|
+
it built this way" belongs in a document above, stated once.
|
|
100
|
+
|
|
101
|
+
## Accessing the v8 Ledger Era
|
|
102
|
+
|
|
103
|
+
The `./v8` subpath re-exports the previous-era ledger (`@midnightntwrk/ledger-v8`), which carries its own WASM. To keep that WASM out of eagerly-loaded module graphs, runtime imports of `@midnightntwrk/midnight-js-protocol/v8` are blocked by ESLint everywhere outside this package. Use the lazy accessor instead:
|
|
104
|
+
|
|
105
|
+
```typescript
|
|
106
|
+
import { loadLedger8Protocol } from '@midnightntwrk/midnight-js-protocol';
|
|
107
|
+
|
|
108
|
+
const v8 = await loadLedger8Protocol();
|
|
109
|
+
const transaction = v8.Transaction.deserialize(rawTransaction);
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Type-only imports of the subpath are allowed:
|
|
113
|
+
|
|
114
|
+
```typescript
|
|
115
|
+
import type { Transaction } from '@midnightntwrk/midnight-js-protocol/v8';
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
If the v8 module cannot be loaded (usually a broken or partial install), `loadLedger8Protocol()` rejects with `Ledger8RuntimeMissingError` (code `MIDNIGHT_JS_P_LEDGER8_RUNTIME_MISSING`) carrying the original error as `cause`. Its `subpath` field is `'/v8'`, naming which chunk failed. The failed load is not memoised — the next call retries.
|
|
119
|
+
|
|
120
|
+
## Running Contracts on the Retained Pre-Fork Engine
|
|
121
|
+
|
|
122
|
+
Contracts compiled against the pre-fork toolchain keep executing on `compact-runtime@0.16` after the fork. That toolchain and its `onchain-runtime-v3` WASM live behind the `./v8/engine` subpath, gated the same way as `./v8` and for the same reason. `loadLedger8Engine()` is the only sanctioned runtime path to it:
|
|
123
|
+
|
|
124
|
+
```typescript
|
|
125
|
+
import { loadLedger8Engine, loadLedgerEra, versionOfRecord } from '@midnightntwrk/midnight-js-protocol';
|
|
126
|
+
|
|
127
|
+
const engine = await loadLedger8Engine();
|
|
128
|
+
const era = await loadLedgerEra(versionOfRecord(indexerRecord));
|
|
129
|
+
|
|
130
|
+
// The DECODED state, not the extracted one: the balances a circuit reads are
|
|
131
|
+
// not part of the primary state, and this value carries them alongside it.
|
|
132
|
+
// One read in, one value out -- there is no second argument that could
|
|
133
|
+
// describe a different block.
|
|
134
|
+
const contractState = era.decodeContractState(rawContractState);
|
|
135
|
+
const transcript = await engine.executeCircuit({
|
|
136
|
+
contract,
|
|
137
|
+
circuitId: 'increment',
|
|
138
|
+
args: [],
|
|
139
|
+
contractState,
|
|
140
|
+
address: contractAddress,
|
|
141
|
+
coinPk: coinPublicKey,
|
|
142
|
+
privateState
|
|
143
|
+
});
|
|
144
|
+
const prototype = engine.wrapKeepStateCall({ transcript, contractAddress, contractState: migratedLedger9ContractState });
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
`executeCircuit` and `executeConstructor` are **asynchronous** — `await` them. There is no separate state conversion step: pass the decoded contract state straight in, and the engine builds the state the retained runtime executes against.
|
|
148
|
+
|
|
149
|
+
Read it with the era the state's own version tag names, not with a fixed one. A contract an earlier post-fork call has MIGRATED carries a current-era version tag while its artifacts stay the retained toolchain's, so `era` above is the network's current era for that contract and the retained era for one that has not migrated. Handing the retained reader state with a current-era version tag is refused on the tag.
|
|
150
|
+
|
|
151
|
+
`contractState` must carry a usable `balance`. It is required rather than defaulted, because an empty balance is a legitimate value — a contract holding nothing has one — and defaulting would make "holds nothing" indistinguishable from "the caller forgot", which is a circuit reading zero where the chain says otherwise. `decodeContractState` produces both halves for you; assembling the value by hand is what the refusal is there for.
|
|
152
|
+
|
|
153
|
+
The engine exposes `executeCircuit`, `executeConstructor` and `wrapKeepStateCall`, and they form a pipeline, each result being the next call's input. Reading a contract state and composing a call or a deploy are **not** here: both eras do those, so they live on the [ledger-era facade](#ledger-era-facade) instead.
|
|
154
|
+
|
|
155
|
+
`migratedLedger9ContractState` passed to `wrapKeepStateCall` must be the migrated v9 state **as read from chain**, which is not `rawContractState` above: it is where the deployed operation and its verifier key come from, and the key location the prototype carries is derived from that key. A blank or constructor-built state throws `ComposeFailedError` (code `MIDNIGHT_JS_P_COMPOSE_FAILED`) with `stage` naming which lookup failed and `version` naming the ledger era it was composing for.
|
|
156
|
+
|
|
157
|
+
Circuits with Zswap coin effects run on this leg like any other. The transcript carries `zswapLocalState` — the post-call Zswap local state, decoded into the runtime's public shape — which is what you turn into the transaction's segmented Zswap offer (`zswapStateToSegmentedOffer` in `@midnightntwrk/midnight-js-contracts`). You do not hand that offer to `composeCallTx` as ready-made bytes: you hand it a `zswapOffer` factory, which the composer calls back with each call's guaranteed/fallible split once it has drawn it. That split is the fourth argument `zswapStateToSegmentedOffer` routes by — without it every movement lands in the guaranteed segment, and a circuit whose transcript is wholly fallible produces an offer the wallet cannot balance. Omitting the factory altogether leaves you composing a transaction missing the coin movements the circuit recorded.
|
|
158
|
+
|
|
159
|
+
The transcript also carries `partitionContext` — the block, the starting effects and the commitment indices the pre-fork query context recorded while the circuit ran. Pass it on unchanged: a transcript composed without it is partitioned against a context the circuit never ran on, and a circuit that RECEIVED a coin in-contract cannot be partitioned at all, because the index its commitment was registered at lives only in that context. `wrapKeepStateCall` carries it for you; a hand-built call entry has to supply it. A context the target era cannot read throws `ComposeFailedError` with `stage: 'call-partition-context'`.
|
|
160
|
+
|
|
161
|
+
A failure to load the chunk itself rejects with `Ledger8RuntimeMissingError` whose `subpath` is `'/v8/engine'`; read `cause` for which module actually failed to resolve.
|
|
162
|
+
|
|
163
|
+
## Ledger-Era Facade
|
|
164
|
+
|
|
165
|
+
Two ledger eras are live at once: `v8` backs the node 1.x line and `v9` the 2.x line. `loadLedgerEra` hands you one of them as a single object with the same methods on both, so code that has resolved which era a record belongs to does not then have to branch on it.
|
|
166
|
+
|
|
167
|
+
```typescript
|
|
168
|
+
import { loadLedgerEra, versionOfRecord } from '@midnightntwrk/midnight-js-protocol';
|
|
169
|
+
|
|
170
|
+
const era = await loadLedgerEra(versionOfRecord(indexerRecord));
|
|
171
|
+
|
|
172
|
+
const state = era.extractState(rawContractState);
|
|
173
|
+
const decoded = era.decodeContractState(rawContractState);
|
|
174
|
+
const { txBytes, partitions } = era.composeCallTx({
|
|
175
|
+
calls,
|
|
176
|
+
networkId,
|
|
177
|
+
ttl,
|
|
178
|
+
// Called back ONCE, with one `[guaranteed, fallible]` split per call, in
|
|
179
|
+
// `calls` order -- cross-contract callees first, the root call last. Route
|
|
180
|
+
// against all of them: a transaction carries one offer per segment, so
|
|
181
|
+
// destructuring the first pair alone would route the whole transaction
|
|
182
|
+
// against a callee's split and drop the root call's.
|
|
183
|
+
// Answers with `{ guaranteedBytes, fallibleBytes }`.
|
|
184
|
+
zswapOffer: (partitions) => buildSegmentedOfferBytes(partitions)
|
|
185
|
+
});
|
|
186
|
+
const deploy = era.composeDeployTx({ contractStateBytes, verifierKeys, networkId, ttl });
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
| Method | What it does |
|
|
190
|
+
| ------ | ------------ |
|
|
191
|
+
| `version` | The era this object is bound to — the value that was passed in |
|
|
192
|
+
| `extractState` | Reads the primary state out of raw contract-state bytes |
|
|
193
|
+
| `decodeContractState` | Reads contract-state bytes into its state plus the entry points it declares, each with its verifier key and that key's hash |
|
|
194
|
+
| `composeCallTx` | Composes an UNPROVEN call transaction and answers with its bytes plus each call's guaranteed/fallible split |
|
|
195
|
+
| `composeDeployTx` | Composes an UNPROVEN deploy and returns it with the address it will have and the initial state that address came from |
|
|
196
|
+
|
|
197
|
+
Derive the era with `versionOfRecord` or `latestNetworkLedgerVersion` (see [Version Module](#version-module)) rather than writing the string by hand. An era string that is not `'v8'` or `'v9'` rejects with `UnknownLedgerEraError`; the offending value is on the error's `requestedVersion` field, not in its message.
|
|
198
|
+
|
|
199
|
+
Each era is memoised, so the retained pre-fork WASM is instantiated at most once per process. Asking for `'v8'` is what acquires it — a consumer that only ever asks for `'v9'` never loads it at all, which is gated by `dist-laziness.test.ts`. A **failed** v8 acquisition is not memoised: the rejection propagates unchanged as `Ledger8RuntimeMissingError` and the next call retries.
|
|
200
|
+
|
|
201
|
+
### Only bytes and plain objects cross this boundary
|
|
202
|
+
|
|
203
|
+
Every value going in or coming out is plain data — `Uint8Array`s and plain objects — never a live WASM handle. A contract state goes in as the bytes it was serialized to and comes back as an `EncodedStateValue` plus plain entry-point records; a composed transaction comes back as bytes. So a result can be stored, compared across eras, or sent through a `structuredClone` or a worker boundary without the module that produced it. `era-parity.test.ts` asserts exactly that, on every method, for both eras.
|
|
204
|
+
|
|
205
|
+
Because the methods are synchronous, all the awaiting happens once, at `loadLedgerEra`.
|
|
206
|
+
|
|
207
|
+
### Where the two eras differ
|
|
208
|
+
|
|
209
|
+
The same method names mostly mean the same capabilities. One thing the v8 era refuses that the v9 era accepts:
|
|
210
|
+
|
|
211
|
+
- **A call tree.** The v8 era composes exactly one call. A cross-contract call is a ledger-9-only feature a pre-fork contract cannot emit, so that era has no call tree to express: a `calls` list longer than one throws `ComposeOptionError` with `option: 'calls'` rather than composing the first entry and dropping the rest.
|
|
212
|
+
|
|
213
|
+
**A Zswap offer is not one of them.** Both eras call the `zswapOffer` factory back with the split they resolved and carry the offer it answers with into the transaction; both throw `ComposeOptionError` with `option: 'zswapOffer'` for bytes their own decoder rejects (`option: 'guaranteedZswapOfferBytes'` for the offer a deploy is given), with the decoder's failure on `cause`. Both read that offer LAST, after the call's unshielded payout has been aggregated, so a call with two faults is refused the same way on either era. A coin-moving call composes on either era.
|
|
214
|
+
|
|
215
|
+
The v8 era also *requires* `verifierKeys` on `composeDeployTx`, where the v9 era accepts its omission in one case. The retained deploy leg registers the compiled contract's keys onto the initial state itself, so it always needs the map; omitting it throws `ComposeOptionError` with `option: 'verifierKeys'`. The v9 era allows the omission only for a state that ALREADY carries its keys, and checks rather than assumes it: a state still declaring a blank-keyed entry point throws the same `ComposeOptionError` with the same `option`. So the two eras agree on every input except one — a pre-keyed state, which deploys as-is on v9 and needs its keys supplied again on v8.
|
|
216
|
+
|
|
217
|
+
What is *not* asymmetric: a call's user-addressed unshielded payouts are aggregated onto the transaction's guaranteed and fallible offers on **both** eras. Attaching them on one era only would leave the other composing an unbalanced transaction the node rejects on submission, with nothing having reported a problem at composition time — so `era-parity.test.ts` asserts the payout each segment carries, per era.
|
|
218
|
+
|
|
219
|
+
### Errors
|
|
220
|
+
|
|
221
|
+
| Error | Code | Raised when |
|
|
222
|
+
| ----- | ---- | ----------- |
|
|
223
|
+
| `StateDecodeFailedError` | `MIDNIGHT_JS_P_STATE_DECODE_FAILED` | Contract-state bytes could not be read by the era it was requested for — most often a state written by the other era |
|
|
224
|
+
| `StateInconsistentError` | `MIDNIGHT_JS_P_STATE_INCONSISTENT` | Contract-state bytes were read, but the state is internally inconsistent: an entry point it cannot resolve, a verifier key that will not hash, or no usable balance. Retrying with the other era will not fix it |
|
|
225
|
+
| `ComposeFailedError` | `MIDNIGHT_JS_P_COMPOSE_FAILED` | Something about a CALL or a DEPLOY could not be composed: an operation that is missing, unkeyed, or names a circuit the contract does not declare; an empty call list; a pre-call state or a recorded query context the era cannot bridge; a supplied transcript with neither half; a public transcript or a set of call inputs the ledger itself rejected; or a claimed payout the transaction cannot settle (dust, or a shielded token type). `stage` is a closed union naming which of those it was — see its own docs for the full list; `version` names the era |
|
|
226
|
+
| `ComposeOptionError` | `MIDNIGHT_JS_P_COMPOSE_OPTION_INVALID` | A transaction-wide OPTION cannot be used at all — an empty network id, an invalid ttl, a contract state whose version tag the era rejected, an offer the era's decoder rejected, a missing verifier-key map, or a call list longer than the era can compose. `option` names the field, `version` names the era |
|
|
227
|
+
| `UnknownLedgerEraError` | `MIDNIGHT_JS_P_UNKNOWN_LEDGER_ERA` | The requested era is not `'v8'` or `'v9'`, or the value carries no era (`requestedVersion` is `undefined`: a pre-5.0.0 provider) |
|
|
228
|
+
|
|
229
|
+
Each names the era it was raised for — `version` on the first four, `requestedVersion` on `UnknownLedgerEraError`, which also takes no `cause`. None renders hex or a byte dump of its own, and the first four preserve the underlying runtime failure on `cause` where there was one.
|
|
230
|
+
|
|
231
|
+
### Planned follow-ups
|
|
232
|
+
|
|
233
|
+
Recorded here so the reasoning is not lost, and deliberately NOT done in the change that introduced this facade:
|
|
234
|
+
|
|
235
|
+
- **Collapse the version dispatch in `lib/era/envelope.ts`.** `extractEncodedStateValue` has one production caller, which passes the literal `'v8'`; the v9 path calls `extractLedger9EncodedStateValue` directly. The decoder table, the unknown-version guard and the null-prototype defence are therefore only reachable from tests, and the per-file 100% floor keeps the tests that reach them alive. Collapsing it to a `extractLedger8EncodedStateValue` beside the v9 one deletes real tests, which belongs in its own change.
|
|
236
|
+
- **Give `ComposeOptionError` a `circuitId`.** The v9 blank-key refusal knows which entry point was blank and cannot say so, because the field does not exist. Adding it would let that refusal name the slot without breaking the class parity the two eras currently have.
|
|
237
|
+
|
|
238
|
+
## Version Module
|
|
239
|
+
|
|
240
|
+
Mapping a raw `protocolVersion` integer onto the ledger runtime it corresponds to. Reachable from the root barrel and, without loading the ledger/compact-js/onchain-runtime/platform namespaces, from the `./version` subpath. The error it throws is reachable from `./errors` on the same terms.
|
|
241
|
+
|
|
242
|
+
The `protocolVersion` integer encodes the **node** version as `major * 1_000_000 + minor * 1_000 + patch`, so a whole node major occupies a 1_000_000-wide range:
|
|
243
|
+
|
|
244
|
+
| protocolVersion range | node version | ledger |
|
|
245
|
+
| --------------------- | ------------ | ------ |
|
|
246
|
+
| 1_000_000 – 1_999_999 | 1.x | v8 |
|
|
247
|
+
| 2_000_000 – 2_999_999 | 2.x | v9 |
|
|
248
|
+
|
|
249
|
+
Anything outside those ranges throws rather than guessing. Node 0.x is deliberately absent: the indexer's own table does map it, but midnight-js meets only node 1.x or 2.x, so a 0.x `protocolVersion` is reported as unknown rather than silently resolved.
|
|
250
|
+
|
|
251
|
+
```typescript
|
|
252
|
+
import {
|
|
253
|
+
LEDGER_ERAS, // readonly ['v8', 'v9']
|
|
254
|
+
protocolVersionToLedger, // (protocolVersion: number, path?: 'read' | 'construct') => 'v8' | 'v9' (path defaults to 'construct')
|
|
255
|
+
versionOfRecord, // (record: { protocolVersion: number }) => 'v8' | 'v9'
|
|
256
|
+
latestNetworkLedgerVersion // (source: { queryLatestProtocolVersion(): Promise<number> }) => Promise<'v8' | 'v9'>
|
|
257
|
+
} from '@midnightntwrk/midnight-js-protocol/version';
|
|
258
|
+
import { UnknownProtocolVersionError } from '@midnightntwrk/midnight-js-protocol/errors';
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
Prefer `versionOfRecord` for a `protocolVersion` already read off an indexer/node record, and `latestNetworkLedgerVersion` for the network's current ledger version — both tag any error with the correct path automatically. `UnknownProtocolVersionError` carries a `reason` of `'malformed'` (the input was not a non-negative integer) or `'unknown'` (a well-formed integer outside every mapped range), so callers can distinguish "bad input" from "genuinely unsupported protocol version".
|
|
262
|
+
|
|
263
|
+
## ESLint Enforcement
|
|
264
|
+
|
|
265
|
+
Three rules in the repo's `eslint.config.mjs` govern how other packages reach protocol internals.
|
|
266
|
+
|
|
267
|
+
**1. The protocol ACL** — a `no-restricted-imports` rule prevents direct imports of the underlying protocol packages outside of this package. If you see an error like:
|
|
268
|
+
|
|
269
|
+
> Import from `@midnightntwrk/midnight-js-protocol/v9` (or `import type` from /v8 for ledger 8) instead.
|
|
270
|
+
|
|
271
|
+
Replace the direct protocol import with the corresponding subpath from this package. For the v8 era specifically, the error
|
|
272
|
+
|
|
273
|
+
> Runtime v8 access only via loadLedger8Protocol() from @midnightntwrk/midnight-js-protocol.
|
|
274
|
+
|
|
275
|
+
means: replace the direct `./v8` runtime import with `loadLedger8Protocol()` (type-only imports stay as they are).
|
|
276
|
+
|
|
277
|
+
**2. The v8 static-import gate** — `@typescript-eslint/no-restricted-imports` blocks runtime imports of `@midnightntwrk/midnight-js-protocol/v8` outside `packages/protocol/src/`. Type-only imports (`import type`) are allowed.
|
|
278
|
+
|
|
279
|
+
**3. The v8 dynamic-import gate** — `no-restricted-syntax` selectors block `import('@midnightntwrk/midnight-js-protocol/v8')` in the same scopes. An interpolated template literal cannot be matched statically and is not covered.
|
|
280
|
+
|
|
281
|
+
Both v8 gates point at `loadLedger8Protocol()`, the accessor on the root barrel — the only sanctioned runtime path to the v8 era.
|
|
282
|
+
|
|
283
|
+
## Resources
|
|
284
|
+
|
|
285
|
+
- [Midnight Network](https://midnight.network)
|
|
286
|
+
- [Developer Hub](https://midnight.network/developer-hub)
|
|
287
|
+
|
|
288
|
+
## Terms & License
|
|
289
|
+
|
|
290
|
+
By using this package, you agree to [Midnight's Terms and Conditions](https://midnight.network/static/terms.pdf) and [Privacy Policy](https://midnight.network/static/privacy-policy.pdf).
|
|
291
|
+
|
|
292
|
+
Licensed under [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0).
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from '@midnight-ntwrk/compact-js/v8/effect';
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"compact-js-v8-effect.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}
|