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

package/dist/simulation/v8/SimulatorState.js

@@ -0,0 +1,290 @@
+// 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.
+/**
+ * SimulatorState types and pure functions for state manipulation.
+ *
+ * This module contains the core data types and pure functions for working with simulator state. All functions are
+ * synchronous and side-effect free.
+ */
+import { Either, Function as EFunction, Array as EArray } from 'effect';
+import { LedgerState, WellFormedStrictness, TransactionContext, } from '@midnight-ntwrk/ledger-v8';
+import { DateOps, LedgerOps } from '@midnight-ntwrk/wallet-sdk-utilities';
+import { ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { blockHash, protocolVersionAt, } from '../core/index.js';
+// Version-agnostic simulator internals, re-exported so each version's barrel presents one complete surface.
+export { blockHash, defaultStrictness, genesisStrictness, getProtocolVersion, nextBlockContextFromBlock, protocolVersionAt, scheduleFork, setProtocolVersion, } from '../core/index.js';
+/**
+ * Assign strictness to a pending transaction, creating a ready transaction. If the pending transaction already has
+ * strictness, use it; otherwise use the provided default.
+ */
+export const assignStrictness = (pendingTx, defaultStrictness) => ({
+    tx: pendingTx.tx,
+    strictness: pendingTx.strictness ?? defaultStrictness,
+});
+/**
+ * Assign strictness to all pending transactions, creating ready transactions. Transactions with existing strictness
+ * keep their strictness; others get the default.
+ */
+export const assignStrictnessToAll = (transactions, defaultStrictness) => transactions.map((tx) => assignStrictness(tx, defaultStrictness));
+// =============================================================================
+// State Accessors (Pure Functions)
+// =============================================================================
+/** Get the last produced block, or undefined if no blocks yet. */
+export const getLastBlock = (state) => EArray.lastNonEmpty(state.blocks);
+/** Get the current block number (height of the last block, or 0 if no blocks). */
+export const getCurrentBlockNumber = (state) => getLastBlock(state)?.number;
+/** Get a block by its number. */
+export const getBlockByNumber = EFunction.dual(2, (state, number) => state.blocks.find((b) => b.number === number));
+/** Get all transaction results from the last block. */
+export const getLastBlockResults = (state) => getLastBlock(state)?.transactions.map((t) => t.result) ?? [];
+/** Get all events from the last block (flattened from all transactions). */
+export const getLastBlockEvents = (state) => getLastBlockResults(state).flatMap((r) => r.events);
+/**
+ * Get all events from blocks with number >= fromBlockNumber. Returns events ordered by block number, with each block's
+ * transactions flattened.
+ *
+ * Use this with the wallet's next-to-process index: `appliedIndex` after processing should be set to `lastBlockNumber +
+ * 1`, not `lastBlockNumber`.
+ */
+export const getBlockEventsFrom = EFunction.dual(2, (state, fromBlockNumber) => state.blocks
+    .filter((b) => b.number >= fromBlockNumber)
+    .flatMap((b) => b.transactions.flatMap((t) => t.result.events)));
+/**
+ * @deprecated Use getBlockEventsFrom instead with proper appliedIndex semantics Get all events from blocks with number
+ *
+ * > AfterBlockNumber.
+ */
+export const getBlockEventsSince = EFunction.dual(2, (state, afterBlockNumber) => state.blocks
+    .filter((b) => b.number > afterBlockNumber)
+    .flatMap((b) => b.transactions.flatMap((t) => t.result.events)));
+/** Check if there are pending transactions in the mempool. */
+export const hasPendingTransactions = (state) => state.mempool.length > 0;
+/** Get the current simulator time. */
+export const getCurrentTime = (state) => state.currentTime;
+// =============================================================================
+// State Transformations (Pure Functions)
+// =============================================================================
+/** Resolve fullness from spec and state. */
+export const resolveFullness = (spec, state) => typeof spec === 'function' ? spec(state) : spec;
+/** Create a block production request that includes all mempool transactions. */
+export const allMempoolTransactions = (state, fullness, defaultStrictness) => ({
+    transactions: assignStrictnessToAll(state.mempool, defaultStrictness),
+    fullness,
+});
+/**
+ * Create a blank initial state.
+ *
+ * @param networkId - Network identifier
+ * @param options - Optional genesis parameters
+ * @param options.protocolVersion - Version the chain starts on (defaults to the minimum supported version)
+ * @param options.genesisBlockNumber - Height of the genesis block (defaults to 0; a ledger-v9 chain continues numbering
+ *   from the fork height instead)
+ * @param options.genesisTime - Timestamp of the genesis block (defaults to the epoch)
+ */
+export const blankState = async (networkId, options) => {
+    const protocolVersion = options?.protocolVersion ?? ProtocolVersion.MinSupportedVersion;
+    const genesisBlockNumber = options?.genesisBlockNumber ?? 0n;
+    const genesisTime = options?.genesisTime ?? new Date(0);
+    const blankGenesis = {
+        number: genesisBlockNumber,
+        hash: await blockHash(genesisBlockNumber),
+        timestamp: genesisTime,
+        transactions: [],
+        protocolVersion,
+    };
+    return {
+        networkId,
+        ledger: LedgerState.blank(networkId),
+        blocks: [blankGenesis],
+        mempool: [],
+        currentTime: genesisTime,
+        protocolVersion,
+        scheduledForks: [],
+    };
+};
+/** Add a pending transaction to the mempool. */
+export const addToMempool = (state, pendingTx) => ({
+    ...state,
+    mempool: [...state.mempool, pendingTx],
+});
+/** Remove transactions from the mempool. */
+export const removeFromMempool = (state, transactions) => {
+    const txsToRemove = new Set(transactions.map((t) => t.tx));
+    return {
+        ...state,
+        mempool: state.mempool.filter((pending) => !txsToRemove.has(pending.tx)),
+    };
+};
+/** Advance the simulator time by the given number of seconds. */
+export const advanceTime = (state, seconds) => ({
+    ...state,
+    currentTime: DateOps.addSeconds(state.currentTime, seconds),
+});
+/** Update the ledger state. */
+export const updateLedger = (state, ledger) => ({
+    ...state,
+    ledger,
+});
+/** Append a block to the state and update time. */
+export const appendBlock = (state, block, newLedger) => ({
+    ...state,
+    ledger: newLedger,
+    blocks: [...state.blocks, block],
+    currentTime: block.timestamp,
+});
+// =============================================================================
+// Transaction Application (Pure Function)
+// =============================================================================
+/**
+ * Pure state transition: apply a transaction to the simulator state. Returns Either with the new state or an error.
+ *
+ * @param state - Current simulator state
+ * @param tx - Transaction to apply
+ * @param strictness - Well-formedness strictness options
+ * @param blockContext - Block context for the transaction
+ * @param options - Optional parameters
+ * @param options.blockNumber - Override block number (defaults to last block + 1)
+ * @param options.blockFullness - Override detailed block fullness (SyntheticCost)
+ * @param options.overallBlockFullness - Override overall block fullness (0-1 value)
+ */
+export const applyTransaction = (state, tx, strictness, blockContext, options) => {
+    return LedgerOps.ledgerTry(() => {
+        const computedFullness = options?.blockFullness ?? tx.cost(state.ledger.parameters);
+        const detailedBlockFullness = state.ledger.parameters.normalizeFullness(computedFullness);
+        const computedBlockFullness = options?.overallBlockFullness ??
+            Math.max(detailedBlockFullness.readTime, detailedBlockFullness.computeTime, detailedBlockFullness.blockUsage, detailedBlockFullness.bytesWritten, detailedBlockFullness.bytesChurned);
+        const blockNumber = options?.blockNumber ?? getCurrentBlockNumber(state) + 1n;
+        const protocolVersion = protocolVersionAt(state, blockNumber);
+        const blockTime = state.currentTime;
+        const verifiedTransaction = tx.wellFormed(state.ledger, strictness, blockTime);
+        const transactionContext = new TransactionContext(state.ledger, blockContext);
+        const [newLedgerState, txResult] = state.ledger.apply(verifiedTransaction, transactionContext);
+        const newBlock = {
+            number: blockNumber,
+            hash: blockContext.parentBlockHash,
+            timestamp: blockTime,
+            transactions: [{ tx, result: txResult }],
+            protocolVersion,
+        };
+        const newState = {
+            ...state,
+            ledger: newLedgerState.postBlockUpdate(blockTime, detailedBlockFullness, computedBlockFullness),
+            blocks: [...state.blocks, newBlock],
+            protocolVersion,
+        };
+        return [newBlock, newState];
+    });
+};
+/**
+ * Process a single pending transaction against the latest ledger state. Returns Either with the processing result or an
+ * error.
+ *
+ * @param ledger - The ledger state to process against
+ * @param readyTx - Transaction to process
+ * @param blockTime - Block timestamp
+ * @param blockContext - Block context
+ * @param minFullness - Minimum block fullness to use
+ */
+export const processTransaction = (ledger, readyTx, blockTime, blockContext, minFullness) => {
+    return LedgerOps.ledgerTry(() => {
+        const computedFullness = readyTx.tx.cost(ledger.parameters);
+        const detailedBlockFullness = ledger.parameters.normalizeFullness(computedFullness);
+        const computedBlockFullness = Math.max(minFullness, detailedBlockFullness.readTime, detailedBlockFullness.computeTime, detailedBlockFullness.blockUsage, detailedBlockFullness.bytesWritten, detailedBlockFullness.bytesChurned);
+        // Use the assigned strictness
+        const verifiedTransaction = readyTx.tx.wellFormed(ledger, readyTx.strictness, blockTime);
+        const transactionContext = new TransactionContext(ledger, blockContext);
+        const [newLedgerState, txResult] = ledger.apply(verifiedTransaction, transactionContext);
+        const postBlockLedger = newLedgerState.postBlockUpdate(blockTime, detailedBlockFullness, computedBlockFullness);
+        return {
+            tx: readyTx.tx,
+            result: txResult,
+            newLedger: postBlockLedger,
+        };
+    });
+};
+/**
+ * Process multiple transactions in sequence, accumulating results. Returns Either with all results and final ledger, or
+ * first error. Each transaction uses its assigned strictness (from ReadyTransaction).
+ *
+ * @param ledger - Initial ledger state
+ * @param transactions - Transactions to process (each with assigned strictness)
+ * @param blockTime - Block timestamp
+ * @param blockContext - Block context
+ * @param fullness - Block fullness (0-1)
+ */
+export const processTransactions = (ledger, transactions, blockTime, blockContext, fullness) => transactions.reduce((acc, readyTx) => Either.flatMap(acc, ({ blockTransactions, finalLedger }) => Either.map(processTransaction(finalLedger, readyTx, blockTime, blockContext, fullness), (result) => ({
+    blockTransactions: [...blockTransactions, { tx: result.tx, result: result.result }],
+    finalLedger: result.newLedger,
+}))), Either.right({ blockTransactions: [], finalLedger: ledger }));
+/**
+ * Create a block from processed transactions and update state. Pure function that takes pre-computed block hash.
+ *
+ * @param state - Current simulator state
+ * @param blockTransactions - Processed transactions to include
+ * @param blockHash - Pre-computed block hash
+ * @param blockTime - Block timestamp
+ * @param newLedger - New ledger state after processing transactions
+ * @param processedTxs - Ready transactions to remove from mempool
+ */
+export const createBlock = (state, blockTransactions, blockHashValue, blockTime, newLedger, processedTxs) => {
+    const nextBlockNumber = getCurrentBlockNumber(state) + 1n;
+    // Resolved once, at production time: the block and the chain's current version cannot disagree.
+    const protocolVersion = protocolVersionAt(state, nextBlockNumber);
+    const block = {
+        number: nextBlockNumber,
+        hash: blockHashValue,
+        timestamp: blockTime,
+        transactions: blockTransactions,
+        protocolVersion,
+    };
+    const txsToRemove = new Set(processedTxs.map((t) => t.tx));
+    const newState = {
+        ...state,
+        ledger: newLedger,
+        blocks: [...state.blocks, block],
+        mempool: state.mempool.filter((pending) => !txsToRemove.has(pending.tx)),
+        currentTime: blockTime,
+        protocolVersion,
+    };
+    return [block, newState];
+};
+/**
+ * Create an empty block (no transactions) and update state.
+ *
+ * @param state - Current simulator state
+ * @param blockHashValue - Pre-computed block hash
+ * @param blockTime - Block timestamp
+ * @param processedTxs - Original pending transactions to remove from mempool (if any)
+ */
+export const createEmptyBlock = (state, blockHashValue, blockTime, processedTxs = []) => {
+    return createBlock(state, [], blockHashValue, blockTime, state.ledger, processedTxs);
+};
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Create a WellFormedStrictness instance with configurable options. All options default to false for maximum testing
+ * flexibility.
+ *
+ * Note: WellFormedStrictness is a class from the ledger library that requires mutation to configure. This is
+ * unavoidable given the external API design.
+ */
+export const createStrictness = (config = {}) => {
+    const strictness = new WellFormedStrictness();
+    strictness.enforceBalancing = config.enforceBalancing ?? false;
+    strictness.verifyNativeProofs = config.verifyNativeProofs ?? false;
+    strictness.verifyContractProofs = config.verifyContractProofs ?? false;
+    strictness.enforceLimits = config.enforceLimits ?? false;
+    strictness.verifySignatures = config.verifySignatures ?? false;
+    return strictness;
+};

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

@@ -0,0 +1,2 @@
+export { getLastBlock, getCurrentBlockNumber, getCurrentTime, getProtocolVersion, protocolVersionAt, getBlockByNumber, getLastBlockResults, getLastBlockEvents, getBlockEventsFrom, getBlockEventsSince, hasPendingTransactions, resolveFullness, allMempoolTransactions, blankState, addToMempool, removeFromMempool, advanceTime, updateLedger, appendBlock, applyTransaction, setProtocolVersion, scheduleFork, 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 ScheduledFork, type StrictnessConfig, } from './SimulatorState.js';
+export { Simulator, immediateBlockProducer, type SimulatorConfig } from './Simulator.js';

package/dist/simulation/v8/index.js

@@ -0,0 +1,26 @@
+// 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.
+// Re-export everything from SimulatorState
+export { 
+// State accessor functions (composable with simulator.query())
+getLastBlock, getCurrentBlockNumber, getCurrentTime, getProtocolVersion, protocolVersionAt, getBlockByNumber, getLastBlockResults, getLastBlockEvents, getBlockEventsFrom, getBlockEventsSince, hasPendingTransactions, 
+// State transformation functions
+resolveFullness, allMempoolTransactions, blankState, addToMempool, removeFromMempool, advanceTime, updateLedger, appendBlock, applyTransaction, setProtocolVersion, scheduleFork, 
+// 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';

package/dist/simulation/{Simulator.d.ts → v9/Simulator.d.ts}

@@ -12,10 +12,10 @@
 import { type Array as Arr, Effect, type Scope, Stream, SubscriptionRef } from 'effect';
 import { type ProofErasedTransaction, type SignatureVerifyingKey } from '@midnightntwrk/ledger-v9';
 import { LedgerOps } from '@midnight-ntwrk/wallet-sdk-utilities';
-import { NetworkId } from '@midnight-ntwrk/wallet-sdk-abstractions';
+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, StrictnessConfig, } from './SimulatorState.js';
-export { getLastBlock, getCurrentBlockNumber, getBlockByNumber, getLastBlockResults, getLastBlockEvents, hasPendingTransactions, getCurrentTime, applyTransaction, defaultStrictness, genesisStrictness, createStrictness, } 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.
  *
@@ -37,6 +37,25 @@ export type SimulatorConfig = Readonly<{
     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.
@@ -85,11 +104,19 @@ export declare class Simulator {
     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.
+     * tokens are auto-detected by comparing tokenType with `Token.night`.
      */
     private static initWithGenesis;
-    /** Create a Simulator from an initial state with proper stream setup. */
-    private static fromState;
+    /**
+     * 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>);
@@ -141,6 +168,30 @@ export declare class Simulator {
     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.

package/dist/simulation/{Simulator.js → v9/Simulator.js}

@@ -22,10 +22,10 @@
  * - Time advancement for TTL and time-sensitive tests
  */
 import { Effect, Either, pipe, Stream, SubscriptionRef } from 'effect';
-import { addressFromKey, ClaimRewardsTransaction, createShieldedCoinInfo, Intent, LedgerState, nativeToken, SignatureErased, Transaction, TransactionContext, UnshieldedOffer, ZswapOffer, ZswapOutput, } from '@midnightntwrk/ledger-v9';
+import { addressFromKey, ClaimRewardsTransaction, createShieldedCoinInfo, Intent, LedgerState, SignatureErased, Transaction, TransactionContext, UnshieldedOffer, ZswapOffer, ZswapOutput, } from '@midnightntwrk/ledger-v9';
 import { DateOps, LedgerOps } from '@midnight-ntwrk/wallet-sdk-utilities';
-import { NetworkId } from '@midnight-ntwrk/wallet-sdk-abstractions';
-import { addToMempool, allMempoolTransactions, blankState, blockHash, createBlock, createEmptyBlock, createStrictness, defaultStrictness, genesisStrictness, getLastBlock, hasPendingTransactions, nextBlockContextFromBlock, processTransactions, removeFromMempool, resolveFullness, } from './SimulatorState.js';
+import { NetworkId, ProtocolVersion, Token } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { addToMempool, allMempoolTransactions, blankState, blockHash, createBlock, createEmptyBlock, createStrictness, defaultStrictness, genesisStrictness, getLastBlock, hasPendingTransactions, nextBlockContextFromBlock, processTransactions, removeFromMempool, resolveFullness, scheduleFork, setProtocolVersion, } from './SimulatorState.js';
 // =============================================================================
 // Type Guards and Helpers for Genesis Mints
 // =============================================================================
@@ -34,12 +34,12 @@ const isShieldedMint = (mint) => mint.type === 'shielded';
 /** Type guard for unshielded genesis mint. */
 const isUnshieldedMint = (mint) => mint.type === 'unshielded';
 /**
- * Check if an unshielded mint is for the native Night token. Night is auto-detected by comparing tokenType with
- * ledger.nativeToken().raw.
+ * Check if an unshielded mint is for the native Night token. Night is auto-detected by comparing tokenType with the
+ * SDK's own `Token.night`, which is what both ledger versions call the native token.
  */
-const isNightToken = (tokenType) => tokenType === nativeToken().raw;
+const isNightToken = (tokenType) => tokenType === Token.night;
 // Re-export state accessors for backward compatibility
-export { getLastBlock, getCurrentBlockNumber, getBlockByNumber, getLastBlockResults, getLastBlockEvents, hasPendingTransactions, getCurrentTime, applyTransaction, defaultStrictness, genesisStrictness, createStrictness, } from './SimulatorState.js';
+export { getLastBlock, getCurrentBlockNumber, getBlockByNumber, getLastBlockResults, getLastBlockEvents, hasPendingTransactions, getCurrentTime, getProtocolVersion, protocolVersionAt, applyTransaction, defaultStrictness, genesisStrictness, createStrictness, } from './SimulatorState.js';
 // =============================================================================
 // Block Producers
 // =============================================================================
@@ -102,19 +102,28 @@ export class Simulator {
      */
     static init(config = {}) {
         const networkId = config.networkId ?? NetworkId.NetworkId.Undeployed;
+        const genesis = {
+            protocolVersion: config.protocolVersion ?? ProtocolVersion.MinSupportedVersion,
+            blockNumber: config.genesisBlockNumber ?? 0n,
+            time: config.genesisTime ?? new Date(0),
+        };
         return config.genesisMints !== undefined && config.genesisMints.length > 0
-            ? Simulator.initWithGenesis(config.genesisMints, networkId, config.blockProducer)
-            : Simulator.initBlank(networkId, config.blockProducer);
+            ? Simulator.initWithGenesis(config.genesisMints, networkId, genesis, config.blockProducer)
+            : Simulator.initBlank(networkId, genesis, config.blockProducer);
     }
     /** Initialize simulator with blank ledger state. */
-    static initBlank(networkId, blockProducer) {
-        return pipe(Effect.promise(() => blankState(networkId)), Effect.flatMap((state) => Simulator.fromState(state, blockProducer)));
+    static initBlank(networkId, genesis, blockProducer) {
+        return pipe(Effect.promise(() => blankState(networkId, {
+            protocolVersion: genesis.protocolVersion,
+            genesisBlockNumber: genesis.blockNumber,
+            genesisTime: genesis.time,
+        })), Effect.flatMap((state) => Simulator.fromState(state, blockProducer)));
     }
     /**
      * 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.
+     * tokens are auto-detected by comparing tokenType with `Token.night`.
      */
-    static initWithGenesis(genesisMints, networkId = NetworkId.NetworkId.Undeployed, blockProducer) {
+    static initWithGenesis(genesisMints, networkId = NetworkId.NetworkId.Undeployed, genesis, blockProducer) {
         const noStrictness = createStrictness();
         // Pure function to extract shielded mint data (returns array for flatMap)
         const toShieldedMint = (mint) => isShieldedMint(mint) ? [{ tokenType: mint.tokenType, amount: mint.amount, keys: mint.recipient }] : [];
@@ -124,7 +133,7 @@ export class Simulator {
             ? [{ tokenType: mint.tokenType, amount: mint.amount, recipient: mint.recipient }]
             : [];
         // Pure function to extract Night mint data from unshielded mints (returns array for flatMap)
-        // Night is auto-detected by comparing tokenType with nativeToken().raw
+        // Night is auto-detected by comparing tokenType with `Token.night`
         const toNightMint = (mint) => isUnshieldedMint(mint) && isNightToken(mint.tokenType) && mint.verifyingKey !== undefined
             ? [{ amount: mint.amount, recipient: mint.recipient, verifyingKey: mint.verifyingKey }]
             : [];
@@ -185,9 +194,9 @@ export class Simulator {
             return { ledgerState: newState, tx: proofErasedTx, result };
         };
         return Effect.gen(function* () {
-            const genesisTime = new Date(0);
+            const genesisTime = genesis.time;
             const emptyState = LedgerState.blank(networkId);
-            const context = yield* Effect.promise(() => nextBlockContextFromBlock(undefined, genesisTime));
+            const context = yield* Effect.promise(() => nextBlockContextFromBlock(undefined, genesisTime, genesis.blockNumber));
             // Process shielded and unshielded mints first
             const init = makeInitialTransactions(emptyState, context, genesisTime);
             // Apply post-block update before processing Night mints
@@ -211,10 +220,11 @@ export class Simulator {
             const allTransactions = [...init.transactions, ...nightResults.transactions];
             // Create genesis block with all transactions
             const genesisBlock = {
-                number: 0n,
+                number: genesis.blockNumber,
                 hash: context.parentBlockHash,
                 timestamp: genesisTime,
                 transactions: allTransactions,
+                protocolVersion: genesis.protocolVersion,
             };
             const initialState = {
                 networkId,
@@ -222,11 +232,21 @@ export class Simulator {
                 blocks: [genesisBlock],
                 mempool: [],
                 currentTime: genesisTime, // Time stays at genesis; next block will advance it
+                protocolVersion: genesis.protocolVersion,
+                scheduledForks: [],
             };
             return yield* Simulator.fromState(initialState, blockProducer);
         });
     }
-    /** Create a Simulator from an initial state with proper stream setup. */
+    /**
+     * 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, blockProducer) {
         return Effect.gen(function* () {
             const stateRef = yield* SubscriptionRef.make(initialState);
@@ -353,6 +373,36 @@ export class Simulator {
         const pendingTx = options?.strictness !== undefined ? { tx, strictness: createStrictness(options.strictness) } : { tx };
         return SubscriptionRef.update(this.#stateRef, (s) => addToMempool(s, pendingTx));
     }
+    /**
+     * 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() {
+        return this.#produceBlock({ transactions: [], fullness: 0 });
+    }
+    /**
+     * 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) {
+        return SubscriptionRef.update(this.#stateRef, (state) => setProtocolVersion(state, version));
+    }
+    /**
+     * 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, version) {
+        return SubscriptionRef.update(this.#stateRef, (state) => scheduleFork(state, atBlock, version));
+    }
     /**
      * 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.