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

package/dist/v1/CoreWallet.js

@@ -10,7 +10,7 @@
 // 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 * as ledger from '@midnight-ntwrk/ledger-v8';
 import { ProtocolVersion, SyncProgress } from '@midnight-ntwrk/wallet-sdk-abstractions';
 import { Either, Iterable, pipe, Record, Array as Arr } from 'effect';
 import { InvalidCoinHashesError } from './WalletError.js';
@@ -97,6 +97,59 @@ export const CoreWallet = {
     initEmpty(keys, networkId) {
         return this.empty(PublicKeys.fromSecretKeys(keys), networkId);
     },
+    /**
+     * Records an observed protocol version on the wallet, never going backwards.
+     *
+     * @remarks
+     *   The version is a signal, not a measurement: writing one outside the running variant's activation range is what
+     *   makes it hand over to the next variant. A source that briefly reports an older version — a reconnect replaying
+     *   from an earlier cursor, say — must therefore not be able to drag the wallet back below a boundary it has already
+     *   crossed, which would ask the runtime to migrate backwards. Taking the maximum makes that unrepresentable.
+     * @param wallet The wallet to annotate.
+     * @param version The protocol version just observed.
+     * @returns `wallet` unchanged if it already records `version` or a later one, otherwise a copy recording `version`.
+     */
+    withProtocolVersion(wallet, version) {
+        return version > wallet.protocolVersion ? { ...wallet, protocolVersion: version } : wallet;
+    },
+    /**
+     * Projects a wallet inherited from the previous ledger version onto a fresh state of this one.
+     *
+     * @remarks
+     *   No coin data crosses the boundary here, and that is a decision rather than an oversight. This is the oldest variant
+     *   the wallet registers and no ledger version below it exists, so nothing ever hands a state to this projection: it
+     *   is shape parity with the twin at `src/v2`, which is the variant a real crossing lands in. That twin adopts the
+     *   previous wallet's local state whole, by deserializing its bytes — the two ledger majors share the
+     *   `zswap-local-state` codec — because the chain's state translation continues the commitment tree across the fork
+     *   and the indexer re-emits none of the ledger-v8 timeline (see `src/v2/Migration.ts`). Mirroring that into a seam
+     *   no chain can reach would buy nothing, so this side stays as it is.
+     *
+     *   What crosses is therefore identity and position: the public keys — which decide whose coins the far side can
+     *   decrypt — the network, the protocol version that triggered the hand-over, kept so the new variant starts inside
+     *   its own activation range rather than immediately signalling backwards, and the cursor the previous variant
+     *   stopped at.
+     *
+     *   **Sync progress is parked at the fork, not rewound**: the previous wallet's cursor crosses unchanged. A fork does
+     *   not restart the timeline — event ids run onwards from whatever the indexer had reached when it happened, never
+     *   from zero — so resuming from the inherited cursor is what puts this wallet in front of what comes next. Rewinding
+     *   to zero would park it on a stretch of history that this ledger version's events do not occupy. What does not
+     *   cross is `isConnected`: no sync is running behind this state yet.
+     *
+     *   Coin hashes start empty for the same reason the tree does: they are commitments and nullifiers computed under the
+     *   previous ledger's codec, and this version recomputes its own from the keys and whatever state it ends up with.
+     * @param previous The plain data read off the previous ledger version's wallet.
+     * @returns A wallet of this ledger version holding no coins, positioned at the fork.
+     */
+    fromPreviousVersion(previous) {
+        return {
+            state: new ledger.ZswapLocalState(),
+            publicKeys: previous.publicKeys,
+            networkId: previous.networkId,
+            coinHashes: CoinHashesMap.empty,
+            progress: SyncProgress.createSyncProgress({ ...previous.progress, isConnected: false }),
+            protocolVersion: ProtocolVersion.ProtocolVersion(previous.protocolVersion),
+        };
+    },
     applyCollapsedUpdate(wallet, collapsed) {
         const newState = wallet.state.applyCollapsedUpdate(collapsed);
         return { ...wallet, state: newState };

package/dist/v1/Migration.d.ts

@@ -0,0 +1,95 @@
+import { type NetworkId, type SyncProgress } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { Effect } from 'effect';
+import { CoreWallet } from './CoreWallet.js';
+import { type WalletError } from './WalletError.js';
+/**
+ * How this variant produces its first state from whatever came before it.
+ *
+ * @remarks
+ *   The strategy is injected through the builder rather than hard-coded into the variant, because "whatever came before"
+ *   is not one thing: an empty wallet at first start, a wallet of this same ledger version, or a wallet of the ledger
+ *   version this one replaced. Those are different functions with different input types, and the runtime only ever
+ *   needs one of them per registration — so which one is a build-time decision, expressed as a dictionary in the
+ *   repository's usual dictionary-passing style.
+ * @typeParam TPreviousState The state this migration consumes.
+ */
+export type StateMigration<TPreviousState> = {
+    migrate: (previousState: TPreviousState) => Effect.Effect<CoreWallet, WalletError>;
+};
+export type EmptyWalletMigrationConfiguration = {
+    networkId: NetworkId.NetworkId;
+};
+/**
+ * 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 declare const makeEmptyWalletMigration: (configuration: EmptyWalletMigrationConfiguration) => StateMigration<null>;
+/**
+ * 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 declare const makeCarryOverMigration: () => StateMigration<CoreWallet>;
+/**
+ * The shape a wallet of the _previous_ ledger version must expose to be projected across a hard fork.
+ *
+ * @remarks
+ *   Structural on purpose. The previous variant's `CoreWallet` is built on a different ledger module, and naming that
+ *   module here would drag a second multi-megabyte WASM binary into this variant for the sake of a type. Everything the
+ *   projection reads is plain data — the ledger's key and network types are all string aliases — so a structural
+ *   description is both sufficient and the only version-agnostic option.
+ *
+ *   `progress` is where a migrated wallet resumes from: event ids continue across a fork rather than restarting, so the
+ *   previous variant's cursor is the position the next one has to start at. Nothing ever fills this shape in practice —
+ *   see {@link makeCrossLedgerMigration} for why this variant is never on the receiving end of a crossing.
+ */
+export type PreviousLedgerWallet = Readonly<{
+    publicKeys: {
+        readonly coinPublicKey: string;
+        readonly encryptionPublicKey: string;
+    };
+    networkId: string;
+    protocolVersion: bigint;
+    progress: SyncProgress.SyncProgressData;
+}>;
+/**
+ * The migration across a ledger-version boundary: for this variant, shape parity and nothing else.
+ *
+ * @remarks
+ *   This is the oldest variant the wallet registers, and no ledger version below the one it is built on exists to be
+ *   registered under it. Nothing can therefore ever hand a state _to_ here: this seam is never exercised by a real
+ *   chain. It exists because both twins declare the same builder surface, and a builder that could not name a
+ *   cross-ledger migration would be a different type on each side of the fork.
+ *
+ *   The twin at `src/v2` is where a crossing actually happens, and it does something this one deliberately does not
+ *   mirror. 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 re-emits none of the ledger-v8 timeline — so a
+ *   wallet that started coinless there would simply lose its coins. That migration therefore reads the previous
+ *   wallet's local state across whole, by handing its serialization to this ledger version's deserializer: the two
+ *   majors either side of that boundary share the `zswap-local-state` codec (see `src/v2/Migration.ts` and
+ *   `src/v2/test/byteCrossing.test.ts`). Porting that back here would be machinery for a case that cannot arise, so it
+ *   stays out: a deliberate, permanent exclusion of the kind the twin convention allows for, not a gap left to close.
+ *
+ *   What crosses here is public keys, the network, the protocol version that triggered the hand-over, and the cursor.
+ *   Sync progress is **parked at the fork** rather than rewound, on the rule that outlives the design change: event ids
+ *   continue across a fork rather than restarting from zero, so the inherited cursor is exactly where 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 declare const makeCrossLedgerMigration: () => StateMigration<PreviousLedgerWallet>;

package/dist/v1/Migration.js

@@ -0,0 +1,82 @@
+// 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 { WalletSeed } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { Effect } 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: for this variant, shape parity and nothing else.
+ *
+ * @remarks
+ *   This is the oldest variant the wallet registers, and no ledger version below the one it is built on exists to be
+ *   registered under it. Nothing can therefore ever hand a state _to_ here: this seam is never exercised by a real
+ *   chain. It exists because both twins declare the same builder surface, and a builder that could not name a
+ *   cross-ledger migration would be a different type on each side of the fork.
+ *
+ *   The twin at `src/v2` is where a crossing actually happens, and it does something this one deliberately does not
+ *   mirror. 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 re-emits none of the ledger-v8 timeline — so a
+ *   wallet that started coinless there would simply lose its coins. That migration therefore reads the previous
+ *   wallet's local state across whole, by handing its serialization to this ledger version's deserializer: the two
+ *   majors either side of that boundary share the `zswap-local-state` codec (see `src/v2/Migration.ts` and
+ *   `src/v2/test/byteCrossing.test.ts`). Porting that back here would be machinery for a case that cannot arise, so it
+ *   stays out: a deliberate, permanent exclusion of the kind the twin convention allows for, not a gap left to close.
+ *
+ *   What crosses here is public keys, the network, the protocol version that triggered the hand-over, and the cursor.
+ *   Sync progress is **parked at the fork** rather than rewound, on the rule that outlives the design change: event ids
+ *   continue across a fork rather than restarting from zero, so the inherited cursor is exactly where 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) => Effect.succeed(CoreWallet.fromPreviousVersion({
+        publicKeys: previousState.publicKeys,
+        networkId: previousState.networkId,
+        protocolVersion: previousState.protocolVersion,
+        progress: previousState.progress,
+    })),
+});

package/dist/v1/RunningV1Variant.d.ts

@@ -1,4 +1,4 @@
-import type * as ledger from '@midnightntwrk/ledger-v9';
+import type * as ledger from '@midnight-ntwrk/ledger-v8';
 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';

package/dist/v1/RunningV1Variant.js

@@ -12,8 +12,23 @@ const progress = (state) => {
     const applyGap = highestRelevantWalletIndex - appliedIndex;
     return [StateChange.ProgressUpdate({ sourceGap, applyGap })];
 };
-const protocolVersionChange = (previous, current) => {
-    return previous.protocolVersion != current.protocolVersion
+/**
+ * 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({
@@ -29,19 +44,25 @@ export class RunningV1Variant {
     #scope;
     #context;
     #v1Context;
+    // 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, 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]) => {
+        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),
+                ...protocolVersionChange(previous, current, isInitial, context.activationRange),
             ];
         }));
     }
@@ -51,7 +72,7 @@ export class RunningV1Variant {
     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);
+                const [newState, changesResult] = this.#v1Context.syncCapability.applyUpdate(state, update, this.#context.activationRange);
                 return [changesResult, newState];
             },
             catch: (err) => new OtherWalletError({
@@ -65,7 +86,15 @@ export class RunningV1Variant {
         // 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) => {
+            : pipe(Effect.forEach(changes, (change) => pipe(this.#txHistoryPermits.withPermits(1)(pipe(this.#v1Context.transactionHistoryService.getTransactionDetails(change.source), Effect.flatMap((metadata) => this.#v1Context.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);

package/dist/v1/Serialization.js

@@ -12,7 +12,7 @@
 // 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 * 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',

package/dist/v1/Sync.d.ts

@@ -1,7 +1,8 @@
-import * as ledger from '@midnightntwrk/ledger-v9';
-import { Schema, type Scope, Stream } from 'effect';
+import * as ledger from '@midnight-ntwrk/ledger-v8';
+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 { V8 } 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> {
@@ -12,8 +13,46 @@ export type ChangesResult = {
     readonly protocolVersion: number;
 };
 export interface SyncCapability<TState, TUpdate, TResult> {
-    applyUpdate: (state: TState, update: TUpdate) => [TState, 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;
@@ -45,9 +84,32 @@ export type BatchUpdatesConfig = {
      */
     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.
+ *
+ *   This variant is the ledger-v8 one, so it is the one that actually crosses: a wallet stranded here is a wallet still
+ *   building transactions for a ledger version the chain has left behind.
+ */
+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;
@@ -56,27 +118,88 @@ export type SecretKeysResource = <A>(cb: (keys: ledger.ZswapSecretKeys) => A) =>
 export declare const SecretKeysResource: {
     create: (secretKeys: ledger.ZswapSecretKeys) => SecretKeysResource;
 };
-export type WalletSyncUpdate = {
+/** The ordinary arm of {@link WalletSyncUpdate}: 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 that would then never reach the far side. 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) => 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;
-    event: Schema.declare<ledger.Event, ledger.Event, readonly [], never>;
+    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;
+    simulator: V8.Simulator;
 };
 export type SimulatorSyncUpdate = {
-    update: SimulatorState;
+    update: V8.SimulatorState;
     secretKeys: ledger.ZswapSecretKeys;
 };
 export declare const makeSimulatorSyncService: (config: SimulatorSyncConfiguration) => SyncService<CoreWallet, ledger.ZswapSecretKeys, SimulatorSyncUpdate>;