@midnightntwrk/wallet-sdk-shielded 4.0.0-beta.2 → 4.0.0-beta.3

package/dist/v2/RunningV2Variant.js

@@ -0,0 +1,127 @@
+import { Effect, pipe, Scope, Stream, SubscriptionRef, Schedule, Duration, Sink, Console } from 'effect';
+import { ProtocolVersion } from '@midnightntwrk/wallet-sdk-abstractions';
+import { StateChange, VersionChangeType, } from '@midnightntwrk/wallet-sdk-runtime/abstractions';
+import { EitherOps } from '@midnightntwrk/wallet-sdk-utilities';
+import { OtherWalletError } from './WalletError.js';
+const progress = (state) => {
+    const appliedIndex = state.progress?.appliedIndex ?? 0n;
+    const highestRelevantWalletIndex = state.progress?.highestRelevantWalletIndex ?? 0n;
+    const highestIndex = state.progress?.highestIndex ?? 0n;
+    const highestRelevantIndex = state.progress?.highestRelevantIndex ?? 0n;
+    const sourceGap = highestIndex - highestRelevantIndex;
+    const applyGap = highestRelevantWalletIndex - appliedIndex;
+    return [StateChange.ProgressUpdate({ sourceGap, applyGap })];
+};
+/**
+ * Reports the protocol version a state observation implies, if any.
+ *
+ * @remarks
+ *   Two situations call for a signal. The ordinary one is a transition: sync annotated the state with a version it did
+ *   not have before, and the runtime decides whether that is a re-annotation inside this variant's range or a hand-over
+ *   to the next one.
+ *
+ *   The other is a state that arrives already outside this variant's range — a snapshot serialized in the window between
+ *   the annotation and the migration it should have caused, or one written by an older protocol version entirely.
+ *   Nothing further will change that value, so waiting for a transition would strand the wallet on a version it does
+ *   not own. Emitting on sight heals it.
+ */
+const protocolVersionChange = (previous, current, isInitial, activationRange) => {
+    const transitioned = previous.protocolVersion != current.protocolVersion;
+    const strandedOutsideRange = isInitial && !ProtocolVersion.withinRange(current.protocolVersion, activationRange);
+    return transitioned || strandedOutsideRange
+        ? [
+            StateChange.VersionChange({
+                change: VersionChangeType.Version({
+                    version: ProtocolVersion.ProtocolVersion(current.protocolVersion),
+                }),
+            }),
+        ]
+        : [];
+};
+export const V2Tag = Symbol('V2');
+export class RunningV2Variant {
+    __polyTag__ = V2Tag;
+    #scope;
+    #context;
+    #v2Context;
+    // Variant-wide cap on concurrent tx-history lookups. Each sync batch forks its own fan-out fiber, so a per-batch
+    // `concurrency` limit alone would let in-flight indexer queries grow with the number of live batches while their
+    // lookups retry through the indexer-lag window. Every lookup acquires a permit here, making the cap global.
+    #txHistoryPermits = Effect.makeSemaphore(8).pipe(Effect.runSync);
+    state;
+    constructor(scope, context, v2Context) {
+        this.#scope = scope;
+        this.#context = context;
+        this.#v2Context = v2Context;
+        this.state = Stream.fromEffect(context.stateRef.get).pipe(Stream.flatMap((initialState) => context.stateRef.changes.pipe(
+        // The accumulator carries the "have we seen anything yet" flag alongside the previous state: the first
+        // observation is the only one that can be a restored state nobody has inspected against this variant's
+        // range yet, and `SubscriptionRef.changes` replays the current value, so it is exactly this element.
+        Stream.mapAccum({ previous: initialState, isInitial: true }, (seen, current) => [{ previous: current, isInitial: false }, [seen.previous, current, seen.isInitial]]))), Stream.mapConcat(([previous, current, isInitial]) => {
+            // TODO: emit progress only upon actual change
+            return [
+                StateChange.State({ state: current }),
+                ...progress(current),
+                ...protocolVersionChange(previous, current, isInitial, context.activationRange),
+            ];
+        }));
+    }
+    startSyncInBackground(startAux) {
+        return this.startSync(startAux).pipe(Stream.runScoped(Sink.drain), Effect.forkScoped, Effect.provideService(Scope.Scope, this.#scope));
+    }
+    startSync(startAux) {
+        return pipe(SubscriptionRef.get(this.#context.stateRef), Stream.fromEffect, Stream.flatMap((state) => this.#v2Context.syncService.updates(state, startAux)), Stream.mapEffect((update) => SubscriptionRef.modifyEffect(this.#context.stateRef, (state) => Effect.try({
+            try: () => {
+                const [newState, changesResult] = this.#v2Context.syncCapability.applyUpdate(state, update, this.#context.activationRange);
+                return [changesResult, newState];
+            },
+            catch: (err) => new OtherWalletError({
+                message: 'Error while applying sync update',
+                cause: err,
+            }),
+        })).pipe(Effect.flatMap(({ changes, protocolVersion }) => 
+        // Skip the tx-history fork entirely when there are no changes.
+        // Forking unconditionally allocates a fiber per apply call (one
+        // for every batch the sync emits, even the all-progress ones),
+        // which adds up fast during catch-up.
+        changes.length === 0
+            ? Effect.void
+            : pipe(Effect.forEach(changes, (change) => pipe(this.#txHistoryPermits.withPermits(1)(pipe(this.#v2Context.transactionHistoryService.getTransactionDetails(change.source), Effect.flatMap((metadata) => this.#v2Context.transactionHistoryService.put(change, metadata, protocolVersion)))), Effect.catchAllCause((cause) => 
+            // A sustained indexer outage (longer than getTransactionDetails' retry window) still lands
+            // here. applyUpdate has already advanced appliedIndex, so this change.source won't be
+            // re-processed — the shielded section is permanently lost. Surface that as a structured
+            // error carrying the tx hash, not a silent Console.error defect.
+            Effect.logError(cause, `Failed to record shielded tx-history section for ${change.source}`))), 
+            // `concurrency` only bounds fiber creation within this one batch; the real cap on simultaneous
+            // indexer queries is the variant-wide semaphore acquired around each lookup above.
+            { discard: true, concurrency: 8 }), Effect.forkScoped)), Effect.provideService(Scope.Scope, this.#scope))), Stream.tapError((error) => Console.error(error)), Stream.retry(pipe(Schedule.exponential(Duration.seconds(1), 2), Schedule.map((delay) => {
+            const maxDelay = Duration.minutes(2);
+            const jitter = Duration.millis(Math.floor(Math.random() * 1000));
+            const delayWithJitter = Duration.toMillis(delay) + Duration.toMillis(jitter);
+            return Duration.millis(Math.min(delayWithJitter, Duration.toMillis(maxDelay)));
+        }))));
+    }
+    balanceTransaction(secretKeys, tx) {
+        return SubscriptionRef.modifyEffect(this.#context.stateRef, (state) => {
+            return pipe(this.#v2Context.transactingCapability.balanceTransaction(secretKeys, state, tx), EitherOps.toEffect);
+        });
+    }
+    transferTransaction(secretKeys, outputs) {
+        return SubscriptionRef.modifyEffect(this.#context.stateRef, (state) => {
+            return pipe(this.#v2Context.transactingCapability.makeTransfer(secretKeys, state, outputs), EitherOps.toEffect);
+        });
+    }
+    initSwap(secretKeys, desiredInputs, desiredOutputs) {
+        return SubscriptionRef.modifyEffect(this.#context.stateRef, (state) => {
+            return pipe(this.#v2Context.transactingCapability.initSwap(secretKeys, state, desiredInputs, desiredOutputs), EitherOps.toEffect);
+        });
+    }
+    revertTransaction(transaction) {
+        return SubscriptionRef.updateEffect(this.#context.stateRef, (state) => {
+            return pipe(this.#v2Context.transactingCapability.revertTransaction(state, transaction), EitherOps.toEffect);
+        });
+    }
+    serializeState(state) {
+        return this.#v2Context.serializationCapability.serialize(state);
+    }
+}

package/dist/v2/Serialization.d.ts

@@ -0,0 +1,12 @@
+import { Either } from 'effect';
+import { WalletError } from './WalletError.js';
+import { CoreWallet } from './CoreWallet.js';
+import { type NetworkId } from '@midnightntwrk/wallet-sdk-abstractions';
+export type SerializationCapability<TWallet, TAux, TSerialized> = {
+    serialize(wallet: TWallet): TSerialized;
+    deserialize(aux: TAux, data: TSerialized): Either.Either<TWallet, WalletError>;
+};
+export type DefaultSerializationConfiguration = {
+    networkId: NetworkId.NetworkId;
+};
+export declare const makeDefaultV2SerializationCapability: () => SerializationCapability<CoreWallet, null, string>;

package/dist/v2/Serialization.js

@@ -0,0 +1,93 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// 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.
+import { Effect, ParseResult, Either, pipe, Schema } from 'effect';
+import { WalletError } from './WalletError.js';
+import * as ledger from '@midnightntwrk/ledger-v9';
+import { CoreWallet } from './CoreWallet.js';
+const StateSchema = Schema.declare((input) => input instanceof ledger.ZswapLocalState).annotations({
+    identifier: 'ledger.ZswapLocalState',
+});
+const Uint8ArraySchema = Schema.declare((input) => input instanceof Uint8Array).annotations({
+    identifier: 'Uint8Array',
+});
+const StateFromUInt8Array = () => Schema.asSchema(Schema.transformOrFail(Uint8ArraySchema, StateSchema, {
+    encode: (state) => {
+        return Effect.try({
+            try: () => {
+                return state.serialize();
+            },
+            catch: (err) => {
+                return new ParseResult.Unexpected(err, 'Could not serialize local state');
+            },
+        });
+    },
+    decode: (bytes) => Effect.try({
+        try: () => ledger.ZswapLocalState.deserialize(bytes),
+        catch: (err) => {
+            return new ParseResult.Unexpected(err, 'Could not deserialize local state');
+        },
+    }),
+}));
+const HexedState = () => pipe(Schema.Uint8ArrayFromHex, Schema.compose(StateFromUInt8Array()));
+export const makeDefaultV2SerializationCapability = () => {
+    const SnapshotSchema = Schema.Struct({
+        publicKeys: Schema.Struct({
+            coinPublicKey: Schema.String,
+            encryptionPublicKey: Schema.String,
+        }),
+        state: HexedState(),
+        protocolVersion: Schema.BigInt,
+        offset: Schema.optional(Schema.BigInt),
+        networkId: Schema.String,
+        coinHashes: Schema.Record({
+            key: Schema.String,
+            value: Schema.Struct({ nullifier: Schema.String, commitment: Schema.String }),
+        }),
+        // Set only on a wallet caught between a cross-ledger migration and its first sync update: its state crossed the
+        // boundary as bytes, but the hashes over that state need secret keys nobody here has (see
+        // `CoreWallet.coinHashesPending`). Optional twice over — a wallet that is not mid-crossing has nothing to declare,
+        // and snapshots written before the field existed must keep decoding unchanged.
+        coinHashesPending: Schema.optional(Schema.Literal(true)),
+    });
+    return {
+        serialize: (wallet) => {
+            const buildSnapshot = (w) => ({
+                publicKeys: w.publicKeys,
+                state: w.state,
+                protocolVersion: w.protocolVersion,
+                networkId: w.networkId,
+                offset: w.progress?.appliedIndex,
+                coinHashes: w.coinHashes,
+                ...(w.coinHashesPending !== undefined ? { coinHashesPending: w.coinHashesPending } : {}),
+            });
+            return pipe(wallet, buildSnapshot, Schema.encodeSync(SnapshotSchema), JSON.stringify);
+        },
+        deserialize: (aux, serialized) => {
+            return pipe(serialized, Schema.decodeUnknownEither(Schema.parseJson(SnapshotSchema)), Either.mapLeft((err) => WalletError.other(err)), Either.flatMap((snapshot) => {
+                const progress = {
+                    appliedIndex: snapshot.offset ?? 0n,
+                    highestRelevantWalletIndex: 0n,
+                    highestIndex: 0n,
+                    highestRelevantIndex: 0n,
+                    isConnected: false,
+                };
+                // A snapshot that declares its hashes pending is the one shape the validation below would wrongly refuse:
+                // its state is full and its hash map is empty by construction, because the migration that wrote it had no
+                // secret keys. Every other snapshot goes on being checked against its own state.
+                return snapshot.coinHashesPending === true
+                    ? Either.right(CoreWallet.restoreWithPendingCoinHashes(snapshot.publicKeys, snapshot.state, progress, snapshot.protocolVersion, snapshot.networkId))
+                    : CoreWallet.restoreWithCoinHashes(snapshot.publicKeys, snapshot.state, snapshot.coinHashes, progress, snapshot.protocolVersion, snapshot.networkId);
+            }));
+        },
+    };
+};

package/dist/v2/Sync.d.ts

@@ -0,0 +1,208 @@
+import * as ledger from '@midnightntwrk/ledger-v9';
+import { Option, Schema, type Scope, Stream } from 'effect';
+import { ProtocolVersion } from '@midnightntwrk/wallet-sdk-abstractions';
+import { CoreWallet } from './CoreWallet.js';
+import { type Simulator, type SimulatorState } from '@midnightntwrk/wallet-sdk-capabilities/simulation';
+import { type WalletError } from './WalletError.js';
+import { type TransactionHistoryService } from './TransactionHistory.js';
+export interface SyncService<TState, TStartAux, TUpdate> {
+    updates: (state: TState, auxData: TStartAux) => Stream.Stream<TUpdate, WalletError, Scope.Scope>;
+}
+export type ChangesResult = {
+    readonly changes: ledger.ZswapStateChanges[];
+    readonly protocolVersion: number;
+};
+export interface SyncCapability<TState, TUpdate, TResult> {
+    /**
+     * Folds a sync update into the wallet state.
+     *
+     * @param state The state to fold into.
+     * @param update The update to apply.
+     * @param activeRange The half-open protocol version range the running variant owns. Anything the source reports at or
+     *   beyond its end belongs to a later variant and must be left unapplied for that variant to fetch.
+     */
+    applyUpdate: (state: TState, update: TUpdate, activeRange: ProtocolVersion.ProtocolVersion.Range) => [TState, TResult];
+}
+/** The result of splitting a batch of version-tagged items at a variant's activation boundary. */
+export type BoundarySplit<T> = {
+    /** The leading items this variant owns, in source order. */
+    readonly applied: readonly T[];
+    /** The trailing items belonging to a later protocol version, left for the next variant to re-fetch. */
+    readonly deferred: readonly T[];
+    /**
+     * The protocol version to record on the state: the first deferred item's version when there is one — that is the
+     * signal that triggers migration — otherwise the last applied item's version. `None` for an empty batch.
+     */
+    readonly observedVersion: Option.Option<ProtocolVersion.ProtocolVersion>;
+};
+/**
+ * Splits a batch of version-tagged items at the end of a variant's activation range.
+ *
+ * @remarks
+ *   The split is positional, not a filter: everything from the first out-of-range item onwards is deferred, even if a
+ *   later item reports an in-range version again. A batch is a contiguous slice of one timeline, so applying past a
+ *   boundary and then resuming behind it would leave a hole no cursor can describe.
+ *
+ *   This is the one place the boundary rule lives; both the indexer capability (per event) and the simulator capability
+ *   (per block) go through it, so they cannot drift apart.
+ * @param items The batch, in source order.
+ * @param versionOf Reads the protocol version an item was reported at.
+ * @param activeRange The variant's half-open activation range.
+ * @returns The applied/deferred split and the version to record.
+ */
+export declare const splitAtVersionBoundary: <T>(items: readonly T[], versionOf: (item: T) => number, activeRange: ProtocolVersion.ProtocolVersion.Range) => BoundarySplit<T>;
+/** Records a batch's observed protocol version on the state, monotonically. A batch that observed none is a no-op. */
+export declare const annotateVersion: (state: CoreWallet, observedVersion: Option.Option<ProtocolVersion.ProtocolVersion>) => CoreWallet;
+export type IndexerClientConnection = {
+    indexerHttpUrl: string;
+    indexerWsUrl?: string;
+    keepAlive?: number;
+    /** Cap on the in-flight event queue between the WebSocket push and the apply loop. Default: 10000. */
+    bufferSize?: number;
+    /** In-flight count at which the disposed WS subscription is reopened. Default: 100. */
+    resumeThreshold?: number;
+};
+export type BatchUpdatesConfig = {
+    /**
+     * Maximum number of events to collect into a single batch before emitting.
+     *
+     * @default 10
+     */
+    readonly size?: number;
+    /**
+     * Maximum time in milliseconds to wait for a full batch before emitting a partial one. Controls the `groupedWithin`
+     * timeout — lower values mean more responsive (but smaller) batches when events arrive slowly.
+     *
+     * @default 1
+     */
+    readonly timeout?: number;
+    /**
+     * Minimum delay in milliseconds injected between consecutive batches. Prevents the sync stream from saturating
+     * downstream consumers when many events are available at once. Set to 0 to disable spacing entirely.
+     *
+     * @default 4
+     */
+    readonly spacing?: number;
+};
+/**
+ * How often the sync source re-asks the chain which protocol version it is on.
+ *
+ * @remarks
+ *   The event subscription this source reads has no progress arm: it says nothing at all when there is nothing to say. A
+ *   wallet therefore observes the chain's protocol version only through events, and on a chain that crosses a protocol
+ *   boundary and then produces no shielded traffic it observes no version at all — it stays on the variant it was
+ *   running, and everything built through it stays routed to that variant's ledger. Asking on a timer is what closes
+ *   that, and the cost of asking is one small query per interval on a chain that has not moved.
+ */
+export type VersionWatchConfig = {
+    /**
+     * Milliseconds between checks. Zero or less turns the watcher off entirely, which is what a source driving a wallet
+     * from something other than a live chain wants.
+     *
+     * @default 30000
+     */
+    readonly intervalMs?: number;
+};
+export type DefaultSyncConfiguration = {
+    indexerClientConnection: IndexerClientConnection;
+    batchUpdates?: BatchUpdatesConfig;
+    versionWatch?: VersionWatchConfig;
+};
+export type DefaultSyncContext = {
+    transactionHistoryService: TransactionHistoryService;
+};
+export type SecretKeysResource = <A>(cb: (keys: ledger.ZswapSecretKeys) => A) => A;
+export declare const SecretKeysResource: {
+    create: (secretKeys: ledger.ZswapSecretKeys) => SecretKeysResource;
+};
+/** A batch of the indexer's event timeline, still encoded. */
+export type EventsWalletSyncUpdate = {
+    _tag: 'Events';
+    updates: EventsSyncUpdate[];
+    secretKeys: ledger.ZswapSecretKeys;
+};
+/**
+ * What the chain says about itself when its timeline says nothing.
+ *
+ * @remarks
+ *   An observation, not a piece of the chain: it moves no cursor, inserts nothing and produces no changes. All it can do
+ *   is record a protocol version, which is enough, because recording one outside the running variant's activation range
+ *   is exactly what makes the runtime hand over.
+ *
+ *   `highestEventId` is what makes the record safe to make. Handing over parks the sync cursor where it stands, and the
+ *   variant that takes over re-fetches from there — so an event still unread below the source's tip would reach it as
+ *   bytes of the version that preceded it, which its ledger cannot deserialize, and which may in any case be carrying a
+ *   coin the crossed local state does not yet contain. The signal therefore travels with the far end of the source's
+ *   event timeline, so the capability can refuse it while anything remains unread. `null` means the source provably
+ *   holds no zswap event at all, which is the one case where nothing can be unread.
+ */
+export type VersionSignalSyncUpdate = Readonly<{
+    _tag: 'VersionSignal';
+    /** The protocol version the source's tip was reported under. */
+    version: number;
+    /** The highest event id the source holds, or `null` when it provably holds no event. */
+    highestEventId: number | null;
+}>;
+export declare const VersionSignalSyncUpdate: {
+    create: (version: number, highestEventId: number | null) => VersionSignalSyncUpdate;
+};
+/**
+ * What the indexer-backed sync source emits.
+ *
+ * @remarks
+ *   Ordinarily a batch of events; and, on a timer, what the chain says about its own version when its timeline says
+ *   nothing.
+ */
+export type WalletSyncUpdate = EventsWalletSyncUpdate | VersionSignalSyncUpdate;
+export declare const WalletSyncUpdate: {
+    create: (updates: EventsSyncUpdate[], secretKeys: ledger.ZswapSecretKeys) => EventsWalletSyncUpdate;
+};
+/**
+ * One event of the source's timeline, still encoded.
+ *
+ * @remarks
+ *   The event is carried as the source served it rather than as a `ledger.Event`, because whether this ledger version may
+ *   read it at all is not the source's question to answer. A batch spanning a protocol boundary carries events of the
+ *   version that follows this one, which this ledger version cannot deserialize — the serialization header names a
+ *   different version — and after a hand-over the inclusive cursor re-delivers an event of the version that preceded
+ *   it, which it equally cannot. Both are ordinary, and neither is an error: they belong to the variant either side.
+ *
+ *   So the bytes travel undecoded and only the capability, which knows the activation range, reads the ones it is about
+ *   to apply — see {@link readEvent}. Decoding here would fail the whole batch on an event nobody intended to apply.
+ */
+export declare const EventsSyncUpdate: Schema.TaggedStruct<"EventsSyncUpdate", {
+    id: typeof Schema.Number;
+    protocolVersion: typeof Schema.Number;
+    maxId: typeof Schema.Number;
+    raw: typeof Schema.String;
+}>;
+export type EventsSyncUpdate = Schema.Schema.Type<typeof EventsSyncUpdate>;
+/**
+ * Reads an event this variant is going to apply.
+ *
+ * @remarks
+ *   The counterpart of {@link EventsSyncUpdate} carrying its event encoded: a capability calls this on the batch prefix it
+ *   owns, and never on what it defers. Failure here is a genuine one — an event this variant claimed and cannot read —
+ *   and is raised rather than returned, because `SyncCapability.applyUpdate` is total in its own domain and the variant
+ *   already turns a throw from it into a typed synchronization error.
+ * @param update The update to read.
+ * @returns The event it carries.
+ * @throws ParseError if the bytes are not an event this ledger version can deserialize.
+ */
+export declare const readEvent: (update: EventsSyncUpdate) => ledger.Event;
+export declare const makeEventsSyncService: (config: DefaultSyncConfiguration) => SyncService<CoreWallet, ledger.ZswapSecretKeys, WalletSyncUpdate>;
+export declare const makeEventsSyncCapability: () => SyncCapability<CoreWallet, WalletSyncUpdate, ChangesResult>;
+export type SimulatorSyncConfiguration = {
+    simulator: Simulator;
+};
+/** What the simulator-backed sync source emits: the simulator's state, from which the pending blocks are read. */
+export type SimulatorSyncUpdate = {
+    _tag: 'Events';
+    update: SimulatorState;
+    secretKeys: ledger.ZswapSecretKeys;
+};
+export declare const SimulatorSyncUpdate: {
+    create: (update: SimulatorState, secretKeys: ledger.ZswapSecretKeys) => SimulatorSyncUpdate;
+};
+export declare const makeSimulatorSyncService: (config: SimulatorSyncConfiguration) => SyncService<CoreWallet, ledger.ZswapSecretKeys, SimulatorSyncUpdate>;
+export declare const makeSimulatorSyncCapability: () => SyncCapability<CoreWallet, SimulatorSyncUpdate, ChangesResult>;