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 mock_chain = MockChain::new();
let faucet = mock_chain.add_pending_new_faucet(Auth::BasicAuth, "USDT", 100_000);  // Create a USDT faucet
let asset = faucet.mint(1000);
let sender = mock_chain.add_pending_new_wallet(Auth::BasicAuth);
let target = mock_chain.add_pending_new_wallet(Auth::BasicAuth);
let note = mock_chain
    .add_pending_p2id_note(
        faucet.id(),
        target.id(),
        &[FungibleAsset::mock(10)],
        NoteType::Public,
      None,
    )
  .unwrap();
mock_chain.prove_next_block();
let tx_context = mock_chain.build_tx_context(sender.id(), &[note.id()], &[]).build();
let result = tx_context.execute();

Executing a Simple Transaction

let mut mock_chain = MockChain::new();
// Add a recipient wallet.
let receiver = mock_chain.add_pending_new_wallet(Auth::BasicAuth);
// Add a wallet with assets.
let sender = mock_chain.add_pending_existing_wallet(Auth::NoAuth, vec![]);
let fungible_asset = FungibleAsset::mock(10).unwrap_fungible();

// Add a pending P2ID note to the chain.
let note = mock_chain
    .add_pending_p2id_note(
        sender.id(),
        receiver.id(),
        &[Asset::Fungible(fungible_asset)],
        NoteType::Public,
        None,
    )
    .unwrap();
// Prove the next block to add the pending note to the chain state, making it available for
// consumption.
mock_chain.prove_next_block();

// Create a transaction context that consumes the note and execute it.
let transaction = mock_chain
    .build_tx_context(receiver.id(), &[note.id()], &[])
    .build()
    .execute()
    .unwrap();

// 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();

// Check that the receiver's balance has increased.
assert_eq!(
    mock_chain
        .committed_account(receiver.id())
        .vault()
        .get_balance(fungible_asset.faucet_id())
        .unwrap(),
    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 with_accounts(accounts: &[Account]) -> Self

Creates a new MockChain with a genesis block containing the provided accounts.

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>, ) -> (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 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 latest_block_header(&self) -> BlockHeader

Returns a reference to the latest BlockHeader in the chain.

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

Returns the BlockHeader with the specified block_number.

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

Returns a reference to slice of all created proven blocks.

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) -> &Account

Returns a reference to the account identified by the given account ID and panics if it does not exist.

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, ProposedBatchError>

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, ) -> 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, ProposedBlockError>

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, ProposedBlockError>

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( &self, input: impl Into<TxContextInput>, note_ids: &[NoteId], unauthenticated_notes: &[Note], ) -> TransactionContextBuilder

Initializes a TransactionContextBuilder.

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

• TxContextInput::AccountId: Initialize the builder with TransactionInputs fetched from the chain for the 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. Additionally, if the account is set to authenticate with Auth::BasicAuth, the executed transaction script is defaulted to DEFAULT_AUTH_SCRIPT.

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 get_transaction_inputs( &self, account: Account, account_seed: Option<Word>, notes: &[NoteId], unauthenticated_notes: &[Note], ) -> 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>, ) -> (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) -> 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>, ) -> 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) -> 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, ) -> 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, reclaim_height: Option<BlockNumber>, ) -> Result<Note, NoteError>

Adds a P2ID 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_nullifier(&mut self, nullifier: Nullifier)

Adds the Nullifier to the list of pending nullifiers.

A block has to be created to add the nullifier to the nullifier tree as part of that block, e.g. using MockChain::prove_next_block.

pub fn add_pending_new_wallet(&mut self, auth_method: Auth) -> Account

Adds a new BasicWallet account to the list of pending accounts.

A block has to be created to add the account to the chain state as part of that block, e.g. using MockChain::prove_next_block.

pub fn add_pending_existing_wallet( &mut self, auth_method: Auth, assets: Vec<Asset>, ) -> Account

Adds an existing BasicWallet account with nonce 1 to the list of pending accounts.

A block has to be created to add the account to the chain state as part of that block, e.g. using MockChain::prove_next_block.

pub fn add_pending_new_faucet( &mut self, auth_method: Auth, token_symbol: &str, max_supply: u64, ) -> MockFungibleFaucet

Adds a new BasicFungibleFaucet account with the specified authentication method and the given token metadata to the list of pending accounts.

A block has to be created to add the account to the chain state as part of that block, e.g. using MockChain::prove_next_block.

pub fn add_pending_existing_faucet( &mut self, auth_method: Auth, token_symbol: &str, max_supply: u64, total_issuance: Option<u64>, ) -> MockFungibleFaucet

Adds an existing BasicFungibleFaucet account with the specified authentication method and the given token metadata to the list of pending accounts.

A block has to be created to add the account to the chain state as part of that block, e.g. using MockChain::prove_next_block.

pub fn add_pending_account_from_builder( &mut self, auth_method: Auth, account_builder: AccountBuilder, account_state: AccountState, ) -> Account

Adds the AccountComponent corresponding to auth_method to the account in the builder and builds a new or existing account depending on account_state.

The account is added to the list of committed accounts and, if AccountState::Exists is passed, is also added to the list of pending accounts. Adding it to committed accounts makes the account seed and authenticator available for account creation and authentication, respectively. If the account exists, then the next block that is created will add the pending accounts to the chain state.

pub fn add_pending_account(&mut self, account: Account)

Adds a new Account to the list of pending objects.

A block has to be created to finalize the new entity.

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.