@midnight-ntwrk/wallet-sdk-dust-wallet 5.0.0-beta.2 → 5.0.0-beta.4

package/README.md

@@ -97,17 +97,44 @@ const signedTx = await dustWallet.addDustGenerationSignature(dustGenerationTx, s
 - `SyncService` - Synchronization service
 - `Transacting` - Transaction utilities
 - `CoinsAndBalances` - Coin and balance management
+- V2 (ledger-v9) variant internals via `@midnight-ntwrk/wallet-sdk-dust-wallet/v2`
+- V1 (ledger-v8) variant internals via `@midnight-ntwrk/wallet-sdk-dust-wallet/v1`
 
-## V1 Builder
+## V2 Builder
 
-Use the V1 builder pattern for wallet construction:
+Use the V2 builder pattern for wallet construction:
 
 ```typescript
-import { V1Builder, RunningV1Variant } from '@midnight-ntwrk/wallet-sdk-dust-wallet';
+import { V2Builder, RunningV2Variant } from '@midnight-ntwrk/wallet-sdk-dust-wallet/v2';
 
-// Build a V1 dust wallet variant
+// Build a V2 dust wallet variant
 ```
 
+## Sync: the V1 variant replays events, permanently
+
+The two variants do not offer the same synchronisation options, and this is not a temporary gap.
+
+`./v2` (ledger-v9) can sync either way: by replaying the indexer's dust ledger events, or through the projections-based
+**eventless fast sync** (`makeEventLessSyncService` / `makeEventLessSyncCapability`).
+
+`./v1` (ledger-v8) offers **event replay only** — the same mechanism the shipped 1.x wallet uses in production today. It
+does not export the projection schema types, the `DustProjectionsUpdate` union, or the eventless sync service and
+capability. The reason is the ledger, not the wallet: the eventless path is built on four `DustLocalState` members that
+exist only in ledger-v9, and no published ledger-v8 (checked through 8.1.1, the latest) has any of them —
+
+| Member                             | Used for                                                     |
+| ---------------------------------- | ------------------------------------------------------------ |
+| `updateGenerationTreeFromEvidence` | applying generation-tree dtime updates from indexer evidence |
+| `commitmentTreeFirstFree`          | placing commitments relative to collapsed-tree updates       |
+| `generatingTreeFirstFree`          | the same, for the generation tree                            |
+| `nullifiers`                       | resolving which dust UTxOs a projection has already spent    |
+
+There is no v8-compatible implementation of them anywhere, so the path cannot be back-ported. **Decided 2026-08-19: the
+V1 variant keeps event-replay sync permanently; no ledger change is being requested to close this.**
+
+Everything else in `./v1` does track the current variant with the ledger swapped — including the sync lock, the one-shot
+`sync` entry point, and typed (non-defect) `blockData` failures.
+
 ## License
 
 Apache-2.0

package/dist/DustWallet.d.ts

@@ -1,105 +1,304 @@
-import { type DustParameters, type DustPublicKey, DustSecretKey, type FinalizedTransaction, type Signature, type SignatureVerifyingKey, type UnprovenTransaction } from '@midnightntwrk/ledger-v9';
-import { type ProtocolState, ProtocolVersion, type SyncProgress } from '@midnight-ntwrk/wallet-sdk-abstractions';
-import { type DustAddress } from '@midnight-ntwrk/wallet-sdk-address-format';
-import { type Variant, type VariantBuilder, type WalletLike } from '@midnight-ntwrk/wallet-sdk-runtime/abstractions';
-import { type Clock } from '@midnight-ntwrk/wallet-sdk-utilities';
-import * as rx from 'rxjs';
-import { type Balance, type CoinsAndBalancesCapability, type UtxoWithFullDustDetails } from './v1/CoinsAndBalances.js';
-import { CoreWallet } from './v1/CoreWallet.js';
-import { type KeysCapability } from './v1/Keys.js';
-import { type SerializationCapability } from './v1/Serialization.js';
-import { type NightUtxoSplitForDustRegistration } from './v1/Transacting.js';
-import { type DustFullInfo, type UtxoWithMeta } from './v1/types/Dust.js';
-import { type AnyTransaction } from './v1/types/ledger.js';
-import { type BaseV1Configuration, type DefaultV1Configuration, type V1Variant } from './v1/V1Builder.js';
-import { type BlockData, type WalletSyncUpdate } from './v1/Sync.js';
-export type { BlockData } from './v1/Sync.js';
-import { type TransactionHistoryService } from './v1/TransactionHistory.js';
-export type DustWalletCapabilities<TSerialized = string> = {
-    serialization: SerializationCapability<CoreWallet, null, TSerialized>;
-    coinsAndBalances: CoinsAndBalancesCapability<CoreWallet>;
-    keys: KeysCapability<CoreWallet>;
-};
-export type DustWalletServices = {
-    transactionHistory: TransactionHistoryService;
+/**
+ * A dust wallet that registers a variant either side of a protocol boundary and follows the chain across it.
+ *
+ * @remarks
+ *   One wallet, two ledger versions. Before the boundary the V1 variant reads the chain with the ledger version that
+ *   produced it; from the boundary the V2 variant does, having been handed identity and a place in the timeline and
+ *   nothing else — the dust itself is re-discovered from the indexer's replay, which is what
+ *   `test/forkSimulation.test.ts` proves. Which variant is running is the runtime's business, not the application's:
+ *   the wallet's public API speaks ledger-v9 throughout, and where the two sides genuinely differ — the key material
+ *   each variant's synchronization needs — the wallet resolves it per variant from what it retained.
+ *
+ *   `DustWallet(configuration)` at the bottom is how this package ships it. `CustomForkingDustWallet` is the same wallet
+ *   over builders the caller chooses, and `SingleVariantDustWallet.ts` is the composition that gives up the crossing to
+ *   run one variant only.
+ */
+import * as ledgerV8 from '@midnight-ntwrk/ledger-v8';
+import * as ledgerV9 from '@midnightntwrk/ledger-v9';
+import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { type ChainVersionProbe } from '@midnight-ntwrk/wallet-sdk-capabilities/chainVersion';
+import { Variant, type VariantBuilder, type WalletLike } from '@midnight-ntwrk/wallet-sdk-runtime/abstractions';
+import { Either } from 'effect';
+import { type UnsupportedSnapshotVersionError } from './Restore.js';
+import { type DefaultDustConfiguration, type DustWalletAPI } from './DustWalletAPI.js';
+import { type V1Variant } from './v1/index.js';
+import { type WalletSyncUpdate as V1SyncUpdate } from './v1/Sync.js';
+import { Migration, type V2Variant } from './v2/index.js';
+import { type WalletSyncUpdate as V2SyncUpdate } from './v2/SyncSchema.js';
+import { type NetworkId } from './v2/types/index.js';
+import { type WalletError as V1WalletError } from './v1/WalletError.js';
+import { type WalletError } from './v2/WalletError.js';
+/**
+ * What restoring a Dust wallet from a snapshot can fail with.
+ *
+ * @remarks
+ *   Two failures, and they mean different things. The snapshot may declare a protocol version no registered variant
+ *   reads, which is a fact about this build of the SDK rather than about the snapshot; or the variant that owns it may
+ *   be unable to make sense of the bytes, which is a fact about the snapshot. Either is an ordinary thing to meet when
+ *   restoring something a user supplied, which is why `tryRestore` reports them rather than throwing.
+ */
+export type DustRestoreError = UnsupportedSnapshotVersionError | V1WalletError | WalletError;
+/** The V1 variant a forking dust wallet registers: the one that reads the chain before the boundary. */
+export type V1DustVariant<TSyncUpdate> = V1Variant<string, TSyncUpdate, ledgerV8.FinalizedTransaction, ledgerV8.DustSecretKey>;
+/** The V2 variant a forking dust wallet registers: the one the V1 wallet is migrated into. */
+export type V2DustVariant<TSyncUpdate> = V2Variant<string, TSyncUpdate, ledgerV9.FinalizedTransaction, ledgerV9.DustSecretKey, Migration.PreviousLedgerWallet>;
+/** The two variants a forking dust wallet runs, in registration order. */
+export type ForkingDustVariants<TV1SyncUpdate, TV2SyncUpdate> = [
+    Variant.VersionedVariant<V1DustVariant<TV1SyncUpdate>>,
+    Variant.VersionedVariant<V2DustVariant<TV2SyncUpdate>>
+];
+/**
+ * A variant builder registered together with the configuration it alone is built from.
+ *
+ * @remarks
+ *   Per-variant rather than shared, and for dust the hazard is concrete rather than theoretical: both variants declare an
+ *   optional `dustParameters`, each of its own ledger's `DustParameters`. The two classes are structurally identical,
+ *   so a wallet-wide intersection accepts either and then hands whichever was supplied to _both_ variants — one of
+ *   which would be building a `DustLocalState` out of the other module's WASM object. Splitting the configuration is
+ *   what makes that unrepresentable.
+ */
+export type SelfConfiguredDustVariant<TVariant extends Variant.AnyVariant, TConfiguration extends object> = Readonly<{
+    builder: VariantBuilder.VariantBuilder<TVariant, TConfiguration>;
+    configuration: TConfiguration;
+}>;
+/** What a forking dust wallet needs to know about itself, whatever its variants are built from. */
+export type ForkingDustConfiguration = {
+    networkId: NetworkId;
+    /** Where each ledger version begins on this chain — see {@link ProtocolVersion.ForkSchedule}. */
+    forks: ProtocolVersion.ForkSchedule;
+    /**
+     * How the wallet asks the chain which protocol version it is on, before it chooses a variant to start at.
+     *
+     * @remarks
+     *   Optional, and best-effort where present: a wallet with no probe — or one whose probe does not answer in time —
+     *   starts on the V1 variant and learns the version from the first event it sees, which is what a wallet with no
+     *   history has always done. What a probe buys is the two things that guess costs: a hand-over per start on a chain
+     *   entirely past the boundary, and, on a chain that has shown this wallet no events at all, an epoch that never gets
+     *   corrected.
+     *
+     *   Nothing about it can make a start fail. A rejection, a timeout, a version no registered variant covers: each leaves
+     *   the wallet exactly where a wallet that never asked would be.
+     */
+    chainVersionProbe?: ChainVersionProbe;
 };
-export declare class DustWalletState<TSerialized = string> {
-    static readonly mapState: <TSerialized_1 = string>(variant: DustWalletCapabilities<TSerialized_1> & DustWalletServices) => (state: ProtocolState.ProtocolState<CoreWallet>) => DustWalletState<TSerialized_1>;
-    readonly protocolVersion: ProtocolVersion.ProtocolVersion;
-    readonly state: CoreWallet;
-    readonly capabilities: DustWalletCapabilities<TSerialized>;
-    readonly services: DustWalletServices;
-    get totalCoins(): readonly DustFullInfo[];
-    get availableCoins(): readonly DustFullInfo[];
-    get pendingCoins(): readonly DustFullInfo[];
-    get publicKey(): DustPublicKey;
-    get address(): DustAddress;
-    get progress(): SyncProgress.SyncProgress;
-    constructor(state: ProtocolState.ProtocolState<CoreWallet>, capabilities: DustWalletCapabilities<TSerialized>, services: DustWalletServices);
-    balance(time: Date): Balance;
-    estimateDustGeneration(nightUtxos: ReadonlyArray<UtxoWithMeta>, currentTime: Date): ReadonlyArray<UtxoWithFullDustDetails>;
-    serialize(): TSerialized;
-}
-export type DustWalletAPI<TStartAux = DustSecretKey, TSerialized = string> = {
-    readonly state: rx.Observable<DustWalletState<TSerialized>>;
-    start(secretKey: TStartAux): Promise<void>;
-    createDustGenerationTransaction(currentTime: Date | undefined, ttl: Date, nightUtxos: Array<UtxoWithMeta>, nightVerifyingKey: SignatureVerifyingKey, dustReceiverAddress: DustAddress | undefined): Promise<UnprovenTransaction>;
-    splitNightUtxosForDustRegistration(currentTime: Date, nightUtxos: ReadonlyArray<UtxoWithMeta>, isRegistration: boolean): Promise<NightUtxoSplitForDustRegistration>;
-    attachDustRegistration(transaction: UnprovenTransaction, currentTime: Date, nightVerifyingKey: SignatureVerifyingKey, dustReceiverAddress: DustAddress | undefined, feePayment: bigint): Promise<UnprovenTransaction>;
-    addDustGenerationSignature(transaction: UnprovenTransaction, signature: Signature): Promise<UnprovenTransaction>;
+/**
+ * One ledger version's dust secret key per side of a protocol boundary.
+ *
+ * @remarks
+ *   Both sides are required. A caller holding key objects rather than a seed has to hold both, because the two belong to
+ *   different ledger runtimes and neither can be derived from the other; a product with one side optional would let a
+ *   wallet be built that cannot read half the chain, which is the shape this replaced.
+ */
+export type DustKeysByEpoch = Readonly<{
+    /** The ledger-v8's dust secret key. */
+    v8: ledgerV8.DustSecretKey;
+    /** The ledger-v9's dust secret key. */
+    v9: ledgerV9.DustSecretKey;
+}>;
+/**
+ * A running dust wallet that spans a protocol boundary.
+ *
+ * @remarks
+ *   Its two extra starts are the instance counterparts of the class-level ones, and they are here rather than on
+ *   {@link DustWalletAPI} because only a wallet with a variant either side of a boundary has anything to do with them: a
+ *   single-variant wallet speaks one ledger version, and the key `start` takes is always the right one.
+ */
+export type ForkingDustWallet<TV1SyncUpdate, TV2SyncUpdate> = DustWalletAPI<ledgerV9.DustSecretKey, string> & WalletLike.WalletLike<ForkingDustVariants<TV1SyncUpdate, TV2SyncUpdate>> & {
     /**
-     * Attaches a signature to the DustRegistration in segment 1's `dustActions` only. Unlike
-     * {@link addDustGenerationSignature}, this does NOT touch the unshielded offers — those should be signed separately
-     * via the unshielded-wallet signing path. Use this when the caller orchestrates signing across both packages (e.g.
-     * the facade's `signRecipe`).
+     * Starts this wallet from a seed, which answers for the variant either side of the boundary.
+     *
+     * @remarks
+     *   The instance counterpart of {@link ForkingDustWalletClass.startWithSeed}, and what a wallet restored from a
+     *   snapshot written below the boundary is started with. A snapshot carries no key material by design, and the
+     *   variant it restores onto is the ledger-v8 one, whose synchronization the ledger-v9 key
+     *   {@link DustWalletAPI.start} takes cannot serve. The class-level start answers for both sides too — but it builds
+     *   a _fresh_ wallet, which is the opposite of what a caller who has just restored one wants.
+     *
+     *   No dust parameters are asked for, because a restored wallet needs none: they parameterise an _empty_ state, which
+     *   is what a fresh build has to construct and a restored one already brought back from its snapshot.
+     *
+     *   The seed itself is not kept: both ledger versions' dust keys are derived from it here and retained instead, which
+     *   is the same capability with a shorter-lived secret.
+     * @example
+     *   ```typescript
+     *   const wallet = DustWallet(configuration).restore(snapshot);
+     *   await wallet.startWithSeed(seed);
+     *   ```;
+     *
+     * @param seed The seed to derive both ledger versions' dust keys from.
+     * @returns Nothing; resolves once synchronization has been started on whichever variant is current.
      */
-    addDustRegistrationSignature(transaction: UnprovenTransaction, signature: Signature): Promise<UnprovenTransaction>;
-    calculateFee(transactions: ReadonlyArray<AnyTransaction>): Promise<bigint>;
-    estimateFee(secretKey: DustSecretKey, transactions: ReadonlyArray<AnyTransaction>, ttl?: Date, currentTime?: Date): Promise<bigint>;
-    balanceTransactions(secretKey: DustSecretKey, transactions: ReadonlyArray<AnyTransaction>, ttl: Date, currentTime?: Date): Promise<{
-        transaction: UnprovenTransaction;
-        blockData: BlockData;
-    }>;
-    serializeState(): Promise<TSerialized>;
-    waitForSyncedState(allowedGap?: bigint): Promise<DustWalletState<TSerialized>>;
+    startWithSeed(seed: Uint8Array): Promise<void>;
     /**
-     * Resolves when the dust projected to be generated by the single highest-generation unregistered Night UTxO reaches
-     * `requiredAmount`. The projection is re-evaluated every second so the wait advances even when the dust state stream
-     * is quiet. Tracks the same quantity used as `allow_fee_payment` for the registration (the maximum across the UTxOs,
-     * not their sum, since `splitNightUtxos` puts only one UTxO in the guaranteed slot), so pairing with
-     * `WalletFacade.estimateRegistration` to pick `requiredAmount` guarantees the subsequent
-     * `registerNightUtxosForDustGeneration` will pass its fee-coverage guard.
+     * Starts this wallet from dust keys of both ledger versions.
+     *
+     * @remarks
+     *   The instance counterpart of {@link ForkingDustWalletClass.startWithKeys}, for a caller that will not part with a
+     *   seed. Both sides are required for the same reason they are there: a `DustSecretKey` belongs to one ledger
+     *   version's runtime, so a wallet given one side alone could not read the other side of the chain.
+     * @example
+     *   ```typescript
+     *   const wallet = DustWallet(configuration).restore(snapshot);
+     *   await wallet.startWithKeys({ v8: v8Key, v9: v9Key });
+     *   ```;
      *
-     * @param nightUtxos - UTxOs to project generation for; same set passed to `registerNightUtxosForDustGeneration`.
-     *   Already-registered UTxOs are ignored. Must be non-empty.
-     * @param requiredAmount - Threshold to wait for, as a Dust amount. Resolves immediately if `<= 0n`.
-     * @param clock - Source of current time, read on every tick. Required, and a {@link Clock.Clock} rather than a
-     *   snapshot `Date` like the other methods' `currentTime`: the projection only advances because the time is re-read
-     *   each tick, and callers must inject their own clock so simulator-driven tests respect simulator time.
-     * @param opts.timeoutMs - Deadline, in ms from subscription, for `requiredAmount` to be reached; rejects if it is
-     *   not. Default `300_000`.
-     * @returns A promise that resolves once the projected dust reaches `requiredAmount`.
-     * @throws Error if `nightUtxos` is empty.
-     * @throws TimeoutError if `requiredAmount` is not reached within `opts.timeoutMs`.
+     * @param keys One ledger version's dust secret key per side of the boundary.
+     * @returns Nothing; resolves once synchronization has been started on whichever variant is current.
      */
-    waitForGeneratedDust(nightUtxos: ReadonlyArray<UtxoWithMeta>, requiredAmount: bigint, clock: Clock.Clock, opts?: {
-        timeoutMs?: number;
-    }): Promise<void>;
-    revertTransaction(transaction: AnyTransaction): Promise<void>;
-    getAddress(): Promise<DustAddress>;
-    stop(): Promise<void>;
+    startWithKeys(keys: DustKeysByEpoch): Promise<void>;
 };
-export type CustomizedDustWallet<TStartAux = DustSecretKey, TTransaction = FinalizedTransaction, TSyncUpdate = WalletSyncUpdate, TSerialized = string> = DustWalletAPI<TStartAux, TSerialized> & WalletLike.WalletLike<[Variant.VersionedVariant<V1Variant<TSerialized, TSyncUpdate, TTransaction, TStartAux>>]>;
-export type DefaultDustConfiguration = DefaultV1Configuration;
-export interface CustomizedDustWalletClass<TStartAux = DustSecretKey, TTransaction = FinalizedTransaction, TSyncUpdate = WalletSyncUpdate, TSerialized = string, TConfig extends BaseV1Configuration = DefaultDustConfiguration> extends WalletLike.BaseWalletClass<[
-    Variant.VersionedVariant<V1Variant<TSerialized, TSyncUpdate, TTransaction, TStartAux>>
-]> {
-    configuration: TConfig;
-    startWithSeed(seed: Uint8Array, dustParameters: DustParameters): CustomizedDustWallet<TStartAux, TTransaction, TSyncUpdate, TSerialized>;
-    startWithSecretKey(secretKey: DustSecretKey, dustParameters: DustParameters): CustomizedDustWallet<TStartAux, TTransaction, TSyncUpdate, TSerialized>;
-    restore(serializedState: TSerialized): CustomizedDustWallet<TStartAux, TTransaction, TSyncUpdate, TSerialized>;
+/** The class a forking dust wallet is started from. */
+export interface ForkingDustWalletClass<TV1SyncUpdate, TV2SyncUpdate, TConfiguration extends ForkingDustConfiguration = ForkingDustConfiguration> extends WalletLike.BaseWalletClass<ForkingDustVariants<TV1SyncUpdate, TV2SyncUpdate>, TConfiguration> {
+    /**
+     * Builds a wallet from a seed, and remembers the seed.
+     *
+     * @remarks
+     *   The only start that can follow the chain the whole way. The seed is the one piece of key material that crosses a
+     *   protocol boundary — each variant derives its own `DustSecretKey` from it, and the two derive the same dust public
+     *   key — so a wallet built this way can synchronize on either side of the fork.
+     *
+     *   Asynchronous because choosing where to begin can mean asking the chain: with a
+     *   {@link ForkingDustConfiguration.chainVersionProbe} configured, the wallet starts at the variant that owns the
+     *   version the chain reports, which on a chain already past the boundary is the ledger-v9 one from the first moment.
+     *   Without one, or when the question goes unanswered, it begins on the V1 variant and is handed over when the chain
+     *   reports a version the V2 variant owns — on a chain that has already forked, the first batch it sees.
+     * @param seed The seed to derive both ledger versions' dust keys from.
+     * @param dustParameters The ledger-v9's dust parameters, which an empty ledger-v9 state is valued against.
+     * @returns A wallet started at the variant the chain is on, or on the V1 variant when the chain was not asked or did
+     *   not say.
+     */
+    startWithSeed(seed: Uint8Array, dustParameters?: DustGenerationRates): Promise<ForkingDustWallet<TV1SyncUpdate, TV2SyncUpdate>>;
+    /**
+     * Builds a wallet from dust keys of both ledger versions.
+     *
+     * @remarks
+     *   The escape hatch for a caller that will not hand over a seed. Both sides are required, and that is the whole point:
+     *   a `DustSecretKey` belongs to one ledger version's runtime — there is nothing to convert, and the dust public keys
+     *   being identical either side does not help, because reading dust needs the secret — so a wallet given one side
+     *   alone could not read the other side of the chain. It costs the caller an import of both ledger packages and the
+     *   same derivation done twice; a seed costs neither.
+     * @param keys One ledger version's dust secret key per side of the boundary.
+     * @param dustParameters The ledger-v9's dust parameters.
+     * @returns A wallet started at the variant the chain is on, or on the V1 variant — where a wallet with no history
+     *   belongs — when the chain was not asked or did not say.
+     */
+    startWithKeys(keys: DustKeysByEpoch, dustParameters?: DustGenerationRates): Promise<ForkingDustWallet<TV1SyncUpdate, TV2SyncUpdate>>;
+    /**
+     * Restores a wallet from a snapshot, into whichever registered variant wrote it.
+     *
+     * @param serializedState The serialized wallet state.
+     * @returns A wallet started from that state, on the variant that owns its protocol version.
+     * @throws UnsupportedSnapshotVersionError if the snapshot declares a version no registered variant reads.
+     */
+    restore(serializedState: string): ForkingDustWallet<TV1SyncUpdate, TV2SyncUpdate>;
+    /**
+     * Restores a wallet from a snapshot, reporting what it could not read rather than throwing.
+     *
+     * @remarks
+     *   Additive alongside {@link restore}, which is unchanged and still the right shape for a snapshot the application has
+     *   just written itself. This is the shape for one it has not: a snapshot a user supplied, or one written by a build
+     *   of the SDK that is no longer the one running, where "I cannot read this" is an ordinary answer rather than a bug.
+     *   The two cannot disagree — `restore` is this, with the reason thrown.
+     * @param serializedState The serialized wallet state.
+     * @returns A wallet started from that state, or the reason the snapshot could not be read. See
+     *   {@link DustRestoreError}.
+     */
+    tryRestore(serializedState: string): Either.Either<ForkingDustWallet<TV1SyncUpdate, TV2SyncUpdate>, DustRestoreError>;
 }
-export type DustWallet = CustomizedDustWallet<DustSecretKey, FinalizedTransaction, WalletSyncUpdate, string>;
-export type DustWalletClass = CustomizedDustWalletClass<DustSecretKey, FinalizedTransaction, WalletSyncUpdate, string>;
+/**
+ * The same dust parameters, rebuilt by the ledger-v8.
+ *
+ * @remarks
+ *   Dust's own departure from shielded, and the one place this wallet has to translate anything. `DustLocalState` is
+ *   parameterised, so an empty ledger-v8 state cannot be built without a ledger-v8 `DustParameters` — and the
+ *   application hands over a ledger-v9 one, because that is the ledger version this wallet's public API speaks. What
+ *   crosses is therefore the three numbers, not the object: they are plain `bigint`s, and the ledger-v8 class takes
+ *   exactly them.
+ * @param parameters The ledger-v9's dust parameters.
+ * @returns The same generation and decay rates, as a ledger-v8 `DustParameters`.
+ */
+/**
+ * The rates dust is generated and decays at, as plain data.
+ *
+ * @remarks
+ *   Structurally what both ledger versions' `DustParameters` are — three scalars and nothing else — which is why the
+ *   ledger classes remain assignable to this and a caller who already holds one can go on passing it. What it removes
+ *   is the reason to obtain one: three numbers do not need a ledger version to express, and asking for a
+ *   `LedgerParameters.initialParameters().dust` made an application import a ledger to start a wallet.
+ */
+export type DustGenerationRates = Readonly<{
+    /** How much dust one Night generates, at the cap. */
+    nightDustRatio: bigint;
+    /** How fast dust decays once its Night is spent. */
+    generationDecayRate: bigint;
+    /** How long dust survives after its Night is spent. */
+    dustGracePeriodSeconds: bigint;
+}>;
+export declare const asV8DustParameters: (parameters: DustGenerationRates) => ledgerV8.DustParameters;
+/**
+ * The same dust rates, as ledger-v9's parameters object.
+ *
+ * @remarks
+ *   The mirror of {@link asV8DustParameters}, and needed for the same reason: an empty state of either variant is
+ *   parameterised, and the rates a caller names are plain numbers rather than either ledger's object. Ordinarily the
+ *   ledger-v9 side's empty state is the migration's business; a wallet that starts on V2 because the chain said so has
+ *   no migration to get one from, and builds its own here.
+ * @param parameters The rates to express.
+ * @returns The same generation and decay rates, as a ledger-v9 `DustParameters`.
+ */
+export declare const asV9DustParameters: (parameters: DustGenerationRates) => ledgerV9.DustParameters;
+/**
+ * Builds a dust wallet class over a variant either side of a protocol boundary.
+ *
+ * @remarks
+ *   The boundary is `configuration.forks.v9` and nothing else: the V1 variant is registered from the minimum supported
+ *   version and the ledger-v9 one from the fork version, so the version at which the runtime hands over and the version
+ *   at which each variant stops applying are the same number, taken from one place.
+ *
+ *   Each variant is built from its own configuration, which for dust is load-bearing rather than tidy — see
+ *   {@link SelfConfiguredDustVariant}.
+ * @example
+ *   ```typescript
+ *   const Wallet = CustomForkingDustWallet(
+ *     { forks },
+ *     { builder: new V1Builder().withDefaults(), configuration: v1Configuration },
+ *     { builder: new V2Builder().withDefaults().withMigration(...), configuration: v2Configuration },
+ *   );
+ *   const wallet = Wallet.startWithSeed(seed, dustParameters);
+ *   ```;
+ *
+ * @param configuration What the wallet layer needs: where the boundary lies.
+ * @param v1 The variant that reads the chain below the boundary, with the configuration it is built from.
+ * @param v2 The variant that reads it from the boundary, with the configuration it is built from.
+ * @returns The wallet class.
+ */
+export declare function CustomForkingDustWallet<TV1SyncUpdate, TV2SyncUpdate, TV1Config extends object, TV2Config extends object, TConfiguration extends ForkingDustConfiguration = ForkingDustConfiguration>(configuration: TConfiguration, v1: SelfConfiguredDustVariant<V1DustVariant<TV1SyncUpdate>, TV1Config>, v2: SelfConfiguredDustVariant<V2DustVariant<TV2SyncUpdate>, TV2Config>): ForkingDustWalletClass<TV1SyncUpdate, TV2SyncUpdate, TConfiguration>;
+/** A dust wallet built the way this package ships it: one variant either side of the protocol boundary. */
+export type DustWallet = ForkingDustWallet<V1SyncUpdate, V2SyncUpdate>;
+/** The class {@link DustWallet} builds. */
+export type DustWalletClass = ForkingDustWalletClass<V1SyncUpdate, V2SyncUpdate, DefaultDustConfiguration>;
+/**
+ * Builds the dust wallet this package ships: the default variant either side of `configuration.forks.v9`.
+ *
+ * @remarks
+ *   Both variants read the chain through the indexer's dust event subscription and record transaction history in the same
+ *   storage. Each is built from the same application configuration, because what they ask for happens to coincide —
+ *   with one exception the type system cannot police: `dustParameters` names a ledger type, and the two ledgers'
+ *   `DustParameters` are structurally identical, so it is passed only to the variant it belongs to.
+ *
+ *   **The V1 variant syncs by event replay only.** The projections fast-sync path is a ledger-v9 capability: it needs
+ *   four `DustLocalState` APIs that no published ledger-v8 has. That is a permanent property of the V1 variant, not a
+ *   gap to be closed.
+ *
+ *   **Fee-paying operations work on either side of the boundary**: the active variant answers with its own ledger's
+ *   objects, and every result travels as a handle stamped with the epoch that built it.
+ *
+ *   **The chain is asked where it is before a variant is chosen.** The indexer this wallet already syncs from answers
+ *   which protocol version the chain is on, so a start on a chain past the boundary begins on V2 rather than handing
+ *   over immediately. An application that would rather ask something else — a cache, a value it already holds —
+ *   supplies its own `chainVersionProbe`; one whose chain cannot be reached loses nothing, because the answer is
+ *   best-effort and its absence is the behaviour this wallet had before.
+ * @param configuration What the wallet and both its variants are built from, including where the boundary lies.
+ * @returns The wallet class.
+ */
 export declare function DustWallet(configuration: DefaultDustConfiguration): DustWalletClass;
-export declare function CustomDustWallet<TConfig extends BaseV1Configuration = DefaultDustConfiguration, TStartAux = DustSecretKey, TTransaction = FinalizedTransaction, TSyncUpdate = WalletSyncUpdate, TSerialized = string>(configuration: TConfig, builder: VariantBuilder.VariantBuilder<V1Variant<TSerialized, TSyncUpdate, TTransaction, TStartAux>, TConfig>): CustomizedDustWalletClass<TStartAux, TTransaction, TSyncUpdate, TSerialized, TConfig>;