@midnightntwrk/midnight-js 0.0.0-stage → 5.0.2-0-pre.d76c0cbe

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 CHANGED
@@ -1,3 +1,169 @@
1
- # Temporary Holding Version
1
+ # Midnight.js
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Barrel package that provides a single entry point to the core components of Midnight.js. Import all core modules from one package instead of installing them individually.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ yarn add @midnightntwrk/midnight-js
9
+ ```
10
+
11
+ ## Quick Start
12
+
13
+ ```typescript
14
+ import { contracts, types, utils } from '@midnightntwrk/midnight-js';
15
+
16
+ // providers.config carries the network id: { networkId: 'preview', ttlSeconds: 3600 }
17
+ const deployed = await contracts.deployContract(providers, {
18
+ compiledContract: myContract,
19
+ privateStateId: 'my-state',
20
+ initialPrivateState: { counter: 0n }
21
+ });
22
+ ```
23
+
24
+ ## Modules
25
+
26
+ | Module | Package | Description |
27
+ | ------------ | ---------------------------------------- | ---------------------------------------------- |
28
+ | `contracts` | `@midnightntwrk/midnight-js-contracts` | Contract deployment and interaction utilities |
29
+ | `types` | `@midnightntwrk/midnight-js-types` | Shared types, interfaces, and provider contracts|
30
+ | `utils` | `@midnightntwrk/midnight-js-utils` | Hex encoding, address validation, and utilities |
31
+
32
+ ## Ledger Era Vocabulary
33
+
34
+ The network runs one of two ledger eras, `v8` or `v9`. The names for saying
35
+ which era produced a payload or a record are re-exported from the barrel
36
+ directly, alongside the namespaces above:
37
+
38
+ ```typescript
39
+ import {
40
+ LEDGER_ERAS, // the closed, frozen set: ['v8', 'v9']
41
+ CURRENT_LEDGER_ERA, // the current era, 'v9': the `era` of every current-era result
42
+ type LedgerEra, // 'v8' | 'v9'
43
+ versionOfRecord, // a record carrying protocolVersion -> LedgerEra
44
+ latestNetworkLedgerVersion // asks a source for the network's current ledger era -> LedgerEra
45
+ } from '@midnightntwrk/midnight-js';
46
+ ```
47
+
48
+ Use `versionOfRecord` for a `protocolVersion` read off an existing record, and
49
+ `latestNetworkLedgerVersion` for the era a transaction built now would land in. Each
50
+ tags its failures with the path it was called on, so a handler can tell the two
51
+ apart.
52
+
53
+ Both refuse rather than guess. They raise `UnknownProtocolVersionError` when a
54
+ `protocolVersion` is malformed (not a non-negative integer) or is well-formed
55
+ but maps to no era this build knows. `versionOfRecord` throws;
56
+ `latestNetworkLedgerVersion` is `async`, so it rejects instead, and a rejection from
57
+ the source itself propagates unchanged.
58
+
59
+ ```typescript
60
+ import {
61
+ type ProtocolVersionUnknownReason,
62
+ UnknownProtocolVersionError,
63
+ versionOfRecord,
64
+ type VersionResolutionPath
65
+ } from '@midnightntwrk/midnight-js';
66
+
67
+ // Any record carrying a raw protocolVersion -- e.g. a transaction or block
68
+ // already read from the indexer. Node major 9 is one this build has no era
69
+ // for, so this record takes the failure path.
70
+ const record = { protocolVersion: 9_000_000 };
71
+
72
+ try {
73
+ const era = versionOfRecord(record);
74
+ console.log(`this record was written under ledger ${era}`);
75
+ } catch (error) {
76
+ // Anything that is not ours is not ours to interpret. Never swallow it.
77
+ if (!(error instanceof UnknownProtocolVersionError)) {
78
+ throw error;
79
+ }
80
+
81
+ const path: VersionResolutionPath = error.path; // 'read' | 'construct'
82
+ const reason: ProtocolVersionUnknownReason = error.reason; // 'unknown' | 'malformed'
83
+
84
+ throw new Error(
85
+ reason === 'unknown'
86
+ ? `This record is from a ledger era this build does not know (${path} path). Upgrade midnight-js.`
87
+ : `The protocolVersion handed to versionOfRecord was malformed (${path} path). Check the source record.`,
88
+ { cause: error }
89
+ );
90
+ }
91
+ ```
92
+
93
+ Both eras are worth handling explicitly, because the two reasons need different
94
+ responses: `'unknown'` means this framework build predates the network, and
95
+ `'malformed'` means the wrong field was wired into the resolver.
96
+
97
+ If you would rather discriminate on a stable string than on a class, every
98
+ error here also carries a `code`. `PROTOCOL_ERROR_CODES` names them and
99
+ `utils.hasErrorCode` is the guard:
100
+
101
+ ```typescript
102
+ import { PROTOCOL_ERROR_CODES, utils } from '@midnightntwrk/midnight-js';
103
+
104
+ if (utils.hasErrorCode(error, PROTOCOL_ERROR_CODES.UNKNOWN_PROTOCOL_VERSION_READ)) {
105
+ // the era of an existing record could not be resolved
106
+ }
107
+ ```
108
+
109
+ ### Errors from the retained era
110
+
111
+ Deploying to or calling a `v8` contract runs through the retained pre-fork
112
+ pipeline, which raises errors of its own. The barrel publishes those classes
113
+ too, so you can catch them and read their payload without a cast:
114
+
115
+ | Class | Payload | Means |
116
+ | ----- | ------- | ----- |
117
+ | `Ledger8RuntimeMissingError` | `subpath` | the retained runtime chunk could not be loaded at all |
118
+ | `ComposeFailedError` | `version`, `stage`, `circuitId` | a circuit operation is missing or under-registered |
119
+ | `ComposeOptionError` | `version`, `option` | one composition option cannot be used |
120
+ | `StateDecodeFailedError` | `version` | contract-state bytes could not be read as that era |
121
+ | `StateInconsistentError` | `version` | contract-state bytes were read as that era, but the state is internally inconsistent |
122
+ | `UnknownLedgerEraError` | `requestedVersion` | the value names an era outside `LEDGER_ERAS`, or carries no era (`requestedVersion` is `undefined`: a pre-5.0.0 provider) |
123
+ | `PayloadNotATransactionError` | none | a `v8` payload sent for proving was not a transaction |
124
+
125
+ ### What importing the barrel loads
126
+
127
+ The retained pre-fork (`v8`) ledger runtime is **not** re-exported here, and it
128
+ is absent from the barrel's static import graph. It is loaded on demand, only
129
+ once you actually touch a `v8` contract.
130
+
131
+ Importing the barrel is not otherwise free: it pulls the `v9` ledger and
132
+ onchain-runtime, because `contracts` needs them. The sub-path imports below let
133
+ you take one module without the rest.
134
+
135
+ ## Sub-path Imports
136
+
137
+ Each module is also available as a sub-path import for tree-shaking:
138
+
139
+ ```typescript
140
+ import { deployContract, findDeployedContract } from '@midnightntwrk/midnight-js/contracts';
141
+ import { type ProofProvider, type WalletProvider } from '@midnightntwrk/midnight-js/types';
142
+ import { toHex, fromHex } from '@midnightntwrk/midnight-js/utils';
143
+ ```
144
+
145
+ ## Exports
146
+
147
+ ```typescript
148
+ // Namespace imports (all modules)
149
+ import { contracts, types, utils } from '@midnightntwrk/midnight-js';
150
+
151
+ // Ledger era vocabulary (named, not namespaced)
152
+ import { LEDGER_ERAS, type LedgerEra } from '@midnightntwrk/midnight-js';
153
+
154
+ // Sub-path imports (individual modules)
155
+ import { ... } from '@midnightntwrk/midnight-js/contracts';
156
+ import { ... } from '@midnightntwrk/midnight-js/types';
157
+ import { ... } from '@midnightntwrk/midnight-js/utils';
158
+ ```
159
+
160
+ ## Resources
161
+
162
+ - [Midnight Network](https://midnight.network)
163
+ - [Developer Hub](https://midnight.network/developer-hub)
164
+
165
+ ## Terms & License
166
+
167
+ 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).
168
+
169
+ Licensed under [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0).
@@ -0,0 +1 @@
1
+ export * from '@midnightntwrk/midnight-js-contracts';
@@ -0,0 +1,2 @@
1
+ export * from '@midnightntwrk/midnight-js-contracts';
2
+ //# sourceMappingURL=contracts.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"contracts.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}
@@ -0,0 +1,23 @@
1
+ import { CompiledContract, ContractExecutable } from '@midnightntwrk/midnight-js-protocol/v9/compact-js';
2
+ import { Contract } from '@midnightntwrk/midnight-js-protocol/v9/compact-js/effect/Contract';
3
+ import * as midnightJsContracts from '@midnightntwrk/midnight-js-contracts';
4
+ export { midnightJsContracts as contracts };
5
+ import * as midnightJsTypes from '@midnightntwrk/midnight-js-types';
6
+ export { midnightJsTypes as types };
7
+ import * as midnightJsUtils from '@midnightntwrk/midnight-js-utils';
8
+ export { midnightJsUtils as utils };
9
+ export { CURRENT_LEDGER_ERA, CurrentLedgerEra, LEDGER_ERAS, LedgerEra, ProtocolVersionSource, VersionedRecord, latestNetworkLedgerVersion, versionOfRecord } from '@midnightntwrk/midnight-js-protocol/version';
10
+ export { COMMON_ERROR_CODES, ComposeFailedError, ComposeOption, ComposeOptionError, ComposeStage, ConfigurationError, ContractExecutionError, EnvironmentUnsupportedError, InvalidArgumentError, InvariantViolationError, Ledger8RuntimeMissingError, Ledger8Subpath, MIDNIGHT_JS_ERROR_CATEGORIES, MidnightJsError, MidnightJsErrorCategory, NO_CIRCUIT, PROTOCOL_ERROR_CODES, PayloadNotATransactionError, ProtocolVersionUnknownReason, StateDecodeFailedError, StateInconsistentError, UnknownLedgerEraError, UnknownProtocolVersionError, VersionResolutionPath } from '@midnightntwrk/midnight-js-protocol/errors';
11
+
12
+ declare const v9_CompiledContract: typeof CompiledContract;
13
+ declare const v9_Contract: typeof Contract;
14
+ declare const v9_ContractExecutable: typeof ContractExecutable;
15
+ declare namespace v9 {
16
+ export {
17
+ v9_CompiledContract as CompiledContract,
18
+ v9_Contract as Contract,
19
+ v9_ContractExecutable as ContractExecutable,
20
+ };
21
+ }
22
+
23
+ export { v9 as ledger9Protocol };
package/dist/index.js ADDED
@@ -0,0 +1,11 @@
1
+ export { v as ledger9Protocol } from './shared/v9-ChRzyKZ8.js';
2
+ import * as midnightJsContracts from '@midnightntwrk/midnight-js-contracts';
3
+ export { midnightJsContracts as contracts };
4
+ import * as midnightJsTypes from '@midnightntwrk/midnight-js-types';
5
+ export { midnightJsTypes as types };
6
+ import * as midnightJsUtils from '@midnightntwrk/midnight-js-utils';
7
+ export { midnightJsUtils as utils };
8
+ export { CURRENT_LEDGER_ERA, LEDGER_ERAS, latestNetworkLedgerVersion, versionOfRecord } from '@midnightntwrk/midnight-js-protocol/version';
9
+ export { COMMON_ERROR_CODES, ComposeFailedError, ComposeOptionError, ConfigurationError, ContractExecutionError, EnvironmentUnsupportedError, InvalidArgumentError, InvariantViolationError, Ledger8RuntimeMissingError, MIDNIGHT_JS_ERROR_CATEGORIES, MidnightJsError, NO_CIRCUIT, PROTOCOL_ERROR_CODES, PayloadNotATransactionError, StateDecodeFailedError, StateInconsistentError, UnknownLedgerEraError, UnknownProtocolVersionError } from '@midnightntwrk/midnight-js-protocol/errors';
10
+ import '@midnightntwrk/midnight-js-protocol/v9/compact-js';
11
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;"}
@@ -0,0 +1,2 @@
1
+ export { CompiledContract, ContractExecutable } from '@midnightntwrk/midnight-js-protocol/v9/compact-js';
2
+ export { Contract } from '@midnightntwrk/midnight-js-protocol/v9/compact-js/effect/Contract';
@@ -0,0 +1,2 @@
1
+ export { CompiledContract, ContractExecutable } from '@midnightntwrk/midnight-js-protocol/v9/compact-js';
2
+ //# sourceMappingURL=v9.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"v9.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}
@@ -0,0 +1,25 @@
1
+ import { CompiledContract, ContractExecutable } from '@midnightntwrk/midnight-js-protocol/v9/compact-js';
2
+
3
+ /*
4
+ * This file is part of midnight-js.
5
+ * Copyright (C) Midnight Foundation
6
+ * SPDX-License-Identifier: Apache-2.0
7
+ * Licensed under the Apache License, Version 2.0 (the "License");
8
+ * You may not use this file except in compliance with the License.
9
+ * You may obtain a copy of the License at
10
+ * http://www.apache.org/licenses/LICENSE-2.0
11
+ * Unless required by applicable law or agreed to in writing, software
12
+ * distributed under the License is distributed on an "AS IS" BASIS,
13
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14
+ * See the License for the specific language governing permissions and
15
+ * limitations under the License.
16
+ */
17
+
18
+ var v9 = /*#__PURE__*/Object.freeze({
19
+ __proto__: null,
20
+ CompiledContract: CompiledContract,
21
+ ContractExecutable: ContractExecutable
22
+ });
23
+
24
+ export { v9 as v };
25
+ //# sourceMappingURL=v9-ChRzyKZ8.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"v9-ChRzyKZ8.js","sources":["../../src/protocol/v9.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAAA;;;;;;;;;;;;;AAaG;;;;;;;;"}
@@ -0,0 +1 @@
1
+ export * from '@midnightntwrk/midnight-js-types';
package/dist/types.js ADDED
@@ -0,0 +1,2 @@
1
+ export * from '@midnightntwrk/midnight-js-types';
2
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}
@@ -0,0 +1 @@
1
+ export * from '@midnightntwrk/midnight-js-utils';
package/dist/utils.js ADDED
@@ -0,0 +1,2 @@
1
+ export * from '@midnightntwrk/midnight-js-utils';
2
+ //# sourceMappingURL=utils.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"utils.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}
package/package.json CHANGED
@@ -1,6 +1,69 @@
1
1
  {
2
2
  "name": "@midnightntwrk/midnight-js",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "5.0.2-0-pre.d76c0cbe",
4
+ "type": "module",
5
+ "description": "Barrel package for Midnight.js core framework",
6
+ "types": "dist/index.d.ts",
7
+ "exports": {
8
+ ".": {
9
+ "types": "./dist/index.d.ts",
10
+ "default": "./dist/index.js"
11
+ },
12
+ "./contracts": {
13
+ "types": "./dist/contracts.d.ts",
14
+ "default": "./dist/contracts.js"
15
+ },
16
+ "./protocol/v9": {
17
+ "types": "./dist/protocol/v9.d.ts",
18
+ "default": "./dist/protocol/v9.js"
19
+ },
20
+ "./types": {
21
+ "types": "./dist/types.d.ts",
22
+ "default": "./dist/types.js"
23
+ },
24
+ "./utils": {
25
+ "types": "./dist/utils.d.ts",
26
+ "default": "./dist/utils.js"
27
+ },
28
+ "./package.json": "./package.json"
29
+ },
30
+ "sideEffects": false,
31
+ "repository": {
32
+ "type": "git",
33
+ "url": "git+https://github.com/midnightntwrk/midnight-js.git",
34
+ "directory": "packages/midnight-js"
35
+ },
36
+ "homepage": "https://github.com/midnightntwrk/midnight-js/tree/main/packages/midnight-js#readme",
37
+ "bugs": {
38
+ "url": "https://github.com/midnightntwrk/midnight-js/issues"
39
+ },
40
+ "author": "Midnight Foundation",
41
+ "packageManager": "yarn@4.14.1",
42
+ "license": "Apache-2.0",
43
+ "scripts": {
44
+ "clean": "rm -rf dist tsconfig.build.tsbuildinfo .rollup.cache reports coverage",
45
+ "build": "rollup -c rollup.config.mjs",
46
+ "test": "vitest run --passWithNoTests"
47
+ },
48
+ "dependencies": {
49
+ "@midnightntwrk/midnight-js-contracts": "5.0.2-0-pre.d76c0cbe",
50
+ "@midnightntwrk/midnight-js-protocol": "5.0.2-0-pre.d76c0cbe",
51
+ "@midnightntwrk/midnight-js-types": "5.0.2-0-pre.d76c0cbe",
52
+ "@midnightntwrk/midnight-js-utils": "5.0.2-0-pre.d76c0cbe"
53
+ },
54
+ "devDependencies": {
55
+ "@rollup/plugin-typescript": "^12.3.0",
56
+ "rollup": "^4.68.2",
57
+ "rollup-plugin-dts": "^6.5.1",
58
+ "typescript": "^6.0.3",
59
+ "vite": "^8.3.4",
60
+ "vitest": "^5.0.4"
61
+ },
62
+ "files": [
63
+ "dist/"
64
+ ],
65
+ "engines": {
66
+ "node": ">=22.12"
67
+ },
68
+ "stableVersion": "5.0.1"
6
69
  }