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

package/dist/simulation/v8/Simulator.js

@@ -0,0 +1,503 @@
+// 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.
+/**
+ * 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 { Effect, Either, pipe, Stream, SubscriptionRef } from 'effect';
+import { addressFromKey, ClaimRewardsTransaction, createShieldedCoinInfo, Intent, LedgerState, SignatureErased, Transaction, TransactionContext, UnshieldedOffer, ZswapOffer, ZswapOutput, } from '@midnight-ntwrk/ledger-v8';
+import { DateOps, LedgerOps } from '@midnight-ntwrk/wallet-sdk-utilities';
+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
+// =============================================================================
+/** Type guard for shielded genesis mint. */
+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 the
+ * SDK's own `Token.night`, which is what both ledger versions call the native token.
+ */
+const isNightToken = (tokenType) => tokenType === Token.night;
+// Re-export state accessors for backward compatibility
+export { getLastBlock, getCurrentBlockNumber, getBlockByNumber, getLastBlockResults, getLastBlockEvents, hasPendingTransactions, getCurrentTime, getProtocolVersion, protocolVersionAt, applyTransaction, defaultStrictness, genesisStrictness, createStrictness, } from './SimulatorState.js';
+// =============================================================================
+// Block Producers
+// =============================================================================
+/**
+ * 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 const immediateBlockProducer = (fullness = 0.5, strictness = defaultStrictness) => (states) => states.pipe(Stream.filter(hasPendingTransactions), Stream.map((s) => allMempoolTransactions(s, resolveFullness(fullness, s), createStrictness(strictness))));
+// =============================================================================
+// Simulator Class
+// =============================================================================
+/**
+ * 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 class Simulator {
+    // ===========================================================================
+    // Static Methods
+    // ===========================================================================
+    /**
+     * 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 = {}) {
+        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, genesis, config.blockProducer)
+            : Simulator.initBlank(networkId, genesis, config.blockProducer);
+    }
+    /** Initialize simulator with blank ledger state. */
+    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 `Token.night`.
+     */
+    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 }] : [];
+        // Pure function to extract non-Night unshielded mint data (returns array for flatMap)
+        // Night is auto-detected by tokenType and excluded from regular unshielded minting
+        const toCustomUnshieldedMint = (mint) => isUnshieldedMint(mint) && !isNightToken(mint.tokenType)
+            ? [{ 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 `Token.night`
+        const toNightMint = (mint) => isUnshieldedMint(mint) && isNightToken(mint.tokenType) && mint.verifyingKey !== undefined
+            ? [{ amount: mint.amount, recipient: mint.recipient, verifyingKey: mint.verifyingKey }]
+            : [];
+        // Pure function to create a ZswapOffer from shielded mint data
+        const createShieldedOffer = (transfer) => {
+            const coin = createShieldedCoinInfo(transfer.tokenType, transfer.amount);
+            const output = ZswapOutput.new(coin, 0, transfer.keys.coinPublicKey, transfer.keys.encryptionPublicKey);
+            return ZswapOffer.fromOutput(output, transfer.tokenType, transfer.amount);
+        };
+        // Pure function to create an Intent with UnshieldedOffer
+        // Note: Intent API requires mutation, isolated here
+        const createUnshieldedIntent = (mints, ttl) => {
+            const outputs = mints.map((mint) => ({ type: mint.tokenType, value: mint.amount, owner: mint.recipient }));
+            const intent = Intent.new(ttl);
+            intent.guaranteedUnshieldedOffer = UnshieldedOffer.new([], outputs, []);
+            return intent;
+        };
+        // Process shielded and custom unshielded mints in initial block (Night handled separately)
+        const makeInitialTransactions = (ledgerState, context, blockTime) => {
+            const verificationTime = blockTime;
+            // Separate mints by type using flatMap (pure, no mutation)
+            // Night tokens are excluded and handled separately via reward/claim mechanism
+            const shieldedMints = genesisMints.flatMap(toShieldedMint);
+            const customUnshieldedMints = genesisMints.flatMap(toCustomUnshieldedMint);
+            // If no shielded or custom unshielded mints, return empty result
+            if (shieldedMints.length === 0 && customUnshieldedMints.length === 0) {
+                return {
+                    initialState: ledgerState,
+                    transactions: [],
+                };
+            }
+            // Create ZswapOffer for shielded mints (if any)
+            const zswapOffer = shieldedMints.length > 0
+                ? shieldedMints.map(createShieldedOffer).reduce((acc, offer) => acc.merge(offer))
+                : undefined;
+            // Create Intent with UnshieldedOffer for custom unshielded mints (if any)
+            const ttl = new Date(blockTime.getTime() + 3600 * 1000); // 1 hour TTL from block time
+            const intent = customUnshieldedMints.length > 0 ? createUnshieldedIntent(customUnshieldedMints, ttl) : undefined;
+            // Build transaction from parts
+            const proofErasedTx = Transaction.fromParts(networkId, zswapOffer, undefined, intent).eraseProofs();
+            const verifiedTx = proofErasedTx.wellFormed(ledgerState, noStrictness, verificationTime);
+            const [newState, result] = ledgerState.apply(verifiedTx, new TransactionContext(ledgerState, context));
+            return {
+                initialState: newState,
+                transactions: [{ tx: proofErasedTx, result }],
+            };
+        };
+        // Process a single Night mint by distributing Night and creating claim transaction
+        const processNightMint = (ledgerState, mint, blockTime, context) => {
+            // Distribute Night tokens (makes them claimable)
+            const ledgerWithReward = ledgerState.testingDistributeNight(mint.recipient, mint.amount, blockTime);
+            // Create claim transaction
+            const signature = new SignatureErased();
+            const claimTx = new ClaimRewardsTransaction(signature.instance, networkId, mint.amount, mint.verifyingKey, LedgerOps.randomNonce(), signature);
+            const proofErasedTx = Transaction.fromRewards(claimTx).eraseProofs();
+            const verifiedTx = proofErasedTx.wellFormed(ledgerWithReward, noStrictness, blockTime);
+            const [newState, result] = ledgerWithReward.apply(verifiedTx, new TransactionContext(ledgerWithReward, context));
+            return { ledgerState: newState, tx: proofErasedTx, result };
+        };
+        return Effect.gen(function* () {
+            const genesisTime = genesis.time;
+            const emptyState = LedgerState.blank(networkId);
+            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
+            // Night distribution requires the ledger to be in a consistent post-block state
+            const postBlockState = init.initialState.postBlockUpdate(genesisTime);
+            // Process Night mints sequentially using reduce (pure functional fold)
+            const nightMints = genesisMints.flatMap(toNightMint);
+            const nightResults = nightMints.reduce((acc, mint) => {
+                const result = processNightMint(acc.ledgerState, mint, genesisTime, context);
+                return {
+                    ledgerState: result.ledgerState,
+                    transactions: [...acc.transactions, { tx: result.tx, result: result.result }],
+                };
+            }, {
+                ledgerState: postBlockState,
+                transactions: [],
+            });
+            // Apply final post-block update
+            const finalLedger = nightResults.ledgerState.postBlockUpdate(genesisTime);
+            // Combine all transactions
+            const allTransactions = [...init.transactions, ...nightResults.transactions];
+            // Create genesis block with all transactions
+            const genesisBlock = {
+                number: genesis.blockNumber,
+                hash: context.parentBlockHash,
+                timestamp: genesisTime,
+                transactions: allTransactions,
+                protocolVersion: genesis.protocolVersion,
+            };
+            const initialState = {
+                networkId,
+                ledger: finalLedger,
+                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.
+     *
+     * 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);
+            // Create a shared stream of state changes.
+            // Note: SubscriptionRef.changes only emits on updates, not the initial value.
+            // Consumers (sync services) should get the initial state via getLatestState() if needed.
+            const stateChangesStream = yield* Stream.share(stateRef.changes, {
+                capacity: 'unbounded',
+                replay: 1,
+            });
+            // Create instance first so we can use instance method in the stream
+            const simulator = new Simulator(stateRef, stateChangesStream);
+            // Set up block production stream
+            const effectiveProducer = blockProducer ?? immediateBlockProducer();
+            const statesForProducer = Stream.concat(Stream.succeed(initialState), stateRef.changes);
+            const productionRequests = effectiveProducer(statesForProducer);
+            yield* Effect.forkScoped(productionRequests.pipe(Stream.runForEach((request) => simulator.#produceBlock(request))));
+            return simulator;
+        });
+    }
+    // ===========================================================================
+    // Instance Properties
+    // ===========================================================================
+    #stateRef;
+    /** Observable stream of simulator state changes. */
+    state$;
+    constructor(stateRef, state$) {
+        this.#stateRef = stateRef;
+        this.state$ = state$;
+    }
+    // ===========================================================================
+    // Instance Methods
+    // ===========================================================================
+    /** Get the current simulator state. */
+    getLatestState() {
+        return SubscriptionRef.get(this.#stateRef);
+    }
+    /**
+     * 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, amount) {
+        const stateRef = this.#stateRef;
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        const simulator = this;
+        const recipient = addressFromKey(verifyingKey);
+        return Effect.gen(function* () {
+            // First, modify ledger state to make Night tokens claimable
+            yield* SubscriptionRef.updateEffect(stateRef, (simulatorState) => pipe(LedgerOps.ledgerTry(() => simulatorState.ledger.testingDistributeNight(recipient, amount, simulatorState.currentTime)), Effect.map((newLedgerState) => ({
+                ...simulatorState,
+                ledger: newLedgerState,
+            }))));
+            // Create and submit the claim transaction through submitTransaction
+            const currentState = yield* SubscriptionRef.get(stateRef);
+            const signature = new SignatureErased();
+            const claimRewardsTransaction = new ClaimRewardsTransaction(signature.instance, currentState.networkId, amount, verifyingKey, LedgerOps.randomNonce(), signature);
+            const tx = Transaction.fromRewards(claimRewardsTransaction).eraseProofs();
+            // Submit transaction with genesisStrictness - reward claims are not balanced transactions
+            return yield* simulator.submitTransaction(tx, { strictness: genesisStrictness });
+        });
+    }
+    /**
+     * 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, options) {
+        // Only set strictness if explicitly provided; otherwise let block producer assign default
+        const pendingTx = options?.strictness !== undefined ? { tx, strictness: createStrictness(options.strictness) } : { tx };
+        const stateRef = this.#stateRef;
+        return Effect.gen(function* () {
+            // Add to mempool
+            yield* SubscriptionRef.update(stateRef, (s) => addToMempool(s, pendingTx));
+            // Wait for the transaction to be processed (removed from mempool)
+            // by watching state changes
+            const finalState = yield* pipe(stateRef.changes, Stream.filter((s) => !s.mempool.includes(pendingTx)), Stream.take(1), Stream.runHead);
+            if (finalState._tag === 'None') {
+                return yield* Effect.die(new Error('State stream ended unexpectedly'));
+            }
+            // Find the block containing our transaction
+            const block = finalState.value.blocks.find((b) => b.transactions.some((bt) => bt.tx === tx));
+            if (!block) {
+                // Transaction was removed from mempool but not in any block - it failed
+                return yield* Effect.fail({
+                    _tag: 'LedgerError',
+                    message: 'Transaction was discarded',
+                });
+            }
+            return block;
+        });
+    }
+    /**
+     * 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, options) {
+        // Only set strictness if explicitly provided; otherwise let block producer assign default
+        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.
+     *
+     * @param seconds - Number of seconds to advance (must be positive)
+     */
+    fastForward(seconds) {
+        return SubscriptionRef.update(this.#stateRef, (simulatorState) => ({
+            ...simulatorState,
+            currentTime: DateOps.addSeconds(simulatorState.currentTime, seconds),
+        }));
+    }
+    // ===========================================================================
+    // Internal Block Production
+    // ===========================================================================
+    /**
+     * Produce a block from the given block production request. Internal method used by the block producer stream.
+     *
+     * This method orchestrates block production by:
+     *
+     * 1. Computing the block hash (async)
+     * 2. Processing transactions using pure functions from SimulatorState
+     * 3. Creating the block and updating state atomically
+     *
+     * Each transaction in the request has its own strictness assigned by the block producer.
+     *
+     * @param request - Block production request with transactions and fullness
+     */
+    #produceBlock(request) {
+        const stateRef = this.#stateRef;
+        const { transactions, fullness } = request;
+        return Effect.gen(function* () {
+            const blockResult = yield* SubscriptionRef.modifyEffect(stateRef, (simulatorState) => Effect.gen(function* () {
+                // Advance time first, then use it for the block
+                const blockTime = DateOps.addSeconds(simulatorState.currentTime, 1);
+                const previousBlock = getLastBlock(simulatorState);
+                const nextBlockNumber = previousBlock !== undefined ? previousBlock.number + 1n : 0n;
+                const hash = yield* Effect.promise(() => blockHash(nextBlockNumber));
+                if (transactions.length === 0) {
+                    // No transactions to process, return empty block using pure function
+                    const [emptyBlock, newState] = createEmptyBlock(simulatorState, hash, blockTime, transactions);
+                    return [Either.right(emptyBlock), newState];
+                }
+                const context = yield* Effect.promise(() => nextBlockContextFromBlock(previousBlock, blockTime));
+                // Process all transactions - each has its own strictness assigned by block producer
+                const processingResult = processTransactions(simulatorState.ledger, transactions, blockTime, context, fullness);
+                if (Either.isLeft(processingResult)) {
+                    // Transaction failed, remove from mempool and return error
+                    const newState = removeFromMempool(simulatorState, transactions);
+                    return [Either.left(processingResult.left), newState];
+                }
+                const { blockTransactions, finalLedger } = processingResult.right;
+                // Create block using pure function
+                const [block, newState] = createBlock(simulatorState, blockTransactions, hash, blockTime, finalLedger, transactions);
+                return [Either.right(block), newState];
+            }));
+            // Return the result
+            if (Either.isLeft(blockResult)) {
+                return yield* Effect.fail(blockResult.left);
+            }
+            return blockResult.right;
+        });
+    }
+    // ===========================================================================
+    // Query Method
+    // ===========================================================================
+    /**
+     * 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(fn) {
+        return Effect.map(SubscriptionRef.get(this.#stateRef), fn);
+    }
+}

package/dist/simulation/{SimulatorState.d.ts → v8/SimulatorState.d.ts}

@@ -5,9 +5,11 @@
  * synchronous and side-effect free.
  */
 import { Either, type Stream, Array as EArray } from 'effect';
-import { LedgerState, type BlockContext, WellFormedStrictness, type TransactionResult, type ProofErasedTransaction, type SyntheticCost, type RawTokenType, type ZswapSecretKeys, type UserAddress, type SignatureVerifyingKey } from '@midnightntwrk/ledger-v9';
+import { LedgerState, WellFormedStrictness, type TransactionResult, type ProofErasedTransaction, type SyntheticCost, type RawTokenType, type ZswapSecretKeys, type UserAddress, type SignatureVerifyingKey } from '@midnight-ntwrk/ledger-v8';
 import { LedgerOps } from '@midnight-ntwrk/wallet-sdk-utilities';
-import { type NetworkId } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { type NetworkId, ProtocolVersion } from '@midnight-ntwrk/wallet-sdk-abstractions';
+import { type BlockContext, type ScheduledFork, type StrictnessConfig } from '../core/index.js';
+export { blockHash, defaultStrictness, genesisStrictness, getProtocolVersion, nextBlockContextFromBlock, protocolVersionAt, scheduleFork, setProtocolVersion, type BlockContext, type ScheduledFork, type StrictnessConfig, } from '../core/index.js';
 /** A transaction included in a block with its execution result. */
 export type BlockTransaction = Readonly<{
     /** The transaction that was executed */
@@ -25,6 +27,12 @@ export type Block = Readonly<{
     timestamp: Date;
     /** Transactions in this block, ordered by execution */
     transactions: readonly BlockTransaction[];
+    /**
+     * Protocol version this block was produced under. Stamped at production time and never revised afterwards, so the
+     * chain's history records which version each block belongs to — exactly what a syncing wallet reads to decide which
+     * codec applies and when to migrate.
+     */
+    protocolVersion: ProtocolVersion.ProtocolVersion;
 }>;
 /**
  * Pending transaction waiting for block production. Strictness is optional - if not specified, block producer assigns
@@ -54,6 +62,10 @@ export type SimulatorState = Readonly<{
     mempool: readonly PendingTransaction[];
     /** Current simulator time (independent of block numbers) */
     currentTime: Date;
+    /** Protocol version the chain is currently on — stamped onto blocks as they are produced */
+    protocolVersion: ProtocolVersion.ProtocolVersion;
+    /** Version activations scheduled at block heights, applied when those heights are produced */
+    scheduledForks: readonly ScheduledFork[];
 }>;
 /** Result of a successful block production. */
 export type BlockInfo = Readonly<{
@@ -170,29 +182,6 @@ export type UnshieldedGenesisMint = Readonly<{
  *   - Night tokens: auto-detected by tokenType, uses reward/claim mechanism (verifyingKey required)
  */
 export type GenesisMint = ShieldedGenesisMint | UnshieldedGenesisMint;
-/** 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;
 /**
  * Assign strictness to a pending transaction, creating a ready transaction. If the pending transaction already has
  * strictness, use it; otherwise use the provided default.
@@ -244,8 +233,21 @@ export declare const getCurrentTime: (state: SimulatorState) => Date;
 export declare const resolveFullness: (spec: FullnessSpec, state: SimulatorState) => number;
 /** Create a block production request that includes all mempool transactions. */
 export declare const allMempoolTransactions: (state: SimulatorState, fullness: number, defaultStrictness: WellFormedStrictness) => BlockProductionRequest;
-/** Create a blank initial state. */
-export declare const blankState: (networkId: NetworkId.NetworkId) => Promise<SimulatorState>;
+/**
+ * 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 declare const blankState: (networkId: NetworkId.NetworkId, options?: {
+    protocolVersion?: ProtocolVersion.ProtocolVersion;
+    genesisBlockNumber?: bigint;
+    genesisTime?: Date;
+}) => Promise<SimulatorState>;
 /** Add a pending transaction to the mempool. */
 export declare const addToMempool: (state: SimulatorState, pendingTx: PendingTransaction) => SimulatorState;
 /** Remove transactions from the mempool. */
@@ -280,10 +282,10 @@ export type TransactionProcessingResult = Readonly<{
     newLedger: LedgerState;
 }>;
 /**
- * Process a single pending transaction against the current ledger. Returns Either with the processing result or an
+ * Process a single pending transaction against the latest ledger state. Returns Either with the processing result or an
  * error.
  *
- * @param ledger - Current ledger state
+ * @param ledger - The ledger state to process against
  * @param readyTx - Transaction to process
  * @param blockTime - Block timestamp
  * @param blockContext - Block context
@@ -332,18 +334,3 @@ export declare const createEmptyBlock: (state: SimulatorState, blockHashValue: s
  * unavoidable given the external API design.
  */
 export declare const createStrictness: (config?: StrictnessConfig) => WellFormedStrictness;
-/**
- * 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
- * @returns A BlockContext suitable for transaction processing
- */
-export declare const nextBlockContextFromBlock: (previousBlock: Block | undefined, blockTime: Date) => Promise<BlockContext>;