@midnight-ntwrk/wallet-sdk-capabilities 3.2.0 → 3.3.0

package/dist/balancer/Balancer.d.ts

@@ -1,5 +1,5 @@
-import { CounterOffer, TransactionCostModel } from './CounterOffer.js';
-import { CoinRecipe, Imbalances, TokenType, TokenValue } from './Imbalances.js';
+import { CounterOffer, type TransactionCostModel } from './CounterOffer.js';
+import type { CoinRecipe, Imbalances, TokenType, TokenValue } from './Imbalances.js';
 export declare class InsufficientFundsError extends Error {
     readonly tokenType: TokenType;
     constructor(tokenType: TokenType);

package/dist/balancer/CounterOffer.d.ts

@@ -1,4 +1,4 @@
-import { CoinRecipe, Imbalance, Imbalances, TokenType } from './Imbalances.js';
+import { type CoinRecipe, type Imbalance, Imbalances, type TokenType } from './Imbalances.js';
 export interface TransactionCostModel {
     inputFeeOverhead: bigint;
     outputFeeOverhead: bigint;

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './balancer/index.js';
 export * from './pendingTransactions/index.js';
 export * from './proving/index.js';
+export * from './simulation/index.js';
 export * from './submission/index.js';

package/dist/index.js

@@ -13,4 +13,5 @@
 export * from './balancer/index.js';
 export * from './pendingTransactions/index.js';
 export * from './proving/index.js';
+export * from './simulation/index.js';
 export * from './submission/index.js';

package/dist/pendingTransactions/pendingTransactions.d.ts

@@ -1,4 +1,4 @@
-import { DateTime, Either, ParseResult, Schema } from 'effect';
+import { type DateTime, Either, type ParseResult, Schema } from 'effect';
 export type TransactionTrait<TTransaction> = {
     ids: (tx: TTransaction) => readonly string[];
     firstId: (tx: TTransaction) => string;

package/dist/pendingTransactions/pendingTransactionsService.d.ts

@@ -1,7 +1,7 @@
-import { Clock, Effect, ParseResult, Scope, Stream } from 'effect';
+import { type Clock, Effect, type ParseResult, Scope, Stream } from 'effect';
 import * as PendingTransactions from './pendingTransactions.js';
-import * as rx from 'rxjs';
-import { QueryClient } from '@midnight-ntwrk/wallet-sdk-indexer-client/effect';
+import type * as rx from 'rxjs';
+import { type QueryClient } from '@midnight-ntwrk/wallet-sdk-indexer-client/effect';
 export type PendingTransactionsService<TTransaction> = {
     start: () => Promise<void>;
     stop: () => Promise<void>;

package/dist/proving/provingService.d.ts

@@ -1,8 +1,8 @@
 import * as ledger from '@midnight-ntwrk/ledger-v8';
 import type { KeyMaterialProvider } from '@midnight-ntwrk/zkir-v2';
-import { InvalidProtocolSchemeError } from '@midnight-ntwrk/wallet-sdk-utilities/networking';
+import { type InvalidProtocolSchemeError } from '@midnight-ntwrk/wallet-sdk-utilities/networking';
 import { Effect } from 'effect';
-declare const ProvingError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+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<{

package/dist/proving/provingService.js

@@ -12,7 +12,7 @@
 // limitations under the License.
 import * as ledger from '@midnight-ntwrk/ledger-v8';
 import { HttpProverClient, WasmProver } from '@midnight-ntwrk/wallet-sdk-prover-client/effect';
-import { ClientError, ServerError } from '@midnight-ntwrk/wallet-sdk-utilities/networking';
+import { ClientError, ServerError, } from '@midnight-ntwrk/wallet-sdk-utilities/networking';
 import { Data, Effect, pipe } from 'effect';
 export class ProvingError extends Data.TaggedError('Wallet.Proving') {
 }

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 '@midnight-ntwrk/wallet-sdk-utilities';
+import { NetworkId } from '@midnight-ntwrk/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>;
+}