@midnight-ntwrk/wallet-sdk-capabilities 4.0.0-beta.2 → 4.0.0-beta.4

package/dist/simulation/v8/Simulator.d.ts

@@ -0,0 +1,231 @@
+/**
+ * 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, ProtocolVersion } 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, ScheduledFork, StrictnessConfig, } from './SimulatorState.js';
+export { getLastBlock, getCurrentBlockNumber, getBlockByNumber, getLastBlockResults, getLastBlockEvents, hasPendingTransactions, getCurrentTime, getProtocolVersion, protocolVersionAt, 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;
+    /**
+     * Protocol version the chain starts on. Defaults to {@link ProtocolVersion.MinSupportedVersion}.
+     *
+     * The version a fork activates is never built in — schedule it with {@link Simulator.scheduleFork} or switch to it
+     * with {@link Simulator.setProtocolVersion}.
+     */
+    protocolVersion?: ProtocolVersion.ProtocolVersion;
+    /**
+     * Height of the genesis block. Defaults to 0.
+     *
+     * Set this to continue an existing chain's numbering, as a ledger-v9 chain does from the fork height.
+     */
+    genesisBlockNumber?: bigint;
+    /**
+     * Timestamp of the genesis block, from which simulator time advances. Defaults to the epoch.
+     *
+     * Set this to continue an existing chain's timeline, so that time-sensitive behaviour does not restart at the epoch.
+     */
+    genesisTime?: Date;
+}>;
+/**
+ * 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 `Token.night`.
+     */
+    private static initWithGenesis;
+    /**
+     * Create a Simulator from an initial state with proper stream setup.
+     *
+     * The low-level constructor behind {@link Simulator.init}. Use it when the initial state cannot be expressed as a
+     * config — most importantly a ledger-v9 chain, whose ledger is handed over from the chain before it.
+     *
+     * @param initialState - State the simulator starts from
+     * @param blockProducer - Custom block producer (defaults to immediateBlockProducer())
+     */
+    static fromState(initialState: SimulatorState, blockProducer?: BlockProducer): Effect.Effect<Simulator, never, Scope.Scope>;
+    /** 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>;
+    /**
+     * Produce a block with no transactions, advancing the chain by one height.
+     *
+     * Bypasses the configured block producer, which only produces when there is something in the mempool. Use it to reach
+     * a given height without traffic — a fork happens at a height whether or not transactions were submitted.
+     *
+     * @returns The produced block
+     */
+    produceEmptyBlock(): Effect.Effect<Block, LedgerOps.LedgerError>;
+    /**
+     * Switch the chain to a protocol version, effective for blocks produced from now on. Already-produced blocks keep the
+     * version they were produced under.
+     *
+     * @param version - Version to switch the chain to
+     */
+    setProtocolVersion(version: ProtocolVersion.ProtocolVersion): Effect.Effect<void>;
+    /**
+     * Schedule a protocol version to activate at a block height — a fork on the simulated chain. The block produced at
+     * that height, and every block after it, is stamped with `version`.
+     *
+     * @param atBlock - Height of the first block produced under `version`
+     * @param version - Version that activates at `atBlock`
+     */
+    scheduleFork(atBlock: bigint, version: ProtocolVersion.ProtocolVersion): 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>;
+}