@midnightntwrk/wallet-sdk-shielded 3.0.2

package/dist/v1/RunningV1Variant.d.ts

@@ -0,0 +1,40 @@
+import type * as ledger from '@midnight-ntwrk/ledger-v8';
+import { Effect, Scope, Stream } from 'effect';
+import { type WalletRuntimeError, type Variant, StateChange } from '@midnightntwrk/wallet-sdk-runtime/abstractions';
+import { type SerializationCapability } from './Serialization.js';
+import { type ChangesResult, type EventsSyncUpdate, type SyncCapability, type SyncService } from './Sync.js';
+import { type TransactingCapability, type TokenTransfer, type BalancingResult } from './Transacting.js';
+import { type WalletError } from './WalletError.js';
+import { type CoinsAndBalancesCapability } from './CoinsAndBalances.js';
+import { type KeysCapability } from './Keys.js';
+import { type CoinSelection } from '@midnightntwrk/wallet-sdk-capabilities';
+import { type CoreWallet } from './CoreWallet.js';
+import { type TransactionHistoryService } from './TransactionHistory.js';
+export declare namespace RunningV1Variant {
+    type Context<TSerialized, TSyncUpdate, TTransaction, TStartAux> = {
+        serializationCapability: SerializationCapability<CoreWallet, null, TSerialized>;
+        syncService: SyncService<CoreWallet, TStartAux, TSyncUpdate>;
+        syncCapability: SyncCapability<CoreWallet, TSyncUpdate, ChangesResult>;
+        transactingCapability: TransactingCapability<ledger.ZswapSecretKeys, CoreWallet, TTransaction>;
+        coinsAndBalancesCapability: CoinsAndBalancesCapability<CoreWallet>;
+        keysCapability: KeysCapability<CoreWallet>;
+        coinSelection: CoinSelection<ledger.QualifiedShieldedCoinInfo>;
+        transactionHistoryService: TransactionHistoryService;
+    };
+    type AnyContext = Context<any, any, any, any>;
+}
+export declare const V1Tag: unique symbol;
+export type DefaultRunningV1 = RunningV1Variant<string, EventsSyncUpdate, ledger.FinalizedTransaction, ledger.ZswapSecretKeys>;
+export declare class RunningV1Variant<TSerialized, TSyncUpdate, TTransaction, TStartAux> implements Variant.RunningVariant<typeof V1Tag, CoreWallet> {
+    #private;
+    readonly __polyTag__: typeof V1Tag;
+    readonly state: Stream.Stream<StateChange.StateChange<CoreWallet>, WalletRuntimeError>;
+    constructor(scope: Scope.Scope, context: Variant.VariantContext<CoreWallet>, v1Context: RunningV1Variant.Context<TSerialized, TSyncUpdate, TTransaction, TStartAux>);
+    startSyncInBackground(startAux: TStartAux): Effect.Effect<void>;
+    startSync(startAux: TStartAux): Stream.Stream<void, WalletError, Scope.Scope>;
+    balanceTransaction(secretKeys: ledger.ZswapSecretKeys, tx: ledger.Transaction<ledger.Signaturish, ledger.Proofish, ledger.Bindingish>): Effect.Effect<BalancingResult, WalletError>;
+    transferTransaction(secretKeys: ledger.ZswapSecretKeys, outputs: ReadonlyArray<TokenTransfer>): Effect.Effect<ledger.UnprovenTransaction, WalletError>;
+    initSwap(secretKeys: ledger.ZswapSecretKeys, desiredInputs: Record<ledger.RawTokenType, bigint>, desiredOutputs: ReadonlyArray<TokenTransfer>): Effect.Effect<ledger.UnprovenTransaction, WalletError>;
+    revertTransaction(transaction: ledger.Transaction<ledger.Signaturish, ledger.Proofish, ledger.Bindingish>): Effect.Effect<void, WalletError>;
+    serializeState(state: CoreWallet): TSerialized;
+}

package/dist/v1/RunningV1Variant.js

@@ -0,0 +1,98 @@
+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 })];
+};
+const protocolVersionChange = (previous, current) => {
+    return previous.protocolVersion != current.protocolVersion
+        ? [
+            StateChange.VersionChange({
+                change: VersionChangeType.Version({
+                    version: ProtocolVersion.ProtocolVersion(current.protocolVersion),
+                }),
+            }),
+        ]
+        : [];
+};
+export const V1Tag = Symbol('V1');
+export class RunningV1Variant {
+    __polyTag__ = V1Tag;
+    #scope;
+    #context;
+    #v1Context;
+    state;
+    constructor(scope, context, v1Context) {
+        this.#scope = scope;
+        this.#context = context;
+        this.#v1Context = v1Context;
+        this.state = Stream.fromEffect(context.stateRef.get).pipe(Stream.flatMap((initialState) => context.stateRef.changes.pipe(Stream.mapAccum(initialState, (previous, current) => {
+            return [current, [previous, current]];
+        }))), Stream.mapConcat(([previous, current]) => {
+            // TODO: emit progress only upon actual change
+            return [
+                StateChange.State({ state: current }),
+                ...progress(current),
+                ...protocolVersionChange(previous, current),
+            ];
+        }));
+    }
+    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.#v1Context.syncService.updates(state, startAux)), Stream.mapEffect((update) => SubscriptionRef.modifyEffect(this.#context.stateRef, (state) => Effect.try({
+            try: () => {
+                const [newState, changesResult] = this.#v1Context.syncCapability.applyUpdate(state, update);
+                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.#v1Context.transactionHistoryService.getTransactionDetails(change.source), Effect.flatMap((metadata) => this.#v1Context.transactionHistoryService.put(change, metadata, protocolVersion)), Effect.catchAllCause((cause) => Console.error('Error processing tx history metadata', cause))), { discard: true, concurrency: 'unbounded' }), 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.#v1Context.transactingCapability.balanceTransaction(secretKeys, state, tx), EitherOps.toEffect);
+        });
+    }
+    transferTransaction(secretKeys, outputs) {
+        return SubscriptionRef.modifyEffect(this.#context.stateRef, (state) => {
+            return pipe(this.#v1Context.transactingCapability.makeTransfer(secretKeys, state, outputs), EitherOps.toEffect);
+        });
+    }
+    initSwap(secretKeys, desiredInputs, desiredOutputs) {
+        return SubscriptionRef.modifyEffect(this.#context.stateRef, (state) => {
+            return pipe(this.#v1Context.transactingCapability.initSwap(secretKeys, state, desiredInputs, desiredOutputs), EitherOps.toEffect);
+        });
+    }
+    revertTransaction(transaction) {
+        return SubscriptionRef.updateEffect(this.#context.stateRef, (state) => {
+            return pipe(this.#v1Context.transactingCapability.revertTransaction(state, transaction), EitherOps.toEffect);
+        });
+    }
+    serializeState(state) {
+        return this.#v1Context.serializationCapability.serialize(state);
+    }
+}

package/dist/v1/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 makeDefaultV1SerializationCapability: () => SerializationCapability<CoreWallet, null, string>;

package/dist/v1/Serialization.js

@@ -0,0 +1,79 @@
+// 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 '@midnight-ntwrk/ledger-v8';
+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 makeDefaultV1SerializationCapability = () => {
+    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 }),
+        }),
+    });
+    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,
+            });
+            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) => CoreWallet.restoreWithCoinHashes(snapshot.publicKeys, snapshot.state, snapshot.coinHashes, {
+                appliedIndex: snapshot.offset ?? 0n,
+                highestRelevantWalletIndex: 0n,
+                highestIndex: 0n,
+                highestRelevantIndex: 0n,
+                isConnected: false,
+            }, snapshot.protocolVersion, snapshot.networkId)));
+        },
+    };
+};

package/dist/v1/Sync.d.ts

@@ -0,0 +1,83 @@
+import * as ledger from '@midnight-ntwrk/ledger-v8';
+import { Schema, type Scope, Stream } from 'effect';
+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> {
+    applyUpdate: (state: TState, update: TUpdate) => [TState, TResult];
+}
+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;
+};
+export type DefaultSyncConfiguration = {
+    indexerClientConnection: IndexerClientConnection;
+    batchUpdates?: BatchUpdatesConfig;
+};
+export type DefaultSyncContext = {
+    transactionHistoryService: TransactionHistoryService;
+};
+export type SecretKeysResource = <A>(cb: (keys: ledger.ZswapSecretKeys) => A) => A;
+export declare const SecretKeysResource: {
+    create: (secretKeys: ledger.ZswapSecretKeys) => SecretKeysResource;
+};
+export type WalletSyncUpdate = {
+    updates: EventsSyncUpdate[];
+    secretKeys: ledger.ZswapSecretKeys;
+};
+export declare const WalletSyncUpdate: {
+    create: (updates: EventsSyncUpdate[], secretKeys: ledger.ZswapSecretKeys) => WalletSyncUpdate;
+};
+export declare const EventsSyncUpdate: Schema.TaggedStruct<"EventsSyncUpdate", {
+    id: typeof Schema.Number;
+    protocolVersion: typeof Schema.Number;
+    maxId: typeof Schema.Number;
+    event: Schema.declare<ledger.Event, ledger.Event, readonly [], never>;
+}>;
+export type EventsSyncUpdate = Schema.Schema.Type<typeof EventsSyncUpdate>;
+export declare const makeEventsSyncService: (config: DefaultSyncConfiguration) => SyncService<CoreWallet, ledger.ZswapSecretKeys, WalletSyncUpdate>;
+export declare const makeEventsSyncCapability: () => SyncCapability<CoreWallet, WalletSyncUpdate, ChangesResult>;
+export type SimulatorSyncConfiguration = {
+    simulator: Simulator;
+};
+export type SimulatorSyncUpdate = {
+    update: SimulatorState;
+    secretKeys: ledger.ZswapSecretKeys;
+};
+export declare const makeSimulatorSyncService: (config: SimulatorSyncConfiguration) => SyncService<CoreWallet, ledger.ZswapSecretKeys, SimulatorSyncUpdate>;
+export declare const makeSimulatorSyncCapability: () => SyncCapability<CoreWallet, SimulatorSyncUpdate, ChangesResult>;

package/dist/v1/Sync.js

@@ -0,0 +1,206 @@
+// 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 * as ledger from '@midnight-ntwrk/ledger-v8';
+import { Chunk, Duration, Effect, Either, ParseResult, pipe, Schedule, Schema, Stream } from 'effect';
+import { CoreWallet } from './CoreWallet.js';
+import { getLastBlock, getBlockEventsFrom, } from '@midnightntwrk/wallet-sdk-capabilities/simulation';
+import { ZswapEvents } from '@midnightntwrk/wallet-sdk-indexer-client';
+import { ConnectionHelper, WsSubscriptionClient } from '@midnightntwrk/wallet-sdk-indexer-client/effect';
+import { SyncWalletError } from './WalletError.js';
+import { WsURL } from '@midnightntwrk/wallet-sdk-utilities/networking';
+import { EitherOps } from '@midnightntwrk/wallet-sdk-utilities';
+const Uint8ArraySchema = Schema.declare((input) => input instanceof Uint8Array).annotations({
+    identifier: 'Uint8Array',
+});
+export const SecretKeysResource = {
+    create: (secretKeys) => {
+        return (cb) => {
+            const result = cb(secretKeys);
+            secretKeys.clear();
+            return result;
+        };
+    },
+};
+export const WalletSyncUpdate = {
+    create: (updates, secretKeys) => {
+        return {
+            updates,
+            secretKeys,
+        };
+    },
+};
+const LedgerEventSchema = Schema.declare((input) => input instanceof ledger.Event).annotations({
+    identifier: 'ledger.Event',
+});
+const LedgerEventFromUint8Array = Schema.transformOrFail(Uint8ArraySchema, LedgerEventSchema, {
+    encode: (event) => Effect.try({
+        try: () => event.serialize(),
+        catch: (error) => new ParseResult.Unexpected(error, 'Could not serialize ledger event'),
+    }),
+    decode: (bytes) => Effect.try({
+        try: () => ledger.Event.deserialize(bytes),
+        catch: (error) => new ParseResult.Unexpected(error, 'Could not deserialize ledger event'),
+    }),
+});
+const HexedLedgerEvent = pipe(Schema.Uint8ArrayFromHex, Schema.compose(LedgerEventFromUint8Array));
+const EventsSyncUpdatePayload = Schema.Struct({
+    id: Schema.Number,
+    raw: Schema.String,
+    protocolVersion: Schema.Number,
+    maxId: Schema.Number,
+});
+export const EventsSyncUpdate = Schema.TaggedStruct('EventsSyncUpdate', {
+    id: Schema.Number,
+    protocolVersion: Schema.Number,
+    maxId: Schema.Number,
+    event: LedgerEventSchema,
+});
+const EventsSyncUpdateFromPayload = Schema.transformOrFail(EventsSyncUpdatePayload, EventsSyncUpdate, {
+    decode: (input) => pipe(Schema.decodeUnknownEither(HexedLedgerEvent)(input.raw), Either.map((event) => ({
+        _tag: 'EventsSyncUpdate',
+        id: input.id,
+        protocolVersion: input.protocolVersion,
+        maxId: input.maxId,
+        event,
+    })), Either.mapLeft((error) => new ParseResult.Unexpected(error, 'Failed to decode ledger event payload')), EitherOps.toEffect),
+    encode: (output) => pipe(Schema.encodeEither(HexedLedgerEvent)(output.event), Either.map((raw) => ({
+        id: output.id,
+        raw,
+        protocolVersion: output.protocolVersion,
+        maxId: output.maxId,
+    })), Either.mapLeft((error) => new ParseResult.Unexpected(error, 'Failed to encode ledger event payload')), EitherOps.toEffect),
+});
+export const makeEventsSyncService = (config) => {
+    return {
+        updates: (state, secretKeys) => {
+            const { indexerClientConnection } = config;
+            const webSocketUrlResult = ConnectionHelper.createWebSocketUrl(indexerClientConnection.indexerHttpUrl, indexerClientConnection.indexerWsUrl);
+            if (Either.isLeft(webSocketUrlResult)) {
+                return Stream.fail(new SyncWalletError(new Error(`Could not derive WebSocket URL from indexer HTTP URL: ${webSocketUrlResult.left.message}`)));
+            }
+            const indexerWsUrlResult = WsURL.make(webSocketUrlResult.right);
+            if (Either.isLeft(indexerWsUrlResult)) {
+                return Stream.fail(new SyncWalletError(new Error(`Invalid indexer WS URL: ${indexerWsUrlResult.left.message}`)));
+            }
+            const indexerWsUrl = indexerWsUrlResult.right;
+            const appliedIndex = state.progress?.appliedIndex ?? 0n;
+            // The boundary is load-bearing, not waste: this subscription emits only events (no tip/progress
+            // sentinel), and `isConnected`/the tip (`maxId`) are set only when an event is received. So the
+            // cursor must stay `<= appliedIndex` — never `appliedIndex + 1`. Requesting one event later would
+            // deliver nothing to a wallet already at the tip, so `applyUpdate` would never run and sync would
+            // hang.
+            //
+            // A fresh wallet has `appliedIndex === 0n` (the "nothing applied yet" sentinel), so `resumeFrom`
+            // is `-1n` and the `variables` mapping below opens the subscription with no `id` — the indexer
+            // streams from the very start. A restored wallet has `appliedIndex >= 1`, so `resumeFrom` is
+            // `appliedIndex - 1` and the inclusive cursor re-delivers the boundary event.
+            const resumeFrom = appliedIndex - 1n;
+            const batchSize = config.batchUpdates?.size ?? 10;
+            const batchTimeout = Duration.millis(config.batchUpdates?.timeout ?? 1);
+            const batchSpacing = config.batchUpdates?.spacing ?? 4;
+            const bufferSize = config.indexerClientConnection.bufferSize ?? 10000;
+            const resumeThreshold = config.indexerClientConnection.resumeThreshold ?? 100;
+            const eventsStream = pipe(
+            // Backpressure caps the in-flight queue between the WS push and the
+            // apply loop. Without it the JS heap grows linearly with catch-up
+            // depth, since `Stream.asyncPush({ bufferSize: 'unbounded' })`
+            // buffers every event the indexer pushes regardless of apply rate.
+            ZswapEvents.runWithBackpressure({
+                bufferSize,
+                resumeThreshold,
+                from: resumeFrom,
+                // `resumeFrom < 0n` means a fresh wallet: send no `id` so the indexer streams from the very
+                // start, rather than relying on `id: 0` sorting below the first real event id.
+                variables: (cursor) => ({ id: cursor < 0n ? null : Number(cursor) }),
+                key: (r) => BigInt(r.zswapLedgerEvents.id),
+            }), Stream.provideLayer(WsSubscriptionClient.layer({ url: indexerWsUrl, keepAlive: config.indexerClientConnection.keepAlive })), Stream.mapError((error) => new SyncWalletError(error)), Stream.mapEffect((subscription) => pipe(subscription.zswapLedgerEvents, Schema.decodeUnknownEither(EventsSyncUpdateFromPayload), Either.mapLeft((err) => new SyncWalletError(err)), EitherOps.toEffect)), Stream.groupedWithin(batchSize, batchTimeout), Stream.map(Chunk.toArray), Stream.map((data) => WalletSyncUpdate.create(data, secretKeys)));
+            return batchSpacing > 0
+                ? Stream.schedule(eventsStream, Schedule.spaced(Duration.millis(batchSpacing)))
+                : eventsStream;
+        },
+    };
+};
+export const makeEventsSyncCapability = () => {
+    return {
+        applyUpdate: (state, wrappedUpdate) => {
+            if (wrappedUpdate.updates.length === 0) {
+                return [state, { changes: [], protocolVersion: Number(state.protocolVersion) }];
+            }
+            // The subscription resumes at the last-applied index and its cursor is inclusive, so the
+            // boundary event (id === appliedIndex) is re-delivered. Replaying it would re-insert
+            // commitments already in the zswap state ("non-linear insertion" error), so only events
+            // strictly after the applied index are replayed. The boundary is still used (below) to
+            // refresh the tip and mark the wallet connected — that is how an already-caught-up wallet
+            // learns it is synced when no new events exist.
+            const appliedIndex = state.progress?.appliedIndex ?? 0n;
+            const freshUpdates = wrappedUpdate.updates.filter((u) => BigInt(u.id) > appliedIndex);
+            const lastUpdate = wrappedUpdate.updates.at(-1);
+            const highestRelevantWalletIndex = BigInt(lastUpdate.maxId);
+            const [newState, newChanges] = freshUpdates.length === 0
+                ? [state, []]
+                : CoreWallet.replayEventsWithChanges(state, wrappedUpdate.secretKeys, freshUpdates.map((u) => u.event));
+            const updatedState = CoreWallet.updateProgress(newState, {
+                highestRelevantWalletIndex,
+                appliedIndex: freshUpdates.length === 0 ? appliedIndex : BigInt(freshUpdates.at(-1).id),
+                isConnected: true,
+            });
+            return [updatedState, { changes: newChanges, protocolVersion: lastUpdate.protocolVersion }];
+        },
+    };
+};
+export const makeSimulatorSyncService = (config) => {
+    return {
+        updates: (_state, secretKeys) => {
+            // Get the initial state immediately to ensure we process the genesis block.
+            // Then subscribe to state$ for subsequent changes, but deduplicate by block number
+            // to avoid processing the same block twice.
+            let lastSeenBlockNumber;
+            return pipe(Stream.fromEffect(config.simulator.getLatestState()), Stream.concat(config.simulator.state$), Stream.filter((state) => {
+                const lastBlock = getLastBlock(state);
+                if (lastBlock === undefined) {
+                    return false; // Skip blank state
+                }
+                const blockNumber = lastBlock.number;
+                // Skip if we've already seen this block (deduplication)
+                if (lastSeenBlockNumber !== undefined && blockNumber <= lastSeenBlockNumber) {
+                    return false;
+                }
+                lastSeenBlockNumber = blockNumber;
+                return true;
+            }), Stream.map((state) => ({ update: state, secretKeys })));
+        },
+    };
+};
+export const makeSimulatorSyncCapability = () => {
+    return {
+        applyUpdate: (state, update) => {
+            const { update: simulatorState, secretKeys } = update;
+            const lastBlock = getLastBlock(simulatorState);
+            if (lastBlock === undefined) {
+                return [state, { changes: [], protocolVersion: Number(state.protocolVersion) }];
+            }
+            // Get all events from blocks starting at appliedIndex (the next block to process).
+            // appliedIndex semantics: the first block number we haven't processed yet.
+            // Initial: appliedIndex = 0 (haven't processed any blocks)
+            // After processing block N: appliedIndex = N + 1 (next block to process)
+            const events = [...getBlockEventsFrom(simulatorState, state.progress.appliedIndex)];
+            const [newState, newChanges] = CoreWallet.replayEventsWithChanges(state, secretKeys, events);
+            return [
+                CoreWallet.updateProgress(newState, {
+                    appliedIndex: lastBlock.number + 1n,
+                }),
+                { changes: newChanges, protocolVersion: Number(state.protocolVersion) },
+            ];
+        },
+    };
+};

package/dist/v1/Transacting.d.ts

@@ -0,0 +1,50 @@
+import * as ledger from '@midnight-ntwrk/ledger-v8';
+import { type NetworkId } from '@midnightntwrk/wallet-sdk-abstractions';
+import { Array as Arr, Either } from 'effect';
+import { CoreWallet } from './CoreWallet.js';
+import { type WalletError } from './WalletError.js';
+import { type CoinSelection } from '@midnightntwrk/wallet-sdk-capabilities';
+import { type ShieldedAddress } from '@midnightntwrk/wallet-sdk-address-format';
+import { TransactionImbalances } from './TransactionImbalances.js';
+import { TransactionOps } from './TransactionOps.js';
+import { type CoinsAndBalancesCapability } from './CoinsAndBalances.js';
+import { type KeysCapability } from './Keys.js';
+export interface TokenTransfer {
+    readonly amount: bigint;
+    readonly type: ledger.RawTokenType;
+    readonly receiverAddress: ShieldedAddress;
+}
+export type BalancingResult = ledger.UnprovenTransaction | undefined;
+export interface TransactingCapability<TSecrets, TState, _TTransaction> {
+    balanceTransaction(secrets: TSecrets, state: TState, tx: ledger.Transaction<ledger.Signaturish, ledger.Proofish, ledger.Bindingish>): Either.Either<[BalancingResult, TState], WalletError>;
+    makeTransfer(secrets: TSecrets, state: TState, outputs: ReadonlyArray<TokenTransfer>): Either.Either<[ledger.UnprovenTransaction, TState], WalletError>;
+    initSwap(secrets: TSecrets, state: TState, desiredInputs: Record<ledger.RawTokenType, bigint>, desiredOutputs: ReadonlyArray<TokenTransfer>): Either.Either<[ledger.UnprovenTransaction, TState], WalletError>;
+    revertTransaction(state: TState, transaction: ledger.Transaction<ledger.Signaturish, ledger.Proofish, ledger.Bindingish>): Either.Either<TState, WalletError>;
+}
+export type DefaultTransactingConfiguration = {
+    networkId: NetworkId.NetworkId;
+};
+export type DefaultTransactingContext = {
+    coinSelection: CoinSelection<ledger.QualifiedShieldedCoinInfo>;
+    coinsAndBalancesCapability: CoinsAndBalancesCapability<CoreWallet>;
+    keysCapability: KeysCapability<CoreWallet>;
+};
+export declare const makeDefaultTransactingCapability: (config: DefaultTransactingConfiguration, getContext: () => DefaultTransactingContext) => TransactingCapability<ledger.ZswapSecretKeys, CoreWallet, ledger.FinalizedTransaction>;
+export declare const makeSimulatorTransactingCapability: (config: DefaultTransactingConfiguration, getContext: () => DefaultTransactingContext) => TransactingCapability<ledger.ZswapSecretKeys, CoreWallet, ledger.ProofErasedTransaction>;
+export declare class TransactingCapabilityImplementation<TTransaction extends ledger.Transaction<ledger.Signaturish, ledger.Proofish, ledger.Bindingish>> implements TransactingCapability<ledger.ZswapSecretKeys, CoreWallet, TTransaction> {
+    #private;
+    readonly networkId: NetworkId.NetworkId;
+    readonly getCoinSelection: () => CoinSelection<ledger.QualifiedShieldedCoinInfo>;
+    readonly txOps: TransactionOps<TTransaction>;
+    readonly getCoins: () => CoinsAndBalancesCapability<CoreWallet>;
+    readonly getKeys: () => KeysCapability<CoreWallet>;
+    constructor(networkId: NetworkId.NetworkId, getCoinSelection: () => CoinSelection<ledger.QualifiedShieldedCoinInfo>, getCoins: () => CoinsAndBalancesCapability<CoreWallet>, getKeys: () => KeysCapability<CoreWallet>, txOps: TransactionOps<TTransaction>);
+    balanceTransaction(secretKeys: ledger.ZswapSecretKeys, state: CoreWallet, tx: TTransaction): Either.Either<[BalancingResult, CoreWallet], WalletError>;
+    makeTransfer(secretKeys: ledger.ZswapSecretKeys, state: CoreWallet, transfers: Arr.NonEmptyReadonlyArray<TokenTransfer>): Either.Either<[ledger.UnprovenTransaction, CoreWallet], WalletError>;
+    initSwap(secretKeys: ledger.ZswapSecretKeys, state: CoreWallet, desiredInputs: Record<ledger.RawTokenType, bigint>, desiredOutputs: ReadonlyArray<TokenTransfer>): Either.Either<[ledger.UnprovenTransaction, CoreWallet], WalletError>;
+    revertTransaction(state: CoreWallet, transaction: TTransaction | ledger.UnprovenTransaction): Either.Either<CoreWallet, WalletError>;
+    balanceFallibleSection(secretKeys: ledger.ZswapSecretKeys, state: CoreWallet, imbalances: TransactionImbalances, coinSelection: CoinSelection<ledger.QualifiedShieldedCoinInfo>): Either.Either<{
+        fallibleOffers: Map<number, ledger.ZswapOffer<ledger.PreProof>>;
+        newState: CoreWallet;
+    }, WalletError>;
+}