@midnightntwrk/wallet-sdk-capabilities 3.3.1

package/dist/pendingTransactions/pendingTransactionsService.js

@@ -0,0 +1,146 @@
+/*
+ * 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 { DateTime, DefaultServices, Duration, Effect, Exit, Iterable, Option, pipe, Schedule, Scope, Stream, SubscriptionRef, } from 'effect';
+import * as PendingTransactions from './pendingTransactions.js';
+import { HttpQueryClient } from '@midnightntwrk/wallet-sdk-indexer-client/effect';
+import { TransactionStatus } from '@midnightntwrk/wallet-sdk-indexer-client';
+import { EitherOps, ObservableOps } from '@midnightntwrk/wallet-sdk-utilities';
+export class PendingTransactionsServiceImpl {
+    static init(initParams) {
+        return PendingTransactionsServiceImpl.initEffect(initParams).pipe(Effect.runPromise);
+    }
+    static restore(data, txTrait, configuration) {
+        return pipe(PendingTransactions.deserialize(data, txTrait), EitherOps.toEffect, Effect.andThen((state) => PendingTransactionsServiceImpl.initEffect({ txTrait, initialState: state, configuration })), Effect.runPromise);
+    }
+    static initEffect(initParams) {
+        return Effect.gen(function* () {
+            const service = new PendingTransactionsServiceEffectImpl(initParams.txTrait, initParams.initialState);
+            const scope = yield* Scope.make();
+            return new PendingTransactionsServiceImpl(service, scope, initParams.configuration);
+        });
+    }
+    #effectService;
+    #scope;
+    #configuration;
+    constructor(effectService, scope, configuration) {
+        this.#effectService = effectService;
+        this.#scope = scope;
+        this.#configuration = configuration;
+    }
+    addPendingTransaction(tx) {
+        return this.#effectService.addPendingTransaction(tx).pipe(Effect.runPromise);
+    }
+    clear(tx) {
+        return this.#effectService.clear(tx).pipe(Effect.runPromise);
+    }
+    start() {
+        return this.#effectService.startPolling(Stream.tick(Duration.seconds(1))).pipe(Effect.provide(HttpQueryClient.layer({
+            url: this.#configuration.indexerClientConnection.indexerHttpUrl,
+        })), Effect.provideService(Scope.Scope, this.#scope), Effect.provide(DefaultServices.liveServices), Effect.runFork, () => Promise.resolve());
+    }
+    state() {
+        return this.#effectService.state().pipe(ObservableOps.fromStream);
+    }
+    stop() {
+        return pipe(Scope.close(this.#scope, Exit.succeed(undefined)), Effect.runPromise);
+    }
+}
+export class PendingTransactionsServiceEffectImpl {
+    #state;
+    #txTrait;
+    static restore(data, txTrait) {
+        return pipe(data, (data) => PendingTransactions.deserialize(data, txTrait), EitherOps.toEffect, Effect.map((state) => new PendingTransactionsServiceEffectImpl(txTrait, state)));
+    }
+    constructor(txTrait, initialState) {
+        this.#txTrait = txTrait;
+        this.#state = SubscriptionRef.make(initialState ?? PendingTransactions.empty()).pipe(Effect.runSync); // Should not be here, but otherwise initialization would be too involved
+    }
+    state() {
+        return Stream.concat(Stream.fromEffect(SubscriptionRef.get(this.#state)), this.#state.changes);
+    }
+    startPolling(ticks) {
+        return ticks.pipe(Stream.mapEffect(() => SubscriptionRef.get(this.#state)), Stream.mapConcat(PendingTransactions.allPending), Stream.mapConcatEffect((item) => {
+            return Effect.gen(this, function* () {
+                const now = yield* DateTime.now;
+                const result = yield* this.queryForStatus(item.tx);
+                return Option.match(result, {
+                    onSome: (status) => [{ ...item, result: status }],
+                    onNone: () => {
+                        const failedResult = {
+                            status: 'FAILURE',
+                            segments: [],
+                        };
+                        return this.#txTrait.hasTTLExpired(item.tx, item.creationTime, now)
+                            ? [{ ...item, result: failedResult }]
+                            : [];
+                    },
+                });
+            });
+        }), Stream.retry(pipe(Schedule.exponential(Duration.millis(1)), Schedule.jitteredWith({ min: 0.1, max: 1.2 }), Schedule.resetAfter(Duration.minutes(5)))), Stream.catchAll((error) => {
+            return Stream.execute(Effect.logWarning(error, 'Caught error in PendingTransactionsService'));
+        }), Stream.runForEachScoped((item) => {
+            return this.saveResult(item.tx, item.result);
+        }));
+    }
+    addPendingTransaction(tx) {
+        return SubscriptionRef.updateEffect(this.#state, (state) => {
+            return DateTime.now.pipe(Effect.andThen((now) => PendingTransactions.addPendingTransaction(state, tx, now, this.#txTrait)));
+        });
+    }
+    clear(tx) {
+        return SubscriptionRef.update(this.#state, (state) => {
+            return PendingTransactions.clear(state, tx, this.#txTrait);
+        });
+    }
+    saveResult(tx, result) {
+        switch (result.status) {
+            case 'SUCCESS':
+                return this.clear(tx);
+            case 'FAILURE':
+            case 'PARTIAL_SUCCESS':
+                return SubscriptionRef.update(this.#state, (state) => {
+                    return PendingTransactions.saveResult(state, tx, result, this.#txTrait);
+                });
+        }
+    }
+    queryForStatus(tx) {
+        return Effect.gen(this, function* () {
+            const statusQuery = yield* TransactionStatus;
+            const result = yield* statusQuery({ transactionId: this.#txTrait.firstId(tx) }).pipe(Effect.catchAll((error) => {
+                const fallback = { transactions: [] };
+                return pipe(Effect.logWarning(error, 'Observed error in PendingTransactionsService, retrying'), Effect.as(fallback));
+            }));
+            return pipe(result.transactions, Iterable.filterMap((res) => {
+                if (res.__typename == 'SystemTransaction') {
+                    return Option.none();
+                }
+                if (res.transactionResult.status != 'SUCCESS' &&
+                    res.transactionResult.status != 'FAILURE' &&
+                    res.transactionResult.status != 'PARTIAL_SUCCESS') {
+                    return Option.none();
+                }
+                if (this.#txTrait.areAllTxIdsIncluded(tx, res.identifiers)) {
+                    return Option.some({
+                        status: res.transactionResult.status,
+                        segments: res.transactionResult.segments ?? [],
+                    });
+                }
+                else {
+                    return Option.none();
+                }
+            }), Iterable.head);
+        });
+    }
+}

package/dist/proving/index.d.ts

@@ -0,0 +1 @@
+export * from './provingService.js';

package/dist/proving/index.js

@@ -0,0 +1,15 @@
+/*
+ * 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.
+ */
+export * from './provingService.js';

package/dist/proving/provingService.d.ts

@@ -0,0 +1,37 @@
+import * as ledger from '@midnight-ntwrk/ledger-v8';
+import type { KeyMaterialProvider } from '@midnight-ntwrk/zkir-v2';
+import { type InvalidProtocolSchemeError } from '@midnightntwrk/wallet-sdk-utilities/networking';
+import { Effect } from 'effect';
+declare const ProvingError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "Wallet.Proving";
+} & Readonly<A>;
+export declare class ProvingError extends ProvingError_base<{
+    message: string;
+    cause: Error;
+}> {
+}
+export interface ProvingServiceEffect<TTransaction> {
+    prove(transaction: ledger.UnprovenTransaction): Effect.Effect<TTransaction, ProvingError>;
+}
+export interface ProvingService<TTransaction> {
+    prove(transaction: ledger.UnprovenTransaction): Promise<TTransaction>;
+}
+export type UnboundTransaction = ledger.Transaction<ledger.SignatureEnabled, ledger.Proof, ledger.PreBinding>;
+export declare const fromProvingProviderEffect: (provider: Effect.Effect<ledger.ProvingProvider, InvalidProtocolSchemeError>) => ProvingServiceEffect<UnboundTransaction>;
+export declare const fromProvingProvider: (provider: ledger.ProvingProvider) => ProvingServiceEffect<UnboundTransaction>;
+export type ServerProvingConfiguration = {
+    provingServerUrl: URL;
+};
+export type WasmProvingConfiguration = {
+    keyMaterialProvider?: KeyMaterialProvider;
+};
+export type DefaultProvingConfiguration = ServerProvingConfiguration;
+export declare const makeServerProvingServiceEffect: (configuration: ServerProvingConfiguration) => ProvingServiceEffect<UnboundTransaction>;
+export declare const makeWasmProvingServiceEffect: (configuration?: WasmProvingConfiguration) => ProvingServiceEffect<UnboundTransaction>;
+export declare const makeSimulatorProvingServiceEffect: () => ProvingServiceEffect<ledger.ProofErasedTransaction>;
+export declare const makeDefaultProvingServiceEffect: (configuration: DefaultProvingConfiguration) => ProvingServiceEffect<UnboundTransaction>;
+export declare const makeDefaultProvingService: (configuration: DefaultProvingConfiguration) => ProvingService<UnboundTransaction>;
+export declare const makeServerProvingService: (configuration: ServerProvingConfiguration) => ProvingService<UnboundTransaction>;
+export declare const makeWasmProvingService: (configuration?: WasmProvingConfiguration) => ProvingService<UnboundTransaction>;
+export declare const makeSimulatorProvingService: () => ProvingService<ledger.ProofErasedTransaction>;
+export {};

package/dist/proving/provingService.js

@@ -0,0 +1,61 @@
+// 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 { HttpProverClient, WasmProver } from '@midnightntwrk/wallet-sdk-prover-client/effect';
+import { ClientError, ServerError, } from '@midnightntwrk/wallet-sdk-utilities/networking';
+import { Data, Effect, pipe } from 'effect';
+export class ProvingError extends Data.TaggedError('Wallet.Proving') {
+}
+const wrapEffectService = (effectService) => ({
+    prove: (transaction) => Effect.runPromise(effectService.prove(transaction)),
+});
+export const fromProvingProviderEffect = (provider) => {
+    return {
+        prove(transaction) {
+            return pipe(provider, Effect.flatMap((provider) => Effect.tryPromise({
+                try: () => transaction.prove(provider, ledger.CostModel.initialCostModel()),
+                catch: (error) => error instanceof ClientError || error instanceof ServerError
+                    ? error
+                    : new ClientError({ message: 'Failed to prove transaction', cause: error }),
+            })), Effect.catchAll((error) => Effect.fail(new ProvingError({
+                message: error.message,
+                cause: error,
+            }))));
+        },
+    };
+};
+export const fromProvingProvider = (provider) => {
+    return fromProvingProviderEffect(Effect.succeed(provider));
+};
+export const makeServerProvingServiceEffect = (configuration) => {
+    return pipe(HttpProverClient.create({
+        url: configuration.provingServerUrl,
+    }), Effect.map((client) => client.asProvingProvider()), fromProvingProviderEffect);
+};
+export const makeWasmProvingServiceEffect = (configuration) => {
+    return pipe(WasmProver.create({
+        keyMaterialProvider: configuration?.keyMaterialProvider ?? WasmProver.makeDefaultKeyMaterialProvider(),
+    }), Effect.map((prover) => prover.asProvingProvider()), fromProvingProviderEffect);
+};
+export const makeSimulatorProvingServiceEffect = () => {
+    return {
+        prove(transaction) {
+            return Effect.succeed(transaction.eraseProofs());
+        },
+    };
+};
+export const makeDefaultProvingServiceEffect = (configuration) => makeServerProvingServiceEffect(configuration);
+export const makeDefaultProvingService = (configuration) => wrapEffectService(makeDefaultProvingServiceEffect(configuration));
+export const makeServerProvingService = (configuration) => wrapEffectService(makeServerProvingServiceEffect(configuration));
+export const makeWasmProvingService = (configuration) => wrapEffectService(makeWasmProvingServiceEffect(configuration));
+export const makeSimulatorProvingService = () => wrapEffectService(makeSimulatorProvingServiceEffect());

package/dist/simulation/Simulator.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Unified Simulator for wallet testing.
+ *
+ * This module provides a simulated ledger environment for testing wallet functionality without requiring a real
+ * blockchain node. It supports:
+ *
+ * - Optional genesis mints for pre-funded accounts (shielded, unshielded, or Night tokens)
+ * - Transaction submission with configurable strictness
+ * - Night token rewards via rewardNight()
+ * - Time advancement for TTL and time-sensitive tests
+ */
+import { type Array as Arr, Effect, type Scope, Stream, SubscriptionRef } from 'effect';
+import { type ProofErasedTransaction, type SignatureVerifyingKey } from '@midnight-ntwrk/ledger-v8';
+import { LedgerOps } from '@midnightntwrk/wallet-sdk-utilities';
+import { NetworkId } from '@midnightntwrk/wallet-sdk-abstractions';
+import { type Block, type BlockProducer, type FullnessSpec, type GenesisMint, type SimulatorState, type StrictnessConfig } from './SimulatorState.js';
+export type { SimulatorState, Block, BlockTransaction, PendingTransaction, BlockInfo, BlockProductionRequest, BlockProducer, FullnessSpec, GenesisMint, StrictnessConfig, } from './SimulatorState.js';
+export { getLastBlock, getCurrentBlockNumber, getBlockByNumber, getLastBlockResults, getLastBlockEvents, hasPendingTransactions, getCurrentTime, applyTransaction, defaultStrictness, genesisStrictness, createStrictness, } from './SimulatorState.js';
+/**
+ * Default block producer: produces a block for each state change with non-empty mempool.
+ *
+ * By default, uses post-genesis strictness (balancing, signatures, limits enforced). This ensures realistic simulation
+ * where transactions must be properly balanced (pay fees).
+ *
+ * @param fullness - Static fullness (0-1) or callback based on state
+ * @param strictness - Strictness config (defaults to defaultStrictness)
+ */
+export declare const immediateBlockProducer: (fullness?: FullnessSpec, strictness?: StrictnessConfig) => BlockProducer;
+/** Simulator initialization configuration. */
+export type SimulatorConfig = Readonly<{
+    /**
+     * Pre-funded accounts to create at genesis. When provided, creates a genesis block with transactions minting tokens
+     * to recipients. When omitted, the simulator starts with an empty ledger.
+     */
+    genesisMints?: Arr.NonEmptyArray<GenesisMint>;
+    /** Network identifier. Defaults to Undeployed. */
+    networkId?: NetworkId.NetworkId;
+    /** Custom block producer. Defaults to immediateBlockProducer(). */
+    blockProducer?: BlockProducer;
+}>;
+/**
+ * Unified simulator for wallet testing.
+ *
+ * Provides a simulated ledger environment for testing wallet functionality without a real blockchain. Optionally
+ * pre-funds accounts via genesis mints.
+ *
+ * @example
+ *   ```typescript
+ *   // Empty ledger (useful for dust/Night token testing via rewardNight)
+ *   const simulator = yield* Simulator.init({});
+ *
+ *   // Pre-funded accounts (useful for token transfer testing)
+ *   const simulator = yield* Simulator.init({
+ *     genesisMints: [{ amount: 1000n, tokenType, shieldedRecipient: secretKeys }],
+ *   });
+ *   ```;
+ */
+export declare class Simulator {
+    #private;
+    /**
+     * Initialize a new simulator.
+     *
+     * @example
+     *   ```typescript
+     *   // Empty ledger - use rewardNight() for Night tokens
+     *   const simulator = yield* Simulator.init({});
+     *
+     *   // Pre-funded accounts for token transfer testing
+     *   const simulator = yield* Simulator.init({
+     *     genesisMints: [{ amount: 1000n, tokenType, shieldedRecipient: secretKeys }],
+     *   });
+     *
+     *   // With custom network ID
+     *   const simulator = yield* Simulator.init({
+     *     networkId: NetworkId.Preview,
+     *     genesisMints: [...],
+     *   });
+     *   ```;
+     *
+     * @param config - Configuration options (all optional)
+     * @returns Effect that produces a Simulator instance
+     */
+    static init(config?: SimulatorConfig): Effect.Effect<Simulator, never, Scope.Scope>;
+    /** Initialize simulator with blank ledger state. */
+    private static initBlank;
+    /**
+     * Initialize simulator with genesis mints (pre-funded accounts). Supports shielded and unshielded token mints. Night
+     * tokens are auto-detected by comparing tokenType with nativeToken().raw.
+     */
+    private static initWithGenesis;
+    /** Create a Simulator from an initial state with proper stream setup. */
+    private static fromState;
+    /** Observable stream of simulator state changes. */
+    readonly state$: Stream.Stream<SimulatorState>;
+    constructor(stateRef: SubscriptionRef.SubscriptionRef<SimulatorState>, state$: Stream.Stream<SimulatorState>);
+    /** Get the current simulator state. */
+    getLatestState(): Effect.Effect<SimulatorState>;
+    /**
+     * Distribute Night tokens to a recipient and submit claim transaction to mempool. Used for testing dust token
+     * generation.
+     *
+     * This method:
+     *
+     * 1. Modifies the ledger to make Night tokens claimable
+     * 2. Creates and submits a ClaimRewardsTransaction to the mempool
+     * 3. The block producer will process the transaction
+     *
+     * @param verifyingKey - Signature verifying key (recipient address is derived from it)
+     * @param amount - Amount of Night tokens to distribute
+     */
+    rewardNight(verifyingKey: SignatureVerifyingKey, amount: bigint): Effect.Effect<Block, LedgerOps.LedgerError>;
+    /**
+     * Submit a transaction and wait for it to be included in a block.
+     *
+     * This method adds the transaction to the mempool and blocks until the block producer includes it in a block. Use
+     * this when you need confirmation that the transaction was processed.
+     *
+     * For fire-and-forget scenarios where you don't need to wait for block inclusion, use `submitAndForget` instead.
+     *
+     * @param tx - Transaction to submit (proofs erased)
+     * @param options - Optional submission options
+     * @param options.strictness - Override well-formedness strictness
+     * @returns The block containing the transaction
+     */
+    submitTransaction(tx: ProofErasedTransaction, options?: {
+        strictness?: StrictnessConfig;
+    }): Effect.Effect<Block, LedgerOps.LedgerError>;
+    /**
+     * Submit a transaction without waiting for block inclusion.
+     *
+     * This method adds the transaction to the mempool and returns immediately. The block producer will process it
+     * asynchronously. Use this for fire-and-forget scenarios or when testing custom block producers with batched
+     * transactions.
+     *
+     * To wait for block inclusion, use `submitTransaction` instead.
+     *
+     * @param tx - Transaction to submit (proofs erased)
+     * @param options - Optional options
+     * @param options.strictness - Override well-formedness strictness
+     */
+    submitAndForget(tx: ProofErasedTransaction, options?: {
+        strictness?: StrictnessConfig;
+    }): Effect.Effect<void>;
+    /**
+     * Fast-forward the simulator time by the given number of seconds. Does not produce a block - only advances the
+     * internal clock. Useful for testing time-sensitive functionality like TTL.
+     *
+     * @param seconds - Number of seconds to advance (must be positive)
+     */
+    fastForward(seconds: bigint): Effect.Effect<void>;
+    /**
+     * Query the simulator state with a custom function. This is a generic query mechanism that allows extracting any
+     * information from the current state without modifying it.
+     *
+     * @example
+     *   ```typescript
+     *   // Query fee prices
+     *   const feePrices = yield* simulator.query(state => state.ledger.parameters.feePrices);
+     *
+     *   // Use composable state accessors
+     *   const blockNumber = yield* simulator.query(getCurrentBlockNumber);
+     *   const lastBlock = yield* simulator.query(getLastBlock);
+     *   const events = yield* simulator.query(getLastBlockEvents);
+     *
+     *   // Query UTXOs for an address
+     *   const utxos = yield* simulator.query(state => Array.from(state.ledger.utxo.filter(address)));
+     *
+     *   // Complex query returning multiple values
+     *   const info = yield* simulator.query(state => ({
+     *     networkId: state.networkId,
+     *     blockNumber: getCurrentBlockNumber(state),
+     *     feePrices: state.ledger.parameters.feePrices,
+     *   }));
+     *   ```;
+     *
+     * @param fn - Function that receives the current state and returns a result
+     * @returns The result of applying the function to the current state
+     */
+    query<T>(fn: (state: SimulatorState) => T): Effect.Effect<T>;
+}