@midnightntwrk/wallet-sdk-unshielded-wallet 3.1.0

package/dist/v1/Transacting.js

@@ -0,0 +1,385 @@
+// 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 { Either, Option, pipe, Array as Arr } from 'effect';
+import { CoreWallet } from './CoreWallet.js';
+import { InsufficientFundsError, OtherWalletError, TransactingError } from './WalletError.js';
+import { getBalanceRecipe, Imbalances, InsufficientFundsError as BalancingInsufficientFundsError, } from '@midnightntwrk/wallet-sdk-capabilities';
+import { TransactionOps } from './TransactionOps.js';
+const GUARANTEED_SEGMENT = 0;
+export const makeDefaultTransactingCapability = (config, getContext) => {
+    return new TransactingCapabilityImplementation(config.networkId, () => getContext().coinSelection, () => getContext().coinsAndBalancesCapability, () => getContext().keysCapability, TransactionOps);
+};
+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;
+    }
+    /**
+     * Balances an unbound transaction Note: Unbound transactions are balanced in place and returned
+     *
+     * @param wallet - The wallet to balance the transaction with
+     * @param transaction - The transaction to balance
+     * @returns The balanced transaction and the new wallet state if successful, otherwise an error
+     */
+    balanceUnboundTransaction(wallet, transaction) {
+        return this.#balanceUnboundishTransaction(wallet, transaction);
+    }
+    /**
+     * Balances an unproven transaction Note: This method does the same thing as balanceUnboundTransaction but is provided
+     * for convenience and type safety
+     *
+     * @param wallet - The wallet to balance the transaction with
+     * @param transaction - The transaction to balance
+     * @returns The balanced transaction and the new wallet state if successful, otherwise an error
+     */
+    balanceUnprovenTransaction(wallet, transaction) {
+        return this.#balanceUnboundishTransaction(wallet, transaction);
+    }
+    /**
+     * Balances a bound transaction Note: In bound transactions we can only balance the guaranteed section in intents
+     *
+     * @param wallet - The wallet to balance the transaction with
+     * @param transaction - The transaction to balance
+     * @returns A balancing counterpart transaction (which should be merged with the original transaction ) and the new
+     *   wallet state if successful, otherwise an error
+     */
+    balanceFinalizedTransaction(wallet, transaction) {
+        return Either.gen(this, function* () {
+            // Ensure all intents are bound
+            const segments = this.txOps.getSegments(transaction);
+            for (const segment of segments) {
+                const intent = transaction.intents?.get(segment);
+                const isBound = this.txOps.isIntentBound(intent);
+                if (!isBound) {
+                    return yield* Either.left(new TransactingError({ message: `Intent with id ${segment} is not bound` }));
+                }
+            }
+            // get the first intent so we can use its ttl to create the balancing intent
+            const intent = transaction.intents?.get(segments[0]);
+            const imbalances = this.txOps.getImbalances(transaction, GUARANTEED_SEGMENT);
+            // guaranteed section is balanced
+            if (imbalances.size === 0) {
+                return [undefined, wallet];
+            }
+            const recipe = yield* this.#balanceSegment(wallet, imbalances, Imbalances.empty(), this.getCoinSelection());
+            const { newState, offer } = yield* this.#prepareOffer(wallet, recipe);
+            const balancingIntent = ledger.Intent.new(intent.ttl);
+            balancingIntent.guaranteedUnshieldedOffer = offer;
+            const segmentId = Option.getOrElse(this.txOps.findAvailableSegmentId(transaction), () => 1);
+            const balancingTx = ledger.Transaction.fromParts(this.networkId).addIntent({ tag: 'specific', value: segmentId }, balancingIntent);
+            return [balancingTx, newState];
+        });
+    }
+    /**
+     * Makes a transfer transaction
+     *
+     * @param wallet - The wallet to make the transfer with
+     * @param outputs - The outputs for the transfer
+     * @param ttl - The TTL for the transaction
+     * @returns The balanced transfer transaction and the new wallet state if successful, otherwise an error
+     */
+    makeTransfer(wallet, outputs, ttl) {
+        return Either.gen(this, function* () {
+            const { networkId } = this;
+            const isValid = outputs.every((output) => output.amount > 0n);
+            if (!isValid) {
+                return yield* Either.left(new TransactingError({ message: 'The amount of all inputs needs to be positive' }));
+            }
+            const ledgerOutputs = outputs.map((output) => {
+                return {
+                    value: output.amount,
+                    owner: output.receiverAddress.data.toString('hex'),
+                    type: output.type,
+                };
+            });
+            const recipe = yield* this.#balanceSegment(wallet, Imbalances.empty(), Imbalances.fromEntries(ledgerOutputs.map((output) => [output.type, output.value])), this.getCoinSelection());
+            const { newState, offer } = yield* this.#prepareOffer(wallet, {
+                inputs: recipe.inputs,
+                outputs: [...recipe.outputs, ...ledgerOutputs],
+            });
+            const intent = ledger.Intent.new(ttl);
+            const hasNightOutput = ledgerOutputs.some((output) => output.type === ledger.nativeToken().raw);
+            if (hasNightOutput) {
+                intent.fallibleUnshieldedOffer = offer;
+            }
+            else {
+                intent.guaranteedUnshieldedOffer = offer;
+            }
+            return {
+                newState,
+                transaction: ledger.Transaction.fromParts(networkId, undefined, undefined, intent),
+            };
+        });
+    }
+    rotateUtxos(wallet, guaranteedUtxos, fallibleUtxos, nightVerifyingKey, ttl) {
+        return Either.gen(this, function* () {
+            const { networkId } = this;
+            if (guaranteedUtxos.length === 0 && fallibleUtxos.length === 0) {
+                return yield* Either.left(new TransactingError({ message: 'At least one UTxO must be provided to rotateUtxos' }));
+            }
+            const ownerAddress = ledger.addressFromKey(nightVerifyingKey);
+            const makeOffer = (utxos) => {
+                if (utxos.length === 0) {
+                    return Option.none();
+                }
+                const inputs = utxos.map(({ utxo }) => ({
+                    value: utxo.value,
+                    type: utxo.type,
+                    intentHash: utxo.intentHash,
+                    outputNo: utxo.outputNo,
+                    owner: nightVerifyingKey,
+                }));
+                const totalValue = pipe(utxos, Arr.map(({ utxo }) => utxo.value), Arr.reduce(0n, (a, b) => a + b));
+                const output = {
+                    owner: ownerAddress,
+                    type: ledger.nativeToken().raw,
+                    value: totalValue,
+                };
+                return Option.some(ledger.UnshieldedOffer.new(inputs, [output], []));
+            };
+            const allUtxos = [...guaranteedUtxos, ...fallibleUtxos].map(({ utxo }) => utxo);
+            const [, walletAfterBooking] = yield* CoreWallet.spendUtxos(wallet, allUtxos);
+            const guaranteedOffer = makeOffer(guaranteedUtxos);
+            const fallibleOffer = makeOffer(fallibleUtxos);
+            const intent = pipe(ledger.Intent.new(ttl), (i) => Option.match(guaranteedOffer, {
+                onNone: () => i,
+                onSome: (offer) => {
+                    i.guaranteedUnshieldedOffer = offer;
+                    return i;
+                },
+            }), (i) => Option.match(fallibleOffer, {
+                onNone: () => i,
+                onSome: (offer) => {
+                    i.fallibleUnshieldedOffer = offer;
+                    return i;
+                },
+            }));
+            const transaction = ledger.Transaction.fromParts(networkId, undefined, undefined, intent);
+            return {
+                newState: walletAfterBooking,
+                transaction,
+            };
+        });
+    }
+    /**
+     * Initializes a swap transaction
+     *
+     * @param wallet - The wallet to initialize the swap for
+     * @param desiredInputs - The desired inputs for the swap
+     * @param desiredOutputs - The desired outputs for the swap
+     * @param ttl - The TTL for the swap
+     * @returns The initialized swap transaction and the new wallet state if successful, otherwise an error
+     */
+    initSwap(wallet, desiredInputs, desiredOutputs, ttl) {
+        return Either.gen(this, function* () {
+            const { networkId } = this;
+            const outputsValid = desiredOutputs.every((output) => output.amount > 0n);
+            if (!outputsValid) {
+                return yield* Either.left(new TransactingError({ message: 'The amount of all outputs needs to be positive' }));
+            }
+            const inputsValid = Object.entries(desiredInputs).every(([, amount]) => amount > 0n);
+            if (!inputsValid) {
+                return yield* Either.left(new TransactingError({ message: 'The amount of all inputs needs to be positive' }));
+            }
+            const ledgerOutputs = desiredOutputs.map((output) => ({
+                value: output.amount,
+                owner: output.receiverAddress.data.toString('hex'),
+                type: output.type,
+            }));
+            const targetImbalances = Imbalances.fromEntries(Object.entries(desiredInputs));
+            const recipe = yield* this.#balanceSegment(wallet, Imbalances.empty(), targetImbalances, this.getCoinSelection());
+            const { newState, offer } = yield* this.#prepareOffer(wallet, {
+                inputs: recipe.inputs,
+                outputs: [...recipe.outputs, ...ledgerOutputs],
+            });
+            const intent = ledger.Intent.new(ttl);
+            intent.guaranteedUnshieldedOffer = offer;
+            const tx = ledger.Transaction.fromParts(networkId, undefined, undefined, intent);
+            return {
+                newState,
+                transaction: tx,
+            };
+        });
+    }
+    signUnprovenTransaction(transaction, signSegment) {
+        return this.#signTransactionInternal(transaction, signSegment);
+    }
+    signUnboundTransaction(transaction, signSegment) {
+        return this.#signTransactionInternal(transaction, signSegment);
+    }
+    /**
+     * Internal method to sign either an unproven or unbound transaction
+     *
+     * @param transaction - The transaction to sign
+     * @param signSegment - The signing function
+     * @returns The signed transaction if successful, otherwise an error
+     */
+    #signTransactionInternal(transaction, signSegment) {
+        return Either.gen(this, function* () {
+            const segments = this.txOps.getSegments(transaction);
+            for (const segment of segments) {
+                const signedData = yield* this.txOps.getSignatureData(transaction, segment);
+                const signature = signSegment(signedData);
+                transaction = yield* this.txOps.addSignature(transaction, signature, segment);
+            }
+            return transaction;
+        });
+    }
+    /**
+     * Reverts a transaction by rolling back all inputs owned by this wallet
+     *
+     * @param wallet - The wallet to revert the transaction for
+     * @param transaction - The transaction to revert (can be FinalizedTransaction, UnboundTransaction, or
+     *   UnprovenTransaction)
+     * @returns The updated wallet with rolled back UTXOs if successful, otherwise an error
+     */
+    revertTransaction(wallet, transaction) {
+        return pipe(this.txOps.extractOwnInputs(transaction, wallet.publicKey.publicKey), Arr.reduce(Either.right(wallet), (walletAcc, utxo) => pipe(walletAcc, Either.flatMap((w) => CoreWallet.rollbackUtxo(w, utxo)))));
+    }
+    /**
+     * Balances a segment of a transaction
+     *
+     * @param wallet - The wallet to balance the segment for
+     * @param imbalances - The imbalances to balance the segment for
+     * @param targetImbalances - The target imbalances to balance the segment for
+     * @param coinSelection - The coin selection to use for the balance recipe
+     * @returns The balance recipe if successful, otherwise an error
+     */
+    #balanceSegment(wallet, imbalances, targetImbalances, coinSelection) {
+        return Either.try({
+            try: () => getBalanceRecipe({
+                coins: this.getCoins()
+                    .getAvailableCoins(wallet)
+                    .map(({ utxo }) => utxo),
+                initialImbalances: imbalances,
+                feeTokenType: '',
+                transactionCostModel: {
+                    inputFeeOverhead: 0n,
+                    outputFeeOverhead: 0n,
+                },
+                coinSelection,
+                createOutput: (coin) => ({
+                    ...coin,
+                    owner: wallet.publicKey.addressHex,
+                }),
+                isCoinEqual: (a, b) => a.intentHash === b.intentHash && a.outputNo === b.outputNo,
+                targetImbalances,
+            }),
+            catch: (err) => {
+                if (err instanceof BalancingInsufficientFundsError) {
+                    return new InsufficientFundsError({
+                        message: 'Insufficient funds',
+                        tokenType: err.tokenType,
+                        amount: imbalances.get(err.tokenType) ?? 0n,
+                    });
+                }
+                else {
+                    return new OtherWalletError({
+                        message: 'Balancing unshielded segment failed',
+                        cause: err,
+                    });
+                }
+            },
+        });
+    }
+    /**
+     * Prepares an offer for a given balance recipe
+     *
+     * @param wallet - The wallet to prepare the offer for
+     * @param balanceRecipe - The balance recipe to prepare the offer for
+     * @returns The prepared offer and the new wallet state if successful, otherwise an error
+     */
+    #prepareOffer(wallet, balanceRecipe) {
+        return Either.gen(function* () {
+            const [spentInputs, updatedWallet] = yield* CoreWallet.spendUtxos(wallet, balanceRecipe.inputs);
+            const { publicKey } = wallet.publicKey;
+            const ledgerInputs = spentInputs.map((input) => ({
+                ...input,
+                intentHash: input.intentHash,
+                owner: publicKey,
+            }));
+            const counterOffer = yield* Either.try({
+                try: () => ledger.UnshieldedOffer.new(ledgerInputs, [...balanceRecipe.outputs], []),
+                catch: (error) => new TransactingError({ message: 'Failed to create counter offer', cause: error }),
+            });
+            return {
+                newState: updatedWallet,
+                offer: counterOffer,
+            };
+        });
+    }
+    #mergeOffers(offerA, offerB) {
+        return pipe(Option.fromNullable(offerB), Option.match({
+            onNone: () => Either.right(offerA),
+            onSome: (offerB) => Either.try({
+                try: () => ledger.UnshieldedOffer.new([...offerB.inputs, ...offerA.inputs], [...offerB.outputs, ...offerA.outputs], [...offerB.signatures, ...offerA.signatures]),
+                catch: (error) => new TransactingError({ message: 'Failed to merge offers', cause: error }),
+            }),
+        }));
+    }
+    /**
+     * Balances an unboundish (unproven or unbound) transaction
+     *
+     * @param wallet - The wallet to balance the transaction with
+     * @param transaction - The transaction to balance
+     * @returns The balanced transaction and the new wallet state if successful, otherwise an error
+     * @todo - https://shielded.atlassian.net/browse/PM-21260
+     */
+    #balanceUnboundishTransaction(wallet, transaction) {
+        return Either.gen(this, function* () {
+            const segments = this.txOps.getSegments(transaction);
+            // no segments to balance
+            if (segments.length === 0) {
+                return [undefined, wallet];
+            }
+            for (const segment of [...segments, GUARANTEED_SEGMENT]) {
+                const imbalances = this.txOps.getImbalances(transaction, segment);
+                // intent is balanced
+                if (imbalances.size === 0) {
+                    continue;
+                }
+                // if segment is GUARANTEED_SEGMENT, use the first intent to place the balancing offer in the guaranteed section
+                const intentSegment = segment === GUARANTEED_SEGMENT ? segments[0] : segment;
+                const intent = transaction.intents?.get(intentSegment);
+                if (!intent) {
+                    return yield* Either.left(new TransactingError({ message: `Intent with id ${segment} was not found` }));
+                }
+                const isBound = this.txOps.isIntentBound(intent);
+                if (isBound) {
+                    return yield* Either.left(new TransactingError({ message: `Intent with id ${segment} is already bound` }));
+                }
+                const recipe = yield* this.#balanceSegment(wallet, imbalances, Imbalances.empty(), this.getCoinSelection());
+                const { offer } = yield* this.#prepareOffer(wallet, recipe);
+                const targetOffer = segment !== GUARANTEED_SEGMENT ? intent.fallibleUnshieldedOffer : intent.guaranteedUnshieldedOffer;
+                const mergedOffer = yield* this.#mergeOffers(offer, targetOffer);
+                if (segment !== GUARANTEED_SEGMENT) {
+                    intent.fallibleUnshieldedOffer = mergedOffer;
+                }
+                else {
+                    intent.guaranteedUnshieldedOffer = mergedOffer;
+                }
+                transaction.intents = transaction.intents.set(intentSegment, intent);
+            }
+            return [transaction, wallet];
+        });
+    }
+}

package/dist/v1/TransactionHistory.d.ts

@@ -0,0 +1,54 @@
+import { TransactionHistoryStorage } from '@midnightntwrk/wallet-sdk-abstractions';
+import { Effect, Schema } from 'effect';
+import { type UnshieldedUpdate } from './SyncSchema.js';
+import { TransactionHistoryError } from './WalletError.js';
+export declare const UnshieldedSectionSchema: Schema.Struct<{
+    id: typeof Schema.Number;
+    createdUtxos: Schema.Array$<Schema.Struct<{
+        value: Schema.Schema<bigint, string, never>;
+        owner: typeof Schema.String;
+        tokenType: typeof Schema.String;
+        intentHash: typeof Schema.String;
+        outputIndex: typeof Schema.Number;
+    }>>;
+    spentUtxos: Schema.Array$<Schema.Struct<{
+        value: Schema.Schema<bigint, string, never>;
+        owner: typeof Schema.String;
+        tokenType: typeof Schema.String;
+        intentHash: typeof Schema.String;
+        outputIndex: typeof Schema.Number;
+    }>>;
+}>;
+export declare const UnshieldedTransactionHistoryEntrySchema: Schema.Struct<{
+    unshielded: Schema.Struct<{
+        id: typeof Schema.Number;
+        createdUtxos: Schema.Array$<Schema.Struct<{
+            value: Schema.Schema<bigint, string, never>;
+            owner: typeof Schema.String;
+            tokenType: typeof Schema.String;
+            intentHash: typeof Schema.String;
+            outputIndex: typeof Schema.Number;
+        }>>;
+        spentUtxos: Schema.Array$<Schema.Struct<{
+            value: Schema.Schema<bigint, string, never>;
+            owner: typeof Schema.String;
+            tokenType: typeof Schema.String;
+            intentHash: typeof Schema.String;
+            outputIndex: typeof Schema.Number;
+        }>>;
+    }>;
+    hash: typeof Schema.String;
+    protocolVersion: typeof Schema.Number;
+    status: Schema.Literal<["SUCCESS", "FAILURE", "PARTIAL_SUCCESS"]>;
+    identifiers: Schema.optional<Schema.Array$<typeof Schema.String>>;
+    timestamp: Schema.optional<typeof Schema.Date>;
+    fees: Schema.optional<Schema.NullOr<typeof Schema.BigInt>>;
+}>;
+export type UnshieldedTransactionHistoryEntry = Schema.Schema.Type<typeof UnshieldedTransactionHistoryEntrySchema>;
+export type TransactionHistoryService = {
+    put(update: UnshieldedUpdate): Effect.Effect<void, TransactionHistoryError>;
+};
+export type DefaultTransactionHistoryConfiguration = {
+    txHistoryStorage: TransactionHistoryStorage.TransactionHistoryStorage<TransactionHistoryStorage.TransactionHistoryEntryWithHash>;
+};
+export declare const makeDefaultTransactionHistoryService: (config: DefaultTransactionHistoryConfiguration, _getContext: () => unknown) => TransactionHistoryService;

package/dist/v1/TransactionHistory.js

@@ -0,0 +1,66 @@
+// 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 { Effect, Schema } from 'effect';
+import { SafeBigInt } from '@midnightntwrk/wallet-sdk-utilities';
+import { TransactionHistoryError } from './WalletError.js';
+const UtxoSchema = Schema.Struct({
+    value: SafeBigInt.SafeBigInt,
+    owner: Schema.String,
+    tokenType: Schema.String,
+    intentHash: Schema.String,
+    outputIndex: Schema.Number,
+});
+export const UnshieldedSectionSchema = Schema.Struct({
+    id: Schema.Number,
+    createdUtxos: Schema.Array(UtxoSchema),
+    spentUtxos: Schema.Array(UtxoSchema),
+});
+export const UnshieldedTransactionHistoryEntrySchema = Schema.Struct({
+    ...TransactionHistoryStorage.TransactionHistoryCommonSchema.fields,
+    unshielded: UnshieldedSectionSchema,
+});
+const convertUpdateToStorageEntry = ({ transaction, createdUtxos, spentUtxos, status, }) => ({
+    hash: transaction.hash,
+    protocolVersion: transaction.protocolVersion,
+    status,
+    identifiers: transaction.identifiers ?? [],
+    timestamp: transaction.block.timestamp,
+    fees: transaction.fees?.paidFees ?? null,
+    unshielded: {
+        id: transaction.id,
+        createdUtxos: createdUtxos.map(({ utxo }) => ({
+            value: utxo.value,
+            owner: utxo.owner,
+            tokenType: utxo.type,
+            intentHash: utxo.intentHash,
+            outputIndex: utxo.outputNo,
+        })),
+        spentUtxos: spentUtxos.map(({ utxo }) => ({
+            value: utxo.value,
+            owner: utxo.owner,
+            tokenType: utxo.type,
+            intentHash: utxo.intentHash,
+            outputIndex: utxo.outputNo,
+        })),
+    },
+});
+export const makeDefaultTransactionHistoryService = (config, _getContext) => {
+    const txHistoryStorage = config.txHistoryStorage;
+    return {
+        put: (update) => Effect.tryPromise({
+            try: () => txHistoryStorage.upsert(convertUpdateToStorageEntry(update)),
+            catch: (e) => new TransactionHistoryError({ message: 'Failed to put transaction history entry', cause: e }),
+        }),
+    };
+};

package/dist/v1/TransactionOps.d.ts

@@ -0,0 +1,19 @@
+import { Either, type Option } from 'effect';
+import { Imbalances } from '@midnightntwrk/wallet-sdk-capabilities';
+import type * as ledger from '@midnight-ntwrk/ledger-v8';
+import { type WalletError } from './WalletError.js';
+/** Unbound transaction type. This is a transaction that has no signatures and is not bound yet. */
+export type UnboundTransaction = ledger.Transaction<ledger.SignatureEnabled, ledger.Proof, ledger.PreBinding>;
+/** Utility type to extract the Intent type from a Transaction type. Maps Transaction<S, P, B> to Intent<S, P, B>. */
+export type IntentOf<T> = T extends ledger.Transaction<infer S, infer P, infer B> ? ledger.Intent<S, P, B> : never;
+export type TransactionOps = {
+    getSignatureData: (transaction: ledger.Transaction<ledger.SignatureEnabled, ledger.Proofish, ledger.PreBinding>, segment: number) => Either.Either<Uint8Array, WalletError>;
+    getSegments(transaction: ledger.Transaction<ledger.SignatureEnabled, ledger.Proofish, ledger.Bindingish>): number[];
+    findAvailableSegmentId(transaction: ledger.Transaction<ledger.SignatureEnabled, ledger.Proofish, ledger.Bindingish>): Option.Option<number>;
+    addSignature<TTransaction extends ledger.UnprovenTransaction | UnboundTransaction>(transaction: TTransaction, signature: ledger.Signature, segment: number): Either.Either<TTransaction, WalletError>;
+    getImbalances(transaction: ledger.FinalizedTransaction | UnboundTransaction | ledger.UnprovenTransaction, segment: number): Imbalances;
+    addSignaturesToOffer(offer: ledger.UnshieldedOffer<ledger.SignatureEnabled>, signature: ledger.Signature, segment: number, offerType: 'guaranteed' | 'fallible'): Either.Either<ledger.UnshieldedOffer<ledger.SignatureEnabled>, WalletError>;
+    isIntentBound(intent: ledger.Intent<ledger.SignatureEnabled, ledger.Proofish, ledger.Bindingish>): boolean;
+    extractOwnInputs(transaction: ledger.Transaction<ledger.SignatureEnabled, ledger.Proofish, ledger.Bindingish>, signatureVerifyingKey: ledger.SignatureVerifyingKey): ledger.Utxo[];
+};
+export declare const TransactionOps: TransactionOps;

package/dist/v1/TransactionOps.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 { Either, pipe, Array as Arr, Iterable as IterableOps } from 'effect';
+import { Imbalances } from '@midnightntwrk/wallet-sdk-capabilities';
+import { TransactingError } from './WalletError.js';
+export const TransactionOps = {
+    getSignatureData(tx, segment) {
+        if (!tx.intents) {
+            return Either.left(new TransactingError({ message: 'Transaction has no intents' }));
+        }
+        const intent = tx.intents.get(segment);
+        if (!intent) {
+            return Either.left(new TransactingError({ message: `Intent with segment ${segment} was not found` }));
+        }
+        return Either.try({
+            try: () => intent.signatureData(segment),
+            catch: (error) => new TransactingError({ message: 'Failed to get offer signature data', cause: error }),
+        });
+    },
+    getSegments(transaction) {
+        return transaction.intents?.keys().toArray() ?? [];
+    },
+    findAvailableSegmentId(transaction) {
+        const used = new Set(transaction.intents?.keys() ?? []);
+        return pipe(IterableOps.range(1, 65535), IterableOps.findFirst((segmentId) => !used.has(segmentId)));
+    },
+    // @TODO - https://shielded.atlassian.net/browse/PM-21260
+    addSignature(transaction, signature, segment) {
+        return Either.gen(function* () {
+            if (!transaction.intents || transaction.intents.size === 0) {
+                return yield* Either.left(new TransactingError({ message: 'No intents found in the transaction' }));
+            }
+            const intent = transaction.intents?.get(segment);
+            if (!intent) {
+                return yield* Either.left(new TransactingError({ message: `Intent with id ${segment} was not found` }));
+            }
+            if (TransactionOps.isIntentBound(intent)) {
+                return yield* Either.left(new TransactingError({ message: `Intent at segment ${segment} is already bound` }));
+            }
+            if (intent.fallibleUnshieldedOffer) {
+                intent.fallibleUnshieldedOffer = yield* TransactionOps.addSignaturesToOffer(intent.fallibleUnshieldedOffer, signature, segment, 'fallible');
+            }
+            if (intent.guaranteedUnshieldedOffer) {
+                intent.guaranteedUnshieldedOffer = yield* TransactionOps.addSignaturesToOffer(intent.guaranteedUnshieldedOffer, signature, segment, 'guaranteed');
+            }
+            transaction.intents = transaction.intents.set(segment, intent);
+            return transaction;
+        });
+    },
+    getImbalances(transaction, segment) {
+        const imbalances = transaction
+            .imbalances(segment)
+            .entries()
+            .filter(([token, value]) => token.tag === 'unshielded' && value !== 0n)
+            .map(([token, value]) => [token.raw.toString(), value])
+            .toArray();
+        return Imbalances.fromEntries(imbalances);
+    },
+    addSignaturesToOffer(offer, signature, segment, offerType) {
+        return pipe(offer.inputs, Arr.map((_, i) => offer.signatures.at(i) ?? signature), (signatures) => Either.try({
+            try: () => offer.addSignatures(signatures),
+            catch: (error) => new TransactingError({
+                message: `Failed to add ${offerType} signature at segment ${segment}`,
+                cause: error,
+            }),
+        }));
+    },
+    isIntentBound(intent) {
+        return intent.binding.instance === 'binding';
+    },
+    extractOwnInputs(transaction, signatureVerifyingKey) {
+        const segments = TransactionOps.getSegments(transaction);
+        return pipe(segments, Arr.flatMap((segment) => {
+            const intent = transaction.intents?.get(segment);
+            if (!intent) {
+                return [];
+            }
+            const { guaranteedUnshieldedOffer, fallibleUnshieldedOffer } = intent;
+            const ownedInputsfromGuaranteedSection = guaranteedUnshieldedOffer?.inputs
+                ? guaranteedUnshieldedOffer.inputs.filter((input) => input.owner === signatureVerifyingKey)
+                : [];
+            const ownedInputsfromFallibleSection = fallibleUnshieldedOffer
+                ? fallibleUnshieldedOffer.inputs.filter((input) => input.owner === signatureVerifyingKey)
+                : [];
+            return [...ownedInputsfromGuaranteedSection, ...ownedInputsfromFallibleSection];
+        }));
+    },
+};

package/dist/v1/UnshieldedState.d.ts

@@ -0,0 +1,37 @@
+import type * as ledger from '@midnight-ntwrk/ledger-v8';
+import { Data, Either, HashMap } from 'effect';
+import { ApplyTransactionError, UtxoNotFoundError } from './WalletError.js';
+export interface UtxoMeta {
+    readonly ctime: Date;
+    readonly registeredForDustGeneration: boolean;
+}
+export type UtxoHash = string;
+export declare class UtxoWithMeta extends Data.Class<{
+    readonly utxo: ledger.Utxo;
+    readonly meta: UtxoMeta;
+}> {
+}
+export type UpdateStatus = 'SUCCESS' | 'FAILURE' | 'PARTIAL_SUCCESS';
+export interface UnshieldedUpdate {
+    readonly createdUtxos: readonly UtxoWithMeta[];
+    readonly spentUtxos: readonly UtxoWithMeta[];
+    readonly status: UpdateStatus;
+}
+export interface UnshieldedState {
+    readonly availableUtxos: HashMap.HashMap<UtxoHash, UtxoWithMeta>;
+    readonly pendingUtxos: HashMap.HashMap<UtxoHash, UtxoWithMeta>;
+}
+export declare const UnshieldedState: {
+    readonly empty: () => UnshieldedState;
+    readonly restore: (availableUtxos: readonly UtxoWithMeta[], pendingUtxos: readonly UtxoWithMeta[]) => UnshieldedState;
+    readonly spend: (state: UnshieldedState, utxo: UtxoWithMeta) => Either.Either<UnshieldedState, UtxoNotFoundError>;
+    readonly rollbackSpend: (state: UnshieldedState, utxo: UtxoWithMeta) => Either.Either<UnshieldedState, never>;
+    readonly spendByUtxo: (state: UnshieldedState, utxo: ledger.Utxo) => Either.Either<UnshieldedState, UtxoNotFoundError>;
+    readonly rollbackSpendByUtxo: (state: UnshieldedState, utxo: ledger.Utxo) => Either.Either<UnshieldedState, never>;
+    readonly applyUpdate: (state: UnshieldedState, update: UnshieldedUpdate) => Either.Either<UnshieldedState, ApplyTransactionError>;
+    readonly applyFailedUpdate: (state: UnshieldedState, update: UnshieldedUpdate) => Either.Either<UnshieldedState, ApplyTransactionError>;
+    readonly toArrays: (state: UnshieldedState) => {
+        readonly availableUtxos: readonly UtxoWithMeta[];
+        readonly pendingUtxos: readonly UtxoWithMeta[];
+    };
+};