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

package/dist/v1/Sync.js

@@ -10,15 +10,49 @@
 // 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 { Chunk, Duration, Effect, Either, ParseResult, pipe, Schedule, Schema, Stream } from 'effect';
+import * as ledger from '@midnight-ntwrk/ledger-v8';
+import { Chunk, Duration, Effect, Either, identity, Option, ParseResult, pipe, Schedule, Schema, Stream, } from 'effect';
+import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
 import { CoreWallet } from './CoreWallet.js';
-import { getLastBlock, getBlockEventsFrom, } from '@midnight-ntwrk/wallet-sdk-capabilities/simulation';
-import { ZswapEvents } from '@midnight-ntwrk/wallet-sdk-indexer-client';
-import { ConnectionHelper, WsSubscriptionClient } from '@midnight-ntwrk/wallet-sdk-indexer-client/effect';
+import { V8 } from '@midnight-ntwrk/wallet-sdk-capabilities/simulation';
+import { BlockHash, ZswapEventTip, ZswapEvents } from '@midnight-ntwrk/wallet-sdk-indexer-client';
+import { ConnectionHelper, HttpQueryClient, WsSubscriptionClient, } from '@midnight-ntwrk/wallet-sdk-indexer-client/effect';
 import { SyncWalletError } from './WalletError.js';
 import { WsURL } from '@midnight-ntwrk/wallet-sdk-utilities/networking';
 import { EitherOps } from '@midnight-ntwrk/wallet-sdk-utilities';
+/**
+ * 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 const splitAtVersionBoundary = (items, versionOf, activeRange) => {
+    const [, end] = activeRange;
+    const boundary = items.findIndex((item) => BigInt(versionOf(item)) >= end);
+    const [applied, deferred] = boundary < 0 ? [items, []] : [items.slice(0, boundary), items.slice(boundary)];
+    const signalling = deferred.at(0) ?? applied.at(-1);
+    return {
+        applied,
+        deferred,
+        observedVersion: signalling === undefined
+            ? Option.none()
+            : Option.some(ProtocolVersion.ProtocolVersion(BigInt(versionOf(signalling)))),
+    };
+};
+/** Records a batch's observed protocol version on the state, monotonically. A batch that observed none is a no-op. */
+export const annotateVersion = (state, observedVersion) => Option.match(observedVersion, {
+    onNone: () => state,
+    onSome: (version) => CoreWallet.withProtocolVersion(state, version),
+});
 const Uint8ArraySchema = Schema.declare((input) => input instanceof Uint8Array).annotations({
     identifier: 'Uint8Array',
 });
@@ -31,9 +65,19 @@ export const SecretKeysResource = {
         };
     },
 };
+export const VersionSignalSyncUpdate = {
+    create: (version, highestEventId) => {
+        return {
+            _tag: 'VersionSignal',
+            version,
+            highestEventId,
+        };
+    },
+};
 export const WalletSyncUpdate = {
     create: (updates, secretKeys) => {
         return {
+            _tag: 'Events',
             updates,
             secretKeys,
         };
@@ -59,27 +103,132 @@ const EventsSyncUpdatePayload = Schema.Struct({
     protocolVersion: Schema.Number,
     maxId: Schema.Number,
 });
+/**
+ * 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 const EventsSyncUpdate = Schema.TaggedStruct('EventsSyncUpdate', {
     id: Schema.Number,
     protocolVersion: Schema.Number,
     maxId: Schema.Number,
-    event: LedgerEventSchema,
+    raw: Schema.String,
 });
-const EventsSyncUpdateFromPayload = Schema.transformOrFail(EventsSyncUpdatePayload, EventsSyncUpdate, {
-    decode: (input) => pipe(Schema.decodeUnknownEither(HexedLedgerEvent)(input.raw), Either.map((event) => ({
+const EventsSyncUpdateFromPayload = Schema.transform(EventsSyncUpdatePayload, EventsSyncUpdate, {
+    strict: true,
+    decode: (input) => ({
         _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),
+        raw: input.raw,
+    }),
+    encode: (update) => ({
+        id: update.id,
+        raw: update.raw,
+        protocolVersion: update.protocolVersion,
+        maxId: update.maxId,
+    }),
 });
+/**
+ * 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 const readEvent = (update) => Schema.decodeSync(HexedLedgerEvent)(update.raw);
+/** How often the chain is asked its version when the configuration does not say. */
+const DEFAULT_VERSION_WATCH_INTERVAL_MS = 30_000;
+/**
+ * How long one event-id probe is given to produce its single answer.
+ *
+ * @remarks
+ *   Only a stall guard. The probe subscribes at a cursor whose event provably exists, so the answer arrives at once or
+ *   the transport is broken; without a bound, a half-open socket would leave the poll loop parked on a tick that never
+ *   completes and the wallet would stop asking altogether. A bound turns that into a skipped tick.
+ */
+const EVENT_TIP_PROBE_TIMEOUT = Duration.seconds(10);
+/**
+ * Asks the source how far its zswap event timeline goes.
+ *
+ * @remarks
+ *   Over the event subscription rather than a query, because the schema has no query that reaches a zswap ledger event:
+ *   `block`/`transactions` reach one only through a block that happens to contain zswap events, which on a quiet chain
+ *   is precisely the block that does not. `maxId` is a property of the whole timeline, so any single event answers it —
+ *   the first one delivered is taken and the subscription closed.
+ *
+ *   The cursor is the wallet's own. The event it last applied provably exists, so the source answers immediately and has
+ *   the least backfill to abandon; a wallet that has applied nothing asks from the start, where the first event is.
+ * @param config The sync configuration, for the keep-alive the source's subscriptions use.
+ * @param url Where to subscribe.
+ * @param resumeFrom The wallet's cursor; below zero means "from the very start".
+ * @returns The highest event id, or nothing if the source did not answer.
+ */
+const highestEventId = (config, url, resumeFrom) => pipe(ZswapEventTip.run({ id: resumeFrom < 0n ? null : Number(resumeFrom) }), Stream.runHead, Effect.map(Option.map((answer) => answer.zswapLedgerEvents.maxId)), Effect.provide(WsSubscriptionClient.layer({ url, keepAlive: config.indexerClientConnection.keepAlive })), Effect.scoped, Effect.timeout(EVENT_TIP_PROBE_TIMEOUT));
+/**
+ * One check of the chain's protocol version, gated on the wallet being caught up on the source's event ids.
+ *
+ * @remarks
+ *   The order of the two questions is load-bearing. The tip is read **first**: a tip reported at a version means the
+ *   source has indexed through the block that carries it, so every event below it is already counted in the `maxId`
+ *   read afterwards. Asked the other way round, an event indexed between the two answers could be one of the version
+ *   that preceded the tip — unread, uncounted, and exactly what the gate exists to catch.
+ *
+ *   Two short-circuits, both of them answers rather than shortcuts. A tip at or below the version the wallet already held
+ *   is a signal that could only be a no-op, so no probe is opened and nothing is emitted — which is what keeps a
+ *   settled wallet from polling a subscription for the rest of its life. And a tip whose commitment tree has never
+ *   grown cannot have had a nullifier spent against it either, so such a chain provably holds no zswap event: nothing
+ *   can be unread, and the signal goes out with `null`.
+ *
+ *   Everything else is swallowed. A tick that fails says nothing about the chain, so it must neither reach the state nor
+ *   take the sync stream down with it; the next tick is the retry, and costs nothing to wait for.
+ * @param config The sync configuration, for the indexer to ask.
+ * @param url Where to run the event-id probe.
+ * @param resumeFrom The wallet's cursor, for the probe.
+ * @param knownVersion The version the wallet already held when this stream opened — a lower bound on what it holds now.
+ * @returns The signal, or nothing when there is nothing to say or nobody said it.
+ */
+const readVersionSignal = (config, url, resumeFrom, knownVersion) => pipe(BlockHash.run({ offset: null }), Effect.provide(HttpQueryClient.layer({ url: config.indexerClientConnection.indexerHttpUrl })), Effect.scoped, Effect.flatMap((answer) => Option.match(Option.fromNullable(answer.block), {
+    onNone: () => Effect.succeedNone,
+    onSome: (tip) => BigInt(tip.protocolVersion) <= knownVersion
+        ? Effect.succeedNone
+        : tip.zswapEndIndex === 0
+            ? Effect.succeedSome(VersionSignalSyncUpdate.create(tip.protocolVersion, null))
+            : pipe(highestEventId(config, url, resumeFrom), Effect.map(Option.map((maxId) => VersionSignalSyncUpdate.create(tip.protocolVersion, maxId)))),
+})), Effect.catchAll(() => Effect.succeedNone));
+/**
+ * The chain's version, re-asked on a timer for as long as sync runs.
+ *
+ * @remarks
+ *   Deliberately silent about ticks that say nothing: a tick that finds the chain where the wallet left it, or that
+ *   cannot reach the chain at all, emits no element rather than an empty one, so nothing downstream has to know that
+ *   polling is how the answer was arrived at.
+ * @param config The sync configuration, carrying the interval.
+ * @param url Where to run the event-id probe.
+ * @param resumeFrom The wallet's cursor, for the probe.
+ * @param knownVersion The version the wallet held when this stream opened.
+ * @returns The signals, or an empty stream when watching is turned off.
+ */
+const versionWatch = (config, url, resumeFrom, knownVersion) => {
+    const intervalMs = config.versionWatch?.intervalMs ?? DEFAULT_VERSION_WATCH_INTERVAL_MS;
+    return intervalMs <= 0
+        ? Stream.empty
+        : pipe(Stream.fromSchedule(Schedule.spaced(Duration.millis(intervalMs))), Stream.mapEffect(() => readVersionSignal(config, url, resumeFrom, knownVersion)), Stream.filterMap(identity));
+};
 export const makeEventsSyncService = (config) => {
     return {
         updates: (state, secretKeys) => {
@@ -124,17 +273,54 @@ export const makeEventsSyncService = (config) => {
                 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;
+            const timeline = batchSpacing > 0 ? Stream.schedule(eventsStream, Schedule.spaced(Duration.millis(batchSpacing))) : eventsStream;
+            // The timeline is what the source is for, so it decides when the source is done: `haltStrategy: 'left'` stops the
+            // watcher with it rather than leaving a poll loop running against a stream nobody is reading. It has nothing to
+            // say about failure — a failing timeline still fails the merged stream, where the variant's retry can see it.
+            return Stream.merge(timeline, versionWatch(config, indexerWsUrl, resumeFrom, state.protocolVersion), {
+                haltStrategy: 'left',
+            });
         },
     };
 };
+/** The result of an update that observed nothing of the chain. */
+const noChanges = (state) => ({
+    changes: [],
+    protocolVersion: Number(state.protocolVersion),
+});
+/**
+ * Folds what the chain said about its own version into the wallet state.
+ *
+ * @remarks
+ *   The same recording the event path makes through {@link annotateVersion}, and nothing else: no cursor moves, no coin
+ *   changes hands, no tree grows. A signal is an observation about the chain, not a piece of it.
+ *
+ *   Unread events below the source's tip make the observation unsafe to record, and leave the state exactly as it was:
+ *   the hand-over would park the cursor in front of history the next variant cannot read — and those events carry the
+ *   version themselves, so nothing is lost by waiting for them. That is not an error; the next tick asks again.
+ *
+ *   A version at or below the one already recorded needs no guard of its own — {@link annotateVersion} never goes
+ *   backwards — so a source briefly answering from a lagging replica cannot drag a wallet back over a boundary.
+ * @param state The wallet to record on.
+ * @param update What the chain said, and how far its event timeline goes.
+ * @returns The wallet, annotated or untouched, and an empty result.
+ */
+const applyVersionSignal = (state, update) => {
+    const appliedIndex = state.progress?.appliedIndex ?? 0n;
+    const unreadEvents = update.highestEventId !== null && BigInt(update.highestEventId) > appliedIndex;
+    return [
+        unreadEvents ? state : annotateVersion(state, Option.some(ProtocolVersion.ProtocolVersion(BigInt(update.version)))),
+        noChanges(state),
+    ];
+};
 export const makeEventsSyncCapability = () => {
     return {
-        applyUpdate: (state, wrappedUpdate) => {
+        applyUpdate: (state, wrappedUpdate, activeRange) => {
+            if (wrappedUpdate._tag === 'VersionSignal') {
+                return applyVersionSignal(state, wrappedUpdate);
+            }
             if (wrappedUpdate.updates.length === 0) {
-                return [state, { changes: [], protocolVersion: Number(state.protocolVersion) }];
+                return [state, noChanges(state)];
             }
             // 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
@@ -144,17 +330,32 @@ export const makeEventsSyncCapability = () => {
             // 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);
+            // The tip is a property of the source, not of what this variant chose to apply, so it is read from
+            // the batch tail even when the tail belongs to the next protocol version.
             const lastUpdate = wrappedUpdate.updates.at(-1);
             const highestRelevantWalletIndex = BigInt(lastUpdate.maxId);
-            const [newState, newChanges] = freshUpdates.length === 0
+            const { applied, observedVersion } = splitAtVersionBoundary(freshUpdates, (update) => update.protocolVersion, activeRange);
+            // Read here and nowhere earlier: `applied` is exactly the slice this variant owns, so nothing outside its
+            // activation range — nor anything below its cursor — is ever handed to this ledger version's deserializer.
+            const [newState, newChanges] = applied.length === 0
                 ? [state, []]
-                : CoreWallet.replayEventsWithChanges(state, wrappedUpdate.secretKeys, freshUpdates.map((u) => u.event));
-            const updatedState = CoreWallet.updateProgress(newState, {
+                : CoreWallet.replayEventsWithChanges(state, wrappedUpdate.secretKeys, applied.map(readEvent));
+            // `appliedIndex` stops at the last event this variant actually replayed. The next variant resumes one
+            // below it on an inclusive cursor, so the deferred suffix is re-fetched rather than skipped.
+            const updatedState = CoreWallet.updateProgress(annotateVersion(newState, observedVersion), {
                 highestRelevantWalletIndex,
-                appliedIndex: freshUpdates.length === 0 ? appliedIndex : BigInt(freshUpdates.at(-1).id),
+                appliedIndex: applied.length === 0 ? appliedIndex : BigInt(applied.at(-1).id),
                 isConnected: true,
             });
-            return [updatedState, { changes: newChanges, protocolVersion: lastUpdate.protocolVersion }];
+            return [
+                updatedState,
+                {
+                    changes: newChanges,
+                    // Tags the changes that were actually produced, so tx-history records the version they were applied
+                    // under rather than the one that is about to trigger the hand-over.
+                    protocolVersion: applied.at(-1)?.protocolVersion ?? Number(state.protocolVersion),
+                },
+            ];
         },
     };
 };
@@ -166,7 +367,7 @@ export const makeSimulatorSyncService = (config) => {
             // 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);
+                const lastBlock = V8.getLastBlock(state);
                 if (lastBlock === undefined) {
                     return false; // Skip blank state
                 }
@@ -183,23 +384,31 @@ export const makeSimulatorSyncService = (config) => {
 };
 export const makeSimulatorSyncCapability = () => {
     return {
-        applyUpdate: (state, update) => {
+        applyUpdate: (state, update, activeRange) => {
             const { update: simulatorState, secretKeys } = update;
-            const lastBlock = getLastBlock(simulatorState);
+            const lastBlock = V8.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);
+            //
+            // The boundary is applied at block granularity here — a block carries exactly one protocol version,
+            // stamped when it was produced — but it is the same rule and the same helper the indexer path uses.
+            const pending = simulatorState.blocks.filter((block) => block.number >= state.progress.appliedIndex);
+            const { applied, observedVersion } = splitAtVersionBoundary(pending, (block) => Number(block.protocolVersion), activeRange);
+            const events = applied.flatMap((block) => block.transactions.flatMap((tx) => tx.result.events));
+            const [newState, newChanges] = applied.length === 0 ? [state, []] : CoreWallet.replayEventsWithChanges(state, secretKeys, events);
+            const lastAppliedBlock = applied.at(-1);
             return [
-                CoreWallet.updateProgress(newState, {
-                    appliedIndex: lastBlock.number + 1n,
+                CoreWallet.updateProgress(annotateVersion(newState, observedVersion), {
+                    appliedIndex: lastAppliedBlock === undefined ? state.progress.appliedIndex : lastAppliedBlock.number + 1n,
                 }),
-                { changes: newChanges, protocolVersion: Number(state.protocolVersion) },
+                {
+                    changes: newChanges,
+                    protocolVersion: lastAppliedBlock === undefined ? Number(state.protocolVersion) : Number(lastAppliedBlock.protocolVersion),
+                },
             ];
         },
     };

package/dist/v1/Transacting.d.ts

@@ -1,4 +1,4 @@
-import * as ledger from '@midnightntwrk/ledger-v9';
+import * as ledger from '@midnight-ntwrk/ledger-v8';
 import { type NetworkId } from '@midnight-ntwrk/wallet-sdk-abstractions';
 import { Array as Arr, Either } from 'effect';
 import { CoreWallet } from './CoreWallet.js';

package/dist/v1/Transacting.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 { Array as Arr, Either, Option, pipe, Record } from 'effect';
 import { ArrayOps } from '@midnight-ntwrk/wallet-sdk-utilities';
 import { CoreWallet } from './CoreWallet.js';

package/dist/v1/TransactionHistory.d.ts

@@ -1,6 +1,6 @@
 import { TransactionHistoryStorage } from '@midnight-ntwrk/wallet-sdk-abstractions';
-import type * as ledger from '@midnightntwrk/ledger-v9';
-import { Effect, Schema } from 'effect';
+import type * as ledger from '@midnight-ntwrk/ledger-v8';
+import { Duration, Effect, Schema } from 'effect';
 import { TransactionHistoryError } from './WalletError.js';
 export declare const QualifiedShieldedCoinInfoSchema: Schema.Struct<{
     type: typeof Schema.String;
@@ -72,6 +72,13 @@ export type DefaultTransactionHistoryConfiguration = {
     indexerClientConnection: {
         indexerHttpUrl: string;
     };
+    /**
+     * How long to keep re-querying the indexer for a transaction's details before giving up, when the WS event arrives
+     * ahead of HTTP ingestion. This is a bounded window, not a guarantee: if the indexer lags beyond it the shielded
+     * section is lost (the change is not re-processed, even across restarts) and the failure is logged. Default: 2
+     * minutes.
+     */
+    transactionDetailsRetryWindow?: Duration.DurationInput;
 };
 export type TransactionDetails = {
     hash: string;

package/dist/v1/TransactionHistory.js

@@ -60,12 +60,17 @@ const gotFinalizedShielded = (txHistoryStorage, input) => Effect.tryPromise({
 export const makeDefaultTransactionHistoryService = (config, _getContext) => {
     const txHistoryStorage = config.txHistoryStorage;
     const queryClientLayer = HttpQueryClient.layer({ url: config.indexerClientConnection.indexerHttpUrl });
+    const retryWindow = config.transactionDetailsRetryWindow ?? Duration.minutes(2);
     return {
         put: (changes, metadata, protocolVersion) => gotFinalizedShielded(txHistoryStorage, convertUpdateToFinalizedInput(changes, metadata, protocolVersion)),
         getTransactionDetails: (hash) => Effect.gen(function* () {
             const statusQuery = yield* TransactionHistoryDetail;
             const result = yield* statusQuery({ transactionHash: hash });
-            const tx = result.transactions[0];
+            // The WS ZswapEvents stream can deliver a relevant event before the indexer's HTTP `transactions(...)`
+            // endpoint has ingested the same hash — a normal race on any deployed network. In that window the array
+            // is empty; fail with a *typed* error so the retry schedule below engages and re-queries once the indexer
+            // catches up (rather than dereferencing `undefined` and dying with an unretriable defect).
+            const tx = yield* EArray.head(result.transactions).pipe(Effect.orElseFail(() => new TransactionHistoryError({ message: `Indexer has not yet indexed transaction ${hash}` })));
             const rawStatus = tx.__typename === 'RegularTransaction' ? tx.transactionResult.status : undefined;
             const status = rawStatus === 'FAILURE' || rawStatus === 'PARTIAL_SUCCESS' ? rawStatus : 'SUCCESS';
             const identifiers = tx.__typename === 'RegularTransaction' ? tx.identifiers : [];
@@ -79,10 +84,26 @@ export const makeDefaultTransactionHistoryService = (config, _getContext) => {
                 status,
                 identifiers,
             };
-        }).pipe(Effect.provide(queryClientLayer), Effect.scoped, Effect.retry(Schedule.exponential(Duration.seconds(1)).pipe(Schedule.compose(Schedule.recurs(3)))), Effect.mapError((cause) => new TransactionHistoryError({
-            message: `Failed to fetch transaction metadata for ${hash}`,
-            cause,
-        }))),
+        }).pipe(Effect.provide(queryClientLayer), Effect.scoped, 
+        // Retry for a bounded window (default 2 min) while the indexer catches up. The exponential delay is capped
+        // at 10s (`either` takes the earlier of the two schedules) so probes keep landing every ≤10s late in the
+        // window — uncapped doubling would leave minute-long gaps and overshoot the window. Jitter the delays so a
+        // batch of concurrent lookups that all hit the indexer-lag race don't retry in lockstep against an
+        // already-behind indexer. Beyond the window we give up — the change is not re-processed, so the caller logs
+        // the loss. Only the typed "not yet indexed" failure is transient; anything else (bad URL, 4xx, schema
+        // mismatch) cannot succeed by waiting, so it fails fast instead of holding a fan-out slot for the whole
+        // window.
+        Effect.retry({
+            schedule: Schedule.exponential(Duration.seconds(1)).pipe(Schedule.either(Schedule.spaced(Duration.seconds(10))), Schedule.jittered, Schedule.upTo(retryWindow)),
+            while: (error) => error instanceof TransactionHistoryError,
+        }), 
+        // Let our own "not yet indexed" error through untouched; only wrap the indexer query's ClientError/ServerError.
+        Effect.mapError((error) => error instanceof TransactionHistoryError
+            ? error
+            : new TransactionHistoryError({
+                message: `Failed to fetch transaction metadata for ${hash}`,
+                cause: error,
+            }))),
     };
 };
 export const makeSimulatorTransactionHistoryService = (config, _getContext) => {

package/dist/v1/TransactionOps.d.ts

@@ -1,6 +1,6 @@
 import { Imbalances } from '@midnight-ntwrk/wallet-sdk-capabilities';
 import { type TransactionImbalances } from './TransactionImbalances.js';
-import type * as ledger from '@midnightntwrk/ledger-v9';
+import type * as ledger from '@midnight-ntwrk/ledger-v8';
 export type TransactionOps<Tx> = {
     getImbalances(tx: Tx): TransactionImbalances;
     id(tx: Tx): string;