@midnightntwrk/wallet-sdk-dust-wallet 4.2.0

package/README.md

@@ -0,0 +1,106 @@
+# @midnightntwrk/wallet-sdk-dust-wallet
+
+Manages dust (transaction fees) on the Midnight network.
+
+## Installation
+
+```bash
+npm install @midnightntwrk/wallet-sdk-dust-wallet
+```
+
+## Overview
+
+The Dust Wallet handles dust operations on the Midnight network. Dust is required to pay transaction fees. This package
+provides:
+
+- Dust coin management and tracking
+- Balance synchronization with the network
+- Transaction fee calculation
+- Dust generation from Night UTXOs
+- Fee balancing for transactions
+
+## Usage
+
+### Starting the Wallet
+
+```typescript
+import { DustWallet } from '@midnightntwrk/wallet-sdk-dust-wallet';
+
+await dustWallet.start(dustSecretKey);
+```
+
+### Observing State
+
+```typescript
+dustWallet.state.subscribe((state) => {
+  console.log('Progress:', state.state.progress);
+  console.log('Balance:', state.state.balance);
+  console.log('Dust Address:', state.dustAddress);
+});
+
+// Or wait for sync
+const syncedState = await dustWallet.waitForSyncedState();
+```
+
+### Balancing Transaction Fees
+
+```typescript
+// Add fee balancing to a transaction
+const feeBalancingTx = await dustWallet.balanceTransactions(dustSecretKey, [transactionToBalance], ttl);
+```
+
+### Calculating Fees
+
+```typescript
+// Calculate the fee for a transaction only (does not include the balancing transaction fee)
+const fee = await dustWallet.calculateFee([transaction]);
+
+// Estimate the total fee including the balancing transaction fee
+// ttl and currentTime are optional (default: 1 hour from now, and current block timestamp)
+const totalFee = await dustWallet.estimateFee(dustSecretKey, [transaction]);
+
+// With explicit ttl and currentTime
+const totalFeeWithOptions = await dustWallet.estimateFee(dustSecretKey, [transaction], ttl, currentTime);
+```
+
+### Dust Generation
+
+Register Night UTXOs to generate dust:
+
+```typescript
+const dustGenerationTx = await dustWallet.createDustGenerationTransaction(
+  previousState,
+  ttl,
+  nightUtxos,
+  nightVerifyingKey,
+  dustReceiverAddress,
+);
+
+// Add signature for dust registration
+const signedTx = await dustWallet.addDustGenerationSignature(dustGenerationTx, signature);
+```
+
+## Exports
+
+- `DustWallet` - Main wallet class
+- `DustWalletState` - Wallet state type
+- `DustCoreWallet` - Core wallet implementation
+- `Keys` - Key management utilities
+- `Simulator` - Dust simulation utilities
+- `SyncService` - Synchronization service
+- `Transacting` - Transaction utilities
+- `CoinsAndBalances` - Coin and balance management
+
+## V1 Builder
+
+Use the V1 builder pattern for wallet construction:
+
+```typescript
+import { V1Builder, RunningV1Variant } from '@midnightntwrk/wallet-sdk-dust-wallet';
+
+// Build a V1 dust wallet variant
+```
+
+## License
+
+Apache-2.0

package/dist/DustWallet.d.ts

@@ -0,0 +1,101 @@
+import { type DustParameters, type DustPublicKey, DustSecretKey, type FinalizedTransaction, type Signature, type SignatureVerifyingKey, type UnprovenTransaction } from '@midnight-ntwrk/ledger-v8';
+import { type ProtocolState, ProtocolVersion, type SyncProgress } from '@midnightntwrk/wallet-sdk-abstractions';
+import { type DustAddress } from '@midnightntwrk/wallet-sdk-address-format';
+import { type Variant, type VariantBuilder, type WalletLike } from '@midnightntwrk/wallet-sdk-runtime/abstractions';
+import { type Clock } from '@midnightntwrk/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 WalletSyncUpdate } 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;
+};
+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>;
+    /**
+     * 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`).
+     */
+    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<UnprovenTransaction>;
+    serializeState(): Promise<TSerialized>;
+    waitForSyncedState(allowedGap?: bigint): Promise<DustWalletState<TSerialized>>;
+    /**
+     * 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.
+     *
+     * @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`.
+     */
+    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>;
+};
+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>;
+}
+export type DustWallet = CustomizedDustWallet<DustSecretKey, FinalizedTransaction, WalletSyncUpdate, string>;
+export type DustWalletClass = CustomizedDustWalletClass<DustSecretKey, FinalizedTransaction, WalletSyncUpdate, string>;
+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>;

package/dist/DustWallet.js

@@ -0,0 +1,192 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// Licensed under the Apache License, Version 2.0 (the "License");
+// You may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import { DustSecretKey, } from '@midnight-ntwrk/ledger-v8';
+import { ProtocolVersion } from '@midnightntwrk/wallet-sdk-abstractions';
+import { WalletBuilder } from '@midnightntwrk/wallet-sdk-runtime';
+import { Effect, Either } from 'effect';
+import * as rx from 'rxjs';
+import { CoreWallet } from './v1/CoreWallet.js';
+import { V1Tag } from './v1/RunningV1Variant.js';
+import { V1Builder } from './v1/V1Builder.js';
+export class DustWalletState {
+    static mapState = (variant) => (state) => {
+        const { serialization, coinsAndBalances, keys } = variant;
+        const { transactionHistory } = variant;
+        return new DustWalletState(state, { serialization, coinsAndBalances, keys }, { transactionHistory });
+    };
+    protocolVersion;
+    state;
+    capabilities;
+    services;
+    get totalCoins() {
+        return this.capabilities.coinsAndBalances.getTotalCoins(this.state);
+    }
+    get availableCoins() {
+        return this.capabilities.coinsAndBalances.getAvailableCoins(this.state);
+    }
+    get pendingCoins() {
+        return this.capabilities.coinsAndBalances.getPendingCoins(this.state);
+    }
+    get publicKey() {
+        return this.capabilities.keys.getPublicKey(this.state);
+    }
+    get address() {
+        return this.capabilities.keys.getAddress(this.state);
+    }
+    get progress() {
+        return this.state.progress;
+    }
+    constructor(state, capabilities, services) {
+        this.protocolVersion = state.version;
+        this.state = state.state;
+        this.capabilities = capabilities;
+        this.services = services;
+    }
+    balance(time) {
+        return this.capabilities.coinsAndBalances.getWalletBalance(this.state, time);
+    }
+    estimateDustGeneration(nightUtxos, currentTime) {
+        return this.capabilities.coinsAndBalances.estimateDustGeneration(this.state, nightUtxos, currentTime);
+    }
+    serialize() {
+        return this.capabilities.serialization.serialize(this.state);
+    }
+}
+export function DustWallet(configuration) {
+    return CustomDustWallet(configuration, new V1Builder().withDefaults());
+}
+export function CustomDustWallet(configuration, builder) {
+    const buildArgs = [configuration];
+    const BaseWallet = WalletBuilder.init()
+        .withVariant(ProtocolVersion.MinSupportedVersion, builder)
+        .build(...buildArgs);
+    return class CustomDustWalletImplementation extends BaseWallet {
+        static startWithSeed(seed, dustParameters) {
+            const dustSecretKey = DustSecretKey.fromSeed(seed);
+            return CustomDustWalletImplementation.startFirst(CustomDustWalletImplementation, CoreWallet.initEmpty(dustParameters, dustSecretKey, CustomDustWalletImplementation.configuration.networkId));
+        }
+        static startWithSecretKey(secretKey, dustParameters) {
+            return CustomDustWalletImplementation.startFirst(CustomDustWalletImplementation, CoreWallet.initEmpty(dustParameters, secretKey, CustomDustWalletImplementation.configuration.networkId));
+        }
+        static restore(serializedState) {
+            const deserialized = CustomDustWalletImplementation.allVariantsRecord()[V1Tag].variant.deserializeState(serializedState)
+                .pipe(Either.getOrThrow);
+            return CustomDustWalletImplementation.startFirst(CustomDustWalletImplementation, deserialized);
+        }
+        state;
+        constructor(runtime, scope) {
+            super(runtime, scope);
+            this.state = this.rawState.pipe(rx.map(DustWalletState.mapState(CustomDustWalletImplementation.allVariantsRecord()[V1Tag].variant)), rx.shareReplay({ refCount: true, bufferSize: 1 }));
+        }
+        start(secretKey) {
+            return this.runtime.dispatch({ [V1Tag]: (v1) => v1.startSyncInBackground(secretKey) }).pipe(Effect.runPromise);
+        }
+        async createDustGenerationTransaction(currentTime, ttl, nightUtxos, nightVerifyingKey, dustReceiverAddress) {
+            return this.runtime
+                .dispatch({
+                [V1Tag]: (v1) => v1.createDustGenerationTransaction(currentTime, ttl, nightUtxos, nightVerifyingKey, dustReceiverAddress),
+            })
+                .pipe(Effect.runPromise);
+        }
+        async splitNightUtxosForDustRegistration(currentTime, nightUtxos, isRegistration) {
+            return this.runtime
+                .dispatch({
+                [V1Tag]: (v1) => v1.splitNightUtxosForDustRegistration(currentTime, nightUtxos, isRegistration),
+            })
+                .pipe(Effect.runPromise);
+        }
+        async attachDustRegistration(transaction, currentTime, nightVerifyingKey, dustReceiverAddress, feePayment) {
+            return this.runtime
+                .dispatch({
+                [V1Tag]: (v1) => v1.attachDustRegistration(transaction, currentTime, nightVerifyingKey, dustReceiverAddress, feePayment),
+            })
+                .pipe(Effect.runPromise);
+        }
+        addDustGenerationSignature(transaction, signature) {
+            return this.runtime
+                .dispatch({
+                [V1Tag]: (v1) => v1.addDustGenerationSignature(transaction, signature),
+            })
+                .pipe(Effect.runPromise);
+        }
+        addDustRegistrationSignature(transaction, signature) {
+            return this.runtime
+                .dispatch({
+                [V1Tag]: (v1) => v1.addDustRegistrationSignature(transaction, signature),
+            })
+                .pipe(Effect.runPromise);
+        }
+        calculateFee(transactions) {
+            return this.runtime
+                .dispatch({
+                [V1Tag]: (v1) => v1.calculateFee(transactions),
+            })
+                .pipe(Effect.runPromise);
+        }
+        estimateFee(secretKey, transactions, ttl, currentTime) {
+            const effectiveTtl = ttl ?? new Date(Date.now() + 60 * 60 * 1000);
+            return this.runtime
+                .dispatch({
+                [V1Tag]: (v1) => v1.estimateFee(secretKey, transactions, effectiveTtl, currentTime),
+            })
+                .pipe(Effect.runPromise);
+        }
+        balanceTransactions(secretKey, transactions, ttl, currentTime) {
+            return this.runtime
+                .dispatch({
+                [V1Tag]: (v1) => v1.balanceTransactions(secretKey, transactions, ttl, currentTime),
+            })
+                .pipe(Effect.runPromise);
+        }
+        revertTransaction(transaction) {
+            return this.runtime
+                .dispatch({
+                [V1Tag]: (v1) => v1.revertTransaction(transaction),
+            })
+                .pipe(Effect.runPromise);
+        }
+        waitForSyncedState(allowedGap = 0n) {
+            return rx.firstValueFrom(this.state.pipe(rx.filter((state) => state.state.progress.isCompleteWithin(allowedGap))));
+        }
+        async waitForGeneratedDust(nightUtxos, requiredAmount, clock, opts) {
+            if (nightUtxos.length === 0) {
+                throw Error('At least one Night UTXO is required.');
+            }
+            if (requiredAmount <= 0n) {
+                return;
+            }
+            const timeoutMs = opts?.timeoutMs ?? 300_000;
+            // Combine the dust state stream with a 1 s tick — the dust state only emits when sync
+            // updates apply, but the generation projection depends on a current-time reading, which
+            // advances continuously. Without a periodic tick the filter would never re-run between
+            // state emissions on a quiet wallet, and the wait would hang.
+            await rx.firstValueFrom(rx.combineLatest([this.state, rx.timer(0, 1000)]).pipe(rx.filter(([dustState]) => {
+                // The registration's allow_fee_payment is capped at the single highest-generation
+                // unregistered Night UTxO (splitNightUtxos puts only 1 UTxO in the guaranteed slot),
+                // so the wait must track that same quantity — summing across UTxOs would resolve
+                // optimistically and the registration would still fail the fee check.
+                const maxGeneratedNow = dustState
+                    .estimateDustGeneration(nightUtxos, clock.now())
+                    .filter((u) => !u.utxo.registeredForDustGeneration)
+                    .reduce((max, u) => (u.dust.generatedNow > max ? u.dust.generatedNow : max), 0n);
+                return maxGeneratedNow >= requiredAmount;
+            }), rx.timeout({ first: timeoutMs })));
+        }
+        serializeState() {
+            return rx.firstValueFrom(this.state).then((state) => state.serialize());
+        }
+        getAddress() {
+            return rx.firstValueFrom(this.state).then((state) => state.address);
+        }
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './DustWallet.js';
+export { type DustTransactionHistoryEntry, DustSectionSchema, mergeDustSections } from './v1/TransactionHistory.js';

package/dist/index.js

@@ -0,0 +1,14 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// Licensed under the Apache License, Version 2.0 (the "License");
+// You may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+export * from './DustWallet.js';
+export { DustSectionSchema, mergeDustSections } from './v1/TransactionHistory.js';

package/dist/v1/CoinsAndBalances.d.ts

@@ -0,0 +1,47 @@
+import { type CoinRecipe } from '@midnightntwrk/wallet-sdk-capabilities';
+import { type CoreWallet } from './CoreWallet.js';
+import { type KeysCapability } from './Keys.js';
+import { type DustGenerationDetails, type DustGenerationInfo, type Dust, type DustFullInfo, type UtxoWithMeta } from './types/Dust.js';
+export type Balance = bigint;
+export type CoinWithValue<TToken> = {
+    token: TToken;
+    value: Balance;
+};
+/**
+ * Type describing a Night UTxO together with details of estimated Dust generation. It is meant to be primarily used for
+ * fee estimation of Dust registration transaction
+ */
+export type UtxoWithFullDustDetails = Readonly<{
+    utxo: UtxoWithMeta;
+    dust: DustGenerationDetails;
+}>;
+export type CoinSelection = <TCoin extends CoinRecipe>(coins: readonly TCoin[]) => TCoin | undefined;
+export declare const chooseCoin: CoinSelection;
+export type CoinsAndBalancesCapability<TState> = {
+    getWalletBalance(state: TState, time: Date): Balance;
+    getAvailableCoins(state: TState, time?: Date): readonly DustFullInfo[];
+    getPendingCoins(state: TState, time?: Date): readonly DustFullInfo[];
+    getTotalCoins(state: TState, time?: Date): ReadonlyArray<DustFullInfo>;
+    getAvailableCoinsWithGeneratedDust(state: TState, currentTime: Date): ReadonlyArray<CoinWithValue<Dust>>;
+    getGenerationInfo(state: TState, coin: Dust): DustGenerationInfo | undefined;
+    /** Splits provided Night utxos into the ones that will be used as inputs in the guaranteed and fallible sections */
+    splitNightUtxos(nightUtxos: ReadonlyArray<UtxoWithFullDustDetails>): {
+        guaranteed: ReadonlyArray<UtxoWithFullDustDetails>;
+        fallible: ReadonlyArray<UtxoWithFullDustDetails>;
+    };
+    /**
+     * Estimate how much Dust would be available to use if the Utxos provided were used for Dust generation from their
+     * beginning. This function is particularly useful for the purpose of registering for Dust generation and selecting
+     * the Utxo to be used for paying fees and approving the registration itself.
+     *
+     * @param state Current state of the wallet
+     * @param nightUtxos Existing Night utxos
+     * @param currentTime Current time
+     * @returns Estimated Dust generation per Utxo
+     */
+    estimateDustGeneration(state: TState, nightUtxos: ReadonlyArray<UtxoWithMeta>, currentTime: Date): ReadonlyArray<UtxoWithFullDustDetails>;
+};
+export type DefaultCoinsAndBalancesContext = {
+    keysCapability: KeysCapability<CoreWallet>;
+};
+export declare const makeDefaultCoinsAndBalancesCapability: (_config: unknown, getContext: () => DefaultCoinsAndBalancesContext) => CoinsAndBalancesCapability<CoreWallet>;

package/dist/v1/CoinsAndBalances.js

@@ -0,0 +1,102 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) Midnight Foundation
+// SPDX-License-Identifier: Apache-2.0
+// Licensed under the Apache License, Version 2.0 (the "License");
+// You may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import * as ledger from '@midnight-ntwrk/ledger-v8';
+import { DateOps } from '@midnightntwrk/wallet-sdk-utilities';
+import { pipe, Array as Arr, Order } from 'effect';
+export const chooseCoin = (coins) => coins
+    .filter((coin) => coin.value > 0n)
+    .toSorted((a, b) => Number(a.value - b.value))
+    .at(0);
+const FAKE_NONCE = '0'.repeat(64);
+export const makeDefaultCoinsAndBalancesCapability = (_config, getContext) => {
+    const getWalletBalance = (state, time) => {
+        return state.state.walletBalance(time);
+    };
+    const getGenerationInfo = (state, coin) => {
+        const info = state.state.generationInfo(coin);
+        return info && info.dtime
+            ? {
+                ...info,
+                dtime: new Date(+info.dtime), // TODO: remove when the ledger start to return a date instead of the number
+            }
+            : info;
+    };
+    const resolveTime = (state, time) => time ?? state.state.syncTime;
+    const toFullInfo = (state, coins, time) => coins.flatMap((coin) => {
+        const genInfo = getGenerationInfo(state, coin);
+        return genInfo ? [{ token: coin, ...getFullDustInfo(state.state.params, genInfo, coin, time) }] : [];
+    });
+    const availableDustTokens = (state) => {
+        const pendingSpends = new Set([...state.pendingDust.values()].map((coin) => coin.nonce));
+        return pipe(state.state.utxos, Arr.filter((coin) => !pendingSpends.has(coin.nonce)));
+    };
+    const getAvailableCoins = (state, time) => toFullInfo(state, availableDustTokens(state), resolveTime(state, time));
+    const getPendingCoins = (state, time) => toFullInfo(state, state.pendingDust, resolveTime(state, time));
+    const getTotalCoins = (state, time) => {
+        const effectiveTime = resolveTime(state, time);
+        return [...getAvailableCoins(state, effectiveTime), ...getPendingCoins(state, effectiveTime)];
+    };
+    const getAvailableCoinsWithGeneratedDust = (state, currentTime) => getAvailableCoins(state, currentTime).map((info) => ({ token: info.token, value: info.generatedNow }));
+    const getFullDustInfo = (parameters, genInfo, coin, currentTime) => {
+        const generatedValue = ledger.updatedValue(coin.ctime, coin.initialValue, genInfo, currentTime, parameters);
+        return {
+            dtime: genInfo.dtime,
+            maxCap: genInfo.value * parameters.nightDustRatio,
+            maxCapReachedAt: DateOps.addSeconds(coin.ctime, parameters.timeToCapSeconds),
+            generatedNow: generatedValue,
+            rate: genInfo.value * parameters.generationDecayRate,
+        };
+    };
+    const estimateDustGeneration = (state, nightUtxos, currentTime) => {
+        const dustPublicKey = getContext().keysCapability.getPublicKey(state);
+        return pipe(nightUtxos, Arr.map((utxo) => {
+            const genInfo = fakeGenerationInfo(utxo, dustPublicKey);
+            const fakeDustCoin = fakeDustToken(dustPublicKey, utxo);
+            const details = getFullDustInfo(state.state.params, genInfo, fakeDustCoin, currentTime);
+            return { utxo, dust: details };
+        }));
+    };
+    /** Create a fake generation info for a given Utxo. It allows to estimate the Dust generation from it */
+    const fakeGenerationInfo = (utxo, dustPublicKey) => {
+        return {
+            value: utxo.value,
+            owner: dustPublicKey,
+            nonce: FAKE_NONCE,
+            dtime: undefined,
+        };
+    };
+    /** Create a fake dust coin for a given Utxo. It allows to estimate full details of the Dust generation from it */
+    const fakeDustToken = (dustPublicKey, utxo) => ({
+        initialValue: 0n,
+        owner: dustPublicKey,
+        nonce: 0n,
+        seq: 0,
+        ctime: utxo.ctime,
+        backingNight: '',
+        mtIndex: 0n,
+    });
+    const splitNightUtxos = (utxos) => {
+        const [guaranteed, fallible] = pipe(utxos, Arr.sort(pipe(Order.bigint, Order.reverse, Order.mapInput((coin) => coin.dust.generatedNow))), Arr.splitAt(1));
+        return { guaranteed, fallible };
+    };
+    return {
+        getWalletBalance,
+        getAvailableCoins,
+        getPendingCoins,
+        getTotalCoins,
+        getAvailableCoinsWithGeneratedDust,
+        getGenerationInfo,
+        estimateDustGeneration,
+        splitNightUtxos,
+    };
+};

package/dist/v1/CoreWallet.d.ts

@@ -0,0 +1,31 @@
+import { type Bindingish, DustLocalState, type DustNullifier, type DustParameters, type DustPublicKey, type DustSecretKey, type DustStateChanges, type Proofish, type Signaturish, type Transaction, type Event } from '@midnight-ntwrk/ledger-v8';
+import { ProtocolVersion, SyncProgress } from '@midnightntwrk/wallet-sdk-abstractions';
+import { type Dust, type DustWithNullifier } from './types/Dust.js';
+import { type CoinWithValue } from './CoinsAndBalances.js';
+import { type NetworkId, type UnprovenDustSpend } from './types/ledger.js';
+export type PublicKey = {
+    publicKey: DustPublicKey;
+};
+export declare const PublicKey: {
+    fromSecretKey: (secretKey: DustSecretKey) => PublicKey;
+};
+export type CoreWallet = Readonly<{
+    state: DustLocalState;
+    publicKey: PublicKey;
+    protocolVersion: ProtocolVersion.ProtocolVersion;
+    progress: SyncProgress.SyncProgress;
+    networkId: NetworkId;
+    pendingDust: Array<DustWithNullifier>;
+}>;
+export declare const CoreWallet: {
+    init(localState: DustLocalState, secretKey: DustSecretKey, networkId: NetworkId): CoreWallet;
+    initEmpty(dustParameters: DustParameters, secretKey: DustSecretKey, networkId: NetworkId): CoreWallet;
+    empty(localState: DustLocalState, publicKey: PublicKey, networkId: NetworkId): CoreWallet;
+    restore(localState: DustLocalState, publicKey: PublicKey, pendingTokens: Array<DustWithNullifier>, syncProgress: Omit<SyncProgress.SyncProgressData, "isConnected">, protocolVersion: bigint, networkId: NetworkId): CoreWallet;
+    applyEventsWithChanges(wallet: CoreWallet, secretKey: DustSecretKey, events: Event[], currentTime: Date): [CoreWallet, DustStateChanges[]];
+    applyFailed(wallet: CoreWallet, tx: Transaction<Signaturish, Proofish, Bindingish>): CoreWallet;
+    revertTransaction<TTransaction extends Transaction<Signaturish, Proofish, Bindingish>>(wallet: CoreWallet, tx: TTransaction): CoreWallet;
+    updateProgress(wallet: CoreWallet, { appliedIndex, highestRelevantWalletIndex, highestIndex, highestRelevantIndex, isConnected, }: Partial<SyncProgress.SyncProgressData>): CoreWallet;
+    spendCoins(wallet: CoreWallet, secretKey: DustSecretKey, coins: ReadonlyArray<CoinWithValue<Dust>>, currentTime: Date): [ReadonlyArray<UnprovenDustSpend>, CoreWallet];
+    pendingDustToMap(coins: Array<DustWithNullifier>): Map<DustNullifier, Dust>;
+};