@midnightntwrk/wallet-sdk-shielded 4.0.0-rc.0 → 4.0.0-rc.1

package/dist/Restore.d.ts

@@ -1,5 +1,5 @@
-import { ProtocolVersion } from '@midnightntwrk/wallet-sdk-abstractions';
-import { Either, Option } from 'effect';
+import { ProtocolVersion, type SnapshotFormat } from '@midnightntwrk/wallet-sdk-abstractions';
+import { type Either, Option } from 'effect';
 declare const UnsupportedSnapshotVersionError_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: "@midnightntwrk/wallet-sdk-shielded/Restore/UnsupportedSnapshotVersionError";
 } & Readonly<A>;
@@ -17,24 +17,41 @@ export declare class UnsupportedSnapshotVersionError extends UnsupportedSnapshot
 }> {
 }
 /**
- * Reads the protocol version a serialized wallet snapshot declares.
+ * Reads the protocol version a serialized shielded wallet snapshot declares.
  *
  * @param serialized The serialized wallet state.
  * @returns The declared version, or `Option.none()` when the snapshot declares none or cannot be read at all.
  */
 export declare const peekProtocolVersion: (serialized: string) => Option.Option<ProtocolVersion.ProtocolVersion>;
 /**
- * Chooses the variant that should read a serialized wallet snapshot.
+ * Reads which variant wrote a serialized shielded wallet snapshot, when it says.
  *
  * @remarks
- *   A snapshot that declares no version predates snapshots declaring one, and can only have been written by the variant
- *   that shipped before the question arose — the head variant. The same fallback covers an envelope this function
- *   cannot read at all: refusing it here would replace the deserializer's precise error with a vaguer one.
+ *   Shielded snapshots carry nothing in their shape that says which variant wrote them, so only the name counts; a
+ *   snapshot written before snapshots named their writer reads as naming none.
+ * @param serialized The serialized wallet state.
+ * @returns The writer, or `Option.none()` when the snapshot predates the field, names a writer this build does not
+ *   know, or cannot be read at all.
+ */
+export declare const peekWriter: (serialized: string) => Option.Option<SnapshotFormat.SnapshotWriter>;
+/**
+ * Chooses the variant that should read a serialized shielded wallet snapshot.
+ *
+ * @remarks
+ *   The rule is {@link SnapshotRouting.routeSnapshot}'s: the variant that wrote the snapshot when it says which and that
+ *   variant is registered, otherwise the variant that owns the declared version, otherwise the head variant. The
+ *   envelope is read once here, not once per question.
  * @param serialized The serialized wallet state.
  * @param variantFor Resolves the variant registered for a protocol version.
  * @param headVariant The variant a snapshot with no declared version is restored into.
- * @returns The variant to restore with, or {@link UnsupportedSnapshotVersionError} when the declared version is one no
- *   registered variant owns.
+ * @param variantWrittenBy Resolves the registered variant that a snapshot names as its writer, if it is registered.
+ *   Defaults to none, which is the routing every caller had before snapshots named their writer.
+ * @param activationOf The protocol version a registered variant starts answering for, as the wallet registered it. The
+ *   writer takes a snapshot only from that version upwards; below it the version routes, since the runtime cannot hand
+ *   over backwards. Defaults to the minimum version, which lets the writer take any snapshot, for compositions that
+ *   pass no writer resolver either.
+ * @returns The variant to restore with, or {@link UnsupportedSnapshotVersionError} when the writer is not registered and
+ *   the declared version is one no registered variant owns.
  */
-export declare const variantForSnapshot: <TVariant>(serialized: string, variantFor: (version: ProtocolVersion.ProtocolVersion) => Option.Option<TVariant>, headVariant: TVariant) => Either.Either<TVariant, UnsupportedSnapshotVersionError>;
+export declare const variantForSnapshot: <TVariant>(serialized: string, variantFor: (version: ProtocolVersion.ProtocolVersion) => Option.Option<TVariant>, headVariant: TVariant, variantWrittenBy?: (writer: SnapshotFormat.SnapshotWriter) => Option.Option<TVariant>, activationOf?: (variant: TVariant) => ProtocolVersion.ProtocolVersion) => Either.Either<TVariant, UnsupportedSnapshotVersionError>;
 export {};

package/dist/Restore.js

@@ -10,8 +10,8 @@
 // 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 '@midnightntwrk/wallet-sdk-abstractions';
-import { Data, Either, Option, Schema } from 'effect';
+import { ProtocolVersion, SnapshotRouting } from '@midnightntwrk/wallet-sdk-abstractions';
+import { Data, Option } from 'effect';
 /**
  * Raised when a snapshot declares a protocol version that no registered variant is able to read.
  *
@@ -23,41 +23,50 @@ import { Data, Either, Option, Schema } from 'effect';
 export class UnsupportedSnapshotVersionError extends Data.TaggedError('@midnightntwrk/wallet-sdk-shielded/Restore/UnsupportedSnapshotVersionError') {
 }
 /**
- * The envelope the peek reads.
+ * Reads the protocol version a serialized shielded wallet snapshot declares.
  *
- * @remarks
- *   Deliberately the smallest possible description of a snapshot: one optional field, every other ignored. It has to read
- *   snapshots written by _any_ variant, including ones whose full schema this build does not have, so it must not
- *   assert anything it does not need. Everything it cannot make sense of is reported as "no version declared", leaving
- *   the real diagnosis to the deserializer that eventually reads the whole thing.
+ * @param serialized The serialized wallet state.
+ * @returns The declared version, or `Option.none()` when the snapshot declares none or cannot be read at all.
  */
-const EnvelopeSchema = Schema.Struct({
-    protocolVersion: Schema.optional(ProtocolVersion.ProtocolVersionSchema),
-});
+export const peekProtocolVersion = (serialized) => SnapshotRouting.readEnvelope(serialized).protocolVersion;
 /**
- * Reads the protocol version a serialized wallet snapshot declares.
+ * Reads which variant wrote a serialized shielded wallet snapshot, when it says.
  *
+ * @remarks
+ *   Shielded snapshots carry nothing in their shape that says which variant wrote them, so only the name counts; a
+ *   snapshot written before snapshots named their writer reads as naming none.
  * @param serialized The serialized wallet state.
- * @returns The declared version, or `Option.none()` when the snapshot declares none or cannot be read at all.
+ * @returns The writer, or `Option.none()` when the snapshot predates the field, names a writer this build does not
+ *   know, or cannot be read at all.
  */
-export const peekProtocolVersion = (serialized) => Schema.decodeUnknownOption(Schema.parseJson(EnvelopeSchema))(serialized).pipe(Option.flatMap((envelope) => Option.fromNullable(envelope.protocolVersion)));
+export const peekWriter = (serialized) => SnapshotRouting.readEnvelope(serialized).writer;
 /**
- * Chooses the variant that should read a serialized wallet snapshot.
+ * Chooses the variant that should read a serialized shielded wallet snapshot.
  *
  * @remarks
- *   A snapshot that declares no version predates snapshots declaring one, and can only have been written by the variant
- *   that shipped before the question arose — the head variant. The same fallback covers an envelope this function
- *   cannot read at all: refusing it here would replace the deserializer's precise error with a vaguer one.
+ *   The rule is {@link SnapshotRouting.routeSnapshot}'s: the variant that wrote the snapshot when it says which and that
+ *   variant is registered, otherwise the variant that owns the declared version, otherwise the head variant. The
+ *   envelope is read once here, not once per question.
  * @param serialized The serialized wallet state.
  * @param variantFor Resolves the variant registered for a protocol version.
  * @param headVariant The variant a snapshot with no declared version is restored into.
- * @returns The variant to restore with, or {@link UnsupportedSnapshotVersionError} when the declared version is one no
- *   registered variant owns.
+ * @param variantWrittenBy Resolves the registered variant that a snapshot names as its writer, if it is registered.
+ *   Defaults to none, which is the routing every caller had before snapshots named their writer.
+ * @param activationOf The protocol version a registered variant starts answering for, as the wallet registered it. The
+ *   writer takes a snapshot only from that version upwards; below it the version routes, since the runtime cannot hand
+ *   over backwards. Defaults to the minimum version, which lets the writer take any snapshot, for compositions that
+ *   pass no writer resolver either.
+ * @returns The variant to restore with, or {@link UnsupportedSnapshotVersionError} when the writer is not registered and
+ *   the declared version is one no registered variant owns.
  */
-export const variantForSnapshot = (serialized, variantFor, headVariant) => Option.match(peekProtocolVersion(serialized), {
-    onNone: () => Either.right(headVariant),
-    onSome: (protocolVersion) => Either.fromOption(variantFor(protocolVersion), () => new UnsupportedSnapshotVersionError({
+export const variantForSnapshot = (serialized, variantFor, headVariant, variantWrittenBy = () => Option.none(), activationOf = () => ProtocolVersion.MinSupportedVersion) => SnapshotRouting.routeSnapshot({
+    activationOf,
+    envelope: SnapshotRouting.readEnvelope(serialized),
+    variantFor,
+    headVariant,
+    variantWrittenBy,
+    unsupported: (protocolVersion) => new UnsupportedSnapshotVersionError({
         message: `No registered variant reads shielded wallet snapshots of protocol version ${protocolVersion}.`,
         protocolVersion,
-    })),
+    }),
 });

package/dist/ShieldedWallet.js

@@ -10,12 +10,12 @@
 // 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, WalletSeed, WalletTransaction, } from '@midnightntwrk/wallet-sdk-abstractions';
+import { ProtocolVersion, WalletSeed, WalletTransaction, SnapshotFormat, } from '@midnightntwrk/wallet-sdk-abstractions';
 import { makeIndexerChainVersionProbe, } from '@midnightntwrk/wallet-sdk-capabilities/chainVersion';
 import { WalletBuilder } from '@midnightntwrk/wallet-sdk-runtime';
 import { StartMaterial, Variant, } from '@midnightntwrk/wallet-sdk-runtime/abstractions';
 import { EitherOps, HList } from '@midnightntwrk/wallet-sdk-utilities';
-import { Duration, Effect, Either, Option, Ref, pipe } from 'effect';
+import { Duration, Effect, Either, Match, Option, Ref, pipe } from 'effect';
 import * as rx from 'rxjs';
 import { variantForSnapshot } from './Restore.js';
 import { ShieldedWalletState, } from './ShieldedWalletAPI.js';
@@ -167,9 +167,26 @@ export function CustomForkingShieldedWallet(configuration, v1, v2) {
             wallet.#retainKeys({ v8: Option.some(keys.v8), v9: Option.some(keys.v9) });
             return wallet;
         }
+        /**
+         * The registered variant a snapshot names as its writer, if that variant is registered.
+         *
+         * @remarks
+         *   Snapshots name their writer by the ordinal in the variant's name, and each variant registers under its tag; this
+         *   is the one place the two are paired, so routing can send a snapshot home whatever version it carries.
+         * @param writer The writer a snapshot names.
+         * @returns That variant, or none when this composition does not register it.
+         */
+        static variantWrittenBy(writer) {
+            // Exhaustive on purpose: a writer added to `SNAPSHOT_WRITERS` must fail here at compile time, never fall
+            // through to a variant that did not write the snapshot.
+            const tag = Match.value(writer).pipe(Match.when(SnapshotFormat.V1_SNAPSHOT_WRITER, () => V1Tag), Match.when(SnapshotFormat.V2_SNAPSHOT_WRITER, () => V2Tag), Match.exhaustive);
+            return Option.fromNullable(ForkingShieldedWalletImplementation.allVariants().find((variant) => Variant.getVersionedVariantTag(variant) === tag));
+        }
         static tryRestore(serializedState) {
             const headVariant = HList.head(ForkingShieldedWalletImplementation.allVariants());
-            return variantForSnapshot(serializedState, (version) => ForkingShieldedWalletImplementation.variantFor(version), headVariant).pipe(
+            return variantForSnapshot(serializedState, (version) => ForkingShieldedWalletImplementation.variantFor(version), headVariant, (writer) => ForkingShieldedWalletImplementation.variantWrittenBy(writer), 
+            // Each variant's activation as registered here, so a writer never takes a snapshot from below its own range.
+            (variant) => variant.sinceVersion).pipe(
             // Stated with its result type because the resolved variant is either of the two, so its deserializer is
             // either of theirs: what comes back is a state of whichever one wrote the snapshot, which is what
             // `startAtVariant` takes.
@@ -182,7 +199,7 @@ export function CustomForkingShieldedWallet(configuration, v1, v2) {
             }));
         }
         static restore(serializedState) {
-            return Either.getOrThrow(ForkingShieldedWalletImplementation.tryRestore(serializedState));
+            return Either.getOrThrowWith(ForkingShieldedWalletImplementation.tryRestore(serializedState), (error) => error);
         }
         state;
         /**

package/dist/SingleVariantShieldedWallet.js

@@ -82,10 +82,14 @@ export function CustomShieldedWallet(configuration, builder) {
             // Routing reads a serialized envelope, which only a wallet keeping the default string serialization has. A
             // custom format is left with the behaviour it has always had.
             typeof serializedState === 'string'
-                ? variantForSnapshot(serializedState, (version) => CustomShieldedWalletImplementation.variantFor(version), headVariant)
+                ? variantForSnapshot(serializedState, (version) => CustomShieldedWalletImplementation.variantFor(version), headVariant, 
+                // A custom composition registers one variant, so there is no other writer to route to.
+                () => Option.none())
                 : Either.right(headVariant);
-            const variant = routed.pipe(Either.getOrThrow);
-            const deserialized = variant.variant.deserializeState(serializedState).pipe(Either.getOrThrow);
+            const variant = routed.pipe(Either.getOrThrowWith((error) => error));
+            const deserialized = variant.variant
+                .deserializeState(serializedState)
+                .pipe(Either.getOrThrowWith((error) => error));
             return CustomShieldedWalletImplementation.startAtVariant(CustomShieldedWalletImplementation, variant, deserialized);
         }
         state;

package/dist/SnapshotFormat.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The format version this build writes into a shielded snapshot. It versions the encoded shape of the snapshot and is
+ * not `protocolVersion`, which is the chain's hard-fork number and lives inside it.
+ *
+ * Snapshots written before this field existed carry the same fields under a different name for the same shape, so a
+ * missing `version` reads as this one and no upgrade runs. The field earns its keep on the day the shape does change:
+ * that shape becomes `v2` and a single v1-to-v2 step is written, rather than every reader having to guess.
+ *
+ * Declared here, with no ledger import, so that both variants share one constant and neither pulls the other's ledger
+ * into its module graph to read it.
+ */
+export declare const SNAPSHOT_FORMAT_VERSION = "v1";

package/dist/SnapshotFormat.js

@@ -0,0 +1,24 @@
+// 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 format version this build writes into a shielded snapshot. It versions the encoded shape of the snapshot and is
+ * not `protocolVersion`, which is the chain's hard-fork number and lives inside it.
+ *
+ * Snapshots written before this field existed carry the same fields under a different name for the same shape, so a
+ * missing `version` reads as this one and no upgrade runs. The field earns its keep on the day the shape does change:
+ * that shape becomes `v2` and a single v1-to-v2 step is written, rather than every reader having to guess.
+ *
+ * Declared here, with no ledger import, so that both variants share one constant and neither pulls the other's ledger
+ * into its module graph to read it.
+ */
+export const SNAPSHOT_FORMAT_VERSION = 'v1';

package/dist/v1/CoreWallet.d.ts

@@ -28,12 +28,31 @@ export type CoreWallet = Readonly<{
     progress: SyncProgress.SyncProgress;
     networkId: string;
     coinHashes: CoinHashesMap;
+    /**
+     * The transaction history that a 1.0.0 snapshot embedded, as the hex-encoded proven ledger transactions it was
+     * written with. Carried across a restore and written back out untouched, so upgrading does not destroy it; this SDK
+     * keeps history in its own storage and never reads or adds to this list.
+     *
+     * Absent for every snapshot written since the field was dropped from the schema, and absent means absent — it is not
+     * written back as an empty list, so those snapshots keep the bytes they had.
+     */
+    legacyTxHistory?: readonly string[];
+    /**
+     * The V2 variant's mid-crossing marker, when a snapshot this variant was handed happened to carry one.
+     *
+     * This variant has no such state: it never crosses into itself, so it neither sets this nor reads it. It is kept only
+     * so that reading such a snapshot and writing it back does not quietly discard the field — the same reason
+     * {@link legacyTxHistory} is kept, and the same failure it exists to prevent. `Restore.ts` routes a snapshot to the
+     * variant that owns its `protocolVersion`, so in a build registering both twins this is never populated; it is the
+     * reader's promise not to lose what it cannot represent, not a state this variant can be in.
+     */
+    foreignCoinHashesPending?: true;
 }>;
 export declare const CoreWallet: {
     init(localState: ledger.ZswapLocalState, secretKeys: ledger.ZswapSecretKeys, networkId: string): CoreWallet;
     empty(publicKeys: PublicKeys, networkId: string): CoreWallet;
     restore(localState: ledger.ZswapLocalState, secretKeys: ledger.ZswapSecretKeys, syncProgress: Omit<SyncProgress.SyncProgressData, "isConnected">, protocolVersion: bigint, networkId: string): CoreWallet;
-    restoreWithCoinHashes(publicKeys: PublicKeys, localState: ledger.ZswapLocalState, coinHashes: CoinHashesMap, syncProgress: SyncProgress.SyncProgressData, protocolVersion: bigint, networkId: string): Either.Either<CoreWallet, WalletError>;
+    restoreWithCoinHashes(publicKeys: PublicKeys, localState: ledger.ZswapLocalState, coinHashes: CoinHashesMap, syncProgress: SyncProgress.SyncProgressData, protocolVersion: bigint, networkId: string, legacyTxHistory?: readonly string[], foreignCoinHashesPending?: true): Either.Either<CoreWallet, WalletError>;
     initEmpty(keys: ledger.ZswapSecretKeys, networkId: string): CoreWallet;
     /**
      * Records an observed protocol version on the wallet, never going backwards.

package/dist/v1/CoreWallet.js

@@ -81,7 +81,7 @@ export const CoreWallet = {
             protocolVersion: ProtocolVersion.ProtocolVersion(protocolVersion),
         };
     },
-    restoreWithCoinHashes(publicKeys, localState, coinHashes, syncProgress, protocolVersion, networkId) {
+    restoreWithCoinHashes(publicKeys, localState, coinHashes, syncProgress, protocolVersion, networkId, legacyTxHistory, foreignCoinHashesPending) {
         return CoinHashesMap.assertValid(coinHashes, localState).pipe(Either.mapBoth({
             onLeft: (missingNonces) => new InvalidCoinHashesError({ message: 'Missing coin hashes for coins present in the state', missingNonces }),
             onRight: () => ({
@@ -91,6 +91,10 @@ export const CoreWallet = {
                 coinHashes,
                 progress: SyncProgress.createSyncProgress(syncProgress),
                 protocolVersion: ProtocolVersion.ProtocolVersion(protocolVersion),
+                // Spread conditionally: a snapshot that carried no embedded history must not gain a `legacyTxHistory` key,
+                // so that re-serializing it writes no `txHistory` field it did not already have.
+                ...(legacyTxHistory === undefined ? {} : { legacyTxHistory }),
+                ...(foreignCoinHashesPending === undefined ? {} : { foreignCoinHashesPending }),
             }),
         }));
     },

package/dist/v1/Serialization.d.ts

@@ -1,5 +1,5 @@
 import { Either } from 'effect';
-import { WalletError } from './WalletError.js';
+import { type WalletError } from './WalletError.js';
 import { CoreWallet } from './CoreWallet.js';
 import { type NetworkId } from '@midnightntwrk/wallet-sdk-abstractions';
 export type SerializationCapability<TWallet, TAux, TSerialized> = {
@@ -9,4 +9,5 @@ export type SerializationCapability<TWallet, TAux, TSerialized> = {
 export type DefaultSerializationConfiguration = {
     networkId: NetworkId.NetworkId;
 };
+export { SNAPSHOT_FORMAT_VERSION } from '../SnapshotFormat.js';
 export declare const makeDefaultV1SerializationCapability: () => SerializationCapability<CoreWallet, null, string>;

package/dist/v1/Serialization.js

@@ -11,9 +11,9 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 import { Effect, ParseResult, Either, pipe, Schema } from 'effect';
-import { WalletError } from './WalletError.js';
 import * as ledger from '@midnight-ntwrk/ledger-v8';
 import { CoreWallet } from './CoreWallet.js';
+import { SnapshotFormat } from '@midnightntwrk/wallet-sdk-abstractions';
 const StateSchema = Schema.declare((input) => input instanceof ledger.ZswapLocalState).annotations({
     identifier: 'ledger.ZswapLocalState',
 });
@@ -39,8 +39,14 @@ const StateFromUInt8Array = () => Schema.asSchema(Schema.transformOrFail(Uint8Ar
     }),
 }));
 const HexedState = () => pipe(Schema.Uint8ArrayFromHex, Schema.compose(StateFromUInt8Array()));
+// The format version lives beside the twins, not in either of them, so the V2 variant can read it without loading
+// ledger-v8. Re-exported here because the version is part of this variant's serialization surface.
+export { SNAPSHOT_FORMAT_VERSION } from '../SnapshotFormat.js';
+import { SNAPSHOT_FORMAT_VERSION } from '../SnapshotFormat.js';
 export const makeDefaultV1SerializationCapability = () => {
     const SnapshotSchema = Schema.Struct({
+        version: SnapshotFormat.versionField('shielded', SNAPSHOT_FORMAT_VERSION),
+        writtenBy: SnapshotFormat.writtenByField(),
         publicKeys: Schema.Struct({
             coinPublicKey: Schema.String,
             encryptionPublicKey: Schema.String,
@@ -53,27 +59,43 @@ export const makeDefaultV1SerializationCapability = () => {
             key: Schema.String,
             value: Schema.Struct({ nullifier: Schema.String, commitment: Schema.String }),
         }),
+        // 1.0.0 embedded the transaction history here, as hex-encoded proven ledger transactions. The field was dropped
+        // from this schema when history moved to its own storage, and because Effect Schema ignores keys it does not
+        // know, those snapshots restored without complaint and lost the history on the next write. Declaring it optional
+        // carries it back out untouched. Optional, not defaulted: a snapshot written without it keeps its exact bytes.
+        txHistory: Schema.optional(Schema.Array(Schema.String)),
+        // The V2 variant's mid-crossing marker. This variant is never in that state and never reads this, but the twins
+        // share one format version, so a V2-written snapshot is this schema's shape too — and a key this schema did not
+        // declare would be ignored on the way in and dropped on the way out, which is exactly how `txHistory` above was
+        // lost. Declared here so it is carried instead. See `CoreWallet.foreignCoinHashesPending`.
+        coinHashesPending: Schema.optional(Schema.Literal(true)),
     });
     return {
         serialize: (wallet) => {
             const buildSnapshot = (w) => ({
+                version: SNAPSHOT_FORMAT_VERSION,
+                writtenBy: SnapshotFormat.V1_SNAPSHOT_WRITER,
                 publicKeys: w.publicKeys,
                 state: w.state,
                 protocolVersion: w.protocolVersion,
                 networkId: w.networkId,
-                offset: w.progress?.appliedIndex,
                 coinHashes: w.coinHashes,
+                // Optional fields are spread in only when present, so the snapshot object never carries an `undefined` key:
+                // the bytes must not depend on `JSON.stringify` dropping one.
+                ...(w.progress?.appliedIndex !== undefined ? { offset: w.progress.appliedIndex } : {}),
+                ...(w.legacyTxHistory !== undefined ? { txHistory: w.legacyTxHistory } : {}),
+                ...(w.foreignCoinHashesPending !== undefined ? { coinHashesPending: w.foreignCoinHashesPending } : {}),
             });
             return pipe(wallet, buildSnapshot, Schema.encodeSync(SnapshotSchema), JSON.stringify);
         },
         deserialize: (aux, serialized) => {
-            return pipe(serialized, Schema.decodeUnknownEither(Schema.parseJson(SnapshotSchema)), Either.mapLeft((err) => WalletError.other(err)), Either.flatMap((snapshot) => CoreWallet.restoreWithCoinHashes(snapshot.publicKeys, snapshot.state, snapshot.coinHashes, {
+            return pipe(serialized, SnapshotFormat.readSnapshot({ surface: 'shielded', reads: [SNAPSHOT_FORMAT_VERSION], schema: SnapshotSchema }), Either.flatMap((snapshot) => CoreWallet.restoreWithCoinHashes(snapshot.publicKeys, snapshot.state, snapshot.coinHashes, {
                 appliedIndex: snapshot.offset ?? 0n,
                 highestRelevantWalletIndex: 0n,
                 highestIndex: 0n,
                 highestRelevantIndex: 0n,
                 isConnected: false,
-            }, snapshot.protocolVersion, snapshot.networkId)));
+            }, snapshot.protocolVersion, snapshot.networkId, snapshot.txHistory, snapshot.coinHashesPending)));
         },
     };
 };

package/dist/v1/TransactionHistory.d.ts

@@ -1,7 +1,7 @@
 import { TransactionHistoryStorage } from '@midnightntwrk/wallet-sdk-abstractions';
 import type * as ledger from '@midnight-ntwrk/ledger-v8';
 import { Duration, Effect, Schema } from 'effect';
-import { TransactionHistoryError } from './WalletError.js';
+import { BlocklessFinalizedEntryError, TransactionHistoryError } from './WalletError.js';
 export declare const QualifiedShieldedCoinInfoSchema: Schema.Struct<{
     type: typeof Schema.String;
     nonce: typeof Schema.String;
@@ -39,11 +39,11 @@ export declare const ShieldedTransactionHistoryEntrySchema: Schema.Struct<Readon
         submittedAt: typeof Schema.Date;
     }>, Schema.Struct<{
         status: Schema.Literal<["finalized"]>;
-        finalizedBlock: Schema.Struct<{
+        finalizedBlock: Schema.optional<Schema.Struct<{
             hash: typeof Schema.String;
             height: typeof Schema.Number;
             timestamp: typeof Schema.Date;
-        }>;
+        }>>;
     }>, Schema.Struct<{
         status: Schema.Literal<["rejected"]>;
         rejectedAt: typeof Schema.Date;
@@ -92,7 +92,7 @@ export type TransactionDetails = {
 };
 export type TransactionHistoryService = {
     put(changes: ledger.ZswapStateChanges, metadata: TransactionDetails, protocolVersion: number): Effect.Effect<void, TransactionHistoryError>;
-    getTransactionDetails(hash: TransactionHistoryStorage.TransactionHash): Effect.Effect<TransactionDetails, TransactionHistoryError>;
+    getTransactionDetails(hash: TransactionHistoryStorage.TransactionHash): Effect.Effect<TransactionDetails, TransactionHistoryError | BlocklessFinalizedEntryError>;
 };
 export declare const mergeShieldedSections: (existing: ShieldedSection, incoming: ShieldedSection) => ShieldedSection;
 export declare const makeDefaultTransactionHistoryService: (config: DefaultTransactionHistoryConfiguration, _getContext: () => unknown) => TransactionHistoryService;

package/dist/v1/TransactionHistory.js

@@ -14,7 +14,7 @@ import { TransactionHistoryStorage } from '@midnightntwrk/wallet-sdk-abstraction
 import { Duration, Array as EArray, Effect, Schedule, Schema } from 'effect';
 import { TransactionHistoryDetail } from '@midnightntwrk/wallet-sdk-indexer-client';
 import { HttpQueryClient } from '@midnightntwrk/wallet-sdk-indexer-client/effect';
-import { TransactionHistoryError } from './WalletError.js';
+import { BlocklessFinalizedEntryError, TransactionHistoryError } from './WalletError.js';
 export const QualifiedShieldedCoinInfoSchema = Schema.Struct({
     type: Schema.String,
     nonce: Schema.String,
@@ -116,17 +116,26 @@ export const makeSimulatorTransactionHistoryService = (config, _getContext) => {
         getTransactionDetails: (hash) => Effect.tryPromise({
             try: () => txHistoryStorage.get(hash),
             catch: (e) => new TransactionHistoryError({ message: `Failed to get transaction details for ${hash}`, cause: e }),
-        }).pipe(Effect.flatMap((entry) => isFinalized(entry)
-            ? Effect.succeed({
-                hash: entry.hash,
-                block: {
-                    hash: entry.lifecycle.finalizedBlock.hash,
-                    height: entry.lifecycle.finalizedBlock.height,
-                    timestamp: entry.lifecycle.finalizedBlock.timestamp.getTime(),
-                },
-                status: entry.status ?? 'SUCCESS',
-                identifiers: entry.identifiers,
-            })
-            : Effect.fail(new TransactionHistoryError({ message: `No transaction found in storage for hash: ${hash}` })))),
+        }).pipe(
+        // Two distinct failures, reported distinctly. Storage may never have heard of the transaction; or it holds a
+        // finalized entry restored from a history written before the lifecycle field existed, which records no block.
+        // This service backs the simulator, where storage is the only source, so neither case can be repaired here.
+        Effect.flatMap((entry) => !isFinalized(entry)
+            ? Effect.fail(new TransactionHistoryError({ message: `No transaction found in storage for hash: ${hash}` }))
+            : entry.lifecycle.finalizedBlock === undefined
+                ? Effect.fail(new BlocklessFinalizedEntryError({
+                    message: `Transaction ${hash} is finalized but its history entry records no block (restored from a pre-lifecycle history)`,
+                    hash,
+                }))
+                : Effect.succeed({
+                    hash: entry.hash,
+                    block: {
+                        hash: entry.lifecycle.finalizedBlock.hash,
+                        height: entry.lifecycle.finalizedBlock.height,
+                        timestamp: entry.lifecycle.finalizedBlock.timestamp.getTime(),
+                    },
+                    status: entry.status ?? 'SUCCESS',
+                    identifiers: entry.identifiers,
+                }))),
     };
 };

package/dist/v1/V1Builder.js

@@ -203,6 +203,9 @@ export class V1Builder {
                 message: 'Failed to migrate shielded wallet state into this variant',
                 cause: error,
             }))),
+            // The version the state was left at: where the chain was when a snapshot was written, or what the chain answered
+            // when a fresh state was stamped from it. The runtime starts at this version rather than the variant's lower bound.
+            protocolVersionOf: (state) => state.protocolVersion,
             deserializeState: (serialized) => {
                 return v1Context.serializationCapability.deserialize(null, serialized);
             },

package/dist/v1/WalletError.d.ts

@@ -1,10 +1,11 @@
+import { type SnapshotFormat } from '@midnightntwrk/wallet-sdk-abstractions';
 import type * as ledger from '@midnight-ntwrk/ledger-v8';
 import { type LedgerOps } from '@midnightntwrk/wallet-sdk-utilities';
 export declare const WalletError: {
     other(err: unknown): WalletError;
     submission(err: unknown): WalletError;
 };
-export type WalletError = OtherWalletError | InsufficientFundsError | SubmissionError | AddressError | SyncWalletError | InvalidCoinHashesError | TransactingError | OutOfOrderSyncUpdateError | LedgerOps.LedgerError;
+export type WalletError = SnapshotFormat.SnapshotRestoreError | OtherWalletError | InsufficientFundsError | SubmissionError | AddressError | SyncWalletError | InvalidCoinHashesError | TransactingError | OutOfOrderSyncUpdateError | LedgerOps.LedgerError;
 declare const OtherWalletError_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: "Wallet.Other";
 } & Readonly<A>;
@@ -71,6 +72,28 @@ export declare class TransactionHistoryError extends TransactionHistoryError_bas
     cause?: unknown;
 }> {
 }
+declare const BlocklessFinalizedEntryError_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: "Wallet.BlocklessFinalizedEntry";
+} & Readonly<A>;
+/**
+ * A finalized history entry that records no block, met where a block is needed.
+ *
+ * @remarks
+ *   Only an entry restored from a history written before the lifecycle field existed looks like this: it is known to have
+ *   been finalized, but the block it landed in was never recorded, and none is invented. It is its own error rather
+ *   than a message on {@link TransactionHistoryError} so that a caller which can fetch the block by hash matches on the
+ *   tag.
+ * @example
+ *   ```ts
+ *   if (error._tag === 'Wallet.BlocklessFinalizedEntry') fetchBlockFor(error.hash);
+ *   ```;
+ */
+export declare class BlocklessFinalizedEntryError extends BlocklessFinalizedEntryError_base<{
+    readonly message: string;
+    /** The transaction whose history entry records no block. */
+    readonly hash: string;
+}> {
+}
 declare const OutOfOrderSyncUpdateError_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: "Wallet.OutOfOrderSyncUpdate";
 } & Readonly<A>;

package/dist/v1/WalletError.js

@@ -51,6 +51,21 @@ export class TransactingError extends Data.TaggedError('Wallet.Transacting') {
 }
 export class TransactionHistoryError extends Data.TaggedError('Wallet.TransactionHistory') {
 }
+/**
+ * A finalized history entry that records no block, met where a block is needed.
+ *
+ * @remarks
+ *   Only an entry restored from a history written before the lifecycle field existed looks like this: it is known to have
+ *   been finalized, but the block it landed in was never recorded, and none is invented. It is its own error rather
+ *   than a message on {@link TransactionHistoryError} so that a caller which can fetch the block by hash matches on the
+ *   tag.
+ * @example
+ *   ```ts
+ *   if (error._tag === 'Wallet.BlocklessFinalizedEntry') fetchBlockFor(error.hash);
+ *   ```;
+ */
+export class BlocklessFinalizedEntryError extends Data.TaggedError('Wallet.BlocklessFinalizedEntry') {
+}
 /**
  * A batch of zswap ledger events was not in ascending id order: an event arrived at or below the one before it, or at
  * or below the applied cursor.

package/dist/v2/CoreWallet.d.ts

@@ -43,12 +43,21 @@ export type CoreWallet = Readonly<{
      *   inhabitant, so "pending" and "absent" are the only two states.
      */
     coinHashesPending?: true;
+    /**
+     * The transaction history that a 1.0.0 snapshot embedded, as the hex-encoded proven ledger transactions it was
+     * written with. Carried across a restore and across the ledger-version boundary, and written back out untouched, so
+     * upgrading does not destroy it; this SDK keeps history in its own storage and never reads or adds to this list.
+     *
+     * Absent for every snapshot written since the field was dropped from the schema, and absent means absent — it is not
+     * written back as an empty list, so those snapshots keep the bytes they had.
+     */
+    legacyTxHistory?: readonly string[];
 }>;
 export declare const CoreWallet: {
     init(localState: ledger.ZswapLocalState, secretKeys: ledger.ZswapSecretKeys, networkId: string): CoreWallet;
     empty(publicKeys: PublicKeys, networkId: string): CoreWallet;
     restore(localState: ledger.ZswapLocalState, secretKeys: ledger.ZswapSecretKeys, syncProgress: Omit<SyncProgress.SyncProgressData, "isConnected">, protocolVersion: bigint, networkId: string): CoreWallet;
-    restoreWithCoinHashes(publicKeys: PublicKeys, localState: ledger.ZswapLocalState, coinHashes: CoinHashesMap, syncProgress: SyncProgress.SyncProgressData, protocolVersion: bigint, networkId: string): Either.Either<CoreWallet, WalletError>;
+    restoreWithCoinHashes(publicKeys: PublicKeys, localState: ledger.ZswapLocalState, coinHashes: CoinHashesMap, syncProgress: SyncProgress.SyncProgressData, protocolVersion: bigint, networkId: string, legacyTxHistory?: readonly string[]): Either.Either<CoreWallet, WalletError>;
     /**
      * Restores a wallet whose coin hashes were never computed — a snapshot taken mid-crossing.
      *
@@ -64,9 +73,10 @@ export declare const CoreWallet: {
      * @param syncProgress Where the snapshot's reading had got to.
      * @param protocolVersion The version the snapshot was written under.
      * @param networkId The network the snapshot claims.
+     * @param legacyTxHistory The transaction history the snapshot embedded, when it carried one.
      * @returns A wallet holding that state, its coin hashes still pending.
      */
-    restoreWithPendingCoinHashes(publicKeys: PublicKeys, localState: ledger.ZswapLocalState, syncProgress: SyncProgress.SyncProgressData, protocolVersion: bigint, networkId: string): CoreWallet;
+    restoreWithPendingCoinHashes(publicKeys: PublicKeys, localState: ledger.ZswapLocalState, syncProgress: SyncProgress.SyncProgressData, protocolVersion: bigint, networkId: string, legacyTxHistory?: readonly string[]): CoreWallet;
     initEmpty(keys: ledger.ZswapSecretKeys, networkId: string): CoreWallet;
     /**
      * Records an observed protocol version on the wallet, never going backwards.
@@ -105,7 +115,9 @@ export declare const CoreWallet: {
      *   the first place in this variant where keys and state meet. The same step releases the spends the state crossed
      *   with: those transactions belong to the ledger version the chain has left behind and can never be included, so
      *   nothing else would ever free the coins they reserved.
-     * @param previous The identity and position read off the previous ledger version's wallet, and its decoded state.
+     * @param previous The identity and position read off the previous ledger version's wallet, and its decoded state. Its
+     *   embedded transaction history, when it holds one, crosses too: the far side writes it back out and nothing there
+     *   could rebuild it.
      * @returns A wallet of this ledger version holding what its predecessor held, positioned at the fork.
      */
     fromPreviousVersion(previous: {
@@ -114,6 +126,7 @@ export declare const CoreWallet: {
         readonly networkId: string;
         readonly protocolVersion: bigint;
         readonly progress: SyncProgress.SyncProgressData;
+        readonly legacyTxHistory?: readonly string[];
     }): CoreWallet;
     /**
      * Finishes a crossing at the first sync update: the reservations released, then the coin hashes computed.

package/dist/v2/CoreWallet.js

@@ -102,7 +102,7 @@ export const CoreWallet = {
             protocolVersion: ProtocolVersion.ProtocolVersion(protocolVersion),
         };
     },
-    restoreWithCoinHashes(publicKeys, localState, coinHashes, syncProgress, protocolVersion, networkId) {
+    restoreWithCoinHashes(publicKeys, localState, coinHashes, syncProgress, protocolVersion, networkId, legacyTxHistory) {
         return CoinHashesMap.assertValid(coinHashes, localState).pipe(Either.mapBoth({
             onLeft: (missingNonces) => new InvalidCoinHashesError({ message: 'Missing coin hashes for coins present in the state', missingNonces }),
             onRight: () => ({
@@ -112,6 +112,9 @@ export const CoreWallet = {
                 coinHashes,
                 progress: SyncProgress.createSyncProgress(syncProgress),
                 protocolVersion: ProtocolVersion.ProtocolVersion(protocolVersion),
+                // Spread conditionally: a snapshot that carried no embedded history must not gain a `legacyTxHistory` key,
+                // so that re-serializing it writes no `txHistory` field it did not already have.
+                ...(legacyTxHistory === undefined ? {} : { legacyTxHistory }),
             }),
         }));
     },
@@ -130,9 +133,10 @@ export const CoreWallet = {
      * @param syncProgress Where the snapshot's reading had got to.
      * @param protocolVersion The version the snapshot was written under.
      * @param networkId The network the snapshot claims.
+     * @param legacyTxHistory The transaction history the snapshot embedded, when it carried one.
      * @returns A wallet holding that state, its coin hashes still pending.
      */
-    restoreWithPendingCoinHashes(publicKeys, localState, syncProgress, protocolVersion, networkId) {
+    restoreWithPendingCoinHashes(publicKeys, localState, syncProgress, protocolVersion, networkId, legacyTxHistory) {
         return {
             state: localState,
             publicKeys,
@@ -141,6 +145,7 @@ export const CoreWallet = {
             coinHashesPending: true,
             progress: SyncProgress.createSyncProgress(syncProgress),
             protocolVersion: ProtocolVersion.ProtocolVersion(protocolVersion),
+            ...(legacyTxHistory === undefined ? {} : { legacyTxHistory }),
         };
     },
     initEmpty(keys, networkId) {
@@ -185,7 +190,9 @@ export const CoreWallet = {
      *   the first place in this variant where keys and state meet. The same step releases the spends the state crossed
      *   with: those transactions belong to the ledger version the chain has left behind and can never be included, so
      *   nothing else would ever free the coins they reserved.
-     * @param previous The identity and position read off the previous ledger version's wallet, and its decoded state.
+     * @param previous The identity and position read off the previous ledger version's wallet, and its decoded state. Its
+     *   embedded transaction history, when it holds one, crosses too: the far side writes it back out and nothing there
+     *   could rebuild it.
      * @returns A wallet of this ledger version holding what its predecessor held, positioned at the fork.
      */
     fromPreviousVersion(previous) {
@@ -197,6 +204,7 @@ export const CoreWallet = {
             coinHashesPending: true,
             progress: SyncProgress.createSyncProgress({ ...previous.progress, isConnected: false }),
             protocolVersion: ProtocolVersion.ProtocolVersion(previous.protocolVersion),
+            ...(previous.legacyTxHistory === undefined ? {} : { legacyTxHistory: previous.legacyTxHistory }),
         };
     },
     /**
@@ -238,16 +246,12 @@ export const CoreWallet = {
      * @returns `wallet` unchanged if its hashes were never pending, otherwise a copy holding them.
      */
     resolveCoinHashes(wallet, secretKeys) {
-        return wallet.coinHashesPending === undefined
-            ? wallet
-            : {
-                state: wallet.state,
-                publicKeys: wallet.publicKeys,
-                networkId: wallet.networkId,
-                coinHashes: CoinHashesMap.init(secretKeys, CoinHashesMap.pickAllCoins(wallet.state)),
-                progress: wallet.progress,
-                protocolVersion: wallet.protocolVersion,
-            };
+        if (wallet.coinHashesPending === undefined)
+            return wallet;
+        // Rebuilt by spread rather than from a list of fields, so nothing the wallet carried can be left behind: only the
+        // marker is shed, and the embedded transaction history of a 1.0.0 snapshot survives the first update after crossing.
+        const { coinHashesPending: _pending, ...carried } = wallet;
+        return { ...carried, coinHashes: CoinHashesMap.init(secretKeys, CoinHashesMap.pickAllCoins(wallet.state)) };
     },
     applyCollapsedUpdate(wallet, collapsed) {
         const newState = wallet.state.applyCollapsedUpdate(collapsed);

package/dist/v2/Migration.d.ts

@@ -72,6 +72,8 @@ export type PreviousLedgerWallet = Readonly<{
     state: Readonly<{
         serialize: () => Uint8Array;
     }>;
+    /** The transaction history a 1.0.0 snapshot embedded, when the previous wallet was restored from one. */
+    legacyTxHistory?: readonly string[];
 }>;
 /**
  * The migration across a ledger-version boundary: the local state crosses as bytes, identity and position beside it.

package/dist/v2/Migration.js

@@ -92,5 +92,6 @@ export const makeCrossLedgerMigration = () => ({
         networkId: previousState.networkId,
         protocolVersion: previousState.protocolVersion,
         progress: previousState.progress,
+        ...(previousState.legacyTxHistory === undefined ? {} : { legacyTxHistory: previousState.legacyTxHistory }),
     })), EitherOps.toEffect),
 });

package/dist/v2/Serialization.d.ts

@@ -1,6 +1,7 @@
 import { Either } from 'effect';
-import { WalletError } from './WalletError.js';
+import { type WalletError } from './WalletError.js';
 import { CoreWallet } from './CoreWallet.js';
+export { SNAPSHOT_FORMAT_VERSION } from '../SnapshotFormat.js';
 import { type NetworkId } from '@midnightntwrk/wallet-sdk-abstractions';
 export type SerializationCapability<TWallet, TAux, TSerialized> = {
     serialize(wallet: TWallet): TSerialized;

package/dist/v2/Serialization.js

@@ -11,9 +11,12 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 import { Effect, ParseResult, Either, pipe, Schema } from 'effect';
-import { WalletError } from './WalletError.js';
 import * as ledger from '@midnightntwrk/ledger-v9';
 import { CoreWallet } from './CoreWallet.js';
+import { SNAPSHOT_FORMAT_VERSION } from '../SnapshotFormat.js';
+// Re-exported because the version this variant writes is part of its serialization surface, as on the V1 twin.
+export { SNAPSHOT_FORMAT_VERSION } from '../SnapshotFormat.js';
+import { SnapshotFormat } from '@midnightntwrk/wallet-sdk-abstractions';
 const StateSchema = Schema.declare((input) => input instanceof ledger.ZswapLocalState).annotations({
     identifier: 'ledger.ZswapLocalState',
 });
@@ -41,6 +44,13 @@ const StateFromUInt8Array = () => Schema.asSchema(Schema.transformOrFail(Uint8Ar
 const HexedState = () => pipe(Schema.Uint8ArrayFromHex, Schema.compose(StateFromUInt8Array()));
 export const makeDefaultV2SerializationCapability = () => {
     const SnapshotSchema = Schema.Struct({
+        // The version names the snapshot's shape, not the variant that wrote it, and the constant lives in
+        // `../SnapshotFormat.ts` so the twins cannot drift apart. Both variants write this shape — the V2 variant adds
+        // only optional fields to it, which is not a new version. A V1 reader never meets a V2 snapshot anyway:
+        // `../Restore.ts` routes each snapshot to the variant it names as its writer, and by the variant that owns its
+        // `protocolVersion` when it names none.
+        version: SnapshotFormat.versionField('shielded', SNAPSHOT_FORMAT_VERSION),
+        writtenBy: SnapshotFormat.writtenByField(),
         publicKeys: Schema.Struct({
             coinPublicKey: Schema.String,
             encryptionPublicKey: Schema.String,
@@ -58,22 +68,30 @@ export const makeDefaultV2SerializationCapability = () => {
         // `CoreWallet.coinHashesPending`). Optional twice over — a wallet that is not mid-crossing has nothing to declare,
         // and snapshots written before the field existed must keep decoding unchanged.
         coinHashesPending: Schema.optional(Schema.Literal(true)),
+        // The transaction history a 1.0.0 snapshot embedded. Read back and written out untouched, never added to; absent
+        // for every snapshot written since, and kept absent for them. See `CoreWallet.legacyTxHistory`.
+        txHistory: Schema.optional(Schema.Array(Schema.String)),
     });
     return {
         serialize: (wallet) => {
             const buildSnapshot = (w) => ({
+                version: SNAPSHOT_FORMAT_VERSION,
+                writtenBy: SnapshotFormat.V2_SNAPSHOT_WRITER,
                 publicKeys: w.publicKeys,
                 state: w.state,
                 protocolVersion: w.protocolVersion,
                 networkId: w.networkId,
-                offset: w.progress?.appliedIndex,
                 coinHashes: w.coinHashes,
+                // Optional fields are spread in only when present, so the snapshot object never carries an `undefined` key:
+                // the bytes must not depend on `JSON.stringify` dropping one.
+                ...(w.progress?.appliedIndex !== undefined ? { offset: w.progress.appliedIndex } : {}),
+                ...(w.legacyTxHistory !== undefined ? { txHistory: w.legacyTxHistory } : {}),
                 ...(w.coinHashesPending !== undefined ? { coinHashesPending: w.coinHashesPending } : {}),
             });
             return pipe(wallet, buildSnapshot, Schema.encodeSync(SnapshotSchema), JSON.stringify);
         },
         deserialize: (aux, serialized) => {
-            return pipe(serialized, Schema.decodeUnknownEither(Schema.parseJson(SnapshotSchema)), Either.mapLeft((err) => WalletError.other(err)), Either.flatMap((snapshot) => {
+            return pipe(serialized, SnapshotFormat.readSnapshot({ surface: 'shielded', reads: [SNAPSHOT_FORMAT_VERSION], schema: SnapshotSchema }), Either.flatMap((snapshot) => {
                 const progress = {
                     appliedIndex: snapshot.offset ?? 0n,
                     highestRelevantWalletIndex: 0n,
@@ -85,8 +103,8 @@ export const makeDefaultV2SerializationCapability = () => {
                 // its state is full and its hash map is empty by construction, because the migration that wrote it had no
                 // secret keys. Every other snapshot goes on being checked against its own state.
                 return snapshot.coinHashesPending === true
-                    ? Either.right(CoreWallet.restoreWithPendingCoinHashes(snapshot.publicKeys, snapshot.state, progress, snapshot.protocolVersion, snapshot.networkId))
-                    : CoreWallet.restoreWithCoinHashes(snapshot.publicKeys, snapshot.state, snapshot.coinHashes, progress, snapshot.protocolVersion, snapshot.networkId);
+                    ? Either.right(CoreWallet.restoreWithPendingCoinHashes(snapshot.publicKeys, snapshot.state, progress, snapshot.protocolVersion, snapshot.networkId, snapshot.txHistory))
+                    : CoreWallet.restoreWithCoinHashes(snapshot.publicKeys, snapshot.state, snapshot.coinHashes, progress, snapshot.protocolVersion, snapshot.networkId, snapshot.txHistory);
             }));
         },
     };

package/dist/v2/TransactionHistory.d.ts

@@ -1,7 +1,7 @@
 import { TransactionHistoryStorage } from '@midnightntwrk/wallet-sdk-abstractions';
 import type * as ledger from '@midnightntwrk/ledger-v9';
 import { Duration, Effect, Schema } from 'effect';
-import { TransactionHistoryError } from './WalletError.js';
+import { BlocklessFinalizedEntryError, TransactionHistoryError } from './WalletError.js';
 export declare const QualifiedShieldedCoinInfoSchema: Schema.Struct<{
     type: typeof Schema.String;
     nonce: typeof Schema.String;
@@ -39,11 +39,11 @@ export declare const ShieldedTransactionHistoryEntrySchema: Schema.Struct<Readon
         submittedAt: typeof Schema.Date;
     }>, Schema.Struct<{
         status: Schema.Literal<["finalized"]>;
-        finalizedBlock: Schema.Struct<{
+        finalizedBlock: Schema.optional<Schema.Struct<{
             hash: typeof Schema.String;
             height: typeof Schema.Number;
             timestamp: typeof Schema.Date;
-        }>;
+        }>>;
     }>, Schema.Struct<{
         status: Schema.Literal<["rejected"]>;
         rejectedAt: typeof Schema.Date;
@@ -92,7 +92,7 @@ export type TransactionDetails = {
 };
 export type TransactionHistoryService = {
     put(changes: ledger.ZswapStateChanges, metadata: TransactionDetails, protocolVersion: number): Effect.Effect<void, TransactionHistoryError>;
-    getTransactionDetails(hash: TransactionHistoryStorage.TransactionHash): Effect.Effect<TransactionDetails, TransactionHistoryError>;
+    getTransactionDetails(hash: TransactionHistoryStorage.TransactionHash): Effect.Effect<TransactionDetails, TransactionHistoryError | BlocklessFinalizedEntryError>;
 };
 export declare const mergeShieldedSections: (existing: ShieldedSection, incoming: ShieldedSection) => ShieldedSection;
 export declare const makeDefaultTransactionHistoryService: (config: DefaultTransactionHistoryConfiguration, _getContext: () => unknown) => TransactionHistoryService;

package/dist/v2/TransactionHistory.js

@@ -14,7 +14,7 @@ import { TransactionHistoryStorage } from '@midnightntwrk/wallet-sdk-abstraction
 import { Duration, Array as EArray, Effect, Schedule, Schema } from 'effect';
 import { TransactionHistoryDetail } from '@midnightntwrk/wallet-sdk-indexer-client';
 import { HttpQueryClient } from '@midnightntwrk/wallet-sdk-indexer-client/effect';
-import { TransactionHistoryError } from './WalletError.js';
+import { BlocklessFinalizedEntryError, TransactionHistoryError } from './WalletError.js';
 export const QualifiedShieldedCoinInfoSchema = Schema.Struct({
     type: Schema.String,
     nonce: Schema.String,
@@ -116,17 +116,26 @@ export const makeSimulatorTransactionHistoryService = (config, _getContext) => {
         getTransactionDetails: (hash) => Effect.tryPromise({
             try: () => txHistoryStorage.get(hash),
             catch: (e) => new TransactionHistoryError({ message: `Failed to get transaction details for ${hash}`, cause: e }),
-        }).pipe(Effect.flatMap((entry) => isFinalized(entry)
-            ? Effect.succeed({
-                hash: entry.hash,
-                block: {
-                    hash: entry.lifecycle.finalizedBlock.hash,
-                    height: entry.lifecycle.finalizedBlock.height,
-                    timestamp: entry.lifecycle.finalizedBlock.timestamp.getTime(),
-                },
-                status: entry.status ?? 'SUCCESS',
-                identifiers: entry.identifiers,
-            })
-            : Effect.fail(new TransactionHistoryError({ message: `No transaction found in storage for hash: ${hash}` })))),
+        }).pipe(
+        // Two distinct failures, reported distinctly. Storage may never have heard of the transaction; or it holds a
+        // finalized entry restored from a history written before the lifecycle field existed, which records no block.
+        // This service backs the simulator, where storage is the only source, so neither case can be repaired here.
+        Effect.flatMap((entry) => !isFinalized(entry)
+            ? Effect.fail(new TransactionHistoryError({ message: `No transaction found in storage for hash: ${hash}` }))
+            : entry.lifecycle.finalizedBlock === undefined
+                ? Effect.fail(new BlocklessFinalizedEntryError({
+                    message: `Transaction ${hash} is finalized but its history entry records no block (restored from a pre-lifecycle history)`,
+                    hash,
+                }))
+                : Effect.succeed({
+                    hash: entry.hash,
+                    block: {
+                        hash: entry.lifecycle.finalizedBlock.hash,
+                        height: entry.lifecycle.finalizedBlock.height,
+                        timestamp: entry.lifecycle.finalizedBlock.timestamp.getTime(),
+                    },
+                    status: entry.status ?? 'SUCCESS',
+                    identifiers: entry.identifiers,
+                }))),
     };
 };

package/dist/v2/V2Builder.js

@@ -203,6 +203,9 @@ export class V2Builder {
                 message: 'Failed to migrate shielded wallet state into this variant',
                 cause: error,
             }))),
+            // The version the state was left at: where the chain was when a snapshot was written, or what the chain answered
+            // when a fresh state was stamped from it. The runtime starts at this version rather than the variant's lower bound.
+            protocolVersionOf: (state) => state.protocolVersion,
             deserializeState: (serialized) => {
                 return v2Context.serializationCapability.deserialize(null, serialized);
             },

package/dist/v2/WalletError.d.ts

@@ -1,10 +1,11 @@
+import { type SnapshotFormat } from '@midnightntwrk/wallet-sdk-abstractions';
 import type * as ledger from '@midnightntwrk/ledger-v9';
 import { type LedgerOps } from '@midnightntwrk/wallet-sdk-utilities';
 export declare const WalletError: {
     other(err: unknown): WalletError;
     submission(err: unknown): WalletError;
 };
-export type WalletError = OtherWalletError | InsufficientFundsError | SubmissionError | AddressError | SyncWalletError | InvalidCoinHashesError | TransactingError | OutOfOrderSyncUpdateError | LedgerOps.LedgerError;
+export type WalletError = SnapshotFormat.SnapshotRestoreError | OtherWalletError | InsufficientFundsError | SubmissionError | AddressError | SyncWalletError | InvalidCoinHashesError | TransactingError | OutOfOrderSyncUpdateError | LedgerOps.LedgerError;
 declare const OtherWalletError_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: "Wallet.Other";
 } & Readonly<A>;
@@ -71,6 +72,28 @@ export declare class TransactionHistoryError extends TransactionHistoryError_bas
     cause?: unknown;
 }> {
 }
+declare const BlocklessFinalizedEntryError_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: "Wallet.BlocklessFinalizedEntry";
+} & Readonly<A>;
+/**
+ * A finalized history entry that records no block, met where a block is needed.
+ *
+ * @remarks
+ *   Only an entry restored from a history written before the lifecycle field existed looks like this: it is known to have
+ *   been finalized, but the block it landed in was never recorded, and none is invented. It is its own error rather
+ *   than a message on {@link TransactionHistoryError} so that a caller which can fetch the block by hash matches on the
+ *   tag.
+ * @example
+ *   ```ts
+ *   if (error._tag === 'Wallet.BlocklessFinalizedEntry') fetchBlockFor(error.hash);
+ *   ```;
+ */
+export declare class BlocklessFinalizedEntryError extends BlocklessFinalizedEntryError_base<{
+    readonly message: string;
+    /** The transaction whose history entry records no block. */
+    readonly hash: string;
+}> {
+}
 declare const OutOfOrderSyncUpdateError_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: "Wallet.OutOfOrderSyncUpdate";
 } & Readonly<A>;

package/dist/v2/WalletError.js

@@ -51,6 +51,21 @@ export class TransactingError extends Data.TaggedError('Wallet.Transacting') {
 }
 export class TransactionHistoryError extends Data.TaggedError('Wallet.TransactionHistory') {
 }
+/**
+ * A finalized history entry that records no block, met where a block is needed.
+ *
+ * @remarks
+ *   Only an entry restored from a history written before the lifecycle field existed looks like this: it is known to have
+ *   been finalized, but the block it landed in was never recorded, and none is invented. It is its own error rather
+ *   than a message on {@link TransactionHistoryError} so that a caller which can fetch the block by hash matches on the
+ *   tag.
+ * @example
+ *   ```ts
+ *   if (error._tag === 'Wallet.BlocklessFinalizedEntry') fetchBlockFor(error.hash);
+ *   ```;
+ */
+export class BlocklessFinalizedEntryError extends Data.TaggedError('Wallet.BlocklessFinalizedEntry') {
+}
 /**
  * A batch of zswap ledger events was not in ascending id order: an event arrived at or below the one before it, or at
  * or below the applied cursor.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midnightntwrk/wallet-sdk-shielded",
-  "version": "4.0.0-rc.0",
+  "version": "4.0.0-rc.1",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -36,11 +36,11 @@
   "dependencies": {
     "@midnight-ntwrk/ledger-v8": "^8.1.0",
     "@midnightntwrk/ledger-v9": "1.0.0-rc.5",
-    "@midnightntwrk/wallet-sdk-abstractions": "3.0.0-rc.0",
+    "@midnightntwrk/wallet-sdk-abstractions": "3.0.0-rc.1",
     "@midnightntwrk/wallet-sdk-address-format": "4.0.0-rc.0",
-    "@midnightntwrk/wallet-sdk-capabilities": "4.0.0-rc.0",
-    "@midnightntwrk/wallet-sdk-indexer-client": "2.0.0-rc.0",
-    "@midnightntwrk/wallet-sdk-runtime": "1.1.0-rc.0",
+    "@midnightntwrk/wallet-sdk-capabilities": "4.0.0-rc.1",
+    "@midnightntwrk/wallet-sdk-indexer-client": "2.0.0-rc.1",
+    "@midnightntwrk/wallet-sdk-runtime": "2.0.0-rc.1",
     "@midnightntwrk/wallet-sdk-utilities": "1.2.2-rc.0",
     "effect": "^3.19.19",
     "rxjs": "^7.8.2"