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

package/dist/index.d.ts

@@ -1,17 +1,19 @@
-import * as ledger from '@midnightntwrk/ledger-v9';
+import * as ledgerV9 from '@midnightntwrk/ledger-v9';
 import { type DefaultSubmissionConfiguration, type SubmissionService } from '@midnight-ntwrk/wallet-sdk-capabilities';
-import { type DefaultProvingConfiguration, type ProvingService, type UnboundTransaction } from '@midnight-ntwrk/wallet-sdk-capabilities/proving';
+import { type AnyVersionUnboundTransaction, type AnyVersionUnprovenTransaction, type DefaultProvingConfiguration, type VersionedProvingService } from '@midnight-ntwrk/wallet-sdk-capabilities/proving';
 import { type DefaultDustConfiguration, type DustWalletAPI, type DustWalletState } from '@midnight-ntwrk/wallet-sdk-dust-wallet';
-import { type AnyTransaction, type CoinsAndBalances as DustCoinsAndBalances } from '@midnight-ntwrk/wallet-sdk-dust-wallet/v1';
+import { type CoinsAndBalances as DustCoinsAndBalances } from '@midnight-ntwrk/wallet-sdk-dust-wallet/v2';
 import { type DefaultShieldedConfiguration, type ShieldedWalletAPI, type ShieldedWalletState } from '@midnight-ntwrk/wallet-sdk-shielded';
 import type { DefaultUnshieldedConfiguration, SignSegment, UnshieldedWalletAPI } from '@midnight-ntwrk/wallet-sdk-unshielded-wallet';
 import { type UnshieldedWalletState } from '@midnight-ntwrk/wallet-sdk-unshielded-wallet';
 import { Clock } from '@midnight-ntwrk/wallet-sdk-utilities';
-import { Schema } from 'effect';
-import { TransactionHistoryStorage } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { type DateTime, Option, Schema } from 'effect';
+import { type AnyTx, type FinalizedTx, ProtocolVersion, TransactionHistoryStorage, type UnboundTx, type UnprovenTx } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import * as ledgerV8 from '@midnight-ntwrk/ledger-v8';
+import { type WalletSeeds } from '@midnight-ntwrk/wallet-sdk-hd';
 import { type Observable } from 'rxjs';
 import { type DefaultPendingTransactionsServiceConfiguration, PendingTransactions, type PendingTransactionsService } from '@midnight-ntwrk/wallet-sdk-capabilities';
-import { type BlockData, type BlockDataFetcher, type ValidateTxOptions, ValidationFetchError, type ValidationService, WellFormedError, type WellFormedStrictnessFlags } from '@midnight-ntwrk/wallet-sdk-capabilities/validation';
+import { type AnyLedgerParameters, type AnyVersionValidatableTransaction, type BlockData, type BlockDataFetcher, type ValidateTxOptions, ValidationFetchError, type VersionedValidationService, WellFormedError, type WellFormedStrictnessFlags } from '@midnight-ntwrk/wallet-sdk-capabilities/validation';
 import { type DustAddress, type ShieldedAddress, type UnshieldedAddress } from '@midnight-ntwrk/wallet-sdk-address-format';
 /**
  * Full entry schema for transaction history. The common entry data and wallet-specific sections (`shielded`,
@@ -101,6 +103,15 @@ export type FinalizedWalletEntry = WalletEntry & {
 export declare const isPendingWalletEntry: (entry: WalletEntry) => entry is PendingWalletEntry;
 export declare const isFinalizedWalletEntry: (entry: WalletEntry) => entry is FinalizedWalletEntry;
 export declare function mergeWalletEntries(existing: WalletEntry, incoming: WalletEntry): WalletEntry;
+/**
+ * Every transaction shape the facade will take from a caller.
+ *
+ * @remarks
+ *   Now a handle: what an application carries between facade calls is sealed together with the protocol version it was
+ *   built at, so it can be routed rather than guessed about. The name is kept because it is what these signatures have
+ *   always been stated in terms of.
+ */
+export type AnyTransaction = AnyTx;
 type TokenKind = 'dust' | 'shielded' | 'unshielded';
 type TokenKindsToBalance = 'all' | TokenKind[];
 declare const TokenKindsToBalance: {
@@ -113,28 +124,34 @@ declare const TokenKindsToBalance: {
 };
 export type FinalizedTransactionRecipe = {
     type: 'FINALIZED_TRANSACTION';
-    originalTransaction: ledger.FinalizedTransaction;
-    balancingTransaction: ledger.UnprovenTransaction;
-    blockData?: BlockData;
+    /** The protocol version this recipe was built for, and so the version its parts have to be proved at. */
+    protocolVersion: ProtocolVersion.ProtocolVersion;
+    originalTransaction: FinalizedTx;
+    balancingTransaction: UnprovenTx;
+    blockData?: BlockData<AnyLedgerParameters>;
 };
 export type UnboundTransactionRecipe = {
     type: 'UNBOUND_TRANSACTION';
-    baseTransaction: UnboundTransaction;
-    balancingTransaction?: ledger.UnprovenTransaction | undefined;
-    blockData?: BlockData;
+    /** The protocol version this recipe was built for, and so the version its parts have to be proved at. */
+    protocolVersion: ProtocolVersion.ProtocolVersion;
+    baseTransaction: UnboundTx;
+    balancingTransaction?: UnprovenTx | undefined;
+    blockData?: BlockData<AnyLedgerParameters>;
 };
 export type UnprovenTransactionRecipe = {
     type: 'UNPROVEN_TRANSACTION';
-    transaction: ledger.UnprovenTransaction;
-    blockData?: BlockData;
+    /** The protocol version this recipe was built for, and so the version its parts have to be proved at. */
+    protocolVersion: ProtocolVersion.ProtocolVersion;
+    transaction: UnprovenTx;
+    blockData?: BlockData<AnyLedgerParameters>;
 };
 export type BalancingRecipe = FinalizedTransactionRecipe | UnboundTransactionRecipe | UnprovenTransactionRecipe;
 export declare const BalancingRecipe: {
     isRecipe: (value: unknown) => value is BalancingRecipe;
-    getTransactions: (recipe: BalancingRecipe) => readonly AnyTransaction[];
+    getTransactions: (recipe: BalancingRecipe) => readonly AnyTx[];
 };
 export interface TokenTransfer<AddressType extends ShieldedAddress | UnshieldedAddress> {
-    type: ledger.RawTokenType;
+    type: ledgerV9.RawTokenType;
     receiverAddress: AddressType;
     amount: bigint;
 }
@@ -148,25 +165,191 @@ export type UnshieldedTokenTransfer = {
 };
 export type CombinedTokenTransfer = ShieldedTokenTransfer | UnshieldedTokenTransfer;
 export type CombinedSwapInputs = {
-    shielded?: Record<ledger.RawTokenType, bigint>;
-    unshielded?: Record<ledger.RawTokenType, bigint>;
+    shielded?: Record<ledgerV9.RawTokenType, bigint>;
+    unshielded?: Record<ledgerV9.RawTokenType, bigint>;
 };
 export type CombinedSwapOutputs = CombinedTokenTransfer;
 export type TransactionIdentifier = string;
 export type UtxoWithMeta = {
-    utxo: ledger.Utxo;
+    utxo: ledgerV9.Utxo;
     meta: {
         ctime: Date;
         registeredForDustGeneration: boolean;
     };
 };
+/** The protocol version each of the three wallets has reached. */
+export type WalletProtocolVersions = Readonly<{
+    shielded: ProtocolVersion.ProtocolVersion;
+    unshielded: ProtocolVersion.ProtocolVersion;
+    dust: ProtocolVersion.ProtocolVersion;
+}>;
+/**
+ * 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 declare const lowestProtocolVersion: (versions: WalletProtocolVersions) => ProtocolVersion.ProtocolVersion;
+/**
+ * One ledger version's key objects per side of a protocol boundary.
+ *
+ * @remarks
+ *   The escape hatch for a caller that holds key objects rather than a seed. Both sides are required: key objects belong
+ *   to one ledger version's runtime and neither can be derived from the other, so a facade given one side alone would
+ *   hold wallets that cannot read half the chain. That is the shape seeds exist to avoid, and a product with one side
+ *   optional would reintroduce it.
+ */
+export type FacadeKeysByEpoch = Readonly<{
+    /** The ledger-v8's key objects. */
+    v8: Readonly<{
+        shielded: ledgerV8.ZswapSecretKeys;
+        dust: ledgerV8.DustSecretKey;
+    }>;
+    /** The ledger-v9's key objects. */
+    v9: Readonly<{
+        shielded: ledgerV9.ZswapSecretKeys;
+        dust: ledgerV9.DustSecretKey;
+    }>;
+}>;
+/** What the facade will start its wallets from: seeds, or both ledger versions' key objects. */
+export type FacadeStartMaterial = WalletSeeds | FacadeKeysByEpoch;
+/** How the wallets are started. */
+export type FacadeStartOptions = Readonly<{
+    /**
+     * Leaves the dust wallet unstarted in the background, to be driven a step at a time with `doSync`.
+     *
+     * @remarks
+     *   Requires a dust wallet built with the projections sync service; see `makeEventLessSyncService`.
+     */
+    manualSync?: boolean;
+}>;
+/** Which of the three wallets a reading is about. */
+export type WalletKind = keyof WalletProtocolVersions;
+/**
+ * Whether the three wallets agree about which side of a protocol boundary the chain is on.
+ *
+ * @remarks
+ *   `Settled` is the ordinary state, and says which protocol version the facade is acting at. `Crossing` is the window
+ *   around a fork during which the wallets disagree: each one learns of the change when its own synchronization reaches
+ *   it, so for a while some have crossed and some have not. Nothing the facade builds during that window can span the
+ *   boundary, so it stays bound to the version the laggards are still on — which is what `from` reports, and what
+ *   `activeProtocolVersion` answers.
+ *
+ *   A difference in version _within_ one epoch is not a crossing: two versions on the same side of the boundary are the
+ *   same ledger version, and a wallet lagging there is ordinary synchronization.
+ */
+export type ProtocolPhase = Readonly<{
+    _tag: 'Settled';
+    version: ProtocolVersion.ProtocolVersion;
+}> | Readonly<{
+    _tag: 'Crossing';
+    /** The version the facade is still bound to: the epoch the wallets that have not crossed are in. */
+    from: ProtocolVersion.ProtocolVersion;
+    /** The version the wallets that have crossed have reached. */
+    to: ProtocolVersion.ProtocolVersion;
+    /** The wallets still on the near side, in a fixed order, so an application can say what it is waiting for. */
+    behind: readonly WalletKind[];
+}>;
+/**
+ * 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 declare const protocolPhaseOf: (versions: WalletProtocolVersions, forkVersion: ProtocolVersion.ProtocolVersion) => ProtocolPhase;
+/**
+ * What has become of a transaction the wallet submitted.
+ *
+ * @remarks
+ *   Tagged rather than a status string, and deliberately: `Orphaned` and `Rejected` are different facts about the world
+ *   and the difference matters to what an application should do next. A rejection is the chain's verdict — the node saw
+ *   the transaction and refused it. An orphaned transaction has no verdict at all and never will: its bytes were
+ *   authored under a protocol version the chain has moved past, and nothing can include them afterwards. The wallet has
+ *   already unbooked its coins and recorded the rejection either way; what differs is what an application can tell a
+ *   user, and whether re-submitting the same bytes could ever help.
+ */
+export type PendingStatus = Readonly<{
+    _tag: 'Submitted';
+}> | Readonly<{
+    _tag: 'Confirmed';
+    segments: readonly Readonly<{
+        id: number;
+        success: boolean;
+    }>[];
+}> | Readonly<{
+    _tag: 'Rejected';
+    segments: readonly Readonly<{
+        id: number;
+        success: boolean;
+    }>[];
+}> | Readonly<{
+    _tag: 'Orphaned';
+    /** The protocol version the transaction was authored for. */
+    authoredFor: ProtocolVersion.ProtocolVersion;
+    /** The protocol version the chain had reached when the wallet gave up on it. */
+    chainNow: ProtocolVersion.ProtocolVersion;
+}>;
+/** A transaction the wallet has submitted and the chain has not finished answering for. */
+export type PendingTransaction = Readonly<{
+    /** The transaction itself, as the handle an application carries. */
+    transaction: FinalizedTx;
+    /** When the wallet recorded it as pending. */
+    submittedAt: DateTime.Utc;
+    /**
+     * The protocol version it was authored for, when the wallet had observed one.
+     *
+     * @remarks
+     *   `Option.none()` means the wallet never learned which version it was authored against. Such a transaction is never
+     *   orphaned — an unobserved version is not evidence of anything.
+     */
+    authoredFor: Option.Option<ProtocolVersion.ProtocolVersion>;
+    /** What has become of it. See {@link PendingStatus}. */
+    status: PendingStatus;
+}>;
+/**
+ * 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 declare const pendingTransactionsOf: (pending: PendingTransactions.PendingTransactions<FinalizedTx>) => readonly PendingTransaction[];
 export declare class FacadeState {
+    #private;
     readonly shielded: ShieldedWalletState;
     readonly unshielded: UnshieldedWalletState;
     readonly dust: DustWalletState;
-    readonly pending: PendingTransactions.PendingTransactions<ledger.FinalizedTransaction>;
+    readonly pending: readonly PendingTransaction[];
+    /** The protocol version each of the three wallets has reached. */
+    get protocolVersion(): WalletProtocolVersions;
+    /**
+     * 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(): ProtocolVersion.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(): ProtocolPhase;
     get isSynced(): boolean;
-    constructor(shielded: ShieldedWalletState, unshielded: UnshieldedWalletState, dust: DustWalletState, pending: PendingTransactions.PendingTransactions<ledger.FinalizedTransaction>);
+    constructor(shielded: ShieldedWalletState, unshielded: UnshieldedWalletState, dust: DustWalletState, pending: PendingTransactions.PendingTransactions<FinalizedTx>, forkVersion?: ProtocolVersion.ProtocolVersion);
 }
 /**
  * Clock abstraction for obtaining the current time. By default, the facade uses the system clock
@@ -205,41 +388,108 @@ export type FetchTermsAndConditionsConfiguration = {
         indexerWsUrl?: string;
     };
 };
-export type DefaultConfiguration = DefaultUnshieldedConfiguration & DefaultShieldedConfiguration & DefaultDustConfiguration & DefaultSubmissionConfiguration & DefaultPendingTransactionsServiceConfiguration & Partial<DefaultProvingConfiguration>;
+/**
+ * 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 declare const DefaultForkSchedule: ProtocolVersion.ForkSchedule;
+/** What the three wallets and the default services are built from, as the wallet packages take it. */
+type WalletsConfiguration = DefaultUnshieldedConfiguration & DefaultShieldedConfiguration & DefaultDustConfiguration & DefaultSubmissionConfiguration & DefaultPendingTransactionsServiceConfiguration & DefaultProvingConfiguration;
+/**
+ * The configuration {@link WalletFacade.init} takes: what the three wallets and the default services are built from.
+ *
+ * @remarks
+ *   The one difference from the wallets' own configurations is that `forks` may be left out — see
+ *   {@link DefaultForkSchedule} for what is then preset, and {@link ResolvedConfiguration} for what a factory is handed.
+ */
+export type DefaultConfiguration = Omit<WalletsConfiguration, 'forks'> & {
+    /**
+     * Where each ledger version begins on this chain — see {@link ProtocolVersion.ForkSchedule}. Left out, the facade
+     * presets {@link DefaultForkSchedule}.
+     */
+    forks?: ProtocolVersion.ForkSchedule;
+};
+/**
+ * A {@link DefaultConfiguration} with what the facade presets filled in: `forks` is always present, the schedule the
+ * configuration named or {@link DefaultForkSchedule}.
+ *
+ * @remarks
+ *   What every factory in {@link InitParams} is handed, so that a wallet can be built from it directly: the wallet
+ *   packages require `forks`, and this is what lets `shielded: (config) => ShieldedWallet(config)` compile. Code
+ *   outside a factory gets the same from {@link WalletFacade.resolveConfiguration}.
+ * @typeParam TConfig The configuration as given, which may extend {@link DefaultConfiguration} with settings of its own.
+ */
+export type ResolvedConfiguration<TConfig extends DefaultConfiguration = DefaultConfiguration> = TConfig & {
+    forks: ProtocolVersion.ForkSchedule;
+};
 type MaybePromise<T> = T | Promise<T>;
 /**
  * Parameters object for {@link WalletFacade.init}. It features configuration and bunch of initializers for the wallets
  * and services, all of them are in a form of a function that takes the configuration and returns proper implementation,
  * either synchronously or wrapped in a Promise. Services are optional to provide ({@link WalletFacade.init} will provide
- * default implementations), but all 3 wallets: shielded, unshielded and Dust one need to be present
+ * default implementations), but all 3 wallets: shielded, unshielded and Dust one need to be present.
  */
 export type InitParams<TConfig extends DefaultConfiguration> = {
     configuration: TConfig;
     /** Optional factory for the clock abstraction. Defaults to system clock (`() => new Date()`). */
-    clock?: (config: TConfig) => MaybePromise<Clock.Clock>;
-    submissionService?: (config: TConfig) => MaybePromise<SubmissionService<ledger.FinalizedTransaction>>;
-    pendingTransactionsService?: (config: TConfig) => MaybePromise<PendingTransactionsService<ledger.FinalizedTransaction>>;
-    provingService?: (config: TConfig) => MaybePromise<ProvingService<UnboundTransaction>>;
+    clock?: (config: ResolvedConfiguration<TConfig>) => MaybePromise<Clock.Clock>;
+    submissionService?: (config: ResolvedConfiguration<TConfig>) => MaybePromise<SubmissionService<FinalizedTx>>;
+    pendingTransactionsService?: (config: ResolvedConfiguration<TConfig>) => MaybePromise<PendingTransactionsService<FinalizedTx>>;
+    provingService?: (config: ResolvedConfiguration<TConfig>) => MaybePromise<VersionedProvingService<AnyVersionUnboundTransaction, AnyVersionUnprovenTransaction>>;
     /**
      * Optional factory for the block-data fetcher used by validation. Defaults to an HTTP indexer-backed fetcher built
      * from `configuration.indexerClientConnection`. Override for simulator-based tests with
      * `makeSimulatorBlockDataFetcher(simulator)` from `@midnight-ntwrk/wallet-sdk-capabilities/validation`.
      */
-    fetchBlockData?: (config: TConfig) => MaybePromise<BlockDataFetcher>;
-    validationService?: (config: TConfig, deps: {
+    fetchBlockData?: (config: ResolvedConfiguration<TConfig>) => MaybePromise<BlockDataFetcher>;
+    validationService?: (config: ResolvedConfiguration<TConfig>, deps: {
         fetchBlockData: BlockDataFetcher;
         clock: Clock.Clock;
-    }) => MaybePromise<ValidationService>;
-    shielded: (config: TConfig) => MaybePromise<ShieldedWalletAPI>;
-    unshielded: (config: TConfig) => MaybePromise<UnshieldedWalletAPI>;
-    dust: (config: TConfig) => MaybePromise<DustWalletAPI>;
+    }) => MaybePromise<VersionedValidationService<AnyVersionValidatableTransaction, AnyLedgerParameters>>;
+    shielded: (config: ResolvedConfiguration<TConfig>) => MaybePromise<ShieldedWalletAPI>;
+    unshielded: (config: ResolvedConfiguration<TConfig>) => MaybePromise<UnshieldedWalletAPI>;
+    dust: (config: ResolvedConfiguration<TConfig>) => MaybePromise<DustWalletAPI>;
 };
-export { type BlockDataFetcher, type ValidateTxOptions, type ValidationService, ValidationFetchError, WellFormedError, type WellFormedStrictnessFlags, };
+export { type BlockDataFetcher, type ValidateTxOptions, type VersionedValidationService, ValidationFetchError, WellFormedError, type WellFormedStrictnessFlags, };
 export declare class WalletFacade {
     #private;
     private static makeDefaultSubmissionService;
     private static makeDefaultPendingTransactionsService;
+    /**
+     * 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.
+     */
     private static makeDefaultProvingService;
+    /**
+     * 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<TConfig extends DefaultConfiguration>(configuration: TConfig): ResolvedConfiguration<TConfig>;
     /**
      * Fetches the current Terms and Conditions from the network indexer.
      *
@@ -261,7 +511,9 @@ export declare 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)
@@ -270,21 +522,22 @@ export declare 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 init<TConfig extends DefaultConfiguration>(initParams: InitParams<TConfig>): Promise<WalletFacade>;
     readonly shielded: ShieldedWalletAPI;
     readonly unshielded: UnshieldedWalletAPI;
     readonly dust: DustWalletAPI;
-    readonly submissionService: SubmissionService<ledger.FinalizedTransaction>;
-    readonly pendingTransactionsService: PendingTransactionsService<ledger.FinalizedTransaction>;
-    readonly provingService: ProvingService<UnboundTransaction>;
-    readonly validationService: ValidationService;
+    readonly submissionService: SubmissionService<FinalizedTx>;
+    readonly pendingTransactionsService: PendingTransactionsService<FinalizedTx>;
+    readonly provingService: VersionedProvingService<AnyVersionUnboundTransaction, AnyVersionUnprovenTransaction>;
+    readonly validationService: VersionedValidationService<AnyVersionValidatableTransaction, AnyLedgerParameters>;
     readonly clock: Clock.Clock;
     /**
      * Constructor is private on purpose - much of initialization of the facade is potentially asynchronous, and adding
@@ -293,6 +546,49 @@ export declare class WalletFacade {
      * @private
      */
     private constructor();
+    /**
+     * 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.
+     */
+    private currentVersion;
+    /** The range of protocol versions on the same side of the boundary as a given one. */
+    private epochOf;
+    /** The range of protocol versions on the facade's current side of the boundary. */
+    private currentEpoch;
+    /**
+     * 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.
+     */
+    private accept;
+    /**
+     * 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.
+     */
+    private seal;
+    /** The ledger primitives the facade signs with on its current side of the boundary. */
+    private authoring;
     private defaultTtl;
     /**
      * Checks whether a transaction is structurally well-formed before passing it to a balance or submit method.
@@ -339,7 +635,14 @@ export declare class WalletFacade {
      * @throws {@link WellFormedError} If the transaction fails any enabled check.
      * @throws {@link ValidationFetchError} If the block-data fetch fails.
      */
-    validateTransaction(tx: ledger.FinalizedTransaction | UnboundTransaction | ledger.UnprovenTransaction, options: ValidateTxOptions): Promise<void>;
+    validateTransaction(tx: AnyTx, options: ValidateTxOptions<AnyLedgerParameters>): Promise<void>;
+    /**
+     * 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.
+     */
     private mergeUnprovenTransactions;
     private createDustActionTransaction;
     state(): Observable<FacadeState>;
@@ -354,7 +657,7 @@ export declare class WalletFacade {
      * @returns The transaction identifier.
      * @throws {@link WellFormedError} — call {@link validateTransaction} first to get this error early.
      */
-    submitTransaction(tx: ledger.FinalizedTransaction): Promise<TransactionIdentifier>;
+    submitTransaction(tx: FinalizedTx): Promise<TransactionIdentifier>;
     /**
      * Balances a finalized transaction by adding shielded, unshielded, and dust inputs/outputs as needed.
      *
@@ -367,10 +670,7 @@ export declare 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.
      */
-    balanceFinalizedTransaction(tx: ledger.FinalizedTransaction, secretKeys: {
-        shieldedSecretKeys: ledger.ZswapSecretKeys;
-        dustSecretKey: ledger.DustSecretKey;
-    }, options: {
+    balanceFinalizedTransaction(tx: FinalizedTx, options: {
         ttl: Date;
         tokenKindsToBalance?: TokenKindsToBalance;
     }): Promise<FinalizedTransactionRecipe>;
@@ -386,10 +686,7 @@ export declare 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.
      */
-    balanceUnboundTransaction(tx: UnboundTransaction, secretKeys: {
-        shieldedSecretKeys: ledger.ZswapSecretKeys;
-        dustSecretKey: ledger.DustSecretKey;
-    }, options: {
+    balanceUnboundTransaction(tx: UnboundTx, options: {
         ttl: Date;
         tokenKindsToBalance?: TokenKindsToBalance;
     }): Promise<UnboundTransactionRecipe>;
@@ -405,29 +702,41 @@ export declare 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.
      */
-    balanceUnprovenTransaction(tx: ledger.UnprovenTransaction, secretKeys: {
-        shieldedSecretKeys: ledger.ZswapSecretKeys;
-        dustSecretKey: ledger.DustSecretKey;
-    }, options: {
+    balanceUnprovenTransaction(tx: UnprovenTx, options: {
         ttl: Date;
         tokenKindsToBalance?: TokenKindsToBalance;
     }): Promise<UnprovenTransactionRecipe>;
-    finalizeRecipe(recipe: BalancingRecipe): Promise<ledger.FinalizedTransaction>;
+    finalizeRecipe(recipe: BalancingRecipe): Promise<FinalizedTx>;
     signRecipe(recipe: BalancingRecipe, signSegment: SignSegment): Promise<BalancingRecipe>;
-    signUnprovenTransaction(tx: ledger.UnprovenTransaction, signSegment: SignSegment): Promise<ledger.UnprovenTransaction>;
-    signUnboundTransaction(tx: UnboundTransaction, signSegment: SignSegment): Promise<UnboundTransaction>;
-    finalizeTransaction(tx: ledger.UnprovenTransaction): Promise<ledger.FinalizedTransaction>;
+    signUnprovenTransaction(tx: UnprovenTx, signSegment: SignSegment): Promise<UnprovenTx>;
+    signUnboundTransaction(tx: UnboundTx, signSegment: SignSegment): Promise<UnboundTx>;
+    /**
+     * 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.
+     */
+    finalizeTransaction(tx: UnprovenTx): Promise<FinalizedTx>;
     /** Estimates the fee for the given transaction only. This lacks the fees of the balancing transaction. */
-    calculateTransactionFee(tx: AnyTransaction): Promise<bigint>;
+    calculateTransactionFee(tx: AnyTx): Promise<bigint>;
     /** Calculates the total fee for the given transaction plus the fee of the balancing transaction. */
-    estimateTransactionFee(tx: AnyTransaction, secretKey: ledger.DustSecretKey, options?: {
+    estimateTransactionFee(tx: AnyTx, options?: {
         ttl?: Date;
         currentTime?: Date;
     }): Promise<bigint>;
-    transferTransaction(outputs: CombinedTokenTransfer[], secretKeys: {
-        shieldedSecretKeys: ledger.ZswapSecretKeys;
-        dustSecretKey: ledger.DustSecretKey;
-    }, options: {
+    transferTransaction(outputs: CombinedTokenTransfer[], options: {
         ttl: Date;
         payFees?: boolean;
     }): Promise<UnprovenTransactionRecipe>;
@@ -442,14 +751,11 @@ export declare class WalletFacade {
         fee: bigint;
         dustGenerationEstimations: ReadonlyArray<DustCoinsAndBalances.UtxoWithFullDustDetails>;
     }>;
-    initSwap(desiredInputs: CombinedSwapInputs, desiredOutputs: CombinedSwapOutputs[], secretKeys: {
-        shieldedSecretKeys: ledger.ZswapSecretKeys;
-        dustSecretKey: ledger.DustSecretKey;
-    }, options: {
+    initSwap(desiredInputs: CombinedSwapInputs, desiredOutputs: CombinedSwapOutputs[], options: {
         ttl: Date;
         payFees?: boolean;
     }): Promise<UnprovenTransactionRecipe>;
-    registerNightUtxosForDustGeneration(nightUtxos: readonly UtxoWithMeta[], nightVerifyingKey: ledger.SignatureVerifyingKey, signDustRegistration: SignSegment, dustReceiverAddress?: DustAddress): Promise<UnprovenTransactionRecipe>;
+    registerNightUtxosForDustGeneration(nightUtxos: readonly UtxoWithMeta[], nightVerifyingKey: ledgerV9.SignatureVerifyingKey, signDustRegistration: SignSegment, dustReceiverAddress?: DustAddress): Promise<UnprovenTransactionRecipe>;
     /**
      * Waits until the dust projected to be generated by the given Night UTxOs reaches `requiredAmount`, re-checking every
      * second. Pair with {@link estimateRegistration} to pick `requiredAmount`, then call before
@@ -463,10 +769,47 @@ export declare class WalletFacade {
     waitForGeneratedDust(nightUtxos: readonly UtxoWithMeta[], requiredAmount: bigint, opts?: {
         timeoutMs?: number;
     }): Promise<void>;
-    deregisterFromDustGeneration(nightUtxos: UtxoWithMeta[], nightVerifyingKey: ledger.SignatureVerifyingKey, signDustRegistration: SignSegment): Promise<UnprovenTransactionRecipe>;
-    revert(txOrRecipe: AnyTransaction | BalancingRecipe): Promise<void>;
-    revertTransaction(tx: AnyTransaction): Promise<void>;
-    start(shieldedSecretKeys: ledger.ZswapSecretKeys, dustSecretKey: ledger.DustSecretKey): Promise<void>;
+    deregisterFromDustGeneration(nightUtxos: UtxoWithMeta[], nightVerifyingKey: ledgerV9.SignatureVerifyingKey, signDustRegistration: SignSegment): Promise<UnprovenTransactionRecipe>;
+    revert(txOrRecipe: AnyTx | BalancingRecipe, reason?: string): Promise<void>;
+    /**
+     * 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.
+     */
+    private finalizedEntryFor;
+    /** Sync can record inclusion before the independent pending-status poller observes it. */
+    private reconcileFinalizedTransaction;
+    revertTransaction(tx: AnyTx, reason?: string): Promise<void>;
+    /**
+     * 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`).
+     */
+    start(material: FacadeStartMaterial, options?: FacadeStartOptions): Promise<void>;
+    /**
+     * 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.
+     */
+    doSync(material: FacadeStartMaterial): Promise<void>;
     stop(): Promise<void>;
     queryTxHistoryByHash(hash: TransactionHistoryStorage.TransactionHash): Promise<WalletEntry | undefined>;
     getAllFromTxHistory(): Promise<WalletEntry[]>;