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

package/README.md

@@ -94,9 +94,7 @@ const recipe = getBalanceRecipe({
 import { getBalanceRecipe, InsufficientFundsError } from '@midnight-ntwrk/wallet-sdk-capabilities';
 
 try {
-  const recipe = getBalanceRecipe({
-    /* ... */
-  });
+  const recipe = getBalanceRecipe({/* ... */});
 } catch (error) {
   if (error instanceof InsufficientFundsError) {
     console.log(`Cannot balance: insufficient ${error.tokenType}`);
@@ -104,6 +102,32 @@ try {
 }
 ```
 
+### Proving, either side of a protocol boundary
+
+A proving backend is written against one ledger version — it drives that version's `Transaction.prove` with that
+version's cost model, and frames its proof-server requests with that version's payload helpers. Backends are therefore
+named per ledger version, keyed the way `forks` is, and the range each serves is read off the same fork schedule the
+wallets are built with:
+
+```typescript
+import { makeDefaultVersionedProvingService } from '@midnight-ntwrk/wallet-sdk-capabilities/proving';
+
+const service = makeDefaultVersionedProvingService(
+  { provers: { v8: { kind: 'server', url: v8ProofServer }, v9: { kind: 'wasm' } } },
+  forks,
+); // Either<VersionedProvingService, ProvingConfigurationError>
+```
+
+- `provers` wins over `provingServerUrl`; naming neither is a `ProvingConfigurationError`. `v9` is required and `v8` is
+  optional: a version below `forks.v9` with no `v8` backend fails with `UnsupportedProvingVersionError`.
+- `provingServerUrl` is one server under every key, driven by each ledger version on its own side of `forks.v9`. That is
+  what makes the single-URL form frame correctly on both sides; whether one server can actually prove both is an
+  operational fact about that server, not something the SDK enforces.
+- Each registered backend refuses the other ledger version's transaction with `ProvingEpochMismatchError` rather than
+  handing it to a ledger that cannot read it.
+- `makeV9ServerProvingServiceEffect` / `makeV9WasmProvingServiceEffect` build a single ledger-v9 backend;
+  `makeV8ServerProvingServiceEffect` / `makeV8WasmProvingServiceEffect` are their ledger-v8 twins.
+
 ## Exports
 
 ### Balancer

package/dist/chainVersion/chainVersionProbe.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Asking the chain which protocol version its timeline starts under.
+ *
+ * @remarks
+ *   A wallet that registers a variant either side of a protocol boundary learns the chain's version from the events it
+ *   observes, which is too late for one decision: which variant to start on. Until an event arrives its only guess is
+ *   the bottom of the timeline, so it starts on V1 — and on a chain that is entirely past the boundary that costs a
+ *   hand-over per start, or, on a chain that has produced no event this wallet can see, is simply wrong for as long as
+ *   the wallet runs.
+ *
+ *   This is the question that removes the guess, and it is asked about the **first** block rather than the latest. A
+ *   fresh wallet reads a timeline from its start, so what decides where it begins is which ledger version can
+ *   deserialize the first event it will fetch — a fact about the bottom of the timeline. On a chain that forked with
+ *   history behind it the tip's version answers a different question and answers this one wrongly: it starts the wallet
+ *   on a ledger version that cannot read a byte of the history it is about to be served. A chain whose genesis is
+ *   already past the boundary has no such history, so it still starts a fresh wallet on V2 directly; a chain that
+ *   forked over its own past routes it to V1, where its coins are readable, and the hand-over carries them across.
+ *
+ *   The answer is read from the same block query validation already reads, so nothing new is asked of the indexer, and it
+ *   is best-effort by design: a chain that will not answer leaves the wallet exactly where it was.
+ */
+import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { Effect, Option } from 'effect';
+/**
+ * Asks the chain which protocol version its timeline starts under.
+ *
+ * @remarks
+ *   The version of the chain's **first** block, not its latest one. A wallet uses the answer to pick the variant it will
+ *   start reading history on, so what it needs to know is which ledger version wrote the beginning of that history —
+ *   the tip's version is a different fact, and on a chain that forked over existing history it is the wrong one. An
+ *   application supplying its own probe answers that question or the wallet starts on a ledger version that cannot read
+ *   what it is served.
+ *
+ *   Promise-shaped rather than `Effect`-shaped because it is a wallet-configuration field, and an application supplying
+ *   its own — pointing at a cache, a node RPC, or a value it already holds — should not have to speak `Effect` to do
+ *   it. Every caller treats it as best-effort: a rejection, including a timeout, means "the chain did not say", never
+ *   "the wallet cannot start".
+ */
+export type ChainVersionProbe = () => Promise<ProtocolVersion.ProtocolVersion>;
+/** The indexer's answer about one block, cut down to the one field a version probe reads. */
+export type BlockVersionAnswer = Readonly<{
+    block: Readonly<{
+        protocolVersion: number;
+    }> | null;
+}>;
+declare const ChainVersionUnavailableError_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]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "@midnight-ntwrk/wallet-sdk-capabilities/chainVersion/chainVersionProbe/ChainVersionUnavailableError";
+} & Readonly<A>;
+/** Raised when the chain named no version, because it has produced no block for one to be reported under. */
+export declare class ChainVersionUnavailableError extends ChainVersionUnavailableError_base<{
+    readonly message: string;
+}> {
+}
+/**
+ * Reads the protocol version out of the indexer's answer about a block.
+ *
+ * @remarks
+ *   Absent rather than zero when there is no block. A chain that has produced nothing has not said which side of any
+ *   boundary it is on, and the bottom of the timeline is precisely the wrong guess — it is the one the probe exists to
+ *   replace.
+ * @param answer The indexer's answer about the block that was asked for.
+ * @returns The version that block was reported under, or nothing when there is no block.
+ */
+export declare const chainVersionOf: (answer: BlockVersionAnswer) => Option.Option<ProtocolVersion.ProtocolVersion>;
+/**
+ * The protocol version the chain's timeline starts under, read through whichever query client is provided.
+ *
+ * @remarks
+ *   The same `BlockHash` query the default block-data fetcher runs, so nothing new is asked of the indexer — pointed at
+ *   height zero, the first block the chain ever produced, rather than at the absent offset that means "whatever the tip
+ *   is". That block is the one whose ledger version has to be able to read the first event a fresh wallet fetches,
+ *   which is the only thing this answer decides.
+ */
+export declare const timelineStartChainVersion: Effect.Effect<Option.Option<ProtocolVersion.ProtocolVersion>, import("@midnight-ntwrk/wallet-sdk-utilities/networking").ClientError | import("@midnight-ntwrk/wallet-sdk-utilities/networking").ServerError, import("@midnight-ntwrk/wallet-sdk-indexer-client/effect").QueryClient>;
+/** What building the default {@link ChainVersionProbe} needs: somewhere to ask. */
+export type DefaultChainVersionProbeConfiguration = {
+    indexerClientConnection: {
+        indexerHttpUrl: string;
+    };
+};
+/**
+ * Builds a {@link ChainVersionProbe} that asks the indexer over HTTP for the version its first block was reported under.
+ *
+ * @remarks
+ *   Each call opens a short-lived query client and closes it again, as the default block-data fetcher does. It carries no
+ *   timeout of its own: the caller that blocks on it owns how long it is prepared to wait, and the wallet that starts
+ *   with one applies its own bound.
+ *
+ *   A chain that reports no block at all is not an answer: the failure below is what every caller reads as "the chain did
+ *   not say", and leaves the wallet starting ledger-v8 exactly as a wallet with no probe does.
+ * @param config Where to ask.
+ * @returns The probe.
+ */
+export declare const makeIndexerChainVersionProbe: (config: DefaultChainVersionProbeConfiguration) => ChainVersionProbe;
+export {};

package/dist/chainVersion/chainVersionProbe.js

@@ -0,0 +1,83 @@
+// 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.
+/**
+ * Asking the chain which protocol version its timeline starts under.
+ *
+ * @remarks
+ *   A wallet that registers a variant either side of a protocol boundary learns the chain's version from the events it
+ *   observes, which is too late for one decision: which variant to start on. Until an event arrives its only guess is
+ *   the bottom of the timeline, so it starts on V1 — and on a chain that is entirely past the boundary that costs a
+ *   hand-over per start, or, on a chain that has produced no event this wallet can see, is simply wrong for as long as
+ *   the wallet runs.
+ *
+ *   This is the question that removes the guess, and it is asked about the **first** block rather than the latest. A
+ *   fresh wallet reads a timeline from its start, so what decides where it begins is which ledger version can
+ *   deserialize the first event it will fetch — a fact about the bottom of the timeline. On a chain that forked with
+ *   history behind it the tip's version answers a different question and answers this one wrongly: it starts the wallet
+ *   on a ledger version that cannot read a byte of the history it is about to be served. A chain whose genesis is
+ *   already past the boundary has no such history, so it still starts a fresh wallet on V2 directly; a chain that
+ *   forked over its own past routes it to V1, where its coins are readable, and the hand-over carries them across.
+ *
+ *   The answer is read from the same block query validation already reads, so nothing new is asked of the indexer, and it
+ *   is best-effort by design: a chain that will not answer leaves the wallet exactly where it was.
+ */
+import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { BlockHash } from '@midnight-ntwrk/wallet-sdk-indexer-client';
+import { HttpQueryClient } from '@midnight-ntwrk/wallet-sdk-indexer-client/effect';
+import { Data, Effect, Option, pipe } from 'effect';
+/** Raised when the chain named no version, because it has produced no block for one to be reported under. */
+export class ChainVersionUnavailableError extends Data.TaggedError('@midnight-ntwrk/wallet-sdk-capabilities/chainVersion/chainVersionProbe/ChainVersionUnavailableError') {
+}
+/**
+ * Reads the protocol version out of the indexer's answer about a block.
+ *
+ * @remarks
+ *   Absent rather than zero when there is no block. A chain that has produced nothing has not said which side of any
+ *   boundary it is on, and the bottom of the timeline is precisely the wrong guess — it is the one the probe exists to
+ *   replace.
+ * @param answer The indexer's answer about the block that was asked for.
+ * @returns The version that block was reported under, or nothing when there is no block.
+ */
+export const chainVersionOf = (answer) => pipe(Option.fromNullable(answer.block), Option.map((block) => ProtocolVersion.ProtocolVersion(BigInt(block.protocolVersion))));
+/**
+ * The protocol version the chain's timeline starts under, read through whichever query client is provided.
+ *
+ * @remarks
+ *   The same `BlockHash` query the default block-data fetcher runs, so nothing new is asked of the indexer — pointed at
+ *   height zero, the first block the chain ever produced, rather than at the absent offset that means "whatever the tip
+ *   is". That block is the one whose ledger version has to be able to read the first event a fresh wallet fetches,
+ *   which is the only thing this answer decides.
+ */
+export const timelineStartChainVersion = Effect.gen(function* () {
+    const query = yield* BlockHash;
+    return chainVersionOf(yield* query({ offset: { height: 0 } }));
+});
+/**
+ * Builds a {@link ChainVersionProbe} that asks the indexer over HTTP for the version its first block was reported under.
+ *
+ * @remarks
+ *   Each call opens a short-lived query client and closes it again, as the default block-data fetcher does. It carries no
+ *   timeout of its own: the caller that blocks on it owns how long it is prepared to wait, and the wallet that starts
+ *   with one applies its own bound.
+ *
+ *   A chain that reports no block at all is not an answer: the failure below is what every caller reads as "the chain did
+ *   not say", and leaves the wallet starting ledger-v8 exactly as a wallet with no probe does.
+ * @param config Where to ask.
+ * @returns The probe.
+ */
+export const makeIndexerChainVersionProbe = (config) => () => pipe(timelineStartChainVersion, Effect.provide(HttpQueryClient.layer({ url: config.indexerClientConnection.indexerHttpUrl })), Effect.scoped, Effect.flatMap(Option.match({
+    onNone: () => Effect.fail(new ChainVersionUnavailableError({
+        message: 'The indexer reports no block, so the chain has named no protocol version.',
+    })),
+    onSome: Effect.succeed,
+})), Effect.runPromise);

package/dist/chainVersion/index.d.ts

@@ -0,0 +1 @@
+export * from './chainVersionProbe.js';

package/dist/chainVersion/index.js

@@ -0,0 +1,13 @@
+// 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 './chainVersionProbe.js';

package/dist/codecs/index.d.ts

@@ -0,0 +1 @@
+export * as LedgerParametersCodec from './ledgerParameters.js';

package/dist/codecs/index.js

@@ -0,0 +1,13 @@
+// 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 * as LedgerParametersCodec from './ledgerParameters.js';

package/dist/codecs/ledgerParameters.d.ts

@@ -0,0 +1,81 @@
+import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { Either } from 'effect';
+/**
+ * Reads the indexer's hex-encoded ledger parameters as one ledger version understands them.
+ *
+ * @remarks
+ *   A codec is deliberately allowed to throw: it wraps a WASM deserializer, and what it throws on is precisely the other
+ *   ledger version's bytes. {@link decode} is the only way to call one, and it turns that into a typed failure.
+ * @typeParam TParameters The `LedgerParameters` type of the ledger version this codec speaks.
+ */
+export type LedgerParametersCodec<TParameters> = Readonly<{
+    decode: (hex: string) => TParameters;
+}>;
+/**
+ * The codecs a caller is willing to decode with, keyed by the protocol version range each one serves.
+ *
+ * @remarks
+ *   Registration is per caller, not global, and a caller registers only the ledger versions its own types are written
+ *   against — which is why the registry stays homogeneous in `TParameters` while the SDK as a whole spans two ledgers.
+ *   A version outside every registered range therefore means "this block belongs to a different variant", and
+ *   {@link decode} says so instead of handing the bytes to a deserializer that would reject them.
+ * @typeParam TParameters The `LedgerParameters` type the registered codecs produce.
+ */
+export type LedgerParametersCodecs<TParameters> = ProtocolVersion.Registry<LedgerParametersCodec<TParameters>>;
+declare const UnsupportedProtocolVersionError_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]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "@midnight-ntwrk/wallet-sdk-capabilities/codecs/ledgerParameters/UnsupportedProtocolVersionError";
+} & Readonly<A>;
+/** Raised when no registered codec claims the protocol version a block was reported under. */
+export declare class UnsupportedProtocolVersionError extends UnsupportedProtocolVersionError_base<{
+    readonly message: string;
+    /** The version the block was reported under, which no registered codec covers. */
+    readonly protocolVersion: ProtocolVersion.ProtocolVersion;
+}> {
+}
+declare const LedgerParametersDecodeError_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]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "@midnight-ntwrk/wallet-sdk-capabilities/codecs/ledgerParameters/LedgerParametersDecodeError";
+} & Readonly<A>;
+/** Raised when the codec chosen for a protocol version could not read the bytes it was given. */
+export declare class LedgerParametersDecodeError extends LedgerParametersDecodeError_base<{
+    readonly message: string;
+    /** The version the block was reported under, and so the codec that was chosen. */
+    readonly protocolVersion: ProtocolVersion.ProtocolVersion;
+    readonly cause: unknown;
+}> {
+}
+/** Every way a version-routed ledger parameters decode can fail. */
+export type LedgerParametersCodecError = UnsupportedProtocolVersionError | LedgerParametersDecodeError;
+/**
+ * Builds a codec from a ledger version's `LedgerParameters.deserialize`.
+ *
+ * @param deserialize The ledger version's deserializer.
+ * @returns A codec that hex-decodes the indexer's encoding before handing the bytes over.
+ */
+export declare const fromDeserializer: <TParameters>(deserialize: (bytes: Uint8Array) => TParameters) => LedgerParametersCodec<TParameters>;
+/**
+ * Decodes hex-encoded ledger parameters with the codec registered for the protocol version the block was reported
+ * under.
+ *
+ * @param codecs The codecs the caller is willing to decode with.
+ * @param protocolVersion The version the indexer reported the block under.
+ * @param hex The block's hex-encoded ledger parameters.
+ * @returns The decoded parameters, an {@link UnsupportedProtocolVersionError} when no codec claims that version, or a
+ *   {@link LedgerParametersDecodeError} when the chosen codec could not read the bytes.
+ */
+export declare const decode: <TParameters>(codecs: LedgerParametersCodecs<TParameters>, protocolVersion: ProtocolVersion.ProtocolVersion, hex: string) => Either.Either<TParameters, LedgerParametersCodecError>;
+/**
+ * Builds a registry from codecs and the versions they activate at.
+ *
+ * @remarks
+ *   A thin name over {@link ProtocolVersion.makeRegistryFromActivations} so that codec registration reads the same as
+ *   variant registration and cannot drift from it. The activation list is a constant at every call site in the SDK, so
+ *   a rejection here is a programming error rather than a runtime condition — callers that build one at module scope
+ *   are entitled to let it throw.
+ * @param activations The codecs and the versions they start serving, in strictly ascending order.
+ * @returns The registry, or the {@link ProtocolVersion.RegistryError} naming the versions that broke the ordering.
+ */
+export declare const makeCodecs: <TParameters>(activations: readonly Readonly<{
+    sinceVersion: ProtocolVersion.ProtocolVersion;
+    codec: LedgerParametersCodec<TParameters>;
+}>[]) => Either.Either<LedgerParametersCodecs<TParameters>, ProtocolVersion.RegistryError>;
+export {};

package/dist/codecs/ledgerParameters.js

@@ -0,0 +1,63 @@
+// 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 { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { Buffer } from 'buffer';
+import { Data, Either, pipe } from 'effect';
+/** Raised when no registered codec claims the protocol version a block was reported under. */
+export class UnsupportedProtocolVersionError extends Data.TaggedError('@midnight-ntwrk/wallet-sdk-capabilities/codecs/ledgerParameters/UnsupportedProtocolVersionError') {
+}
+/** Raised when the codec chosen for a protocol version could not read the bytes it was given. */
+export class LedgerParametersDecodeError extends Data.TaggedError('@midnight-ntwrk/wallet-sdk-capabilities/codecs/ledgerParameters/LedgerParametersDecodeError') {
+}
+/**
+ * Builds a codec from a ledger version's `LedgerParameters.deserialize`.
+ *
+ * @param deserialize The ledger version's deserializer.
+ * @returns A codec that hex-decodes the indexer's encoding before handing the bytes over.
+ */
+export const fromDeserializer = (deserialize) => ({
+    decode: (hex) => deserialize(Buffer.from(hex, 'hex')),
+});
+/**
+ * Decodes hex-encoded ledger parameters with the codec registered for the protocol version the block was reported
+ * under.
+ *
+ * @param codecs The codecs the caller is willing to decode with.
+ * @param protocolVersion The version the indexer reported the block under.
+ * @param hex The block's hex-encoded ledger parameters.
+ * @returns The decoded parameters, an {@link UnsupportedProtocolVersionError} when no codec claims that version, or a
+ *   {@link LedgerParametersDecodeError} when the chosen codec could not read the bytes.
+ */
+export const decode = (codecs, protocolVersion, hex) => pipe(ProtocolVersion.select(codecs, protocolVersion), Either.fromOption(() => new UnsupportedProtocolVersionError({
+    message: `No ledger parameters codec is registered for protocol version ${protocolVersion}.`,
+    protocolVersion,
+})), Either.flatMap((codec) => Either.try({
+    try: () => codec.decode(hex),
+    catch: (cause) => new LedgerParametersDecodeError({
+        message: `Could not decode ledger parameters reported at protocol version ${protocolVersion}.`,
+        protocolVersion,
+        cause,
+    }),
+})));
+/**
+ * Builds a registry from codecs and the versions they activate at.
+ *
+ * @remarks
+ *   A thin name over {@link ProtocolVersion.makeRegistryFromActivations} so that codec registration reads the same as
+ *   variant registration and cannot drift from it. The activation list is a constant at every call site in the SDK, so
+ *   a rejection here is a programming error rather than a runtime condition — callers that build one at module scope
+ *   are entitled to let it throw.
+ * @param activations The codecs and the versions they start serving, in strictly ascending order.
+ * @returns The registry, or the {@link ProtocolVersion.RegistryError} naming the versions that broke the ordering.
+ */
+export const makeCodecs = (activations) => ProtocolVersion.makeRegistryFromActivations(activations.map(({ sinceVersion, codec }) => ({ sinceVersion, value: codec })));

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 export * from './balancer/index.js';
+export * from './chainVersion/index.js';
+export * from './codecs/index.js';
 export * from './pendingTransactions/index.js';
 export * from './proving/index.js';
+export * from './signatures/index.js';
 export * from './simulation/index.js';
 export * from './submission/index.js';
 export * from './validation/index.js';

package/dist/index.js

@@ -11,8 +11,11 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 export * from './balancer/index.js';
+export * from './chainVersion/index.js';
+export * from './codecs/index.js';
 export * from './pendingTransactions/index.js';
 export * from './proving/index.js';
+export * from './signatures/index.js';
 export * from './simulation/index.js';
 export * from './submission/index.js';
 export * from './validation/index.js';

package/dist/pendingTransactions/pendingTransactions.d.ts

@@ -1,4 +1,5 @@
-import { type DateTime, Either, type ParseResult, Schema } from 'effect';
+import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { type DateTime, Either, Option, ParseResult, Schema } from 'effect';
 export type TransactionTrait<TTransaction> = {
     ids: (tx: TTransaction) => readonly string[];
     firstId: (tx: TTransaction) => string;
@@ -12,6 +13,47 @@ export type TransactionTrait<TTransaction> = {
 export type HasTransactionTrait<TTransaction> = {
     txTrait: TransactionTrait<TTransaction>;
 };
+/**
+ * The transaction traits a wallet can read pending transactions with, keyed by the protocol version range each one
+ * serves.
+ *
+ * @remarks
+ *   A transaction's bytes, identifiers and TTL are only meaningful under the ledger version it was authored against, so
+ *   which trait applies is a property of the transaction rather than of the wallet holding it. Keeping that in the
+ *   shared {@link ProtocolVersion.Registry} means the boundary between two traits is the same boundary variant selection
+ *   and codec selection use.
+ */
+export type VersionedTransactionTrait<TTransaction> = ProtocolVersion.Registry<TransactionTrait<TTransaction>>;
+export type HasVersionedTransactionTrait<TTransaction> = {
+    txTraits: VersionedTransactionTrait<TTransaction>;
+};
+/** Registers one trait for every protocol version: the shape a wallet that speaks a single ledger version has. */
+export declare const singleTrait: <TTransaction>(trait: TransactionTrait<TTransaction>) => VersionedTransactionTrait<TTransaction>;
+/** The oldest registered trait: what an envelope that carries no version stamp is read with. */
+export declare const headTrait: <TTransaction>(traits: VersionedTransactionTrait<TTransaction>) => Option.Option<TransactionTrait<TTransaction>>;
+/**
+ * The trait registered for a protocol version, or the oldest trait when nothing says which version applies.
+ *
+ * @remarks
+ *   Falling back to the oldest trait is the same convention snapshot restore uses for an envelope written before versions
+ *   were recorded: the only envelopes without a stamp are ones written before stamping existed, and those necessarily
+ *   predate every version boundary since.
+ * @param traits The registered traits.
+ * @param protocolVersion The version the transaction was authored for, when one is known.
+ * @returns The trait to read with, or `Option.none()` when the version falls outside every registered range.
+ */
+export declare const traitForVersion: <TTransaction>(traits: VersionedTransactionTrait<TTransaction>, protocolVersion: Option.Option<ProtocolVersion.ProtocolVersion>) => Option.Option<TransactionTrait<TTransaction>>;
+/** The registered trait that recognises a transaction object as its own, if any does. */
+export declare const recognisingTrait: <TTransaction>(traits: VersionedTransactionTrait<TTransaction>, tx: unknown) => Option.Option<TransactionTrait<TTransaction>>;
+/**
+ * The trait to read an incoming transaction with: the one that recognises it, or the oldest as a last resort.
+ *
+ * @param traits The registered traits.
+ * @param tx The transaction to place.
+ * @returns The trait that owns `tx`, the oldest trait when none claims it, or `Option.none()` when nothing is
+ *   registered at all.
+ */
+export declare const traitForTx: <TTransaction>(traits: VersionedTransactionTrait<TTransaction>, tx: TTransaction) => Option.Option<TransactionTrait<TTransaction>>;
 export type FailedTransactionResult = Readonly<{
     segments: ReadonlyArray<{
         id: number;
@@ -26,10 +68,34 @@ export type SuccessTransactionResult = Readonly<{
     }>;
     status: 'SUCCESS';
 }>;
-export type TransactionResult = FailedTransactionResult | SuccessTransactionResult;
+/**
+ * The verdict on a transaction a protocol upgrade left behind.
+ *
+ * @remarks
+ *   Deliberately not one of the indexer's statuses: the chain never reported anything about this transaction and never
+ *   will, because bytes authored under the previous protocol version cannot be included under the new one. Saying so in
+ *   its own arm keeps "the node rejected this" and "this can no longer be submitted at all" distinguishable.
+ */
+export type OrphanedByForkResult = Readonly<{
+    status: 'ORPHANED_BY_FORK';
+    /** The protocol version the transaction was authored for. */
+    authoredFor: ProtocolVersion.ProtocolVersion;
+    /** The protocol version the chain had reached when the wallet gave up on it. */
+    chainNow: ProtocolVersion.ProtocolVersion;
+}>;
+export type TransactionResult = FailedTransactionResult | SuccessTransactionResult | OrphanedByForkResult;
 export type PendingItem<TTransaction> = Readonly<{
     tx: TTransaction;
     creationTime: DateTime.Utc;
+    /**
+     * The protocol version the transaction was authored for, when the wallet had observed one.
+     *
+     * @remarks
+     *   `Option.none()` means the wallet never learned what version it was authored against — either the envelope predates
+     *   stamping, or no wallet had reported a version yet. That is not evidence the transaction was left behind, so such
+     *   an item is read with the oldest trait but never orphaned.
+     */
+    protocolVersion: Option.Option<ProtocolVersion.ProtocolVersion>;
 }>;
 export type CheckedItem<TTransaction> = PendingItem<TTransaction> & {
     result: TransactionResult;
@@ -38,24 +104,62 @@ export type PendingTransactionsItem<TTransaction> = PendingItem<TTransaction> |
 export type FailedTransactionItem<TTransaction> = PendingTransactionsItem<TTransaction> & {
     result: FailedTransactionResult;
 };
+export type OrphanedTransactionItem<TTransaction> = PendingTransactionsItem<TTransaction> & {
+    result: OrphanedByForkResult;
+};
+/** An item the wallet has given up on, whether the chain rejected it or a protocol upgrade stranded it. */
+export type RejectedTransactionItem<TTransaction> = PendingTransactionsItem<TTransaction> & {
+    result: FailedTransactionResult | OrphanedByForkResult;
+};
 export type PendingTransactions<TTransaction> = Readonly<{
     all: ReadonlyArray<PendingTransactionsItem<TTransaction>>;
 }>;
-export declare const has: <TTransaction>(transactions: PendingTransactions<TTransaction>, transaction: TTransaction, txTrait: TransactionTrait<TTransaction>) => boolean;
+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>>;
+/** Transactions a protocol upgrade stranded: they were authored for a version the chain has moved past. */
+export declare const allOrphaned: <TTransaction>(transactions: PendingTransactions<TTransaction>) => ReadonlyArray<OrphanedTransactionItem<TTransaction>>;
+/**
+ * Everything the wallet has given up on, in the order it was added: reported failures and orphaned transactions alike.
+ * Both need the same treatment — unbook the coins, record the rejection — so both belong on one list.
+ */
+export declare const allRejected: <TTransaction>(transactions: PendingTransactions<TTransaction>) => ReadonlyArray<RejectedTransactionItem<TTransaction>>;
 export declare const allPending: <TTransaction>(state: PendingTransactions<TTransaction>) => readonly PendingItem<TTransaction>[];
 export declare const empty: <TTransaction>() => PendingTransactions<TTransaction>;
-export declare const addPendingTransaction: <TTransaction>(state: PendingTransactions<TTransaction>, tx: TTransaction, now: DateTime.Utc, txTrait: TransactionTrait<TTransaction>) => PendingTransactions<TTransaction>;
-export declare const clear: <TTransaction>(state: PendingTransactions<TTransaction>, tx: TTransaction, txTrait: TransactionTrait<TTransaction>) => PendingTransactions<TTransaction>;
-export declare const saveResult: <TTransaction>(state: PendingTransactions<TTransaction>, tx: TTransaction, result: TransactionResult, txTrait: TransactionTrait<TTransaction>) => PendingTransactions<TTransaction>;
+/**
+ * Records a transaction as pending, stamped with the protocol version it was authored for.
+ *
+ * @param state The pending transactions.
+ * @param tx The transaction to record.
+ * @param now The time it was authored.
+ * @param traits The traits pending transactions are read with.
+ * @param protocolVersion The version the chain had reached when it was authored, when the wallet knew one.
+ * @returns The pending transactions including `tx`, with any superseded entry from the same version epoch replaced.
+ */
+export declare const addPendingTransaction: <TTransaction>(state: PendingTransactions<TTransaction>, tx: TTransaction, now: DateTime.Utc, traits: VersionedTransactionTrait<TTransaction>, protocolVersion: Option.Option<ProtocolVersion.ProtocolVersion>) => PendingTransactions<TTransaction>;
+export declare const clear: <TTransaction>(state: PendingTransactions<TTransaction>, tx: TTransaction, traits: VersionedTransactionTrait<TTransaction>) => PendingTransactions<TTransaction>;
+export declare const saveResult: <TTransaction>(state: PendingTransactions<TTransaction>, tx: TTransaction, result: TransactionResult, traits: VersionedTransactionTrait<TTransaction>) => PendingTransactions<TTransaction>;
+/**
+ * Gives up on every unresolved transaction whose version epoch the chain has moved past.
+ *
+ * @remarks
+ *   The epochs are the registry's own ranges, so "the chain has moved past" means exactly "a different trait answers for
+ *   the chain now than answered for this transaction". A transaction authored under the previous protocol version can
+ *   never be included afterwards, so waiting for its TTL only delays the inevitable and holds its coins hostage
+ *   meanwhile.
+ * @param state The pending transactions.
+ * @param traits The traits pending transactions are read with, whose ranges define the epochs.
+ * @param chainNow The protocol version the wallets have reached.
+ * @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>;
 type Serialized<TTransaction> = Readonly<{
     version: 'v1';
     transactions: readonly PendingItem<TTransaction>[];
 }>;
-export declare const SerializedSchema: <TTransaction>(txTrait: TransactionTrait<TTransaction>) => Schema.Schema<Serialized<TTransaction>, any>;
-export declare const serialize: <TTransaction>(state: PendingTransactions<TTransaction>, txTrait: TransactionTrait<TTransaction>) => string;
-export declare const deserialize: <TTransaction>(serialized: string, txTrait: TransactionTrait<TTransaction>) => Either.Either<PendingTransactions<TTransaction>, ParseResult.ParseError>;
+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;
+export declare const deserialize: <TTransaction>(serialized: string, traits: VersionedTransactionTrait<TTransaction>) => Either.Either<PendingTransactions<TTransaction>, ParseResult.ParseError>;
 export declare const toSerialized: <TTransaction>(pendingTransactions: PendingTransactions<TTransaction>) => Serialized<TTransaction>;
 export declare const fromSerialized: <TTransaction>(serialized: Serialized<TTransaction>) => PendingTransactions<TTransaction>;
 export {};