@midnight-ntwrk/midnight-js-protocol 5.0.0-beta.7 → 5.0.0-beta.8

package/dist/version.d.ts

@@ -0,0 +1,121 @@
+/**
+ * The two ledger runtimes midnight-js can talk to. `v8` backs the node 1.x
+ * line; `v9` backs the 2.x line. This is a closed, exhaustive set — see
+ * `protocolVersionToLedger` (`../version.ts`) for how a raw `protocolVersion`
+ * integer maps onto it.
+ *
+ * @see {@link SharedTableDiscipline} for why the array is frozen.
+ * @see {@link ModuleGraphAndLazyLoading} for why the constant is declared in
+ * this leaf module and re-exported by `../version.ts`.
+ */
+declare const LEDGER_VERSIONS: readonly ["v8", "v9"];
+type LedgerVersion = (typeof LEDGER_VERSIONS)[number];
+/**
+ * The era whose objects this build hands out live, through `./ledger`.
+ *
+ * A protocol fact rather than a consumer's choice: it is decided by which
+ * ledger the package links eagerly, and every other era is reached lazily and
+ * crosses package boundaries as bytes. Declared here so that no package
+ * downstream restates "which era is now" as a literal of its own.
+ *
+ * The type is the single literal, not {@link LedgerVersion}, so a value typed
+ * by it DISCRIMINATES — the same discipline `CurrentPipelineEra` follows in
+ * `midnight-js-contracts`.
+ */
+declare const CURRENT_LEDGER_VERSION: "v9";
+type CurrentLedgerVersion = typeof CURRENT_LEDGER_VERSION;
+/**
+ * Every era this build still speaks but does not run live — the eras that
+ * cross a package boundary as serialized bytes.
+ *
+ * Defined as the complement of {@link CURRENT_LEDGER_VERSION}, so a further
+ * era joins this set by being added to {@link LEDGER_VERSIONS} and nothing
+ * else. The value list below is checked against that complement at build time.
+ */
+type RetainedLedgerVersion = Exclude<LedgerVersion, CurrentLedgerVersion>;
+declare const RETAINED_LEDGER_VERSIONS: readonly ["v8"];
+
+/**
+ * Which call path asked for a ledger version:
+ * - `'read'` — the version was taken off an existing record.
+ * - `'construct'` — the version was chosen to build something new against the
+ *   network's current head.
+ */
+type VersionResolutionPath = 'read' | 'construct';
+
+/**
+ * Anything that can report the network's current head protocol version —
+ * typically an indexer or node client. Consumed by {@link networkHeadVersion}.
+ */
+interface ProtocolVersionSource {
+    /**
+     * @returns The network's current head `protocolVersion` integer.
+     */
+    queryLatestProtocolVersion(): Promise<number>;
+}
+/**
+ * Any record carrying a raw `protocolVersion` integer field, e.g. a
+ * transaction or block already read from the indexer. Consumed by
+ * {@link versionOfRecord}.
+ */
+interface VersionedRecord {
+    readonly protocolVersion: number;
+}
+/**
+ * Maps a raw `protocolVersion` integer (as returned by the indexer or node)
+ * onto the ledger runtime it corresponds to.
+ *
+ * | protocolVersion range | node version | ledger |
+ * | --------------------- | ------------ | ------ |
+ * | 1_000_000 – 1_999_999 | 1.x          | v8     |
+ * | 2_000_000 – 2_999_999 | 2.x          | v9     |
+ *
+ * Most call sites should not call this directly. Prefer
+ * {@link versionOfRecord} for a `protocolVersion` read off an existing
+ * indexer/node record, or {@link networkHeadVersion} for the network's
+ * current head version — both tag the resulting error with the correct
+ * `path` automatically. Pass `path` explicitly here only when neither helper
+ * fits the call site.
+ *
+ * @param protocolVersion The raw integer read from an indexer or node record.
+ * @param path Which resolution path a failure is attributed to. Defaults to
+ * `'construct'`, and decides which of the two error codes a failure carries.
+ * @returns The {@link LedgerVersion} that `protocolVersion`'s node major maps
+ * onto.
+ * @throws {@link UnknownProtocolVersionError} with `reason: 'malformed'` when
+ * `protocolVersion` is not a non-negative integer, and with `reason: 'unknown'`
+ * when it is a well-formed integer outside every range above.
+ * @see {@link SharedTableDiscipline}
+ */
+declare const protocolVersionToLedger: (protocolVersion: number, path?: VersionResolutionPath) => LedgerVersion;
+/**
+ * Resolves the ledger version for a record's `protocolVersion` field (e.g. a
+ * transaction or block already read from the indexer).
+ *
+ * @param record Any object carrying a raw `protocolVersion` integer field.
+ * @returns The {@link LedgerVersion} that record was written under.
+ * @throws {@link UnknownProtocolVersionError} tagged with the `read` path, on
+ * the same two conditions as {@link protocolVersionToLedger}.
+ */
+declare const versionOfRecord: (record: VersionedRecord) => LedgerVersion;
+/**
+ * Queries `source` for the network's current head protocol version and
+ * resolves it to a {@link LedgerVersion}.
+ *
+ * The source is expected to read the network on every call. This is the
+ * construct path: the era being resolved is the one a transaction built now
+ * will land in, and a stale reading is wrong exactly at the fork boundary,
+ * where that question matters. `PublicDataProvider.queryLatestProtocolVersion`
+ * states the same prohibition as a requirement on its implementations; this
+ * parameter is a structural type, so nothing here can enforce it. See ADR 0007.
+ *
+ * @param source The indexer or node client to ask for the head version.
+ * @returns A promise for the {@link LedgerVersion} at the network head.
+ * @throws {@link UnknownProtocolVersionError} tagged with the `construct`
+ * path, on the same two conditions as {@link protocolVersionToLedger}. A
+ * rejection from `source.queryLatestProtocolVersion()` propagates unchanged.
+ */
+declare const networkHeadVersion: (source: ProtocolVersionSource) => Promise<LedgerVersion>;
+
+export { CURRENT_LEDGER_VERSION, LEDGER_VERSIONS, RETAINED_LEDGER_VERSIONS, networkHeadVersion, protocolVersionToLedger, versionOfRecord };
+export type { CurrentLedgerVersion, LedgerVersion, ProtocolVersionSource, RetainedLedgerVersion, VersionedRecord };

package/dist/version.js

@@ -0,0 +1,132 @@
+import { UnknownProtocolVersionError } from './errors.js';
+
+/*
+ * This file is part of midnight-js.
+ * Copyright (C) Midnight Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The two ledger runtimes midnight-js can talk to. `v8` backs the node 1.x
+ * line; `v9` backs the 2.x line. This is a closed, exhaustive set — see
+ * `protocolVersionToLedger` (`../version.ts`) for how a raw `protocolVersion`
+ * integer maps onto it.
+ *
+ * @see {@link SharedTableDiscipline} for why the array is frozen.
+ * @see {@link ModuleGraphAndLazyLoading} for why the constant is declared in
+ * this leaf module and re-exported by `../version.ts`.
+ */
+const LEDGER_VERSIONS = Object.freeze(['v8', 'v9']);
+/**
+ * The era whose objects this build hands out live, through `./ledger`.
+ *
+ * A protocol fact rather than a consumer's choice: it is decided by which
+ * ledger the package links eagerly, and every other era is reached lazily and
+ * crosses package boundaries as bytes. Declared here so that no package
+ * downstream restates "which era is now" as a literal of its own.
+ *
+ * The type is the single literal, not {@link LedgerVersion}, so a value typed
+ * by it DISCRIMINATES — the same discipline `CurrentPipelineEra` follows in
+ * `midnight-js-contracts`.
+ */
+const CURRENT_LEDGER_VERSION = 'v9';
+const RETAINED_LEDGER_VERSIONS = Object.freeze(['v8']);
+
+/*
+ * This file is part of midnight-js.
+ * Copyright (C) Midnight Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+// Deliberately narrower than the indexer's table: do not "restore" the 0.x
+// major to match it without a caller needing it — see SharedTableDiscipline.
+const NODE_MAJOR_TO_LEDGER = {
+    1: 'v8',
+    2: 'v9'
+};
+// A typed function rather than a direct index, because a `number`-typed key
+// cannot index the `as const` table — see SharedTableDiscipline.
+const lookupLedger = (table, key) => table[key];
+/**
+ * Maps a raw `protocolVersion` integer (as returned by the indexer or node)
+ * onto the ledger runtime it corresponds to.
+ *
+ * | protocolVersion range | node version | ledger |
+ * | --------------------- | ------------ | ------ |
+ * | 1_000_000 – 1_999_999 | 1.x          | v8     |
+ * | 2_000_000 – 2_999_999 | 2.x          | v9     |
+ *
+ * Most call sites should not call this directly. Prefer
+ * {@link versionOfRecord} for a `protocolVersion` read off an existing
+ * indexer/node record, or {@link networkHeadVersion} for the network's
+ * current head version — both tag the resulting error with the correct
+ * `path` automatically. Pass `path` explicitly here only when neither helper
+ * fits the call site.
+ *
+ * @param protocolVersion The raw integer read from an indexer or node record.
+ * @param path Which resolution path a failure is attributed to. Defaults to
+ * `'construct'`, and decides which of the two error codes a failure carries.
+ * @returns The {@link LedgerVersion} that `protocolVersion`'s node major maps
+ * onto.
+ * @throws {@link UnknownProtocolVersionError} with `reason: 'malformed'` when
+ * `protocolVersion` is not a non-negative integer, and with `reason: 'unknown'`
+ * when it is a well-formed integer outside every range above.
+ * @see {@link SharedTableDiscipline}
+ */
+const protocolVersionToLedger = (protocolVersion, path = 'construct') => {
+    if (!Number.isInteger(protocolVersion) || protocolVersion < 0) {
+        throw new UnknownProtocolVersionError(protocolVersion, path, 'malformed');
+    }
+    const ledger = lookupLedger(NODE_MAJOR_TO_LEDGER, Math.floor(protocolVersion / 1_000_000));
+    if (ledger === undefined) {
+        throw new UnknownProtocolVersionError(protocolVersion, path, 'unknown');
+    }
+    return ledger;
+};
+/**
+ * Resolves the ledger version for a record's `protocolVersion` field (e.g. a
+ * transaction or block already read from the indexer).
+ *
+ * @param record Any object carrying a raw `protocolVersion` integer field.
+ * @returns The {@link LedgerVersion} that record was written under.
+ * @throws {@link UnknownProtocolVersionError} tagged with the `read` path, on
+ * the same two conditions as {@link protocolVersionToLedger}.
+ */
+const versionOfRecord = (record) => protocolVersionToLedger(record.protocolVersion, 'read');
+/**
+ * Queries `source` for the network's current head protocol version and
+ * resolves it to a {@link LedgerVersion}.
+ *
+ * The source is expected to read the network on every call. This is the
+ * construct path: the era being resolved is the one a transaction built now
+ * will land in, and a stale reading is wrong exactly at the fork boundary,
+ * where that question matters. `PublicDataProvider.queryLatestProtocolVersion`
+ * states the same prohibition as a requirement on its implementations; this
+ * parameter is a structural type, so nothing here can enforce it. See ADR 0007.
+ *
+ * @param source The indexer or node client to ask for the head version.
+ * @returns A promise for the {@link LedgerVersion} at the network head.
+ * @throws {@link UnknownProtocolVersionError} tagged with the `construct`
+ * path, on the same two conditions as {@link protocolVersionToLedger}. A
+ * rejection from `source.queryLatestProtocolVersion()` propagates unchanged.
+ */
+const networkHeadVersion = async (source) => protocolVersionToLedger(await source.queryLatestProtocolVersion(), 'construct');
+
+export { CURRENT_LEDGER_VERSION, LEDGER_VERSIONS, RETAINED_LEDGER_VERSIONS, networkHeadVersion, protocolVersionToLedger, versionOfRecord };
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sources":["../src/lib/shared/ledger-version.ts","../src/version.ts"],"sourcesContent":[null,null],"names":[],"mappings":";;AAAA;;;;;;;;;;;;;AAaG;AAEH;;;;;;;;;AASG;AACI,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,IAAI,CAAU;AAGlE;;;;;;;;;;;AAWG;AACI,MAAM,sBAAsB,GAAG;AAa/B,MAAM,wBAAwB,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAqD;;ACrDhH;;;;;;;;;;;;;AAaG;AA2CH;AACA;AACA,MAAM,oBAAoB,GAAG;AAC3B,IAAA,CAAC,EAAE,IAAI;AACP,IAAA,CAAC,EAAE;CACsD;AAQ3D;AACA;AACA,MAAM,YAAY,GAAG,CAAC,KAA6C,EAAE,GAAW,KAC9E,KAAK,CAAC,GAAG,CAAC;AAEZ;;;;;;;;;;;;;;;;;;;;;;;;;AAyBG;AACI,MAAM,uBAAuB,GAAG,CACrC,eAAuB,EACvB,IAAA,GAA8B,WAAW,KACxB;AACjB,IAAA,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,eAAe,CAAC,IAAI,eAAe,GAAG,CAAC,EAAE;QAC7D,MAAM,IAAI,2BAA2B,CAAC,eAAe,EAAE,IAAI,EAAE,WAAW,CAAC;IAC3E;AACA,IAAA,MAAM,MAAM,GAAG,YAAY,CAAC,oBAAoB,EAAE,IAAI,CAAC,KAAK,CAAC,eAAe,GAAG,SAAS,CAAC,CAAC;AAC1F,IAAA,IAAI,MAAM,KAAK,SAAS,EAAE;QACxB,MAAM,IAAI,2BAA2B,CAAC,eAAe,EAAE,IAAI,EAAE,SAAS,CAAC;IACzE;AACA,IAAA,OAAO,MAAM;AACf;AAEA;;;;;;;;AAQG;AACI,MAAM,eAAe,GAAG,CAAC,MAAuB,KACrD,uBAAuB,CAAC,MAAM,CAAC,eAAe,EAAE,MAAM;AAExD;;;;;;;;;;;;;;;;AAgBG;MACU,kBAAkB,GAAG,OAAO,MAA6B,KACpE,uBAAuB,CAAC,MAAM,MAAM,CAAC,0BAA0B,EAAE,EAAE,WAAW;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midnight-ntwrk/midnight-js-protocol",
-  "version": "5.0.0-beta.7",
+  "version": "5.0.0-beta.8",
   "type": "module",
   "description": "Protocol type re-exports for midnight-js framework",
   "types": "dist/index.d.ts",
@@ -9,10 +9,30 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "default": "./dist/errors.js"
+    },
+    "./version": {
+      "types": "./dist/version.d.ts",
+      "default": "./dist/version.js"
+    },
+    "./prove": {
+      "types": "./dist/prove.d.ts",
+      "default": "./dist/prove.js"
+    },
     "./ledger": {
       "types": "./dist/ledger.d.ts",
       "default": "./dist/ledger.js"
     },
+    "./v8": {
+      "types": "./dist/v8.d.ts",
+      "default": "./dist/v8.js"
+    },
+    "./engine": {
+      "types": "./dist/engine.d.ts",
+      "default": "./dist/engine.js"
+    },
     "./compact-runtime": {
       "types": "./dist/compact-runtime.d.ts",
       "default": "./dist/compact-runtime.js"
@@ -64,15 +84,19 @@
   ],
   "dependencies": {
     "@midnight-ntwrk/compact-js": "2.5.5-rc.8",
-    "@midnight-ntwrk/compact-runtime": "0.19.0-rc.0",
+    "@midnight-ntwrk/compact-runtime": "0.19.0",
+    "@midnight-ntwrk/onchain-runtime-v3": "3.1.1",
     "@midnight-ntwrk/platform-js": "3.0.0",
-    "@midnightntwrk/ledger-v9": "1.0.0-rc.3",
-    "@midnightntwrk/onchain-runtime-v4": "4.0.0-rc.3"
+    "@midnightntwrk/ledger-v8": "8.1.2",
+    "@midnightntwrk/ledger-v9": "1.0.0-rc.4",
+    "@midnightntwrk/onchain-runtime-v4": "4.0.0-rc.3",
+    "compact-runtime-ledger8": "npm:@midnight-ntwrk/compact-runtime@0.16.0"
   },
   "devDependencies": {
     "@rollup/plugin-typescript": "^12.3.0",
     "@vitest/coverage-v8": "^4.1.10",
     "eslint": "^10.8.1",
+    "onchain-runtime-v3-test-only": "npm:@midnight-ntwrk/onchain-runtime-v3@3.1.0",
     "rollup": "^4.60.4",
     "rollup-plugin-dts": "^6.4.1",
     "typescript": "^6.0.3",