@midnight-ntwrk/wallet-sdk-shielded 4.0.0-beta.3 → 4.0.0-beta.4

package/README.md

@@ -89,8 +89,10 @@ wallet.state.subscribe((state) => {
 ### Creating Transfer Transactions
 
 ```typescript
+// tokenType: the shielded token type (raw hex) of a token you hold,
+// e.g. one minted by a contract — NIGHT is unshielded and cannot appear here
 const tx = await wallet.transferTransaction(shieldedSecretKeys, [
-  { type: 'NIGHT', receiverAddress: 'mn_shield-addr1...', amount: 1000n },
+  { type: tokenType, receiverAddress: 'mn_shield-addr1...', amount: 1000n },
 ]);
 ```
 
@@ -103,10 +105,12 @@ const balancingTx = await wallet.balanceTransaction(shieldedSecretKeys, transact
 ### Creating Swap Offers
 
 ```typescript
+// tokenTypeA / tokenTypeB: shielded token types (raw hex) — both sides of a
+// shielded swap are shielded tokens; NIGHT is unshielded and cannot appear here
 const swapTx = await wallet.initSwap(
   shieldedSecretKeys,
-  { NIGHT: 500n }, // inputs
-  [{ type: 'TOKEN_A', receiverAddress: shieldedAddress, amount: 100n }], // outputs
+  { [tokenTypeA]: 500n }, // inputs
+  [{ type: tokenTypeB, receiverAddress: shieldedAddress, amount: 100n }], // outputs
 );
 ```
 

package/dist/v1/Sync.js

@@ -11,13 +11,13 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 import * as ledger from '@midnight-ntwrk/ledger-v8';
-import { Chunk, Duration, Effect, Either, identity, Option, ParseResult, pipe, Schedule, Schema, Stream, } from 'effect';
+import { Array as Arr, Chunk, Duration, Effect, Either, identity, Option, ParseResult, pipe, Schedule, Schema, Stream, } from 'effect';
 import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
 import { CoreWallet } from './CoreWallet.js';
 import { V8 } from '@midnight-ntwrk/wallet-sdk-capabilities/simulation';
 import { BlockHash, ZswapEventTip, ZswapEvents } from '@midnight-ntwrk/wallet-sdk-indexer-client';
 import { ConnectionHelper, HttpQueryClient, WsSubscriptionClient, } from '@midnight-ntwrk/wallet-sdk-indexer-client/effect';
-import { SyncWalletError } from './WalletError.js';
+import { OutOfOrderSyncUpdateError, SyncWalletError } from './WalletError.js';
 import { WsURL } from '@midnight-ntwrk/wallet-sdk-utilities/networking';
 import { EitherOps } from '@midnight-ntwrk/wallet-sdk-utilities';
 /**
@@ -48,6 +48,26 @@ export const splitAtVersionBoundary = (items, versionOf, activeRange) => {
             : Option.some(ProtocolVersion.ProtocolVersion(BigInt(versionOf(signalling)))),
     };
 };
+/**
+ * Checks that freshly delivered events arrive in strictly ascending id order.
+ *
+ * @remarks
+ *   Order is all that can be checked, never contiguity: zswap events share one id sequence with dust and contract events
+ *   in the indexer, so gaps in a zswap stream are normal. A skipped commitment-inserting event is caught by the
+ *   ledger's own insertion check instead. An empty batch is trivially ordered.
+ * @param fresh The events left after the cursor filter, in source order.
+ * @param appliedIndex The highest event id already applied; the first fresh id must exceed it.
+ * @returns The batch unchanged, or the first id that fails to exceed its predecessor as an
+ *   {@link OutOfOrderSyncUpdateError}.
+ */
+const expectAscending = (fresh, appliedIndex) => pipe(Arr.zipWith(fresh, Arr.prepend(Arr.map(fresh, (item) => BigInt(item.id)), appliedIndex), (item, previous) => ({ item, previous })), Arr.findFirst(({ item, previous }) => BigInt(item.id) <= previous), Option.match({
+    onNone: () => Either.right(fresh),
+    onSome: ({ item, previous }) => Either.left(new OutOfOrderSyncUpdateError({
+        message: `Zswap event ${item.id} delivered at or below its predecessor ${previous}; batch refused, applied index stays at ${appliedIndex}`,
+        expected: previous,
+        received: BigInt(item.id),
+    })),
+}));
 /** Records a batch's observed protocol version on the state, monotonically. A batch that observed none is a no-op. */
 export const annotateVersion = (state, observedVersion) => Option.match(observedVersion, {
     onNone: () => state,
@@ -334,7 +354,14 @@ export const makeEventsSyncCapability = () => {
             // the batch tail even when the tail belongs to the next protocol version.
             const lastUpdate = wrappedUpdate.updates.at(-1);
             const highestRelevantWalletIndex = BigInt(lastUpdate.maxId);
-            const { applied, observedVersion } = splitAtVersionBoundary(freshUpdates, (update) => update.protocolVersion, activeRange);
+            // Refuse the whole batch: applying the sound prefix would move the cursor and hide the fault behind
+            // `isConnected: true`. State and cursor stay untouched, so the retry re-fetches the same range; a transient
+            // reorder heals, a persistent one fails visibly.
+            //
+            // `SyncCapability.applyUpdate` has no typed error channel, so throwing preserves its public tuple-returning API;
+            // `RunningV1Variant` catches this at the capability boundary. See #572 for the planned `Either`-based API.
+            const orderedUpdates = Either.getOrThrowWith(expectAscending(freshUpdates, appliedIndex), identity);
+            const { applied, observedVersion } = splitAtVersionBoundary(orderedUpdates, (update) => update.protocolVersion, activeRange);
             // Read here and nowhere earlier: `applied` is exactly the slice this variant owns, so nothing outside its
             // activation range — nor anything below its cursor — is ever handed to this ledger version's deserializer.
             const [newState, newChanges] = applied.length === 0

package/dist/v1/Transacting.js

@@ -132,7 +132,8 @@ export class TransactingCapabilityImplementation {
                     feeTokenType: '',
                     coinSelection,
                     createOutput: (coin) => ledger.createShieldedCoinInfo(coin.type, coin.value),
-                    isCoinEqual: (a, b) => a.type === b.type && a.value === b.value,
+                    // Distinct coins can share a type and a value; only the nonce tells them apart.
+                    isCoinEqual: (a, b) => a.nonce === b.nonce,
                 });
                 return this.#prepareOffer(secretKeys, newState, fallibleBalanceRecipe, segment);
             },

package/dist/v1/WalletError.d.ts

@@ -4,7 +4,7 @@ export declare const WalletError: {
     other(err: unknown): WalletError;
     submission(err: unknown): WalletError;
 };
-export type WalletError = OtherWalletError | InsufficientFundsError | SubmissionError | AddressError | SyncWalletError | InvalidCoinHashesError | TransactingError | LedgerOps.LedgerError;
+export type WalletError = OtherWalletError | InsufficientFundsError | SubmissionError | AddressError | SyncWalletError | InvalidCoinHashesError | TransactingError | OutOfOrderSyncUpdateError | LedgerOps.LedgerError;
 declare const OtherWalletError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
     readonly _tag: "Wallet.Other";
 } & Readonly<A>;
@@ -71,4 +71,29 @@ export declare class TransactionHistoryError extends TransactionHistoryError_bas
     cause?: unknown;
 }> {
 }
+declare const OutOfOrderSyncUpdateError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "Wallet.OutOfOrderSyncUpdate";
+} & Readonly<A>;
+/**
+ * A batch of zswap ledger events was not in ascending id order: an event arrived at or below the one before it, or at
+ * or below the applied cursor.
+ *
+ * @remarks
+ *   Order is all the wallet can check: zswap events share one id sequence with dust and contract events in the indexer,
+ *   so gaps in the stream are normal and a skipped event is only ever caught by the ledger's own insertion check. The
+ *   whole batch is refused, nothing is applied and the cursor stays, so the running variant retries from the same
+ *   place.
+ * @example
+ *   ```ts
+ *   if (error._tag === 'Wallet.OutOfOrderSyncUpdate') console.warn(`expected above ${error.expected}, got ${error.received}`);
+ *   ```
+ */
+export declare class OutOfOrderSyncUpdateError extends OutOfOrderSyncUpdateError_base<{
+    readonly message: string;
+    /** The id the delivered event had to exceed: its predecessor in the batch, or the applied cursor. */
+    readonly expected: bigint;
+    /** The event id the source delivered instead. */
+    readonly received: bigint;
+}> {
+}
 export {};

package/dist/v1/WalletError.js

@@ -51,3 +51,19 @@ export class TransactingError extends Data.TaggedError('Wallet.Transacting') {
 }
 export class TransactionHistoryError extends Data.TaggedError('Wallet.TransactionHistory') {
 }
+/**
+ * A batch of zswap ledger events was not in ascending id order: an event arrived at or below the one before it, or at
+ * or below the applied cursor.
+ *
+ * @remarks
+ *   Order is all the wallet can check: zswap events share one id sequence with dust and contract events in the indexer,
+ *   so gaps in the stream are normal and a skipped event is only ever caught by the ledger's own insertion check. The
+ *   whole batch is refused, nothing is applied and the cursor stays, so the running variant retries from the same
+ *   place.
+ * @example
+ *   ```ts
+ *   if (error._tag === 'Wallet.OutOfOrderSyncUpdate') console.warn(`expected above ${error.expected}, got ${error.received}`);
+ *   ```
+ */
+export class OutOfOrderSyncUpdateError extends Data.TaggedError('Wallet.OutOfOrderSyncUpdate') {
+}

package/dist/v2/Sync.js

@@ -11,13 +11,13 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 import * as ledger from '@midnightntwrk/ledger-v9';
-import { Chunk, Duration, Effect, Either, identity, Option, ParseResult, pipe, Schedule, Schema, Stream, } from 'effect';
+import { Array as Arr, Chunk, Duration, Effect, Either, identity, Option, ParseResult, pipe, Schedule, Schema, Stream, } from 'effect';
 import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
 import { CoreWallet } from './CoreWallet.js';
 import { getLastBlock } from '@midnight-ntwrk/wallet-sdk-capabilities/simulation';
 import { BlockHash, ZswapEventTip, ZswapEvents } from '@midnight-ntwrk/wallet-sdk-indexer-client';
 import { ConnectionHelper, HttpQueryClient, WsSubscriptionClient, } from '@midnight-ntwrk/wallet-sdk-indexer-client/effect';
-import { SyncWalletError } from './WalletError.js';
+import { OutOfOrderSyncUpdateError, SyncWalletError } from './WalletError.js';
 import { WsURL } from '@midnight-ntwrk/wallet-sdk-utilities/networking';
 import { EitherOps } from '@midnight-ntwrk/wallet-sdk-utilities';
 /**
@@ -48,6 +48,26 @@ export const splitAtVersionBoundary = (items, versionOf, activeRange) => {
             : Option.some(ProtocolVersion.ProtocolVersion(BigInt(versionOf(signalling)))),
     };
 };
+/**
+ * Checks that freshly delivered events arrive in strictly ascending id order.
+ *
+ * @remarks
+ *   Order is all that can be checked, never contiguity: zswap events share one id sequence with dust and contract events
+ *   in the indexer, so gaps in a zswap stream are normal. A skipped commitment-inserting event is caught by the
+ *   ledger's own insertion check instead. An empty batch is trivially ordered.
+ * @param fresh The events left after the cursor filter, in source order.
+ * @param appliedIndex The highest event id already applied; the first fresh id must exceed it.
+ * @returns The batch unchanged, or the first id that fails to exceed its predecessor as an
+ *   {@link OutOfOrderSyncUpdateError}.
+ */
+const expectAscending = (fresh, appliedIndex) => pipe(Arr.zipWith(fresh, Arr.prepend(Arr.map(fresh, (item) => BigInt(item.id)), appliedIndex), (item, previous) => ({ item, previous })), Arr.findFirst(({ item, previous }) => BigInt(item.id) <= previous), Option.match({
+    onNone: () => Either.right(fresh),
+    onSome: ({ item, previous }) => Either.left(new OutOfOrderSyncUpdateError({
+        message: `Zswap event ${item.id} delivered at or below its predecessor ${previous}; batch refused, applied index stays at ${appliedIndex}`,
+        expected: previous,
+        received: BigInt(item.id),
+    })),
+}));
 /** Records a batch's observed protocol version on the state, monotonically. A batch that observed none is a no-op. */
 export const annotateVersion = (state, observedVersion) => Option.match(observedVersion, {
     onNone: () => state,
@@ -343,7 +363,14 @@ export const makeEventsSyncCapability = () => {
             // the batch tail even when the tail belongs to the next protocol version.
             const lastUpdate = wrappedUpdate.updates.at(-1);
             const highestRelevantWalletIndex = BigInt(lastUpdate.maxId);
-            const { applied, observedVersion } = splitAtVersionBoundary(freshUpdates, (update) => update.protocolVersion, activeRange);
+            // Refuse the whole batch: applying the sound prefix would move the cursor and hide the fault behind
+            // `isConnected: true`. State and cursor stay untouched, so the retry re-fetches the same range; a transient
+            // reorder heals, a persistent one fails visibly.
+            //
+            // `SyncCapability.applyUpdate` has no typed error channel, so throwing preserves its public tuple-returning API;
+            // `RunningV2Variant` catches this at the capability boundary. See #572 for the planned `Either`-based API.
+            const orderedUpdates = Either.getOrThrowWith(expectAscending(freshUpdates, appliedIndex), identity);
+            const { applied, observedVersion } = splitAtVersionBoundary(orderedUpdates, (update) => update.protocolVersion, activeRange);
             // Read here and nowhere earlier: `applied` is exactly the slice this variant owns, so nothing outside its
             // activation range — nor anything below its cursor — is ever handed to this ledger version's deserializer.
             const [newState, newChanges] = applied.length === 0

package/dist/v2/Transacting.js

@@ -132,7 +132,8 @@ export class TransactingCapabilityImplementation {
                     feeTokenType: '',
                     coinSelection,
                     createOutput: (coin) => ledger.createShieldedCoinInfo(coin.type, coin.value),
-                    isCoinEqual: (a, b) => a.type === b.type && a.value === b.value,
+                    // Distinct coins can share a type and a value; only the nonce tells them apart.
+                    isCoinEqual: (a, b) => a.nonce === b.nonce,
                 });
                 return this.#prepareOffer(secretKeys, newState, fallibleBalanceRecipe, segment);
             },

package/dist/v2/WalletError.d.ts

@@ -4,7 +4,7 @@ export declare const WalletError: {
     other(err: unknown): WalletError;
     submission(err: unknown): WalletError;
 };
-export type WalletError = OtherWalletError | InsufficientFundsError | SubmissionError | AddressError | SyncWalletError | InvalidCoinHashesError | TransactingError | LedgerOps.LedgerError;
+export type WalletError = OtherWalletError | InsufficientFundsError | SubmissionError | AddressError | SyncWalletError | InvalidCoinHashesError | TransactingError | OutOfOrderSyncUpdateError | LedgerOps.LedgerError;
 declare const OtherWalletError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
     readonly _tag: "Wallet.Other";
 } & Readonly<A>;
@@ -71,4 +71,29 @@ export declare class TransactionHistoryError extends TransactionHistoryError_bas
     cause?: unknown;
 }> {
 }
+declare const OutOfOrderSyncUpdateError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "Wallet.OutOfOrderSyncUpdate";
+} & Readonly<A>;
+/**
+ * A batch of zswap ledger events was not in ascending id order: an event arrived at or below the one before it, or at
+ * or below the applied cursor.
+ *
+ * @remarks
+ *   Order is all the wallet can check: zswap events share one id sequence with dust and contract events in the indexer,
+ *   so gaps in the stream are normal and a skipped event is only ever caught by the ledger's own insertion check. The
+ *   whole batch is refused, nothing is applied and the cursor stays, so the running variant retries from the same
+ *   place.
+ * @example
+ *   ```ts
+ *   if (error._tag === 'Wallet.OutOfOrderSyncUpdate') console.warn(`expected above ${error.expected}, got ${error.received}`);
+ *   ```
+ */
+export declare class OutOfOrderSyncUpdateError extends OutOfOrderSyncUpdateError_base<{
+    readonly message: string;
+    /** The id the delivered event had to exceed: its predecessor in the batch, or the applied cursor. */
+    readonly expected: bigint;
+    /** The event id the source delivered instead. */
+    readonly received: bigint;
+}> {
+}
 export {};

package/dist/v2/WalletError.js

@@ -51,3 +51,19 @@ export class TransactingError extends Data.TaggedError('Wallet.Transacting') {
 }
 export class TransactionHistoryError extends Data.TaggedError('Wallet.TransactionHistory') {
 }
+/**
+ * A batch of zswap ledger events was not in ascending id order: an event arrived at or below the one before it, or at
+ * or below the applied cursor.
+ *
+ * @remarks
+ *   Order is all the wallet can check: zswap events share one id sequence with dust and contract events in the indexer,
+ *   so gaps in the stream are normal and a skipped event is only ever caught by the ledger's own insertion check. The
+ *   whole batch is refused, nothing is applied and the cursor stays, so the running variant retries from the same
+ *   place.
+ * @example
+ *   ```ts
+ *   if (error._tag === 'Wallet.OutOfOrderSyncUpdate') console.warn(`expected above ${error.expected}, got ${error.received}`);
+ *   ```
+ */
+export class OutOfOrderSyncUpdateError extends Data.TaggedError('Wallet.OutOfOrderSyncUpdate') {
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midnight-ntwrk/wallet-sdk-shielded",
-  "version": "4.0.0-beta.3",
+  "version": "4.0.0-beta.4",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -35,12 +35,12 @@
   },
   "dependencies": {
     "@midnight-ntwrk/ledger-v8": "^8.1.0",
-    "@midnightntwrk/ledger-v9": "1.0.0-rc.4",
-    "@midnight-ntwrk/wallet-sdk-abstractions": "3.0.0-beta.1",
-    "@midnight-ntwrk/wallet-sdk-address-format": "4.0.0-beta.3",
-    "@midnight-ntwrk/wallet-sdk-capabilities": "4.0.0-beta.3",
+    "@midnightntwrk/ledger-v9": "1.0.0-rc.5",
+    "@midnight-ntwrk/wallet-sdk-abstractions": "3.0.0-beta.2",
+    "@midnight-ntwrk/wallet-sdk-address-format": "4.0.0-beta.4",
+    "@midnight-ntwrk/wallet-sdk-capabilities": "4.0.0-beta.4",
     "@midnight-ntwrk/wallet-sdk-indexer-client": "2.0.0-beta.2",
-    "@midnight-ntwrk/wallet-sdk-runtime": "1.1.0-beta.1",
+    "@midnight-ntwrk/wallet-sdk-runtime": "1.1.0-beta.2",
     "@midnight-ntwrk/wallet-sdk-utilities": "1.2.2-beta.0",
     "effect": "^3.19.19",
     "rxjs": "^7.8.2"