@midnightntwrk/wallet-sdk-shielded 4.0.0-beta.2 → 4.0.0-beta.3

package/dist/v2/CoreWallet.js

@@ -0,0 +1,305 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// Licensed under the Apache License, Version 2.0 (the "License");
+// You may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import * as ledger from '@midnightntwrk/ledger-v9';
+import { ProtocolVersion, SyncProgress } from '@midnightntwrk/wallet-sdk-abstractions';
+import { LedgerOps } from '@midnightntwrk/wallet-sdk-utilities';
+import { Either, Iterable, pipe, Record, Array as Arr } from 'effect';
+import { InvalidCoinHashesError } from './WalletError.js';
+export const PublicKeys = {
+    fromSecretKeys: (secretKeys) => {
+        return {
+            coinPublicKey: secretKeys.coinPublicKey,
+            encryptionPublicKey: secretKeys.encryptionPublicKey,
+        };
+    },
+};
+export const CoinHashesMap = {
+    empty: {},
+    pickAllCoins(state) {
+        return [...state.coins, ...state.pendingOutputs.values().map(([coin]) => coin)];
+    },
+    assertValid(map, state) {
+        const coins = CoinHashesMap.pickAllCoins(state);
+        const coinNonces = new Set(Iterable.map(coins, (coin) => coin.nonce));
+        const definedNonces = new Set(Object.keys(map));
+        const missingNonces = coinNonces.difference(definedNonces);
+        return missingNonces.size === 0 ? Either.void : Either.left(missingNonces);
+    },
+    updateWithCoins(secretKeys, existing, coins) {
+        return Record.fromIterableWith(coins, (coin) => [
+            coin.nonce,
+            existing[coin.nonce] ?? {
+                commitment: ledger.coinCommitment(coin, secretKeys.coinPublicKey),
+                nullifier: ledger.coinNullifier(coin, secretKeys.coinSecretKey),
+            },
+        ]);
+    },
+    updateWithNewCoins(secretKeys, existing, coins) {
+        const newMap = CoinHashesMap.updateWithCoins(secretKeys, CoinHashesMap.empty, coins);
+        return Record.union(existing, newMap, (a) => a);
+    },
+    init(secretKeys, coins) {
+        return CoinHashesMap.updateWithCoins(secretKeys, {}, coins);
+    },
+};
+/**
+ * Releases every coin reservation a wallet carried across the ledger-version boundary.
+ *
+ * @remarks
+ *   `pendingSpends` crosses with the rest of the local state, and on the far side its entries name transactions of a
+ *   ledger version the chain has left behind: none of them can be included, so no inclusion will ever clear them, and a
+ *   coin held for one would sit outside the available set for the rest of the wallet's life. Re-deriving each spend and
+ *   reporting it failed is the ledger's own way of un-booking one: the reservation goes, and the coin stays at the
+ *   Merkle index the chain gave it, in a tree of unchanged height and root.
+ * @param state The local state as it crossed.
+ * @param secretKeys The keys the first sync update arrived with.
+ * @returns The same state with nothing reserved.
+ */
+const releaseStrandedSpends = (state, secretKeys) => pipe([...state.pendingSpends.values()], Arr.reduce(state, (released, [coin]) => pipe(LedgerOps.ledgerTry(() => {
+    const [reserved, input] = released.spend(secretKeys, coin, 0);
+    return reserved.applyFailed(ledger.ZswapOffer.fromInput(input, coin.type, coin.value));
+}), 
+// A reservation the ledger declines to re-derive is left exactly where it already was: one stranded coin is
+// not worth failing the update every other coin in this wallet is waiting on.
+Either.getOrElse(() => released))));
+export const CoreWallet = {
+    init(localState, secretKeys, networkId) {
+        const publicKeys = PublicKeys.fromSecretKeys(secretKeys);
+        const coinHashes = CoinHashesMap.init(secretKeys, CoinHashesMap.pickAllCoins(localState));
+        const progress = SyncProgress.createSyncProgress();
+        const protocolVersion = ProtocolVersion.MinSupportedVersion;
+        return { state: localState, publicKeys, networkId, coinHashes, progress, protocolVersion };
+    },
+    empty(publicKeys, networkId) {
+        return {
+            state: new ledger.ZswapLocalState(),
+            publicKeys,
+            networkId,
+            coinHashes: CoinHashesMap.empty,
+            progress: SyncProgress.createSyncProgress(),
+            protocolVersion: ProtocolVersion.MinSupportedVersion,
+        };
+    },
+    restore(localState, secretKeys, syncProgress, protocolVersion, networkId) {
+        const publicKeys = PublicKeys.fromSecretKeys(secretKeys);
+        const coinHashes = CoinHashesMap.init(secretKeys, CoinHashesMap.pickAllCoins(localState));
+        return {
+            state: localState,
+            publicKeys,
+            networkId,
+            coinHashes,
+            progress: SyncProgress.createSyncProgress(syncProgress),
+            protocolVersion: ProtocolVersion.ProtocolVersion(protocolVersion),
+        };
+    },
+    restoreWithCoinHashes(publicKeys, localState, coinHashes, syncProgress, protocolVersion, networkId) {
+        return CoinHashesMap.assertValid(coinHashes, localState).pipe(Either.mapBoth({
+            onLeft: (missingNonces) => new InvalidCoinHashesError({ message: 'Missing coin hashes for coins present in the state', missingNonces }),
+            onRight: () => ({
+                state: localState,
+                publicKeys,
+                networkId,
+                coinHashes,
+                progress: SyncProgress.createSyncProgress(syncProgress),
+                protocolVersion: ProtocolVersion.ProtocolVersion(protocolVersion),
+            }),
+        }));
+    },
+    /**
+     * Restores a wallet whose coin hashes were never computed — a snapshot taken mid-crossing.
+     *
+     * @remarks
+     *   The counterpart of {@link CoreWallet.restoreWithCoinHashes} for the one shape that validation would otherwise
+     *   refuse: a full local state, carried across the ledger-version boundary as bytes, beside an empty hash map. The
+     *   hashes are commitments and nullifiers, and computing them needs the secret keys a deserializer does not hold, so
+     *   the wallet comes back still marked pending and the first sync update fills them in
+     *   ({@link CoreWallet.resolveCoinHashes}). Total: there is nothing here to reject, which is exactly why it is a
+     *   separate entry point rather than a flag on the validating one.
+     * @param publicKeys The identity the snapshot declared.
+     * @param localState The local state the snapshot carried.
+     * @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.
+     * @returns A wallet holding that state, its coin hashes still pending.
+     */
+    restoreWithPendingCoinHashes(publicKeys, localState, syncProgress, protocolVersion, networkId) {
+        return {
+            state: localState,
+            publicKeys,
+            networkId,
+            coinHashes: CoinHashesMap.empty,
+            coinHashesPending: true,
+            progress: SyncProgress.createSyncProgress(syncProgress),
+            protocolVersion: ProtocolVersion.ProtocolVersion(protocolVersion),
+        };
+    },
+    initEmpty(keys, networkId) {
+        return this.empty(PublicKeys.fromSecretKeys(keys), networkId);
+    },
+    /**
+     * Records an observed protocol version on the wallet, never going backwards.
+     *
+     * @remarks
+     *   The version is a signal, not a measurement: writing one outside the running variant's activation range is what
+     *   makes it hand over to the next variant. A source that briefly reports an older version — a reconnect replaying
+     *   from an earlier cursor, say — must therefore not be able to drag the wallet back below a boundary it has already
+     *   crossed, which would ask the runtime to migrate backwards. Taking the maximum makes that unrepresentable.
+     * @param wallet The wallet to annotate.
+     * @param version The protocol version just observed.
+     * @returns `wallet` unchanged if it already records `version` or a later one, otherwise a copy recording `version`.
+     */
+    withProtocolVersion(wallet, version) {
+        return version > wallet.protocolVersion ? { ...wallet, protocolVersion: version } : wallet;
+    },
+    /**
+     * Adopts a wallet inherited from the previous ledger version: its local state, its identity, and its position.
+     *
+     * @remarks
+     *   The state passed in is this ledger version's own object, decoded from the previous version's bytes — the two majors
+     *   share the `zswap-local-state` codec, so the crossing is a round-trip rather than a reconstruction (see
+     *   `Migration.makeCrossLedgerMigration`, and the characterization test that pins the codec). So everything the
+     *   previous wallet's tree held arrives intact: its coins at the Merkle indices the chain gave them, the height it
+     *   had reached, and the outputs it was still expecting. What also crosses is the public keys, the network, the
+     *   protocol version that triggered the hand-over (kept so the new variant starts inside its own activation range
+     *   rather than immediately signalling backwards), and the cursor the previous variant stopped at.
+     *
+     *   **Sync progress is parked at the fork, not rewound**: the previous wallet's cursor crosses unchanged. The indexer
+     *   numbers ledger-v9 events onwards from whatever id it had reached when the fork happened, never from zero, so
+     *   resuming from the inherited cursor is what puts this wallet in front of them. Rewinding to zero would park it on
+     *   a stretch of history that this ledger version's events do not occupy. What does not cross is `isConnected`: no
+     *   sync is running behind this state yet.
+     *
+     *   The one thing the bytes cannot supply is the coin hashes: commitments and nullifiers are computed from the secret
+     *   keys, which a migration by design does not hold. They are therefore left empty and marked
+     *   {@link CoreWallet.coinHashesPending}, for {@link CoreWallet.completeCrossing} to fill in at the first sync update —
+     *   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.
+     * @returns A wallet of this ledger version holding what its predecessor held, positioned at the fork.
+     */
+    fromPreviousVersion(previous) {
+        return {
+            state: previous.state,
+            publicKeys: previous.publicKeys,
+            networkId: previous.networkId,
+            coinHashes: CoinHashesMap.empty,
+            coinHashesPending: true,
+            progress: SyncProgress.createSyncProgress({ ...previous.progress, isConnected: false }),
+            protocolVersion: ProtocolVersion.ProtocolVersion(previous.protocolVersion),
+        };
+    },
+    /**
+     * Finishes a crossing at the first sync update: the reservations released, then the coin hashes computed.
+     *
+     * @remarks
+     *   The other half of {@link CoreWallet.fromPreviousVersion}. A migrated wallet arrives holding its whole local state
+     *   but nothing it needs the secret keys for — no commitments or nullifiers, and no way to un-book the spends it
+     *   carried — because a migration is by design handed no key material. The first sync update carries it, so this is
+     *   where both gaps close: {@link releaseStrandedSpends} first, since a released coin is one more coin the hashes have
+     *   to name, and {@link CoreWallet.resolveCoinHashes} over the state that comes back. Applied at the head of both sync
+     *   capabilities, before anything else they do, so a batch that turns out to be empty still runs it: a wallet that
+     *   crossed into a quiet timeline must not be left unable to name or to spend the coins it crossed with.
+     *
+     *   Idempotent and self-clearing: without the marker this is the identity, so it costs a field read on every update
+     *   thereafter and nothing else. That is also what keeps it away from a reservation made on this side of the
+     *   boundary, whose transaction is live and whose coins are genuinely spoken for.
+     * @param wallet The wallet to complete.
+     * @param secretKeys The keys the update arrived with.
+     * @returns `wallet` unchanged if it never crossed, otherwise a copy whose coins are nameable and spendable again.
+     */
+    completeCrossing(wallet, secretKeys) {
+        return wallet.coinHashesPending === undefined
+            ? wallet
+            : CoreWallet.resolveCoinHashes({ ...wallet, state: releaseStrandedSpends(wallet.state, secretKeys) }, secretKeys);
+    },
+    /**
+     * Computes the coin hashes a wallet crossed the ledger-version boundary without.
+     *
+     * @remarks
+     *   The hash half of {@link CoreWallet.completeCrossing}, which is what the sync capabilities call: a crossing has a
+     *   second gap to close beside this one, so a caller finishing one should go through the combined step rather than
+     *   here. A migrated wallet arrives holding its whole local state but no commitments or nullifiers for it, because
+     *   deriving those needs the secret keys, and the first sync update is what carries them.
+     *
+     *   Idempotent and self-clearing: without the marker this is the identity.
+     * @param wallet The wallet to complete.
+     * @param secretKeys The keys the update arrived with.
+     * @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,
+            };
+    },
+    applyCollapsedUpdate(wallet, collapsed) {
+        const newState = wallet.state.applyCollapsedUpdate(collapsed);
+        return { ...wallet, state: newState };
+    },
+    apply(wallet, secretKeys, offer) {
+        const newState = wallet.state.apply(secretKeys, offer);
+        const newCoinHashes = CoinHashesMap.updateWithCoins(secretKeys, wallet.coinHashes, CoinHashesMap.pickAllCoins(newState));
+        return { ...wallet, state: newState, coinHashes: newCoinHashes };
+    },
+    replayEventsWithChanges(wallet, secretKeys, events) {
+        const stateWithChanges = wallet.state.replayEventsWithChanges(secretKeys, events);
+        const newState = stateWithChanges.state;
+        const newCoinHashes = CoinHashesMap.updateWithCoins(secretKeys, wallet.coinHashes, CoinHashesMap.pickAllCoins(newState));
+        const updatedWallet = { ...wallet, state: newState, coinHashes: newCoinHashes };
+        return [updatedWallet, stateWithChanges.changes];
+    },
+    updateProgress(wallet, { appliedIndex, highestRelevantWalletIndex, highestIndex, highestRelevantIndex, isConnected, }) {
+        const updatedProgress = SyncProgress.createSyncProgress({
+            appliedIndex: appliedIndex ?? wallet.progress.appliedIndex,
+            highestRelevantWalletIndex: highestRelevantWalletIndex ?? wallet.progress.highestRelevantWalletIndex,
+            highestIndex: highestIndex ?? wallet.progress.highestIndex,
+            highestRelevantIndex: highestRelevantIndex ?? wallet.progress.highestRelevantIndex,
+            isConnected: isConnected ?? wallet.progress.isConnected,
+        });
+        return { ...wallet, progress: updatedProgress };
+    },
+    // TODO: Remove after tx history is implemented
+    addTransaction(wallet, _tx) {
+        return wallet;
+    },
+    /* not implemented until this is done https://shielded.atlassian.net/browse/PM-19678 */
+    revertTransaction(wallet, tx) {
+        const newState = wallet.state.revertTransaction(tx);
+        return { ...wallet, state: newState };
+    },
+    // TODO: Remove after tx history is implemented
+    updateTxHistory(wallet, _newTxs) {
+        return wallet;
+    },
+    spendCoins(wallet, secretKeys, coins, segment) {
+        const [offers, newLocalState] = pipe(coins, Arr.reduce([[], wallet.state], ([accOffers, localState], coinToSpend) => {
+            const [nextState, newInput] = localState.spend(secretKeys, coinToSpend, segment);
+            const inputOffer = ledger.ZswapOffer.fromInput(newInput, coinToSpend.type, coinToSpend.value);
+            return [accOffers.concat([inputOffer]), nextState];
+        }));
+        const updated = { ...wallet, state: newLocalState };
+        return [offers, updated];
+    },
+    watchCoins(wallet, secretKeys, coins) {
+        const newLocalState = coins.reduce((localState, coin) => localState.watchFor(wallet.publicKeys.coinPublicKey, coin), wallet.state);
+        const newCoinHashes = CoinHashesMap.updateWithNewCoins(secretKeys, wallet.coinHashes, coins);
+        return { ...wallet, state: newLocalState, coinHashes: newCoinHashes };
+    },
+};

package/dist/v2/Keys.d.ts

@@ -0,0 +1,8 @@
+import type { CoreWallet } from './CoreWallet.js';
+import { ShieldedAddress, ShieldedCoinPublicKey, ShieldedEncryptionPublicKey } from '@midnightntwrk/wallet-sdk-address-format';
+export type KeysCapability<TState> = {
+    getCoinPublicKey(state: TState): ShieldedCoinPublicKey;
+    getEncryptionPublicKey(state: TState): ShieldedEncryptionPublicKey;
+    getAddress(state: TState): ShieldedAddress;
+};
+export declare const makeDefaultKeysCapability: () => KeysCapability<CoreWallet>;

package/dist/v2/Keys.js

@@ -0,0 +1,16 @@
+import { ShieldedAddress, ShieldedCoinPublicKey, ShieldedEncryptionPublicKey, } from '@midnightntwrk/wallet-sdk-address-format';
+export const makeDefaultKeysCapability = () => {
+    return {
+        getCoinPublicKey: (state) => {
+            return new ShieldedCoinPublicKey(Buffer.from(state.publicKeys.coinPublicKey, 'hex'));
+        },
+        getEncryptionPublicKey: (state) => {
+            return new ShieldedEncryptionPublicKey(Buffer.from(state.publicKeys.encryptionPublicKey, 'hex'));
+        },
+        getAddress: (state) => {
+            const coinPublicKey = new ShieldedCoinPublicKey(Buffer.from(state.publicKeys.coinPublicKey, 'hex'));
+            const encryptionPublicKey = new ShieldedEncryptionPublicKey(Buffer.from(state.publicKeys.encryptionPublicKey, 'hex'));
+            return new ShieldedAddress(coinPublicKey, encryptionPublicKey);
+        },
+    };
+};

package/dist/v2/Migration.d.ts

@@ -0,0 +1,112 @@
+import { type NetworkId, type SyncProgress } from '@midnightntwrk/wallet-sdk-abstractions';
+import { Effect } from 'effect';
+import { CoreWallet } from './CoreWallet.js';
+import { type WalletError } from './WalletError.js';
+/**
+ * How this variant produces its first state from whatever came before it.
+ *
+ * @remarks
+ *   The strategy is injected through the builder rather than hard-coded into the variant, because "whatever came before"
+ *   is not one thing: an empty wallet at first start, a wallet of this same ledger version, or a wallet of the ledger
+ *   version this one replaced. Those are different functions with different input types, and the runtime only ever
+ *   needs one of them per registration — so which one is a build-time decision, expressed as a dictionary in the
+ *   repository's usual dictionary-passing style.
+ * @typeParam TPreviousState The state this migration consumes.
+ */
+export type StateMigration<TPreviousState> = {
+    migrate: (previousState: TPreviousState) => Effect.Effect<CoreWallet, WalletError>;
+};
+export type EmptyWalletMigrationConfiguration = {
+    networkId: NetworkId.NetworkId;
+};
+/**
+ * The migration used when there is no previous wallet at all.
+ *
+ * @remarks
+ *   It backs `WalletLike.startEmpty`, which builds a wallet before any key material exists. The resulting state has no
+ *   coins and public keys derived from a fixed placeholder seed; it is a scaffold to be replaced by a real start, not a
+ *   wallet anybody can transact with. Preserved verbatim from the ledger-v8 implementation so that `startEmpty` behaves
+ *   exactly as it did.
+ * @example
+ *   ```typescript
+ *   const builder = new V2Builder().withDefaults().withMigration(makeEmptyWalletMigration({ networkId }));
+ *   ```;
+ *
+ * @param configuration Supplies the network the scaffold state claims to be on.
+ * @returns A migration from `null`.
+ */
+export declare const makeEmptyWalletMigration: (configuration: EmptyWalletMigrationConfiguration) => StateMigration<null>;
+/**
+ * The migration between two variants that share this ledger version.
+ *
+ * @remarks
+ *   Both sides speak the same state type, so the carry is the identity: local Merkle tree, coins, coin hashes and sync
+ *   progress all remain valid, and nothing has to be re-read. This is the right strategy for a protocol bump that does
+ *   not change serialization.
+ * @returns A migration from a {@link CoreWallet} of this ledger version.
+ */
+export declare const makeCarryOverMigration: () => StateMigration<CoreWallet>;
+/**
+ * The shape a wallet of the _previous_ ledger version must expose to be carried across a hard fork.
+ *
+ * @remarks
+ *   Structural on purpose. The previous variant's `CoreWallet` is built on a different ledger module, and naming that
+ *   module here would drag a second multi-megabyte WASM binary into this variant for the sake of a type. Everything the
+ *   crossing reads is plain data — the ledger's key and network types are all string aliases — with one exception,
+ *   `state`, which is named by the single capability the crossing uses: it can serialize itself. Both ledger versions'
+ *   `ZswapLocalState` satisfies that as it is, and describing it that narrowly is what keeps this type version-agnostic
+ *   — the bytes are the interface, not the object (see {@link makeCrossLedgerMigration}).
+ *
+ *   `progress` is where the migrated wallet resumes from: the ledger-v9 timeline continues the indexer's event ids rather
+ *   than restarting them, so the previous variant's cursor is the position the next one has to start at (see
+ *   {@link makeCrossLedgerMigration}).
+ */
+export type PreviousLedgerWallet = Readonly<{
+    publicKeys: {
+        readonly coinPublicKey: string;
+        readonly encryptionPublicKey: string;
+    };
+    networkId: string;
+    protocolVersion: bigint;
+    progress: SyncProgress.SyncProgressData;
+    state: Readonly<{
+        serialize: () => Uint8Array;
+    }>;
+}>;
+/**
+ * The migration across a ledger-version boundary: the local state crosses as bytes, identity and position beside it.
+ *
+ * @remarks
+ *   The chain's state translation carries every commitment across the fork in place — the ledger-v9 tree continues at the
+ *   index the ledger-v8 tree reached, and the indexer does **not** replay the ledger-v8 timeline as new-version events.
+ *   So the wallet's own state must cross with it, or the coins are gone.
+ *
+ *   It crosses as bytes. The two ledger majors either side of this boundary serialize `ZswapLocalState` under the same
+ *   `zswap-local-state` codec — the transaction codec moved at the fork, this one did not — so the previous version's
+ *   serialization is something this version can simply read. The crossing is therefore a round-trip and not a
+ *   reconstruction, and everything survives it: the coins at the Merkle indices the chain gave them, the height the
+ *   tree had reached, and the outputs the wallet was still expecting, which no reconstruction from spendable coins
+ *   could have recovered. `src/v2/test/byteCrossing.test.ts` pins that codec against both real ledgers, and states what
+ *   to do if it ever goes red.
+ *
+ *   **The coins booked for transactions still in flight cross too, and are released at the first sync update.** Those
+ *   transactions belong to the ledger version the chain has left behind, so none of them can ever be included and no
+ *   inclusion will ever clear the reservations they left in `pendingSpends` — the coins would simply stop being
+ *   spendable. The release cannot happen here, because un-booking a spend needs the secret keys a migration is by
+ *   design handed none of; it happens at the first sync update instead, which is where keys and carried state meet
+ *   (`CoreWallet.completeCrossing`). The change outputs those same transactions would have paid back are left as they
+ *   are, and nothing ever removes them: these entries carry no TTL and `ZswapLocalState.clearPending` does nothing in
+ *   either ledger, so they sit in `pendingOutputs` for the life of the wallet. A known limitation, and a mild one —
+ *   they overstate the pending balance, but they reserve no coin and block no spending.
+ *
+ *   Read through `LedgerOps.ledgerTry`, so a codec that has moved is a `WalletError` at the boundary and never a throw:
+ *   the failure mode of a future major moving `zswap-local-state` is loud, and lands here, where the
+ *   {@link StateMigration} seam can be given the ledger team's own translation instead.
+ *
+ *   Sync progress is **parked at the fork** rather than rewound: the indexer numbers ledger-v9 events onwards from
+ *   whatever id it had reached when the fork happened, never from zero, so the inherited cursor is exactly where this
+ *   wallet's reading resumes. A wallet that rewound to zero would wait on a stretch of the timeline this ledger
+ *   version's events do not occupy.
+ * @returns A migration from a previous-ledger-version wallet.
+ */
+export declare const makeCrossLedgerMigration: () => StateMigration<PreviousLedgerWallet>;

package/dist/v2/Migration.js

@@ -0,0 +1,96 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// Licensed under the Apache License, Version 2.0 (the "License");
+// You may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import * as ledger from '@midnightntwrk/ledger-v9';
+import { WalletSeed } from '@midnightntwrk/wallet-sdk-abstractions';
+import { EitherOps, LedgerOps } from '@midnightntwrk/wallet-sdk-utilities';
+import { Effect, Either, pipe } from 'effect';
+import { CoreWallet, PublicKeys } from './CoreWallet.js';
+/**
+ * The migration used when there is no previous wallet at all.
+ *
+ * @remarks
+ *   It backs `WalletLike.startEmpty`, which builds a wallet before any key material exists. The resulting state has no
+ *   coins and public keys derived from a fixed placeholder seed; it is a scaffold to be replaced by a real start, not a
+ *   wallet anybody can transact with. Preserved verbatim from the ledger-v8 implementation so that `startEmpty` behaves
+ *   exactly as it did.
+ * @example
+ *   ```typescript
+ *   const builder = new V2Builder().withDefaults().withMigration(makeEmptyWalletMigration({ networkId }));
+ *   ```;
+ *
+ * @param configuration Supplies the network the scaffold state claims to be on.
+ * @returns A migration from `null`.
+ */
+export const makeEmptyWalletMigration = (configuration) => ({
+    migrate: () => {
+        const seed = WalletSeed.fromString('0000000000000000000000000000000000000000000000000000000000000001');
+        return Effect.succeed(CoreWallet.empty(PublicKeys.fromSecretKeys(ledger.ZswapSecretKeys.fromSeed(seed)), configuration.networkId));
+    },
+});
+/**
+ * The migration between two variants that share this ledger version.
+ *
+ * @remarks
+ *   Both sides speak the same state type, so the carry is the identity: local Merkle tree, coins, coin hashes and sync
+ *   progress all remain valid, and nothing has to be re-read. This is the right strategy for a protocol bump that does
+ *   not change serialization.
+ * @returns A migration from a {@link CoreWallet} of this ledger version.
+ */
+export const makeCarryOverMigration = () => ({
+    migrate: (previousState) => Effect.succeed(previousState),
+});
+/**
+ * The migration across a ledger-version boundary: the local state crosses as bytes, identity and position beside it.
+ *
+ * @remarks
+ *   The chain's state translation carries every commitment across the fork in place — the ledger-v9 tree continues at the
+ *   index the ledger-v8 tree reached, and the indexer does **not** replay the ledger-v8 timeline as new-version events.
+ *   So the wallet's own state must cross with it, or the coins are gone.
+ *
+ *   It crosses as bytes. The two ledger majors either side of this boundary serialize `ZswapLocalState` under the same
+ *   `zswap-local-state` codec — the transaction codec moved at the fork, this one did not — so the previous version's
+ *   serialization is something this version can simply read. The crossing is therefore a round-trip and not a
+ *   reconstruction, and everything survives it: the coins at the Merkle indices the chain gave them, the height the
+ *   tree had reached, and the outputs the wallet was still expecting, which no reconstruction from spendable coins
+ *   could have recovered. `src/v2/test/byteCrossing.test.ts` pins that codec against both real ledgers, and states what
+ *   to do if it ever goes red.
+ *
+ *   **The coins booked for transactions still in flight cross too, and are released at the first sync update.** Those
+ *   transactions belong to the ledger version the chain has left behind, so none of them can ever be included and no
+ *   inclusion will ever clear the reservations they left in `pendingSpends` — the coins would simply stop being
+ *   spendable. The release cannot happen here, because un-booking a spend needs the secret keys a migration is by
+ *   design handed none of; it happens at the first sync update instead, which is where keys and carried state meet
+ *   (`CoreWallet.completeCrossing`). The change outputs those same transactions would have paid back are left as they
+ *   are, and nothing ever removes them: these entries carry no TTL and `ZswapLocalState.clearPending` does nothing in
+ *   either ledger, so they sit in `pendingOutputs` for the life of the wallet. A known limitation, and a mild one —
+ *   they overstate the pending balance, but they reserve no coin and block no spending.
+ *
+ *   Read through `LedgerOps.ledgerTry`, so a codec that has moved is a `WalletError` at the boundary and never a throw:
+ *   the failure mode of a future major moving `zswap-local-state` is loud, and lands here, where the
+ *   {@link StateMigration} seam can be given the ledger team's own translation instead.
+ *
+ *   Sync progress is **parked at the fork** rather than rewound: the indexer numbers ledger-v9 events onwards from
+ *   whatever id it had reached when the fork happened, never from zero, so the inherited cursor is exactly where this
+ *   wallet's reading resumes. A wallet that rewound to zero would wait on a stretch of the timeline this ledger
+ *   version's events do not occupy.
+ * @returns A migration from a previous-ledger-version wallet.
+ */
+export const makeCrossLedgerMigration = () => ({
+    migrate: (previousState) => pipe(LedgerOps.ledgerTry(() => ledger.ZswapLocalState.deserialize(previousState.state.serialize())), Either.map((state) => CoreWallet.fromPreviousVersion({
+        state,
+        publicKeys: previousState.publicKeys,
+        networkId: previousState.networkId,
+        protocolVersion: previousState.protocolVersion,
+        progress: previousState.progress,
+    })), EitherOps.toEffect),
+});

package/dist/v2/RunningV2Variant.d.ts

@@ -0,0 +1,40 @@
+import type * as ledger from '@midnightntwrk/ledger-v9';
+import { Effect, Scope, Stream } from 'effect';
+import { type WalletRuntimeError, type Variant, StateChange } from '@midnightntwrk/wallet-sdk-runtime/abstractions';
+import { type SerializationCapability } from './Serialization.js';
+import { type ChangesResult, type EventsSyncUpdate, type SyncCapability, type SyncService } from './Sync.js';
+import { type TransactingCapability, type TokenTransfer, type BalancingResult } from './Transacting.js';
+import { type WalletError } from './WalletError.js';
+import { type CoinsAndBalancesCapability } from './CoinsAndBalances.js';
+import { type KeysCapability } from './Keys.js';
+import { type CoinSelection } from '@midnightntwrk/wallet-sdk-capabilities';
+import { type CoreWallet } from './CoreWallet.js';
+import { type TransactionHistoryService } from './TransactionHistory.js';
+export declare namespace RunningV2Variant {
+    type Context<TSerialized, TSyncUpdate, TTransaction, TStartAux> = {
+        serializationCapability: SerializationCapability<CoreWallet, null, TSerialized>;
+        syncService: SyncService<CoreWallet, TStartAux, TSyncUpdate>;
+        syncCapability: SyncCapability<CoreWallet, TSyncUpdate, ChangesResult>;
+        transactingCapability: TransactingCapability<ledger.ZswapSecretKeys, CoreWallet, TTransaction>;
+        coinsAndBalancesCapability: CoinsAndBalancesCapability<CoreWallet>;
+        keysCapability: KeysCapability<CoreWallet>;
+        coinSelection: CoinSelection<ledger.QualifiedShieldedCoinInfo>;
+        transactionHistoryService: TransactionHistoryService;
+    };
+    type AnyContext = Context<any, any, any, any>;
+}
+export declare const V2Tag: unique symbol;
+export type DefaultRunningV2 = RunningV2Variant<string, EventsSyncUpdate, ledger.FinalizedTransaction, ledger.ZswapSecretKeys>;
+export declare class RunningV2Variant<TSerialized, TSyncUpdate, TTransaction, TStartAux> implements Variant.RunningVariant<typeof V2Tag, CoreWallet> {
+    #private;
+    readonly __polyTag__: typeof V2Tag;
+    readonly state: Stream.Stream<StateChange.StateChange<CoreWallet>, WalletRuntimeError>;
+    constructor(scope: Scope.Scope, context: Variant.VariantContext<CoreWallet>, v2Context: RunningV2Variant.Context<TSerialized, TSyncUpdate, TTransaction, TStartAux>);
+    startSyncInBackground(startAux: TStartAux): Effect.Effect<void>;
+    startSync(startAux: TStartAux): Stream.Stream<void, WalletError, Scope.Scope>;
+    balanceTransaction(secretKeys: ledger.ZswapSecretKeys, tx: ledger.Transaction<ledger.Signaturish, ledger.Proofish, ledger.Bindingish>): Effect.Effect<BalancingResult, WalletError>;
+    transferTransaction(secretKeys: ledger.ZswapSecretKeys, outputs: ReadonlyArray<TokenTransfer>): Effect.Effect<ledger.UnprovenTransaction, WalletError>;
+    initSwap(secretKeys: ledger.ZswapSecretKeys, desiredInputs: Record<ledger.RawTokenType, bigint>, desiredOutputs: ReadonlyArray<TokenTransfer>): Effect.Effect<ledger.UnprovenTransaction, WalletError>;
+    revertTransaction(transaction: ledger.Transaction<ledger.Signaturish, ledger.Proofish, ledger.Bindingish>): Effect.Effect<void, WalletError>;
+    serializeState(state: CoreWallet): TSerialized;
+}