@midnight-ntwrk/wallet-sdk-shielded 4.0.0-beta.2 → 4.0.0-beta.3

package/dist/v2/Sync.js

@@ -0,0 +1,436 @@
+// 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 { Chunk, Duration, Effect, Either, identity, Option, ParseResult, pipe, Schedule, Schema, Stream, } from 'effect';
+import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { CoreWallet } from './CoreWallet.js';
+import { getLastBlock } from '@midnight-ntwrk/wallet-sdk-capabilities/simulation';
+import { BlockHash, ZswapEventTip, ZswapEvents } from '@midnight-ntwrk/wallet-sdk-indexer-client';
+import { ConnectionHelper, HttpQueryClient, WsSubscriptionClient, } from '@midnight-ntwrk/wallet-sdk-indexer-client/effect';
+import { SyncWalletError } from './WalletError.js';
+import { WsURL } from '@midnight-ntwrk/wallet-sdk-utilities/networking';
+import { EitherOps } from '@midnight-ntwrk/wallet-sdk-utilities';
+/**
+ * Splits a batch of version-tagged items at the end of a variant's activation range.
+ *
+ * @remarks
+ *   The split is positional, not a filter: everything from the first out-of-range item onwards is deferred, even if a
+ *   later item reports an in-range version again. A batch is a contiguous slice of one timeline, so applying past a
+ *   boundary and then resuming behind it would leave a hole no cursor can describe.
+ *
+ *   This is the one place the boundary rule lives; both the indexer capability (per event) and the simulator capability
+ *   (per block) go through it, so they cannot drift apart.
+ * @param items The batch, in source order.
+ * @param versionOf Reads the protocol version an item was reported at.
+ * @param activeRange The variant's half-open activation range.
+ * @returns The applied/deferred split and the version to record.
+ */
+export const splitAtVersionBoundary = (items, versionOf, activeRange) => {
+    const [, end] = activeRange;
+    const boundary = items.findIndex((item) => BigInt(versionOf(item)) >= end);
+    const [applied, deferred] = boundary < 0 ? [items, []] : [items.slice(0, boundary), items.slice(boundary)];
+    const signalling = deferred.at(0) ?? applied.at(-1);
+    return {
+        applied,
+        deferred,
+        observedVersion: signalling === undefined
+            ? Option.none()
+            : Option.some(ProtocolVersion.ProtocolVersion(BigInt(versionOf(signalling)))),
+    };
+};
+/** Records a batch's observed protocol version on the state, monotonically. A batch that observed none is a no-op. */
+export const annotateVersion = (state, observedVersion) => Option.match(observedVersion, {
+    onNone: () => state,
+    onSome: (version) => CoreWallet.withProtocolVersion(state, version),
+});
+const Uint8ArraySchema = Schema.declare((input) => input instanceof Uint8Array).annotations({
+    identifier: 'Uint8Array',
+});
+export const SecretKeysResource = {
+    create: (secretKeys) => {
+        return (cb) => {
+            const result = cb(secretKeys);
+            secretKeys.clear();
+            return result;
+        };
+    },
+};
+export const VersionSignalSyncUpdate = {
+    create: (version, highestEventId) => {
+        return {
+            _tag: 'VersionSignal',
+            version,
+            highestEventId,
+        };
+    },
+};
+export const WalletSyncUpdate = {
+    create: (updates, secretKeys) => {
+        return {
+            _tag: 'Events',
+            updates,
+            secretKeys,
+        };
+    },
+};
+const LedgerEventSchema = Schema.declare((input) => input instanceof ledger.Event).annotations({
+    identifier: 'ledger.Event',
+});
+const LedgerEventFromUint8Array = Schema.transformOrFail(Uint8ArraySchema, LedgerEventSchema, {
+    encode: (event) => Effect.try({
+        try: () => event.serialize(),
+        catch: (error) => new ParseResult.Unexpected(error, 'Could not serialize ledger event'),
+    }),
+    decode: (bytes) => Effect.try({
+        try: () => ledger.Event.deserialize(bytes),
+        catch: (error) => new ParseResult.Unexpected(error, 'Could not deserialize ledger event'),
+    }),
+});
+const HexedLedgerEvent = pipe(Schema.Uint8ArrayFromHex, Schema.compose(LedgerEventFromUint8Array));
+const EventsSyncUpdatePayload = Schema.Struct({
+    id: Schema.Number,
+    raw: Schema.String,
+    protocolVersion: Schema.Number,
+    maxId: Schema.Number,
+});
+/**
+ * One event of the source's timeline, still encoded.
+ *
+ * @remarks
+ *   The event is carried as the source served it rather than as a `ledger.Event`, because whether this ledger version may
+ *   read it at all is not the source's question to answer. A batch spanning a protocol boundary carries events of the
+ *   version that follows this one, which this ledger version cannot deserialize — the serialization header names a
+ *   different version — and after a hand-over the inclusive cursor re-delivers an event of the version that preceded
+ *   it, which it equally cannot. Both are ordinary, and neither is an error: they belong to the variant either side.
+ *
+ *   So the bytes travel undecoded and only the capability, which knows the activation range, reads the ones it is about
+ *   to apply — see {@link readEvent}. Decoding here would fail the whole batch on an event nobody intended to apply.
+ */
+export const EventsSyncUpdate = Schema.TaggedStruct('EventsSyncUpdate', {
+    id: Schema.Number,
+    protocolVersion: Schema.Number,
+    maxId: Schema.Number,
+    raw: Schema.String,
+});
+const EventsSyncUpdateFromPayload = Schema.transform(EventsSyncUpdatePayload, EventsSyncUpdate, {
+    strict: true,
+    decode: (input) => ({
+        _tag: 'EventsSyncUpdate',
+        id: input.id,
+        protocolVersion: input.protocolVersion,
+        maxId: input.maxId,
+        raw: input.raw,
+    }),
+    encode: (update) => ({
+        id: update.id,
+        raw: update.raw,
+        protocolVersion: update.protocolVersion,
+        maxId: update.maxId,
+    }),
+});
+/**
+ * Reads an event this variant is going to apply.
+ *
+ * @remarks
+ *   The counterpart of {@link EventsSyncUpdate} carrying its event encoded: a capability calls this on the batch prefix it
+ *   owns, and never on what it defers. Failure here is a genuine one — an event this variant claimed and cannot read —
+ *   and is raised rather than returned, because `SyncCapability.applyUpdate` is total in its own domain and the variant
+ *   already turns a throw from it into a typed synchronization error.
+ * @param update The update to read.
+ * @returns The event it carries.
+ * @throws ParseError if the bytes are not an event this ledger version can deserialize.
+ */
+export const readEvent = (update) => Schema.decodeSync(HexedLedgerEvent)(update.raw);
+/** How often the chain is asked its version when the configuration does not say. */
+const DEFAULT_VERSION_WATCH_INTERVAL_MS = 30_000;
+/**
+ * How long one event-id probe is given to produce its single answer.
+ *
+ * @remarks
+ *   Only a stall guard. The probe subscribes at a cursor whose event provably exists, so the answer arrives at once or
+ *   the transport is broken; without a bound, a half-open socket would leave the poll loop parked on a tick that never
+ *   completes and the wallet would stop asking altogether. A bound turns that into a skipped tick.
+ */
+const EVENT_TIP_PROBE_TIMEOUT = Duration.seconds(10);
+/**
+ * Asks the source how far its zswap event timeline goes.
+ *
+ * @remarks
+ *   Over the event subscription rather than a query, because the schema has no query that reaches a zswap ledger event:
+ *   `block`/`transactions` reach one only through a block that happens to contain zswap events, which on a quiet chain
+ *   is precisely the block that does not. `maxId` is a property of the whole timeline, so any single event answers it —
+ *   the first one delivered is taken and the subscription closed.
+ *
+ *   The cursor is the wallet's own. The event it last applied provably exists, so the source answers immediately and has
+ *   the least backfill to abandon; a wallet that has applied nothing asks from the start, where the first event is.
+ * @param config The sync configuration, for the keep-alive the source's subscriptions use.
+ * @param url Where to subscribe.
+ * @param resumeFrom The wallet's cursor; below zero means "from the very start".
+ * @returns The highest event id, or nothing if the source did not answer.
+ */
+const highestEventId = (config, url, resumeFrom) => pipe(ZswapEventTip.run({ id: resumeFrom < 0n ? null : Number(resumeFrom) }), Stream.runHead, Effect.map(Option.map((answer) => answer.zswapLedgerEvents.maxId)), Effect.provide(WsSubscriptionClient.layer({ url, keepAlive: config.indexerClientConnection.keepAlive })), Effect.scoped, Effect.timeout(EVENT_TIP_PROBE_TIMEOUT));
+/**
+ * One check of the chain's protocol version, gated on the wallet being caught up on the source's event ids.
+ *
+ * @remarks
+ *   The order of the two questions is load-bearing. The tip is read **first**: a tip reported at a version means the
+ *   source has indexed through the block that carries it, so every event below it is already counted in the `maxId`
+ *   read afterwards. Asked the other way round, an event indexed between the two answers could be one of the version
+ *   that preceded the tip — unread, uncounted, and exactly what the gate exists to catch.
+ *
+ *   Two short-circuits, both of them answers rather than shortcuts. A tip at or below the version the wallet already held
+ *   is a signal that could only be a no-op, so no probe is opened and nothing is emitted — which is what keeps a
+ *   settled wallet from polling a subscription for the rest of its life. And a tip whose commitment tree has never
+ *   grown cannot have had a nullifier spent against it either, so such a chain provably holds no zswap event: nothing
+ *   can be unread, and the signal goes out with `null`.
+ *
+ *   Everything else is swallowed. A tick that fails says nothing about the chain, so it must neither reach the state nor
+ *   take the sync stream down with it; the next tick is the retry, and costs nothing to wait for.
+ * @param config The sync configuration, for the indexer to ask.
+ * @param url Where to run the event-id probe.
+ * @param resumeFrom The wallet's cursor, for the probe.
+ * @param knownVersion The version the wallet already held when this stream opened — a lower bound on what it holds now.
+ * @returns The signal, or nothing when there is nothing to say or nobody said it.
+ */
+const readVersionSignal = (config, url, resumeFrom, knownVersion) => pipe(BlockHash.run({ offset: null }), Effect.provide(HttpQueryClient.layer({ url: config.indexerClientConnection.indexerHttpUrl })), Effect.scoped, Effect.flatMap((answer) => Option.match(Option.fromNullable(answer.block), {
+    onNone: () => Effect.succeedNone,
+    onSome: (tip) => BigInt(tip.protocolVersion) <= knownVersion
+        ? Effect.succeedNone
+        : tip.zswapEndIndex === 0
+            ? Effect.succeedSome(VersionSignalSyncUpdate.create(tip.protocolVersion, null))
+            : pipe(highestEventId(config, url, resumeFrom), Effect.map(Option.map((maxId) => VersionSignalSyncUpdate.create(tip.protocolVersion, maxId)))),
+})), Effect.catchAll(() => Effect.succeedNone));
+/**
+ * The chain's version, re-asked on a timer for as long as sync runs.
+ *
+ * @remarks
+ *   Deliberately silent about ticks that say nothing: a tick that finds the chain where the wallet left it, or that
+ *   cannot reach the chain at all, emits no element rather than an empty one, so nothing downstream has to know that
+ *   polling is how the answer was arrived at.
+ * @param config The sync configuration, carrying the interval.
+ * @param url Where to run the event-id probe.
+ * @param resumeFrom The wallet's cursor, for the probe.
+ * @param knownVersion The version the wallet held when this stream opened.
+ * @returns The signals, or an empty stream when watching is turned off.
+ */
+const versionWatch = (config, url, resumeFrom, knownVersion) => {
+    const intervalMs = config.versionWatch?.intervalMs ?? DEFAULT_VERSION_WATCH_INTERVAL_MS;
+    return intervalMs <= 0
+        ? Stream.empty
+        : pipe(Stream.fromSchedule(Schedule.spaced(Duration.millis(intervalMs))), Stream.mapEffect(() => readVersionSignal(config, url, resumeFrom, knownVersion)), Stream.filterMap(identity));
+};
+export const makeEventsSyncService = (config) => {
+    return {
+        updates: (state, secretKeys) => {
+            const { indexerClientConnection } = config;
+            const webSocketUrlResult = ConnectionHelper.createWebSocketUrl(indexerClientConnection.indexerHttpUrl, indexerClientConnection.indexerWsUrl);
+            if (Either.isLeft(webSocketUrlResult)) {
+                return Stream.fail(new SyncWalletError(new Error(`Could not derive WebSocket URL from indexer HTTP URL: ${webSocketUrlResult.left.message}`)));
+            }
+            const indexerWsUrlResult = WsURL.make(webSocketUrlResult.right);
+            if (Either.isLeft(indexerWsUrlResult)) {
+                return Stream.fail(new SyncWalletError(new Error(`Invalid indexer WS URL: ${indexerWsUrlResult.left.message}`)));
+            }
+            const indexerWsUrl = indexerWsUrlResult.right;
+            const appliedIndex = state.progress?.appliedIndex ?? 0n;
+            // The boundary is load-bearing, not waste: this subscription emits only events (no tip/progress
+            // sentinel), and `isConnected`/the tip (`maxId`) are set only when an event is received. So the
+            // cursor must stay `<= appliedIndex` — never `appliedIndex + 1`. Requesting one event later would
+            // deliver nothing to a wallet already at the tip, so `applyUpdate` would never run and sync would
+            // hang.
+            //
+            // A fresh wallet has `appliedIndex === 0n` (the "nothing applied yet" sentinel), so `resumeFrom`
+            // is `-1n` and the `variables` mapping below opens the subscription with no `id` — the indexer
+            // streams from the very start. A restored wallet has `appliedIndex >= 1`, so `resumeFrom` is
+            // `appliedIndex - 1` and the inclusive cursor re-delivers the boundary event.
+            const resumeFrom = appliedIndex - 1n;
+            const batchSize = config.batchUpdates?.size ?? 10;
+            const batchTimeout = Duration.millis(config.batchUpdates?.timeout ?? 1);
+            const batchSpacing = config.batchUpdates?.spacing ?? 4;
+            const bufferSize = config.indexerClientConnection.bufferSize ?? 10000;
+            const resumeThreshold = config.indexerClientConnection.resumeThreshold ?? 100;
+            const eventsStream = pipe(
+            // Backpressure caps the in-flight queue between the WS push and the
+            // apply loop. Without it the JS heap grows linearly with catch-up
+            // depth, since `Stream.asyncPush({ bufferSize: 'unbounded' })`
+            // buffers every event the indexer pushes regardless of apply rate.
+            ZswapEvents.runWithBackpressure({
+                bufferSize,
+                resumeThreshold,
+                from: resumeFrom,
+                // `resumeFrom < 0n` means a fresh wallet: send no `id` so the indexer streams from the very
+                // start, rather than relying on `id: 0` sorting below the first real event id.
+                variables: (cursor) => ({ id: cursor < 0n ? null : Number(cursor) }),
+                key: (r) => BigInt(r.zswapLedgerEvents.id),
+            }), Stream.provideLayer(WsSubscriptionClient.layer({ url: indexerWsUrl, keepAlive: config.indexerClientConnection.keepAlive })), Stream.mapError((error) => new SyncWalletError(error)), Stream.mapEffect((subscription) => pipe(subscription.zswapLedgerEvents, Schema.decodeUnknownEither(EventsSyncUpdateFromPayload), Either.mapLeft((err) => new SyncWalletError(err)), EitherOps.toEffect)), Stream.groupedWithin(batchSize, batchTimeout), Stream.map(Chunk.toArray), Stream.map((data) => WalletSyncUpdate.create(data, secretKeys)));
+            const timeline = batchSpacing > 0 ? Stream.schedule(eventsStream, Schedule.spaced(Duration.millis(batchSpacing))) : eventsStream;
+            // The timeline is what the source is for, so it decides when the source is done: `haltStrategy: 'left'` stops the
+            // watcher with it rather than leaving a poll loop running against a stream nobody is reading. It has nothing to
+            // say about failure — a failing timeline still fails the merged stream, where the variant's retry can see it.
+            return Stream.merge(timeline, versionWatch(config, indexerWsUrl, resumeFrom, state.protocolVersion), {
+                haltStrategy: 'left',
+            });
+        },
+    };
+};
+/** The result of an update that observed nothing of the chain. */
+const noChanges = (state) => ({
+    changes: [],
+    protocolVersion: Number(state.protocolVersion),
+});
+/**
+ * Folds what the chain said about its own version into the wallet state.
+ *
+ * @remarks
+ *   The same recording the event path makes through {@link annotateVersion}, and nothing else: no cursor moves, no coin
+ *   changes hands, no tree grows. A signal is an observation about the chain, not a piece of it — which is also why it
+ *   does not resolve pending coin hashes: it carries no keys, and the first batch of the timeline does.
+ *
+ *   One situation makes the observation unsafe to record, and it leaves the state exactly as it was: unread events below
+ *   the source's tip mean the hand-over would park the cursor in front of history the next variant cannot read — and
+ *   those events carry the version themselves, so nothing is lost by waiting for them. Not an error: the next tick asks
+ *   again.
+ *
+ *   A version at or below the one already recorded needs no guard of its own — {@link annotateVersion} never goes
+ *   backwards — so a source briefly answering from a lagging replica cannot drag a wallet back over a boundary.
+ * @param wallet The wallet to record on.
+ * @param update What the chain said, and how far its event timeline goes.
+ * @returns The wallet, annotated or untouched, and an empty result.
+ */
+const applyVersionSignal = (wallet, update) => {
+    const appliedIndex = wallet.progress?.appliedIndex ?? 0n;
+    const unreadEvents = update.highestEventId !== null && BigInt(update.highestEventId) > appliedIndex;
+    return [
+        unreadEvents
+            ? wallet
+            : annotateVersion(wallet, Option.some(ProtocolVersion.ProtocolVersion(BigInt(update.version)))),
+        noChanges(wallet),
+    ];
+};
+export const makeEventsSyncCapability = () => {
+    return {
+        applyUpdate: (wallet, wrappedUpdate, activeRange) => {
+            if (wrappedUpdate._tag === 'VersionSignal') {
+                return applyVersionSignal(wallet, wrappedUpdate);
+            }
+            // First, and before any early return: a wallet that crossed the ledger-version boundary arrives with its whole
+            // local state but neither hashes for it nor a way to un-book the spends it carried, and this update is the first
+            // place its keys are at hand. An empty batch is exactly the case that must not skip this — a wallet whose
+            // timeline has gone quiet still has to be able to name and to spend the coins it crossed with.
+            const state = CoreWallet.completeCrossing(wallet, wrappedUpdate.secretKeys);
+            if (wrappedUpdate.updates.length === 0) {
+                return [state, noChanges(state)];
+            }
+            // The subscription resumes at the last-applied index and its cursor is inclusive, so the
+            // boundary event (id === appliedIndex) is re-delivered. Replaying it would re-insert
+            // commitments already in the zswap state ("non-linear insertion" error), so only events
+            // strictly after the applied index are replayed. The boundary is still used (below) to
+            // refresh the tip and mark the wallet connected — that is how an already-caught-up wallet
+            // learns it is synced when no new events exist.
+            const appliedIndex = state.progress?.appliedIndex ?? 0n;
+            const freshUpdates = wrappedUpdate.updates.filter((u) => BigInt(u.id) > appliedIndex);
+            // The tip is a property of the source, not of what this variant chose to apply, so it is read from
+            // the batch tail even when the tail belongs to the next protocol version.
+            const lastUpdate = wrappedUpdate.updates.at(-1);
+            const highestRelevantWalletIndex = BigInt(lastUpdate.maxId);
+            const { applied, observedVersion } = splitAtVersionBoundary(freshUpdates, (update) => update.protocolVersion, activeRange);
+            // Read here and nowhere earlier: `applied` is exactly the slice this variant owns, so nothing outside its
+            // activation range — nor anything below its cursor — is ever handed to this ledger version's deserializer.
+            const [newState, newChanges] = applied.length === 0
+                ? [state, []]
+                : CoreWallet.replayEventsWithChanges(state, wrappedUpdate.secretKeys, applied.map(readEvent));
+            // `appliedIndex` stops at the last event this variant actually replayed. The next variant resumes one
+            // below it on an inclusive cursor, so the deferred suffix is re-fetched rather than skipped.
+            const updatedState = CoreWallet.updateProgress(annotateVersion(newState, observedVersion), {
+                highestRelevantWalletIndex,
+                appliedIndex: applied.length === 0 ? appliedIndex : BigInt(applied.at(-1).id),
+                isConnected: true,
+            });
+            return [
+                updatedState,
+                {
+                    changes: newChanges,
+                    // Tags the changes that were actually produced, so tx-history records the version they were applied
+                    // under rather than the one that is about to trigger the hand-over.
+                    protocolVersion: applied.at(-1)?.protocolVersion ?? Number(state.protocolVersion),
+                },
+            ];
+        },
+    };
+};
+export const SimulatorSyncUpdate = {
+    create: (update, secretKeys) => {
+        return {
+            _tag: 'Events',
+            update,
+            secretKeys,
+        };
+    },
+};
+export const makeSimulatorSyncService = (config) => {
+    return {
+        updates: (_state, secretKeys) => {
+            // Get the initial state immediately to ensure we process the genesis block.
+            // Then subscribe to state$ for subsequent changes, but deduplicate by block number
+            // to avoid processing the same block twice.
+            let lastSeenBlockNumber;
+            return pipe(Stream.fromEffect(config.simulator.getLatestState()), Stream.concat(config.simulator.state$), Stream.filter((simulatorState) => {
+                const lastBlock = getLastBlock(simulatorState);
+                if (lastBlock === undefined) {
+                    return false; // Skip blank state
+                }
+                const blockNumber = lastBlock.number;
+                // Skip if we've already seen this block (deduplication)
+                if (lastSeenBlockNumber !== undefined && blockNumber <= lastSeenBlockNumber) {
+                    return false;
+                }
+                lastSeenBlockNumber = blockNumber;
+                return true;
+            }), Stream.map((simulatorState) => SimulatorSyncUpdate.create(simulatorState, secretKeys)));
+        },
+    };
+};
+export const makeSimulatorSyncCapability = () => {
+    return {
+        applyUpdate: (wallet, update, activeRange) => {
+            const { update: simulatorState, secretKeys } = update;
+            // The same first step as the indexer capability's, for the same reason: this is where a migrated wallet's keys
+            // and its carried state first meet, and a block that turns out to hold nothing must not skip it.
+            const state = CoreWallet.completeCrossing(wallet, secretKeys);
+            const lastBlock = getLastBlock(simulatorState);
+            if (lastBlock === undefined) {
+                return [state, noChanges(state)];
+            }
+            // appliedIndex semantics: the first block number we haven't processed yet.
+            // Initial: appliedIndex = 0 (haven't processed any blocks)
+            // After processing block N: appliedIndex = N + 1 (next block to process)
+            //
+            // The boundary is applied at block granularity here — a block carries exactly one protocol version,
+            // stamped when it was produced — but it is the same rule and the same helper the indexer path uses.
+            const pending = simulatorState.blocks.filter((block) => block.number >= state.progress.appliedIndex);
+            const { applied, observedVersion } = splitAtVersionBoundary(pending, (block) => Number(block.protocolVersion), activeRange);
+            const events = applied.flatMap((block) => block.transactions.flatMap((tx) => tx.result.events));
+            const [newState, newChanges] = applied.length === 0 ? [state, []] : CoreWallet.replayEventsWithChanges(state, secretKeys, events);
+            const lastAppliedBlock = applied.at(-1);
+            return [
+                CoreWallet.updateProgress(annotateVersion(newState, observedVersion), {
+                    appliedIndex: lastAppliedBlock === undefined ? state.progress.appliedIndex : lastAppliedBlock.number + 1n,
+                }),
+                {
+                    changes: newChanges,
+                    protocolVersion: lastAppliedBlock === undefined ? Number(state.protocolVersion) : Number(lastAppliedBlock.protocolVersion),
+                },
+            ];
+        },
+    };
+};

package/dist/v2/Transacting.d.ts

@@ -0,0 +1,50 @@
+import * as ledger from '@midnightntwrk/ledger-v9';
+import { type NetworkId } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { Array as Arr, Either } from 'effect';
+import { CoreWallet } from './CoreWallet.js';
+import { type WalletError } from './WalletError.js';
+import { type CoinSelection } from '@midnight-ntwrk/wallet-sdk-capabilities';
+import { type ShieldedAddress } from '@midnight-ntwrk/wallet-sdk-address-format';
+import { TransactionImbalances } from './TransactionImbalances.js';
+import { TransactionOps } from './TransactionOps.js';
+import { type CoinsAndBalancesCapability } from './CoinsAndBalances.js';
+import { type KeysCapability } from './Keys.js';
+export interface TokenTransfer {
+    readonly amount: bigint;
+    readonly type: ledger.RawTokenType;
+    readonly receiverAddress: ShieldedAddress;
+}
+export type BalancingResult = ledger.UnprovenTransaction | undefined;
+export interface TransactingCapability<TSecrets, TState, _TTransaction> {
+    balanceTransaction(secrets: TSecrets, state: TState, tx: ledger.Transaction<ledger.Signaturish, ledger.Proofish, ledger.Bindingish>): Either.Either<[BalancingResult, TState], WalletError>;
+    makeTransfer(secrets: TSecrets, state: TState, outputs: ReadonlyArray<TokenTransfer>): Either.Either<[ledger.UnprovenTransaction, TState], WalletError>;
+    initSwap(secrets: TSecrets, state: TState, desiredInputs: Record<ledger.RawTokenType, bigint>, desiredOutputs: ReadonlyArray<TokenTransfer>): Either.Either<[ledger.UnprovenTransaction, TState], WalletError>;
+    revertTransaction(state: TState, transaction: ledger.Transaction<ledger.Signaturish, ledger.Proofish, ledger.Bindingish>): Either.Either<TState, WalletError>;
+}
+export type DefaultTransactingConfiguration = {
+    networkId: NetworkId.NetworkId;
+};
+export type DefaultTransactingContext = {
+    coinSelection: CoinSelection<ledger.QualifiedShieldedCoinInfo>;
+    coinsAndBalancesCapability: CoinsAndBalancesCapability<CoreWallet>;
+    keysCapability: KeysCapability<CoreWallet>;
+};
+export declare const makeDefaultTransactingCapability: (config: DefaultTransactingConfiguration, getContext: () => DefaultTransactingContext) => TransactingCapability<ledger.ZswapSecretKeys, CoreWallet, ledger.FinalizedTransaction>;
+export declare const makeSimulatorTransactingCapability: (config: DefaultTransactingConfiguration, getContext: () => DefaultTransactingContext) => TransactingCapability<ledger.ZswapSecretKeys, CoreWallet, ledger.ProofErasedTransaction>;
+export declare class TransactingCapabilityImplementation<TTransaction extends ledger.Transaction<ledger.Signaturish, ledger.Proofish, ledger.Bindingish>> implements TransactingCapability<ledger.ZswapSecretKeys, CoreWallet, TTransaction> {
+    #private;
+    readonly networkId: NetworkId.NetworkId;
+    readonly getCoinSelection: () => CoinSelection<ledger.QualifiedShieldedCoinInfo>;
+    readonly txOps: TransactionOps<TTransaction>;
+    readonly getCoins: () => CoinsAndBalancesCapability<CoreWallet>;
+    readonly getKeys: () => KeysCapability<CoreWallet>;
+    constructor(networkId: NetworkId.NetworkId, getCoinSelection: () => CoinSelection<ledger.QualifiedShieldedCoinInfo>, getCoins: () => CoinsAndBalancesCapability<CoreWallet>, getKeys: () => KeysCapability<CoreWallet>, txOps: TransactionOps<TTransaction>);
+    balanceTransaction(secretKeys: ledger.ZswapSecretKeys, state: CoreWallet, tx: TTransaction): Either.Either<[BalancingResult, CoreWallet], WalletError>;
+    makeTransfer(secretKeys: ledger.ZswapSecretKeys, state: CoreWallet, transfers: Arr.NonEmptyReadonlyArray<TokenTransfer>): Either.Either<[ledger.UnprovenTransaction, CoreWallet], WalletError>;
+    initSwap(secretKeys: ledger.ZswapSecretKeys, state: CoreWallet, desiredInputs: Record<ledger.RawTokenType, bigint>, desiredOutputs: ReadonlyArray<TokenTransfer>): Either.Either<[ledger.UnprovenTransaction, CoreWallet], WalletError>;
+    revertTransaction(state: CoreWallet, transaction: TTransaction | ledger.UnprovenTransaction): Either.Either<CoreWallet, WalletError>;
+    balanceFallibleSection(secretKeys: ledger.ZswapSecretKeys, state: CoreWallet, imbalances: TransactionImbalances, coinSelection: CoinSelection<ledger.QualifiedShieldedCoinInfo>): Either.Either<{
+        fallibleOffers: Map<number, ledger.ZswapOffer<ledger.PreProof>>;
+        newState: CoreWallet;
+    }, WalletError>;
+}