@midnightntwrk/wallet-sdk-shielded 4.0.0-beta.2 → 4.0.0-beta.4

package/dist/v2/Transacting.js

@@ -0,0 +1,259 @@
+// 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 '@midnightntwrk/ledger-v9';
+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),
+                    // Distinct coins can share a type and a value; only the nonce tells them apart.
+                    isCoinEqual: (a, b) => a.nonce === b.nonce,
+                });
+                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/v2/TransactionHistory.d.ts

@@ -0,0 +1,100 @@
+import { TransactionHistoryStorage } from '@midnightntwrk/wallet-sdk-abstractions';
+import type * as ledger from '@midnightntwrk/ledger-v9';
+import { Duration, 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>;
+/**
+ * Shielded entry schema. Extends the common entry shape with an optional `shielded` section. Tightening — required
+ * `shielded` plus required `protocolVersion`/`status` — happens at the writer-input type, not on the stored shape.
+ */
+export declare const ShieldedTransactionHistoryEntrySchema: Schema.Struct<Readonly<{
+    hash: typeof Schema.String;
+    identifiers: Schema.Array$<typeof Schema.String>;
+    protocolVersion: Schema.optional<typeof Schema.Number>;
+    status: Schema.optional<Schema.Literal<["SUCCESS", "FAILURE", "PARTIAL_SUCCESS"]>>;
+    timestamp: Schema.optional<typeof Schema.Date>;
+    fees: Schema.optional<Schema.NullOr<typeof Schema.BigInt>>;
+    lifecycle: Schema.Union<[Schema.Struct<{
+        status: Schema.Literal<["pending"]>;
+        submittedAt: typeof Schema.Date;
+    }>, Schema.Struct<{
+        status: Schema.Literal<["finalized"]>;
+        finalizedBlock: Schema.Struct<{
+            hash: typeof Schema.String;
+            height: typeof Schema.Number;
+            timestamp: typeof Schema.Date;
+        }>;
+    }>, Schema.Struct<{
+        status: Schema.Literal<["rejected"]>;
+        rejectedAt: typeof Schema.Date;
+        reason: Schema.optional<typeof Schema.String>;
+    }>]>;
+}> & {
+    shielded: Schema.optional<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 ShieldedHistoryStorage = TransactionHistoryStorage.TransactionHistoryReader<TransactionHistoryStorage.TransactionHistoryEntryWithHash> & TransactionHistoryStorage.TransactionHistoryWriter<ShieldedTransactionHistoryEntry>;
+export type DefaultTransactionHistoryConfiguration = {
+    txHistoryStorage: ShieldedHistoryStorage;
+    indexerClientConnection: {
+        indexerHttpUrl: string;
+    };
+    /**
+     * How long to keep re-querying the indexer for a transaction's details before giving up, when the WS event arrives
+     * ahead of HTTP ingestion. This is a bounded window, not a guarantee: if the indexer lags beyond it the shielded
+     * section is lost (the change is not re-processed, even across restarts) and the failure is logged. Default: 2
+     * minutes.
+     */
+    transactionDetailsRetryWindow?: Duration.DurationInput;
+};
+export type TransactionDetails = {
+    hash: string;
+    block: {
+        hash: string;
+        height: number;
+        timestamp: number;
+    };
+    status: 'SUCCESS' | 'FAILURE' | 'PARTIAL_SUCCESS';
+    identifiers: readonly string[];
+};
+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/v2/TransactionHistory.js

@@ -0,0 +1,132 @@
+// 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),
+});
+/**
+ * Shielded entry schema. Extends the common entry shape with an optional `shielded` section. Tightening — required
+ * `shielded` plus required `protocolVersion`/`status` — happens at the writer-input type, not on the stored shape.
+ */
+export const ShieldedTransactionHistoryEntrySchema = TransactionHistoryStorage.extendEntrySchema({
+    shielded: Schema.optional(ShieldedSectionSchema),
+});
+const coinEquals = Schema.equivalence(QualifiedShieldedCoinInfoSchema);
+const isFinalized = (entry) => entry !== undefined && entry.lifecycle.status === 'finalized';
+export const mergeShieldedSections = (existing, incoming) => ({
+    receivedCoins: EArray.unionWith(existing.receivedCoins, incoming.receivedCoins, coinEquals),
+    spentCoins: EArray.unionWith(existing.spentCoins, incoming.spentCoins, coinEquals),
+});
+const convertUpdateToFinalizedInput = (changes, metadata, protocolVersion) => ({
+    hash: changes.source,
+    protocolVersion,
+    status: metadata.status,
+    identifiers: metadata.identifiers,
+    finalizedBlock: {
+        hash: metadata.block.hash,
+        height: metadata.block.height,
+        timestamp: new Date(metadata.block.timestamp),
+    },
+    shielded: {
+        receivedCoins: changes.receivedCoins.map(({ mt_index, ...rest }) => ({ ...rest, mtIndex: mt_index })),
+        spentCoins: changes.spentCoins.map(({ mt_index, ...rest }) => ({ ...rest, mtIndex: mt_index })),
+    },
+});
+const gotFinalizedShielded = (txHistoryStorage, input) => Effect.tryPromise({
+    try: () => txHistoryStorage.gotFinalized(input),
+    catch: (e) => new TransactionHistoryError({ message: `Failed to record finalized history entry for ${input.hash}`, cause: e }),
+});
+export const makeDefaultTransactionHistoryService = (config, _getContext) => {
+    const txHistoryStorage = config.txHistoryStorage;
+    const queryClientLayer = HttpQueryClient.layer({ url: config.indexerClientConnection.indexerHttpUrl });
+    const retryWindow = config.transactionDetailsRetryWindow ?? Duration.minutes(2);
+    return {
+        put: (changes, metadata, protocolVersion) => gotFinalizedShielded(txHistoryStorage, convertUpdateToFinalizedInput(changes, metadata, protocolVersion)),
+        getTransactionDetails: (hash) => Effect.gen(function* () {
+            const statusQuery = yield* TransactionHistoryDetail;
+            const result = yield* statusQuery({ transactionHash: hash });
+            // The WS ZswapEvents stream can deliver a relevant event before the indexer's HTTP `transactions(...)`
+            // endpoint has ingested the same hash — a normal race on any deployed network. In that window the array
+            // is empty; fail with a *typed* error so the retry schedule below engages and re-queries once the indexer
+            // catches up (rather than dereferencing `undefined` and dying with an unretriable defect).
+            const tx = yield* EArray.head(result.transactions).pipe(Effect.orElseFail(() => new TransactionHistoryError({ message: `Indexer has not yet indexed transaction ${hash}` })));
+            const rawStatus = tx.__typename === 'RegularTransaction' ? tx.transactionResult.status : undefined;
+            const status = rawStatus === 'FAILURE' || rawStatus === 'PARTIAL_SUCCESS' ? rawStatus : 'SUCCESS';
+            const identifiers = tx.__typename === 'RegularTransaction' ? tx.identifiers : [];
+            return {
+                hash: tx.hash,
+                block: {
+                    hash: tx.block.hash,
+                    height: tx.block.height,
+                    timestamp: tx.block.timestamp,
+                },
+                status,
+                identifiers,
+            };
+        }).pipe(Effect.provide(queryClientLayer), Effect.scoped, 
+        // Retry for a bounded window (default 2 min) while the indexer catches up. The exponential delay is capped
+        // at 10s (`either` takes the earlier of the two schedules) so probes keep landing every ≤10s late in the
+        // window — uncapped doubling would leave minute-long gaps and overshoot the window. Jitter the delays so a
+        // batch of concurrent lookups that all hit the indexer-lag race don't retry in lockstep against an
+        // already-behind indexer. Beyond the window we give up — the change is not re-processed, so the caller logs
+        // the loss. Only the typed "not yet indexed" failure is transient; anything else (bad URL, 4xx, schema
+        // mismatch) cannot succeed by waiting, so it fails fast instead of holding a fan-out slot for the whole
+        // window.
+        Effect.retry({
+            schedule: Schedule.exponential(Duration.seconds(1)).pipe(Schedule.either(Schedule.spaced(Duration.seconds(10))), Schedule.jittered, Schedule.upTo(retryWindow)),
+            while: (error) => error instanceof TransactionHistoryError,
+        }), 
+        // Let our own "not yet indexed" error through untouched; only wrap the indexer query's ClientError/ServerError.
+        Effect.mapError((error) => error instanceof TransactionHistoryError
+            ? error
+            : new TransactionHistoryError({
+                message: `Failed to fetch transaction metadata for ${hash}`,
+                cause: error,
+            }))),
+    };
+};
+export const makeSimulatorTransactionHistoryService = (config, _getContext) => {
+    const txHistoryStorage = config.txHistoryStorage;
+    return {
+        put: (changes, metadata, protocolVersion) => {
+            const input = convertUpdateToFinalizedInput(changes, metadata, protocolVersion);
+            return gotFinalizedShielded(txHistoryStorage, { ...input, timestamp: input.finalizedBlock.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) => isFinalized(entry)
+            ? Effect.succeed({
+                hash: entry.hash,
+                block: {
+                    hash: entry.lifecycle.finalizedBlock.hash,
+                    height: entry.lifecycle.finalizedBlock.height,
+                    timestamp: entry.lifecycle.finalizedBlock.timestamp.getTime(),
+                },
+                status: entry.status ?? 'SUCCESS',
+                identifiers: entry.identifiers,
+            })
+            : Effect.fail(new TransactionHistoryError({ message: `No transaction found in storage for hash: ${hash}` })))),
+    };
+};

package/dist/v2/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/v2/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/v2/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 '@midnightntwrk/ledger-v9';
+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/v2/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);
+        },
+    };
+})();