Bankrun

exception BanksClientError

Raised when BanksClient encounters an error.

class BanksClient

A client for the ledger state, from the perspective of an arbitrary validator.

The client is used to send transactions and query account data, among other things. Use bankrun.start() to initialize a BanksClient.

get_account(address, commitment=None)

Return the account at the given address at the slot corresponding to the given commitment level. If the account is not found, None is returned.

Parameters:

  • address (Pubkey) – The account address to look up.

  • commitment (Optional[CommitmentLevel]) – The commitment level to use.

Returns:

The account object, if the account exists

Return type:

Optional[Account]

get_balance(address, commitment=None)

Return the balance in lamports of an account at the given address at the slot corresponding to the given commitment level.

Parameters:

  • address (Pubkey) – The account to look up.

  • commitment (Optional[CommitmentLevel]) – The commitment level to use.

Returns:

The account balance in lamports.

Return type:

int

get_block_height(commitment=None)

Get the current block height.

Parameters:

commitment (Optional[CommitmentLevel]) – The commitment level to use.

Returns:

The current block height.

Return type:

int

get_clock()

Get the cluster clock.

Returns:

the clock object.

Return type:

Clock

get_fee_for_message(message, commitment=None)

Get the fee in lamports for a given message.

Parameters:

  • message (Message) – The message to check.

  • commitment (Optional[CommitmentLevel]) – The commitment level to use.

Returns:

The fee for the given message.

Return type:

Optional[int]

get_latest_blockhash(commitment=None)

Returns latest blockhash and last valid block height for given commitment level.

Parameters:

commitment (Optional[CommitmentLevel]) – The commitment level to use.

Returns:

The blockhash and last valid block height.

Return type:

tuple[Hash, int]

get_rent()

Get the cluster rent.

Returns:

The rent object.

Return type:

Rent

get_slot(commitment=None)

Get the slot that has reached the given commitment level (or the default commitment).

Parameters:

commitment (Optional[CommitmentLevel]) – The commitment level to use.

Returns:

The current slot.

Return type:

int

get_transaction_status(signature)

Return the status of a transaction with a signature matching the transaction’s first signature.

Return None if the transaction is not found, which may be because the blockhash was expired or the fee-paying account had insufficient funds to pay the transaction fee. Note that servers rarely store the full transaction history. This method may return None if the transaction status has been discarded.

Parameters:

signature (Signature) – The transaction signature (the first signature of the transaction).

Returns:

The transaction status, if found.

Return type:

Optional[TransactionStatus]

get_transaction_statuses(signatures)

Same as get_transaction_status, but for multiple transactions.

Parameters:

signatures (Sequence[Signature]) – The transaction signatures.

Returns:

The transaction statuses, if found.

Return type:

List[Optional[TransactionStatus]]

process_transaction(transaction)

Process a transaction and return the transaction metadata, raising any errors.

Parameters:

transaction (Transaction | VersionedTransaction) – The transaction to send.

Returns:

The transaction result and metadata.

Return type:

BanksTransactionResultWithMeta

send_transaction(transaction)

Send a transaction and return immediately.

Parameters:

transaction (Transaction | VersionedTransaction) – The transaction to send.

simulate_transaction(transaction, commitment=None)

Simulate a transaction at the given commitment level.

Parameters:
Returns:

The transaction simulation result.

Return type:

BanksTransactionResultWithMeta

class ProgramTestContext

The result of calling bankrun.start().

Contains a BanksClient, a recent blockhash and a funded payer keypair.

banks_client

The client for this test.

Type:

BanksClient

increment_vote_account_credits(vote_account_address, number_of_credits)

Manually increment vote credits for the current epoch in the specified vote account to simulate validator voting activity.

Parameters:

  • vote_account_address (Pubkey) – The vote account addess in which to increment credits.

  • number_of_credits (int) – How many credits to increment by.

last_blockhash

The last blockhash registered when the client was initialized.

Type:

Hash

payer

A funded keypair for sending transactions.

Type:

Keypair

set_account(address, account)

Create or overwrite an account, subverting normal runtime checks.

This method exists to make it easier to set up artificial situations that would be difficult to replicate by sending individual transactions. Beware that it can be used to create states that would not be reachable by sending transactions!

Parameters:

  • address (Pubkey) – The address to write to.

  • account (Account) – The account object to write.

set_clock(clock)

Overwrite the clock sysvar.

Parameters:

clock (Clock) – The new clock object.

set_rent(rent)

Overwrite the rent sysvar.

Parameters:

rent (Rent) – The new rent object.

warp_to_slot(warp_slot)

Force the working bank ahead to a new slot

Parameters:

warp_slot (int) – The slot to warp to.

class BanksTransactionResultWithMeta

A transaction result.

Contains transaction metadata, and the transaction error, if there is one.

static from_bytes(data)

Deserialize from bytes.

Parameters:

data (bytes) – the serialized object.

Returns: the deserialized object.

static from_json(raw)

Build from a JSON string.

meta

The transaction metadata.

Type:

Optional[BanksTransactionMeta]

result

The transaction error info, if the transaction failed.

Type:

Optional[TransactionErrorType]

to_json()

Convert to a JSON string.

class BanksTransactionMeta

Transaction metadata.

compute_units_consumed

The number of compute units consumed by the transaction.

Type:

int

static from_bytes(data)

Deserialize from bytes.

Parameters:

data (bytes) – the serialized object.

Returns: the deserialized object.

static from_json(raw)

Build from a JSON string.

log_messages

The log messages written during transaction execution.

Type:

List[str]

return_data

The transaction return data, if present.

Type:

Optional[TransactionReturnData]

to_json()

Convert to a JSON string.

start(programs=None, accounts=None, compute_max_units=None, transaction_account_lock_limit=None)

Start a bankrun!

This will spin up a BanksServer and a BanksClient, deploy programs and add accounts as instructed.

Parameters:

  • programs (Optional[Sequence[Tuple[str, Pubkey]]]) – A sequence of (program_name, program_id) tuples indicating which programs to deploy to the test environment. See the main bankrun docs for more explanation on how to add programs.

  • accounts (Optional[Sequence[Tuple[Pubkey, Account]]]) – A sequence of (address, account_object) tuples, indicating what data to write to the given addresses.

  • compute_max_units (Optional[int]) – Override the default compute unit limit for a transaction.

  • transaction_account_lock_limit (Optional[int]) – Override the default transaction account lock limit.

Returns:

a container for stuff you’ll need to send transactions and interact with the test environment.

Return type:

ProgramTestContext

start_anchor(path, extra_programs=None, accounts=None, compute_max_units=None, transaction_account_lock_limit=None)

Start a bankrun in an Anchor workspace, with all the workspace programs deployed.

This will spin up a BanksServer and a BanksClient, deploy programs and add accounts as instructed.

Parameters:

  • path (pathlib.Path) – Path to root of the Anchor project.

  • extra_programs (Optional[Sequence[Tuple[str, Pubkey]]]) – A sequence of (program_name, program_id) tuples indicating extra programs to deploy alongside the Anchor workspace programs. See the main bankrun docs for more explanation on how to add programs.

  • accounts (Optional[Sequence[Tuple[Pubkey, Account]]]) – A sequence of (address, account_object) tuples, indicating what data to write to the given addresses.

  • compute_max_units (Optional[int]) – Override the default compute unit limit for a transaction.

  • transaction_account_lock_limit (Optional[int]) – Override the default transaction account lock limit.

Returns:

a container for stuff you’ll need to send transactions and interact with the test environment.

Return type:

ProgramTestContext