@midnightntwrk/wallet-sdk-node-client 2.0.0-rc.0 → 2.0.0-rc.1

package/dist/effect/NodeClient.d.ts

@@ -1,18 +1,148 @@
-import { Context, Effect, Stream } from 'effect';
+import { Context, Effect, Option, Stream } from 'effect';
 import * as SubmissionEvent from './SubmissionEvent.js';
 import * as NodeClientError from './NodeClientError.js';
 import { type SerializedTransaction } from '@midnightntwrk/wallet-sdk-abstractions';
 export type Genesis = {
     readonly transactions: readonly SerializedTransaction.SerializedTransaction[];
 };
+/**
+ * The node's highest block that GRANDPA has finalized.
+ *
+ * @remarks
+ *   This is the reference a wallet compares an indexer's self-reported position against. It comes from consensus rather
+ *   than from the indexer, which is what makes the comparison meaningful.
+ */
+export type FinalizedBlock = {
+    /** The hash of the finalized block, hex-encoded. */
+    readonly hash: string;
+    /** The height of the finalized block. */
+    readonly height: bigint;
+};
 export interface Service {
     sendMidnightTransaction(serializedTransaction: SerializedTransaction.SerializedTransaction): Stream.Stream<SubmissionEvent.SubmissionEvent, NodeClientError.NodeClientError>;
     getGenesis(): Effect.Effect<Genesis, NodeClientError.NodeClientError>;
+    /**
+     * Reads the node's highest finalized block.
+     *
+     * @remarks
+     *   Finalized, not best: the wallet's liveness check compares an indexer's self-reported position against this value,
+     *   and the indexer ingests finalized blocks only. An implementation that answered with the best (latest, possibly
+     *   reverted) head would report a healthy indexer as behind by the finality gap on every poll. The default
+     *   implementation reads the finalized head's hash and then the header at that hash, so the two fields describe the
+     *   same block.
+     *
+     *   Must be safe to call while a `sendMidnightTransaction` is in flight on the same instance: the liveness check polls
+     *   on a timer and takes no lock. The default implementation reference-counts its shared connection and disconnects
+     *   only when the last in-flight call finishes, so a read completing never drops a submission's status subscription.
+     *
+     *   An unreachable node must surface as a typed `NodeClientError`, not a defect: the liveness check turns that failure
+     *   into an `Unavailable` verdict, and a defect would kill its poll instead.
+     * @example
+     *   ```ts
+     *   const { hash, height } = yield* client.getFinalizedBlock();
+     *   ```;
+     *
+     * @returns An effect yielding the hex-encoded hash and the height of the highest block GRANDPA has finalized.
+     */
+    getFinalizedBlock(): Effect.Effect<FinalizedBlock, NodeClientError.NodeClientError>;
+    /**
+     * Reads the hash of the block at a given height.
+     *
+     * @remarks
+     *   This is what makes the wallet's liveness check a comparison of blocks rather than of numbers. A height is a value
+     *   the indexer chooses, so an indexer reporting one it never reached passes a height-only comparison at no cost; the
+     *   block at that height is the part it cannot invent. The check reads one block here per poll — the newest block
+     *   both endpoints claim to have passed — and compares it against what the indexer names there.
+     *
+     *   `height` is at or below the node's own finalized head, so an implementation may answer from finalized blocks only.
+     *   A canonical chain has a block at every such height, which is what makes absence meaningful: it says this node
+     *   does not have the block the indexer is claiming, not that the read went wrong. Absence is therefore `Option.none`
+     *   rather than a failure — to the liveness check one is a wrong-network proof and the other an outage.
+     *
+     *   An unreachable node must surface as a typed `NodeClientError`, not a defect, for the same reason as
+     *   {@link Service.getFinalizedBlock}: the check turns that failure into an `Unavailable` verdict, and a defect would
+     *   kill its poll instead.
+     * @example
+     *   ```ts
+     *   const hash = yield* client.getBlockHashAt(1_000n);
+     *   // Option.some('0x1234…'), or Option.none() when this node has no block at that height
+     *   ```;
+     *
+     * @param height - The height to read, at or below the node's finalized head.
+     * @returns An effect yielding the block's hex-encoded hash, or `Option.none` when the node has no block at that
+     *   height.
+     */
+    getBlockHashAt(height: bigint): Effect.Effect<Option.Option<string>, NodeClientError.NodeClientError>;
+    /**
+     * Reads the hash of the node's genesis block.
+     *
+     * @remarks
+     *   Identifies the chain the node is on. The wallet compares it, once, against the indexer's block at height zero, and
+     *   pins a `WrongNetwork` verdict when they differ — so this must be the hash of block zero, not of any later
+     *   checkpoint. The comparison is by bytes, tolerant of a `0x` prefix and of case, but the convention on this
+     *   interface is a lowercase, `0x`-prefixed hex string, which is what the default implementation returns.
+     *
+     *   Should not require a live connection. The default implementation answers from state the api captured when it was
+     *   created, so the check can establish the chain identity even while the node is temporarily unreachable.
+     * @example
+     *   ```ts
+     *   const genesisHash = yield* client.getGenesisHash();
+     *   // '0x1234…' — compare with IndexerLiveness.sameBlockHash(indexerHash, genesisHash)
+     *   ```;
+     *
+     * @returns An effect yielding the genesis-block hash as a `0x`-prefixed hex string.
+     */
+    getGenesisHash(): Effect.Effect<string, NodeClientError.NodeClientError>;
 }
 declare const NodeClient_base: Context.TagClass<NodeClient, "@midnight-ntwrk/wallet-node-client#NodeClient", Service>;
 export declare class NodeClient extends NodeClient_base {
 }
 export declare const getGenesisTransactions: () => Effect.Effect<Genesis, NodeClientError.NodeClientError, NodeClient>;
+/**
+ * Reads the node's highest finalized block.
+ *
+ * @remarks
+ *   Safe to interleave with other calls on the same service instance: the default implementation reference-counts its
+ *   shared connection and disconnects only when the last in-flight call finishes, so a read completing never drops an
+ *   in-flight `sendMidnightTransaction`'s status subscription.
+ * @example
+ *   ```ts
+ *   const finalized = yield* NodeClient.getFinalizedBlock();
+ *   ```;
+ *
+ * @returns An effect yielding the hash and height of the highest block GRANDPA has finalized.
+ */
+export declare const getFinalizedBlock: () => Effect.Effect<FinalizedBlock, NodeClientError.NodeClientError, NodeClient>;
+/**
+ * Reads the hash of the block at a given height.
+ *
+ * @remarks
+ *   The wallet's liveness check reads one block per poll through this, to compare the block the indexer names at that
+ *   height rather than only the height itself. Absence is `Option.none` rather than a failure: a node with no block at
+ *   a height below its own finalized head is answering that it does not have the block being claimed.
+ * @example
+ *   ```ts
+ *   const hash = yield* NodeClient.getBlockHashAt(1_000n);
+ *   ```;
+ *
+ * @param height - The height to read, at or below the node's finalized head.
+ * @returns An effect yielding the block's hex-encoded hash, or `Option.none` when the node has no block at that height.
+ */
+export declare const getBlockHashAt: (height: bigint) => Effect.Effect<Option.Option<string>, NodeClientError.NodeClientError, NodeClient>;
+/**
+ * Reads the hash of the node's genesis block.
+ *
+ * @remarks
+ *   Identifies the chain the node is on: two endpoints reporting different genesis hashes are on different networks. The
+ *   default implementation answers from state the client already holds, without opening a connection.
+ * @example
+ *   ```ts
+ *   const genesisHash = yield* NodeClient.getGenesisHash();
+ *   ```;
+ *
+ * @returns An effect yielding the genesis-block hash as a `0x`-prefixed hex string.
+ */
+export declare const getGenesisHash: () => Effect.Effect<string, NodeClientError.NodeClientError, NodeClient>;
 export declare const sendMidnightTransaction: (serializedTransaction: SerializedTransaction.SerializedTransaction) => Stream.Stream<SubmissionEvent.SubmissionEvent, NodeClientError.NodeClientError, NodeClient>;
 export declare function sendMidnightTransactionAndWait(serializedTransaction: SerializedTransaction.SerializedTransaction, waitFor: SubmissionEvent.Cases.Submitted['_tag']): Effect.Effect<SubmissionEvent.Cases.Submitted, NodeClientError.NodeClientError, NodeClient>;
 export declare function sendMidnightTransactionAndWait(serializedTransaction: SerializedTransaction.SerializedTransaction, waitFor: SubmissionEvent.Cases.InBlock['_tag']): Effect.Effect<SubmissionEvent.Cases.InBlock, NodeClientError.NodeClientError, NodeClient>;

package/dist/effect/NodeClient.js

@@ -16,6 +16,51 @@ import * as NodeClientError from './NodeClientError.js';
 export class NodeClient extends Context.Tag('@midnight-ntwrk/wallet-node-client#NodeClient')() {
 }
 export const getGenesisTransactions = () => NodeClient.pipe(Effect.flatMap((client) => client.getGenesis()));
+/**
+ * Reads the node's highest finalized block.
+ *
+ * @remarks
+ *   Safe to interleave with other calls on the same service instance: the default implementation reference-counts its
+ *   shared connection and disconnects only when the last in-flight call finishes, so a read completing never drops an
+ *   in-flight `sendMidnightTransaction`'s status subscription.
+ * @example
+ *   ```ts
+ *   const finalized = yield* NodeClient.getFinalizedBlock();
+ *   ```;
+ *
+ * @returns An effect yielding the hash and height of the highest block GRANDPA has finalized.
+ */
+export const getFinalizedBlock = () => NodeClient.pipe(Effect.flatMap((client) => client.getFinalizedBlock()));
+/**
+ * Reads the hash of the block at a given height.
+ *
+ * @remarks
+ *   The wallet's liveness check reads one block per poll through this, to compare the block the indexer names at that
+ *   height rather than only the height itself. Absence is `Option.none` rather than a failure: a node with no block at
+ *   a height below its own finalized head is answering that it does not have the block being claimed.
+ * @example
+ *   ```ts
+ *   const hash = yield* NodeClient.getBlockHashAt(1_000n);
+ *   ```;
+ *
+ * @param height - The height to read, at or below the node's finalized head.
+ * @returns An effect yielding the block's hex-encoded hash, or `Option.none` when the node has no block at that height.
+ */
+export const getBlockHashAt = (height) => NodeClient.pipe(Effect.flatMap((client) => client.getBlockHashAt(height)));
+/**
+ * Reads the hash of the node's genesis block.
+ *
+ * @remarks
+ *   Identifies the chain the node is on: two endpoints reporting different genesis hashes are on different networks. The
+ *   default implementation answers from state the client already holds, without opening a connection.
+ * @example
+ *   ```ts
+ *   const genesisHash = yield* NodeClient.getGenesisHash();
+ *   ```;
+ *
+ * @returns An effect yielding the genesis-block hash as a `0x`-prefixed hex string.
+ */
+export const getGenesisHash = () => NodeClient.pipe(Effect.flatMap((client) => client.getGenesisHash()));
 export const sendMidnightTransaction = (serializedTransaction) => NodeClient.pipe(Stream.fromEffect, Stream.flatMap((client) => client.sendMidnightTransaction(serializedTransaction)));
 export function sendMidnightTransactionAndWait(serializedTransaction, waitFor) {
     return sendMidnightTransaction(serializedTransaction).pipe(Stream.find(SubmissionEvent.is(waitFor)), Stream.runHead, Effect.flatMap(Option.match({

package/dist/effect/PolkadotNodeClient.d.ts

@@ -1,6 +1,6 @@
 import '../gen/augment-api.js';
 import { ApiPromise } from '@polkadot/api';
-import { Duration, Effect, Layer, type Scope, Stream } from 'effect';
+import { Duration, Effect, Layer, Option, type Scope, Stream, SynchronizedRef } from 'effect';
 import * as NodeClient from './NodeClient.js';
 import * as SubmissionEvent from './SubmissionEvent.js';
 import * as NodeClientError from './NodeClientError.js';
@@ -21,10 +21,13 @@ export declare class PolkadotNodeClient implements NodeClient.Service {
     static layer(configInput: Partial<Config> & Pick<Config, 'nodeURL'>): Layer.Layer<NodeClient.NodeClient, NodeClientError.NodeClientError, Scope.Scope>;
     readonly config: Config;
     readonly api: ApiPromise;
-    constructor(config: Config, api: ApiPromise);
+    constructor(config: Config, api: ApiPromise, activeCalls: SynchronizedRef.SynchronizedRef<number>);
     ensureConnection(): Effect.Effect<void, NodeClientError.NodeClientError>;
     sendMidnightTransaction(serializedTransaction: SerializedTransaction.SerializedTransaction): Stream.Stream<SubmissionEvent.SubmissionEvent, NodeClientError.NodeClientError>;
     getGenesis(): Effect.Effect<{
         readonly transactions: readonly SerializedTransaction.SerializedTransaction[];
     }, NodeClientError.NodeClientError>;
+    getGenesisHash(): Effect.Effect<string, NodeClientError.NodeClientError>;
+    getFinalizedBlock(): Effect.Effect<NodeClient.FinalizedBlock, NodeClientError.NodeClientError>;
+    getBlockHashAt(height: bigint): Effect.Effect<Option.Option<string>, NodeClientError.NodeClientError>;
 }

package/dist/effect/PolkadotNodeClient.js

@@ -12,13 +12,78 @@
 // limitations under the License.
 import '../gen/augment-api.js';
 import { ApiPromise, WsProvider } from '@polkadot/api';
-import { Duration, Effect, Either, Layer, pipe, Schedule, Schema, Stream, } from 'effect';
+import { Duration, Effect, Either, Layer, Option, pipe, Ref, Schedule, Schema, Stream, SynchronizedRef, } from 'effect';
 import * as NodeClient from './NodeClient.js';
 import * as SubmissionEvent from './SubmissionEvent.js';
 import * as NodeClientError from './NodeClientError.js';
 import BN from 'bn.js';
 import { u8aToHex } from '@polkadot/util';
 import { SerializedTransaction } from '@midnightntwrk/wallet-sdk-abstractions';
+/**
+ * How many consecutive readiness probes may fail on a connected socket before the failure is surfaced.
+ *
+ * @remarks
+ *   Small, because each failure on a connected socket already says the node is answering the transport but not RPC — more
+ *   retries only delay the verdict. Three tolerates a probe racing a reconnect that has not finished re-initialising,
+ *   without letting a genuinely broken node hide behind an unbounded retry loop.
+ */
+const MAX_CONNECTED_PROBE_FAILURES = 3;
+/**
+ * Clamps a duration to the largest delay `setTimeout` honours.
+ *
+ * @remarks
+ *   A delay of 2^31 ms or more overflows and fires after about a millisecond, which turned a generous bound such as 30
+ *   days into an instant failure on every connection attempt. A bound that large behaves as "still waiting" on any
+ *   human timescale, so the clamp loses nothing.
+ */
+const toTimerMillis = (duration) => Math.min(Duration.toMillis(duration), 2 ** 31 - 1);
+/**
+ * Recognises the hash the chain RPC answers with for a height it has no block at.
+ *
+ * @remarks
+ *   It is a well-formed hash of all zeroes rather than an error, so only its value distinguishes "no such block" from a
+ *   real answer. The `0x` prefix is optional here because nothing guarantees which presentation a given codec returns.
+ */
+const isEmptyHash = (hash) => /^(0x)?0*$/.test(hash);
+/**
+ * Disconnects the api and waits until its socket has actually closed.
+ *
+ * @remarks
+ *   `WsProvider.disconnect()` is fire-and-forget: it dispatches the close frame and returns while the socket is still
+ *   CLOSING, and `isConnected` only flips false once the close event fires. A caller that returns without waiting
+ *   leaves the next `ensureConnection()` reading a stale `true`: it skips the reconnect, drops its readiness probe on
+ *   the dying socket, sleeps `reconnectionDelay`, reconnects, and usually fails one more pre-open probe — seconds lost
+ *   on every call. Locally the close-ack lands fast enough to hide this; against a remote node it does not. Both places
+ *   that release the socket — the build in `make()` and the last call's `#deregister` — wait here, so the two cannot
+ *   drift.
+ *
+ *   The wait shares the caller's bound. A node that completes the handshake and then goes half-open never acknowledges
+ *   the close frame, and only ws's own 30-second close timeout would end the wait — from inside an uninterruptible
+ *   acquire, in `make()`'s case, which no outer deadline can cut short. A finite bound is therefore honoured here too:
+ *   the wait is abandoned once it elapses, the socket is left CLOSING for ws to finish, and a stale `isConnected` costs
+ *   one failed readiness probe. An infinite bound waits for the event, as an unbounded caller expects.
+ * @param api - The api whose socket to release.
+ * @param bound - How long to wait for the close to be acknowledged; `Duration.infinity` waits indefinitely.
+ * @returns A promise that settles once the socket has closed or the bound has elapsed.
+ */
+const disconnectAndAwaitClose = (api, bound) => new Promise((resolve) => {
+    if (!api.isConnected) {
+        resolve();
+        return;
+    }
+    const closeTimer = {};
+    // The handler stays registered if the bound wins: firing later, it resolves a settled promise and clears a fired
+    // timer, both no-ops. `once` returns the api, not an unsubscribe, so there is nothing cheaper to do.
+    api.once('disconnected', () => {
+        if (closeTimer.handle !== undefined)
+            clearTimeout(closeTimer.handle);
+        resolve();
+    });
+    if (Duration.isFinite(bound)) {
+        closeTimer.handle = setTimeout(resolve, toTimerMillis(bound));
+    }
+    void api.disconnect();
+});
 export const DEFAULT_CONFIG = {
     reconnectionTimeout: Duration.infinity,
     reconnectionDelay: Duration.seconds(1),
@@ -30,84 +95,144 @@ export const makeConfig = (input) => ({
 export class PolkadotNodeClient {
     static make(configInput) {
         const config = makeConfig(configInput);
-        return Effect.acquireRelease(Effect.promise(async () => {
-            const api = await ApiPromise.create({
+        // A finite `reconnectionTimeout` is a caller asking to be told when the node cannot be reached. Honouring it here as
+        // well as in `ensureConnection` is what makes that possible: left to its defaults, `WsProvider` retries on a timer
+        // and `ApiPromise.create` waits for a connection that may never arrive.
+        const isBounded = Duration.isFinite(config.reconnectionTimeout);
+        // The bound is enforced inside the promise rather than with `Effect.timeout`, because `Effect.acquireRelease` runs
+        // its acquire uninterruptibly — deliberately, so a resource cannot be acquired and then leaked — and an
+        // uninterruptible region ignores an outer timeout. Racing here also lets the half-open provider be closed, which an
+        // interruption could not do.
+        const connect = Effect.tryPromise(async () => {
+            // `autoConnectMs` keeps its default deliberately. Passing `false` does not mean "connect once without retrying" —
+            // it means "do not connect at all", leaving `ApiPromise.create` waiting on a connection nobody started. The bound
+            // below is what limits the wait; the provider's own retry behaviour is left alone.
+            const provider = new WsProvider(config.nodeURL.toString());
+            const created = ApiPromise.create({
                 // @ts-expect-error -- exactOptionalPropertyTypes cause an incompatibility here
-                provider: new WsProvider(config.nodeURL.toString()),
+                provider,
+                // Off for bounded callers too. With it on, `create` returns `isReadyOrError`, which rejects on the provider's
+                // first `error` event — any socket error, such as a node restarting — although the provider would have retried
+                // and connected moments later. A bounded caller then failed within milliseconds and never used the window it
+                // asked for. The race below is the bound; the provider's retries fill the window, as `ensureConnection`'s do.
                 throwOnConnect: false,
                 noInitWarn: true,
             });
+            const timeoutMillis = toTimerMillis(config.reconnectionTimeout);
+            // Held so the timer can be cleared once the race settles. Left armed, it keeps Node's event loop alive, so a
+            // short-lived process that reads once cannot exit until it fires.
+            const timer = {};
+            const api = isBounded
+                ? await Promise.race([
+                    created,
+                    new Promise((_resolve, reject) => {
+                        timer.handle = setTimeout(() => reject(new Error(`Timed out after ${timeoutMillis}ms`)), timeoutMillis);
+                    }),
+                ])
+                    .catch(async (error) => {
+                    // Without this the provider keeps retrying on its timer for the lifetime of the process.
+                    await provider.disconnect().catch(() => undefined);
+                    throw error;
+                })
+                    .finally(() => {
+                    if (timer.handle !== undefined)
+                        clearTimeout(timer.handle);
+                })
+                : await created;
             // Disconnect immediately after loading metadata to avoid keeping the WebSocket open.
             // The health-check timer (10s interval) and timeout handler (5s interval) are cleared on disconnect.
-            // Metadata and type registry remain cached in memory for subsequent on-demand connections.
-            //
-            // WsProvider.disconnect() is fire-and-forget: it dispatches the close frame and returns while the socket is
-            // still CLOSING. `isConnected` only flips false once #onSocketClose fires, so returning here without waiting
-            // leaves ensureConnection() reading a stale `true`, skipping the reconnect, and sending on a dying socket.
-            // Locally the close-ack lands fast enough to hide this; against a remote node it does not.
-            await new Promise((resolve) => {
-                if (!api.isConnected) {
-                    resolve();
-                    return;
-                }
-                api.once('disconnected', () => resolve());
-                void api.disconnect();
-            });
+            // Metadata and type registry remain cached in memory for subsequent on-demand connections. The wait for the
+            // close, and its bound, are explained on `disconnectAndAwaitClose`.
+            await disconnectAndAwaitClose(api, config.reconnectionTimeout);
             return api;
-        }), (api) => Effect.promise(() => api.disconnect())).pipe(Effect.map((api) => new PolkadotNodeClient(config, api)));
+        });
+        return Effect.acquireRelease(
+        // `tryPromise` rather than `promise`: a rejected connection has to reach the error channel this method already
+        // declares, instead of arriving as a defect that no `catchTag` can handle.
+        connect.pipe(Effect.mapError((cause) => new NodeClientError.ConnectionError({
+            message: `Could not connect to ${config.nodeURL.toString()}`,
+            cause,
+        }))), (api) => Effect.promise(() => api.disconnect())).pipe(Effect.flatMap((api) => SynchronizedRef.make(0).pipe(Effect.map((activeCalls) => new PolkadotNodeClient(config, api, activeCalls)))));
     }
     static layer(configInput) {
         return Layer.scoped(NodeClient.NodeClient, PolkadotNodeClient.make(configInput));
     }
     config;
     api;
-    /** Operations currently holding the shared connection open. */
-    #activeOperations = 0;
-    constructor(config, api) {
+    /**
+     * How many calls are in flight on this instance's shared `api`.
+     *
+     * @remarks
+     *   Every method used to end with an unconditional disconnect of the one shared socket, so interleaving any two calls
+     *   on the same instance let whichever finished first tear the socket down under the other — an in-flight
+     *   submission's status subscription being the costly case. The count makes the disconnect conditional: each call
+     *   registers before it connects and deregisters when it finishes, and only the last one out releases the socket.
+     *   `SynchronizedRef` serialises the transitions, so a call arriving while the last one is disconnecting waits, then
+     *   reconnects through `ensureConnection`.
+     */
+    #activeCalls;
+    constructor(config, api, activeCalls) {
         this.config = config;
         this.api = api;
+        this.#activeCalls = activeCalls;
     }
-    ensureConnection() {
-        return pipe(Effect.promise(async () => {
-            if (!this.api.isConnected) {
-                try {
-                    await this.api.connect();
-                }
-                catch (error) {
-                    // WsProvider.connect() rejects if a WebSocket already exists (connection in progress).
-                    // This is expected when the repeat loop re-enters before the 'open' event fires.
-                    if (!(error instanceof Error && error.message === 'WebSocket is already connected')) {
-                        throw error;
-                    }
-                }
-            }
-        }), Effect.andThen(Effect.sync(() => this.api.isConnected)), Effect.repeat({
-            until: (value) => value,
-            schedule: Schedule.spaced(this.config.reconnectionDelay),
-        }), Effect.timeout(this.config.reconnectionTimeout), Effect.asVoid, Effect.mapError((timeout) => new NodeClientError.ConnectionError({
-            message: `Could not establish a usable connection within ${Duration.format(this.config.reconnectionTimeout)}`,
-            cause: timeout,
-        })));
-    }
-    /** Takes a hold on the shared connection for the duration of one operation. */
-    #acquire() {
-        return pipe(this.ensureConnection(), Effect.tap(() => Effect.sync(() => {
-            this.#activeOperations += 1;
-        })));
+    /** Registers one call on the shared connection. Must be balanced by {@link PolkadotNodeClient.#deregister}. */
+    #register() {
+        return SynchronizedRef.update(this.#activeCalls, (active) => active + 1);
     }
     /**
-     * Drops one hold, disconnecting only once the last operation finishes.
+     * Deregisters one call, disconnecting the shared socket when it was the last one in flight.
      *
-     * The api instance is shared, so an unconditional `disconnect()` in a per-operation finalizer closes the transport
-     * out from under any operation still in flight.
+     * @remarks
+     *   Waits for the close to be acknowledged, as `make()` does — see `disconnectAndAwaitClose`. Returning on
+     *   `disconnect()` alone left the next call a stale `isConnected: true` and cost it a dropped probe and a reconnect
+     *   delay.
      */
-    #release() {
-        return Effect.promise(async () => {
-            this.#activeOperations = Math.max(0, this.#activeOperations - 1);
-            if (this.#activeOperations === 0) {
-                await this.api.disconnect();
+    #deregister() {
+        return SynchronizedRef.updateEffect(this.#activeCalls, (active) => active === 1
+            ? Effect.promise(() => disconnectAndAwaitClose(this.api, this.config.reconnectionTimeout)).pipe(Effect.as(0))
+            : Effect.succeed(active - 1));
+    }
+    ensureConnection() {
+        // The counter distinguishes "the node is not there yet" from "the node is there and broken". Failures while the
+        // socket is down retry without limit — that is the unbounded caller's contract, and what submission relies on.
+        // Failures while the socket reports connected are a verdict about the node, and surfacing them restores the loud
+        // failure this method's probe had silently absorbed: before the probe existed, such a node failed on the first
+        // real call; with the probe swallowing every error, it span the retry loop forever under the default (infinite)
+        // reconnectionTimeout.
+        return Ref.make(0).pipe(Effect.flatMap((connectedProbeFailures) => pipe(
+        // `tryPromise` + swallow, not `Effect.promise`: a rejected connect() inside `Effect.promise` is a defect that
+        // bypasses the typed ConnectionError mapping below and kills the caller's fibre as a crash. A rejection here
+        // is one failed attempt, not a verdict — the probe below decides usability and the schedule retries, with
+        // the surrounding timeout as the overall bound. This also covers WsProvider's rejection when a WebSocket
+        // already exists (a connection in progress), which the repeat loop routinely races into.
+        Effect.tryPromise(async () => {
+            if (!this.api.isConnected) {
+                await this.api.connect();
             }
-        });
+        }), Effect.catchAll(() => Effect.void), 
+        // Readiness is established by making a call, not by reading `isConnected`. That flag goes true when the
+        // socket opens, which is earlier than the api can serve requests: after `make()` disconnects to release the
+        // socket, a reconnect has to re-initialise the runtime metadata and subscriptions, and any `api.rpc` call
+        // issued in the gap fails with a disconnection. A trivial call is the only honest test of "usable".
+        Effect.andThen(Effect.tryPromise(() => this.api.rpc.system.chain()).pipe(Effect.zipLeft(Ref.set(connectedProbeFailures, 0)), Effect.as(true), Effect.catchAll((probeError) => this.api.isConnected
+            ? Ref.updateAndGet(connectedProbeFailures, (failures) => failures + 1).pipe(Effect.flatMap((failures) => failures >= MAX_CONNECTED_PROBE_FAILURES
+                ? Effect.fail(new NodeClientError.ConnectionError({
+                    message: 'Node accepted the connection but repeatedly failed to answer RPC',
+                    cause: probeError,
+                }))
+                : Effect.succeed(false)))
+            : // A failed probe on a closed socket says nothing beyond "not connected yet" — reset, keep waiting.
+                Ref.set(connectedProbeFailures, 0).pipe(Effect.as(false))))), Effect.repeat({
+            until: (usable) => usable,
+            schedule: Schedule.spaced(this.config.reconnectionDelay),
+        }), Effect.timeout(this.config.reconnectionTimeout), Effect.asVoid, 
+        // `catchTag`, not `mapError`: the probe's ConnectionError must pass through unwrapped, so the caller sees
+        // "node answered the socket but not RPC" rather than a second ConnectionError blaming the timeout.
+        Effect.catchTag('TimeoutException', (timeout) => new NodeClientError.ConnectionError({
+            message: 'Could not connect before the configured reconnectionTimeout elapsed',
+            cause: timeout,
+        })))));
     }
     sendMidnightTransaction(serializedTransaction) {
         const outputStream = Stream.async((emit) => {
@@ -126,10 +251,13 @@ export class PolkadotNodeClient {
             });
             return Effect.promise(callUnsubscribe);
         });
-        return pipe(Stream.fromEffect(this.#acquire()), Stream.flatMap(() => outputStream), Stream.ensuring(this.#release()));
+        return pipe(Stream.acquireRelease(this.#register(), () => this.#deregister()), Stream.flatMap(() => Stream.fromEffect(this.ensureConnection())), Stream.flatMap(() => outputStream));
     }
     getGenesis() {
-        return pipe(this.#acquire(), Effect.andThen(() => Effect.promise(() => this.api.rpc.chain.getBlock(this.api.genesisHash))), 
+        return Effect.acquireUseRelease(this.#register(), () => pipe(this.ensureConnection(), 
+        // `tryPromise` rather than `promise`: a rejected RPC has to reach the `mapError` below and the caller's
+        // `catchTag`, not arrive as a defect that bypasses both and kills the fibre as a crash.
+        Effect.andThen(() => Effect.tryPromise(() => this.api.rpc.chain.getBlock(this.api.genesisHash))), 
         // https://polkadot.js.org/docs/api/cookbook/blocks/#how-do-i-view-extrinsic-information
         Effect.map(({ block }) => ({
             transactions: block.extrinsics
@@ -139,7 +267,40 @@ export class PolkadotNodeClient {
         })), Effect.mapError((error) => new NodeClientError.ConnectionError({
             message: 'Failed to retrieve genesis transactions',
             cause: error,
-        })), Effect.ensuring(this.#release()));
+        }))), () => this.#deregister());
+    }
+    getGenesisHash() {
+        // Answered from the api rather than the chain: `ApiPromise.create` fetched the genesis hash once and caches it, so
+        // this read needs neither a connection nor the register/deregister dance the RPC-backed calls run.
+        return Effect.sync(() => this.api.genesisHash.toString());
+    }
+    getFinalizedBlock() {
+        return Effect.acquireUseRelease(this.#register(), () => pipe(this.ensureConnection(), Effect.andThen(() => 
+        // `tryPromise` rather than `promise`: an unreachable node has to surface as a typed failure the periodic
+        // liveness check can handle, not as a defect that tears the caller's fiber down.
+        Effect.tryPromise(async () => {
+            // The header must be read at the finalized head's hash. `getHeader()` with no argument returns the best
+            // block, whose height may not be finalized yet.
+            const hash = await this.api.rpc.chain.getFinalizedHead();
+            const header = await this.api.rpc.chain.getHeader(hash.toString());
+            return { hash: hash.toString(), height: header.number.toBigInt() };
+        })), Effect.mapError((error) => new NodeClientError.ConnectionError({
+            message: 'Failed to retrieve the finalized block',
+            cause: error,
+        }))), () => this.#deregister());
+    }
+    getBlockHashAt(height) {
+        return Effect.acquireUseRelease(this.#register(), () => pipe(this.ensureConnection(), Effect.andThen(() => 
+        // `tryPromise` rather than `promise`: an unreachable node has to surface as a typed failure the periodic
+        // liveness check can handle, not as a defect that tears the caller's fiber down.
+        Effect.tryPromise(() => this.api.rpc.chain.getBlockHash(height))), 
+        // The RPC does not fail for a height the chain has nothing at — it answers with a hash of all zeroes. Passed
+        // on as a hash, that would compare unequal to every real block and so read as a chain mismatch rather than as
+        // the absence it is.
+        Effect.map((hash) => Option.liftPredicate(hash.toString(), (value) => !isEmptyHash(value))), Effect.mapError((error) => new NodeClientError.ConnectionError({
+            message: `Failed to retrieve the block hash at height ${height}`,
+            cause: error,
+        }))), () => this.#deregister());
     }
     #handleSubmissionResult = (serializedTransaction, emit, unsubscribe) => {
         const WithBNBlockNumber = Schema.Struct({

package/dist/testing/test-transactions.js

@@ -114,7 +114,7 @@ export const generateTestTransactions = (environment, paths) => Effect.gen(funct
     }), Stream.tapBoth({
         onSuccess: (entry) => Effect.log('entry', entry),
         onFailure: (error) => Effect.log(error),
-    }), Stream.mapEffect((entry) => Stream.fromAsyncIterable(entry, (error) => error).pipe(Stream.tapBoth({
+    }), Stream.mapEffect((entry) => Stream.fromAsyncIterable(entry, (error) => error).pipe(Stream.mapEffect(Schema.decodeUnknown(Uint8ArraySchema)), Stream.tapBoth({
         onSuccess: (chunk) => Effect.log('chunk', chunk),
         onFailure: (error) => Effect.log(error),
     }), Stream.run(fs.sink(paths.fullPath)))), Stream.runDrain, Effect.andThen(Effect.log('done')))));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midnightntwrk/wallet-sdk-node-client",
-  "version": "2.0.0-rc.0",
+  "version": "2.0.0-rc.1",
   "type": "module",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -33,7 +33,7 @@
     }
   },
   "dependencies": {
-    "@midnightntwrk/wallet-sdk-abstractions": "3.0.0-rc.0",
+    "@midnightntwrk/wallet-sdk-abstractions": "3.0.0-rc.1",
     "@midnightntwrk/wallet-sdk-utilities": "1.2.2-rc.0",
     "@polkadot/api": "^16.5.4",
     "@polkadot/types": "^16.5.4",
@@ -57,16 +57,15 @@
   "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",
     "@midnightntwrk/ledger-v9": "1.0.0-rc.5",
     "@midnightntwrk/wallet-sdk-prover-client": "^2.0.0-rc.0",
-    "@types/tar-stream": "3.1.4",
-    "tar-stream": "3.2.0",
-    "tsx": "4.23.13"
+    "tar-stream": "3.2.1",
+    "tsx": "4.23.15"
   },
   "scripts": {
     "typecheck-script": "tsc -b ./tsconfig.script.json --noEmit",