@midnightntwrk/wallet-sdk-shielded 3.0.2

package/dist/v1/Transacting.js

@@ -0,0 +1,258 @@
+// 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 { Array as Arr, Either, Option, pipe, Record } from 'effect';
+import { ArrayOps } from '@midnightntwrk/wallet-sdk-utilities';
+import { CoreWallet } from './CoreWallet.js';
+import { InsufficientFundsError, OtherWalletError } from './WalletError.js';
+import { getBalanceRecipe, Imbalances, InsufficientFundsError as BalancingInsufficientFundsError, } from '@midnightntwrk/wallet-sdk-capabilities';
+import { ShieldedCostModel, TransactionImbalances } from './TransactionImbalances.js';
+import { TransactionOps } from './TransactionOps.js';
+export const makeDefaultTransactingCapability = (config, getContext) => {
+    return new TransactingCapabilityImplementation(config.networkId, () => getContext().coinSelection, () => getContext().coinsAndBalancesCapability, () => getContext().keysCapability, TransactionOps.default);
+};
+export const makeSimulatorTransactingCapability = (config, getContext) => {
+    return new TransactingCapabilityImplementation(config.networkId, () => getContext().coinSelection, () => getContext().coinsAndBalancesCapability, () => getContext().keysCapability, TransactionOps.proofErased);
+};
+export class TransactingCapabilityImplementation {
+    networkId;
+    getCoinSelection;
+    txOps;
+    getCoins;
+    getKeys;
+    constructor(networkId, getCoinSelection, getCoins, getKeys, txOps) {
+        this.getCoins = getCoins;
+        this.networkId = networkId;
+        this.getCoinSelection = getCoinSelection;
+        this.getKeys = getKeys;
+        this.txOps = txOps;
+    }
+    balanceTransaction(secretKeys, state, tx) {
+        return Either.gen(this, function* () {
+            const coinSelection = this.getCoinSelection();
+            const initialImbalances = this.txOps.getImbalances(tx);
+            if (TransactionImbalances.areBalanced(initialImbalances)) {
+                return [undefined, state];
+            }
+            const { newState: afterFallible, fallibleOffers } = yield* this.balanceFallibleSection(secretKeys, state, initialImbalances, coinSelection);
+            const { newState: afterGuaranteed, offer: guaranteed } = yield* this.#balanceGuaranteedSection(secretKeys, afterFallible, initialImbalances, coinSelection, Imbalances.empty());
+            const balancedTx = Array.from(fallibleOffers.entries()).reduce((tx, [segment, offer]) => tx.addZswapOffer({ tag: 'specific', value: segment }, offer), ledger.Transaction.fromParts(this.networkId, guaranteed));
+            return [balancedTx, afterGuaranteed];
+        });
+    }
+    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 = TransactionOps.unproven.getImbalances(unprovenTxToBalance);
+            const { offer, newState } = yield* this.#balanceGuaranteedSection(secretKeys, state, imbalances, this.getCoinSelection(), Imbalances.empty());
+            const finalState = CoreWallet.watchCoins(newState, secretKeys, selfCoins);
+            const finalTx = unprovenTxToBalance.merge(ledger.Transaction.fromParts(networkId, offer));
+            return [finalTx, finalState];
+        });
+    }
+    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(), 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 [finalTx, finalState];
+        });
+    }
+    revertTransaction(state, transaction) {
+        return Either.try({
+            try: () => {
+                return CoreWallet.revertTransaction(state, transaction);
+            },
+            catch: (err) => {
+                return new OtherWalletError({
+                    message: `Error while reverting transaction ${transaction.identifiers().at(0)}`,
+                    cause: err,
+                });
+            },
+        });
+    }
+    #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 Array.from(imbalances.fallible.entries()).reduce((acc, [segment, segmentImbalances]) => Either.flatMap(acc, ({ fallibleOffers, newState }) => pipe(Either.try({
+            try: () => {
+                const fallibleBalanceRecipe = getBalanceRecipe({
+                    coins: this.getCoins()
+                        .getAvailableCoins(newState)
+                        .map((c) => c.coin),
+                    initialImbalances: segmentImbalances,
+                    transactionCostModel: ShieldedCostModel,
+                    feeTokenType: '',
+                    coinSelection,
+                    createOutput: (coin) => ledger.createShieldedCoinInfo(coin.type, coin.value),
+                    isCoinEqual: (a, b) => a.type === b.type && a.value === b.value,
+                });
+                return this.#prepareOffer(secretKeys, newState, fallibleBalanceRecipe, segment);
+            },
+            catch: (err) => {
+                if (err instanceof BalancingInsufficientFundsError) {
+                    return new InsufficientFundsError({
+                        message: `Insufficient funds for fallible segment ${segment}`,
+                        tokenType: err.tokenType,
+                        amount: segmentImbalances.get(err.tokenType) ?? 0n,
+                    });
+                }
+                return new OtherWalletError({
+                    message: `Balancing fallible segment ${segment} failed`,
+                    cause: err,
+                });
+            },
+        }), Either.map(Option.match({
+            onNone: () => ({ fallibleOffers, newState }),
+            onSome: (res) => ({
+                fallibleOffers: new Map([...fallibleOffers, [segment, res.offer]]),
+                newState: res.newState,
+            }),
+        })))), Either.right({
+            fallibleOffers: new Map(),
+            newState: state,
+        }));
+    }
+    #balanceGuaranteedSection(secretKeys, state, imbalances, coinSelection, 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,
+                        });
+                    }
+                },
+            });
+            // An empty recipe (e.g. the guaranteed section is already balanced) yields no offer.
+            // Treat that as "nothing to add" rather than a failure, mirroring the fallible section.
+            return pipe(this.#prepareOffer(secretKeys, state, balanceRecipe, 0), Option.match({
+                onNone: () => ({ offer: undefined, newState: state }),
+                onSome: (result) => result,
+            }));
+        });
+    }
+    #processDesiredOutputs(state, transfers) {
+        return Either.try({
+            try: () => {
+                const initialOffersAndCoins = pipe(transfers, Arr.map((transfer) => {
+                    const { receiverAddress, type, amount } = transfer;
+                    const coin = ledger.createShieldedCoinInfo(type, amount);
+                    const output = ledger.ZswapOutput.new(coin, 0, receiverAddress.coinPublicKey.toHexString(), receiverAddress.encryptionPublicKey.toHexString());
+                    const outputOffer = ledger.ZswapOffer.fromOutput(output, type, amount);
+                    return {
+                        coin,
+                        outputOffer,
+                        isForSelf: receiverAddress.coinPublicKey.equals(this.getKeys().getCoinPublicKey(state)),
+                    };
+                }));
+                const selfCoins = Arr.flatMap(initialOffersAndCoins, ({ coin, isForSelf }) => {
+                    if (isForSelf) {
+                        return [coin];
+                    }
+                    else {
+                        return [];
+                    }
+                });
+                return { initialOffersAndCoins, selfCoins };
+            },
+            catch: (err) => {
+                return new OtherWalletError({
+                    message: 'Failed to process desired outputs',
+                    cause: err,
+                });
+            },
+        });
+    }
+    #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 = TransactionOps.unproven.getImbalances(unprovenTxToBalance);
+                    return {
+                        imbalances,
+                        selfCoins,
+                        unprovenTxToBalance,
+                    };
+                }));
+            },
+        }));
+    }
+}

package/dist/v1/TransactionHistory.d.ts

@@ -0,0 +1,64 @@
+import { TransactionHistoryStorage } from '@midnightntwrk/wallet-sdk-abstractions';
+import type * as ledger from '@midnight-ntwrk/ledger-v8';
+import { Effect, Schema } from 'effect';
+import { TransactionHistoryError } from './WalletError.js';
+export declare const QualifiedShieldedCoinInfoSchema: Schema.Struct<{
+    type: typeof Schema.String;
+    nonce: typeof Schema.String;
+    value: typeof Schema.BigInt;
+    mtIndex: typeof Schema.BigInt;
+}>;
+export declare const ShieldedSectionSchema: Schema.Struct<{
+    receivedCoins: Schema.Array$<Schema.Struct<{
+        type: typeof Schema.String;
+        nonce: typeof Schema.String;
+        value: typeof Schema.BigInt;
+        mtIndex: typeof Schema.BigInt;
+    }>>;
+    spentCoins: Schema.Array$<Schema.Struct<{
+        type: typeof Schema.String;
+        nonce: typeof Schema.String;
+        value: typeof Schema.BigInt;
+        mtIndex: typeof Schema.BigInt;
+    }>>;
+}>;
+type ShieldedSection = Schema.Schema.Type<typeof ShieldedSectionSchema>;
+export declare const ShieldedTransactionHistoryEntrySchema: Schema.Struct<{
+    hash: typeof Schema.String;
+    protocolVersion: typeof Schema.Number;
+    status: Schema.Literal<["SUCCESS", "FAILURE", "PARTIAL_SUCCESS"]>;
+    shielded: Schema.Struct<{
+        receivedCoins: Schema.Array$<Schema.Struct<{
+            type: typeof Schema.String;
+            nonce: typeof Schema.String;
+            value: typeof Schema.BigInt;
+            mtIndex: typeof Schema.BigInt;
+        }>>;
+        spentCoins: Schema.Array$<Schema.Struct<{
+            type: typeof Schema.String;
+            nonce: typeof Schema.String;
+            value: typeof Schema.BigInt;
+            mtIndex: typeof Schema.BigInt;
+        }>>;
+    }>;
+}>;
+export type ShieldedTransactionHistoryEntry = Schema.Schema.Type<typeof ShieldedTransactionHistoryEntrySchema>;
+export type DefaultTransactionHistoryConfiguration = {
+    txHistoryStorage: TransactionHistoryStorage.TransactionHistoryStorage<TransactionHistoryStorage.TransactionHistoryEntryWithHash>;
+    indexerClientConnection: {
+        indexerHttpUrl: string;
+    };
+};
+export type TransactionDetails = {
+    hash: string;
+    timestamp: number;
+    status: 'SUCCESS' | 'FAILURE' | 'PARTIAL_SUCCESS';
+};
+export type TransactionHistoryService = {
+    put(changes: ledger.ZswapStateChanges, metadata: TransactionDetails, protocolVersion: number): Effect.Effect<void, TransactionHistoryError>;
+    getTransactionDetails(hash: TransactionHistoryStorage.TransactionHash): Effect.Effect<TransactionDetails, TransactionHistoryError>;
+};
+export declare const mergeShieldedSections: (existing: ShieldedSection, incoming: ShieldedSection) => ShieldedSection;
+export declare const makeDefaultTransactionHistoryService: (config: DefaultTransactionHistoryConfiguration, _getContext: () => unknown) => TransactionHistoryService;
+export declare const makeSimulatorTransactionHistoryService: (config: DefaultTransactionHistoryConfiguration, _getContext: () => unknown) => TransactionHistoryService;
+export {};

package/dist/v1/TransactionHistory.js

@@ -0,0 +1,98 @@
+// 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 { TransactionHistoryStorage } from '@midnightntwrk/wallet-sdk-abstractions';
+import { Duration, Array as EArray, Effect, Schedule, Schema } from 'effect';
+import { TransactionHistoryDetail } from '@midnightntwrk/wallet-sdk-indexer-client';
+import { HttpQueryClient } from '@midnightntwrk/wallet-sdk-indexer-client/effect';
+import { TransactionHistoryError } from './WalletError.js';
+export const QualifiedShieldedCoinInfoSchema = Schema.Struct({
+    type: Schema.String,
+    nonce: Schema.String,
+    value: Schema.BigInt,
+    mtIndex: Schema.BigInt,
+});
+export const ShieldedSectionSchema = Schema.Struct({
+    receivedCoins: Schema.Array(QualifiedShieldedCoinInfoSchema),
+    spentCoins: Schema.Array(QualifiedShieldedCoinInfoSchema),
+});
+export const ShieldedTransactionHistoryEntrySchema = Schema.Struct({
+    hash: TransactionHistoryStorage.TransactionHashSchema,
+    protocolVersion: Schema.Number,
+    status: TransactionHistoryStorage.TransactionHistoryStatusSchema,
+    shielded: ShieldedSectionSchema,
+});
+const coinEquals = Schema.equivalence(QualifiedShieldedCoinInfoSchema);
+export const mergeShieldedSections = (existing, incoming) => ({
+    receivedCoins: EArray.unionWith(existing.receivedCoins, incoming.receivedCoins, coinEquals),
+    spentCoins: EArray.unionWith(existing.spentCoins, incoming.spentCoins, coinEquals),
+});
+const convertUpdateToStorageEntry = (changes, metadata, protocolVersion) => ({
+    hash: changes.source,
+    protocolVersion,
+    status: metadata.status,
+    shielded: {
+        receivedCoins: changes.receivedCoins.map(({ mt_index, ...rest }) => ({ ...rest, mtIndex: mt_index })),
+        spentCoins: changes.spentCoins.map(({ mt_index, ...rest }) => ({ ...rest, mtIndex: mt_index })),
+    },
+});
+const upsertShieldedEntry = (txHistoryStorage, entry) => Effect.tryPromise({
+    try: () => txHistoryStorage.upsert(entry),
+    catch: (e) => new TransactionHistoryError({ message: `Failed to upsert history entry for ${entry.hash}`, cause: e }),
+});
+export const makeDefaultTransactionHistoryService = (config, _getContext) => {
+    const txHistoryStorage = config.txHistoryStorage;
+    const queryClientLayer = HttpQueryClient.layer({ url: config.indexerClientConnection.indexerHttpUrl });
+    return {
+        put: (changes, metadata, protocolVersion) => {
+            const entry = convertUpdateToStorageEntry(changes, metadata, protocolVersion);
+            return upsertShieldedEntry(txHistoryStorage, entry);
+        },
+        getTransactionDetails: (hash) => Effect.gen(function* () {
+            const statusQuery = yield* TransactionHistoryDetail;
+            const result = yield* statusQuery({ transactionHash: hash });
+            const tx = result.transactions[0];
+            const rawStatus = tx.__typename === 'RegularTransaction' ? tx.transactionResult.status : undefined;
+            const status = rawStatus === 'FAILURE' || rawStatus === 'PARTIAL_SUCCESS' ? rawStatus : 'SUCCESS';
+            return {
+                hash: tx.hash,
+                timestamp: tx.block.timestamp,
+                status,
+            };
+        }).pipe(Effect.provide(queryClientLayer), Effect.scoped, Effect.retry(Schedule.exponential(Duration.seconds(1)).pipe(Schedule.compose(Schedule.recurs(3)))), Effect.mapError((cause) => new TransactionHistoryError({
+            message: `Failed to fetch transaction metadata for ${hash}`,
+            cause,
+        }))),
+    };
+};
+export const makeSimulatorTransactionHistoryService = (config, _getContext) => {
+    const txHistoryStorage = config.txHistoryStorage;
+    return {
+        put: (changes, metadata, protocolVersion) => {
+            const entry = convertUpdateToStorageEntry(changes, metadata, protocolVersion);
+            return upsertShieldedEntry(txHistoryStorage, {
+                ...entry,
+                timestamp: new Date(metadata.timestamp),
+            });
+        },
+        getTransactionDetails: (hash) => Effect.tryPromise({
+            try: () => txHistoryStorage.get(hash),
+            catch: (e) => new TransactionHistoryError({ message: `Failed to get transaction details for ${hash}`, cause: e }),
+        }).pipe(Effect.flatMap((entry) => entry
+            ? Effect.succeed({
+                hash: entry.hash,
+                timestamp: entry.timestamp ? entry.timestamp.getTime() : Date.now(),
+                status: entry.status,
+            })
+            : Effect.fail(new TransactionHistoryError({ message: `No transaction found in storage for hash: ${hash}` })))),
+    };
+};

package/dist/v1/TransactionImbalances.d.ts

@@ -0,0 +1,10 @@
+import { Imbalances, type TransactionCostModel } from '@midnightntwrk/wallet-sdk-capabilities';
+export declare const ShieldedCostModel: TransactionCostModel;
+export type TransactionImbalances = Readonly<{
+    guaranteed: Imbalances;
+    fallible: ReadonlyMap<number, Imbalances>;
+}>;
+export declare const TransactionImbalances: {
+    empty: () => TransactionImbalances;
+    areBalanced: (imbalances: TransactionImbalances) => boolean;
+};

package/dist/v1/TransactionImbalances.js

@@ -0,0 +1,30 @@
+// 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 { Imbalances } from '@midnightntwrk/wallet-sdk-capabilities';
+export const ShieldedCostModel = {
+    inputFeeOverhead: 0n,
+    outputFeeOverhead: 0n,
+};
+export const TransactionImbalances = new (class {
+    empty = () => {
+        return {
+            guaranteed: Imbalances.empty(),
+            fallible: new Map(),
+        };
+    };
+    areBalanced = (imbalances) => {
+        const areGuaranteedAllZeroes = imbalances.guaranteed.entries().every(([, value]) => value === 0n);
+        const areFallibleAllZeroes = Array.from(imbalances.fallible.values()).every((segmentImbalances) => segmentImbalances.entries().every(([, value]) => value === 0n));
+        return areGuaranteedAllZeroes && areFallibleAllZeroes;
+    };
+})();

package/dist/v1/TransactionOps.d.ts

@@ -0,0 +1,17 @@
+import { Imbalances } from '@midnightntwrk/wallet-sdk-capabilities';
+import { type TransactionImbalances } from './TransactionImbalances.js';
+import type * as ledger from '@midnight-ntwrk/ledger-v8';
+export type TransactionOps<Tx> = {
+    getImbalances(tx: Tx): TransactionImbalances;
+    id(tx: Tx): string;
+};
+export declare const TransactionOps: {
+    default: TransactionOps<ledger.FinalizedTransaction>;
+    proofErased: TransactionOps<ledger.ProofErasedTransaction>;
+    unproven: TransactionOps<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) => ReadonlyMap<number, Imbalances>;
+    };
+};

package/dist/v1/TransactionOps.js

@@ -0,0 +1,73 @@
+// 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 { Imbalances } from '@midnightntwrk/wallet-sdk-capabilities';
+export const TransactionOps = new (class {
+    default = {
+        getImbalances(tx) {
+            return TransactionOps.shared.getImbalances(tx);
+        },
+        id(tx) {
+            return tx.identifiers().at(0);
+        },
+    };
+    proofErased = {
+        getImbalances(tx) {
+            return TransactionOps.shared.getImbalances(tx);
+        },
+        id(tx) {
+            return tx.identifiers().at(0);
+        },
+    };
+    unproven = {
+        getImbalances(tx) {
+            return TransactionOps.shared.getImbalances(tx);
+        },
+        id(tx) {
+            return tx.identifiers().at(0);
+        },
+    };
+    shared = {
+        getImbalances(tx) {
+            const guaranteedImbalances = TransactionOps.shared.getGuaranteedImbalances(tx);
+            const fallibleImbalances = TransactionOps.shared.getFallibleImbalances(tx);
+            return {
+                guaranteed: guaranteedImbalances,
+                fallible: fallibleImbalances,
+            };
+        },
+        getGuaranteedImbalances: (tx) => {
+            const rawGuaranteedImbalances = tx
+                .imbalances(0)
+                .entries()
+                .filter(([token]) => token.tag === 'shielded')
+                .map(([token, value]) => {
+                return [token.raw, value];
+            });
+            return Imbalances.fromEntries(rawGuaranteedImbalances);
+        },
+        getFallibleImbalances: (tx) => {
+            const segments = Array.from(tx.fallibleOffer?.keys() ?? []);
+            const fallibleImbalances = segments.flatMap((segment) => {
+                const rawImbalances = tx
+                    .imbalances(segment)
+                    .entries()
+                    .filter(([token]) => token.tag === 'shielded')
+                    .map(([token, value]) => {
+                    return [token.raw, value];
+                });
+                return [[segment, Imbalances.fromEntries(rawImbalances)]];
+            });
+            return new Map(fallibleImbalances);
+        },
+    };
+})();

package/dist/v1/V1Builder.d.ts

@@ -0,0 +1,93 @@
+import * as ledger from '@midnight-ntwrk/ledger-v8';
+import { type Either, type Types } from 'effect';
+import { type NetworkId } from '@midnightntwrk/wallet-sdk-abstractions';
+import { type Variant, type VariantBuilder } from '@midnightntwrk/wallet-sdk-runtime/abstractions';
+import { RunningV1Variant, V1Tag } from './RunningV1Variant.js';
+import { type SerializationCapability } from './Serialization.js';
+import { type DefaultSyncContext, type DefaultSyncConfiguration, type ChangesResult, type SyncCapability, type SyncService, type WalletSyncUpdate } from './Sync.js';
+import { type DefaultTransactingConfiguration, type DefaultTransactingContext, type TransactingCapability } from './Transacting.js';
+import { type WalletError } from './WalletError.js';
+import { type CoinsAndBalancesCapability } from './CoinsAndBalances.js';
+import { type KeysCapability } from './Keys.js';
+import { type CoinSelection } from '@midnightntwrk/wallet-sdk-capabilities';
+import { CoreWallet } from './CoreWallet.js';
+import { type DefaultTransactionHistoryConfiguration, type TransactionHistoryService } from './TransactionHistory.js';
+export type BaseV1Configuration = {
+    networkId: NetworkId.NetworkId;
+};
+export type DefaultV1Configuration = BaseV1Configuration & DefaultSyncConfiguration & DefaultTransactingConfiguration & DefaultTransactionHistoryConfiguration;
+declare const V1BuilderSymbol: {
+    readonly typeId: unique symbol;
+};
+export type V1Variant<TSerialized, TSyncUpdate, TTransaction, TAuxData> = Variant.Variant<typeof V1Tag, CoreWallet, null, RunningV1Variant<TSerialized, TSyncUpdate, TTransaction, TAuxData>> & {
+    deserializeState: (serialized: TSerialized) => Either.Either<CoreWallet, WalletError>;
+    coinsAndBalances: CoinsAndBalancesCapability<CoreWallet>;
+    keys: KeysCapability<CoreWallet>;
+    serialization: SerializationCapability<CoreWallet, null, TSerialized>;
+    transactionHistory: TransactionHistoryService;
+};
+export type AnyV1Variant = V1Variant<any, any, any, any>;
+export type DefaultV1Variant = V1Variant<string, WalletSyncUpdate, ledger.FinalizedTransaction, ledger.ZswapSecretKeys>;
+export type TransactionOf<T extends AnyV1Variant> = T extends V1Variant<any, any, infer TTransaction, any> ? TTransaction : never;
+export type AuxDataOf<T extends AnyV1Variant> = T extends V1Variant<any, any, any, infer TAuxData> ? TAuxData : never;
+export type SerializedStateOf<T extends AnyV1Variant> = T extends V1Variant<infer TSerialized, any, any, any> ? TSerialized : never;
+export type DefaultV1Builder = V1Builder<DefaultV1Configuration, RunningV1Variant.Context<string, WalletSyncUpdate, ledger.FinalizedTransaction, ledger.ZswapSecretKeys>, string, WalletSyncUpdate, ledger.FinalizedTransaction, ledger.ZswapSecretKeys>;
+export declare class V1Builder<TConfig extends BaseV1Configuration = BaseV1Configuration, TContext extends Partial<RunningV1Variant.AnyContext> = object, TSerialized = never, TSyncUpdate = never, TTransaction = never, TStartAux extends object = object> implements VariantBuilder.VariantBuilder<V1Variant<TSerialized, TSyncUpdate, TTransaction, TStartAux>, TConfig> {
+    #private;
+    constructor(buildState?: V1Builder.PartialBuildState<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>);
+    withDefaults(): DefaultV1Builder;
+    withTransactionType<Transaction>(): V1Builder<TConfig, TContext, TSerialized, TSyncUpdate, Transaction, TStartAux>;
+    withDefaultTransactionType(): V1Builder<TConfig, TContext, TSerialized, TSyncUpdate, ledger.FinalizedTransaction, TStartAux>;
+    withSyncDefaults(): V1Builder<TConfig & DefaultSyncConfiguration, TContext & DefaultSyncContext, TSerialized, WalletSyncUpdate, TTransaction, ledger.ZswapSecretKeys>;
+    withSync<TSyncConfig, TSyncContext extends Partial<RunningV1Variant.AnyContext>, TSyncUpdate, TStartAux extends object>(syncService: (configuration: TSyncConfig, getContext: () => TSyncContext) => SyncService<CoreWallet, TStartAux, TSyncUpdate>, syncCapability: (configuration: TSyncConfig, getContext: () => TSyncContext) => SyncCapability<CoreWallet, TSyncUpdate, ChangesResult>): V1Builder<TConfig & TSyncConfig, TContext & TSyncContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>;
+    withSerializationDefaults(): V1Builder<TConfig, TContext, string, TSyncUpdate, TTransaction, TStartAux>;
+    withSerialization<TSerializationConfig, TSerializationContext extends Partial<RunningV1Variant.AnyContext>, TSerialized>(serializationCapability: (configuration: TSerializationConfig, getContext: () => TSerializationContext) => SerializationCapability<CoreWallet, null, TSerialized>): V1Builder<TConfig & TSerializationConfig, TContext & TSerializationContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>;
+    withTransactingDefaults(this: V1Builder<TConfig, TContext, TSerialized, TSyncUpdate, ledger.FinalizedTransaction, TStartAux>): V1Builder<TConfig & DefaultTransactingConfiguration, TContext & DefaultTransactingContext, TSerialized, TSyncUpdate, ledger.FinalizedTransaction, TStartAux>;
+    withTransacting<TTransactingConfig, TTransactingContext extends Partial<RunningV1Variant.AnyContext>>(transactingCapability: (config: TTransactingConfig, getContext: () => TTransactingContext) => TransactingCapability<ledger.ZswapSecretKeys, CoreWallet, TTransaction>): V1Builder<TConfig & TTransactingConfig, TContext & TTransactingContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>;
+    withCoinSelection<TCoinSelectionConfig, TCoinSelectionContext extends Partial<RunningV1Variant.AnyContext>>(coinSelection: (config: TCoinSelectionConfig, getContext: () => TCoinSelectionContext) => CoinSelection<ledger.QualifiedShieldedCoinInfo>): V1Builder<TConfig & TCoinSelectionConfig, TContext & TCoinSelectionContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>;
+    withCoinSelectionDefaults(): V1Builder<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>;
+    withCoinsAndBalancesDefaults(): V1Builder<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>;
+    withCoinsAndBalances<TBalancesConfig, TBalancesContext extends Partial<RunningV1Variant.AnyContext>>(coinsAndBalancesCapability: (configuration: TBalancesConfig, getContext: () => TBalancesContext) => CoinsAndBalancesCapability<CoreWallet>): V1Builder<TConfig & TBalancesConfig, TContext & TBalancesContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>;
+    withTransactionHistoryDefaults(this: V1Builder<TConfig, TContext, TSerialized, TSyncUpdate, ledger.FinalizedTransaction, TStartAux>): V1Builder<TConfig & DefaultTransactionHistoryConfiguration, TContext, TSerialized, TSyncUpdate, ledger.FinalizedTransaction, TStartAux>;
+    withTransactionHistory<TTransactionHistoryConfig, TTransactionHistoryContext extends Partial<RunningV1Variant.AnyContext>>(transactionHistoryService: (configuration: TTransactionHistoryConfig, getContext: () => TTransactionHistoryContext) => TransactionHistoryService): V1Builder<TConfig & TTransactionHistoryConfig, TContext & TTransactionHistoryContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>;
+    withKeysDefaults(): V1Builder<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>;
+    withKeys<TKeysConfig, TKeysContext extends Partial<RunningV1Variant.AnyContext>>(keysCapability: (configuration: TKeysConfig, getContext: () => TKeysContext) => KeysCapability<CoreWallet>): V1Builder<TConfig & TKeysConfig, TContext & TKeysContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>;
+    build(this: V1Builder<TConfig, RunningV1Variant.Context<TSerialized, TSyncUpdate, TTransaction, TStartAux>, TSerialized, TSyncUpdate, TTransaction, TStartAux>, configuration: TConfig): V1Variant<TSerialized, TSyncUpdate, TTransaction, TStartAux>;
+}
+/** @internal */
+declare namespace V1Builder {
+    type HasSync<TConfig, TContext, TSyncUpdate, TStartAux> = {
+        readonly syncService: (configuration: TConfig, getContext: () => TContext) => SyncService<CoreWallet, TStartAux, TSyncUpdate>;
+        readonly syncCapability: (configuration: TConfig, getContext: () => TContext) => SyncCapability<CoreWallet, TSyncUpdate, ChangesResult>;
+    };
+    type HasTransacting<TConfig, TContext, TTransaction> = {
+        readonly transactingCapability: (configuration: TConfig, getContext: () => TContext) => TransactingCapability<ledger.ZswapSecretKeys, CoreWallet, TTransaction>;
+    };
+    type HasCoinSelection<TConfig, TContext> = {
+        readonly coinSelection: (configuration: TConfig, getContext: () => TContext) => CoinSelection<ledger.QualifiedShieldedCoinInfo>;
+    };
+    type HasSerialization<TConfig, TContext, TSerialized> = {
+        readonly serializationCapability: (configuration: TConfig, getContext: () => TContext) => SerializationCapability<CoreWallet, null, TSerialized>;
+    };
+    type HasCoinsAndBalances<TConfig, TContext> = {
+        readonly coinsAndBalancesCapability: (configuration: TConfig, getContext: () => TContext) => CoinsAndBalancesCapability<CoreWallet>;
+    };
+    type HasTransactionHistory<TConfig, TContext> = {
+        readonly transactionHistoryService: (configuration: TConfig, getContext: () => TContext) => TransactionHistoryService;
+    };
+    type HasKeys<TConfig, TContext> = {
+        readonly keysCapability: (configuration: TConfig, getContext: () => TContext) => KeysCapability<CoreWallet>;
+    };
+    /** The internal build state of {@link V1Builder}. */
+    type FullBuildState<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux> = Types.Simplify<HasSync<TConfig, TContext, TSyncUpdate, TStartAux> & HasSerialization<TConfig, TContext, TSerialized> & HasTransacting<TConfig, TContext, TTransaction> & HasCoinSelection<TConfig, TContext> & HasCoinsAndBalances<TConfig, TContext> & HasKeys<TConfig, TContext> & HasTransactionHistory<TConfig, TContext>>;
+    type PartialBuildState<TConfig = object, TContext = object, TSerialized = never, TSyncUpdate = never, TTransaction = never, TStartAux = object> = {
+        [K in keyof FullBuildState<never, never, never, never, never, never>]?: FullBuildState<TConfig, TContext, TSerialized, TSyncUpdate, TTransaction, TStartAux>[K] | undefined;
+    };
+    /** Utility interface that manages the type variance of {@link V1Builder}. */
+    interface Variance<R> {
+        readonly [V1BuilderSymbol.typeId]: {
+            readonly _R: Types.Covariant<R>;
+        };
+    }
+}
+export {};