Struct MockChain 

pub struct MockChain { /* private fields */ }

Available on crate feature testing only.

The MockChain simulates a simplified blockchain environment for testing purposes.

The typical usage of a mock chain is:

• Creating it using a MockChainBuilder, which allows adding accounts and notes to the genesis state.
• Creating transactions against the chain state and executing them.
• Adding executed or proven transactions to the set of pending transactions (the “mempool”), e.g. using MockChain::add_pending_executed_transaction.
• Proving a block, which adds all pending transactions to the chain state, e.g. using MockChain::prove_next_block.

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.

Examples

Executing a simple transaction

// Build a genesis state for a mock chain using a MockChainBuilder.
// --------------------------------------------------------------------------------------------

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 P2ID note with a fungible asset to the chain.
let note = builder.add_p2id_note(
    sender.id(),
    receiver.id(),
    &[Asset::Fungible(fungible_asset)],
    NoteType::Public,
)?;

let mut mock_chain: MockChain = builder.build()?;

// Create a transaction against the receiver account consuming the note.
// --------------------------------------------------------------------------------------------

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

// Add the transaction to the chain state.
// --------------------------------------------------------------------------------------------

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

// The receiver account should now have the asset in its account vault.
assert_eq!(
    mock_chain
        .committed_account(receiver.id())?
        .vault()
        .get_balance(fungible_asset.faucet_id())?,
    fungible_asset.amount()
);

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().await?;

Implementations

impl MockChain

pub const TIMESTAMP_START_SECS: u32 = 1700000000

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

pub const TIMESTAMP_STEP_SECS: u32 = 10

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() -> MockChain

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

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

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 latest_block(&self) -> ProvenBlock

Returns the latest ProvenBlock 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, Error>

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

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

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

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

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

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.

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

TxContextInput::Account 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, Error>

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: impl Into<PartialAccount>, notes: &[NoteId], unauthenticated_notes: &[Note], ) -> Result<TransactionInputs, Error>

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

pub fn get_transaction_inputs( &self, account: impl Into<PartialAccount>, notes: &[NoteId], unauthenticated_notes: &[Note], ) -> Result<TransactionInputs, Error>

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

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<(Account, AccountWitness), Error>

Gets foreign account inputs to execute FPI transactions.

Used in tests to get foreign account inputs for FPI calls.

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

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

Proves the next block in the mock chain.

This will commit all the currently pending transactions into the chain state.

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

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

This will commit all the currently pending transactions into the chain state.

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

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 add_pending_executed_transaction( &mut self, transaction: &ExecutedTransaction, ) -> Result<(), Error>

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.

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 prove_block( &self, proposed_block: ProposedBlock, ) -> Result<ProvenBlock, Error>

Proves proposed block alongside a corresponding list of batches.

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<(), Error>

Formats the value using the given formatter.

impl Default for MockChain

fn default() -> MockChain

Returns the “default value” for a type.

impl Deserializable for MockChain

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

where R: ByteReader,

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 From<MockChain> for MockRpcApi

fn from(mock_chain: MockChain) -> Self

Converts to this type from the input type.

impl Serializable for MockChain

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

where W: ByteWriter,

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.