@midnightntwrk/midnight-js 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 +168 -2
- package/dist/contracts.d.ts +1 -0
- package/dist/contracts.js +2 -0
- package/dist/contracts.js.map +1 -0
- package/dist/index.d.ts +23 -0
- package/dist/index.js +11 -0
- package/dist/index.js.map +1 -0
- package/dist/protocol/v9.d.ts +2 -0
- package/dist/protocol/v9.js +2 -0
- package/dist/protocol/v9.js.map +1 -0
- package/dist/shared/v9-LayEquWD.js +25 -0
- package/dist/shared/v9-LayEquWD.js.map +1 -0
- package/dist/types.d.ts +1 -0
- package/dist/types.js +2 -0
- package/dist/types.js.map +1 -0
- package/dist/utils.d.ts +1 -0
- package/dist/utils.js +2 -0
- package/dist/utils.js.map +1 -0
- package/package.json +65 -3
package/README.md
CHANGED
|
@@ -1,3 +1,169 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Midnight.js
|
|
2
2
|
|
|
3
|
-
|
|
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 @@
|
|
|
1
|
+
{"version":3,"file":"contracts.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}
|
package/dist/index.d.ts
ADDED
|
@@ -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-LayEquWD.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 @@
|
|
|
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-LayEquWD.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"v9-LayEquWD.js","sources":["../../src/protocol/v9.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAAA;;;;;;;;;;;;;AAaG;;;;;;;;"}
|
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from '@midnightntwrk/midnight-js-types';
|
package/dist/types.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}
|
package/dist/utils.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from '@midnightntwrk/midnight-js-utils';
|
package/dist/utils.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"utils.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}
|
package/package.json
CHANGED
|
@@ -1,6 +1,68 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@midnightntwrk/midnight-js",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"description": "
|
|
3
|
+
"version": "5.0.1",
|
|
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.1",
|
|
50
|
+
"@midnightntwrk/midnight-js-protocol": "5.0.1",
|
|
51
|
+
"@midnightntwrk/midnight-js-types": "5.0.1",
|
|
52
|
+
"@midnightntwrk/midnight-js-utils": "5.0.1"
|
|
53
|
+
},
|
|
54
|
+
"devDependencies": {
|
|
55
|
+
"@rollup/plugin-typescript": "^12.3.0",
|
|
56
|
+
"rollup": "^4.60.4",
|
|
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
|
+
}
|
|
6
68
|
}
|