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

package/dist/v2/Migration.js

@@ -0,0 +1,96 @@
+// 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 '@midnightntwrk/ledger-v9';
+import { WalletSeed } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { EitherOps, LedgerOps } from '@midnight-ntwrk/wallet-sdk-utilities';
+import { Effect, Either, pipe } from 'effect';
+import { CoreWallet, PublicKeys } from './CoreWallet.js';
+/**
+ * The migration used when there is no previous wallet at all.
+ *
+ * @remarks
+ *   It backs `WalletLike.startEmpty`, which builds a wallet before any key material exists. The resulting state has no
+ *   coins and public keys derived from a fixed placeholder seed; it is a scaffold to be replaced by a real start, not a
+ *   wallet anybody can transact with. Preserved verbatim from the ledger-v8 implementation so that `startEmpty` behaves
+ *   exactly as it did.
+ * @example
+ *   ```typescript
+ *   const builder = new V2Builder().withDefaults().withMigration(makeEmptyWalletMigration({ networkId }));
+ *   ```;
+ *
+ * @param configuration Supplies the network the scaffold state claims to be on.
+ * @returns A migration from `null`.
+ */
+export const makeEmptyWalletMigration = (configuration) => ({
+    migrate: () => {
+        const seed = WalletSeed.fromString('0000000000000000000000000000000000000000000000000000000000000001');
+        return Effect.succeed(CoreWallet.empty(PublicKeys.fromSecretKeys(ledger.ZswapSecretKeys.fromSeed(seed)), configuration.networkId));
+    },
+});
+/**
+ * The migration between two variants that share this ledger version.
+ *
+ * @remarks
+ *   Both sides speak the same state type, so the carry is the identity: local Merkle tree, coins, coin hashes and sync
+ *   progress all remain valid, and nothing has to be re-read. This is the right strategy for a protocol bump that does
+ *   not change serialization.
+ * @returns A migration from a {@link CoreWallet} of this ledger version.
+ */
+export const makeCarryOverMigration = () => ({
+    migrate: (previousState) => Effect.succeed(previousState),
+});
+/**
+ * The migration across a ledger-version boundary: the local state crosses as bytes, identity and position beside it.
+ *
+ * @remarks
+ *   The chain's state translation carries every commitment across the fork in place — the ledger-v9 tree continues at the
+ *   index the ledger-v8 tree reached, and the indexer does **not** replay the ledger-v8 timeline as new-version events.
+ *   So the wallet's own state must cross with it, or the coins are gone.
+ *
+ *   It crosses as bytes. The two ledger majors either side of this boundary serialize `ZswapLocalState` under the same
+ *   `zswap-local-state` codec — the transaction codec moved at the fork, this one did not — so the previous version's
+ *   serialization is something this version can simply read. The crossing is therefore a round-trip and not a
+ *   reconstruction, and everything survives it: the coins at the Merkle indices the chain gave them, the height the
+ *   tree had reached, and the outputs the wallet was still expecting, which no reconstruction from spendable coins
+ *   could have recovered. `src/v2/test/byteCrossing.test.ts` pins that codec against both real ledgers, and states what
+ *   to do if it ever goes red.
+ *
+ *   **The coins booked for transactions still in flight cross too, and are released at the first sync update.** Those
+ *   transactions belong to the ledger version the chain has left behind, so none of them can ever be included and no
+ *   inclusion will ever clear the reservations they left in `pendingSpends` — the coins would simply stop being
+ *   spendable. The release cannot happen here, because un-booking a spend needs the secret keys a migration is by
+ *   design handed none of; it happens at the first sync update instead, which is where keys and carried state meet
+ *   (`CoreWallet.completeCrossing`). The change outputs those same transactions would have paid back are left as they
+ *   are, and nothing ever removes them: these entries carry no TTL and `ZswapLocalState.clearPending` does nothing in
+ *   either ledger, so they sit in `pendingOutputs` for the life of the wallet. A known limitation, and a mild one —
+ *   they overstate the pending balance, but they reserve no coin and block no spending.
+ *
+ *   Read through `LedgerOps.ledgerTry`, so a codec that has moved is a `WalletError` at the boundary and never a throw:
+ *   the failure mode of a future major moving `zswap-local-state` is loud, and lands here, where the
+ *   {@link StateMigration} seam can be given the ledger team's own translation instead.
+ *
+ *   Sync progress is **parked at the fork** rather than rewound: the indexer numbers ledger-v9 events onwards from
+ *   whatever id it had reached when the fork happened, never from zero, so the inherited cursor is exactly where this
+ *   wallet's reading resumes. A wallet that rewound to zero would wait on a stretch of the timeline this ledger
+ *   version's events do not occupy.
+ * @returns A migration from a previous-ledger-version wallet.
+ */
+export const makeCrossLedgerMigration = () => ({
+    migrate: (previousState) => pipe(LedgerOps.ledgerTry(() => ledger.ZswapLocalState.deserialize(previousState.state.serialize())), Either.map((state) => CoreWallet.fromPreviousVersion({
+        state,
+        publicKeys: previousState.publicKeys,
+        networkId: previousState.networkId,
+        protocolVersion: previousState.protocolVersion,
+        progress: previousState.progress,
+    })), EitherOps.toEffect),
+});

package/dist/v2/RunningV2Variant.d.ts

@@ -0,0 +1,40 @@
+import type * as ledger from '@midnightntwrk/ledger-v9';
+import { Effect, Scope, Stream } from 'effect';
+import { type WalletRuntimeError, type Variant, StateChange } from '@midnight-ntwrk/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 '@midnight-ntwrk/wallet-sdk-capabilities';
+import { type CoreWallet } from './CoreWallet.js';
+import { type TransactionHistoryService } from './TransactionHistory.js';
+export declare namespace RunningV2Variant {
+    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 V2Tag: unique symbol;
+export type DefaultRunningV2 = RunningV2Variant<string, EventsSyncUpdate, ledger.FinalizedTransaction, ledger.ZswapSecretKeys>;
+export declare class RunningV2Variant<TSerialized, TSyncUpdate, TTransaction, TStartAux> implements Variant.RunningVariant<typeof V2Tag, CoreWallet> {
+    #private;
+    readonly __polyTag__: typeof V2Tag;
+    readonly state: Stream.Stream<StateChange.StateChange<CoreWallet>, WalletRuntimeError>;
+    constructor(scope: Scope.Scope, context: Variant.VariantContext<CoreWallet>, v2Context: RunningV2Variant.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/v2/RunningV2Variant.js

@@ -0,0 +1,127 @@
+import { Effect, pipe, Scope, Stream, SubscriptionRef, Schedule, Duration, Sink, Console } from 'effect';
+import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { StateChange, VersionChangeType, } from '@midnight-ntwrk/wallet-sdk-runtime/abstractions';
+import { EitherOps } from '@midnight-ntwrk/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 '@midnight-ntwrk/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 '@midnight-ntwrk/wallet-sdk-abstractions';
+import { CoreWallet } from './CoreWallet.js';
+import { type Simulator, type SimulatorState } from '@midnight-ntwrk/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>;