@midnight-ntwrk/wallet-sdk-facade 5.0.0-beta.2 → 5.0.0-beta.3

package/dist/index.js

@@ -10,21 +10,31 @@
 // 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 * as ledgerV9 from '@midnightntwrk/ledger-v9';
 import { makeDefaultSubmissionService, } from '@midnight-ntwrk/wallet-sdk-capabilities';
-import { makeDefaultProvingService, } from '@midnight-ntwrk/wallet-sdk-capabilities/proving';
+import { makeDefaultVersionedProvingService, } from '@midnight-ntwrk/wallet-sdk-capabilities/proving';
 import { ShieldedSectionSchema, mergeShieldedSections, } from '@midnight-ntwrk/wallet-sdk-shielded';
 import { UnshieldedSectionSchema, mergeUnshieldedSections, } from '@midnight-ntwrk/wallet-sdk-unshielded-wallet';
 import { DustSectionSchema, mergeDustSections } from '@midnight-ntwrk/wallet-sdk-dust-wallet';
 import { Clock } from '@midnight-ntwrk/wallet-sdk-utilities';
 import { FetchTermsAndConditions as FetchTermsAndConditionsQuery } from '@midnight-ntwrk/wallet-sdk-indexer-client';
 import { QueryRunner } from '@midnight-ntwrk/wallet-sdk-indexer-client/effect';
-import { Array as Arr, pipe, Schema } from 'effect';
-import { TransactionHistoryStorage } from '@midnight-ntwrk/wallet-sdk-abstractions';
-import { combineLatest, map, firstValueFrom, concatMap } from 'rxjs';
+import { Array as Arr, Either, Option, pipe, Schema } from 'effect';
+import { ProtocolVersion, TransactionHistoryStorage, WalletTransaction, } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import * as ledgerV8 from '@midnight-ntwrk/ledger-v8';
+import * as Signatures from '@midnight-ntwrk/wallet-sdk-capabilities/signatures';
+import { BehaviorSubject, combineLatest, concatMap, distinctUntilChanged, firstValueFrom, map, tap, } from 'rxjs';
 import { PendingTransactions, PendingTransactionsServiceImpl, } from '@midnight-ntwrk/wallet-sdk-capabilities';
-import { makeDefaultBlockDataFetcher, makeDefaultValidationService, ValidationFetchError, WellFormedError, } from '@midnight-ntwrk/wallet-sdk-capabilities/validation';
-import { finalizedTransactionTrait, txHistoryHash } from './transaction.js';
+import { makeDefaultBlockDataFetcher, makeDefaultVersionedValidationService, ValidationFetchError, WellFormedError, } from '@midnight-ntwrk/wallet-sdk-capabilities/validation';
+import { finalizedTransactionTraits, txHistoryHash } from './transaction.js';
+/**
+ * Why the wallet gave up on a transaction, for the history entry.
+ *
+ * @remarks
+ *   A chain rejection speaks for itself through the entry's status; an orphaned transaction has no chain verdict at all,
+ *   so the entry is the only place the reason can be recorded.
+ */
+const rejectionReason = (result) => result.status === 'ORPHANED_BY_FORK' ? 'orphaned-by-protocol-upgrade' : undefined;
 /**
  * Full entry schema for transaction history. The common entry data and wallet-specific sections (`shielded`,
  * `unshielded`, `dust`) live on every entry regardless of lifecycle; the `lifecycle` field is the only discriminator.
@@ -44,7 +54,7 @@ export const isFinalizedWalletEntry = (entry) => entry.lifecycle.status === 'fin
  *   wallet has set the value, later writes are no-ops for these fields. This is correct because the value is the same
  *   across all wallets (it's a property of the on-chain tx, not the wallet's view of it).
  * - **`identifiers`** — unioned (each wallet may surface a different identifier subset).
- * - **`lifecycle`** — incoming wins (this is how `pending → finalized` transitions are recorded).
+ * - **`lifecycle`** — incoming wins, except that a late rejection cannot overwrite recorded on-chain inclusion.
  * - **Wallet sections** (`shielded`, `unshielded`, `dust`) — combined via per-section merge when both sides have them;
  *   otherwise whichever side is present is used.
  */
@@ -73,8 +83,9 @@ export function mergeWalletEntries(existing, incoming) {
         status: existing.status ?? incoming.status,
         timestamp: existing.timestamp ?? incoming.timestamp,
         fees: existing.fees ?? incoming.fees,
-        // lifecycle: incoming wins — this is how pending → finalized/rejected transitions are recorded
-        lifecycle: incoming.lifecycle,
+        lifecycle: existing.lifecycle.status === 'finalized' && incoming.lifecycle.status === 'rejected'
+            ? existing.lifecycle
+            : incoming.lifecycle,
         ...(shielded !== undefined ? { shielded } : {}),
         ...(unshielded !== undefined ? { unshielded } : {}),
         ...(dust !== undefined ? { dust } : {}),
@@ -99,6 +110,16 @@ const revertTxHistoryKey = (tx) => {
         return undefined;
     return { hash: txHistoryHash(tx), identifiers };
 };
+const v9Authoring = {
+    sampleSigningKey: () => ledgerV9.sampleSigningKey(),
+    signatureVerifyingKey: (signingKey) => ledgerV9.signatureVerifyingKey(signingKey),
+    signData: (signingKey, data) => ledgerV9.signData(signingKey, data),
+};
+const v8Authoring = {
+    sampleSigningKey: () => ledgerV8.sampleSigningKey(),
+    signatureVerifyingKey: (signingKey) => Signatures.liftSignatureVerifyingKey(ledgerV8.signatureVerifyingKey(signingKey)),
+    signData: (signingKey, data) => Signatures.liftSignature(ledgerV8.signData(signingKey, data)),
+};
 const TokenKindsToBalance = new (class {
     allTokenKinds = ['shielded', 'unshielded', 'dust'];
     toFlags = (tokenKinds) => {
@@ -132,21 +153,132 @@ export const BalancingRecipe = {
         }
     },
 };
+/**
+ * The lowest of the protocol versions the three wallets have reached.
+ *
+ * @remarks
+ *   The three wallets follow the same chain but not in lock-step: each recognises a protocol version change when its own
+ *   synchronization reaches it, so around a fork they disagree for a while. A transaction spans all three, so the one
+ *   still behind is what bounds the facade as a whole — the highest version every wallet is known to be at.
+ * @param versions The version each wallet has reached.
+ * @returns The lowest of the three.
+ */
+export const lowestProtocolVersion = (versions) => [versions.shielded, versions.unshielded, versions.dust].reduce((lowest, candidate) => candidate < lowest ? candidate : lowest);
+/**
+ * The ledger-v9 key objects the wallets' own `start` takes, from whichever material the caller supplied.
+ *
+ * @remarks
+ *   Only the ledger-v9 side is needed here: a wallet built from seeds or from both versions' keys already holds what its
+ *   V1 variant needs, retained when it was built. What `start` supplies is the side the wallet's own API speaks.
+ */
+const v9KeysOf = (material) => 'v9' in material
+    ? material.v9
+    : {
+        shielded: ledgerV9.ZswapSecretKeys.fromSeed(material.shielded),
+        dust: ledgerV9.DustSecretKey.fromSeed(material.dust),
+    };
+/** The three wallets in a fixed order, so {@link protocolPhaseOf} reports them the same way every time. */
+const walletKinds = ['shielded', 'unshielded', 'dust'];
+/**
+ * Reads whether the wallets are settled on one side of a protocol boundary, or still crossing it.
+ *
+ * @remarks
+ *   Derived entirely from the version each wallet has reported and where the boundary lies — the same two facts every
+ *   other version-routing decision in the SDK is made from, so this reading cannot disagree with them.
+ * @param versions The version each wallet has reached.
+ * @param forkVersion The version at which the chain hands over to the next ledger version.
+ * @returns The reading. See {@link ProtocolPhase}.
+ */
+export const protocolPhaseOf = (versions, forkVersion) => {
+    const reported = walletKinds.map((kind) => [kind, versions[kind]]);
+    const from = lowestProtocolVersion(versions);
+    const epoch = ProtocolVersion.epochOf(from, forkVersion);
+    const crossed = reported.filter(([, version]) => !ProtocolVersion.withinRange(version, epoch));
+    if (crossed.length === 0)
+        return { _tag: 'Settled', version: from };
+    return {
+        _tag: 'Crossing',
+        from,
+        to: crossed.reduce((highest, [, version]) => (version > highest ? version : highest), crossed[0][1]),
+        behind: reported.filter(([, version]) => ProtocolVersion.withinRange(version, epoch)).map(([kind]) => kind),
+    };
+};
+/** Reads what has become of a transaction from the verdict the pending set holds, if it holds one. */
+const pendingStatusOf = (result) => {
+    if (result === undefined)
+        return { _tag: 'Submitted' };
+    switch (result.status) {
+        case 'SUCCESS':
+            return { _tag: 'Confirmed', segments: result.segments };
+        case 'FAILURE':
+        case 'PARTIAL_SUCCESS':
+            // A transaction only some of whose segments succeeded is still not a transaction that happened as submitted.
+            return { _tag: 'Rejected', segments: result.segments };
+        case 'ORPHANED_BY_FORK':
+            return { _tag: 'Orphaned', authoredFor: result.authoredFor, chainNow: result.chainNow };
+    }
+};
+/**
+ * The pending transactions as an application reads them.
+ *
+ * @remarks
+ *   A projection over the pending set the services keep, not a second copy of it: the facts are the same, stated as a
+ *   list of transactions with a status each rather than as the bag the machinery works in.
+ * @param pending The pending set.
+ * @returns One entry per transaction, in the order the wallet recorded them.
+ */
+export const pendingTransactionsOf = (pending) => pending.all.map((item) => ({
+    transaction: item.tx,
+    submittedAt: item.creationTime,
+    authoredFor: item.protocolVersion,
+    status: pendingStatusOf('result' in item ? item.result : undefined),
+}));
 export class FacadeState {
     shielded;
     unshielded;
     dust;
     pending;
+    /** The protocol version each of the three wallets has reached. */
+    get protocolVersion() {
+        return {
+            shielded: this.shielded.protocolVersion,
+            unshielded: this.unshielded.protocolVersion,
+            dust: this.dust.protocolVersion,
+        };
+    }
+    /**
+     * The protocol version the facade as a whole can act at: the lowest the three wallets have reached.
+     *
+     * @remarks
+     *   Around a protocol boundary the three wallets cross at slightly different moments, and a transaction needs all
+     *   three. This is the version every one of them is known to understand.
+     */
+    get activeProtocolVersion() {
+        return lowestProtocolVersion(this.protocolVersion);
+    }
+    /**
+     * Whether the three wallets are settled on one side of the protocol boundary, or still crossing it.
+     *
+     * @remarks
+     *   Additive, and the reading `protocolVersion` alone cannot give: three versions that differ tell an application
+     *   nothing about whether the difference matters. See {@link ProtocolPhase}.
+     */
+    get protocol() {
+        return protocolPhaseOf(this.protocolVersion, this.#forkVersion);
+    }
     get isSynced() {
         return (this.shielded.state.progress.isStrictlyComplete() &&
             this.dust.state.progress.isStrictlyComplete() &&
             this.unshielded.progress.isStrictlyComplete());
     }
-    constructor(shielded, unshielded, dust, pending) {
+    /** Where the chain hands over from one ledger version to the next, which is what {@link protocol} is read against. */
+    #forkVersion;
+    constructor(shielded, unshielded, dust, pending, forkVersion = ProtocolVersion.MinSupportedVersion) {
         this.shielded = shielded;
         this.unshielded = unshielded;
         this.dust = dust;
-        this.pending = pending;
+        this.pending = pendingTransactionsOf(pending);
+        this.#forkVersion = forkVersion;
     }
 }
 const DEFAULT_TTL_MS = 60 * 60 * 1000; // 1 hour
@@ -161,29 +293,65 @@ const DEFAULT_TTL_MS = 60 * 60 * 1000; // 1 hour
  * without a circular dependency.
  */
 export { Clock };
+/**
+ * The fork schedule the facade presets when a configuration names none: {@link ProtocolVersion.V9NativeForkSchedule},
+ * ledger-v9 from the version a 2.x node reports.
+ *
+ * @remarks
+ *   Where a chain forks is a fact about the chain, which is why each wallet package requires `forks` and presets nothing.
+ *   The facade is the one place a preset decides nothing the SDK has not already decided: every chain the 2.x node line
+ *   runs hands over at this version, so an application copying the constant into its configuration only restates it. A
+ *   chain that hands over elsewhere states its own `forks`, which wins.
+ */
+export const DefaultForkSchedule = ProtocolVersion.V9NativeForkSchedule;
 // `BlockData` is not re-exported from the facade to avoid a name collision with the
 // `@midnight-ntwrk/wallet-sdk-dust-wallet` export. The two are structurally identical; users can name the type via
 // `@midnight-ntwrk/wallet-sdk-dust-wallet` or `@midnight-ntwrk/wallet-sdk-capabilities/validation`.
 export { ValidationFetchError, WellFormedError, };
 export class WalletFacade {
     static makeDefaultSubmissionService(config) {
+        // A handle serializes itself, which is all submission needs of a transaction — and the one thing every ledger
+        // version's transaction does identically.
         return makeDefaultSubmissionService(config);
     }
     static makeDefaultPendingTransactionsService(config) {
         return PendingTransactionsServiceImpl.init({
             configuration: config,
-            txTrait: finalizedTransactionTrait,
+            txTraits: finalizedTransactionTraits(config.forks.v9),
         });
     }
+    /**
+     * Builds the proving service a configuration describes.
+     *
+     * @remarks
+     *   Handed the same fork schedule the wallets are built with, because a proving backend is chosen by the epoch a
+     *   transaction belongs to and the two ends of that question must not be able to compute the boundary differently.
+     */
     static makeDefaultProvingService(config) {
-        if (config.provingServerUrl) {
-            return makeDefaultProvingService({
-                provingServerUrl: config.provingServerUrl,
-            });
-        }
-        else {
-            throw new Error("Missing required configuration: 'provingServerUrl' must be set in config, or provide a custom provingService in init parameters.");
-        }
+        return Either.getOrThrowWith(makeDefaultVersionedProvingService(config, config.forks), (error) => new Error(error.message));
+    }
+    /**
+     * Fills in what the facade presets — `forks`, as {@link DefaultForkSchedule} — so that the result is a configuration a
+     * wallet package can be built from.
+     *
+     * @remarks
+     *   {@link WalletFacade.init} does this itself, once and before anything is built, so the wallets, the default services
+     *   and the facade's own boundary cannot be given different schedules, and no factory needs to call it. It is public
+     *   for code outside a factory that needs the configuration the facade will use: an application building a wallet
+     *   package directly, or reading `forks` back to author a transaction for the right ledger version. Resolving twice
+     *   is the same as resolving once, so `init` may be handed the result.
+     * @example
+     *   ```typescript
+     *   const configuration = WalletFacade.resolveConfiguration({ networkId: 'undeployed', ... });
+     *   const facade = await WalletFacade.init({ configuration, shielded: (config) => ShieldedWallet(config), ... });
+     *   const authoredForV9 = protocolVersion >= configuration.forks.v9;
+     *   ```;
+     *
+     * @param configuration The configuration as given, with or without `forks`.
+     * @returns The same configuration with `forks` present: the schedule it named, or {@link DefaultForkSchedule}.
+     */
+    static resolveConfiguration(configuration) {
+        return { ...configuration, forks: configuration.forks ?? DefaultForkSchedule };
     }
     /**
      * Fetches the current Terms and Conditions from the network indexer.
@@ -215,7 +383,9 @@ export class WalletFacade {
      * and initialization of necessary components. Specifically - it requires following fields:
      *
      * - `configuration` - holding a configuration, which needs to extend {@link DefaultConfiguration} - this way allows to
-     *   convey use-case-specific settings in the same way, as the SDK works by default
+     *   convey use-case-specific settings in the same way, as the SDK works by default. `forks` may be left out; every
+     *   factory below is handed a {@link ResolvedConfiguration}, which always has it — what
+     *   {@link WalletFacade.resolveConfiguration} returns
      * - `shielded` - a function taking the configuration and returning shielded wallet (or a promise with such)
      *   implementing {@link ShieldedWalletAPI}
      * - `unshielded` - a function taking the configuration and returning unshielded wallet (or a promise with such)
@@ -224,38 +394,38 @@ export class WalletFacade {
      *   {@link DustWalletAPI} There are some optional services/abstractions to provide, too. If not provided - default
      *   implementations will be used, each of them is initialized by a function taking the configuration and returning
      *   proper implementation (wrapped in a {@link Promise} or not).
-     * - `submissionService` - needs to implement {@link SubmissionService} for a {@link ledger.FinalizedTransaction} to
+     * - `submissionService` - needs to implement {@link SubmissionService} for a {@link ledgerV9.FinalizedTransaction} to
      *   submit transactions to the network, default uses Node RPC connection
      * - `pendingTransactionsService` - needs to implement {@link PendingTransactionsService} for a
-     *   {@link ledger.FinalizedTransaction} to keep track of pending transactions, default uses in-memory implementation
-     * - `provingService` - needs to implement {@link ProvingService} to prove it, default uses proving server
+     *   {@link ledgerV9.FinalizedTransaction} to keep track of pending transactions, default uses in-memory
+     *   implementation
+     * - `provingService` - needs to implement {@link VersionedProvingService} to prove it, default uses proving server
      * - `clock` - needs to implement {@link Clock.Clock} for getting current time, default uses system clock
      */
     static async init(initParams) {
+        const configuration = WalletFacade.resolveConfiguration(initParams.configuration);
         const submissionService = await Promise.resolve(initParams.submissionService
-            ? initParams.submissionService(initParams.configuration)
-            : WalletFacade.makeDefaultSubmissionService(initParams.configuration));
+            ? initParams.submissionService(configuration)
+            : WalletFacade.makeDefaultSubmissionService(configuration));
         const pendingTransactionsService = await Promise.resolve(initParams.pendingTransactionsService
-            ? initParams.pendingTransactionsService(initParams.configuration)
-            : WalletFacade.makeDefaultPendingTransactionsService(initParams.configuration));
+            ? initParams.pendingTransactionsService(configuration)
+            : WalletFacade.makeDefaultPendingTransactionsService(configuration));
         const provingService = await Promise.resolve(initParams.provingService
-            ? initParams.provingService(initParams.configuration)
-            : WalletFacade.makeDefaultProvingService(initParams.configuration));
-        const shielded = await Promise.resolve(initParams.shielded(initParams.configuration));
-        const unshielded = await Promise.resolve(initParams.unshielded(initParams.configuration));
-        const dust = await Promise.resolve(initParams.dust(initParams.configuration));
-        const clock = await Promise.resolve(initParams.clock ? initParams.clock(initParams.configuration) : Clock.systemClock);
-        const fetchBlockData = await Promise.resolve(initParams.fetchBlockData
-            ? initParams.fetchBlockData(initParams.configuration)
-            : makeDefaultBlockDataFetcher(initParams.configuration));
+            ? initParams.provingService(configuration)
+            : WalletFacade.makeDefaultProvingService(configuration));
+        const shielded = await Promise.resolve(initParams.shielded(configuration));
+        const unshielded = await Promise.resolve(initParams.unshielded(configuration));
+        const dust = await Promise.resolve(initParams.dust(configuration));
+        const clock = await Promise.resolve(initParams.clock ? initParams.clock(configuration) : Clock.systemClock);
+        const fetchBlockData = await Promise.resolve(initParams.fetchBlockData ? initParams.fetchBlockData(configuration) : makeDefaultBlockDataFetcher(configuration));
         const validationService = await Promise.resolve(initParams.validationService
-            ? initParams.validationService(initParams.configuration, { fetchBlockData, clock })
-            : makeDefaultValidationService({
+            ? initParams.validationService(configuration, { fetchBlockData, clock })
+            : makeDefaultVersionedValidationService({
                 fetchBlockData,
-                networkId: initParams.configuration.networkId,
+                networkId: configuration.networkId,
                 clock,
-            }));
-        return new WalletFacade(shielded, unshielded, dust, submissionService, pendingTransactionsService, provingService, validationService, initParams.configuration.txHistoryStorage, clock);
+            }, configuration.forks.v9));
+        return new WalletFacade(shielded, unshielded, dust, submissionService, pendingTransactionsService, provingService, validationService, configuration.txHistoryStorage, configuration.forks.v9, clock);
     }
     shielded;
     unshielded;
@@ -267,13 +437,24 @@ export class WalletFacade {
     #txHistoryStorage;
     clock;
     #pendingSubscription;
+    #protocolVersionSubscription;
+    /**
+     * The protocol version the wallets have all reached, as last observed.
+     *
+     * @remarks
+     *   `Option.none()` until the three wallets have each emitted once. A transaction stamped with `none` is never
+     *   orphaned, so an unobserved version costs a transaction nothing but the ability to be given up on early.
+     */
+    #observedProtocolVersion = new BehaviorSubject(Option.none());
+    /** Where the chain hands over from one ledger version to the next, which is what divides the two epochs. */
+    #forkVersion;
     /**
      * Constructor is private on purpose - much of initialization of the facade is potentially asynchronous, and adding
      * new parameters is a breaking change to the users Use {@link WalletFacade.init} instead
      *
      * @private
      */
-    constructor(shieldedWallet, unshieldedWallet, dustWallet, submissionService, pendingTransactionsService, provingService, validationService, txHistoryStorage, clock = Clock.systemClock) {
+    constructor(shieldedWallet, unshieldedWallet, dustWallet, submissionService, pendingTransactionsService, provingService, validationService, txHistoryStorage, forkVersion, clock = Clock.systemClock) {
         this.shielded = shieldedWallet;
         this.unshielded = unshieldedWallet;
         this.dust = dustWallet;
@@ -282,11 +463,83 @@ export class WalletFacade {
         this.provingService = provingService;
         this.validationService = validationService;
         this.#txHistoryStorage = txHistoryStorage;
+        this.#forkVersion = forkVersion;
         this.clock = clock;
         this.#pendingSubscription = this.pendingTransactionsService
             .state()
-            .pipe(concatMap((pending) => PendingTransactions.allFailed(pending)), concatMap((item) => this.revert(item.tx)))
+            .pipe(concatMap((pending) => PendingTransactions.allRejected(pending)), concatMap(async (item) => {
+            if (!(await this.reconcileFinalizedTransaction(item.tx, await this.#txHistoryStorage.getAll()))) {
+                await this.revert(item.tx, rejectionReason(item.result));
+            }
+        }))
             .subscribe();
+        // Deliberately built from the wallets' own states rather than from `state()`: `state()` includes the pending set,
+        // and orphaning writes to it, so feeding that back here would be a cycle.
+        this.#protocolVersionSubscription = combineLatest([this.shielded.state, this.unshielded.state, this.dust.state])
+            .pipe(map(([shieldedState, unshieldedState, dustState]) => lowestProtocolVersion({
+            shielded: shieldedState.protocolVersion,
+            unshielded: unshieldedState.protocolVersion,
+            dust: dustState.protocolVersion,
+        })), distinctUntilChanged(), tap((version) => this.#observedProtocolVersion.next(Option.some(version))), 
+        // Nothing fallible belongs here: this chain is the only writer of the observed version, and an orphaned
+        // transaction sync already saw included is reconciled by the pending subscription like any other verdict.
+        concatMap((version) => this.pendingTransactionsService.orphanBeyond(version)))
+            .subscribe();
+    }
+    /**
+     * The protocol version the facade is currently acting at.
+     *
+     * @remarks
+     *   The lowest the three wallets have reached, once they have all reported; the minimum supported version until then,
+     *   which is the epoch a wallet with no history belongs to. It is what a transaction the facade builds is stamped
+     *   with, and what the side of the boundary it accepts transactions from is measured against.
+     */
+    currentVersion() {
+        return Option.getOrElse(this.#observedProtocolVersion.getValue(), () => ProtocolVersion.MinSupportedVersion);
+    }
+    /** The range of protocol versions on the same side of the boundary as a given one. */
+    epochOf(version) {
+        return ProtocolVersion.epochOf(version, this.#forkVersion);
+    }
+    /** The range of protocol versions on the facade's current side of the boundary. */
+    currentEpoch() {
+        return this.epochOf(this.currentVersion());
+    }
+    /**
+     * Reads a transaction an application handed in, refusing one built on the other side of the boundary.
+     *
+     * @remarks
+     *   The enforcement point for everything that enters the facade — a transaction the wallets built, or one an
+     *   application authored and sealed with `WalletTransaction.adopt`. Only the current epoch is accepted, because a
+     *   transaction of the other one cannot be merged, proved or submitted alongside anything the facade would build for
+     *   it. Both a stranded ledger-v8 transaction after the crossing and a ledger-v9 transaction offered before it are
+     *   refused here, by name, with the versions written down.
+     * @param handle The handle to read.
+     * @returns The carried transaction.
+     * @throws {@link ProtocolVersionMismatchError} When the transaction was built on the other side of the boundary.
+     */
+    accept(handle) {
+        return Either.getOrThrowWith(WalletTransaction.unwrapWithin(handle, this.currentEpoch()), (error) => error);
+    }
+    /**
+     * Seals a transaction the facade or a wallet produced, at the version its bytes were fixed by.
+     *
+     * @remarks
+     *   The version is the caller's to state, never read from the facade here, because the two can differ: a crossing can
+     *   land while a transaction is at the prover, and what comes back is still the bytes of the ledger version that made
+     *   them. A caller sealing something it has just built passes the version it is building at; a caller sealing
+     *   something that has travelled through an await passes the version stamped on the handle it started from.
+     * @param stage How far along the building of the transaction the sealed handle is.
+     * @param transaction The transaction to seal.
+     * @param protocolVersion The version the transaction's bytes were fixed by.
+     * @returns The sealed handle.
+     */
+    seal(stage, transaction, protocolVersion) {
+        return WalletTransaction.adopt(stage, transaction, protocolVersion);
+    }
+    /** The ledger primitives the facade signs with on its current side of the boundary. */
+    authoring() {
+        return this.currentVersion() < this.#forkVersion ? v8Authoring : v9Authoring;
     }
     defaultTtl() {
         return new Date(this.clock.now().getTime() + DEFAULT_TTL_MS);
@@ -337,11 +590,21 @@ export class WalletFacade {
      * @throws {@link ValidationFetchError} If the block-data fetch fails.
      */
     async validateTransaction(tx, options) {
-        return this.validationService.validateTx(tx, options);
+        // Checked at the version the transaction says it was authored for, and never at the version the chain has since
+        // reached: well-formedness asks whether the ledger that produced these bytes would accept them, and a fork landing
+        // afterwards cannot change that answer. The transaction is read at its own epoch for the same reason.
+        return this.validationService.validateTx(Either.getOrThrowWith(WalletTransaction.unwrapWithin(tx, ProtocolVersion.epochOf(tx.protocolVersion, this.#forkVersion)), (error) => error), tx.protocolVersion, options);
     }
+    /**
+     * Merges two unproven transactions of the same epoch, or returns whichever there is.
+     *
+     * @remarks
+     *   Both are unwrapped before merging, which is where a pair from different epochs is refused: a merge across the
+     *   boundary is not a failure to compute, it is unrepresentable, and saying so is the whole point of the stamp.
+     */
     mergeUnprovenTransactions(a, b) {
         if (a && b)
-            return a.merge(b);
+            return this.seal('Unproven', this.accept(a).merge(this.accept(b)), this.currentVersion());
         return a ?? b;
     }
     async createDustActionTransaction(action, nightUtxos, nightVerifyingKey, signDustRegistration) {
@@ -390,6 +653,11 @@ export class WalletFacade {
         // on-chain with BalanceCheckOverspend. Skip for re-registration (all guaranteed UTxOs already
         // registered) since `feePayment` is 0 by design and the caller is expected to balance the fee
         // externally via `balanceUnprovenTransaction({ tokenKindsToBalance: ['dust'] })`.
+        //
+        // `registeredForDustGeneration` is the indexer's answer as of the chain's current dust epoch, so it is the one
+        // authority on which of the two a registration is. Night carried across the v8 -> v9 fork arrives with it set to
+        // `false` — the fork wipes dust generation state and the unshielded crossing carries the flag accordingly — so a
+        // re-registration on ledger-v9 is correctly treated as first-time.
         const hasUnregisteredGuaranteed = split.guaranteedUtxos.some((u) => !u.utxo.registeredForDustGeneration);
         if (isRegistration && hasUnregisteredGuaranteed) {
             const fee = await this.dust.calculateFee([txWithDustActions]);
@@ -402,7 +670,7 @@ export class WalletFacade {
         // Step 5 — Sign via the standard signRecipe pathway, which now stamps both the unshielded
         // offers and the dust registration. Signing failures also need to release the booking.
         try {
-            const signedRecipe = await this.signRecipe({ type: 'UNPROVEN_TRANSACTION', transaction: txWithDustActions }, signDustRegistration);
+            const signedRecipe = await this.signRecipe({ type: 'UNPROVEN_TRANSACTION', protocolVersion: this.currentVersion(), transaction: txWithDustActions }, signDustRegistration);
             if (signedRecipe.type !== 'UNPROVEN_TRANSACTION') {
                 throw Error('signRecipe returned unexpected recipe type for dust action transaction.');
             }
@@ -419,7 +687,7 @@ export class WalletFacade {
             this.unshielded.state,
             this.dust.state,
             this.pendingTransactionsService.state(),
-        ]).pipe(map(([shieldedState, unshieldedState, dustState, pending]) => new FacadeState(shieldedState, unshieldedState, dustState, pending)));
+        ]).pipe(map(([shieldedState, unshieldedState, dustState, pending]) => new FacadeState(shieldedState, unshieldedState, dustState, pending, this.#forkVersion)));
     }
     async waitForSyncedState() {
         const [shieldedState, unshieldedState, dustState, pending] = await Promise.all([
@@ -428,7 +696,7 @@ export class WalletFacade {
             this.dust.waitForSyncedState(),
             firstValueFrom(this.pendingTransactionsService.state()),
         ]);
-        return new FacadeState(shieldedState, unshieldedState, dustState, pending);
+        return new FacadeState(shieldedState, unshieldedState, dustState, pending, this.#forkVersion);
     }
     /**
      * Submits a finalized transaction to the network and tracks it as pending until finalized or discarded.
@@ -441,12 +709,13 @@ export class WalletFacade {
      * @throws {@link WellFormedError} — call {@link validateTransaction} first to get this error early.
      */
     async submitTransaction(tx) {
-        const identifiers = tx.identifiers();
+        const carried = this.accept(tx);
+        const identifiers = carried.identifiers();
         try {
-            await this.pendingTransactionsService.addPendingTransaction(tx);
+            await this.pendingTransactionsService.addPendingTransaction(tx, this.#observedProtocolVersion.getValue());
             // Insert before awaiting submission so the entry exists while the tx is in flight — the per-wallet sync
             // handlers' gotFinalized call clears the pending entry on confirmation.
-            const key = submitTxHistoryKey(tx);
+            const key = submitTxHistoryKey(carried);
             await this.#txHistoryStorage.gotPending({ ...key, submittedAt: this.clock.now() });
             await this.submissionService.submitTransaction(tx, 'Finalized');
             return identifiers.at(-1);
@@ -468,22 +737,19 @@ export class WalletFacade {
      * @param options - TTL for the balancing transaction, and optional subset of token kinds to balance.
      * @returns A {@link FinalizedTransactionRecipe} containing the original and balancing transactions.
      */
-    async balanceFinalizedTransaction(tx, secretKeys, options) {
-        const { shieldedSecretKeys, dustSecretKey } = secretKeys;
+    async balanceFinalizedTransaction(tx, options) {
         const { ttl, tokenKindsToBalance = 'all' } = options;
         const { shouldBalanceDust, shouldBalanceShielded, shouldBalanceUnshielded } = TokenKindsToBalance.toFlags(tokenKindsToBalance);
         // Step 1: Run unshielded and shielded balancing
         const unshieldedBalancingTx = shouldBalanceUnshielded
             ? await this.unshielded.balanceFinalizedTransaction(tx)
             : undefined;
-        const shieldedBalancingTx = shouldBalanceShielded
-            ? await this.shielded.balanceTransaction(shieldedSecretKeys, tx)
-            : undefined;
+        const shieldedBalancingTx = shouldBalanceShielded ? await this.shielded.balanceTransaction(tx) : undefined;
         // Step 2: Merge unshielded and shielded balancing
         const mergedBalancingTx = this.mergeUnprovenTransactions(shieldedBalancingTx, unshieldedBalancingTx);
         // Step 3: Conditionally add dust/fee balancing
         const dustResult = shouldBalanceDust
-            ? await this.dust.balanceTransactions(dustSecretKey, mergedBalancingTx ? [tx, mergedBalancingTx] : [tx], ttl)
+            ? await this.dust.balanceTransactions(mergedBalancingTx ? [tx, mergedBalancingTx] : [tx], ttl)
             : undefined;
         const feeBalancingTx = dustResult?.transaction;
         // Step 4: Merge fee balancing and create final recipe
@@ -493,6 +759,7 @@ export class WalletFacade {
         }
         return {
             type: 'FINALIZED_TRANSACTION',
+            protocolVersion: this.currentVersion(),
             originalTransaction: tx,
             balancingTransaction: balancingTx,
             ...(dustResult ? { blockData: dustResult.blockData } : {}),
@@ -510,14 +777,11 @@ export class WalletFacade {
      * @param options - TTL for the balancing transaction, and optional subset of token kinds to balance.
      * @returns An {@link UnboundTransactionRecipe} containing the base and optional balancing transactions.
      */
-    async balanceUnboundTransaction(tx, secretKeys, options) {
-        const { shieldedSecretKeys, dustSecretKey } = secretKeys;
+    async balanceUnboundTransaction(tx, options) {
         const { ttl, tokenKindsToBalance = 'all' } = options;
         const { shouldBalanceDust, shouldBalanceShielded, shouldBalanceUnshielded } = TokenKindsToBalance.toFlags(tokenKindsToBalance);
         // Step 1: Run unshielded and shielded balancing
-        const shieldedBalancingTx = shouldBalanceShielded
-            ? await this.shielded.balanceTransaction(shieldedSecretKeys, tx)
-            : undefined;
+        const shieldedBalancingTx = shouldBalanceShielded ? await this.shielded.balanceTransaction(tx) : undefined;
         // For unbound transactions, unshielded balancing happens in place not with a balancing transaction
         const balancedUnshieldedTx = shouldBalanceUnshielded
             ? await this.unshielded.balanceUnboundTransaction(tx)
@@ -526,7 +790,7 @@ export class WalletFacade {
         const baseTx = balancedUnshieldedTx ?? tx;
         // Step 3: Conditionally add dust/fee balancing
         const dustResult = shouldBalanceDust
-            ? await this.dust.balanceTransactions(dustSecretKey, shieldedBalancingTx ? [baseTx, shieldedBalancingTx] : [baseTx], ttl)
+            ? await this.dust.balanceTransactions(shieldedBalancingTx ? [baseTx, shieldedBalancingTx] : [baseTx], ttl)
             : undefined;
         const feeBalancingTransaction = dustResult?.transaction;
         // Step 4: Create the final balancing transaction
@@ -537,6 +801,7 @@ export class WalletFacade {
         }
         return {
             type: 'UNBOUND_TRANSACTION',
+            protocolVersion: this.currentVersion(),
             baseTransaction: baseTx,
             balancingTransaction: balancingTransaction ?? undefined,
             ...(dustResult ? { blockData: dustResult.blockData } : {}),
@@ -554,14 +819,11 @@ export class WalletFacade {
      * @param options - TTL for the balancing transaction, and optional subset of token kinds to balance.
      * @returns An {@link UnprovenTransactionRecipe} containing the balanced transaction.
      */
-    async balanceUnprovenTransaction(tx, secretKeys, options) {
-        const { shieldedSecretKeys, dustSecretKey } = secretKeys;
+    async balanceUnprovenTransaction(tx, options) {
         const { ttl, tokenKindsToBalance = 'all' } = options;
         const { shouldBalanceDust, shouldBalanceShielded, shouldBalanceUnshielded } = TokenKindsToBalance.toFlags(tokenKindsToBalance);
         // Step 1: Run unshielded and shielded balancing
-        const shieldedBalancingTx = shouldBalanceShielded
-            ? await this.shielded.balanceTransaction(shieldedSecretKeys, tx)
-            : undefined;
+        const shieldedBalancingTx = shouldBalanceShielded ? await this.shielded.balanceTransaction(tx) : undefined;
         // For unproven transactions, unshielded balancing happens in place
         const balancedUnshieldedTx = shouldBalanceUnshielded
             ? await this.unshielded.balanceUnprovenTransaction(tx)
@@ -571,14 +833,13 @@ export class WalletFacade {
         // Step 3: Merge shielded balancing into base tx if present
         const mergedTx = this.mergeUnprovenTransactions(baseTx, shieldedBalancingTx);
         // Step 4: Conditionally add dust/fee balancing
-        const dustResult = shouldBalanceDust
-            ? await this.dust.balanceTransactions(dustSecretKey, [mergedTx], ttl)
-            : undefined;
+        const dustResult = shouldBalanceDust ? await this.dust.balanceTransactions([mergedTx], ttl) : undefined;
         const feeBalancingTx = dustResult?.transaction;
         // Step 5: Merge fee balancing if present
         const balancedTx = this.mergeUnprovenTransactions(mergedTx, feeBalancingTx);
         return {
             type: 'UNPROVEN_TRANSACTION',
+            protocolVersion: this.currentVersion(),
             transaction: balancedTx,
             ...(dustResult ? { blockData: dustResult.blockData } : {}),
         };
@@ -589,14 +850,16 @@ export class WalletFacade {
             switch (recipe.type) {
                 case 'FINALIZED_TRANSACTION': {
                     const finalizedBalancing = await this.finalizeTransaction(recipe.balancingTransaction);
-                    return recipe.originalTransaction.merge(finalizedBalancing);
+                    return this.seal('Finalized', this.accept(recipe.originalTransaction).merge(this.accept(finalizedBalancing)), recipe.originalTransaction.protocolVersion);
                 }
                 case 'UNBOUND_TRANSACTION': {
                     const finalizedBalancingTx = recipe.balancingTransaction
                         ? await this.finalizeTransaction(recipe.balancingTransaction)
                         : undefined;
-                    const finalizedTransaction = recipe.baseTransaction.bind();
-                    return finalizedBalancingTx ? finalizedTransaction.merge(finalizedBalancingTx) : finalizedTransaction;
+                    const finalizedTransaction = this.accept(recipe.baseTransaction).bind();
+                    return this.seal('Finalized', finalizedBalancingTx
+                        ? finalizedTransaction.merge(this.accept(finalizedBalancingTx))
+                        : finalizedTransaction, recipe.baseTransaction.protocolVersion);
                 }
                 case 'UNPROVEN_TRANSACTION': {
                     return await this.finalizeTransaction(recipe.transaction);
@@ -604,7 +867,7 @@ export class WalletFacade {
             }
         })
             .then(async (finalizedTx) => {
-            await this.pendingTransactionsService.addPendingTransaction(finalizedTx);
+            await this.pendingTransactionsService.addPendingTransaction(finalizedTx, Option.some(finalizedTx.protocolVersion));
             return finalizedTx;
         });
     }
@@ -615,6 +878,7 @@ export class WalletFacade {
                 const withDustSig = await this.#signDustRegistrationIfPresent(signedBalancingTx, signSegment);
                 return {
                     type: 'FINALIZED_TRANSACTION',
+                    protocolVersion: recipe.protocolVersion,
                     originalTransaction: recipe.originalTransaction,
                     balancingTransaction: withDustSig,
                     ...(recipe.blockData ? { blockData: recipe.blockData } : {}),
@@ -627,6 +891,7 @@ export class WalletFacade {
                 const signedBaseTx = await this.signUnboundTransaction(recipe.baseTransaction, signSegment);
                 return {
                     type: 'UNBOUND_TRANSACTION',
+                    protocolVersion: recipe.protocolVersion,
                     baseTransaction: signedBaseTx,
                     balancingTransaction: signedBalancingTx,
                     ...(recipe.blockData ? { blockData: recipe.blockData } : {}),
@@ -637,6 +902,7 @@ export class WalletFacade {
                 const withDustSig = await this.#signDustRegistrationIfPresent(signedTx, signSegment);
                 return {
                     type: 'UNPROVEN_TRANSACTION',
+                    protocolVersion: recipe.protocolVersion,
                     transaction: withDustSig,
                     ...(recipe.blockData ? { blockData: recipe.blockData } : {}),
                 };
@@ -644,7 +910,7 @@ export class WalletFacade {
         }
     }
     async #signDustRegistrationIfPresent(tx, signSegment) {
-        const intent = tx.intents?.get(1);
+        const intent = this.accept(tx).intents?.get(1);
         const registrations = intent?.dustActions?.registrations ?? [];
         if (!intent || registrations.length === 0) {
             return tx;
@@ -658,11 +924,34 @@ export class WalletFacade {
     async signUnboundTransaction(tx, signSegment) {
         return await this.unshielded.signUnboundTransaction(tx, signSegment);
     }
+    /**
+     * Proves and binds an unproven transaction, and records it as pending.
+     *
+     * @remarks
+     *   Proved at the version stamped on the transaction itself, which is the version that fixed its bytes, and sealed at
+     *   that same version: proving is a long await, so the wallets can move under it, and neither the prover a
+     *   transaction is routed to nor the stamp it comes back with may be decided by where they have moved to.
+     *
+     *   Where they have moved to decides one thing only, and it is decided again once the proof is back: a crossing while
+     *   the transaction was in flight leaves it belonging to an epoch the wallets have left, and no chain they are on can
+     *   include it. Such a transaction is refused rather than sealed, and nothing is recorded as pending for it — a
+     *   pending entry would only wait out a TTL for an inclusion that cannot happen — while the reservations it made in
+     *   the three wallets are given back like those of any other failure here.
+     * @param tx The unproven transaction.
+     * @returns The finalized transaction, stamped with the version it was authored at.
+     * @throws {@link ProtocolVersionMismatchError} When the wallets left the transaction's epoch while it was being
+     *   proved, or were never in it.
+     */
     async finalizeTransaction(tx) {
         try {
-            const unboundTx = await this.provingService.prove(tx);
-            const finalizedTx = unboundTx.bind();
-            await this.pendingTransactionsService.addPendingTransaction(finalizedTx);
+            // Named as the prover's input rather than its output: the router hands the transaction to the prover registered
+            // for the version it was authored at, and what comes back is that ledger version's unbound transaction.
+            const unboundTx = await this.provingService.prove(this.accept(tx), tx.protocolVersion);
+            // Read again on the far side of the proof: the epoch is the one thing about the transaction that a crossing
+            // during proving can change, and this is where it is caught.
+            this.accept(tx);
+            const finalizedTx = this.seal('Finalized', unboundTx.bind(), tx.protocolVersion);
+            await this.pendingTransactionsService.addPendingTransaction(finalizedTx, Option.some(finalizedTx.protocolVersion));
             return finalizedTx;
         }
         catch (error) {
@@ -679,12 +968,11 @@ export class WalletFacade {
         return await this.dust.calculateFee([tx]);
     }
     /** Calculates the total fee for the given transaction plus the fee of the balancing transaction. */
-    async estimateTransactionFee(tx, secretKey, options) {
+    async estimateTransactionFee(tx, options) {
         const ttl = options?.ttl ?? this.defaultTtl();
-        return await this.dust.estimateFee(secretKey, [tx], ttl, options?.currentTime);
+        return await this.dust.estimateFee([tx], ttl, options?.currentTime);
     }
-    async transferTransaction(outputs, secretKeys, options) {
-        const { shieldedSecretKeys, dustSecretKey } = secretKeys;
+    async transferTransaction(outputs, options) {
         const { ttl, payFees = true } = options;
         const unshieldedOutputs = outputs
             .filter((output) => output.type === 'unshielded')
@@ -693,17 +981,16 @@ export class WalletFacade {
         if (unshieldedOutputs.length === 0 && shieldedOutputs.length === 0) {
             throw Error('At least one shielded or unshielded output is required.');
         }
-        const shieldedTx = shieldedOutputs.length > 0
-            ? await this.shielded.transferTransaction(shieldedSecretKeys, shieldedOutputs)
-            : undefined;
+        const shieldedTx = shieldedOutputs.length > 0 ? await this.shielded.transferTransaction(shieldedOutputs) : undefined;
         const unshieldedTx = unshieldedOutputs.length > 0 ? await this.unshielded.transferTransaction(unshieldedOutputs, ttl) : undefined;
         const mergedTxs = this.mergeUnprovenTransactions(shieldedTx, unshieldedTx);
         // Add fee payment
-        const dustResult = payFees ? await this.dust.balanceTransactions(dustSecretKey, [mergedTxs], ttl) : undefined;
+        const dustResult = payFees ? await this.dust.balanceTransactions([mergedTxs], ttl) : undefined;
         const feeBalancingTx = dustResult?.transaction;
         const finalTx = this.mergeUnprovenTransactions(mergedTxs, feeBalancingTx);
         return {
             type: 'UNPROVEN_TRANSACTION',
+            protocolVersion: this.currentVersion(),
             transaction: finalTx,
             ...(dustResult ? { blockData: dustResult.blockData } : {}),
         };
@@ -722,9 +1009,12 @@ export class WalletFacade {
             ...utxo,
             ctime: meta.ctime,
             registeredForDustGeneration: meta.registeredForDustGeneration,
-        })), (utxosWithMeta) => dustState.estimateDustGeneration(utxosWithMeta, now), (estimatedUtxos) => dustState.capabilities.coinsAndBalances.splitNightUtxos(estimatedUtxos), (split) => split.guaranteed);
-        const fakeSigningKey = ledger.sampleSigningKey();
-        const fakeVerifyingKey = ledger.signatureVerifyingKey(fakeSigningKey);
+        })), (utxosWithMeta) => dustState.estimateDustGeneration(utxosWithMeta, now), (estimatedUtxos) => dustState.splitNightUtxos(estimatedUtxos), (split) => split.guaranteed);
+        const authoring = this.authoring();
+        // Type cast required because: a signing key belongs to one ledger version's runtime and the two are nominally
+        // distinct, so the epoch's own primitives are the only things that may touch it; it never leaves this block.
+        const fakeSigningKey = authoring.sampleSigningKey();
+        const fakeVerifyingKey = authoring.signatureVerifyingKey(fakeSigningKey);
         // Use the legacy dust-only construction path here so estimation does NOT book real UTxOs in the
         // unshielded wallet state. (The race-fix path in createDustActionTransaction books on purpose;
         // estimation is meant to be observation-only.)
@@ -734,22 +1024,20 @@ export class WalletFacade {
             ctime: meta.ctime,
             registeredForDustGeneration: meta.registeredForDustGeneration,
         })), fakeVerifyingKey, dustState.address);
-        const intent = fakeUnsignedTx.intents?.get(1);
+        const intent = this.accept(fakeUnsignedTx).intents?.get(1);
         if (!intent) {
             throw Error('Dust generation transaction is missing intent segment 1.');
         }
-        const signatureData = intent.signatureData(1);
-        const signature = ledger.signData(fakeSigningKey, signatureData);
+        const signature = authoring.signData(fakeSigningKey, intent.signatureData(1));
         const fakeSignedTx = await this.dust.addDustGenerationSignature(fakeUnsignedTx, signature);
-        const finalizedFakeTx = fakeSignedTx.mockProve().bind();
+        const finalizedFakeTx = this.seal('Finalized', this.accept(fakeSignedTx).mockProve().bind(), this.currentVersion());
         const fee = await this.calculateTransactionFee(finalizedFakeTx);
         return {
             fee,
             dustGenerationEstimations,
         };
     }
-    async initSwap(desiredInputs, desiredOutputs, secretKeys, options) {
-        const { shieldedSecretKeys, dustSecretKey } = secretKeys;
+    async initSwap(desiredInputs, desiredOutputs, options) {
         const { ttl, payFees = false } = options;
         const { shielded: shieldedInputs, unshielded: unshieldedInputs } = desiredInputs;
         const shieldedOutputs = desiredOutputs
@@ -764,7 +1052,7 @@ export class WalletFacade {
             throw Error('At least one shielded or unshielded swap is required.');
         }
         const shieldedTx = hasShieldedPart && shieldedInputs !== undefined
-            ? await this.shielded.initSwap(shieldedSecretKeys, shieldedInputs, shieldedOutputs)
+            ? await this.shielded.initSwap(shieldedInputs, shieldedOutputs)
             : undefined;
         const unshieldedTx = hasUnshieldedPart && unshieldedInputs !== undefined
             ? await this.unshielded.initSwap(unshieldedInputs, unshieldedOutputs, ttl)
@@ -773,11 +1061,12 @@ export class WalletFacade {
         if (!combinedTx) {
             throw Error('Unexpected transaction state.');
         }
-        const dustResult = payFees ? await this.dust.balanceTransactions(dustSecretKey, [combinedTx], ttl) : undefined;
+        const dustResult = payFees ? await this.dust.balanceTransactions([combinedTx], ttl) : undefined;
         const feeBalancingTx = dustResult?.transaction;
         const finalTx = this.mergeUnprovenTransactions(combinedTx, feeBalancingTx);
         return {
             type: 'UNPROVEN_TRANSACTION',
+            protocolVersion: this.currentVersion(),
             transaction: finalTx,
             ...(dustResult ? { blockData: dustResult.blockData } : {}),
         };
@@ -790,6 +1079,7 @@ export class WalletFacade {
         const dustRegistrationTx = await this.createDustActionTransaction({ type: 'registration', dustReceiverAddress: receiverAddress }, nightUtxos, nightVerifyingKey, signDustRegistration);
         return {
             type: 'UNPROVEN_TRANSACTION',
+            protocolVersion: this.currentVersion(),
             transaction: dustRegistrationTx,
         };
     }
@@ -814,37 +1104,111 @@ export class WalletFacade {
         const dustDeregistrationTx = await this.createDustActionTransaction({ type: 'deregistration' }, nightUtxos, nightVerifyingKey, signDustRegistration);
         return {
             type: 'UNPROVEN_TRANSACTION',
+            protocolVersion: this.currentVersion(),
             transaction: dustDeregistrationTx,
         };
     }
-    async revert(txOrRecipe) {
+    async revert(txOrRecipe, reason) {
         // avoid instanceof check
         const transactionsToRevert = BalancingRecipe.isRecipe(txOrRecipe)
             ? BalancingRecipe.getTransactions(txOrRecipe)
             : [txOrRecipe];
-        await Promise.all(transactionsToRevert.map((tx) => this.revertTransaction(tx)));
+        await Promise.all(transactionsToRevert.map((tx) => this.revertTransaction(tx, reason)));
+    }
+    /**
+     * The finalized entry recording `tx`, if sync has written one, even under the hash aggregation gave it on-chain. A
+     * transaction whose stamp no epoch can read has no entry, rather than an error, so a verdict on it still resolves.
+     */
+    finalizedEntryFor(tx, history) {
+        return Option.match(Either.getRight(WalletTransaction.unwrapWithin(tx, this.epochOf(tx.protocolVersion))), {
+            onNone: () => undefined,
+            onSome: (carried) => {
+                const key = submitTxHistoryKey(carried);
+                return history.find((entry) => isFinalizedWalletEntry(entry) && TransactionHistoryStorage.coversTransaction(entry, key));
+            },
+        });
+    }
+    /** Sync can record inclusion before the independent pending-status poller observes it. */
+    async reconcileFinalizedTransaction(tx, history) {
+        const entry = this.finalizedEntryFor(tx, history);
+        if (entry === undefined)
+            return false;
+        // Included failures still need their unexecuted coin reservations released.
+        if (entry.status === 'FAILURE' || entry.status === 'PARTIAL_SUCCESS') {
+            await this.revertTransaction(tx);
+        }
+        else {
+            await this.pendingTransactionsService.clear(tx);
+        }
+        return true;
     }
-    async revertTransaction(tx) {
+    async revertTransaction(tx, reason) {
         await Promise.all([
             this.shielded.revertTransaction(tx),
             this.unshielded.revertTransaction(tx),
             this.dust.revertTransaction(tx),
         ]).then(async () => {
+            // Reverting is total over the stages: a transaction at any of them may have booked coins, and the pending set
+            // recognises only the finalized ones. Narrowing rather than casting is what says so.
             await this.pendingTransactionsService.clear(tx);
-            const key = revertTxHistoryKey(tx);
+            // Read at the epoch the transaction was built for, not the one the facade now acts at. A verdict on a
+            // transaction submitted before a protocol boundary can only arrive after it — a chain rejection, a TTL run out,
+            // or the wallet giving up on bytes that can never be included — and by then the facade has crossed. The pending
+            // entry that verdict has to land on was written by this same session before the crossing, and it is the only
+            // record an application has that the transaction will never be included; keying it against the current epoch
+            // would leave it saying `pending` for the rest of the session. The stamp is what chooses the reader, which is
+            // what the stamp is for.
+            const key = Option.match(Either.getRight(WalletTransaction.unwrapWithin(tx, this.epochOf(tx.protocolVersion))), { onNone: () => undefined, onSome: revertTxHistoryKey });
             if (key !== undefined) {
-                await this.#txHistoryStorage.gotRejected({ ...key, rejectedAt: this.clock.now() });
+                await this.#txHistoryStorage.gotRejected({
+                    ...key,
+                    rejectedAt: this.clock.now(),
+                    ...(reason !== undefined ? { reason } : {}),
+                });
             }
         });
     }
-    async start(shieldedSecretKeys, dustSecretKey) {
+    /**
+     * Starts the wallets and their background synchronization.
+     *
+     * @remarks
+     *   Seeds, not key objects. A seed is the only key material that crosses a protocol boundary — every ledger version
+     *   derives its own keys from the same seed and arrives at the same identity — so a wallet started from seeds can
+     *   follow the chain across a fork, and one started from key objects of a single ledger version cannot. Derive them
+     *   once with `WalletSeeds.fromMasterSeed` and hand them over.
+     *
+     *   {@link FacadeKeysByEpoch} is the escape hatch for a caller that will not part with a seed. It requires **both**
+     *   ledger versions' key objects, because a wallet holding one side could not read the other side of the chain, and
+     *   it costs the caller an import of both ledger packages and the same derivation performed twice. A seed costs
+     *   neither.
+     * @example
+     *   ```typescript
+     *   await facade.start(WalletSeeds.fromMasterSeed(masterSeed));
+     *   ```;
+     *
+     * @param material The three wallets' seeds, or both ledger versions' key objects.
+     * @param options `manualSync` leaves the dust wallet unstarted in the background; drive it explicitly with
+     *   {@link doSync} instead (requires a dust wallet built with the projections sync service, see
+     *   `makeEventLessSyncService`).
+     */
+    async start(material, options = {}) {
+        const keys = v9KeysOf(material);
         await Promise.all([
-            this.shielded.start(shieldedSecretKeys),
+            this.shielded.start(keys.shielded),
             this.unshielded.start(),
-            this.dust.start(dustSecretKey),
+            !options.manualSync ? this.dust.start(keys.dust) : undefined,
             this.pendingTransactionsService.start(),
         ]);
     }
+    /**
+     * Runs a single dust synchronization pass and resolves when it completes. Only the dust wallet supports manual sync;
+     * the shielded and unshielded wallets keep syncing in the background via {@link start}.
+     *
+     * @param material The same material {@link start} was given.
+     */
+    async doSync(material) {
+        await this.dust.stepSync(v9KeysOf(material).dust);
+    }
     async stop() {
         await Promise.all([
             this.shielded.stop(),
@@ -853,6 +1217,7 @@ export class WalletFacade {
             this.submissionService.close(),
             this.pendingTransactionsService.stop(),
             Promise.resolve(this.#pendingSubscription?.unsubscribe()),
+            Promise.resolve(this.#protocolVersionSubscription?.unsubscribe()),
         ]);
     }
     async queryTxHistoryByHash(hash) {