@midnight-ntwrk/wallet-sdk-capabilities 4.0.0-rc.0 → 4.0.0-rc.1

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from './balancer/index.js';
 export * from './chainVersion/index.js';
 export * from './codecs/index.js';
+export * from './liveness/index.js';
 export * from './pendingTransactions/index.js';
 export * from './proving/index.js';
 export * from './signatures/index.js';

package/dist/index.js

@@ -13,6 +13,7 @@
 export * from './balancer/index.js';
 export * from './chainVersion/index.js';
 export * from './codecs/index.js';
+export * from './liveness/index.js';
 export * from './pendingTransactions/index.js';
 export * from './proving/index.js';
 export * from './signatures/index.js';

package/dist/liveness/index.d.ts

@@ -0,0 +1,2 @@
+export * from './livenessReads.js';
+export * from './livenessService.js';

package/dist/liveness/index.js

@@ -0,0 +1,14 @@
+// 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.
+export * from './livenessReads.js';
+export * from './livenessService.js';

package/dist/liveness/livenessReads.d.ts

@@ -0,0 +1,73 @@
+import { type NodeClient, type NodeClientError } from '@midnight-ntwrk/wallet-sdk-node-client/effect';
+import { Effect, Option, Scope } from 'effect';
+import { type LivenessReads } from './livenessService.js';
+/**
+ * Parses a block height reported by the indexer.
+ *
+ * @remarks
+ *   `BigInt` throws a `RangeError` on a non-integral number, and the indexer's payload is not validated against a schema
+ *   anywhere on this path. A misbehaving indexer answering `1.5` would therefore raise a defect inside the poll and
+ *   stop it permanently — letting the very party this check exists to catch switch it off. Parsing here keeps that a
+ *   typed failure, which becomes an `Unavailable` verdict like any other unreadable answer.
+ * @param height - The value the indexer reported.
+ * @returns The height, or `Option.none` when it is not a whole non-negative number.
+ */
+export declare const parseIndexerHeight: (height: unknown) => Option.Option<bigint>;
+export type LivenessReadsConfiguration = {
+    readonly indexerClientConnection: {
+        readonly indexerHttpUrl: string;
+    };
+    readonly nodeClientConnection: {
+        readonly nodeURL: string;
+    };
+};
+/**
+ * The calls the liveness check makes on a node client.
+ *
+ * @remarks
+ *   Narrowed to what the check uses so that a test double answers those methods rather than the whole of
+ *   `NodeClient.Service`, and so that this module depends on no more of the node client's surface than it reads.
+ */
+export type LivenessNodeReader = Pick<NodeClient.Service, 'getFinalizedBlock' | 'getGenesisHash' | 'getBlockHashAt'>;
+/** Builds a client for the liveness check's node reads, scoped so the connection is released with its caller. */
+export type NodeClientFactory = (nodeURL: URL) => Effect.Effect<LivenessNodeReader, NodeClientError.NodeClientError, Scope.Scope>;
+/**
+ * Builds the reads a liveness check compares.
+ *
+ * @remarks
+ *   This is the only place the two sources meet, and it exists in `capabilities` rather than in a wallet package so that
+ *   no wallet has to depend on `node-client` directly.
+ *
+ *   The node client is built once, on the first read that needs it, and then reused. Building one per read repeated the
+ *   full `ApiPromise` handshake — including the runtime metadata download — on every poll, against a node the wallet
+ *   does not own, to fetch two numbers. polkadot-js re-fetches metadata only when the api is not already ready
+ *   (`_loadMeta`), so a reused client pays that cost once per wallet rather than once per poll. The socket itself is
+ *   still closed between reads by `getFinalizedBlock`, so nothing is held open on the node's behalf.
+ *
+ *   Creation is deferred to the first read rather than done here, because a connection failure at construction must
+ *   become an {@link IndexerLiveness.Unavailable} verdict. Connecting while the sync stream is being assembled would put
+ *   that failure in the stream's acquire instead, so an unreachable node would stop the wallet syncing — the one
+ *   outcome this check must never cause.
+ *
+ *   A failed read leaves the cached client in place. It recovers by itself: `getFinalizedBlock` reconnects through
+ *   `ensureConnection`, and polkadot-js retries the metadata load on the next connect whenever an earlier one did not
+ *   complete. Only construction failing leaves nothing cached, and the next read then starts over — so a node that is
+ *   down when the first poll runs does not switch the check off for the rest of the session.
+ *
+ *   Both failures are flattened into {@link LivenessReadError} so the service is coupled to neither the indexer's GraphQL
+ *   errors nor the node client's error type.
+ * @example
+ *   ```ts
+ *   const reads = yield* makeDefaultLivenessReads({
+ *     indexerClientConnection: { indexerHttpUrl: 'http://localhost:8088/api/v1/graphql' },
+ *     nodeClientConnection: { nodeURL: 'ws://localhost:9944' },
+ *   });
+ *   ```;
+ *
+ * @param config - Where to reach the indexer and the node.
+ * @param makeNodeClient - How to build the node client. Defaults to a real connection; supplying this is how a test
+ *   exercises the caching without a node.
+ * @returns An effect yielding reads suitable for {@link LivenessServiceImpl.make}. Scoped, because the client they share
+ *   is released when that scope closes.
+ */
+export declare const makeDefaultLivenessReads: (config: LivenessReadsConfiguration, makeNodeClient?: NodeClientFactory) => Effect.Effect<LivenessReads, never, Scope.Scope>;

package/dist/liveness/livenessReads.js

@@ -0,0 +1,228 @@
+// 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 { BlockHash } from '@midnight-ntwrk/wallet-sdk-indexer-client';
+import { HttpQueryClient } from '@midnight-ntwrk/wallet-sdk-indexer-client/effect';
+import { PolkadotNodeClient, } from '@midnight-ntwrk/wallet-sdk-node-client/effect';
+import { Duration, Effect, Option, Scope, SynchronizedRef } from 'effect';
+import { LivenessReadError } from './livenessService.js';
+/**
+ * How long to spend trying to reach the node before giving up on a poll.
+ *
+ * @remarks
+ *   `PolkadotNodeClient` defaults to `Duration.infinity`, which suits transaction submission — a caller waiting to submit
+ *   wants to keep trying. It is wrong here: a liveness check that waits forever on an unreachable node never publishes
+ *   the {@link IndexerLiveness.Unavailable} verdict that exists to report exactly that condition, and its poll fibre
+ *   hangs instead.
+ *
+ *   The bound applies twice within one connection build — once to the handshake, once to the close that follows it — so
+ *   the build's worst case is double this value, and the build runs uninterruptibly. That is why the poll's own
+ *   deadline does not depend on it: the service disconnects the read before applying its timeout, so a slow build
+ *   finishes in the background and its client is cached for the next poll, while the verdict still lands on time.
+ */
+const NODE_CONNECTION_TIMEOUT = Duration.seconds(10);
+/**
+ * Flattens a chain of wrapped errors into one line.
+ *
+ * @remarks
+ *   Both sources wrap their failures — the node client reports "Failed to retrieve the finalized block" over whatever the
+ *   RPC actually said. Only the outermost message would otherwise reach `Unavailable.lastError`, which names the
+ *   operation that failed but not the reason, and so cannot be acted on.
+ */
+const describeCause = (error) => error instanceof Error
+    ? error.cause === undefined || error.cause === null
+        ? error.message
+        : `${error.message}: ${describeCause(error.cause)}`
+    : String(error);
+/**
+ * Parses a block height reported by the indexer.
+ *
+ * @remarks
+ *   `BigInt` throws a `RangeError` on a non-integral number, and the indexer's payload is not validated against a schema
+ *   anywhere on this path. A misbehaving indexer answering `1.5` would therefore raise a defect inside the poll and
+ *   stop it permanently — letting the very party this check exists to catch switch it off. Parsing here keeps that a
+ *   typed failure, which becomes an `Unavailable` verdict like any other unreadable answer.
+ * @param height - The value the indexer reported.
+ * @returns The height, or `Option.none` when it is not a whole non-negative number.
+ */
+export const parseIndexerHeight = (height) => typeof height === 'number' && Number.isSafeInteger(height) && height >= 0
+    ? Option.some(BigInt(height))
+    : Option.none();
+/**
+ * Parses a node endpoint.
+ *
+ * @remarks
+ *   `new URL` throws on a malformed string — omitting the scheme, for instance — and a throw while constructing a read
+ *   escapes before any Effect can catch it.
+ * @param nodeURL - The configured endpoint.
+ * @returns The parsed URL, or `Option.none` when it cannot be parsed.
+ */
+const parseNodeURL = (nodeURL) => {
+    try {
+        return Option.some(new URL(nodeURL));
+    }
+    catch {
+        return Option.none();
+    }
+};
+/** Describes a failure in a way that is useful when it surfaces as `Unavailable.lastError`. */
+const readError = (what, cause) => new LivenessReadError({
+    message: cause === undefined ? what : `${what}: ${describeCause(cause)}`,
+    cause,
+});
+/**
+ * Connects to the node with a bounded initial connection.
+ *
+ * @remarks
+ *   Separated from {@link makeDefaultLivenessReads} so the caching around it can be tested without a node.
+ */
+const connectToNode = (nodeURL) => PolkadotNodeClient.make({ nodeURL, reconnectionTimeout: NODE_CONNECTION_TIMEOUT });
+/**
+ * Builds the reads a liveness check compares.
+ *
+ * @remarks
+ *   This is the only place the two sources meet, and it exists in `capabilities` rather than in a wallet package so that
+ *   no wallet has to depend on `node-client` directly.
+ *
+ *   The node client is built once, on the first read that needs it, and then reused. Building one per read repeated the
+ *   full `ApiPromise` handshake — including the runtime metadata download — on every poll, against a node the wallet
+ *   does not own, to fetch two numbers. polkadot-js re-fetches metadata only when the api is not already ready
+ *   (`_loadMeta`), so a reused client pays that cost once per wallet rather than once per poll. The socket itself is
+ *   still closed between reads by `getFinalizedBlock`, so nothing is held open on the node's behalf.
+ *
+ *   Creation is deferred to the first read rather than done here, because a connection failure at construction must
+ *   become an {@link IndexerLiveness.Unavailable} verdict. Connecting while the sync stream is being assembled would put
+ *   that failure in the stream's acquire instead, so an unreachable node would stop the wallet syncing — the one
+ *   outcome this check must never cause.
+ *
+ *   A failed read leaves the cached client in place. It recovers by itself: `getFinalizedBlock` reconnects through
+ *   `ensureConnection`, and polkadot-js retries the metadata load on the next connect whenever an earlier one did not
+ *   complete. Only construction failing leaves nothing cached, and the next read then starts over — so a node that is
+ *   down when the first poll runs does not switch the check off for the rest of the session.
+ *
+ *   Both failures are flattened into {@link LivenessReadError} so the service is coupled to neither the indexer's GraphQL
+ *   errors nor the node client's error type.
+ * @example
+ *   ```ts
+ *   const reads = yield* makeDefaultLivenessReads({
+ *     indexerClientConnection: { indexerHttpUrl: 'http://localhost:8088/api/v1/graphql' },
+ *     nodeClientConnection: { nodeURL: 'ws://localhost:9944' },
+ *   });
+ *   ```;
+ *
+ * @param config - Where to reach the indexer and the node.
+ * @param makeNodeClient - How to build the node client. Defaults to a real connection; supplying this is how a test
+ *   exercises the caching without a node.
+ * @returns An effect yielding reads suitable for {@link LivenessServiceImpl.make}. Scoped, because the client they share
+ *   is released when that scope closes.
+ */
+export const makeDefaultLivenessReads = (config, makeNodeClient = connectToNode) => Effect.gen(function* () {
+    // The scope the reads are built in, so the shared client is released when sync stops rather than when a read ends.
+    const scope = yield* Effect.scope;
+    // `SynchronizedRef`, not `Ref`: filling the cache is itself an effect, and two concurrent first reads must not race
+    // into building two clients — the second would replace the first, whose socket nothing would then close until the
+    // scope did.
+    const cachedClient = yield* SynchronizedRef.make(Option.none());
+    /**
+     * Yields the shared client, connecting on the first call.
+     *
+     * @remarks
+     *   A failure to build leaves the cache empty, so the next read tries again rather than inheriting a verdict taken
+     *   once.
+     *
+     *   Uninterruptible, because the poll fails fast: when the sibling indexer read fails, the in-flight node read is
+     *   interrupted. The client's acquire is uninterruptible on its own, so without this the interrupt would land
+     *   between the acquire completing and the cache write — stranding a fully-built client on the sync-lifetime scope
+     *   with the cache still empty, once per poll for as long as the indexer stays down. Deferring the interrupt past
+     *   the write costs at most the build's worst case: the connection bound for the handshake plus the same again for
+     *   the close, twenty seconds with the current value. The poll does not wait that long for its verdict — the
+     *   service disconnects the read before applying its own timeout — but the build itself runs to completion or to
+     *   that bound.
+     */
+    const client = (nodeURL) => Effect.uninterruptible(SynchronizedRef.modifyEffect(cachedClient, (current) => Option.match(current, {
+        onSome: (existing) => Effect.succeed([existing, current]),
+        onNone: () => makeNodeClient(nodeURL).pipe(
+        // Extended into the outer scope, not the read's: the client has to outlive the read that built it.
+        Scope.extend(scope), Effect.map((built) => [built, Option.some(built)])),
+    })));
+    /** Resolves the shared client from the configured endpoint — the step both node reads start with. */
+    const nodeReader = () => Option.match(parseNodeURL(config.nodeClientConnection.nodeURL), {
+        onNone: () => Effect.fail(readError(`Node endpoint is not a valid URL: ${config.nodeClientConnection.nodeURL}`, undefined)),
+        onSome: Effect.succeed,
+    }).pipe(Effect.flatMap((nodeURL) => client(nodeURL)));
+    return {
+        indexerTip: () => Effect.gen(function* () {
+            const query = yield* BlockHash;
+            const { block } = yield* query({ offset: null });
+            // A freshly started indexer has ingested nothing, so there is no block to compare against.
+            if (block === null || block === undefined) {
+                return yield* new LivenessReadError({ message: 'Indexer reported no latest block' });
+            }
+            return yield* Option.match(parseIndexerHeight(block.height), {
+                onNone: () => Effect.fail(new LivenessReadError({
+                    message: `Indexer reported an unusable block height: ${String(block.height)}`,
+                })),
+                // The hash comes from the same answer as the height, so the two describe one block. Reading them
+                // separately would let a chain that advanced in between pair a height with another block's hash.
+                onSome: (height) => Effect.succeed({ height, hash: block.hash }),
+            });
+        }).pipe(Effect.provide(HttpQueryClient.layer({ url: config.indexerClientConnection.indexerHttpUrl })), Effect.scoped, Effect.catchAll((cause) => cause instanceof LivenessReadError
+            ? Effect.fail(cause)
+            : Effect.fail(readError('Failed to read the indexer’s latest block', cause)))),
+        finalizedBlock: () => nodeReader().pipe(Effect.flatMap((reader) => reader.getFinalizedBlock()), 
+        // A bound on the whole read, not just the connection: a node that accepts a socket and then never answers would
+        // otherwise stall the poll just as effectively as one that refuses it.
+        Effect.timeoutFail({
+            duration: NODE_CONNECTION_TIMEOUT,
+            onTimeout: () => readError('Timed out reading the node’s finalized head', undefined),
+        }), Effect.catchAll((cause) => cause instanceof LivenessReadError
+            ? Effect.fail(cause)
+            : Effect.fail(readError('Failed to read the node’s finalized head', cause)))),
+        indexerBlockHashAt: (height) => Effect.gen(function* () {
+            const query = yield* BlockHash;
+            // `Number` rather than the bigint: the height is one the indexer itself just reported, so it is within the
+            // range the indexer's own payload uses.
+            const { block } = yield* query({ offset: { height: Number(height) } });
+            // Absence, not failure: the caller asked for a height this endpoint claimed to have passed, and "I have no
+            // block there" is an answer about the chain rather than a read that went wrong.
+            return block === null || block === undefined ? Option.none() : Option.some(block.hash);
+        }).pipe(Effect.provide(HttpQueryClient.layer({ url: config.indexerClientConnection.indexerHttpUrl })), Effect.scoped, Effect.catchAll((cause) => cause instanceof LivenessReadError
+            ? Effect.fail(cause)
+            : Effect.fail(readError(`Failed to read the indexer’s block at height ${height}`, cause)))),
+        nodeBlockHashAt: (height) => nodeReader().pipe(Effect.flatMap((reader) => reader.getBlockHashAt(height)), Effect.timeoutFail({
+            duration: NODE_CONNECTION_TIMEOUT,
+            onTimeout: () => readError(`Timed out reading the node’s block at height ${height}`, undefined),
+        }), Effect.catchAll((cause) => cause instanceof LivenessReadError
+            ? Effect.fail(cause)
+            : Effect.fail(readError(`Failed to read the node’s block at height ${height}`, cause)))),
+        indexerGenesisHash: () => Effect.gen(function* () {
+            const query = yield* BlockHash;
+            const { block } = yield* query({ offset: { height: 0 } });
+            // An indexer that has ingested nothing has no genesis block to name — which chain it is on is not yet known.
+            if (block === null || block === undefined) {
+                return yield* new LivenessReadError({ message: 'Indexer reported no genesis block' });
+            }
+            return block.hash;
+        }).pipe(Effect.provide(HttpQueryClient.layer({ url: config.indexerClientConnection.indexerHttpUrl })), Effect.scoped, Effect.catchAll((cause) => cause instanceof LivenessReadError
+            ? Effect.fail(cause)
+            : Effect.fail(readError('Failed to read the indexer’s genesis block', cause)))),
+        nodeGenesisHash: () => nodeReader().pipe(Effect.flatMap((reader) => reader.getGenesisHash()), 
+        // The hash itself is served from client state, but the first call builds the client — a connection that
+        // must stay bounded like every other node read.
+        Effect.timeoutFail({
+            duration: NODE_CONNECTION_TIMEOUT,
+            onTimeout: () => readError('Timed out reading the node’s genesis hash', undefined),
+        }), Effect.catchAll((cause) => cause instanceof LivenessReadError
+            ? Effect.fail(cause)
+            : Effect.fail(readError('Failed to read the node’s genesis hash', cause)))),
+    };
+});

package/dist/liveness/livenessService.d.ts

@@ -0,0 +1,137 @@
+import { IndexerLiveness } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { Cause, Duration, Effect, Option, Stream } from 'effect';
+declare const LivenessReadError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
+    readonly _tag: "LivenessReadError";
+} & Readonly<A>;
+/**
+ * A block height could not be read.
+ *
+ * @remarks
+ *   The indexer and the node fail in their own vocabularies — a GraphQL error and a `NodeClientError` respectively. Each
+ *   caller adapts its failure into this one type, so the service depends on neither and needs only what it actually
+ *   uses: a message to report on an {@link IndexerLiveness.Unavailable} verdict.
+ */
+export declare class LivenessReadError extends LivenessReadError_base<{
+    /** A short description of why the read failed, surfaced to callers for diagnosis. */
+    readonly message: string;
+    /** The underlying failure, retained for logging. */
+    readonly cause?: unknown;
+}> {
+}
+/**
+ * The reads a liveness check runs, supplied as a dictionary so that callers decide where each comes from: the two tips
+ * it compares every poll, the block those tips share, and the two genesis hashes it compares once to establish that the
+ * tips describe the same chain.
+ *
+ * @remarks
+ *   Every read is required. A service is only started when a node endpoint is configured — when none is, no service runs
+ *   at all and the progress keeps its {@link IndexerLiveness.Skipped} default. That is why no read is optional: a
+ *   service that might have no node would have to represent, and handle, a state it should never be in.
+ *
+ *   The tips carry hashes as well as heights because a height alone proves nothing — it is a number the indexer chooses.
+ *   The block at that height is what it cannot invent, so the check compares one block per poll: the newest one both
+ *   endpoints claim to have passed.
+ */
+export type LivenessReads = {
+    /** Reads the height and hash of the latest block the indexer reports having processed. */
+    readonly indexerTip: () => Effect.Effect<IndexerLiveness.BlockRef, LivenessReadError>;
+    /** Reads the height and hash of the node's highest finalized block. */
+    readonly finalizedBlock: () => Effect.Effect<IndexerLiveness.BlockRef, LivenessReadError>;
+    /**
+     * Reads the hash of the indexer's block at a given height, or `Option.none` when it has none there.
+     *
+     * @remarks
+     *   Called only for a height the indexer has just claimed to have passed, which is why absence is part of a verdict
+     *   rather than a failure: an indexer that cannot serve a block it reports having ingested contradicts its own
+     *   answer.
+     */
+    readonly indexerBlockHashAt: (height: bigint) => Effect.Effect<Option.Option<string>, LivenessReadError>;
+    /**
+     * Reads the hash of the node's block at a given height, or `Option.none` when it has none there.
+     *
+     * @remarks
+     *   Called only for a height at or below the node's own finalized head, where a canonical chain always has a block — so
+     *   absence says this node does not have the block being claimed, not that the read went wrong.
+     */
+    readonly nodeBlockHashAt: (height: bigint) => Effect.Effect<Option.Option<string>, LivenessReadError>;
+    /** Reads the hash of the indexer's block at height zero — the chain the indexer is indexing. */
+    readonly indexerGenesisHash: () => Effect.Effect<string, LivenessReadError>;
+    /** Reads the hash of the node's genesis block — the chain the node is on. */
+    readonly nodeGenesisHash: () => Effect.Effect<string, LivenessReadError>;
+};
+/** How far apart the indexer and the node may be before the difference is reported. */
+export type LivenessConfiguration = {
+    /** How many blocks the indexer may trail the finalized head by and still count as in sync. */
+    readonly maxBehindBlocks: bigint;
+    /** How many blocks the indexer may lead the finalized head by and still count as in sync. */
+    readonly maxAheadBlocks: bigint;
+    /**
+     * How long a single poll may run before it is abandoned and reported as {@link IndexerLiveness.Unavailable}.
+     *
+     * @remarks
+     *   Defaults to {@link DEFAULT_POLL_TIMEOUT}. Polls run one at a time, so without this bound a read that hangs — an
+     *   endpoint that accepts a connection and never answers — would stop the loop forever, freezing the verdict at
+     *   whatever was published last. A hung read must not be able to switch the check off.
+     */
+    readonly pollTimeout?: Duration.Duration;
+};
+/**
+ * The default bound on a single poll.
+ *
+ * @remarks
+ *   Comfortably above the node read's own ten-second connection bound, and below the default poll interval, so an
+ *   abandoned poll never delays the tick that follows it.
+ */
+export declare const DEFAULT_POLL_TIMEOUT: Duration.Duration;
+/**
+ * Tolerances sized against Midnight's 6-second block slots (the indexer pins `SLOT_DURATION` at 6000 ms).
+ *
+ * @remarks
+ *   `maxBehindBlocks` is a staleness allowance: ten blocks is about a minute of chain time, generous enough that an
+ *   indexer briefly catching up is not reported as stale. `maxAheadBlocks` absorbs read skew — the two heights are read
+ *   at different moments — while staying far below the thousands of blocks that separate two different networks.
+ */
+export declare const DEFAULT_LIVENESS_CONFIGURATION: LivenessConfiguration;
+/**
+ * How often to compare the indexer against the node, by default.
+ *
+ * @remarks
+ *   Deliberately unhurried. Each poll costs a request to a node the wallet does not own, a stalled indexer is a
+ *   slow-developing condition, and polling faster than blocks are produced only re-reads the same block. At Midnight's
+ *   6-second slots, half a minute is about five blocks, and it surfaces a stalled indexer well within the time any
+ *   caller would notice.
+ */
+export declare const DEFAULT_POLL_INTERVAL: Duration.Duration;
+export type LivenessService = {
+    /**
+     * Consumes `ticks`, comparing the indexer against the node once per tick and publishing the verdict.
+     *
+     * @remarks
+     *   Ticks are supplied by the caller rather than generated here, so that tests drive the loop directly instead of
+     *   waiting on a clock. The returned effect cannot fail: a read that fails is folded into the verdict by
+     *   {@link IndexerLiveness.afterFailedPoll} — {@link IndexerLiveness.Unavailable}, or a gating verdict kept as it is —
+     *   because a check that gave up on its first network error would be useless against exactly the conditions it exists
+     *   to detect.
+     */
+    readonly startPolling: (ticks: Stream.Stream<unknown>) => Effect.Effect<void>;
+    /** The current verdict, followed by each subsequent one. */
+    readonly state: () => Stream.Stream<IndexerLiveness.IndexerLiveness>;
+};
+export declare class LivenessServiceImpl implements LivenessService {
+    #private;
+    /**
+     * Creates a service whose verdict starts as {@link IndexerLiveness.Unknown} — a check exists but has not yet run.
+     *
+     * @param reads - Where the two heights come from.
+     * @param configuration - The tolerances to apply, and the bound on a single poll.
+     * @param initialVerdict - The verdict to start from. Callers that rebuild the service mid-session pass the verdict
+     *   they already hold, so a reconnect does not erase a `Behind` the check had already reached — starting afresh at
+     *   `Unknown` would hand back a stale-view answer the moment the gate re-opened.
+     * @returns An effect yielding the service.
+     */
+    static make(reads: LivenessReads, configuration?: LivenessConfiguration, initialVerdict?: IndexerLiveness.IndexerLiveness): Effect.Effect<LivenessServiceImpl>;
+    private constructor();
+    state(): Stream.Stream<IndexerLiveness.IndexerLiveness>;
+    startPolling(ticks: Stream.Stream<unknown>): Effect.Effect<void>;
+}
+export {};

package/dist/liveness/livenessService.js

@@ -0,0 +1,201 @@
+// 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 { IndexerLiveness } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { Cause, Data, Deferred, Duration, Effect, identity, Option, Stream, SubscriptionRef } from 'effect';
+/**
+ * A block height could not be read.
+ *
+ * @remarks
+ *   The indexer and the node fail in their own vocabularies — a GraphQL error and a `NodeClientError` respectively. Each
+ *   caller adapts its failure into this one type, so the service depends on neither and needs only what it actually
+ *   uses: a message to report on an {@link IndexerLiveness.Unavailable} verdict.
+ */
+export class LivenessReadError extends Data.TaggedError('LivenessReadError') {
+}
+/**
+ * The default bound on a single poll.
+ *
+ * @remarks
+ *   Comfortably above the node read's own ten-second connection bound, and below the default poll interval, so an
+ *   abandoned poll never delays the tick that follows it.
+ */
+export const DEFAULT_POLL_TIMEOUT = Duration.seconds(20);
+/**
+ * Tolerances sized against Midnight's 6-second block slots (the indexer pins `SLOT_DURATION` at 6000 ms).
+ *
+ * @remarks
+ *   `maxBehindBlocks` is a staleness allowance: ten blocks is about a minute of chain time, generous enough that an
+ *   indexer briefly catching up is not reported as stale. `maxAheadBlocks` absorbs read skew — the two heights are read
+ *   at different moments — while staying far below the thousands of blocks that separate two different networks.
+ */
+export const DEFAULT_LIVENESS_CONFIGURATION = {
+    maxBehindBlocks: 10n,
+    maxAheadBlocks: 10n,
+};
+/**
+ * How often to compare the indexer against the node, by default.
+ *
+ * @remarks
+ *   Deliberately unhurried. Each poll costs a request to a node the wallet does not own, a stalled indexer is a
+ *   slow-developing condition, and polling faster than blocks are produced only re-reads the same block. At Midnight's
+ *   6-second slots, half a minute is about five blocks, and it surfaces a stalled indexer well within the time any
+ *   caller would notice.
+ */
+export const DEFAULT_POLL_INTERVAL = Duration.seconds(30);
+/**
+ * Reduces a failed poll to one line for {@link IndexerLiveness.Unavailable}'s `lastError`.
+ *
+ * @remarks
+ *   That string is shown to whoever is diagnosing a stalled wallet, so it stays a message rather than a rendered cause: a
+ *   stack trace is noise at that surface. Defects are labelled as unexpected, because unlike a read failure they
+ *   indicate a bug rather than an unreachable node.
+ */
+const describeFailure = (cause) => Option.match(Cause.failureOption(cause), {
+    onSome: (error) => error.message,
+    onNone: () => Option.match(Cause.dieOption(cause), {
+        onSome: (defect) => `Unexpected failure while reading: ${defect instanceof Error ? defect.message : String(defect)}`,
+        onNone: () => 'Unexpected failure while reading',
+    }),
+});
+const GenesisCheck = Data.taggedEnum();
+export class LivenessServiceImpl {
+    #state;
+    #reads;
+    #configuration;
+    // The check settles once and is never rewritten. A `Deferred` enforces that where a `Ref` would only promise it: a
+    // second completion is a no-op, and "not yet settled" is the empty `Deferred` rather than a sentinel value.
+    #genesisCheck;
+    /**
+     * Creates a service whose verdict starts as {@link IndexerLiveness.Unknown} — a check exists but has not yet run.
+     *
+     * @param reads - Where the two heights come from.
+     * @param configuration - The tolerances to apply, and the bound on a single poll.
+     * @param initialVerdict - The verdict to start from. Callers that rebuild the service mid-session pass the verdict
+     *   they already hold, so a reconnect does not erase a `Behind` the check had already reached — starting afresh at
+     *   `Unknown` would hand back a stale-view answer the moment the gate re-opened.
+     * @returns An effect yielding the service.
+     */
+    static make(reads, configuration = DEFAULT_LIVENESS_CONFIGURATION, initialVerdict = IndexerLiveness.Unknown()) {
+        return Effect.all([
+            SubscriptionRef.make(initialVerdict),
+            Deferred.make(),
+        ]).pipe(Effect.map(([state, genesisCheck]) => new LivenessServiceImpl(state, reads, configuration, genesisCheck)));
+    }
+    constructor(state, reads, configuration, genesisCheck) {
+        this.#state = state;
+        this.#reads = reads;
+        this.#configuration = configuration;
+        this.#genesisCheck = genesisCheck;
+    }
+    state() {
+        // `changes` already replays the current value before subsequent ones, under the ref's own semaphore. Prepending a
+        // separate `get` would emit the first verdict twice — and read it outside that semaphore.
+        //
+        // `changesWith` then drops a verdict that says nothing new. Every poll writes unconditionally, and each write fans
+        // out into the wallet's full state stream — without this, a healthy idle wallet re-notified every subscriber once
+        // per poll, forever. Structural equality would not do: the heights on `InSync`, `Behind` and `Ahead` advance with
+        // the chain every poll, so consecutive verdicts are never structurally equal. `equivalent` compares what a caller
+        // acts on — the kind, a `Behind`'s lag, `Unavailable`'s climbing count — so a lengthening outage or a growing lag
+        // still reports, and a healthy idle wallet stays quiet.
+        return this.#state.changes.pipe(Stream.changesWith(IndexerLiveness.equivalent));
+    }
+    startPolling(ticks) {
+        return Stream.runForEach(ticks, () => this.#poll());
+    }
+    /**
+     * Compares the two heights once and publishes the result.
+     *
+     * @remarks
+     *   The whole poll is folded into the verdict: `catchAllCause` hands a failed read to `afterFailedPoll`, so the
+     *   returned effect has no error channel and the polling loop survives an unreachable node. `SubscriptionRef.update`
+     *   reads the previous verdict inside the callback, which is what lets `afterFailedPoll` continue a run of failures —
+     *   or keep a `Behind` that a failed poll cannot disprove — without a separate get-then-write race.
+     */
+    #poll() {
+        return this.#compareOnce().pipe(Effect.map((verdict) => () => verdict), 
+        // `disconnect` makes the deadline below a hard one. A timeout interrupts its loser and then waits for it, so a
+        // read stuck inside an uninterruptible region — the node client's connection build is one, and cannot be made
+        // otherwise without leaking the client it builds — would stretch the deadline to the read's own length. Disconnected,
+        // the read is interrupted in the background instead: the verdict lands on time, and a build that does finish still
+        // caches its client for the next poll.
+        Effect.disconnect, 
+        // A bound on the whole poll, not only on the reads' own deadlines: polls run one at a time, so a read that hangs
+        // — an endpoint that accepts a connection and never answers — would otherwise stop the loop forever, freezing
+        // the verdict at whatever was published last. A hung read must not be able to switch the check off.
+        Effect.timeoutFail({
+            duration: this.#configuration.pollTimeout ?? DEFAULT_POLL_TIMEOUT,
+            onTimeout: () => new LivenessReadError({ message: 'Poll abandoned: a read did not complete in time' }),
+        }), 
+        // `catchAllCause`, not `catchAll`: a read can die as well as fail — an unparsed URL, a payload that is not the
+        // shape it claims — and a defect would kill the poll fibre outright. The verdict would then freeze at whatever
+        // was written last, which at start-up is `Unknown` and never gates, leaving an indexer able to switch off the
+        // check simply by answering badly.
+        Effect.catchAllCause((cause) => Effect.succeed((previous) => IndexerLiveness.afterFailedPoll(previous, describeFailure(cause)))), Effect.flatMap((nextVerdict) => SubscriptionRef.update(this.#state, nextVerdict)));
+    }
+    /**
+     * Runs one comparison: the chain identity first, then the heights.
+     *
+     * @remarks
+     *   Height comparison is meaningful only between endpoints on the same chain, so no height verdict is published until
+     *   the genesis hashes have been read once and found to match. A mismatch pins {@link IndexerLiveness.WrongNetwork}
+     *   for the service's lifetime — neither endpoint changes chain until reconfigured, and reconfiguring builds a new
+     *   wallet — while a match is cached so the hashes are read exactly once. A _failed_ hash read proves nothing about
+     *   which chain anyone is on, so it caches nothing: it surfaces through the ordinary `Unavailable` path and the next
+     *   poll tries the hashes again.
+     */
+    #compareOnce() {
+        // `poll` reads without waiting: an empty `Deferred` means the hashes have not yet been compared, so compare them now.
+        return Deferred.poll(this.#genesisCheck).pipe(Effect.flatMap(Option.match({ onNone: () => this.#verifyGenesis(), onSome: identity })), Effect.flatMap(GenesisCheck.$match({
+            Mismatch: ({ verdict }) => Effect.succeed(verdict),
+            SameChain: () => this.#compareTips(),
+        })));
+    }
+    /** Reads both genesis hashes, settles the check, and caches the outcome. */
+    #verifyGenesis() {
+        return Effect.all([this.#reads.indexerGenesisHash(), this.#reads.nodeGenesisHash()], { concurrency: 2 }).pipe(Effect.map(([indexerGenesisHash, nodeGenesisHash]) => IndexerLiveness.sameBlockHash(indexerGenesisHash, nodeGenesisHash)
+            ? GenesisCheck.SameChain()
+            : GenesisCheck.Mismatch({
+                // The genesis comparison is the height-zero case of the same block comparison every poll runs.
+                verdict: IndexerLiveness.WrongNetwork({
+                    height: 0n,
+                    indexerBlockHash: Option.some(indexerGenesisHash),
+                    nodeBlockHash: Option.some(nodeGenesisHash),
+                }),
+            })), Effect.tap((check) => Deferred.succeed(this.#genesisCheck, check)));
+    }
+    /**
+     * Reads both tips, confirms they name the same block where they overlap, and reduces the heights to a verdict.
+     *
+     * @remarks
+     *   Only one extra block is read per poll, and none at all when the two tips are already at the same height: the
+     *   endpoint that trails is reporting the shared block as its own tip, so the only open question is what the endpoint
+     *   that leads names there. Asking both would be a second round trip for an answer already in hand.
+     */
+    #compareTips() {
+        return Effect.all([this.#reads.indexerTip(), this.#reads.finalizedBlock()], { concurrency: 2 }).pipe(Effect.flatMap(([indexer, finalized]) => this.#sharedBlockHash(indexer, finalized).pipe(Effect.map((sharedHash) => IndexerLiveness.evaluateTips({
+            indexer,
+            finalized,
+            sharedHash,
+            maxBehindBlocks: this.#configuration.maxBehindBlocks,
+            maxAheadBlocks: this.#configuration.maxAheadBlocks,
+        })))));
+    }
+    /** Asks whichever endpoint is ahead what it names at the other's height; neither, when the two are level. */
+    #sharedBlockHash(indexer, finalized) {
+        return indexer.height === finalized.height
+            ? Effect.succeed(Option.none())
+            : indexer.height > finalized.height
+                ? this.#reads.indexerBlockHashAt(finalized.height)
+                : this.#reads.nodeBlockHashAt(indexer.height);
+    }
+}

package/dist/pendingTransactions/pendingTransactions.d.ts

@@ -1,5 +1,5 @@
 import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
-import { type DateTime, Either, Option, ParseResult, Schema } from 'effect';
+import { DateTime, Either, Option, ParseResult, Schema } from 'effect';
 export type TransactionTrait<TTransaction> = {
     ids: (tx: TTransaction) => readonly string[];
     firstId: (tx: TTransaction) => string;
@@ -111,9 +111,102 @@ export type OrphanedTransactionItem<TTransaction> = PendingTransactionsItem<TTra
 export type RejectedTransactionItem<TTransaction> = PendingTransactionsItem<TTransaction> & {
     result: FailedTransactionResult | OrphanedByForkResult;
 };
+/**
+ * A transaction that has been balanced but not yet proven or submitted.
+ *
+ * Balancing reserves the coins a transaction will spend, and until the transaction is submitted nothing else records
+ * that those coins are spoken for — so a transaction abandoned in between strands them. A reservation is that missing
+ * record. It never holds the transaction itself: an unproven transaction carries key material and must not be
+ * persisted.
+ *
+ * `identifiers` is what ties a reservation to the transaction that later arrives, and it is stable: proving and binding
+ * both leave a transaction's identifiers unchanged. `intentHashes` is kept alongside because it is the value the ledger
+ * stamps on the coins the transaction creates.
+ */
+export type Reservation = Readonly<{
+    identifiers: readonly string[];
+    intentHashes: readonly string[];
+    /** Ids of the coins this transaction reserved, per wallet, so each wallet can release its own. */
+    inputs: Readonly<{
+        unshielded: readonly string[];
+    }>;
+    /** The transaction's TTL: from this instant the ledger rejects it, so the reservation cannot still be valid. */
+    ttl: Date;
+    createdAt: DateTime.Utc;
+    expired: boolean;
+}>;
 export type PendingTransactions<TTransaction> = Readonly<{
     all: ReadonlyArray<PendingTransactionsItem<TTransaction>>;
+    reservations: ReadonlyArray<Reservation>;
 }>;
+/**
+ * Records a balanced transaction, replacing any earlier reservation for the same spend.
+ *
+ * @example
+ *   const held = addReservation(state, { identifiers: tx.identifiers(), inputs: { unshielded: ids }, ttl });
+ *
+ * @param state - The pending transactions to add to
+ * @param reservation - The record of what the balanced transaction booked
+ * @returns The state with that reservation held, and any it replaces gone
+ */
+export declare const addReservation: <TTransaction>(state: PendingTransactions<TTransaction>, reservation: Reservation) => PendingTransactions<TTransaction>;
+/**
+ * Forgets every reservation holding one of `identifiers`.
+ *
+ * @example
+ *   const cleared = clearReservation(state, [...tx.identifiers()]);
+ *
+ * @param state - The pending transactions to clear from
+ * @param identifiers - Identifiers of the spend whose record is finished with
+ * @returns The state with those reservations gone; identifiers no reservation holds are ignored
+ */
+export declare const clearReservation: <TTransaction>(state: PendingTransactions<TTransaction>, identifiers: readonly string[]) => PendingTransactions<TTransaction>;
+/**
+ * Marks every reservation whose TTL `now` has passed. Marked rather than removed, mirroring how a failed transaction is
+ * kept until a caller has acted on it: the coins still have to be released before the record is dropped.
+ *
+ * Passed, not reached: the ledger accepts an intent while its TTL is at or after the block's timestamp, so a
+ * transaction is still perfectly valid at the instant its TTL names.
+ *
+ * Returns the state it was given when nothing reaches its expiry. This runs on a timer, so most visits change nothing,
+ * and handing back the same value is what lets a caller publish only when something actually moved.
+ *
+ * @example
+ *   const swept = expireReservations(state, DateTime.unsafeNow());
+ *
+ * @param state - The pending transactions to sweep
+ * @param now - The instant to expire against
+ * @returns The state with newly expired reservations marked, or the same state when none is
+ */
+export declare const expireReservations: <TTransaction>(state: PendingTransactions<TTransaction>, now: DateTime.Utc) => PendingTransactions<TTransaction>;
+/**
+ * The unshielded coin ids some spend still accounts for.
+ *
+ * Every reservation's inputs, plus the inputs of every transaction being tracked. Both halves are needed: a reservation
+ * covers a transaction that was balanced and never submitted, and registering a transaction drops the reservation
+ * standing in for it, so from submission onwards only the tracked transaction says the coins are spoken for.
+ *
+ * @example
+ *   const spokenFor = coveredUnshieldedIds(pending, (tx) => ownInputIdsOf(tx));
+ *
+ * @param state - The reservations and tracked transactions to read
+ * @param unshieldedInputsOf - How to name the unshielded coins a tracked transaction spends
+ * @returns Every such coin id, without repeats
+ */
+export declare const coveredUnshieldedIds: <TTransaction>(state: PendingTransactions<TTransaction>, unshieldedInputsOf: (tx: TTransaction) => readonly string[]) => readonly string[];
+/**
+ * The reservations whose transactions can no longer be accepted, and whose coins are therefore free.
+ *
+ * Expiry marks a reservation rather than removing it, so this is what a caller reads to find the records it still has
+ * to act on before dropping them.
+ *
+ * @example
+ *   const finished = allExpiredReservations(state);
+ *
+ * @param state - The pending transactions to read
+ * @returns The marked reservations, in the order they were added; empty when none has expired
+ */
+export declare const allExpiredReservations: <TTransaction>(state: PendingTransactions<TTransaction>) => ReadonlyArray<Reservation>;
 export declare const has: <TTransaction>(transactions: PendingTransactions<TTransaction>, transaction: TTransaction, traits: VersionedTransactionTrait<TTransaction>) => boolean;
 export declare const all: <TTransaction>(transactions: PendingTransactions<TTransaction>) => readonly TTransaction[];
 export declare const allFailed: <TTransaction>(transactions: PendingTransactions<TTransaction>) => ReadonlyArray<FailedTransactionItem<TTransaction>>;
@@ -153,9 +246,17 @@ export declare const saveResult: <TTransaction>(state: PendingTransactions<TTran
  * @returns The pending transactions with the stranded ones given an {@link OrphanedByForkResult}.
  */
 export declare const orphanBeyond: <TTransaction>(state: PendingTransactions<TTransaction>, traits: VersionedTransactionTrait<TTransaction>, chainNow: ProtocolVersion.ProtocolVersion) => PendingTransactions<TTransaction>;
+/**
+ * The stored shape. Reservations arrived after the format was already in the field, so they are an optional member of
+ * the version that was already there rather than a version of their own: a reader that predates them sees the version
+ * it knows and ignores the member it does not, which is what keeps a store written here readable by an older package.
+ *
+ * A snapshot that omits them records no reservations, which is the truth about what the writer knew.
+ */
 type Serialized<TTransaction> = Readonly<{
     version: 'v1';
     transactions: readonly PendingItem<TTransaction>[];
+    reservations: readonly Reservation[];
 }>;
 export declare const SerializedSchema: <TTransaction>(traits: VersionedTransactionTrait<TTransaction>) => Schema.Schema<Serialized<TTransaction>, any>;
 export declare const serialize: <TTransaction>(state: PendingTransactions<TTransaction>, traits: VersionedTransactionTrait<TTransaction>) => string;

package/dist/pendingTransactions/pendingTransactions.js

@@ -14,7 +14,7 @@
  */
 import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
 import { Buffer } from 'buffer';
-import { Array as Arr, Either, Option, Order, ParseResult, pipe, Schema } from 'effect';
+import { Array as Arr, DateTime, Either, Option, Order, ParseResult, pipe, Schema } from 'effect';
 /** Registers one trait for every protocol version: the shape a wallet that speaks a single ledger version has. */
 export const singleTrait = (trait) => ({
     entries: [
@@ -60,6 +60,90 @@ const idsOf = (traits, tx) => traitForTx(traits, tx).pipe(Option.map((trait) =>
 const idsOfItem = (traits, item) => traitOfItem(traits, item).pipe(Option.map((trait) => trait.ids(item.tx)), Option.getOrElse(() => []));
 /** Whether a stored item is covered by the identifiers of an incoming transaction, each read with its own trait. */
 const isCoveredBy = (traits, item, txIds) => traitOfItem(traits, item).pipe(Option.map((trait) => trait.areAllTxIdsIncluded(item.tx, txIds)), Option.getOrElse(() => false));
+/** Two reservations, or a reservation and a transaction, are the same spend if they share any identifier. */
+const sharesIdentifier = (reservation, identifiers) => reservation.identifiers.some((id) => identifiers.includes(id));
+/**
+ * Records a balanced transaction, replacing any earlier reservation for the same spend.
+ *
+ * @example
+ *   const held = addReservation(state, { identifiers: tx.identifiers(), inputs: { unshielded: ids }, ttl });
+ *
+ * @param state - The pending transactions to add to
+ * @param reservation - The record of what the balanced transaction booked
+ * @returns The state with that reservation held, and any it replaces gone
+ */
+export const addReservation = (state, reservation) => ({
+    ...state,
+    reservations: Arr.append(Arr.filter(state.reservations, (existing) => !sharesIdentifier(existing, reservation.identifiers)), reservation),
+});
+/**
+ * Forgets every reservation holding one of `identifiers`.
+ *
+ * @example
+ *   const cleared = clearReservation(state, [...tx.identifiers()]);
+ *
+ * @param state - The pending transactions to clear from
+ * @param identifiers - Identifiers of the spend whose record is finished with
+ * @returns The state with those reservations gone; identifiers no reservation holds are ignored
+ */
+export const clearReservation = (state, identifiers) => ({
+    ...state,
+    reservations: Arr.filter(state.reservations, (reservation) => !sharesIdentifier(reservation, identifiers)),
+});
+/**
+ * Marks every reservation whose TTL `now` has passed. Marked rather than removed, mirroring how a failed transaction is
+ * kept until a caller has acted on it: the coins still have to be released before the record is dropped.
+ *
+ * Passed, not reached: the ledger accepts an intent while its TTL is at or after the block's timestamp, so a
+ * transaction is still perfectly valid at the instant its TTL names.
+ *
+ * Returns the state it was given when nothing reaches its expiry. This runs on a timer, so most visits change nothing,
+ * and handing back the same value is what lets a caller publish only when something actually moved.
+ *
+ * @example
+ *   const swept = expireReservations(state, DateTime.unsafeNow());
+ *
+ * @param state - The pending transactions to sweep
+ * @param now - The instant to expire against
+ * @returns The state with newly expired reservations marked, or the same state when none is
+ */
+export const expireReservations = (state, now) => {
+    const hasExpiry = (reservation) => !reservation.expired && reservation.ttl.getTime() < DateTime.toEpochMillis(now);
+    return Arr.some(state.reservations, hasExpiry)
+        ? {
+            ...state,
+            reservations: Arr.map(state.reservations, (reservation) => hasExpiry(reservation) ? { ...reservation, expired: true } : reservation),
+        }
+        : state;
+};
+/**
+ * The unshielded coin ids some spend still accounts for.
+ *
+ * Every reservation's inputs, plus the inputs of every transaction being tracked. Both halves are needed: a reservation
+ * covers a transaction that was balanced and never submitted, and registering a transaction drops the reservation
+ * standing in for it, so from submission onwards only the tracked transaction says the coins are spoken for.
+ *
+ * @example
+ *   const spokenFor = coveredUnshieldedIds(pending, (tx) => ownInputIdsOf(tx));
+ *
+ * @param state - The reservations and tracked transactions to read
+ * @param unshieldedInputsOf - How to name the unshielded coins a tracked transaction spends
+ * @returns Every such coin id, without repeats
+ */
+export const coveredUnshieldedIds = (state, unshieldedInputsOf) => pipe(Arr.appendAll(Arr.flatMap(state.reservations, (reservation) => reservation.inputs.unshielded), Arr.flatMap(state.all, (item) => unshieldedInputsOf(item.tx))), Arr.dedupe);
+/**
+ * The reservations whose transactions can no longer be accepted, and whose coins are therefore free.
+ *
+ * Expiry marks a reservation rather than removing it, so this is what a caller reads to find the records it still has
+ * to act on before dropping them.
+ *
+ * @example
+ *   const finished = allExpiredReservations(state);
+ *
+ * @param state - The pending transactions to read
+ * @returns The marked reservations, in the order they were added; empty when none has expired
+ */
+export const allExpiredReservations = (state) => Arr.filter(state.reservations, (reservation) => reservation.expired);
 export const has = (transactions, transaction, traits) => traitForTx(traits, transaction).pipe(Option.map((trait) => transactions.all.some((item) => trait.areAllTxIdsIncluded(transaction, idsOfItem(traits, item)))), Option.getOrElse(() => false));
 export const all = (transactions) => {
     return transactions.all.map((item) => item.tx);
@@ -88,6 +172,7 @@ export const allPending = (state) => {
 export const empty = () => {
     return {
         all: [],
+        reservations: [],
     };
 };
 /**
@@ -115,6 +200,8 @@ export const addPendingTransaction = (state, tx, now, traits, protocolVersion) =
     return {
         ...state,
         all: Arr.append(rest, theBiggestMatchingTx),
+        // The transaction now stands for the spend its reservation was holding open, and carries the same identifiers.
+        reservations: Arr.filter(state.reservations, (reservation) => !sharesIdentifier(reservation, idsOf(traits, tx))),
     };
 };
 export const clear = (state, tx, traits) => {
@@ -122,6 +209,8 @@ export const clear = (state, tx, traits) => {
     return {
         ...state,
         all: Arr.filter(state.all, (item) => !isCoveredBy(traits, item, txIds)),
+        // Whatever stopped tracking the transaction — a revert, or a spend that confirmed — also ends the reservation.
+        reservations: Arr.filter(state.reservations, (reservation) => !sharesIdentifier(reservation, txIds)),
     };
 };
 export const saveResult = (state, tx, result, traits) => {
@@ -156,6 +245,14 @@ export const orphanBeyond = (state, traits, chainNow) => ({
         })),
 });
 const hasEpochEnded = (traits, authoredFor, chainNow) => ProtocolVersion.selectEntry(traits, authoredFor).pipe(Option.map((entry) => chainNow >= entry.range[1]), Option.getOrElse(() => false));
+const ReservationSchema = Schema.Struct({
+    identifiers: Schema.Array(Schema.String),
+    intentHashes: Schema.Array(Schema.String),
+    inputs: Schema.Struct({ unshielded: Schema.Array(Schema.String) }),
+    ttl: Schema.Date,
+    createdAt: Schema.DateTimeUtc,
+    expired: Schema.Boolean,
+});
 const WireItemSchema = Schema.Struct({
     tx: Schema.String,
     creationTime: Schema.DateTimeUtc,
@@ -184,6 +281,7 @@ const PendingItemSchema = (traits) => {
 export const SerializedSchema = (traits) => Schema.Struct({
     version: Schema.Literal('v1'),
     transactions: Schema.Array(PendingItemSchema(traits)),
+    reservations: Schema.optionalWith(Schema.Array(ReservationSchema), { default: () => [] }),
 });
 export const serialize = (state, traits) => pipe(state, toSerialized, Schema.encodeSync(SerializedSchema(traits)), JSON.stringify);
 export const deserialize = (serialized, traits) => {
@@ -193,10 +291,12 @@ export const toSerialized = (pendingTransactions) => {
     return {
         version: 'v1',
         transactions: pendingTransactions.all,
+        reservations: pendingTransactions.reservations,
     };
 };
 export const fromSerialized = (serialized) => {
     return {
         all: serialized.transactions,
+        reservations: serialized.reservations,
     };
 };

package/dist/pendingTransactions/pendingTransactionsService.d.ts

@@ -21,6 +21,33 @@ export type PendingTransactionsService<TTransaction> = {
      * @param chainNow The protocol version the wallets have reached.
      */
     orphanBeyond: (chainNow: ProtocolVersion.ProtocolVersion) => Promise<void>;
+    /**
+     * Records that a balanced transaction has coins reserved, before it is proven or submitted.
+     *
+     * Between balancing and submission nothing else says those coins are spoken for, so this is the only durable record
+     * of them. Any earlier reservation sharing an identifier is replaced, so re-balancing the same spend does not
+     * accumulate records.
+     *
+     * @example
+     *   await service.addReservation({ identifiers: tx.identifiers(), inputs: { unshielded: ids }, ttl, ... });
+     *
+     * @param reservation - What the balanced transaction booked, and when the ledger stops accepting it
+     * @returns A promise that resolves once the record is held
+     */
+    addReservation: (reservation: PendingTransactions.Reservation) => Promise<void>;
+    /**
+     * Forgets the reservation holding any of `identifiers`, once its coins have been released.
+     *
+     * Call it wherever the booking it stands for ends: the transaction is registered and tracked on its own, the booking
+     * is reverted, or the record has expired. A record left behind outlives the coins it named.
+     *
+     * @example
+     *   await service.clearReservation([...tx.identifiers()]);
+     *
+     * @param identifiers - Identifiers of the spend whose record is finished with; unknown ones are ignored
+     * @returns A promise that resolves once the record is gone
+     */
+    clearReservation: (identifiers: readonly string[]) => Promise<void>;
 };
 export type IndexerClientConnection = {
     indexerHttpUrl: string;
@@ -43,6 +70,8 @@ export declare class PendingTransactionsServiceImpl<TTransaction> implements Pen
     addPendingTransaction(tx: TTransaction, protocolVersion: Option.Option<ProtocolVersion.ProtocolVersion>): Promise<void>;
     clear(tx: TTransaction): Promise<void>;
     orphanBeyond(chainNow: ProtocolVersion.ProtocolVersion): Promise<void>;
+    addReservation(reservation: PendingTransactions.Reservation): Promise<void>;
+    clearReservation(identifiers: readonly string[]): Promise<void>;
     start(): Promise<void>;
     state(): rx.Observable<PendingTransactions.PendingTransactions<TTransaction>>;
     stop(): Promise<void>;
@@ -53,14 +82,25 @@ export type PendingTransactionsServiceEffect<TTransaction> = {
     addPendingTransaction: (tx: TTransaction, protocolVersion: Option.Option<ProtocolVersion.ProtocolVersion>) => Effect.Effect<void, never, never>;
     clear: (tx: TTransaction) => Effect.Effect<void, never, never>;
     orphanBeyond: (chainNow: ProtocolVersion.ProtocolVersion) => Effect.Effect<void, never, never>;
+    addReservation: (reservation: PendingTransactions.Reservation) => Effect.Effect<void, never, never>;
+    clearReservation: (identifiers: readonly string[]) => Effect.Effect<void, never, never>;
 };
 export declare class PendingTransactionsServiceEffectImpl<TTransaction> implements PendingTransactionsServiceEffect<TTransaction> {
     #private;
     static restore<TTransaction>(data: string, txTraits: PendingTransactions.VersionedTransactionTrait<TTransaction>): Effect.Effect<PendingTransactionsServiceEffectImpl<TTransaction>, ParseResult.ParseError>;
     constructor(txTraits: PendingTransactions.VersionedTransactionTrait<TTransaction>, initialState?: PendingTransactions.PendingTransactions<TTransaction>);
+    /**
+     * The state, published when it moves. The poll writes the ref on every tick whether or not anything expired, and a
+     * write publishes regardless, so consecutive identical values are dropped here. Every real change builds a new value,
+     * so comparing by identity keeps a change from being mistaken for a repeat.
+     */
     state(): Stream.Stream<PendingTransactions.PendingTransactions<TTransaction>>;
     startPolling(ticks: Stream.Stream<unknown>): Effect.Effect<void, Error, QueryClient | Scope.Scope>;
     addPendingTransaction(tx: TTransaction, protocolVersion: Option.Option<ProtocolVersion.ProtocolVersion>): Effect.Effect<void>;
+    addReservation(reservation: PendingTransactions.Reservation): Effect.Effect<void>;
+    clearReservation(identifiers: readonly string[]): Effect.Effect<void>;
+    /** Marks the reservations whose transactions the ledger would no longer accept. Runs on every poll. */
+    private expireReservations;
     clear(tx: TTransaction): Effect.Effect<void>;
     orphanBeyond(chainNow: ProtocolVersion.ProtocolVersion): Effect.Effect<void>;
     private saveResult;

package/dist/pendingTransactions/pendingTransactionsService.js

@@ -48,6 +48,12 @@ export class PendingTransactionsServiceImpl {
     orphanBeyond(chainNow) {
         return this.#effectService.orphanBeyond(chainNow).pipe(Effect.runPromise);
     }
+    addReservation(reservation) {
+        return this.#effectService.addReservation(reservation).pipe(Effect.runPromise);
+    }
+    clearReservation(identifiers) {
+        return this.#effectService.clearReservation(identifiers).pipe(Effect.runPromise);
+    }
     start() {
         return this.#effectService.startPolling(Stream.tick(Duration.seconds(1))).pipe(Effect.provide(HttpQueryClient.layer({
             url: this.#configuration.indexerClientConnection.indexerHttpUrl,
@@ -70,11 +76,19 @@ export class PendingTransactionsServiceEffectImpl {
         this.#txTraits = txTraits;
         this.#state = SubscriptionRef.make(initialState ?? PendingTransactions.empty()).pipe(Effect.runSync); // Should not be here, but otherwise initialization would be too involved
     }
+    /**
+     * The state, published when it moves. The poll writes the ref on every tick whether or not anything expired, and a
+     * write publishes regardless, so consecutive identical values are dropped here. Every real change builds a new value,
+     * so comparing by identity keeps a change from being mistaken for a repeat.
+     */
     state() {
-        return Stream.concat(Stream.fromEffect(SubscriptionRef.get(this.#state)), this.#state.changes);
+        return Stream.concat(Stream.fromEffect(SubscriptionRef.get(this.#state)), this.#state.changes).pipe(Stream.changesWith((a, b) => a === b));
     }
     startPolling(ticks) {
-        return ticks.pipe(Stream.mapEffect(() => SubscriptionRef.get(this.#state)), Stream.mapConcat(PendingTransactions.allPending), Stream.mapConcatEffect((item) => {
+        return ticks.pipe(
+        // A reservation stands in for a transaction that was never submitted, so no indexer query can settle it. The
+        // only thing that can is its TTL, checked on the same beat that reaps the transactions.
+        Stream.tap(() => this.expireReservations()), Stream.mapEffect(() => SubscriptionRef.get(this.#state)), Stream.mapConcat(PendingTransactions.allPending), Stream.mapConcatEffect((item) => {
             return Effect.gen(this, function* () {
                 const now = yield* DateTime.now;
                 const trait = PendingTransactions.traitForVersion(this.#txTraits, item.protocolVersion);
@@ -105,6 +119,16 @@ export class PendingTransactionsServiceEffectImpl {
             return DateTime.now.pipe(Effect.andThen((now) => PendingTransactions.addPendingTransaction(state, tx, now, this.#txTraits, protocolVersion)));
         });
     }
+    addReservation(reservation) {
+        return SubscriptionRef.update(this.#state, (state) => PendingTransactions.addReservation(state, reservation));
+    }
+    clearReservation(identifiers) {
+        return SubscriptionRef.update(this.#state, (state) => PendingTransactions.clearReservation(state, identifiers));
+    }
+    /** Marks the reservations whose transactions the ledger would no longer accept. Runs on every poll. */
+    expireReservations() {
+        return SubscriptionRef.updateEffect(this.#state, (state) => DateTime.now.pipe(Effect.map((now) => PendingTransactions.expireReservations(state, now))));
+    }
     clear(tx) {
         return SubscriptionRef.update(this.#state, (state) => {
             return PendingTransactions.clear(state, tx, this.#txTraits);
@@ -135,6 +159,10 @@ export class PendingTransactionsServiceEffectImpl {
                 return pipe(Effect.logWarning(error, 'Observed error in PendingTransactionsService, retrying'), Effect.as(fallback));
             }));
             return pipe(result.transactions, Iterable.filterMap((res) => {
+                // Only RegularTransaction carries the identifiers and transactionResult this matching
+                // needs — and wallet-submitted transactions are always regular. Narrowing to it (rather
+                // than excluding known other variants) keeps future schema variants ignored instead of
+                // breaking compilation, as BridgeClaimTransaction (indexer 4.4.0) once did.
                 if (res.__typename !== 'RegularTransaction') {
                     return Option.none();
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midnight-ntwrk/wallet-sdk-capabilities",
-  "version": "4.0.0-rc.0",
+  "version": "4.0.0-rc.1",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -65,9 +65,9 @@
     "@midnight-ntwrk/ledger-v8": "^8.1.0",
     "@midnight-ntwrk/zkir-v2": "^2.1.0",
     "@midnightntwrk/ledger-v9": "1.0.0-rc.5",
-    "@midnight-ntwrk/wallet-sdk-abstractions": "3.0.0-rc.0",
-    "@midnight-ntwrk/wallet-sdk-indexer-client": "2.0.0-rc.0",
-    "@midnight-ntwrk/wallet-sdk-node-client": "2.0.0-rc.0",
+    "@midnight-ntwrk/wallet-sdk-abstractions": "3.0.0-rc.1",
+    "@midnight-ntwrk/wallet-sdk-indexer-client": "2.0.0-rc.1",
+    "@midnight-ntwrk/wallet-sdk-node-client": "2.0.0-rc.1",
     "@midnight-ntwrk/wallet-sdk-prover-client": "2.0.0-rc.0",
     "@midnight-ntwrk/wallet-sdk-utilities": "1.2.2-rc.0",
     "effect": "^3.19.19",
@@ -76,8 +76,8 @@
   "devDependencies": {
     "@effect/cluster": "0.60.2",
     "@effect/experimental": "0.61.1",
-    "@effect/platform": "0.97.1",
-    "@effect/platform-node": "0.108.1",
+    "@effect/platform": "0.97.2",
+    "@effect/platform-node": "0.108.2",
     "@effect/rpc": "0.76.2",
     "@effect/sql": "0.52.1",
     "@effect/workflow": "0.19.1",