Struct MockChain 

pub struct MockChain { /* private fields */ }

The MockChain simulates a simplified blockchain environment for testing purposes. It allows creating and managing accounts, minting assets, executing transactions, and applying state updates.

This struct is designed to mock transaction workflows, asset transfers, and note creation in a test setting. Once entities are set up, TransactionContextBuilder objects can be obtained in order to execute transactions accordingly.

On a high-level, there are two ways to interact with the mock chain:

• Generating transactions yourself and adding them to the mock chain “mempool” using MockChain::add_pending_executed_transaction or MockChain::add_pending_proven_transaction. Once some transactions have been added, they can be proven into a block using MockChain::prove_next_block, which commits them to the chain state.
• Using any of the other pending APIs to magically add new notes, accounts or nullifiers in the next block. For example, MockChain::add_pending_p2id_note will create a new P2ID note in the next proven block, without actually containing a transaction that creates that note.

Both approaches can be mixed in the same block, within limits. In particular, avoid modification of the same entities using both regular transactions and the magic pending APIs.

The mock chain uses the batch and block provers underneath to process pending transactions, so the generated blocks are realistic and indistinguishable from a real node. The only caveat is that no real ZK proofs are generated or validated as part of transaction, batch or block building. If realistic data is important for your use case, avoid using any pending APIs except for MockChain::add_pending_executed_transaction and MockChain::add_pending_proven_transaction.

Examples

Create mock objects and build a transaction context

let mut builder = MockChain::builder();

let faucet = builder.create_new_faucet(Auth::BasicAuth, "USDT", 100_000)?;
let asset = Asset::from(FungibleAsset::new(faucet.id(), 10)?);

let sender = builder.create_new_wallet(Auth::BasicAuth)?;
let target = builder.create_new_wallet(Auth::BasicAuth)?;

let note = builder.add_p2id_note(faucet.id(), target.id(), &[asset], NoteType::Public)?;

let mock_chain = builder.build()?;

// The target account is a new account so we move it into the build_tx_context, since the
// chain's committed accounts do not yet contain it.
let tx_context = mock_chain.build_tx_context(target, &[note.id()], &[])?.build()?;
let executed_transaction = tx_context.execute_blocking()?;

Executing a simple transaction

let mut builder = MockChain::builder();

// Add a recipient wallet.
let receiver = builder.add_existing_wallet(Auth::BasicAuth)?;

// Add a wallet with assets.
let sender = builder.add_existing_wallet(Auth::IncrNonce)?;
let fungible_asset = FungibleAsset::mock(10).unwrap_fungible();

// Add a pending P2ID note to the chain.
let note = builder.add_p2id_note(
    sender.id(),
    receiver.id(),
    &[Asset::Fungible(fungible_asset)],
    NoteType::Public,
)?;

let mut mock_chain = builder.build()?;

let transaction = mock_chain
    .build_tx_context(receiver.id(), &[note.id()], &[])?
    .build()?
    .execute_blocking()?;

// Add the transaction to the mock chain's "mempool" of pending transactions.
mock_chain.add_pending_executed_transaction(&transaction);

// Prove the next block to include the transaction in the chain state.
mock_chain.prove_next_block()?;

assert_eq!(
    mock_chain
        .committed_account(receiver.id())?
        .vault()
        .get_balance(fungible_asset.faucet_id())?,
    fungible_asset.amount()
);

Implementations

impl MockChain

pub const TIMESTAMP_START_SECS: u32 = 1_700_000_000u32

The timestamp of the genesis block of the chain. Chosen as an easily readable number.

pub const TIMESTAMP_STEP_SECS: u32 = 10u32

The number of seconds by which a block’s timestamp increases over the previous block’s timestamp, unless overwritten when calling Self::prove_next_block_at.

pub fn new() -> Self

Creates a new MockChain with an empty genesis block.

pub fn builder() -> MockChainBuilder

Returns a new, empty MockChainBuilder.

pub fn blockchain(&self) -> &Blockchain

Returns a reference to the current Blockchain.

pub fn latest_partial_blockchain(&self) -> PartialBlockchain

Returns a PartialBlockchain instantiated from the current Blockchain and with authentication paths for all all blocks in the chain.

pub fn latest_selective_partial_blockchain( &self, reference_blocks: impl IntoIterator<Item = BlockNumber>, ) -> Result<(BlockHeader, PartialBlockchain)>

Creates a new PartialBlockchain with all reference blocks in the given iterator except for the latest block header in the chain and returns that latest block header.

The intended use for the latest block header is to become the reference block of a new transaction batch or block.

pub fn selective_partial_blockchain( &self, reference_block: BlockNumber, reference_blocks: impl IntoIterator<Item = BlockNumber>, ) -> Result<(BlockHeader, PartialBlockchain)>

Creates a new PartialBlockchain with all reference blocks in the given iterator except for the reference block header in the chain and returns that reference block header.

The intended use for the reference block header is to become the reference block of a new transaction batch or block.

pub fn account_witnesses( &self, account_ids: impl IntoIterator<Item = AccountId>, ) -> BTreeMap<AccountId, AccountWitness>

Returns a map of AccountWitnesses for the requested account IDs from the current AccountTree in the chain.

pub fn nullifier_witnesses( &self, nullifiers: impl IntoIterator<Item = Nullifier>, ) -> BTreeMap<Nullifier, NullifierWitness>

Returns a map of NullifierWitnesses for the requested nullifiers from the current NullifierTree in the chain.

pub fn unauthenticated_note_proofs( &self, notes: impl IntoIterator<Item = NoteId>, ) -> BTreeMap<NoteId, NoteInclusionProof>

Returns all note inclusion proofs for the requested note IDs, if they are available for consumption. Therefore, not all of the requested notes will be guaranteed to have an entry in the returned map.

pub fn genesis_block_header(&self) -> BlockHeader

Returns the genesis BlockHeader of the chain.

pub fn latest_block_header(&self) -> BlockHeader

Returns the latest BlockHeader in the chain.

pub fn block_header(&self, block_number: usize) -> BlockHeader

Returns the BlockHeader with the specified block_number.

Panics

• If the block number does not exist in the chain.

pub fn proven_blocks(&self) -> &[ProvenBlock]

Returns a reference to slice of all created proven blocks.

pub fn native_asset_id(&self) -> AccountId

Returns the AccountId of the faucet whose assets are accepted for fee payments in the transaction kernel, or in other words, the native asset of the blockchain.

This value is taken from the genesis block because it is assumed not to change throughout the chain’s lifecycle.

pub fn nullifier_tree(&self) -> &NullifierTree

Returns a reference to the nullifier tree.

pub fn committed_notes(&self) -> &BTreeMap<NoteId, MockChainNote>

Returns the map of note IDs to committed notes.

These notes are committed for authenticated consumption.

pub fn get_public_note(&self, note_id: &NoteId) -> Option<InputNote>

Returns an InputNote for the given note ID. If the note does not exist or is not public, None is returned.

pub fn committed_account(&self, account_id: AccountId) -> Result<&Account>

Returns a reference to the account identified by the given account ID.

The account is retrieved with the latest state known to the MockChain.

pub fn account_tree(&self) -> &AccountTree

Returns a reference to the AccountTree of the chain.

pub fn propose_transaction_batch<I>( &self, txs: impl IntoIterator<Item = ProvenTransaction, IntoIter = I>, ) -> Result<ProposedBatch>

where I: Iterator<Item = ProvenTransaction> + Clone,

Proposes a new transaction batch from the provided transactions and returns it.

This method does not modify the chain state.

pub fn prove_transaction_batch( &self, proposed_batch: ProposedBatch, ) -> Result<ProvenBatch>

Mock-proves a proposed transaction batch from the provided ProposedBatch and returns it.

This method does not modify the chain state.

pub fn propose_block_at<I>( &self, batches: impl IntoIterator<Item = ProvenBatch, IntoIter = I>, timestamp: u32, ) -> Result<ProposedBlock>

where I: Iterator<Item = ProvenBatch> + Clone,

Proposes a new block from the provided batches with the given timestamp and returns it.

This method does not modify the chain state.

pub fn propose_block<I>( &self, batches: impl IntoIterator<Item = ProvenBatch, IntoIter = I>, ) -> Result<ProposedBlock>

where I: Iterator<Item = ProvenBatch> + Clone,

Proposes a new block from the provided batches and returns it.

This method does not modify the chain state.

pub fn prove_block( &self, proposed_block: ProposedBlock, ) -> Result<ProvenBlock, ProvenBlockError>

Mock-proves a proposed block into a proven block and returns it.

This method does not modify the chain state.

pub fn build_tx_context_at( &self, reference_block: impl Into<BlockNumber>, input: impl Into<TxContextInput>, note_ids: &[NoteId], unauthenticated_notes: &[Note], ) -> Result<TransactionContextBuilder>

Initializes a TransactionContextBuilder for executing against a specific block number.

Depending on the provided input, the builder is initialized differently:

• TxContextInput::AccountId: Initialize the builder with TransactionInputs fetched from the chain for the public account identified by the ID.
• TxContextInput::Account: Initialize the builder with TransactionInputs where the account is passed as-is to the inputs.
• TxContextInput::ExecutedTransaction: Initialize the builder with TransactionInputs where the account passed to the inputs is the final account of the executed transaction. This is the initial account of the transaction with the account delta applied.

In all cases, if the chain contains a seed or authenticator for the account, they are added to the builder.

TxContextInput::Account and TxContextInput::ExecutedTransaction can be used to build a chain of transactions against the same account that build on top of each other. For example, transaction A modifies an account from state 0 to 1, and transaction B modifies it from state 1 to 2.

pub fn build_tx_context( &self, input: impl Into<TxContextInput>, note_ids: &[NoteId], unauthenticated_notes: &[Note], ) -> Result<TransactionContextBuilder>

Initializes a TransactionContextBuilder for executing against the last block header.

This is a wrapper around Self::build_tx_context_at which uses the latest block as the reference block. See that function’s docs for details.

pub fn get_transaction_inputs_at( &self, reference_block: BlockNumber, account: Account, account_seed: Option<Word>, notes: &[NoteId], unauthenticated_notes: &[Note], ) -> Result<TransactionInputs>

Returns a valid TransactionInputs for the specified entities, executing against a specific block number.

pub fn get_transaction_inputs( &self, account: Account, account_seed: Option<Word>, notes: &[NoteId], unauthenticated_notes: &[Note], ) -> Result<TransactionInputs>

Returns a valid TransactionInputs for the specified entities.

pub fn get_batch_inputs( &self, tx_reference_blocks: impl IntoIterator<Item = BlockNumber>, unauthenticated_notes: impl Iterator<Item = NoteId>, ) -> Result<(BlockHeader, PartialBlockchain, BTreeMap<NoteId, NoteInclusionProof>)>

Returns inputs for a transaction batch for all the reference blocks of the provided transactions.

pub fn get_foreign_account_inputs( &self, account_id: AccountId, ) -> Result<AccountInputs>

Gets foreign account inputs to execute FPI transactions.

pub fn get_block_inputs<'batch, I>( &self, batch_iter: impl IntoIterator<Item = &'batch ProvenBatch, IntoIter = I>, ) -> Result<BlockInputs>

where I: Iterator<Item = &'batch ProvenBatch> + Clone,

Gets the inputs for a block for the provided batches.

pub fn prove_next_block(&mut self) -> Result<ProvenBlock>

Creates the next block in the mock chain.

This will make all the objects currently pending available for use.

pub fn prove_next_block_at(&mut self, timestamp: u32) -> Result<ProvenBlock>

Proves the next block in the mock chain at the given timestamp.

pub fn prove_until_block( &mut self, target_block_num: impl Into<BlockNumber>, ) -> Result<ProvenBlock>

Proves new blocks until the block with the given target block number has been created.

For example, if the latest block is 5 and this function is called with 10, then blocks 6..=10 will be created and block 10 will be returned.

Panics

Panics if:

• the given block number is smaller or equal to the number of the latest block in the chain.

pub fn set_rng_seed(&mut self, seed: [u8; 32])

Sets the seed for the internal RNG.

pub fn add_pending_executed_transaction( &mut self, transaction: &ExecutedTransaction, ) -> Result<Account>

Adds the given ExecutedTransaction to the list of pending transactions.

A block has to be created to apply the transaction effects to the chain state, e.g. using MockChain::prove_next_block.

Returns the resulting state of the executing account after executing the transaction.

pub fn add_pending_proven_transaction(&mut self, transaction: ProvenTransaction)

Adds the given ProvenTransaction to the list of pending transactions.

A block has to be created to apply the transaction effects to the chain state, e.g. using MockChain::prove_next_block.

pub fn add_pending_note(&mut self, note: OutputNote)

Adds the given OutputNote to the list of pending notes.

A block has to be created to add the note to that block and make it available in the chain state, e.g. using MockChain::prove_next_block.

pub fn add_pending_p2id_note( &mut self, sender_account_id: AccountId, target_account_id: AccountId, asset: &[Asset], note_type: NoteType, ) -> Result<Note, NoteError>

Adds a plain P2ID OutputNote to the list of pending notes.

The note is immediately spendable by target_account_id and carries no additional reclaim or timelock conditions.

pub fn add_pending_p2ide_note( &mut self, sender_account_id: AccountId, target_account_id: AccountId, asset: &[Asset], note_type: NoteType, reclaim_height: Option<BlockNumber>, timelock_height: Option<BlockNumber>, ) -> Result<Note, NoteError>

Adds a P2IDE OutputNote (pay‑to‑ID‑extended) to the list of pending notes.

A P2IDE note can include an optional timelock_height and/or an optional reclaim_height after which the sender_account_id may reclaim the funds.

Trait Implementations

impl Clone for MockChain

fn clone(&self) -> MockChain

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for MockChain

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for MockChain

fn default() -> Self

Returns the “default value” for a type.

impl Deserializable for MockChain

fn read_from<R: ByteReader>( source: &mut R, ) -> Result<Self, DeserializationError>

Reads a sequence of bytes from the provided source, attempts to deserialize these bytes into Self, and returns the result.

fn read_from_bytes(bytes: &[u8]) -> Result<Self, DeserializationError>

Attempts to deserialize the provided bytes into Self and returns the result.

impl Serializable for MockChain

fn write_into<W: ByteWriter>(&self, target: &mut W)

Serializes self into bytes and writes these bytes into the target.

fn to_bytes(&self) -> Vec<u8>

Serializes self into a vector of bytes.

fn get_size_hint(&self) -> usize

Returns an estimate of how many bytes are needed to represent self.