@midnight-ntwrk/wallet-sdk-shielded 1.0.0-beta.10

package/dist/v1/Sync.js

@@ -0,0 +1,139 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) 2025 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-v6';
+import { Effect, ParseResult, Stream, Schema, pipe, Either } from 'effect';
+import { CoreWallet } from './CoreWallet.js';
+import { ZswapEvents } from '@midnight-ntwrk/wallet-sdk-indexer-client';
+import { WsSubscriptionClient, ConnectionHelper } from '@midnight-ntwrk/wallet-sdk-indexer-client/effect';
+import { SyncWalletError } from './WalletError.js';
+import { WsURL } from '@midnight-ntwrk/wallet-sdk-utilities/networking';
+import { EitherOps } from '@midnight-ntwrk/wallet-sdk-utilities';
+const Uint8ArraySchema = Schema.declare((input) => input instanceof Uint8Array).annotations({
+    identifier: 'Uint8Array',
+});
+export const SecretKeysResource = {
+    create: (secretKeys) => {
+        /**
+         * TODO: future Ledger version will include `clear` function to clear the secret keys,
+         * it is intentend to be used here instead of `null`
+         */
+        let sk = secretKeys;
+        return (cb) => {
+            if (sk === null) {
+                throw new Error('Secret keys have been consumed');
+            }
+            const result = cb(sk);
+            sk = null;
+            return result;
+        };
+    },
+};
+export const WalletSyncUpdate = {
+    create: (update, secretKeys) => {
+        return {
+            update,
+            secretKeys: SecretKeysResource.create(secretKeys),
+        };
+    },
+};
+const LedgerEventSchema = Schema.declare((input) => input instanceof ledger.Event).annotations({
+    identifier: 'ledger.Event',
+});
+const LedgerEventFromUint8Array = Schema.transformOrFail(Uint8ArraySchema, LedgerEventSchema, {
+    encode: (event) => Effect.try({
+        try: () => event.serialize(),
+        catch: (error) => new ParseResult.Unexpected(error, 'Could not serialize ledger event'),
+    }),
+    decode: (bytes) => Effect.try({
+        try: () => ledger.Event.deserialize(bytes),
+        catch: (error) => new ParseResult.Unexpected(error, 'Could not deserialize ledger event'),
+    }),
+});
+const HexedLedgerEvent = pipe(Schema.Uint8ArrayFromHex, Schema.compose(LedgerEventFromUint8Array));
+const EventsSyncUpdatePayload = Schema.Struct({
+    id: Schema.Number,
+    raw: Schema.String,
+    maxId: Schema.Number,
+});
+export const EventsSyncUpdate = Schema.TaggedStruct('EventsSyncUpdate', {
+    id: Schema.Number,
+    maxId: Schema.Number,
+    event: LedgerEventSchema,
+});
+const EventsSyncUpdateFromPayload = Schema.transformOrFail(EventsSyncUpdatePayload, EventsSyncUpdate, {
+    decode: (input) => pipe(Schema.decodeUnknownEither(HexedLedgerEvent)(input.raw), Either.map((event) => ({
+        _tag: 'EventsSyncUpdate',
+        id: input.id,
+        maxId: input.maxId,
+        event,
+    })), Either.mapLeft((error) => new ParseResult.Unexpected(error, 'Failed to decode ledger event payload')), EitherOps.toEffect),
+    encode: (output) => pipe(Schema.encodeEither(HexedLedgerEvent)(output.event), Either.map((raw) => ({
+        id: output.id,
+        raw,
+        maxId: output.maxId,
+    })), Either.mapLeft((error) => new ParseResult.Unexpected(error, 'Failed to encode ledger event payload')), EitherOps.toEffect),
+});
+export const makeEventsSyncService = (config) => {
+    return {
+        updates: (state, secretKeys) => {
+            const { indexerClientConnection } = config;
+            const webSocketUrlResult = ConnectionHelper.createWebSocketUrl(indexerClientConnection.indexerHttpUrl, indexerClientConnection.indexerWsUrl);
+            if (Either.isLeft(webSocketUrlResult)) {
+                return Stream.fail(new SyncWalletError(new Error(`Could not derive WebSocket URL from indexer HTTP URL: ${webSocketUrlResult.left.message}`)));
+            }
+            const indexerWsUrlResult = WsURL.make(webSocketUrlResult.right);
+            if (Either.isLeft(indexerWsUrlResult)) {
+                return Stream.fail(new SyncWalletError(new Error(`Invalid indexer WS URL: ${indexerWsUrlResult.left.message}`)));
+            }
+            const indexerWsUrl = indexerWsUrlResult.right;
+            const appliedIndex = state.progress?.appliedIndex ?? 0n;
+            return pipe(ZswapEvents.run({ id: Number(appliedIndex) }), Stream.provideLayer(WsSubscriptionClient.layer({ url: indexerWsUrl })), Stream.mapError((error) => new SyncWalletError(error)), Stream.mapEffect((subscription) => pipe(Schema.decodeUnknownEither(EventsSyncUpdateFromPayload)(subscription.zswapLedgerEvents), Either.mapLeft((err) => new SyncWalletError(err)), EitherOps.toEffect)), Stream.map((data) => WalletSyncUpdate.create(data, secretKeys)));
+        },
+    };
+};
+export const makeEventsSyncCapability = () => {
+    return {
+        applyUpdate: (state, wrappedUpdate) => {
+            const nextIndex = BigInt(wrappedUpdate.update.id);
+            const highestRelevantWalletIndex = BigInt(wrappedUpdate.update.maxId);
+            // in case the nextIndex is less than or equal to the appliedIndex
+            // just update highestRelevantWalletIndex
+            if (nextIndex <= state.progress.appliedIndex) {
+                return CoreWallet.updateProgress(state, {
+                    highestRelevantWalletIndex,
+                    isConnected: true,
+                });
+            }
+            return wrappedUpdate.secretKeys((keys) => {
+                return CoreWallet.updateProgress(CoreWallet.replayEvents(state, keys, [wrappedUpdate.update.event]), {
+                    highestRelevantWalletIndex,
+                    appliedIndex: nextIndex,
+                    isConnected: true,
+                });
+            });
+        },
+    };
+};
+export const makeSimulatorSyncService = (config) => {
+    return {
+        updates: (_state, secretKeys) => config.simulator.state$.pipe(Stream.map((state) => ({ update: state, secretKeys: secretKeys }))),
+    };
+};
+export const makeSimulatorSyncCapability = () => {
+    return {
+        applyUpdate: (state, update) => {
+            const { update: { lastTxResult: { events }, }, secretKeys, } = update;
+            return CoreWallet.replayEvents(state, secretKeys, events);
+        },
+    };
+};

package/dist/v1/SyncProgress.d.ts

@@ -0,0 +1,22 @@
+export interface SyncProgressData {
+    readonly appliedIndex: bigint;
+    readonly highestRelevantWalletIndex: bigint;
+    readonly highestIndex: bigint;
+    readonly highestRelevantIndex: bigint;
+    readonly isConnected: boolean;
+}
+export interface SyncProgressOps {
+    isCompleteWithin(data: SyncProgressData, maxGap?: bigint): boolean;
+}
+export interface SyncProgress extends SyncProgressData {
+    isStrictlyComplete(): boolean;
+    isCompleteWithin(maxGap?: bigint): boolean;
+}
+export declare const SyncProgress: SyncProgressOps;
+export declare const createSyncProgress: (params?: {
+    appliedIndex?: bigint;
+    highestRelevantWalletIndex?: bigint;
+    highestIndex?: bigint;
+    highestRelevantIndex?: bigint;
+    isConnected?: boolean;
+}) => SyncProgress;

package/dist/v1/SyncProgress.js

@@ -0,0 +1,25 @@
+export const SyncProgress = {
+    isCompleteWithin(data, maxGap = 50n) {
+        const applyLag = BigInt(Math.abs(Number(data.highestRelevantWalletIndex - data.appliedIndex)));
+        return data.isConnected && applyLag <= maxGap;
+    },
+};
+export const createSyncProgress = (params = {}) => {
+    const { appliedIndex = 0n, highestRelevantWalletIndex = 0n, highestIndex = 0n, highestRelevantIndex = 0n, isConnected = false, } = params;
+    const data = {
+        appliedIndex,
+        highestRelevantWalletIndex,
+        highestIndex,
+        highestRelevantIndex,
+        isConnected,
+    };
+    return {
+        ...data,
+        isStrictlyComplete() {
+            return SyncProgress.isCompleteWithin(this, 0n);
+        },
+        isCompleteWithin(maxGap) {
+            return SyncProgress.isCompleteWithin(this, maxGap);
+        },
+    };
+};

package/dist/v1/Transacting.d.ts

@@ -0,0 +1,69 @@
+import * as ledger from '@midnight-ntwrk/ledger-v6';
+import { NetworkId } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { Array as Arr, Either } from 'effect';
+import { ProvingRecipe } from './ProvingRecipe.js';
+import { CoreWallet } from './CoreWallet.js';
+import { WalletError } from './WalletError.js';
+import { CoinSelection } from '@midnight-ntwrk/wallet-sdk-capabilities';
+import { TransactionImbalances } from './TransactionImbalances.js';
+import { TransactionTrait } from './Transaction.js';
+import { CoinsAndBalancesCapability } from './CoinsAndBalances.js';
+import { KeysCapability } from './Keys.js';
+export interface TokenTransfer {
+    readonly amount: bigint;
+    readonly type: ledger.RawTokenType;
+    readonly receiverAddress: string;
+}
+export interface TransactingCapability<TSecrets, TState, TTransaction> {
+    balanceTransaction(secrets: TSecrets, state: TState, tx: ledger.Transaction<ledger.Signaturish, ledger.Proofish, ledger.Bindingish>): Either.Either<{
+        recipe: ProvingRecipe<TTransaction>;
+        newState: TState;
+    }, WalletError>;
+    makeTransfer(secrets: TSecrets, state: TState, outputs: ReadonlyArray<TokenTransfer>): Either.Either<{
+        recipe: ProvingRecipe<TTransaction>;
+        newState: TState;
+    }, WalletError>;
+    initSwap(secrets: TSecrets, state: TState, desiredInputs: Record<ledger.RawTokenType, bigint>, desiredOutputs: ReadonlyArray<TokenTransfer>): Either.Either<{
+        recipe: ProvingRecipe<TTransaction>;
+        newState: TState;
+    }, WalletError>;
+    revert(state: TState, tx: TTransaction): Either.Either<TState, WalletError>;
+    revertRecipe(state: TState, recipe: ProvingRecipe<TTransaction>): Either.Either<TState, WalletError>;
+}
+export type DefaultTransactingConfiguration = {
+    networkId: NetworkId.NetworkId;
+};
+export type DefaultTransactingContext = {
+    coinSelection: CoinSelection<ledger.QualifiedShieldedCoinInfo>;
+    coinsAndBalancesCapability: CoinsAndBalancesCapability<CoreWallet>;
+    keysCapability: KeysCapability<CoreWallet>;
+};
+export declare const makeDefaultTransactingCapability: (config: DefaultTransactingConfiguration, getContext: () => DefaultTransactingContext) => TransactingCapability<ledger.ZswapSecretKeys, CoreWallet, ledger.FinalizedTransaction>;
+export declare const makeSimulatorTransactingCapability: (config: DefaultTransactingConfiguration, getContext: () => DefaultTransactingContext) => TransactingCapability<ledger.ZswapSecretKeys, CoreWallet, ledger.ProofErasedTransaction>;
+export declare class TransactingCapabilityImplementation<TTransaction extends ledger.Transaction<ledger.Signaturish, ledger.Proofish, ledger.Bindingish>> implements TransactingCapability<ledger.ZswapSecretKeys, CoreWallet, TTransaction> {
+    #private;
+    readonly networkId: NetworkId.NetworkId;
+    readonly getCoinSelection: () => CoinSelection<ledger.QualifiedShieldedCoinInfo>;
+    readonly txTrait: TransactionTrait<TTransaction>;
+    readonly getCoins: () => CoinsAndBalancesCapability<CoreWallet>;
+    readonly getKeys: () => KeysCapability<CoreWallet>;
+    constructor(networkId: NetworkId.NetworkId, getCoinSelection: () => CoinSelection<ledger.QualifiedShieldedCoinInfo>, getCoins: () => CoinsAndBalancesCapability<CoreWallet>, getKeys: () => KeysCapability<CoreWallet>, txTrait: TransactionTrait<TTransaction>);
+    balanceTransaction(secretKeys: ledger.ZswapSecretKeys, state: CoreWallet, tx: TTransaction): Either.Either<{
+        recipe: ProvingRecipe<TTransaction>;
+        newState: CoreWallet;
+    }, WalletError>;
+    makeTransfer(secretKeys: ledger.ZswapSecretKeys, state: CoreWallet, transfers: Arr.NonEmptyReadonlyArray<TokenTransfer>): Either.Either<{
+        recipe: ProvingRecipe<TTransaction>;
+        newState: CoreWallet;
+    }, WalletError>;
+    initSwap(secretKeys: ledger.ZswapSecretKeys, state: CoreWallet, desiredInputs: Record<ledger.RawTokenType, bigint>, desiredOutputs: ReadonlyArray<TokenTransfer>): Either.Either<{
+        recipe: ProvingRecipe<TTransaction>;
+        newState: CoreWallet;
+    }, WalletError>;
+    revert(state: CoreWallet, tx: TTransaction): Either.Either<CoreWallet, WalletError>;
+    revertRecipe(state: CoreWallet, recipe: ProvingRecipe<TTransaction>): Either.Either<CoreWallet, WalletError>;
+    balanceFallibleSection(secretKeys: ledger.ZswapSecretKeys, state: CoreWallet, imbalances: TransactionImbalances, coinSelection: CoinSelection<ledger.QualifiedShieldedCoinInfo>): Either.Either<{
+        offer: ledger.ZswapOffer<ledger.PreProof> | undefined;
+        newState: CoreWallet;
+    }, WalletError>;
+}

package/dist/v1/Transacting.js

@@ -0,0 +1,374 @@
+// This file is part of MIDNIGHT-WALLET-SDK.
+// Copyright (C) 2025 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-v6';
+import { Array as Arr, Data, Either, Option, pipe, Record } from 'effect';
+import { ArrayOps, EitherOps } from '@midnight-ntwrk/wallet-sdk-utilities';
+import { BALANCE_TRANSACTION_TO_PROVE, NOTHING_TO_PROVE, TRANSACTION_TO_PROVE, } from './ProvingRecipe.js';
+import { CoreWallet } from './CoreWallet.js';
+import { AddressError, InsufficientFundsError, OtherWalletError } from './WalletError.js';
+import { getBalanceRecipe, Imbalances, InsufficientFundsError as BalancingInsufficientFundsError, } from '@midnight-ntwrk/wallet-sdk-capabilities';
+import { MidnightBech32m, ShieldedAddress } from '@midnight-ntwrk/wallet-sdk-address-format';
+import { ShieldedCostModel, TransactionImbalances } from './TransactionImbalances.js';
+import { TransactionTrait } from './Transaction.js';
+export const makeDefaultTransactingCapability = (config, getContext) => {
+    return new TransactingCapabilityImplementation(config.networkId, () => getContext().coinSelection, () => getContext().coinsAndBalancesCapability, () => getContext().keysCapability, TransactionTrait.default);
+};
+export const makeSimulatorTransactingCapability = (config, getContext) => {
+    return new TransactingCapabilityImplementation(config.networkId, () => getContext().coinSelection, () => getContext().coinsAndBalancesCapability, () => getContext().keysCapability, TransactionTrait.proofErased);
+};
+class NoSelfOutputsError extends Data.TaggedError('NoSelfOutputs') {
+}
+export class TransactingCapabilityImplementation {
+    networkId;
+    getCoinSelection;
+    txTrait;
+    getCoins;
+    getKeys;
+    constructor(networkId, getCoinSelection, getCoins, getKeys, txTrait) {
+        this.getCoins = getCoins;
+        this.networkId = networkId;
+        this.getCoinSelection = getCoinSelection;
+        this.getKeys = getKeys;
+        this.txTrait = txTrait;
+    }
+    balanceTransaction(secretKeys, state, tx) {
+        return Either.gen(this, function* () {
+            const coinSelection = this.getCoinSelection();
+            const networkId = this.networkId;
+            const initialImbalances = this.txTrait.getImbalances(tx);
+            if (TransactionImbalances.areBalanced(initialImbalances)) {
+                return {
+                    recipe: {
+                        type: NOTHING_TO_PROVE,
+                        transaction: tx,
+                    },
+                    newState: state,
+                };
+            }
+            const { newState: afterFallible, offer: maybeFallible } = yield* this.balanceFallibleSection(secretKeys, state, initialImbalances, coinSelection);
+            const { newState: afterGuaranteed, offer: guaranteed } = yield* this.#balanceGuaranteedSection(secretKeys, afterFallible, initialImbalances, coinSelection, 0, Imbalances.empty());
+            return {
+                newState: afterGuaranteed,
+                recipe: {
+                    type: BALANCE_TRANSACTION_TO_PROVE,
+                    transactionToBalance: tx,
+                    transactionToProve: ledger.Transaction.fromParts(networkId, guaranteed, maybeFallible),
+                },
+            };
+        });
+    }
+    makeTransfer(secretKeys, state, transfers) {
+        return Either.gen(this, function* () {
+            const positiveTransfers = yield* pipe(transfers, Arr.filter((t) => t.amount > 0n), Arr.match({
+                onEmpty: () => Either.left(new OtherWalletError({
+                    message: 'The amount needs to be positive',
+                })),
+                onNonEmpty: (nonEmpty) => Either.right(nonEmpty),
+            }));
+            const networkId = this.networkId;
+            const { initialOffersAndCoins, selfCoins } = yield* this.#processDesiredOutputs(state, positiveTransfers);
+            const offerToBalance = pipe(initialOffersAndCoins, Arr.map((o) => o.outputOffer), ArrayOps.fold((a, b) => a.merge(b)));
+            const unprovenTxToBalance = ledger.Transaction.fromParts(networkId, offerToBalance);
+            const imbalances = TransactionTrait.unproven.getImbalances(unprovenTxToBalance);
+            const { offer, newState } = yield* this.#balanceGuaranteedSection(secretKeys, state, imbalances, this.getCoinSelection(), selfCoins.length, Imbalances.empty());
+            const finalState = CoreWallet.watchCoins(newState, secretKeys, selfCoins);
+            const finalTx = unprovenTxToBalance.merge(ledger.Transaction.fromParts(networkId, offer));
+            return {
+                newState: finalState,
+                recipe: {
+                    type: TRANSACTION_TO_PROVE,
+                    transaction: finalTx,
+                },
+            };
+        });
+    }
+    initSwap(secretKeys, state, desiredInputs, desiredOutputs) {
+        return Either.gen(this, function* () {
+            const outputsValid = desiredOutputs.every((output) => output.amount > 0n);
+            if (!outputsValid) {
+                return yield* Either.left(new OtherWalletError({
+                    message: 'The amount needs to be positive',
+                }));
+            }
+            const inputsValid = Object.entries(desiredInputs).every(([, amount]) => amount > 0n);
+            if (!inputsValid) {
+                return yield* Either.left(new OtherWalletError({
+                    message: 'The input amounts need to be positive',
+                }));
+            }
+            const outputsParseResult = yield* this.#processDesiredOutputsPossiblyEmpty(state, desiredOutputs);
+            const inputsParseResult = Imbalances.fromEntries(Record.toEntries(desiredInputs));
+            const networkId = this.networkId;
+            const { offer, newState } = yield* this.#balanceGuaranteedSection(secretKeys, state, TransactionImbalances.empty(), this.getCoinSelection(), outputsParseResult.selfCoins.length, inputsParseResult);
+            const finalState = CoreWallet.watchCoins(newState, secretKeys, outputsParseResult.selfCoins);
+            const balancingTx = ledger.Transaction.fromParts(networkId, offer);
+            const finalTx = outputsParseResult.unprovenTxToBalance
+                ? outputsParseResult.unprovenTxToBalance.merge(balancingTx)
+                : balancingTx;
+            return {
+                newState: finalState,
+                recipe: {
+                    type: TRANSACTION_TO_PROVE,
+                    transaction: finalTx,
+                },
+            };
+        });
+    }
+    revert(state, tx) {
+        return Either.try({
+            try: () => {
+                return CoreWallet.revertTransaction(state, tx);
+            },
+            catch: (err) => {
+                return new OtherWalletError({
+                    message: `Error while reverting transaction ${this.txTrait.id(tx)}`,
+                    cause: err,
+                });
+            },
+        });
+    }
+    revertRecipe(state, recipe) {
+        const doRevert = (tx) => {
+            return Either.try({
+                try: () => {
+                    return CoreWallet.revertTransaction(state, tx);
+                },
+                catch: (err) => {
+                    return new OtherWalletError({
+                        message: `Error while reverting transaction ${TransactionTrait.unproven.id(tx)}`,
+                        cause: err,
+                    });
+                },
+            });
+        };
+        switch (recipe.type) {
+            case TRANSACTION_TO_PROVE:
+                return doRevert(recipe.transaction);
+            case BALANCE_TRANSACTION_TO_PROVE:
+                return doRevert(recipe.transactionToProve);
+            case NOTHING_TO_PROVE:
+                return Either.right(state);
+        }
+    }
+    #prepareOffer(secretKeys, state, recipe, segment) {
+        const [inputOffers, stateAfterSpends] = CoreWallet.spendCoins(state, secretKeys, recipe.inputs, segment);
+        const stateAfterWatches = CoreWallet.watchCoins(stateAfterSpends, secretKeys, recipe.outputs);
+        const outputOffers = recipe.outputs.map((coin) => {
+            const output = ledger.ZswapOutput.new(coin, segment, this.getKeys().getCoinPublicKey(state).toHexString(), this.getKeys().getEncryptionPublicKey(state).toHexString());
+            return ledger.ZswapOffer.fromOutput(output, coin.type, coin.value);
+        });
+        return pipe(Arr.appendAll(inputOffers, outputOffers), Arr.match({
+            onEmpty: () => Option.none(),
+            onNonEmpty: (nonEmpty) => pipe(nonEmpty, ArrayOps.fold((a, b) => a.merge(b)), Option.some),
+        }), Option.map((offer) => ({ offer, newState: stateAfterWatches })));
+    }
+    balanceFallibleSection(secretKeys, state, imbalances, coinSelection) {
+        return Either.try({
+            try: () => {
+                const fallibleBalanceRecipe = getBalanceRecipe({
+                    coins: this.getCoins()
+                        .getAvailableCoins(state)
+                        .map((c) => c.coin),
+                    initialImbalances: imbalances.fallible,
+                    transactionCostModel: ShieldedCostModel,
+                    feeTokenType: '',
+                    coinSelection,
+                    createOutput: (coin) => ledger.createShieldedCoinInfo(coin.type, coin.value),
+                    isCoinEqual: (a, b) => a.type === b.type && a.value === b.value,
+                });
+                return pipe(this.#prepareOffer(secretKeys, state, fallibleBalanceRecipe, 1), Option.match({
+                    onNone: () => ({
+                        newState: state,
+                        offer: undefined,
+                    }),
+                    onSome: (res) => res,
+                }));
+            },
+            catch: (err) => {
+                if (err instanceof BalancingInsufficientFundsError) {
+                    return new InsufficientFundsError({
+                        message: 'Insufficient funds',
+                        tokenType: err.tokenType,
+                        amount: imbalances.fallible.get(err.tokenType) ?? 0n,
+                    });
+                }
+                else {
+                    return new OtherWalletError({
+                        message: 'Balancing fallible section failed',
+                        cause: err,
+                    });
+                }
+            },
+        });
+    }
+    #balanceGuaranteedSection(secretKeys, state, imbalances, coinSelection, knownSelfOutputs, targetImbalances) {
+        return Either.gen(this, function* () {
+            const balanceRecipe = yield* Either.try({
+                try: () => getBalanceRecipe({
+                    coins: this.getCoins()
+                        .getAvailableCoins(state)
+                        .map((c) => c.coin),
+                    initialImbalances: imbalances.guaranteed,
+                    transactionCostModel: ShieldedCostModel,
+                    feeTokenType: '',
+                    coinSelection,
+                    createOutput: (coin) => ledger.createShieldedCoinInfo(coin.type, coin.value),
+                    isCoinEqual: (a, b) => a.nonce === b.nonce,
+                    targetImbalances,
+                }),
+                catch: (err) => {
+                    if (err instanceof BalancingInsufficientFundsError) {
+                        return new InsufficientFundsError({
+                            message: 'Insufficient funds',
+                            tokenType: err.tokenType,
+                            amount: imbalances.guaranteed.get(err.tokenType) ?? 0n,
+                        });
+                    }
+                    else {
+                        return new OtherWalletError({
+                            message: 'Balancing guaranteed section failed',
+                            cause: err,
+                        });
+                    }
+                },
+            });
+            if (balanceRecipe.outputs.length + knownSelfOutputs == 0) {
+                return yield* Either.left(new NoSelfOutputsError({}));
+            }
+            return yield* pipe(this.#prepareOffer(secretKeys, state, balanceRecipe, 0), Either.fromOption(() => {
+                return new OtherWalletError({
+                    message: 'Could not create a valid guaranteed offer',
+                });
+            }));
+        }).pipe(EitherOps.flatMapLeft((err) => {
+            if (err instanceof NoSelfOutputsError) {
+                return this.#balanceGuaranteedWithSelfOutput(secretKeys, state, imbalances, coinSelection, targetImbalances);
+            }
+            else {
+                return Either.left(err);
+            }
+        }));
+    }
+    #balanceGuaranteedWithSelfOutput(secretKeys, state, imbalances, coinSelection, targetImbalances) {
+        return Either.gen(this, function* () {
+            const additionalOutputValue = 100000n;
+            const balanceRecipe = yield* Either.try({
+                try: () => {
+                    return getBalanceRecipe({
+                        coins: this.getCoins()
+                            .getAvailableCoins(state)
+                            .map((c) => c.coin),
+                        initialImbalances: Imbalances.merge(imbalances.guaranteed, Imbalances.fromEntry(ledger.shieldedToken().raw, -1n * additionalOutputValue)),
+                        transactionCostModel: ShieldedCostModel,
+                        feeTokenType: '',
+                        coinSelection,
+                        targetImbalances,
+                        createOutput: (coin) => ledger.createShieldedCoinInfo(coin.type, coin.value),
+                        isCoinEqual: (a, b) => a.nonce === b.nonce,
+                    });
+                },
+                catch: (err) => {
+                    if (err instanceof BalancingInsufficientFundsError) {
+                        return new InsufficientFundsError({
+                            message: 'Insufficient funds',
+                            tokenType: err.tokenType,
+                            amount: imbalances.guaranteed.get(err.tokenType) ?? 0n,
+                        });
+                    }
+                    else {
+                        return new OtherWalletError({
+                            message: 'Balancing guaranteed section failed',
+                            cause: err,
+                        });
+                    }
+                },
+            });
+            const additionalCoin = ledger.createShieldedCoinInfo(ledger.shieldedToken().raw, additionalOutputValue);
+            const additionalOffer = pipe(additionalCoin, (coin) => ledger.ZswapOutput.new(coin, 0, this.getKeys().getCoinPublicKey(state).toHexString(), this.getKeys().getEncryptionPublicKey(state).toHexString()), (output) => ledger.ZswapOffer.fromOutput(output, ledger.shieldedToken().raw, additionalOutputValue));
+            return yield* pipe(this.#prepareOffer(secretKeys, state, balanceRecipe, 0), Option.map(({ newState, offer }) => {
+                return {
+                    newState: CoreWallet.watchCoins(newState, secretKeys, [additionalCoin]),
+                    offer: offer.merge(additionalOffer),
+                };
+            }), Either.fromOption(() => {
+                return new OtherWalletError({
+                    message: 'Balancing guaranteed section failed',
+                });
+            }));
+        });
+    }
+    #parseAddress(addr) {
+        return Either.try({
+            try: () => {
+                const repr = MidnightBech32m.parse(addr);
+                return ShieldedAddress.codec.decode(this.networkId, repr);
+            },
+            catch: (err) => {
+                return new AddressError({
+                    message: `Address parsing error: ${addr}`,
+                    originalAddress: addr,
+                    cause: err,
+                });
+            },
+        });
+    }
+    #processDesiredOutputs(state, transfers) {
+        return Either.gen(this, function* () {
+            const initialOffersAndCoins = yield* pipe(transfers, Arr.map((transfer) => {
+                return pipe(this.#parseAddress(transfer.receiverAddress), Either.map((address) => {
+                    const coin = ledger.createShieldedCoinInfo(transfer.type, transfer.amount);
+                    const output = ledger.ZswapOutput.new(coin, 0, address.coinPublicKey.toHexString(), address.encryptionPublicKey.toHexString());
+                    const outputOffer = ledger.ZswapOffer.fromOutput(output, transfer.type, transfer.amount);
+                    return {
+                        coin,
+                        outputOffer,
+                        isForSelf: address.coinPublicKey.equals(this.getKeys().getCoinPublicKey(state)),
+                    };
+                }));
+            }), Either.all);
+            const selfCoins = Arr.flatMap(initialOffersAndCoins, ({ coin, isForSelf }) => {
+                if (isForSelf) {
+                    return [coin];
+                }
+                else {
+                    return [];
+                }
+            });
+            return { initialOffersAndCoins, selfCoins };
+        });
+    }
+    #processDesiredOutputsPossiblyEmpty(state, desiredOutputs) {
+        return pipe(desiredOutputs, Arr.match({
+            onEmpty: () => {
+                return Either.right({
+                    imbalances: TransactionImbalances.empty(),
+                    selfCoins: [],
+                    unprovenTxToBalance: null,
+                });
+            },
+            onNonEmpty: (desiredOutputs) => {
+                return pipe(this.#processDesiredOutputs(state, desiredOutputs), Either.map(({ initialOffersAndCoins, selfCoins }) => {
+                    const networkId = this.networkId;
+                    const offerToBalance = pipe(initialOffersAndCoins, Arr.map((o) => o.outputOffer), ArrayOps.fold((a, b) => a.merge(b)));
+                    const unprovenTxToBalance = ledger.Transaction.fromParts(networkId, offerToBalance);
+                    const imbalances = TransactionTrait.unproven.getImbalances(unprovenTxToBalance);
+                    return {
+                        imbalances,
+                        selfCoins,
+                        unprovenTxToBalance,
+                    };
+                }));
+            },
+        }));
+    }
+}

package/dist/v1/Transaction.d.ts

@@ -0,0 +1,17 @@
+import { Imbalances } from '@midnight-ntwrk/wallet-sdk-capabilities';
+import { TransactionImbalances } from './TransactionImbalances.js';
+import * as ledger from '@midnight-ntwrk/ledger-v6';
+export type TransactionTrait<Tx> = {
+    getImbalances(tx: Tx): TransactionImbalances;
+    id(tx: Tx): string;
+};
+export declare const TransactionTrait: {
+    default: TransactionTrait<ledger.FinalizedTransaction>;
+    proofErased: TransactionTrait<ledger.ProofErasedTransaction>;
+    unproven: TransactionTrait<ledger.UnprovenTransaction>;
+    shared: {
+        getImbalances(tx: ledger.FinalizedTransaction | ledger.UnprovenTransaction | ledger.ProofErasedTransaction): TransactionImbalances;
+        getGuaranteedImbalances: (tx: ledger.FinalizedTransaction | ledger.UnprovenTransaction | ledger.ProofErasedTransaction) => Imbalances;
+        getFallibleImbalances: (tx: ledger.FinalizedTransaction | ledger.UnprovenTransaction | ledger.ProofErasedTransaction) => Imbalances;
+    };
+};