@midnight-ntwrk/wallet-sdk-abstractions 3.0.0-beta.0 → 3.0.0-beta.2

package/dist/InMemoryTransactionHistoryStorage.js

@@ -11,6 +11,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 import { Schema } from 'effect';
+import { coversTransaction, } from './TransactionHistoryStorage.js';
 /**
  * In-memory implementation of the TransactionHistoryStorage interface.
  *
@@ -42,9 +43,11 @@ export class InMemoryTransactionHistoryStorage {
         const { finalizedBlock, ...rest } = input;
         const entry = { ...rest, lifecycle: { status: 'finalized', finalizedBlock } };
         await this.#upsert(entry);
-        this.#clearPendingByIdentifiers(entry.identifiers, entry.hash);
+        this.#clearUnfinalizedCoveredBy(entry);
     }
     async gotRejected(input) {
+        if (this.#inclusionRecorded(input))
+            return;
         const { rejectedAt, reason, ...rest } = input;
         const lifecycle = reason !== undefined
             ? { status: 'rejected', rejectedAt, reason }
@@ -80,16 +83,15 @@ export class InMemoryTransactionHistoryStorage {
         this.#storage.set(entry.hash, existing ? this.#merge(existing, entry) : entry);
         return Promise.resolve();
     }
-    #clearPendingByIdentifiers(identifiers, newHash) {
-        if (identifiers.length === 0)
-            return;
-        const provided = new Set(identifiers);
-        const match = [...this.#storage.values()].find((entry) => entry.identifiers.length > 0 &&
-            entry.identifiers.every((id) => provided.has(id)) &&
-            entry.lifecycle.status === 'pending' &&
-            entry.hash !== newHash);
-        if (match) {
-            this.#storage.delete(match.hash);
-        }
+    /** Checked synchronously with the write that follows, so a verdict racing sync cannot supersede inclusion. */
+    #inclusionRecorded(key) {
+        return [...this.#storage.values()].some((entry) => entry.lifecycle.status === 'finalized' && coversTransaction(entry, key));
+    }
+    #clearUnfinalizedCoveredBy(finalized) {
+        [...this.#storage.values()]
+            .filter((entry) => entry.lifecycle.status !== 'finalized' &&
+            entry.hash !== finalized.hash &&
+            coversTransaction(finalized, entry))
+            .forEach((entry) => this.#storage.delete(entry.hash));
     }
 }

package/dist/ProtocolState.d.ts

@@ -1,20 +1,28 @@
 import { Equivalence } from 'effect';
 import type * as ProtocolVersion from './ProtocolVersion.js';
 /**
- * A type that associates some state with a given version of the Midnight protocol.
+ * A type that associates some state with a given version of the Midnight protocol, and with the variant that produced
+ * it.
  *
+ * @remarks
+ *   `variantTag` is the tag of the wallet variant the emission came from. The runtime knows it at the moment it publishes
+ *   a state, so it hands it over rather than leaving readers to infer the producing implementation from `version` —
+ *   which would mean re-deriving activation ranges, and casting, on every emission. It travels with the state so that
+ *   selecting the capabilities that understand a state is a lookup by tag.
  * @typeParam TState The type of state.
+ * @typeParam TVariantTag The tag, or union of tags, of the variants that can produce this state.
  */
-export type ProtocolState<TState> = Readonly<{
+export type ProtocolState<TState, TVariantTag extends string | symbol = string | symbol> = Readonly<{
     version: ProtocolVersion.ProtocolVersion;
+    variantTag: TVariantTag;
     state: TState;
 }>;
 export declare const state: <TState>(ps: ProtocolState<TState>) => TState;
 /**
  * Derives an {@link Equivalence.Equivalence} for {@link ProtocolState} values from an equivalence of the underlying
- * state. Versions are compared strictly.
+ * state. Versions and producing variant tags are compared strictly.
  *
  * @param stateEquivalence The equivalence used to compare the `state` field.
  * @returns An equivalence over `ProtocolState<TState>`.
  */
-export declare const getEquivalence: <TState>(stateEquivalence: Equivalence.Equivalence<TState>) => Equivalence.Equivalence<ProtocolState<TState>>;
+export declare const getEquivalence: <TState, TVariantTag extends string | symbol = string | symbol>(stateEquivalence: Equivalence.Equivalence<TState>) => Equivalence.Equivalence<ProtocolState<TState, TVariantTag>>;

package/dist/ProtocolState.js

@@ -14,12 +14,13 @@ import { Equivalence } from 'effect';
 export const state = (ps) => ps.state;
 /**
  * Derives an {@link Equivalence.Equivalence} for {@link ProtocolState} values from an equivalence of the underlying
- * state. Versions are compared strictly.
+ * state. Versions and producing variant tags are compared strictly.
  *
  * @param stateEquivalence The equivalence used to compare the `state` field.
  * @returns An equivalence over `ProtocolState<TState>`.
  */
 export const getEquivalence = (stateEquivalence) => Equivalence.struct({
     version: Equivalence.strict(),
+    variantTag: Equivalence.strict(),
     state: stateEquivalence,
 });

package/dist/ProtocolVersion.d.ts

@@ -1,4 +1,6 @@
 import * as Brand from 'effect/Brand';
+import * as Either from 'effect/Either';
+import * as Option from 'effect/Option';
 import * as Schema from 'effect/Schema';
 /** A branded `bigint` that represents a protocol version. */
 export type ProtocolVersion = Brand.Branded<bigint, 'ProtocolVersion'>;
@@ -38,3 +40,147 @@ export declare const is: (u: unknown, overrideOptions?: import("effect/SchemaAST
 export declare const MinSupportedVersion: ProtocolVersion;
 /** Represents the maximum supported protocol version. */
 export declare const MaxSupportedVersion: ProtocolVersion;
+/**
+ * The protocol version a ledger-v9-native chain hands over at, for the current node line.
+ *
+ * @remarks
+ *   Measured, not assumed: a `midnight-node` 2.x reports protocol version `2000000` on its ledger events — the runtime
+ *   version, scaled, rather than a small ordinal or the ledger major. A chain of the previous node line reports a
+ *   1.x-encoded value, which is below this, so a wallet configured with it stays on the V1 variant there and reaches
+ *   the V2 variant on any v9-native chain.
+ *
+ *   Offered as a named value so applications and test suites pointed at a v9-native chain do not each invent a magic
+ *   number; {@link V9NativeForkSchedule} is the schedule built from it. The final mainnet fork constant is still an open
+ *   question; when it is fixed it will join this one here.
+ */
+export declare const V9NativeForkVersion: ProtocolVersion;
+/**
+ * Where each ledger version after the first begins on a chain, by protocol version.
+ *
+ * @remarks
+ *   One key per ledger version the SDK can run, minus the first: ledger-v8 begins at {@link MinSupportedVersion} and needs
+ *   no entry. `v9` is the protocol version from which ledger-v9 reads the chain — {@link V9NativeForkVersion} on a chain
+ *   born on ledger-v9, and whatever version the hand-over is enacted at on a chain with ledger-v8 history. The next
+ *   hard fork adds a key (`v10`) rather than changing this shape, which is what lets an application's configuration
+ *   outlive the fork.
+ *
+ *   Every entry is required in the wallet packages, for the same reason a single fork version was: where a chain forks is
+ *   a fact about the chain rather than the SDK, and a wrong guess does not degrade — it decides which ledger version
+ *   reads the chain. {@link V9NativeForkSchedule} names the schedule of a chain born on ledger-v9; only the facade
+ *   presets one, `DefaultForkSchedule`, and says there why.
+ */
+export type ForkSchedule = Readonly<{
+    /** The protocol version from which ledger-v9 reads the chain. */
+    v9: ProtocolVersion;
+}>;
+/**
+ * The fork schedule of a chain born on ledger-v9: ledger-v9 from {@link V9NativeForkVersion}, and nothing else.
+ *
+ * @remarks
+ *   Offered as a named value for the same reason {@link V9NativeForkVersion} is: so applications and test suites pointed
+ *   at a v9-native chain do not each write the schedule out by hand. A named value and not a default — the wallet
+ *   packages still require `forks`. The facade's `DefaultForkSchedule` is this value, under the name of what the facade
+ *   presets.
+ */
+export declare const V9NativeForkSchedule: ForkSchedule;
+/**
+ * The range of protocol versions on the same side of a protocol boundary as a given version.
+ *
+ * @remarks
+ *   What the SDK means by "the same ledger version made these bytes". A protocol boundary divides the timeline into two
+ *   epochs, and everything that routes on a version — which prover proves a transaction, which validator checks it,
+ *   which variant may unwrap it — is really asking which epoch it belongs to. Stated once here so the two ends of that
+ *   question, the wallet stamping a transaction and the caller unwrapping it, cannot compute the boundary differently.
+ *
+ *   A chain whose boundary is at or below the minimum supported version has never had two epochs, so the whole range is
+ *   one.
+ * @param version A version in the epoch of interest.
+ * @param forkVersion The version at which the chain hands over to the next ledger version.
+ * @returns The half-open range of versions in that epoch.
+ */
+export declare const epochOf: (version: ProtocolVersion, forkVersion: ProtocolVersion) => ProtocolVersion.Range;
+/**
+ * A value together with the protocol version range it serves.
+ *
+ * @typeParam T The type of the registered value.
+ */
+export type RegistryEntry<T> = Readonly<{
+    range: ProtocolVersion.Range;
+    value: T;
+}>;
+/**
+ * An ordered collection of values, each keyed by the protocol version range it serves.
+ *
+ * @remarks
+ *   This is the shared shape behind every "which implementation speaks this protocol version?" question the SDK asks —
+ *   which codec decodes a block, which prover proves a recipe, which transaction trait understands a pending
+ *   transaction, which variant a snapshot should be restored into. Keeping one primitive means those answers cannot
+ *   disagree about what a version range is or where its boundaries lie.
+ *
+ *   Entries are ascending and non-overlapping by construction, and ranges are half-open (`withinRange`), so exactly one
+ *   entry can match a version. Gaps are allowed: a version no entry covers selects nothing, which callers turn into
+ *   whichever typed error means "unsupported" in their domain.
+ * @typeParam T The type of the registered values.
+ */
+export type Registry<T> = Readonly<{
+    entries: readonly RegistryEntry<T>[];
+}>;
+declare const RegistryError_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-abstractions/ProtocolVersion/RegistryError";
+} & Readonly<A>;
+/**
+ * Raised when entries cannot form a {@link Registry} because their ranges are not ascending, overlap, or cannot be
+ * closed at all.
+ *
+ * @remarks
+ *   Construction is the only place this can happen: once built, a registry is total — selection returns an
+ *   {@link Option.Option} rather than failing.
+ */
+export declare class RegistryError extends RegistryError_base<{
+    readonly message: string;
+    /** The protocol versions whose ordering or overlap made the registry invalid. */
+    readonly versions: readonly ProtocolVersion[];
+}> {
+}
+/** A registry with no entries: {@link select} on it never finds anything. */
+export declare const emptyRegistry: Registry<never>;
+/**
+ * Creates a registry from entries that already carry their own ranges.
+ *
+ * @param entries The entries, in ascending order of range start; ranges must not overlap, though gaps are allowed.
+ * @returns The registry, or a {@link RegistryError} naming the two range boundaries that could not be ordered.
+ */
+export declare const makeRegistry: <T>(entries: readonly RegistryEntry<T>[]) => Either.Either<Registry<T>, RegistryError>;
+/**
+ * Creates a registry from values keyed by the protocol version each becomes active at, deriving the ranges from the
+ * registration order: entry _i_ serves `[sinceVersion(i), sinceVersion(i + 1))`, and the last entry serves
+ * `[sinceVersion(last), MaxSupportedVersion)`.
+ *
+ * @remarks
+ *   This is the shape registration has everywhere in the SDK — a variant, codec or prover says which version it starts
+ *   answering for, never which version it stops at — so the boundary between two of them is derived in exactly one
+ *   place and cannot drift.
+ * @param activations The values and the versions they activate at, in strictly ascending order.
+ * @returns The registry, or a {@link RegistryError} naming the versions that broke the ordering.
+ */
+export declare const makeRegistryFromActivations: <T>(activations: readonly Readonly<{
+    sinceVersion: ProtocolVersion;
+    value: T;
+}>[]) => Either.Either<Registry<T>, RegistryError>;
+/**
+ * Finds the entry whose range contains a given protocol version.
+ *
+ * @param registry The {@link Registry} to search.
+ * @param version The version to find an entry for.
+ * @returns The matching entry, or `Option.none()` when no entry covers `version`.
+ */
+export declare const selectEntry: <T>(registry: Registry<T>, version: ProtocolVersion) => Option.Option<RegistryEntry<T>>;
+/**
+ * Finds the value whose range contains a given protocol version.
+ *
+ * @param registry The {@link Registry} to search.
+ * @param version The version to find a value for.
+ * @returns The matching value, or `Option.none()` when no entry covers `version`.
+ */
+export declare const select: <T>(registry: Registry<T>, version: ProtocolVersion) => Option.Option<T>;
+export {};

package/dist/ProtocolVersion.js

@@ -11,6 +11,9 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 import * as Brand from 'effect/Brand';
+import * as Data from 'effect/Data';
+import * as Either from 'effect/Either';
+import * as Option from 'effect/Option';
 import * as Schema from 'effect/Schema';
 /** Constructs a branded `bigint` represents a protocol version. */
 export const ProtocolVersion = Brand.nominal();
@@ -52,3 +55,124 @@ export const is = Schema.is(ProtocolVersionSchema);
 export const MinSupportedVersion = ProtocolVersion(0n);
 /** Represents the maximum supported protocol version. */
 export const MaxSupportedVersion = ProtocolVersion(BigInt(Number.MAX_SAFE_INTEGER));
+/**
+ * The protocol version a ledger-v9-native chain hands over at, for the current node line.
+ *
+ * @remarks
+ *   Measured, not assumed: a `midnight-node` 2.x reports protocol version `2000000` on its ledger events — the runtime
+ *   version, scaled, rather than a small ordinal or the ledger major. A chain of the previous node line reports a
+ *   1.x-encoded value, which is below this, so a wallet configured with it stays on the V1 variant there and reaches
+ *   the V2 variant on any v9-native chain.
+ *
+ *   Offered as a named value so applications and test suites pointed at a v9-native chain do not each invent a magic
+ *   number; {@link V9NativeForkSchedule} is the schedule built from it. The final mainnet fork constant is still an open
+ *   question; when it is fixed it will join this one here.
+ */
+export const V9NativeForkVersion = ProtocolVersion(2000000n);
+/**
+ * The fork schedule of a chain born on ledger-v9: ledger-v9 from {@link V9NativeForkVersion}, and nothing else.
+ *
+ * @remarks
+ *   Offered as a named value for the same reason {@link V9NativeForkVersion} is: so applications and test suites pointed
+ *   at a v9-native chain do not each write the schedule out by hand. A named value and not a default — the wallet
+ *   packages still require `forks`. The facade's `DefaultForkSchedule` is this value, under the name of what the facade
+ *   presets.
+ */
+export const V9NativeForkSchedule = { v9: V9NativeForkVersion };
+/**
+ * The range of protocol versions on the same side of a protocol boundary as a given version.
+ *
+ * @remarks
+ *   What the SDK means by "the same ledger version made these bytes". A protocol boundary divides the timeline into two
+ *   epochs, and everything that routes on a version — which prover proves a transaction, which validator checks it,
+ *   which variant may unwrap it — is really asking which epoch it belongs to. Stated once here so the two ends of that
+ *   question, the wallet stamping a transaction and the caller unwrapping it, cannot compute the boundary differently.
+ *
+ *   A chain whose boundary is at or below the minimum supported version has never had two epochs, so the whole range is
+ *   one.
+ * @param version A version in the epoch of interest.
+ * @param forkVersion The version at which the chain hands over to the next ledger version.
+ * @returns The half-open range of versions in that epoch.
+ */
+export const epochOf = (version, forkVersion) => forkVersion <= MinSupportedVersion
+    ? makeRange(MinSupportedVersion, MaxSupportedVersion)
+    : version < forkVersion
+        ? makeRange(MinSupportedVersion, forkVersion)
+        : makeRange(forkVersion, MaxSupportedVersion);
+/**
+ * Raised when entries cannot form a {@link Registry} because their ranges are not ascending, overlap, or cannot be
+ * closed at all.
+ *
+ * @remarks
+ *   Construction is the only place this can happen: once built, a registry is total — selection returns an
+ *   {@link Option.Option} rather than failing.
+ */
+export class RegistryError extends Data.TaggedError('@midnight-ntwrk/wallet-sdk-abstractions/ProtocolVersion/RegistryError') {
+}
+/** A registry with no entries: {@link select} on it never finds anything. */
+export const emptyRegistry = { entries: [] };
+/**
+ * Creates a registry from entries that already carry their own ranges.
+ *
+ * @param entries The entries, in ascending order of range start; ranges must not overlap, though gaps are allowed.
+ * @returns The registry, or a {@link RegistryError} naming the two range boundaries that could not be ordered.
+ */
+export const makeRegistry = (entries) => {
+    const brokenAt = entries.findIndex((entry, index) => index > 0 && entry.range[0] < entries[index - 1].range[1]);
+    return brokenAt < 0
+        ? Either.right({ entries })
+        : Either.left(new RegistryError({
+            message: 'Protocol version registry entries must be ascending and must not overlap.',
+            versions: [entries[brokenAt - 1].range[1], entries[brokenAt].range[0]],
+        }));
+};
+/**
+ * Creates a registry from values keyed by the protocol version each becomes active at, deriving the ranges from the
+ * registration order: entry _i_ serves `[sinceVersion(i), sinceVersion(i + 1))`, and the last entry serves
+ * `[sinceVersion(last), MaxSupportedVersion)`.
+ *
+ * @remarks
+ *   This is the shape registration has everywhere in the SDK — a variant, codec or prover says which version it starts
+ *   answering for, never which version it stops at — so the boundary between two of them is derived in exactly one
+ *   place and cannot drift.
+ * @param activations The values and the versions they activate at, in strictly ascending order.
+ * @returns The registry, or a {@link RegistryError} naming the versions that broke the ordering.
+ */
+export const makeRegistryFromActivations = (activations) => {
+    const brokenAt = activations.findIndex((activation, index) => index > 0 && activation.sinceVersion <= activations[index - 1].sinceVersion);
+    if (brokenAt >= 0) {
+        return Either.left(new RegistryError({
+            message: 'Protocol version activations must be strictly ascending.',
+            versions: [activations[brokenAt - 1].sinceVersion, activations[brokenAt].sinceVersion],
+        }));
+    }
+    const last = activations.at(-1);
+    if (last !== undefined && last.sinceVersion >= MaxSupportedVersion) {
+        return Either.left(new RegistryError({
+            message: 'A protocol version activation must leave room for a range above it.',
+            versions: [last.sinceVersion],
+        }));
+    }
+    return Either.right({
+        entries: activations.map(({ sinceVersion, value }, index) => ({
+            range: makeRange(sinceVersion, activations[index + 1]?.sinceVersion ?? MaxSupportedVersion),
+            value,
+        })),
+    });
+};
+/**
+ * Finds the entry whose range contains a given protocol version.
+ *
+ * @param registry The {@link Registry} to search.
+ * @param version The version to find an entry for.
+ * @returns The matching entry, or `Option.none()` when no entry covers `version`.
+ */
+export const selectEntry = (registry, version) => Option.fromNullable(registry.entries.find((entry) => withinRange(version, entry.range)));
+/**
+ * Finds the value whose range contains a given protocol version.
+ *
+ * @param registry The {@link Registry} to search.
+ * @param version The version to find a value for.
+ * @returns The matching value, or `Option.none()` when no entry covers `version`.
+ */
+export const select = (registry, version) => selectEntry(registry, version).pipe(Option.map((entry) => entry.value));

package/dist/TokenType.d.ts

@@ -0,0 +1,57 @@
+import * as Either from 'effect/Either';
+/**
+ * A token type, in the raw form every balance and coin is keyed by.
+ *
+ * @remarks
+ *   Deliberately a plain `string` and **not** a branded type, which is a considered exception to this codebase's
+ *   parse-don't-validate default. Balances are `Record<TokenType, bigint>`, and a branded key type does not produce a
+ *   string index signature: branding here would break every balance read in the SDK and in every application, to buy a
+ *   guarantee that the values are not confusable with anything else a caller holds anyway. Use {@link parseTokenType} at
+ *   the boundary where a token type arrives from outside, which is where the guarantee is actually worth having.
+ */
+export type TokenType = string;
+declare const InvalidTokenTypeError_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-abstractions/TokenType/InvalidTokenTypeError";
+} & Readonly<A>;
+/** Raised when a value offered as a token type is not one. */
+export declare class InvalidTokenTypeError extends InvalidTokenTypeError_base<{
+    readonly message: string;
+    /** What was offered, so the caller can report it alongside the field it came from. */
+    readonly value: string;
+}> {
+}
+/**
+ * The token types the SDK names.
+ *
+ * @remarks
+ *   String literals rather than calls into a ledger, and that is load-bearing: these constants reach an application
+ *   through the umbrella package's root barrel, which is the one place no ledger version's WebAssembly may be loaded. A
+ *   test pins each of them against both ledger versions, so the literal cannot drift away from what the chain means.
+ *
+ *   There is one constant because there is one raw type to name. Both ledger versions report the same thirty-two bytes
+ *   for the native, shielded and unshielded token; what distinguishes them is a `tag` on the ledger's own wrapper, and
+ *   a balance is keyed by the raw type alone.
+ */
+export declare const Token: {
+    /** Night: the token the chain is denominated in, and the resource Dust is generated from. */
+    readonly night: "0000000000000000000000000000000000000000000000000000000000000000";
+};
+/**
+ * Reads a token type from a value that came from outside the SDK.
+ *
+ * @remarks
+ *   The boundary check the unbranded {@link TokenType} does not make for itself: a dApp request, a URL parameter or a
+ *   configuration file can carry anything, and a token type that is quietly wrong selects no coins rather than failing.
+ *   Returns rather than throws, because "this is not a token type" is an ordinary thing for input to be.
+ * @example
+ *   ```typescript
+ *   const tokenType = parseTokenType(request.tokenType).pipe(
+ *     Either.getOrElse(() => Token.night),
+ *   );
+ *   ```;
+ *
+ * @param value The value offered as a token type.
+ * @returns The token type, or an {@link InvalidTokenTypeError} naming what was offered.
+ */
+export declare const parseTokenType: (value: string) => Either.Either<TokenType, InvalidTokenTypeError>;
+export {};

package/dist/TokenType.js

@@ -0,0 +1,68 @@
+// 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.
+/**
+ * The names the SDK gives to token types, so an application never has to ask a ledger version for one.
+ *
+ * @remarks
+ *   A token type is thirty-two bytes, written as hexadecimal, and it is the same thirty-two bytes on either side of a
+ *   protocol boundary — which is the whole reason the SDK can name one for itself. Until now an application wanting the
+ *   Night token type had to call `nativeToken().raw` on a ledger package, which meant importing a ledger version to
+ *   read a constant that does not depend on one.
+ */
+import * as Data from 'effect/Data';
+import * as Either from 'effect/Either';
+/** Raised when a value offered as a token type is not one. */
+export class InvalidTokenTypeError extends Data.TaggedError('@midnight-ntwrk/wallet-sdk-abstractions/TokenType/InvalidTokenTypeError') {
+}
+/** Thirty-two bytes of lower-case hexadecimal: the form both ledger versions write a token type in. */
+const TOKEN_TYPE_PATTERN = /^[0-9a-f]{64}$/;
+/**
+ * The token types the SDK names.
+ *
+ * @remarks
+ *   String literals rather than calls into a ledger, and that is load-bearing: these constants reach an application
+ *   through the umbrella package's root barrel, which is the one place no ledger version's WebAssembly may be loaded. A
+ *   test pins each of them against both ledger versions, so the literal cannot drift away from what the chain means.
+ *
+ *   There is one constant because there is one raw type to name. Both ledger versions report the same thirty-two bytes
+ *   for the native, shielded and unshielded token; what distinguishes them is a `tag` on the ledger's own wrapper, and
+ *   a balance is keyed by the raw type alone.
+ */
+export const Token = {
+    /** Night: the token the chain is denominated in, and the resource Dust is generated from. */
+    night: '0000000000000000000000000000000000000000000000000000000000000000',
+};
+/**
+ * Reads a token type from a value that came from outside the SDK.
+ *
+ * @remarks
+ *   The boundary check the unbranded {@link TokenType} does not make for itself: a dApp request, a URL parameter or a
+ *   configuration file can carry anything, and a token type that is quietly wrong selects no coins rather than failing.
+ *   Returns rather than throws, because "this is not a token type" is an ordinary thing for input to be.
+ * @example
+ *   ```typescript
+ *   const tokenType = parseTokenType(request.tokenType).pipe(
+ *     Either.getOrElse(() => Token.night),
+ *   );
+ *   ```;
+ *
+ * @param value The value offered as a token type.
+ * @returns The token type, or an {@link InvalidTokenTypeError} naming what was offered.
+ */
+export const parseTokenType = (value) => TOKEN_TYPE_PATTERN.test(value)
+    ? Either.right(value)
+    : Either.left(new InvalidTokenTypeError({
+        message: `"${value}" is not a token type: a token type is thirty-two bytes written as sixty-four lower-case ` +
+            `hexadecimal characters.`,
+        value,
+    }));

package/dist/TransactionHistoryStorage.d.ts

@@ -109,6 +109,16 @@ export type RejectedTransactionHistoryCommon = TransactionHistoryEntryCommon & {
     readonly lifecycle: RejectedLifecycle;
 };
 export type SerializedTransactionHistory = string;
+/**
+ * Whether `entry` records the transaction `key` names: the same hash, or every one of `key`'s identifiers. Identifiers
+ * are per-build commitments, so an entry carrying all of them is the same transaction included under an aggregated
+ * hash. An empty identifier set names no transaction and therefore neither covers nor is covered.
+ *
+ * @param entry - The recorded entry.
+ * @param key - The hash and identifiers of the transaction being asked about.
+ * @returns Whether `entry` is a record of that transaction.
+ */
+export declare const coversTransaction: (entry: Pick<TransactionHistoryEntryCommon, "hash" | "identifiers">, key: Pick<TransactionHistoryEntryCommon, "hash" | "identifiers">) => boolean;
 /**
  * An entry with common fields plus any additional properties (wallet sections). Used by wallet packages for
  * projection/filtering when the exact type is not known.
@@ -160,6 +170,11 @@ export interface TransactionHistoryReader<T extends {
  * keys (in particular: clearing a prior `pending` entry keyed by an identifier when its `finalized` or `rejected`
  * counterpart arrives keyed by the tx hash).
  *
+ * Recorded inclusion takes precedence over a later rejection. Sync records inclusion independently of the
+ * pending-status poller, so a verdict may arrive after a `finalized` entry {@link coversTransaction covers} the
+ * transaction, and that verdict must neither overwrite the entry nor leave a rejected duplicate under the submission's
+ * own hash. Implementations check this atomically with the write.
+ *
  * `T` appears only in input position, so this interface is **contravariant** in T: a `TransactionHistoryWriter<Wider>`
  * is assignable to `TransactionHistoryWriter<Narrower>`.
  */
@@ -167,13 +182,14 @@ export interface TransactionHistoryWriter<T extends TransactionHistoryEntryCommo
     /** Record that a tx has been submitted and is awaiting confirmation. */
     gotPending(entry: PendingEntryInput<T>): Promise<void>;
     /**
-     * Record that a tx has been confirmed on-chain. Inserts/merges the entry under its tx hash and clears any earlier
-     * `pending` entry whose identifiers are contained in this entry's identifier set.
+     * Record that a tx has been confirmed on-chain. Inserts/merges the entry under its tx hash and clears every earlier
+     * `pending` or `rejected` entry this entry {@link coversTransaction covers} under another hash.
      */
     gotFinalized(entry: FinalizedEntryInput<T>): Promise<void>;
     /**
      * Record that a tx will not land — failed, partial-success, TTL-expired, or otherwise reverted. Keyed the same way as
-     * `gotPending` so the lifecycle transition is in-place.
+     * `gotPending` so the lifecycle transition is in-place. Writes nothing when a `finalized` entry already covers the
+     * tx.
      */
     gotRejected(entry: RejectedEntryInput<T>): Promise<void>;
 }

package/dist/TransactionHistoryStorage.js

@@ -71,3 +71,18 @@ export const extendEntrySchema = (extensionFields) => Schema.Struct({
     ...TransactionHistoryEntryCommonSchema.fields,
     ...extensionFields,
 });
+/**
+ * Whether `entry` records the transaction `key` names: the same hash, or every one of `key`'s identifiers. Identifiers
+ * are per-build commitments, so an entry carrying all of them is the same transaction included under an aggregated
+ * hash. An empty identifier set names no transaction and therefore neither covers nor is covered.
+ *
+ * @param entry - The recorded entry.
+ * @param key - The hash and identifiers of the transaction being asked about.
+ * @returns Whether `entry` is a record of that transaction.
+ */
+export const coversTransaction = (entry, key) => {
+    if (entry.hash === key.hash)
+        return true;
+    const recorded = new Set(entry.identifiers);
+    return key.identifiers.length > 0 && key.identifiers.every((id) => recorded.has(id));
+};

package/dist/WalletTransaction.d.ts

@@ -0,0 +1,207 @@
+import * as Either from 'effect/Either';
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+import * as ProtocolVersion from './ProtocolVersion.js';
+import * as SerializedTransaction from './SerializedTransaction.js';
+/**
+ * The three stages, as the one thing that decides what they are.
+ *
+ * @remarks
+ *   Declared here rather than beside the wire envelope that reads it, because {@link TransactionStage} — the type an
+ *   application names — is read back off it. Stating the three words once means the type a caller is held to and the
+ *   values an envelope is parsed against cannot come to disagree: adding a stage to one adds it to the other.
+ */
+declare const TransactionStageSchema: Schema.Literal<["Unproven", "Unbound", "Finalized"]>;
+/**
+ * How far along the building of a transaction a handle is.
+ *
+ * @remarks
+ *   The three points at which a transaction changes hands between an application and the SDK: built but not proved,
+ *   proved but not yet bound to its own contents, and finalized — proved, signed and bound, which is the only shape the
+ *   network takes. Both ledger versions have all three, and the words mean the same thing on either side of a protocol
+ *   boundary, which is why the stage can be plain data on a version-agnostic handle.
+ */
+export type TransactionStage = Schema.Schema.Type<typeof TransactionStageSchema>;
+/** What a handle can carry: anything that can write itself out as bytes, which is every ledger's transaction. */
+type Serializable = Readonly<{
+    serialize: () => Uint8Array;
+}>;
+declare const ProtocolVersionMismatchError_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-abstractions/WalletTransaction/ProtocolVersionMismatchError";
+} & Readonly<A>;
+/**
+ * Raised when a transaction is used at a protocol version other than the one it was built for.
+ *
+ * @remarks
+ *   The bytes of a transaction are fixed when it is built, by the ledger version that built them. A protocol boundary
+ *   does not rewrite them, so a transaction authored on one side of the boundary cannot be understood on the other —
+ *   not merged, not proved, not submitted. This is what the SDK answers with rather than handing a transaction to a
+ *   ledger version that would misread it.
+ */
+export declare class ProtocolVersionMismatchError extends ProtocolVersionMismatchError_base<{
+    readonly message: string;
+    /** The protocol version the transaction was built at. */
+    readonly authoredFor: ProtocolVersion.ProtocolVersion;
+    /** The range of protocol versions the caller can act at. */
+    readonly accepted: ProtocolVersion.ProtocolVersion.Range;
+    /** How far along the building of the transaction the handle is, for the diagnostic. */
+    readonly stage: TransactionStage;
+}> {
+}
+declare const WireFormatError_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-abstractions/WalletTransaction/WireFormatError";
+} & Readonly<A>;
+/**
+ * Raised when bytes cannot be read as a transaction of a version this SDK knows — whether they arrived in a wire
+ * envelope that names their version, or bare, to be read at the version the reader is acting at.
+ */
+export declare class WireFormatError extends WireFormatError_base<{
+    readonly message: string;
+    /** What went wrong underneath: a parse failure, or whatever the caller's decoder raised. */
+    readonly cause?: unknown;
+}> {
+}
+/**
+ * The envelope a handle crosses a process boundary in.
+ *
+ * @remarks
+ *   Everything in it is JSON-safe, because the boundary it was designed for — a dApp connector — is a JSON one: the
+ *   protocol version is a decimal string rather than a `bigint`, and the transaction is hex rather than bytes. What
+ *   travels is exactly what a reader needs to decide whether it can read the rest at all: the envelope format, the
+ *   protocol version the transaction was built at, the stage it reached, and the transaction's own serialization.
+ *
+ *   Kept deliberately small. The connector contract is an open question at the time of writing, and an envelope that
+ *   guesses at it would be harder to reconcile than one that carries the minimum.
+ */
+declare const WireTransactionSchema: Schema.Struct<{
+    wireFormat: Schema.Literal<[1]>;
+    protocolVersion: Schema.BrandSchema<bigint & import("effect/Brand").Brand<"ProtocolVersion">, string, never>;
+    stage: Schema.Literal<["Unproven", "Unbound", "Finalized"]>;
+    transaction: Schema.Schema<Uint8Array<ArrayBufferLike>, string, never>;
+}>;
+/** The wire envelope as it travels: a plain JSON-safe record. See {@link WalletTransaction.toWire}. */
+export type WireTransaction = Schema.Schema.Encoded<typeof WireTransactionSchema>;
+/**
+ * A transaction the SDK produced or adopted, sealed together with the protocol version it was built at.
+ *
+ * @remarks
+ *   A class rather than a record, and the one place in this package where that earns its keep: a `#private` field is the
+ *   only way to carry something an application provably cannot reach, and reaching the wrapped transaction is exactly
+ *   what would re-introduce the ledger-version dependency the handle exists to remove. Nothing about it mutates — the
+ *   fields are read-only and every operation returns a new value.
+ *
+ *   The stage is a type parameter as well as a field, so a signature can ask for the shape it needs
+ *   (`WalletTransaction<'Finalized'>`, spelled {@link FinalizedTx}) and a caller who has an unproven transaction finds
+ *   out at compile time. It is covariant: a `FinalizedTx` is an {@link AnyTx}, which is what the operations that accept
+ *   a transaction at any stage — reverting one, say — are stated in terms of.
+ * @example
+ *   Sealing a transaction an application built for itself, and handing it back to the wallet:
+ *
+ *   ```typescript
+ *   import * as ledger from '@midnight-ntwrk/wallet-sdk/ledger/v9';
+ *
+ *   const intent = ledger.Intent.new(ttl);
+ *   const handle = WalletTransaction.adopt('Unproven', ledger.Transaction.fromParts(networkId, undefined, undefined, intent), version);
+ *   ```;
+ *
+ * @typeParam TStage How far along the building of this transaction the handle is.
+ */
+export declare class WalletTransaction<out TStage extends TransactionStage = TransactionStage> {
+    #private;
+    /** The protocol version this transaction was built at, and so the only one it can be used at. */
+    readonly protocolVersion: ProtocolVersion.ProtocolVersion;
+    /** How far along the building of this transaction the handle is. */
+    readonly stage: TStage;
+    private constructor();
+    /**
+     * Seals a transaction built elsewhere into a handle.
+     *
+     * @remarks
+     *   How an application that builds its own transactions — with the ledger version it imported from
+     *   `@midnight-ntwrk/wallet-sdk/ledger/v8` or `/v9` — hands one to the wallet. The version passed here is a claim
+     *   about which ledger version produced the transaction, and the SDK holds the caller to it: a handle stamped for one
+     *   side of a protocol boundary is refused by a wallet acting on the other side, with a
+     *   {@link ProtocolVersionMismatchError}. Until the fork, that means a transaction built with ledger-v9 is refused at
+     *   run time, however well it type-checks.
+     * @param stage How far along the building of the transaction is.
+     * @param transaction The transaction, of whichever ledger version built it.
+     * @param protocolVersion The protocol version that ledger version serves.
+     * @returns The sealed handle.
+     */
+    static adopt<TStage extends TransactionStage>(stage: TStage, transaction: Serializable, protocolVersion: ProtocolVersion.ProtocolVersion): WalletTransaction<TStage>;
+    /**
+     * Reads the transaction a handle carries, if it was built for a protocol version the caller can act at.
+     *
+     * @remarks
+     *   The SDK's own way in, and the enforcement point for everything an application hands back: a caller states the range
+     *   of protocol versions it speaks — a variant's activation range, or the era the chain is currently in — and gets
+     *   the transaction only when the stamp falls inside it. The result type is the caller's to name, because the handle
+     *   deliberately does not remember it; the range is the whole of the guarantee, which is why it is checked here
+     *   rather than trusted anywhere else.
+     * @param handle The handle to read.
+     * @param accepted The range of protocol versions the caller can act at.
+     * @returns The carried transaction, or a {@link ProtocolVersionMismatchError} naming what was carried and what was
+     *   asked for.
+     */
+    static unwrapWithin<T>(handle: WalletTransaction, accepted: ProtocolVersion.ProtocolVersion.Range): Either.Either<T, ProtocolVersionMismatchError>;
+    /**
+     * Narrows a handle to a stage, for a caller that has one of unknown stage.
+     *
+     * @param handle The handle to narrow.
+     * @param stage The stage to narrow it to.
+     * @returns The same handle, typed at that stage, or nothing when it is at another.
+     */
+    static atStage<TStage extends TransactionStage>(handle: WalletTransaction, stage: TStage): Option.Option<WalletTransaction<TStage>>;
+    /**
+     * Determines whether a value is a handle this SDK produced.
+     *
+     * @remarks
+     *   Answers on the sealed transaction itself, so a record that merely has the same readable fields is not mistaken for
+     *   one.
+     * @param value The value to test.
+     * @returns `true` when `value` is a {@link WalletTransaction}.
+     */
+    static is(value: unknown): value is WalletTransaction;
+    /**
+     * Writes a handle out as an envelope that can cross a process boundary.
+     *
+     * @param handle The handle to write out.
+     * @returns The envelope. See {@link WireTransaction}.
+     */
+    static toWire(handle: WalletTransaction): WireTransaction;
+    /**
+     * Reads an envelope back into a handle, decoding its bytes with whichever ledger version the envelope names.
+     *
+     * @remarks
+     *   The decoder is the caller's because the choice of ledger version is: this package has none, and picking one here
+     *   would be the hardcoded version the handle exists to avoid. It is handed the version and stage the envelope
+     *   declares so it can route on them, and it may raise — a deserializer meeting bytes of another ledger version does
+     *   — which is reported as a {@link WireFormatError} rather than escaping.
+     * @param value The envelope, as received.
+     * @param decode Produces the transaction from the envelope's bytes, at the version and stage it names.
+     * @returns The handle, or a {@link WireFormatError} describing what could not be read.
+     */
+    static fromWire(value: unknown, decode: (bytes: Uint8Array, protocolVersion: ProtocolVersion.ProtocolVersion, stage: TransactionStage) => Serializable): Either.Either<WalletTransaction, WireFormatError>;
+    /**
+     * Writes the carried transaction out as bytes.
+     *
+     * @remarks
+     *   The one thing every ledger version's transaction can do identically, and so the one thing a handle can offer
+     *   without knowing which produced it. What the bytes mean still depends on {@link protocolVersion}.
+     * @returns The transaction's own serialization.
+     */
+    serialize(): SerializedTransaction.SerializedTransaction;
+}
+export declare namespace WalletTransaction {
+    /** How far along the building of a transaction a handle is. See {@link TransactionStage}. */
+    type Stage = TransactionStage;
+}
+/** A transaction that has been built but not proved. */
+export type UnprovenTx = WalletTransaction<'Unproven'>;
+/** A transaction that has been proved but not yet bound to its own contents. */
+export type UnboundTx = WalletTransaction<'Unbound'>;
+/** A transaction that is proved, signed and bound: the only shape the network takes. */
+export type FinalizedTx = WalletTransaction<'Finalized'>;
+/** A transaction at whichever stage it happens to have reached. */
+export type AnyTx = WalletTransaction<TransactionStage>;
+export {};

package/dist/WalletTransaction.js

@@ -0,0 +1,250 @@
+// 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.
+/**
+ * The one transaction type an application carries, whichever ledger version produced it.
+ *
+ * @remarks
+ *   An SDK that runs one ledger version before a protocol boundary and another from it has a problem its callers should
+ *   never have to solve: a transaction built before the boundary and a transaction built after it are objects of two
+ *   different runtimes, with two different types, and no conversion between them. Naming either type in a public
+ *   signature is naming a ledger version, which is the thing that breaks when the chain moves on.
+ *
+ *   So the wallet layer hands out a handle instead. It seals the transaction away — an application cannot reach it, and
+ *   so cannot come to depend on which version made it — and carries the protocol version it was built at as ordinary
+ *   readable data. That stamp is what the SDK routes on: which prover proves it, which trait recognises it, which
+ *   variant may unwrap it at all.
+ */
+import * as Data from 'effect/Data';
+import * as Either from 'effect/Either';
+import * as Option from 'effect/Option';
+import * as ParseResult from 'effect/ParseResult';
+import * as Schema from 'effect/Schema';
+import * as ProtocolVersion from './ProtocolVersion.js';
+import * as SerializedTransaction from './SerializedTransaction.js';
+/**
+ * The three stages, as the one thing that decides what they are.
+ *
+ * @remarks
+ *   Declared here rather than beside the wire envelope that reads it, because {@link TransactionStage} — the type an
+ *   application names — is read back off it. Stating the three words once means the type a caller is held to and the
+ *   values an envelope is parsed against cannot come to disagree: adding a stage to one adds it to the other.
+ */
+const TransactionStageSchema = Schema.Literal('Unproven', 'Unbound', 'Finalized');
+/**
+ * Raised when a transaction is used at a protocol version other than the one it was built for.
+ *
+ * @remarks
+ *   The bytes of a transaction are fixed when it is built, by the ledger version that built them. A protocol boundary
+ *   does not rewrite them, so a transaction authored on one side of the boundary cannot be understood on the other —
+ *   not merged, not proved, not submitted. This is what the SDK answers with rather than handing a transaction to a
+ *   ledger version that would misread it.
+ */
+export class ProtocolVersionMismatchError extends Data.TaggedError('@midnight-ntwrk/wallet-sdk-abstractions/WalletTransaction/ProtocolVersionMismatchError') {
+}
+/**
+ * Raised when bytes cannot be read as a transaction of a version this SDK knows — whether they arrived in a wire
+ * envelope that names their version, or bare, to be read at the version the reader is acting at.
+ */
+export class WireFormatError extends Data.TaggedError('@midnight-ntwrk/wallet-sdk-abstractions/WalletTransaction/WireFormatError') {
+}
+/**
+ * The envelope's own format version.
+ *
+ * @remarks
+ *   Deliberately separate from the protocol version it carries. A reader has to be able to tell "I do not know this
+ *   envelope" from "I do not know this ledger version", because only the second is a chain fact.
+ */
+const WIRE_FORMAT = 1;
+/**
+ * The envelope a handle crosses a process boundary in.
+ *
+ * @remarks
+ *   Everything in it is JSON-safe, because the boundary it was designed for — a dApp connector — is a JSON one: the
+ *   protocol version is a decimal string rather than a `bigint`, and the transaction is hex rather than bytes. What
+ *   travels is exactly what a reader needs to decide whether it can read the rest at all: the envelope format, the
+ *   protocol version the transaction was built at, the stage it reached, and the transaction's own serialization.
+ *
+ *   Kept deliberately small. The connector contract is an open question at the time of writing, and an envelope that
+ *   guesses at it would be harder to reconcile than one that carries the minimum.
+ */
+const WireTransactionSchema = Schema.Struct({
+    wireFormat: Schema.Literal(WIRE_FORMAT),
+    protocolVersion: ProtocolVersion.ProtocolVersionSchema,
+    stage: TransactionStageSchema,
+    transaction: Schema.Uint8ArrayFromHex,
+});
+const encodeWire = Schema.encodeSync(WireTransactionSchema);
+const decodeWire = Schema.decodeUnknownEither(WireTransactionSchema);
+/**
+ * A transaction the SDK produced or adopted, sealed together with the protocol version it was built at.
+ *
+ * @remarks
+ *   A class rather than a record, and the one place in this package where that earns its keep: a `#private` field is the
+ *   only way to carry something an application provably cannot reach, and reaching the wrapped transaction is exactly
+ *   what would re-introduce the ledger-version dependency the handle exists to remove. Nothing about it mutates — the
+ *   fields are read-only and every operation returns a new value.
+ *
+ *   The stage is a type parameter as well as a field, so a signature can ask for the shape it needs
+ *   (`WalletTransaction<'Finalized'>`, spelled {@link FinalizedTx}) and a caller who has an unproven transaction finds
+ *   out at compile time. It is covariant: a `FinalizedTx` is an {@link AnyTx}, which is what the operations that accept
+ *   a transaction at any stage — reverting one, say — are stated in terms of.
+ * @example
+ *   Sealing a transaction an application built for itself, and handing it back to the wallet:
+ *
+ *   ```typescript
+ *   import * as ledger from '@midnight-ntwrk/wallet-sdk/ledger/v9';
+ *
+ *   const intent = ledger.Intent.new(ttl);
+ *   const handle = WalletTransaction.adopt('Unproven', ledger.Transaction.fromParts(networkId, undefined, undefined, intent), version);
+ *   ```;
+ *
+ * @typeParam TStage How far along the building of this transaction the handle is.
+ */
+export class WalletTransaction {
+    /** The protocol version this transaction was built at, and so the only one it can be used at. */
+    protocolVersion;
+    /** How far along the building of this transaction the handle is. */
+    stage;
+    /** The transaction itself, reachable only from inside this class. */
+    #carried;
+    constructor(protocolVersion, stage, carried) {
+        this.protocolVersion = protocolVersion;
+        this.stage = stage;
+        this.#carried = carried;
+    }
+    /**
+     * Seals a transaction built elsewhere into a handle.
+     *
+     * @remarks
+     *   How an application that builds its own transactions — with the ledger version it imported from
+     *   `@midnight-ntwrk/wallet-sdk/ledger/v8` or `/v9` — hands one to the wallet. The version passed here is a claim
+     *   about which ledger version produced the transaction, and the SDK holds the caller to it: a handle stamped for one
+     *   side of a protocol boundary is refused by a wallet acting on the other side, with a
+     *   {@link ProtocolVersionMismatchError}. Until the fork, that means a transaction built with ledger-v9 is refused at
+     *   run time, however well it type-checks.
+     * @param stage How far along the building of the transaction is.
+     * @param transaction The transaction, of whichever ledger version built it.
+     * @param protocolVersion The protocol version that ledger version serves.
+     * @returns The sealed handle.
+     */
+    static adopt(stage, transaction, protocolVersion) {
+        return new WalletTransaction(protocolVersion, stage, transaction);
+    }
+    /**
+     * Reads the transaction a handle carries, if it was built for a protocol version the caller can act at.
+     *
+     * @remarks
+     *   The SDK's own way in, and the enforcement point for everything an application hands back: a caller states the range
+     *   of protocol versions it speaks — a variant's activation range, or the era the chain is currently in — and gets
+     *   the transaction only when the stamp falls inside it. The result type is the caller's to name, because the handle
+     *   deliberately does not remember it; the range is the whole of the guarantee, which is why it is checked here
+     *   rather than trusted anywhere else.
+     * @param handle The handle to read.
+     * @param accepted The range of protocol versions the caller can act at.
+     * @returns The carried transaction, or a {@link ProtocolVersionMismatchError} naming what was carried and what was
+     *   asked for.
+     */
+    static unwrapWithin(handle, accepted) {
+        if (!ProtocolVersion.withinRange(handle.protocolVersion, accepted)) {
+            const [from, to] = accepted;
+            return Either.left(new ProtocolVersionMismatchError({
+                message: `This transaction was built for protocol version ${handle.protocolVersion}, and can only be used at ` +
+                    `that version: its bytes were fixed by the ledger version that produced them. The caller acts at ` +
+                    `protocol versions ${from} up to (but not including) ${to}. Build the transaction again on the side of ` +
+                    `the protocol boundary it is to be used on.`,
+                authoredFor: handle.protocolVersion,
+                accepted,
+                stage: handle.stage,
+            }));
+        }
+        // The carried type is erased when a transaction is sealed, and deliberately: remembering it would put a ledger
+        // version back into the handle's own type. The version check above is the whole of what can be guaranteed here,
+        // and it is the same guarantee the caller would have had to make for itself.
+        return Either.right(handle.#carried);
+    }
+    /**
+     * Narrows a handle to a stage, for a caller that has one of unknown stage.
+     *
+     * @param handle The handle to narrow.
+     * @param stage The stage to narrow it to.
+     * @returns The same handle, typed at that stage, or nothing when it is at another.
+     */
+    static atStage(handle, stage) {
+        return handle.stage === stage
+            ? // Narrowed by the value that the type parameter names; `stage` is the only thing distinguishing the two types.
+                Option.some(handle)
+            : Option.none();
+    }
+    /**
+     * Determines whether a value is a handle this SDK produced.
+     *
+     * @remarks
+     *   Answers on the sealed transaction itself, so a record that merely has the same readable fields is not mistaken for
+     *   one.
+     * @param value The value to test.
+     * @returns `true` when `value` is a {@link WalletTransaction}.
+     */
+    static is(value) {
+        return typeof value === 'object' && value !== null && #carried in value;
+    }
+    /**
+     * Writes a handle out as an envelope that can cross a process boundary.
+     *
+     * @param handle The handle to write out.
+     * @returns The envelope. See {@link WireTransaction}.
+     */
+    static toWire(handle) {
+        return encodeWire({
+            wireFormat: WIRE_FORMAT,
+            protocolVersion: handle.protocolVersion,
+            stage: handle.stage,
+            transaction: handle.serialize(),
+        });
+    }
+    /**
+     * Reads an envelope back into a handle, decoding its bytes with whichever ledger version the envelope names.
+     *
+     * @remarks
+     *   The decoder is the caller's because the choice of ledger version is: this package has none, and picking one here
+     *   would be the hardcoded version the handle exists to avoid. It is handed the version and stage the envelope
+     *   declares so it can route on them, and it may raise — a deserializer meeting bytes of another ledger version does
+     *   — which is reported as a {@link WireFormatError} rather than escaping.
+     * @param value The envelope, as received.
+     * @param decode Produces the transaction from the envelope's bytes, at the version and stage it names.
+     * @returns The handle, or a {@link WireFormatError} describing what could not be read.
+     */
+    static fromWire(value, decode) {
+        return decodeWire(value).pipe(Either.mapLeft((error) => new WireFormatError({
+            message: `This is not a transaction envelope this SDK can read: ${ParseResult.TreeFormatter.formatErrorSync(error)}`,
+            cause: error,
+        })), Either.flatMap((envelope) => Either.try({
+            try: () => decode(envelope.transaction, envelope.protocolVersion, envelope.stage),
+            catch: (cause) => new WireFormatError({
+                message: `The envelope declares protocol version ${envelope.protocolVersion}, but its bytes could not be ` +
+                    `read as a ${envelope.stage.toLowerCase()} transaction of that version.`,
+                cause,
+            }),
+        }).pipe(Either.map((transaction) => WalletTransaction.adopt(envelope.stage, transaction, envelope.protocolVersion)))));
+    }
+    /**
+     * Writes the carried transaction out as bytes.
+     *
+     * @remarks
+     *   The one thing every ledger version's transaction can do identically, and so the one thing a handle can offer
+     *   without knowing which produced it. What the bytes mean still depends on {@link protocolVersion}.
+     * @returns The transaction's own serialization.
+     */
+    serialize() {
+        return SerializedTransaction.from(this.#carried);
+    }
+}

package/dist/index.d.ts

@@ -5,6 +5,8 @@ export * as ProtocolState from './ProtocolState.js';
 export * as ProtocolVersion from './ProtocolVersion.js';
 export * as NetworkId from './NetworkId.js';
 export * as SyncProgress from './SyncProgress.js';
+export * from './TokenType.js';
+export * from './WalletTransaction.js';
 export * from './InMemoryTransactionHistoryStorage.js';
 export * from './NoOpTransactionHistoryStorage.js';
 export * as TransactionHistoryStorage from './TransactionHistoryStorage.js';

package/dist/index.js

@@ -17,6 +17,8 @@ export * as ProtocolState from './ProtocolState.js';
 export * as ProtocolVersion from './ProtocolVersion.js';
 export * as NetworkId from './NetworkId.js';
 export * as SyncProgress from './SyncProgress.js';
+export * from './TokenType.js';
+export * from './WalletTransaction.js';
 export * from './InMemoryTransactionHistoryStorage.js';
 export * from './NoOpTransactionHistoryStorage.js';
 export * as TransactionHistoryStorage from './TransactionHistoryStorage.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@midnight-ntwrk/wallet-sdk-abstractions",
   "description": "Domain-specific abstractions for the wallet SDK",
-  "version": "3.0.0-beta.0",
+  "version": "3.0.0-beta.2",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",