Skip to content

Chains and blocks#

For single chain tests, Woke provides the global default_chain variable. This variable is a Chain object that can be used to change the chain parameters or access the chain data. Other Chain instances can be created, which is useful in Cross-chain testing.

Chain properties#

The Chain object has the following properties:

Property Description
accounts list of pre-generated Account objects
automine whether to automatically mine blocks
blocks property to access the chain blocks
block_gas_limit gas limit for blocks
chain_id chain ID
chain_interface low-level chain interface usefull for debugging and power users
coinbase coinbase Account
connected whether the chain is connected
default_call_account default Account used for calls
default_tx_account default Account used for transactions
gas_price gas price used for all transactions sent to the chain
txs dictionary of transaction objects indexed by transaction hash (a string starting with 0x)
tx_callback callback function to be called when a transaction is mined; applies only to return_tx=False transactions

automine, block_gas_limit, coinbase, default_call_account, default_tx_account, gas_price, and tx_callback can be assigned to.

Chain methods#

The Chain object has the following methods:

Method Description
change_automine context manager to temporarily change the automine property
connect context manager to launch a chain and connect to it or connect to an already running chain
mine mine a block with an optional callback function to set the next block timestamp
reset reset the chain to its initial state
revert revert the chain to a previous state given by a snapshot ID
snapshot take a snapshot of the chain state; return a snapshot ID
snapshot_and_revert context manager to take a snapshot and revert to it after the context ends
update_accounts update the accounts list

It is recommended to use the context managers change_automine and snapshot_and_revert instead of setting the automine property directly or calling snapshot and revert manually.

The following example presents the use of Chain methods:

from woke.testing import default_chain

def test_chain():
    # launch a chain and connect to it
    with default_chain.connect(), default_chain.snapshot_and_revert():
        # mine a block with the timestamp 1 greater than the previous block
        default_chain.mine(lambda x: x + 1)

All Chain context managers can be used as decorators:

from woke.testing import default_chain

def test_chain():
    # mine a block with the timestamp 1 greater than the previous block
    default_chain.mine(lambda x: x + 1)

Accessing chain blocks#

The chain.blocks property can be used to access up-to-date chain blocks data. It can be indexed by an integer or string literals latest, pending, earliest, safe, and finalized:

from woke.testing import default_chain
from pytypes.contracts.Counter import Counter

def test_chain_blocks():
    default_chain.default_tx_account = default_chain.accounts[0]

    # get the block 0
    block0 = default_chain.blocks[0]
    # block 0 and earliest are the same
    assert block0 == default_chain.blocks["earliest"]

    counter = Counter.deploy()

    # find the first block with non-zero transactions count
    block = next(block for block in default_chain.blocks if len(block.txs) > 0)

    assert block.txs[0].return_value == counter

    with default_chain.change_automine(False):
        # block -1 and latest are the same
        assert default_chain.blocks[-1] == default_chain.blocks["latest"]

        tx = counter.increment(return_tx=True)

        # pending block contains the transaction
        assert tx in default_chain.blocks["pending"].txs

Block properties#

The following table lists the most important block properties:

Property Description
chain chain the block belongs to
hash block hash
number block number
parent_hash parent block hash
miner miner Account of the block
gas_used amount of gas used in the block
gas_limit block gas limit
timestamp block timestamp
txs list of transaction objects in the block sorted by transaction index