@midnightntwrk/wallet-sdk-capabilities 4.0.0-rc.1 → 4.0.0

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.
Files changed (62) hide show
  1. package/README.md +10 -3
  2. package/dist/index.d.ts +1 -1
  3. package/dist/index.js +1 -1
  4. package/dist/liveness/livenessReads.js +11 -10
  5. package/dist/liveness/livenessService.js +4 -5
  6. package/dist/proving/index.d.ts +1 -0
  7. package/dist/proving/index.js +1 -0
  8. package/dist/proving/provingService.d.ts +16 -49
  9. package/dist/proving/provingService.js +1 -89
  10. package/dist/proving/v8ProvingService.d.ts +34 -7
  11. package/dist/proving/v8ProvingService.js +36 -6
  12. package/dist/proving/v9ProvingService.d.ts +108 -0
  13. package/dist/proving/v9ProvingService.js +146 -0
  14. package/dist/proving/versionedProving.d.ts +22 -4
  15. package/dist/proving/versionedProving.js +28 -2
  16. package/dist/signatures/v8Signatures.d.ts +1 -1
  17. package/dist/simulation/index.d.ts +4 -6
  18. package/dist/simulation/index.js +4 -7
  19. package/dist/simulation/v8/Simulator.d.ts +1 -3
  20. package/dist/simulation/v8/Simulator.js +1 -3
  21. package/dist/simulation/v8/SimulatorState.d.ts +1 -10
  22. package/dist/simulation/v8/SimulatorState.js +1 -9
  23. package/dist/simulation/v8/index.d.ts +1 -1
  24. package/dist/simulation/v8/index.js +1 -1
  25. package/dist/simulation/v9/Simulator.d.ts +0 -2
  26. package/dist/simulation/v9/Simulator.js +0 -2
  27. package/dist/simulation/v9/SimulatorState.d.ts +0 -9
  28. package/dist/simulation/v9/SimulatorState.js +0 -8
  29. package/dist/simulation/v9/index.d.ts +1 -1
  30. package/dist/simulation/v9/index.js +1 -1
  31. package/dist/submission/submissionService.d.ts +57 -9
  32. package/dist/submission/submissionService.js +61 -15
  33. package/dist/transactionLifecycle/SnapshotFormat.d.ts +51 -0
  34. package/dist/transactionLifecycle/SnapshotFormat.js +120 -0
  35. package/dist/transactionLifecycle/index.d.ts +4 -0
  36. package/dist/{pendingTransactions → transactionLifecycle}/index.js +4 -2
  37. package/dist/transactionLifecycle/lifecycle.d.ts +402 -0
  38. package/dist/transactionLifecycle/lifecycle.js +407 -0
  39. package/dist/transactionLifecycle/lifecycleService.d.ts +448 -0
  40. package/dist/transactionLifecycle/lifecycleService.js +350 -0
  41. package/dist/transactionLifecycle/transactionTraits.d.ts +106 -0
  42. package/dist/transactionLifecycle/transactionTraits.js +53 -0
  43. package/dist/validation/blockData.d.ts +23 -4
  44. package/dist/validation/blockData.js +34 -10
  45. package/dist/validation/index.d.ts +1 -0
  46. package/dist/validation/index.js +1 -0
  47. package/dist/validation/promiseBoundary.d.ts +10 -0
  48. package/dist/validation/promiseBoundary.js +30 -0
  49. package/dist/validation/v8ValidationService.d.ts +6 -5
  50. package/dist/validation/v8ValidationService.js +11 -4
  51. package/dist/validation/v9ValidationService.d.ts +30 -0
  52. package/dist/validation/v9ValidationService.js +61 -0
  53. package/dist/validation/validationService.d.ts +54 -32
  54. package/dist/validation/validationService.js +29 -49
  55. package/dist/validation/versionedValidation.d.ts +5 -3
  56. package/dist/validation/versionedValidation.js +5 -3
  57. package/package.json +12 -12
  58. package/dist/pendingTransactions/index.d.ts +0 -2
  59. package/dist/pendingTransactions/pendingTransactions.d.ts +0 -266
  60. package/dist/pendingTransactions/pendingTransactions.js +0 -302
  61. package/dist/pendingTransactions/pendingTransactionsService.d.ts +0 -108
  62. package/dist/pendingTransactions/pendingTransactionsService.js +0 -186
@@ -10,33 +10,64 @@
10
10
  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11
11
  // See the License for the specific language governing permissions and
12
12
  // limitations under the License.
13
- import { Data, Deferred, Effect, Encoding, Exit, pipe, Scope } from 'effect';
14
- import { NodeClient, PolkadotNodeClient, SubmissionEvent as SubmissionEventImported, } from '@midnightntwrk/wallet-sdk-node-client/effect';
13
+ import { Cause, Data, Effect, Encoding, Exit, Fiber, pipe, Scope } from 'effect';
14
+ import { NodeClient, NodeClientError, PolkadotNodeClient, SubmissionEvent as SubmissionEventImported, } from '@midnightntwrk/wallet-sdk-node-client/effect';
15
15
  import { SerializedTransaction } from '@midnightntwrk/wallet-sdk-abstractions';
16
- import { getLastBlock } from '../simulation/v9/Simulator.js';
16
+ import { getLastBlock } from '../simulation/v9/SimulatorState.js';
17
17
  export const SubmissionEvent = SubmissionEventImported;
18
18
  export class SubmissionError extends Data.TaggedError('SubmissionError') {
19
19
  }
20
+ /**
21
+ * Submits transactions to a node through its relay.
22
+ *
23
+ * @remarks
24
+ * The node takes a transaction's bytes, whichever ledger version wrote them, so left unnamed the transaction type is
25
+ * either ledger version's finalized transaction: never one still to be proved or bound, which no block would take.
26
+ * @example
27
+ * ```typescript
28
+ * const submission = makeDefaultSubmissionServiceEffect({ relayURL: new URL('ws://localhost:9944') });
29
+ * const inBlock = yield* submission.submitTransaction(finalizedTransaction, 'InBlock');
30
+ * yield* submission.close();
31
+ * ```;
32
+ *
33
+ * @param config The relay to submit through.
34
+ * @returns A submission service that closes its connection on `close`.
35
+ */
20
36
  export const makeDefaultSubmissionServiceEffect = (config) => {
21
- const scopeAndClientDeferred = Deferred.make().pipe(Effect.runSync);
22
- const makeScopeAndClient = Effect.gen(function* () {
23
- const scope = yield* Scope.make();
24
- const client = yield* PolkadotNodeClient.make({
25
- nodeURL: config.relayURL,
26
- }).pipe(Effect.provideService(Scope.Scope, scope));
27
- return { scope, client };
28
- });
29
- void pipe(scopeAndClientDeferred, Deferred.complete(makeScopeAndClient), Effect.runPromise);
37
+ // The client is built in the background, so the service is usable at once, and in a scope the service owns. Closing
38
+ // interrupts a build still waiting for the node, which stops its connection attempt, then releases a built client.
39
+ const scope = Scope.make().pipe(Effect.runSync);
40
+ const clientBuild = PolkadotNodeClient.make({ nodeURL: config.relayURL }).pipe(Effect.provideService(Scope.Scope, scope), Effect.runFork);
41
+ // A build interrupted by `close` never produced a client, so a submission arriving after it fails instead of waiting.
42
+ const client = pipe(Fiber.await(clientBuild), Effect.flatMap((exit) => Exit.isFailure(exit) && Cause.isInterruptedOnly(exit.cause)
43
+ ? Effect.fail(new NodeClientError.ConnectionError({
44
+ message: `The submission service was closed before it connected to ${config.relayURL.toString()}`,
45
+ }))
46
+ : exit));
30
47
  const submit = (transaction, waitForStatus = 'InBlock') => {
31
- return pipe(NodeClient.sendMidnightTransactionAndWait(SerializedTransaction.from(transaction), waitForStatus), Effect.provideServiceEffect(NodeClient.NodeClient, pipe(scopeAndClientDeferred, Deferred.await, Effect.map(({ client }) => client))), Effect.mapError((err) => new SubmissionError({ message: 'Transaction submission error', cause: err })));
48
+ return pipe(NodeClient.sendMidnightTransactionAndWait(SerializedTransaction.from(transaction), waitForStatus), Effect.provideServiceEffect(NodeClient.NodeClient, client), Effect.mapError((err) => new SubmissionError({ message: 'Transaction submission error', cause: err })));
32
49
  };
33
50
  return {
34
51
  submitTransaction: submit,
35
52
  close() {
36
- return pipe(scopeAndClientDeferred, Deferred.await, Effect.flatMap(({ scope }) => Scope.close(scope, Exit.void)), Effect.ignoreLogged);
53
+ // Releasing the client is the last use of it, so a release that fails is logged rather than failing the caller.
54
+ return pipe(Fiber.interrupt(clientBuild), Effect.zipRight(Scope.close(scope, Exit.void)), Effect.ignoreLogged);
37
55
  },
38
56
  };
39
57
  };
58
+ /**
59
+ * The promise-facing surface of {@link makeDefaultSubmissionServiceEffect}.
60
+ *
61
+ * @example
62
+ * ```typescript
63
+ * const submission = makeDefaultSubmissionService({ relayURL: new URL('ws://localhost:9944') });
64
+ * const inBlock = await submission.submitTransaction(finalizedTransaction, 'InBlock');
65
+ * await submission.close();
66
+ * ```;
67
+ *
68
+ * @param config The relay to submit through.
69
+ * @returns A submission service that closes its connection on `close`.
70
+ */
40
71
  export const makeDefaultSubmissionService = (config) => {
41
72
  const effectService = makeDefaultSubmissionServiceEffect(config);
42
73
  const submit = (transaction, waitForStatus = 'InBlock') => effectService.submitTransaction(transaction, waitForStatus).pipe(Effect.runPromise);
@@ -45,7 +76,22 @@ export const makeDefaultSubmissionService = (config) => {
45
76
  close: () => effectService.close().pipe(Effect.runPromise),
46
77
  };
47
78
  };
48
- export const makeSimulatorSubmissionService = (waitForStatus = 'InBlock') => (config) => {
79
+ /**
80
+ * Submits transactions to the in-memory ledger-v9 simulator, answering as a node would.
81
+ *
82
+ * @remarks
83
+ * The simulator has no relay to report progress, so every submission answers with the one status this service was built
84
+ * for, read off the simulator's latest block once the transaction is in.
85
+ * @example
86
+ * ```typescript
87
+ * const submission = makeV9SimulatorSubmissionService<ledger.ProofErasedTransaction>('InBlock')({ simulator });
88
+ * const inBlock = yield* submission.submitTransaction(proofErasedTransaction);
89
+ * ```;
90
+ *
91
+ * @param waitForStatus The status every submission reports. Defaults to `InBlock`, as a node's does.
92
+ * @returns A function from the simulator to the submission service over it.
93
+ */
94
+ export const makeV9SimulatorSubmissionService = (waitForStatus = 'InBlock') => (config) => {
49
95
  const submit = (transaction) => {
50
96
  return pipe(config.simulator.submitTransaction(transaction),
51
97
  // Wait for stream-based block production
@@ -0,0 +1,51 @@
1
+ import { Either, type ParseResult } from 'effect';
2
+ /**
3
+ * Every format version the transaction lifecycle store has been written in, oldest first.
4
+ *
5
+ * Declared here, with no ledger import, so the reader and the upgrade step share one source of truth.
6
+ */
7
+ export declare const SNAPSHOT_FORMAT_VERSIONS: readonly ["v1", "v2"];
8
+ /** The format version of a store holding pending items and reservations side by side. */
9
+ export declare const V1_SNAPSHOT_FORMAT_VERSION = "v1";
10
+ /**
11
+ * The format version of a store holding one lifecycle record per transaction. {@link upgradeSnapshotV1ToV2} is the one
12
+ * step into it, and this is the version it stamps. Frozen: a later bump adds a version and a step of its own and leaves
13
+ * this one as it is.
14
+ */
15
+ export declare const V2_SNAPSHOT_FORMAT_VERSION = "v2";
16
+ /**
17
+ * The current format version of the store. This is the constant a bump moves; the upgrade steps never read it, because
18
+ * each stamps the version it upgrades to.
19
+ */
20
+ export declare const SNAPSHOT_FORMAT_VERSION = "v2";
21
+ /**
22
+ * Refuses a store stamped `v1` that does not have the `v1` shape, with the reason it does not.
23
+ *
24
+ * @remarks
25
+ * Run before {@link upgradeSnapshotV1ToV2}, which hands back anything that is not a `v1` store unchanged. Without this
26
+ * check a damaged `v1` store would reach the `v2` reader and be refused for its version, which this build does read,
27
+ * rather than for what is actually wrong in it. Anything not stamped `v1` passes through for the reader after it to
28
+ * judge.
29
+ * @example
30
+ * const checked = checkV1Store(JSON.parse(stored));
31
+ *
32
+ * @param json The store as decoded from its JSON string.
33
+ * @returns The input unchanged, or why a store stamped `v1` is not one.
34
+ */
35
+ export declare const checkV1Store: (json: unknown) => Either.Either<unknown, ParseResult.ParseError>;
36
+ /**
37
+ * Upgrades a decoded transaction lifecycle store from format version `v1` to `v2`.
38
+ *
39
+ * @remarks
40
+ * A pure function on the decoded JSON, run before any schema, so the schema only ever has to describe one shape. Each
41
+ * pending item and each reservation becomes one lifecycle record, pending items first; every other top-level member,
42
+ * known or not, passes through untouched. It fills in only what `v1` recorded and leaves out what it never did, so
43
+ * the reader derives that from the transaction or goes without. Anything that is not a `v1` store is handed back as
44
+ * it came, for the schema after it to refuse with a precise reason; and applying the step twice is applying it once.
45
+ * @example
46
+ * const current = upgradeSnapshotV1ToV2(JSON.parse(stored));
47
+ *
48
+ * @param json The store as decoded from its JSON string.
49
+ * @returns The same store in format `v2`, or the input unchanged when the step does not apply.
50
+ */
51
+ export declare const upgradeSnapshotV1ToV2: (json: unknown) => unknown;
@@ -0,0 +1,120 @@
1
+ /*
2
+ * This file is part of MIDNIGHT-WALLET-SDK.
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
+ import { Either, Schema } from 'effect';
16
+ /**
17
+ * Every format version the transaction lifecycle store has been written in, oldest first.
18
+ *
19
+ * Declared here, with no ledger import, so the reader and the upgrade step share one source of truth.
20
+ */
21
+ export const SNAPSHOT_FORMAT_VERSIONS = ['v1', 'v2'];
22
+ /** The format version of a store holding pending items and reservations side by side. */
23
+ export const V1_SNAPSHOT_FORMAT_VERSION = 'v1';
24
+ /**
25
+ * The format version of a store holding one lifecycle record per transaction. {@link upgradeSnapshotV1ToV2} is the one
26
+ * step into it, and this is the version it stamps. Frozen: a later bump adds a version and a step of its own and leaves
27
+ * this one as it is.
28
+ */
29
+ export const V2_SNAPSHOT_FORMAT_VERSION = 'v2';
30
+ /**
31
+ * The current format version of the store. This is the constant a bump moves; the upgrade steps never read it, because
32
+ * each stamps the version it upgrades to.
33
+ */
34
+ export const SNAPSHOT_FORMAT_VERSION = V2_SNAPSHOT_FORMAT_VERSION;
35
+ const V1PendingItem = Schema.Struct({
36
+ tx: Schema.String,
37
+ creationTime: Schema.String,
38
+ protocolVersion: Schema.optional(Schema.String),
39
+ });
40
+ const V1Reservation = Schema.Struct({
41
+ identifiers: Schema.Array(Schema.String),
42
+ intentHashes: Schema.Array(Schema.String),
43
+ inputs: Schema.Struct({
44
+ unshielded: Schema.Array(Schema.String),
45
+ shielded: Schema.optional(Schema.Array(Schema.String)),
46
+ }),
47
+ ttl: Schema.String,
48
+ createdAt: Schema.String,
49
+ expired: Schema.Boolean,
50
+ });
51
+ /** What the step looks for: a `v1` store, whose reservations arrived after it was in the field and may be absent. */
52
+ const V1Store = Schema.Struct({
53
+ version: Schema.Literal(V1_SNAPSHOT_FORMAT_VERSION),
54
+ transactions: Schema.Array(V1PendingItem),
55
+ reservations: Schema.optional(Schema.Array(V1Reservation)),
56
+ });
57
+ const isV1Store = Schema.is(V1Store);
58
+ const isStampedV1 = (json) => typeof json === 'object' && json !== null && 'version' in json && json.version === V1_SNAPSHOT_FORMAT_VERSION;
59
+ /**
60
+ * Refuses a store stamped `v1` that does not have the `v1` shape, with the reason it does not.
61
+ *
62
+ * @remarks
63
+ * Run before {@link upgradeSnapshotV1ToV2}, which hands back anything that is not a `v1` store unchanged. Without this
64
+ * check a damaged `v1` store would reach the `v2` reader and be refused for its version, which this build does read,
65
+ * rather than for what is actually wrong in it. Anything not stamped `v1` passes through for the reader after it to
66
+ * judge.
67
+ * @example
68
+ * const checked = checkV1Store(JSON.parse(stored));
69
+ *
70
+ * @param json The store as decoded from its JSON string.
71
+ * @returns The input unchanged, or why a store stamped `v1` is not one.
72
+ */
73
+ export const checkV1Store = (json) => isStampedV1(json) ? Either.map(Schema.decodeUnknownEither(V1Store)(json), () => json) : Either.right(json);
74
+ /**
75
+ * A pending item was finalized at least, and `v1` showed it as submitted. When it was submitted was never kept: its
76
+ * creation time is when it was finalized. Its identifiers, intent hashes, inputs and TTL live in the transaction, for
77
+ * the reader to take from it.
78
+ */
79
+ const fromPendingItem = (item) => ({
80
+ tx: item.tx,
81
+ createdAt: item.creationTime,
82
+ ...(item.protocolVersion === undefined ? {} : { protocolVersion: item.protocolVersion }),
83
+ state: { _tag: 'Submitted' },
84
+ });
85
+ /** A reservation never held its transaction or the version it was built for, so its record holds neither. */
86
+ const fromReservation = (reservation) => ({
87
+ identifiers: reservation.identifiers,
88
+ intentHashes: reservation.intentHashes,
89
+ inputs: reservation.inputs.shielded === undefined
90
+ ? { unshielded: reservation.inputs.unshielded }
91
+ : { unshielded: reservation.inputs.unshielded, shielded: reservation.inputs.shielded },
92
+ ttl: reservation.ttl,
93
+ createdAt: reservation.createdAt,
94
+ state: { _tag: reservation.expired ? 'Expired' : 'Balanced' },
95
+ });
96
+ /**
97
+ * Upgrades a decoded transaction lifecycle store from format version `v1` to `v2`.
98
+ *
99
+ * @remarks
100
+ * A pure function on the decoded JSON, run before any schema, so the schema only ever has to describe one shape. Each
101
+ * pending item and each reservation becomes one lifecycle record, pending items first; every other top-level member,
102
+ * known or not, passes through untouched. It fills in only what `v1` recorded and leaves out what it never did, so
103
+ * the reader derives that from the transaction or goes without. Anything that is not a `v1` store is handed back as
104
+ * it came, for the schema after it to refuse with a precise reason; and applying the step twice is applying it once.
105
+ * @example
106
+ * const current = upgradeSnapshotV1ToV2(JSON.parse(stored));
107
+ *
108
+ * @param json The store as decoded from its JSON string.
109
+ * @returns The same store in format `v2`, or the input unchanged when the step does not apply.
110
+ */
111
+ export const upgradeSnapshotV1ToV2 = (json) => {
112
+ if (!isV1Store(json))
113
+ return json;
114
+ const { transactions, reservations = [], ...rest } = json;
115
+ return {
116
+ ...rest,
117
+ version: V2_SNAPSHOT_FORMAT_VERSION,
118
+ records: [...transactions.map(fromPendingItem), ...reservations.map(fromReservation)],
119
+ };
120
+ };
@@ -0,0 +1,4 @@
1
+ export * as TransactionTraits from './transactionTraits.js';
2
+ export * as Lifecycle from './lifecycle.js';
3
+ export * from './lifecycleService.js';
4
+ export * as LifecycleFormat from './SnapshotFormat.js';
@@ -12,5 +12,7 @@
12
12
  * See the License for the specific language governing permissions and
13
13
  * limitations under the License.
14
14
  */
15
- export * from './pendingTransactionsService.js';
16
- export * as PendingTransactions from './pendingTransactions.js';
15
+ export * as TransactionTraits from './transactionTraits.js';
16
+ export * as Lifecycle from './lifecycle.js';
17
+ export * from './lifecycleService.js';
18
+ export * as LifecycleFormat from './SnapshotFormat.js';