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

package/dist/simulation/core/VersionTimeline.d.ts

@@ -0,0 +1,54 @@
+import { type ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
+/**
+ * A protocol version scheduled to activate at a block height — a fork on the simulated chain.
+ *
+ * The version itself is always supplied by the caller: the protocol version of the real fork is not final, so nothing
+ * in the simulator may assume a particular value.
+ */
+export type ScheduledFork = Readonly<{
+    /** Height of the first block produced under {@link version}. */
+    atBlock: bigint;
+    /** Version that activates at {@link atBlock}. */
+    version: ProtocolVersion.ProtocolVersion;
+}>;
+/**
+ * The version-timeline part of a simulator state — the current version plus any scheduled activations.
+ *
+ * Every simulator state satisfies this structurally, so the functions below apply to all of them without knowing which
+ * ledger the state's other fields belong to.
+ */
+export type VersionTimeline = Readonly<{
+    protocolVersion: ProtocolVersion.ProtocolVersion;
+    scheduledForks: readonly ScheduledFork[];
+}>;
+/** Get the protocol version the chain is currently on. */
+export declare const getProtocolVersion: (timeline: VersionTimeline) => ProtocolVersion.ProtocolVersion;
+/**
+ * Resolve the protocol version a block of the given height is produced under: the highest scheduled version whose
+ * activation height has been reached, or the chain's current version when no schedule applies.
+ *
+ * Scheduling a version at a height the chain has already passed therefore activates it on the next block rather than
+ * rewriting history — produced blocks keep the version they were produced under.
+ *
+ * @param timeline - Current version timeline
+ * @param blockNumber - Height of the block being produced
+ */
+export declare const protocolVersionAt: {
+    (blockNumber: bigint): (timeline: VersionTimeline) => ProtocolVersion.ProtocolVersion;
+    (timeline: VersionTimeline, blockNumber: bigint): ProtocolVersion.ProtocolVersion;
+};
+/**
+ * Set the protocol version blocks produced from now on are stamped with. Already-produced blocks are untouched.
+ *
+ * @param state - Current simulator state
+ * @param version - Version to switch the chain to
+ */
+export declare const setProtocolVersion: <TState extends VersionTimeline>(state: TState, version: ProtocolVersion.ProtocolVersion) => TState;
+/**
+ * Schedule a protocol version to activate at a block height — a fork on the simulated chain.
+ *
+ * @param state - Current simulator state
+ * @param atBlock - Height of the first block produced under `version`
+ * @param version - Version that activates at `atBlock`
+ */
+export declare const scheduleFork: <TState extends VersionTimeline>(state: TState, atBlock: bigint, version: ProtocolVersion.ProtocolVersion) => TState;

package/dist/simulation/core/VersionTimeline.js

@@ -0,0 +1,56 @@
+// 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.
+/**
+ * A simulated chain's protocol-version timeline.
+ *
+ * Which protocol version a chain is on, and when it changes, is the same question whichever ledger the chain runs — so
+ * it is answered once here and shared by every simulator, rather than duplicated per ledger version.
+ *
+ * Nothing in this module refers to a ledger type. Functions are stated over the smallest structure they need
+ * ({@link VersionTimeline}), which every simulator state satisfies.
+ */
+import { Function as EFunction } from 'effect';
+/** Get the protocol version the chain is currently on. */
+export const getProtocolVersion = (timeline) => timeline.protocolVersion;
+/**
+ * Resolve the protocol version a block of the given height is produced under: the highest scheduled version whose
+ * activation height has been reached, or the chain's current version when no schedule applies.
+ *
+ * Scheduling a version at a height the chain has already passed therefore activates it on the next block rather than
+ * rewriting history — produced blocks keep the version they were produced under.
+ *
+ * @param timeline - Current version timeline
+ * @param blockNumber - Height of the block being produced
+ */
+export const protocolVersionAt = EFunction.dual(2, (timeline, blockNumber) => timeline.scheduledForks.reduce((version, fork) => (fork.atBlock <= blockNumber && fork.version > version ? fork.version : version), timeline.protocolVersion));
+/**
+ * Set the protocol version blocks produced from now on are stamped with. Already-produced blocks are untouched.
+ *
+ * @param state - Current simulator state
+ * @param version - Version to switch the chain to
+ */
+export const setProtocolVersion = (state, version) => ({
+    ...state,
+    protocolVersion: version,
+});
+/**
+ * Schedule a protocol version to activate at a block height — a fork on the simulated chain.
+ *
+ * @param state - Current simulator state
+ * @param atBlock - Height of the first block produced under `version`
+ * @param version - Version that activates at `atBlock`
+ */
+export const scheduleFork = (state, atBlock, version) => ({
+    ...state,
+    scheduledForks: [...state.scheduledForks, { atBlock, version }],
+});

package/dist/simulation/core/blocks.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The context a block is executed against.
+ *
+ * Structurally the ledger's own `BlockContext`, which is a plain record and is defined identically by ledger-v8 and
+ * ledger-v9 — so it is stated once here and a value of this type is accepted by either ledger.
+ */
+export type BlockContext = Readonly<{
+    /** Hash of the parent block */
+    parentBlockHash: string;
+    /** Seconds elapsed since the UNIX epoch */
+    secondsSinceEpoch: bigint;
+    /** Maximum expected error on {@link secondsSinceEpoch}, as a positive number of seconds */
+    secondsSinceEpochErr: number;
+    /** Seconds since the previous block */
+    lastBlockTime: bigint;
+}>;
+/** The part of a produced block that block timing needs — its height and when it was produced. */
+export type PreviousBlock = Readonly<{
+    number: bigint;
+    timestamp: Date;
+}>;
+/**
+ * Compute block hash from block number. Uses a deterministic hash based on block number for easy recomputation.
+ *
+ * @param blockNumber - The block number to compute hash for
+ * @returns A deterministic 64-character hex hash
+ */
+export declare const blockHash: (blockNumber: bigint) => Promise<string>;
+/**
+ * Create the next block context from the previous block.
+ *
+ * @param previousBlock - The previous block (or undefined for genesis)
+ * @param blockTime - The timestamp for the new block
+ * @param blockNumber - Height of the new block, overriding the height derived from `previousBlock`. Needed for a
+ *   genesis block that continues an existing chain's numbering, as a ledger-v9 chain's does.
+ * @returns A BlockContext suitable for transaction processing
+ */
+export declare const nextBlockContextFromBlock: (previousBlock: PreviousBlock | undefined, blockTime: Date, blockNumber?: bigint) => Promise<BlockContext>;

package/dist/simulation/core/blocks.js

@@ -0,0 +1,52 @@
+// 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.
+/**
+ * Block identity and timing for a simulated chain — how a block is hashed and what context it is executed against.
+ *
+ * Neither depends on the ledger a chain runs, so both are shared by every simulator.
+ */
+import { DateOps } from '@midnight-ntwrk/wallet-sdk-utilities';
+/**
+ * Compute block hash from block number. Uses a deterministic hash based on block number for easy recomputation.
+ *
+ * @param blockNumber - The block number to compute hash for
+ * @returns A deterministic 64-character hex hash
+ */
+export const blockHash = async (blockNumber) => {
+    const input = `block-${blockNumber.toString()}`;
+    const hashBuffer = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(input));
+    const { Encoding } = await import('effect');
+    return Encoding.encodeHex(new Uint8Array(hashBuffer));
+};
+/**
+ * Create the next block context from the previous block.
+ *
+ * @param previousBlock - The previous block (or undefined for genesis)
+ * @param blockTime - The timestamp for the new block
+ * @param blockNumber - Height of the new block, overriding the height derived from `previousBlock`. Needed for a
+ *   genesis block that continues an existing chain's numbering, as a ledger-v9 chain's does.
+ * @returns A BlockContext suitable for transaction processing
+ */
+export const nextBlockContextFromBlock = async (previousBlock, blockTime, blockNumber) => {
+    const nextBlockNumber = blockNumber ?? (previousBlock !== undefined ? previousBlock.number + 1n : 0n);
+    const hash = await blockHash(nextBlockNumber);
+    const blockSeconds = DateOps.dateToSeconds(blockTime);
+    const previousSeconds = previousBlock !== undefined ? DateOps.dateToSeconds(previousBlock.timestamp) : blockSeconds - 1n;
+    const timeSinceLastBlock = blockSeconds - previousSeconds;
+    return {
+        parentBlockHash: hash,
+        secondsSinceEpoch: blockSeconds,
+        secondsSinceEpochErr: 1, // Clock error tolerance in seconds (reasonable default for simulator)
+        lastBlockTime: timeSinceLastBlock > 0n ? timeSinceLastBlock : 1n,
+    };
+};

package/dist/simulation/core/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Simulator internals that are the same whichever ledger a simulated chain runs.
+ *
+ * The ledger-v8 and ledger-v9 simulators are otherwise twins, so anything here is written once instead of once per
+ * version. The rule for what belongs: it must not name a ledger type. Everything that constructs or applies ledger
+ * objects — the ledger state, transactions, strictness objects, genesis minting — stays in the per-version simulators,
+ * because that is what genuinely differs between them.
+ *
+ * Not a published entry point; re-exported through each version's barrel.
+ */
+export { getProtocolVersion, protocolVersionAt, scheduleFork, setProtocolVersion, type ScheduledFork, type VersionTimeline, } from './VersionTimeline.js';
+export { blockHash, nextBlockContextFromBlock, type BlockContext, type PreviousBlock } from './blocks.js';
+export { defaultStrictness, genesisStrictness, type StrictnessConfig } from './strictness.js';

package/dist/simulation/core/index.js

@@ -0,0 +1,25 @@
+// 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.
+/**
+ * Simulator internals that are the same whichever ledger a simulated chain runs.
+ *
+ * The ledger-v8 and ledger-v9 simulators are otherwise twins, so anything here is written once instead of once per
+ * version. The rule for what belongs: it must not name a ledger type. Everything that constructs or applies ledger
+ * objects — the ledger state, transactions, strictness objects, genesis minting — stays in the per-version simulators,
+ * because that is what genuinely differs between them.
+ *
+ * Not a published entry point; re-exported through each version's barrel.
+ */
+export { getProtocolVersion, protocolVersionAt, scheduleFork, setProtocolVersion, } from './VersionTimeline.js';
+export { blockHash, nextBlockContextFromBlock } from './blocks.js';
+export { defaultStrictness, genesisStrictness } from './strictness.js';

package/dist/simulation/core/strictness.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Which well-formedness checks a simulated chain enforces, as plain configuration.
+ *
+ * The configuration and its presets say nothing about a ledger, so they are shared. Turning one into the ledger's
+ * `WellFormedStrictness` object is per-ledger and stays with each simulator (`createStrictness`).
+ */
+/** Configuration for well-formedness strictness checks. All options default to false for testing flexibility. */
+export type StrictnessConfig = Readonly<{
+    enforceBalancing?: boolean;
+    verifyNativeProofs?: boolean;
+    verifyContractProofs?: boolean;
+    enforceLimits?: boolean;
+    verifySignatures?: boolean;
+}>;
+/**
+ * Default strictness for post-genesis blocks.
+ *
+ * In a realistic simulation:
+ *
+ * - Signatures should be verified (verifySignatures: true)
+ * - Proofs cannot be verified because they're erased (verifyNativeProofs/verifyContractProofs: false)
+ * - Limits should be enforced (enforceLimits: true)
+ * - Balancing must be enforced (enforceBalancing: true) - transactions must pay fees
+ *
+ * Note: Genesis blocks typically disable all strictness to allow initial token distribution.
+ */
+export declare const defaultStrictness: StrictnessConfig;
+/** Strictness for genesis blocks - all checks disabled to allow initial token distribution. */
+export declare const genesisStrictness: StrictnessConfig;

package/dist/simulation/core/strictness.js

@@ -0,0 +1,39 @@
+// 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.
+/**
+ * Default strictness for post-genesis blocks.
+ *
+ * In a realistic simulation:
+ *
+ * - Signatures should be verified (verifySignatures: true)
+ * - Proofs cannot be verified because they're erased (verifyNativeProofs/verifyContractProofs: false)
+ * - Limits should be enforced (enforceLimits: true)
+ * - Balancing must be enforced (enforceBalancing: true) - transactions must pay fees
+ *
+ * Note: Genesis blocks typically disable all strictness to allow initial token distribution.
+ */
+export const defaultStrictness = {
+    enforceBalancing: true,
+    verifyNativeProofs: false,
+    verifyContractProofs: false,
+    enforceLimits: true,
+    verifySignatures: true,
+};
+/** Strictness for genesis blocks - all checks disabled to allow initial token distribution. */
+export const genesisStrictness = {
+    enforceBalancing: false,
+    verifyNativeProofs: false,
+    verifyContractProofs: false,
+    enforceLimits: false,
+    verifySignatures: false,
+};

package/dist/simulation/index.d.ts

@@ -1,2 +1,22 @@
-export { getLastBlock, getCurrentBlockNumber, getCurrentTime, getBlockByNumber, getLastBlockResults, getLastBlockEvents, getBlockEventsFrom, getBlockEventsSince, hasPendingTransactions, resolveFullness, allMempoolTransactions, blankState, addToMempool, removeFromMempool, advanceTime, updateLedger, appendBlock, applyTransaction, processTransaction, processTransactions, createBlock, createEmptyBlock, type TransactionProcessingResult, createStrictness, blockHash, assignStrictness, assignStrictnessToAll, defaultStrictness, genesisStrictness, type SimulatorState, type Block, type BlockTransaction, type BlockInfo, type PendingTransaction, type ReadyTransaction, type BlockProductionRequest, type BlockProducer, type FullnessSpec, type GenesisMint, type StrictnessConfig, } from './SimulatorState.js';
-export { Simulator, immediateBlockProducer, type SimulatorConfig } from './Simulator.js';
+/**
+ * Simulated ledger environments for wallet testing.
+ *
+ * There is one simulator per ledger version, in `v8/` and `v9/`. They are twins: the same simulator over a different
+ * ledger, so a chain on either side of the hard fork is driven with the same API. Their shared, ledger-agnostic
+ * internals live in `core/`.
+ *
+ * - **{@link V9}** — the ledger-v9 line. Also re-exported unqualified below, so `Simulator` and friends mean the v9
+ *   simulator; this is what existing code gets.
+ * - **{@link V8}** — the ledger-v8 line. Used to drive a chain before the v9 fork, standalone or via {@link ForkSimulator}.
+ * - **{@link ForkSimulator}** — the two composed into a single chain that crosses the fork.
+ *
+ * Both namespaces are needed at once only when working across the boundary; the qualified form is what keeps the two
+ * apart, since the twins export identical names over structurally distinct ledger types.
+ */
+export * from './v9/index.js';
+/** The ledger-v9 simulator. Same as the unqualified exports above, named for symmetry with {@link V8}. */
+export * as V9 from './v9/index.js';
+/** The ledger-v8 simulator. */
+export * as V8 from './v8/index.js';
+export { ForkSimulator, type ForkSimulatorConfig } from './ForkSimulator.js';
+export { LedgerTranslationError, translatorFromAsync, unavailableTranslator, type LedgerStateTranslator, } from './LedgerTranslation.js';

package/dist/simulation/index.js

@@ -10,17 +10,28 @@
 // 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.
-// Re-export everything from SimulatorState
-export { 
-// State accessor functions (composable with simulator.query())
-getLastBlock, getCurrentBlockNumber, getCurrentTime, getBlockByNumber, getLastBlockResults, getLastBlockEvents, getBlockEventsFrom, getBlockEventsSince, hasPendingTransactions, 
-// State transformation functions
-resolveFullness, allMempoolTransactions, blankState, addToMempool, removeFromMempool, advanceTime, updateLedger, appendBlock, applyTransaction, 
-// Block production functions
-processTransaction, processTransactions, createBlock, createEmptyBlock, 
-// Helper functions
-createStrictness, blockHash, assignStrictness, assignStrictnessToAll, 
-// Strictness constants
-defaultStrictness, genesisStrictness, } from './SimulatorState.js';
-// Re-export from Simulator
-export { Simulator, immediateBlockProducer } from './Simulator.js';
+/**
+ * Simulated ledger environments for wallet testing.
+ *
+ * There is one simulator per ledger version, in `v8/` and `v9/`. They are twins: the same simulator over a different
+ * ledger, so a chain on either side of the hard fork is driven with the same API. Their shared, ledger-agnostic
+ * internals live in `core/`.
+ *
+ * - **{@link V9}** — the ledger-v9 line. Also re-exported unqualified below, so `Simulator` and friends mean the v9
+ *   simulator; this is what existing code gets.
+ * - **{@link V8}** — the ledger-v8 line. Used to drive a chain before the v9 fork, standalone or via {@link ForkSimulator}.
+ * - **{@link ForkSimulator}** — the two composed into a single chain that crosses the fork.
+ *
+ * Both namespaces are needed at once only when working across the boundary; the qualified form is what keeps the two
+ * apart, since the twins export identical names over structurally distinct ledger types.
+ */
+// The ledger-v9 simulator, unqualified: the default for code that does not span a fork.
+export * from './v9/index.js';
+/** The ledger-v9 simulator. Same as the unqualified exports above, named for symmetry with {@link V8}. */
+export * as V9 from './v9/index.js';
+/** The ledger-v8 simulator. */
+export * as V8 from './v8/index.js';
+// A chain that crosses the fork, built from both twins.
+export { ForkSimulator } from './ForkSimulator.js';
+// Carrying ledger state across the fork.
+export { LedgerTranslationError, translatorFromAsync, unavailableTranslator, } from './LedgerTranslation.js';

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>;
+}