@midnightntwrk/wallet-sdk-dust-wallet 4.2.0

package/dist/v1/Sync.js

@@ -0,0 +1,218 @@
+// 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 { Effect, Either, Layer, ParseResult, pipe, Schema, Stream, Duration, Chunk, Schedule, } from 'effect';
+import { Event as LedgerEvent, LedgerParameters, } from '@midnight-ntwrk/ledger-v8';
+import { BlockHash, DustLedgerEvents } from '@midnightntwrk/wallet-sdk-indexer-client';
+import { WsSubscriptionClient, HttpQueryClient, ConnectionHelper, } from '@midnightntwrk/wallet-sdk-indexer-client/effect';
+import { EitherOps, LedgerOps } from '@midnightntwrk/wallet-sdk-utilities';
+import { WsURL } from '@midnightntwrk/wallet-sdk-utilities/networking';
+import { OtherWalletError, SyncWalletError } from './WalletError.js';
+import { getBlockEventsFrom, getLastBlock, } from '@midnightntwrk/wallet-sdk-capabilities/simulation';
+import { CoreWallet } from './CoreWallet.js';
+import { Uint8ArraySchema } from './Serialization.js';
+export const SecretKeysResource = {
+    create: (secretKey) => {
+        return (cb) => {
+            const result = cb(secretKey);
+            secretKey.clear();
+            return result;
+        };
+    },
+};
+const LedgerEventSchema = Schema.declare((input) => input instanceof LedgerEvent).annotations({
+    identifier: 'ledger.Event',
+});
+const LedgerEventFromUInt8Array = Schema.asSchema(Schema.transformOrFail(Uint8ArraySchema, LedgerEventSchema, {
+    encode: (e) => Effect.try({
+        try: () => e.serialize(),
+        catch: (err) => new ParseResult.Unexpected(err, 'Could not serialize Ledger Event'),
+    }),
+    decode: (bytes) => Effect.try({
+        try: () => LedgerEvent.deserialize(bytes),
+        catch: (err) => new ParseResult.Unexpected(err, 'Could not deserialize Ledger Event'),
+    }),
+}));
+const HexedEvent = pipe(Schema.Uint8ArrayFromHex, Schema.compose(LedgerEventFromUInt8Array));
+export const SyncEventsUpdateSchema = Schema.Struct({
+    id: Schema.Number,
+    raw: HexedEvent,
+    maxId: Schema.Number,
+});
+export const WalletSyncUpdate = {
+    create: (updates, secretKey, timestamp) => {
+        return {
+            updates,
+            secretKey,
+            timestamp,
+        };
+    },
+};
+export const makeDefaultSyncService = (config) => {
+    const indexerSyncService = makeIndexerSyncService(config);
+    return {
+        updates: (state, secretKey) => {
+            const batchSize = config.batchUpdates?.size ?? 10;
+            const batchTimeout = Duration.millis(config.batchUpdates?.timeout ?? 1);
+            const batchSpacing = config.batchUpdates?.spacing ?? 4;
+            return pipe(indexerSyncService.subscribeWallet(state), Stream.groupedWithin(batchSize, batchTimeout), Stream.map(Chunk.toArray), Stream.map((data) => WalletSyncUpdate.create(data, secretKey, new Date())), batchSpacing > 0
+                ? Stream.schedule(Schedule.spaced(Duration.millis(batchSpacing)))
+                : (eventsStream) => eventsStream, Stream.provideSomeLayer(indexerSyncService.connectionLayer()));
+        },
+        blockData: () => {
+            return Effect.gen(function* () {
+                const query = yield* BlockHash;
+                const result = yield* query({ offset: null });
+                return result.block;
+            }).pipe(Effect.provide(indexerSyncService.queryClient()), Effect.scoped, Effect.catchAll((err) => Effect.fail(new OtherWalletError({ message: `Encountered unexpected error: ${err.message}`, cause: err }))), Effect.flatMap((blockData) => {
+                if (!blockData) {
+                    throw new OtherWalletError({ message: 'Unable to fetch block data' });
+                }
+                // TODO: convert to schema
+                return LedgerOps.ledgerTry(() => ({
+                    hash: blockData.hash,
+                    height: blockData.height,
+                    ledgerParameters: LedgerParameters.deserialize(Buffer.from(blockData.ledgerParameters, 'hex')),
+                    timestamp: new Date(blockData.timestamp),
+                }));
+            }));
+        },
+    };
+};
+export const makeIndexerSyncService = (config) => {
+    return {
+        queryClient() {
+            return pipe(HttpQueryClient.layer({
+                url: config.indexerClientConnection.indexerHttpUrl,
+            }), Layer.mapError((error) => new OtherWalletError(error)));
+        },
+        connectionLayer() {
+            const { indexerClientConnection } = config;
+            return ConnectionHelper.createWebSocketUrl(indexerClientConnection.indexerHttpUrl, indexerClientConnection.indexerWsUrl).pipe(Either.flatMap((url) => WsURL.make(url)), Either.match({
+                onLeft: (error) => Layer.fail(error),
+                onRight: (url) => WsSubscriptionClient.layer({ url, keepAlive: indexerClientConnection.keepAlive }),
+            }), Layer.mapError((e) => new SyncWalletError({ message: 'Failed to to obtain correct indexer URLs', cause: e })));
+        },
+        subscribeWallet(state) {
+            const { appliedIndex } = state.progress;
+            const bufferSize = config.indexerClientConnection.bufferSize ?? 10000;
+            const resumeThreshold = config.indexerClientConnection.resumeThreshold ?? 100;
+            // The boundary is load-bearing, not waste: this subscription emits only events (no tip/progress
+            // sentinel), and `isConnected`/the tip (`maxId`) are set only when an event is received. So the
+            // cursor must stay `<= appliedIndex` — never `appliedIndex + 1`. Requesting one event later would
+            // deliver nothing to a wallet already at the tip, so `applyUpdate` would never run and sync would
+            // hang.
+            //
+            // A fresh wallet has `appliedIndex === 0n` (the "nothing applied yet" sentinel), so `resumeFrom`
+            // is `-1n` and the `variables` mapping below opens the subscription with no `id` — the indexer
+            // streams from the very start. A restored wallet has `appliedIndex >= 1`, so `resumeFrom` is
+            // `appliedIndex - 1` and the inclusive cursor re-delivers the boundary event.
+            const resumeFrom = appliedIndex - 1n;
+            return pipe(
+            // Backpressure caps the in-flight queue between the WS push and the
+            // apply loop. Without it the JS heap grows linearly with catch-up
+            // depth, since `Stream.asyncPush({ bufferSize: 'unbounded' })`
+            // buffers every event the indexer pushes regardless of apply rate.
+            DustLedgerEvents.runWithBackpressure({
+                bufferSize,
+                resumeThreshold,
+                from: resumeFrom,
+                // `resumeFrom < 0n` means a fresh wallet: send no `id` so the indexer streams from the very
+                // start, rather than relying on `id: 0` sorting below the first real event id.
+                variables: (cursor) => ({ id: cursor < 0n ? null : Number(cursor) }),
+                key: (r) => BigInt(r.dustLedgerEvents.id),
+            }), Stream.mapEffect((subscription) => pipe(Schema.decodeUnknownEither(SyncEventsUpdateSchema)(subscription.dustLedgerEvents), Either.mapLeft((err) => new SyncWalletError(err)), EitherOps.toEffect)), Stream.mapError((error) => new SyncWalletError(error)));
+        },
+    };
+};
+export const makeDefaultSyncCapability = () => {
+    return {
+        applyUpdate(state, wrappedUpdate) {
+            const { updates, secretKey } = wrappedUpdate;
+            // Nothing to update yet
+            if (updates.length === 0) {
+                return [state, { changes: [], protocolVersion: Number(state.protocolVersion) }];
+            }
+            const appliedIndex = state.progress.appliedIndex;
+            const freshUpdates = updates.filter((u) => BigInt(u.id) > appliedIndex);
+            const highestRelevantWalletIndex = BigInt(updates.at(-1).maxId);
+            const [newState, changes] = freshUpdates.length === 0
+                ? [state, []]
+                : CoreWallet.applyEventsWithChanges(state, secretKey, freshUpdates.map((u) => u.raw), wrappedUpdate.timestamp);
+            const updatedState = CoreWallet.updateProgress(newState, {
+                appliedIndex: freshUpdates.length === 0 ? appliedIndex : BigInt(freshUpdates.at(-1).id),
+                highestRelevantWalletIndex,
+                isConnected: true,
+            });
+            return [updatedState, { changes, protocolVersion: Number(updatedState.protocolVersion) }];
+        },
+    };
+};
+export const makeSimulatorSyncService = (config) => {
+    return {
+        updates: (_state, secretKey) => {
+            // Get the initial state immediately to ensure we process the genesis block.
+            // Then subscribe to state$ for subsequent changes, but deduplicate by block number
+            // to avoid processing the same block twice.
+            let lastSeenBlockNumber;
+            return pipe(Stream.fromEffect(config.simulator.getLatestState()), Stream.concat(config.simulator.state$), Stream.filter((state) => {
+                const lastBlock = getLastBlock(state);
+                if (lastBlock === undefined) {
+                    return false; // Skip blank state
+                }
+                const blockNumber = lastBlock.number;
+                // Skip if we've already seen this block (deduplication)
+                if (lastSeenBlockNumber !== undefined && blockNumber <= lastSeenBlockNumber) {
+                    return false;
+                }
+                lastSeenBlockNumber = blockNumber;
+                return true;
+            }), Stream.map((state) => ({ update: state, secretKey })));
+        },
+        blockData: () => {
+            return Effect.gen(function* () {
+                const state = yield* config.simulator.getLatestState();
+                const lastBlock = getLastBlock(state);
+                // Use currentTime instead of lastBlock.timestamp for time-sensitive operations
+                // (e.g., Dust generation calculation). The currentTime reflects any fast-forwarding
+                // that has been done, while lastBlock.timestamp only reflects when the block was produced.
+                return {
+                    hash: lastBlock.hash,
+                    height: Number(lastBlock.number),
+                    ledgerParameters: state.ledger.parameters,
+                    timestamp: state.currentTime,
+                };
+            });
+        },
+    };
+};
+export const makeSimulatorSyncCapability = () => {
+    return {
+        applyUpdate: (state, update) => {
+            const lastBlock = getLastBlock(update.update);
+            // If no block exists yet (blank simulator), skip update
+            if (lastBlock === undefined) {
+                return [state, { changes: [], protocolVersion: Number(state.protocolVersion) }];
+            }
+            // Get all events from blocks starting at appliedIndex (the next block to process).
+            // appliedIndex semantics: the first block number we haven't processed yet.
+            // Initial: appliedIndex = 0 (haven't processed any blocks)
+            // After processing block N: appliedIndex = N + 1 (next block to process)
+            const events = [...getBlockEventsFrom(update.update, state.progress.appliedIndex)];
+            const [newState, changes] = CoreWallet.applyEventsWithChanges(state, update.secretKey, events, lastBlock.timestamp);
+            const updatedState = CoreWallet.updateProgress(newState, {
+                appliedIndex: lastBlock.number + 1n,
+            });
+            return [updatedState, { changes, protocolVersion: Number(updatedState.protocolVersion) }];
+        },
+    };
+};

package/dist/v1/Transacting.d.ts

@@ -0,0 +1,97 @@
+import { Either, Option } from 'effect';
+import { type DustSecretKey, type Signature, type SignatureVerifyingKey, type FinalizedTransaction, type ProofErasedTransaction, type UnprovenTransaction, type LedgerParameters } from '@midnight-ntwrk/ledger-v8';
+import { type DustAddress } from '@midnightntwrk/wallet-sdk-address-format';
+import { type WalletError } from './WalletError.js';
+import { CoreWallet } from './CoreWallet.js';
+import { type AnyTransaction, type Dust, type NetworkId, type TotalCostParameters } from './types/index.js';
+import { type CoinsAndBalancesCapability, type CoinSelection, type CoinWithValue, type UtxoWithFullDustDetails } from './CoinsAndBalances.js';
+import { type KeysCapability } from './Keys.js';
+/**
+ * Result of splitting Night UTxOs into the guaranteed/fallible sections of a Dust registration or deregistration
+ * intent, together with the fee-payment allowance the registration may claim from dust generated by the guaranteed
+ * UTxO.
+ *
+ * For deregistration, `feePayment` is always `0n`.
+ */
+export type NightUtxoSplitForDustRegistration = {
+    readonly guaranteedUtxos: ReadonlyArray<UtxoWithFullDustDetails>;
+    readonly fallibleUtxos: ReadonlyArray<UtxoWithFullDustDetails>;
+    readonly feePayment: bigint;
+};
+export interface TransactingCapability<TSecrets, TState, _TTransaction> {
+    readonly networkId: NetworkId;
+    readonly costParams: TotalCostParameters;
+    createDustGenerationTransaction(currentTime: Date, ttl: Date, nightUtxos: ReadonlyArray<UtxoWithFullDustDetails>, nightVerifyingKey: SignatureVerifyingKey, dustReceiverAddress: DustAddress | undefined): Either.Either<UnprovenTransaction, WalletError>;
+    /**
+     * Decides which Night UTxOs belong in the guaranteed vs fallible section of a dust registration/deregistration
+     * transaction, and computes the fee-payment allowance the registration may claim from dust generated by the
+     * guaranteed UTxO.
+     *
+     * For deregistration (`isRegistration === false`) the fee-payment allowance is always `0n`.
+     */
+    splitNightUtxosForDustRegistration(utxosWithDustValue: ReadonlyArray<UtxoWithFullDustDetails>, isRegistration: boolean): NightUtxoSplitForDustRegistration;
+    /**
+     * Attaches a Dust registration / deregistration action onto the intent (at segment 1) of an unproven transaction
+     * whose offers have already been built (typically by the unshielded wallet's `rotateUtxos`). The Night UTxOs are
+     * assumed to already appear in the intent's guaranteed/fallible offers and to already be booked in the unshielded
+     * wallet state.
+     */
+    attachDustRegistration(transaction: UnprovenTransaction, currentTime: Date, nightVerifyingKey: SignatureVerifyingKey, dustReceiverAddress: DustAddress | undefined, feePayment: bigint): Either.Either<UnprovenTransaction, WalletError>;
+    addDustGenerationSignature(transaction: UnprovenTransaction, signature: Signature): Either.Either<UnprovenTransaction, WalletError>;
+    /**
+     * Attaches a signature to the DustRegistration in segment 1's `dustActions` only. Unlike
+     * {@link addDustGenerationSignature}, this does NOT touch the unshielded offers — those are expected to be signed 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): Either.Either<UnprovenTransaction, WalletError>;
+    calculateFee(transaction: AnyTransaction, ledgerParams: LedgerParameters): bigint;
+    estimateFee(secretKey: TSecrets, state: TState, transactions: ReadonlyArray<AnyTransaction>, ttl: Date, currentTime: Date, ledgerParams: LedgerParameters): Either.Either<bigint, WalletError>;
+    balanceTransactions(secretKey: TSecrets, state: TState, transactions: ReadonlyArray<AnyTransaction>, ttl: Date, currentTime: Date, ledgerParams: LedgerParameters): Either.Either<[UnprovenTransaction, TState], WalletError>;
+    revertTransaction(state: TState, transaction: AnyTransaction): Either.Either<TState, WalletError>;
+}
+export type DefaultTransactingConfiguration = {
+    networkId: NetworkId;
+    costParameters: TotalCostParameters;
+};
+export type DefaultTransactingContext = {
+    coinSelection: CoinSelection;
+    coinsAndBalancesCapability: CoinsAndBalancesCapability<CoreWallet>;
+    keysCapability: KeysCapability<CoreWallet>;
+};
+export declare const makeDefaultTransactingCapability: (config: DefaultTransactingConfiguration, getContext: () => DefaultTransactingContext) => TransactingCapability<DustSecretKey, CoreWallet, FinalizedTransaction>;
+export declare const makeSimulatorTransactingCapability: (config: DefaultTransactingConfiguration, getContext: () => DefaultTransactingContext) => TransactingCapability<DustSecretKey, CoreWallet, ProofErasedTransaction>;
+/**
+ * Distributes the fee across multiple inputs, draining smaller inputs first when the fee exceeds any single input's
+ * value. Finds the next available intent segment id in a transaction.
+ *
+ * Fallible intent segments occupy the range `[1, 65535]`; segment `0` is reserved for the guaranteed section and is
+ * never returned.
+ *
+ * @param transaction - Transaction whose intent map is inspected.
+ * @returns `Some(segmentId)` with the lowest unused id, or `None` if all 65535 fallible segments are taken.
+ */
+export declare const findAvailableSegmentId: (transaction: AnyTransaction) => Option.Option<number>;
+export declare class TransactingCapabilityImplementation<TTransaction extends AnyTransaction> implements TransactingCapability<DustSecretKey, CoreWallet, TTransaction> {
+    readonly networkId: string;
+    readonly costParams: TotalCostParameters;
+    readonly getCoinSelection: () => CoinSelection;
+    readonly getCoins: () => CoinsAndBalancesCapability<CoreWallet>;
+    readonly getKeys: () => KeysCapability<CoreWallet>;
+    constructor(networkId: NetworkId, costParams: TotalCostParameters, getCoinSelection: () => CoinSelection, getCoins: () => CoinsAndBalancesCapability<CoreWallet>, getKeys: () => KeysCapability<CoreWallet>);
+    createDustGenerationTransaction(currentTime: Date, ttl: Date, nightUtxos: ReadonlyArray<UtxoWithFullDustDetails>, nightVerifyingKey: SignatureVerifyingKey, dustReceiverAddress: DustAddress | undefined): Either.Either<UnprovenTransaction, WalletError>;
+    splitNightUtxosForDustRegistration(utxosWithDustValue: ReadonlyArray<UtxoWithFullDustDetails>, isRegistration: boolean): NightUtxoSplitForDustRegistration;
+    attachDustRegistration(transaction: UnprovenTransaction, currentTime: Date, nightVerifyingKey: SignatureVerifyingKey, dustReceiverAddress: DustAddress | undefined, feePayment: bigint): Either.Either<UnprovenTransaction, WalletError>;
+    addDustRegistrationSignature(transaction: UnprovenTransaction, signatureData: Signature): Either.Either<UnprovenTransaction, WalletError>;
+    addDustGenerationSignature(transaction: UnprovenTransaction, signatureData: Signature): Either.Either<UnprovenTransaction, WalletError>;
+    calculateFee(transaction: AnyTransaction, ledgerParams: LedgerParameters): bigint;
+    dryRunFee(recipeInputs: ReadonlyArray<CoinWithValue<Dust>>, transactions: ReadonlyArray<FinalizedTransaction | UnprovenTransaction>, secretKey: DustSecretKey, state: CoreWallet, ttl: Date, currentTime: Date, ledgerParams: LedgerParameters): bigint;
+    static feeImbalance(transaction: AnyTransaction, totalFee: bigint): bigint;
+    computeBalancingRecipe(secretKey: DustSecretKey, state: CoreWallet, transactions: ReadonlyArray<FinalizedTransaction | UnprovenTransaction>, ttl: Date, currentTime: Date, ledgerParams: LedgerParameters): Either.Either<{
+        fee: bigint;
+        recipeInputs: ReadonlyArray<CoinWithValue<Dust>>;
+    }, WalletError>;
+    estimateFee(secretKey: DustSecretKey, state: CoreWallet, transactions: ReadonlyArray<FinalizedTransaction | UnprovenTransaction>, ttl: Date, currentTime: Date, ledgerParams: LedgerParameters): Either.Either<bigint, WalletError>;
+    balanceTransactions(secretKey: DustSecretKey, state: CoreWallet, transactions: ReadonlyArray<FinalizedTransaction | UnprovenTransaction>, ttl: Date, currentTime: Date, ledgerParams: LedgerParameters): Either.Either<[UnprovenTransaction, CoreWallet], WalletError>;
+    revertTransaction(state: CoreWallet, transaction: UnprovenTransaction | TTransaction): Either.Either<CoreWallet, WalletError>;
+}

package/dist/v1/Transacting.js

@@ -0,0 +1,327 @@
+// 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 { Effect, Either, pipe, BigInt as BigIntOps, Iterable as IterableOps, Option } from 'effect';
+import { DustActions, DustRegistration, Intent, SignatureEnabled, Transaction, UnshieldedOffer, addressFromKey, nativeToken, } from '@midnight-ntwrk/ledger-v8';
+import { OtherWalletError, TransactingError, InsufficientFundsError } from './WalletError.js';
+import { LedgerOps } from '@midnightntwrk/wallet-sdk-utilities';
+import { CoreWallet } from './CoreWallet.js';
+import { BindingMarker, ProofMarker, SignatureMarker } from './Utils.js';
+import { getBalanceRecipe, Imbalances as CapImbalances, InsufficientFundsError as BalancingInsufficientFundsError, } from '@midnightntwrk/wallet-sdk-capabilities';
+export const makeDefaultTransactingCapability = (config, getContext) => {
+    return new TransactingCapabilityImplementation(config.networkId, config.costParameters, () => getContext().coinSelection, () => getContext().coinsAndBalancesCapability, () => getContext().keysCapability);
+};
+export const makeSimulatorTransactingCapability = (config, getContext) => {
+    return new TransactingCapabilityImplementation(config.networkId, config.costParameters, () => getContext().coinSelection, () => getContext().coinsAndBalancesCapability, () => getContext().keysCapability);
+};
+/**
+ * Distributes the fee across multiple inputs, draining smaller inputs first when the fee exceeds any single input's
+ * value. Finds the next available intent segment id in a transaction.
+ *
+ * Fallible intent segments occupy the range `[1, 65535]`; segment `0` is reserved for the guaranteed section and is
+ * never returned.
+ *
+ * @param transaction - Transaction whose intent map is inspected.
+ * @returns `Some(segmentId)` with the lowest unused id, or `None` if all 65535 fallible segments are taken.
+ */
+export const findAvailableSegmentId = (transaction) => {
+    const used = new Set(transaction.intents?.keys() ?? []);
+    return pipe(IterableOps.range(1, 65535), IterableOps.findFirst((segmentId) => !used.has(segmentId)));
+};
+/**
+ * Distributes the fee across multiple inputs, draining smaller inputs first when the fee exceeds any single input's
+ * value.
+ */
+const distributeFeeAcrossInputs = (inputs, fee) => inputs.reduce(({ result, remaining }, input) => {
+    const deduction = remaining >= input.value ? input.value : remaining;
+    return { result: [...result, { ...input, value: deduction }], remaining: remaining - deduction };
+}, { result: [], remaining: fee }).result;
+export class TransactingCapabilityImplementation {
+    networkId;
+    costParams;
+    getCoinSelection;
+    getCoins;
+    getKeys;
+    constructor(networkId, costParams, getCoinSelection, getCoins, getKeys) {
+        this.getCoins = getCoins;
+        this.networkId = networkId;
+        this.costParams = costParams;
+        this.getCoinSelection = getCoinSelection;
+        this.getKeys = getKeys;
+    }
+    createDustGenerationTransaction(currentTime, ttl, nightUtxos, nightVerifyingKey, dustReceiverAddress) {
+        const makeOffer = (utxos) => {
+            if (utxos.length === 0) {
+                return Option.none();
+            }
+            const totalValue = pipe(utxos, IterableOps.map((coin) => coin.utxo.value), BigIntOps.sumAll);
+            const inputs = utxos.map(({ utxo }) => ({
+                ...utxo,
+                owner: nightVerifyingKey,
+            }));
+            const output = {
+                owner: addressFromKey(nightVerifyingKey),
+                type: nativeToken().raw,
+                value: totalValue,
+            };
+            return Option.some(UnshieldedOffer.new(inputs, [output], []));
+        };
+        return Either.gen(this, function* () {
+            const receiver = dustReceiverAddress ? dustReceiverAddress.data : undefined;
+            return yield* LedgerOps.ledgerTry(() => {
+                const network = this.networkId;
+                const splitResult = this.getCoins().splitNightUtxos(nightUtxos);
+                // if receiver is `undefined`, it means the coin(s) are being deregistered so the allowFeePayment should not be used
+                const feePayment = receiver
+                    ? pipe(splitResult.guaranteed, IterableOps.filter((coin) => !coin.utxo.registeredForDustGeneration), IterableOps.map((coin) => coin.dust.generatedNow), BigIntOps.sumAll)
+                    : 0n;
+                const maybeGuaranteedOffer = makeOffer(splitResult.guaranteed);
+                const maybeFallibleOffer = makeOffer(splitResult.fallible);
+                const dustRegistration = new DustRegistration(SignatureMarker.signature, nightVerifyingKey, receiver, feePayment);
+                const dustActions = new DustActions(SignatureMarker.signature, ProofMarker.preProof, currentTime, [], [dustRegistration]);
+                const intent = pipe(Intent.new(ttl), (intent) => Option.match(maybeGuaranteedOffer, {
+                    onNone: () => intent,
+                    onSome: (guaranteedOffer) => {
+                        intent.guaranteedUnshieldedOffer = guaranteedOffer;
+                        return intent;
+                    },
+                }), (intent) => Option.match(maybeFallibleOffer, {
+                    onNone: () => intent,
+                    onSome: (fallibleOffer) => {
+                        intent.fallibleUnshieldedOffer = fallibleOffer;
+                        return intent;
+                    },
+                }), (intent) => {
+                    intent.dustActions = dustActions;
+                    return intent;
+                });
+                return Transaction.fromParts(network, undefined, undefined, intent);
+            });
+        });
+    }
+    splitNightUtxosForDustRegistration(utxosWithDustValue, isRegistration) {
+        const splitResult = this.getCoins().splitNightUtxos(utxosWithDustValue);
+        // Deregistration must not claim dust as fee payment (matches the historical
+        // `dustReceiverAddress === undefined` branch of createDustGenerationTransaction).
+        const feePayment = isRegistration
+            ? pipe(splitResult.guaranteed, IterableOps.filter((coin) => !coin.utxo.registeredForDustGeneration), IterableOps.map((coin) => coin.dust.generatedNow), BigIntOps.sumAll)
+            : 0n;
+        return {
+            guaranteedUtxos: splitResult.guaranteed,
+            fallibleUtxos: splitResult.fallible,
+            feePayment,
+        };
+    }
+    attachDustRegistration(transaction, currentTime, nightVerifyingKey, dustReceiverAddress, feePayment) {
+        return Either.gen(this, function* () {
+            const intent = transaction.intents?.get(1);
+            if (!intent) {
+                return yield* Either.left(new TransactingError({
+                    message: 'No intent found at segment 1; expected an intent built by rotateUtxos',
+                }));
+            }
+            if (intent.dustActions !== undefined && intent.dustActions.registrations.length > 0) {
+                return yield* Either.left(new TransactingError({ message: 'Intent at segment 1 already has a dust registration attached' }));
+            }
+            return yield* LedgerOps.ledgerTry(() => {
+                const receiver = dustReceiverAddress ? dustReceiverAddress.data : undefined;
+                const dustRegistration = new DustRegistration(SignatureMarker.signature, nightVerifyingKey, receiver, feePayment);
+                const dustActions = new DustActions(SignatureMarker.signature, ProofMarker.preProof, currentTime, [], [dustRegistration]);
+                // Intents fetched from `transaction.intents.get(...)` behave like value copies — assigning
+                // to a field doesn't propagate back. Match the addDustGenerationSignature pattern: copy the
+                // intent via serialize/deserialize, mutate the copy, then set it back into a fresh
+                // transaction's intents map.
+                const newIntent = Intent.deserialize(SignatureMarker.signature, ProofMarker.preProof, BindingMarker.preBinding, intent.serialize());
+                newIntent.dustActions = dustActions;
+                const newTransaction = Transaction.deserialize(SignatureMarker.signature, ProofMarker.preProof, BindingMarker.preBinding, transaction.serialize());
+                newTransaction.intents = newTransaction.intents.set(1, newIntent);
+                return newTransaction;
+            });
+        });
+    }
+    addDustRegistrationSignature(transaction, signatureData) {
+        return Either.gen(this, function* () {
+            const intent = transaction.intents?.get(1);
+            if (!intent) {
+                return yield* Either.left(new TransactingError({ message: 'No intent found in the transaction intents with segment = 1' }));
+            }
+            const { dustActions } = intent;
+            if (!dustActions) {
+                return yield* Either.left(new TransactingError({ message: 'No dustActions found in intent' }));
+            }
+            const [registration, ...restRegistrations] = dustActions.registrations;
+            if (!registration) {
+                return yield* Either.left(new TransactingError({ message: 'No registrations found in dustActions' }));
+            }
+            return yield* LedgerOps.ledgerTry(() => {
+                const signature = new SignatureEnabled(signatureData);
+                const registrationWithSignature = new DustRegistration(signature.instance, registration.nightKey, registration.dustAddress, registration.allowFeePayment, signature);
+                const newDustActions = new DustActions(signature.instance, ProofMarker.preProof, dustActions.ctime, dustActions.spends, [registrationWithSignature, ...restRegistrations]);
+                const newIntent = Intent.deserialize(signature.instance, ProofMarker.preProof, BindingMarker.preBinding, intent.serialize());
+                newIntent.dustActions = newDustActions;
+                const newTransaction = Transaction.deserialize(signature.instance, ProofMarker.preProof, BindingMarker.preBinding, transaction.serialize());
+                newTransaction.intents = newTransaction.intents.set(1, newIntent);
+                return newTransaction;
+            });
+        });
+    }
+    addDustGenerationSignature(transaction, signatureData) {
+        return Either.gen(this, function* () {
+            const intent = transaction.intents?.get(1);
+            if (!intent) {
+                return yield* Either.left(new TransactingError({ message: 'No intent found in the transaction intents with segment = 1' }));
+            }
+            const { dustActions, guaranteedUnshieldedOffer, fallibleUnshieldedOffer } = intent;
+            if (!dustActions) {
+                return yield* Either.left(new TransactingError({ message: 'No dustActions found in intent' }));
+            }
+            if (!guaranteedUnshieldedOffer) {
+                return yield* Either.left(new TransactingError({ message: 'No guaranteedUnshieldedOffer found in intent' }));
+            }
+            const [registration, ...restRegistrations] = dustActions.registrations;
+            if (!registration) {
+                return yield* Either.left(new TransactingError({ message: 'No registrations found in dustActions' }));
+            }
+            return yield* LedgerOps.ledgerTry(() => {
+                const signature = new SignatureEnabled(signatureData);
+                const registrationWithSignature = new DustRegistration(signature.instance, registration.nightKey, registration.dustAddress, registration.allowFeePayment, signature);
+                const newDustActions = new DustActions(signature.instance, ProofMarker.preProof, dustActions.ctime, dustActions.spends, [registrationWithSignature, ...restRegistrations]);
+                // make a copy of intent to avoid mutation
+                const newIntent = Intent.deserialize(signature.instance, ProofMarker.preProof, BindingMarker.preBinding, intent.serialize());
+                newIntent.dustActions = newDustActions;
+                const inputsLen = guaranteedUnshieldedOffer.inputs.length;
+                const signatures = [];
+                for (let i = 0; i < inputsLen; ++i) {
+                    signatures.push(guaranteedUnshieldedOffer.signatures.at(i) ?? signatureData);
+                }
+                newIntent.guaranteedUnshieldedOffer = guaranteedUnshieldedOffer.addSignatures(signatures);
+                if (fallibleUnshieldedOffer) {
+                    const inputsLen = fallibleUnshieldedOffer.inputs.length;
+                    const signatures = [];
+                    for (let i = 0; i < inputsLen; ++i) {
+                        signatures.push(fallibleUnshieldedOffer.signatures.at(i) ?? signatureData);
+                    }
+                    newIntent.fallibleUnshieldedOffer = fallibleUnshieldedOffer.addSignatures(signatures);
+                }
+                // make a copy of transaction to avoid mutation
+                const newTransaction = Transaction.deserialize(signature.instance, ProofMarker.preProof, BindingMarker.preBinding, transaction.serialize());
+                newTransaction.intents = newTransaction.intents.set(1, newIntent);
+                return newTransaction;
+            });
+        });
+    }
+    calculateFee(transaction, ledgerParams) {
+        return (transaction.feesWithMargin(ledgerParams, this.costParams.feeBlocksMargin) +
+            (this.costParams.additionalFeeOverhead ?? 0n));
+    }
+    dryRunFee(recipeInputs, transactions, secretKey, state, ttl, currentTime, ledgerParams) {
+        const network = this.networkId;
+        // Create a balancing tx from recipe inputs without persisting state changes
+        const [spends] = CoreWallet.spendCoins(state, secretKey, recipeInputs, currentTime);
+        const intent = Intent.new(ttl);
+        intent.dustActions = new DustActions(SignatureMarker.signature, ProofMarker.preProof, currentTime, [...spends], []);
+        // Merge existing transactions first so we can pick a segment that doesn't collide
+        const [first, ...rest] = transactions.map((tx) => tx.eraseProofs());
+        const mergedExisting = first ? rest.reduce((acc, tx) => acc.merge(tx), first) : undefined;
+        const segmentId = mergedExisting ? Option.getOrElse(findAvailableSegmentId(mergedExisting), () => 1) : 1;
+        const balancingTx = Transaction.fromParts(network).addIntent({ tag: 'specific', value: segmentId }, intent);
+        const erasedBalancing = balancingTx.eraseProofs();
+        const mergedTx = mergedExisting ? mergedExisting.merge(erasedBalancing) : erasedBalancing;
+        return this.calculateFee(mergedTx, ledgerParams);
+    }
+    static feeImbalance(transaction, totalFee) {
+        const [_, imbalance] = transaction
+            .imbalances(0, totalFee)
+            .entries()
+            .find(([tt, _]) => tt.tag === 'dust') ?? [];
+        return imbalance ?? 0n;
+    }
+    computeBalancingRecipe(secretKey, state, transactions, ttl, currentTime, ledgerParams) {
+        const initialFees = transactions.reduce((total, transaction) => total +
+            TransactingCapabilityImplementation.feeImbalance(transaction, this.calculateFee(transaction, ledgerParams)), 0n);
+        const dust = this.getCoins().getAvailableCoinsWithGeneratedDust(state, currentTime);
+        return pipe(Effect.iterate({ currentFee: initialFees, recipeInputs: [], converged: false }, {
+            while: (s) => !s.converged,
+            body: ({ currentFee }) => Effect.try({
+                try: () => {
+                    const recipe = getBalanceRecipe({
+                        coins: dust.map((coin) => ({
+                            type: 'dust',
+                            value: coin.value,
+                            token: coin.token,
+                        })),
+                        initialImbalances: CapImbalances.fromEntry('dust', currentFee),
+                        feeTokenType: 'dust',
+                        coinSelection: this.getCoinSelection(),
+                        transactionCostModel: {
+                            inputFeeOverhead: 0n,
+                            outputFeeOverhead: 0n,
+                        },
+                        createOutput: (coin) => coin,
+                        isCoinEqual: (a, b) => a.token.nonce === b.token.nonce,
+                    });
+                    const recipeInputs = recipe.inputs.map(({ token, value }) => ({ token, value }));
+                    const newFee = this.dryRunFee(recipeInputs, transactions, secretKey, state, ttl, currentTime, ledgerParams);
+                    const recipeAmountCoverage = recipeInputs.reduce((sum, input) => sum + input.value, 0n);
+                    return { currentFee: newFee, recipeInputs, converged: newFee <= recipeAmountCoverage };
+                },
+                catch: (err) => {
+                    if (err instanceof BalancingInsufficientFundsError) {
+                        return new InsufficientFundsError({
+                            message: err.message,
+                            tokenType: err.tokenType,
+                        });
+                    }
+                    else {
+                        return new OtherWalletError({
+                            message: err instanceof Error ? err.message : 'Dust balancing failed',
+                            cause: err,
+                        });
+                    }
+                },
+            }),
+        }), Effect.either, Effect.runSync, Either.map(({ currentFee, recipeInputs }) => ({
+            fee: currentFee,
+            recipeInputs: distributeFeeAcrossInputs(recipeInputs, currentFee),
+        })));
+    }
+    estimateFee(secretKey, state, transactions, ttl, currentTime, ledgerParams) {
+        return pipe(this.computeBalancingRecipe(secretKey, state, transactions, ttl, currentTime, ledgerParams), Either.map(({ fee }) => fee));
+    }
+    balanceTransactions(secretKey, state, transactions, ttl, currentTime, ledgerParams) {
+        const networkId = this.networkId;
+        return pipe(this.computeBalancingRecipe(secretKey, state, transactions, ttl, currentTime, ledgerParams), Either.flatMap(({ recipeInputs }) => {
+            return LedgerOps.ledgerTry(() => {
+                const intent = Intent.new(ttl);
+                const [spends, updatedState] = CoreWallet.spendCoins(state, secretKey, recipeInputs, currentTime);
+                intent.dustActions = new DustActions(SignatureMarker.signature, ProofMarker.preProof, currentTime, [...spends], []);
+                // Merge existing transactions first so we can pick a segment that doesn't collide
+                const [first, ...rest] = transactions.map((tx) => tx.eraseProofs());
+                const mergedExisting = first ? rest.reduce((acc, tx) => acc.merge(tx), first) : undefined;
+                const segmentId = mergedExisting ? Option.getOrElse(findAvailableSegmentId(mergedExisting), () => 1) : 1;
+                const feeTransaction = Transaction.fromParts(networkId).addIntent({ tag: 'specific', value: segmentId }, intent);
+                return [feeTransaction, updatedState];
+            });
+        }));
+    }
+    revertTransaction(state, transaction) {
+        return Either.try({
+            try: () => CoreWallet.revertTransaction(state, transaction),
+            catch: (err) => {
+                return new OtherWalletError({
+                    message: `Error while reverting transaction ${transaction.identifiers().at(0)}`,
+                    cause: err,
+                });
+            },
+        });
+    }
+}