solitude.client module

class solitude.client.ETHClient(endpoint: str)[source]

Bases: solitude.client.eth_client.AccountContext, solitude.client.eth_client.EventCaptureContext

The ethereum node client object allows to communicate with an ethereum node.

It is mainly used to produce contract objects which allow to interact with a contract instance on the blockchain.

It stores a collection of contracts, their ABI and optionally their bytecode.

__init__(endpoint: str)[source]

Initialize a new ETH client without any contract.

Parameters:endpoint – URL of the ethereum server node
account(address)[source]

Enter a context which uses a specific account to perform all transactions in the context.

Parameters:address – address of the account to use
Returns:an account context

Contexts can be nested. In this case, the account in the last context will be used.

with client.account(client.address(0)):
    client.deploy("ContractName", args=())
add_filter(contracts: List[solitude.client.contract.ContractBase], event_names: List[str], parameters=None) → solitude.client.eth_client.Filter[source]

Subscribe to events occurring on the ETH node

Creates a filter on the ETH node. Returns an object with the filter information, which can be used to retrieve the events or unsubscribe.

Parameters:
  • contracts – list of contract instances which can generate the event. All instances must refer to the same contract, possibly deployed at multiple addresses.
  • event_names – names of events to listen for
  • parameters – additional raw topics (optional)
Returns:

a Filter object

address(account_id: int)[source]

Get the address of an account in the ETH node

Parameters:account_id – index of the account in the ETH node
Returns:address of the account
capture(pattern)[source]

Enter a context which captures events emitted by transactions.

Parameters:pattern – a glob pattern string, or a regex object, to match the event name
Returns:a capture context

The event name is in the format: {unitname}:{contractname}.{eventname}

All emitted events that match are stored within the client and can be accessed with client.get_events(). They are cleared before every capture.

Nested captures will filter events that match any of the patterns in the context.

with client.capture("*:MyToken.Transfer"):
    my_token_instance.transfer(address, 13)

assert client.get_events()[0].args[2] == 13

with client.capture(re.compile(r".*:MyToken\.Transfer")):
    my_token_instance.transfer(address, 1)

assert client.get_events()[0].args[2] == 1
clear_events() → None[source]

Clear events generated within the last capture context

contracts

The collection of all contracts known by this client, as a ContractObjectList object

deploy(contract_selector: str, args=(), wrapper=<class 'solitude.client.contract.ContractBase'>)[source]

Deploy a contract

Parameters:
  • contract_selector – contract selector string, see solitude.common.ContractObjectList.select(). The contract must be present in the compiler’s collection and must contain ABI and bytecode.
  • args – constructor arguments
  • wrapper – wrapper class for contract (see ContractBase)
get_accounts(reload=False) → list[source]

Get the accounts stored in the ETH node

Parameters:reload – whether to refresh the account list by querying the node
Retrurn:list of accounts
get_current_account()[source]

Get the account which is currently in use

Returns:address of the account in use
get_events() → List[solitude.client.eth_client.EventLog][source]

Get events generated within the last capture context

Returns:list of event logs
get_last_blocktime() → int[source]

Get timestamp of last mined block

Returns:last block’s timestamp (in seconds)
import_raw_key(private_key: str, passphrase: str = '')[source]
increase_blocktime_offset(seconds: int) → int[source]

Increase the offset to apply to block.timestamp for newly mined blocks

Parameters:seconds – number of seconds to add to block.timestamp offset (in seconds)
Returns:new block.timestamp offset (in seconds)
iter_filters(filters: List[solitude.client.eth_client.Filter], interval=1.0)[source]

Iterate over events generated by a list of filters

Parameters:interval – polling interval in seconds
Returns:an iterator of EventLog objects
mine_block() → None[source]

Ask the ETH node to mine a new block

miner_start(num_threads: int)[source]
remove_filter(flt: solitude.client.eth_client.Filter) → None[source]

Unsubscribe from previously created filter.

Clean up the filter from the ETH node.

Parameters:flt – a Filter object (created by EthClient.add_filter())
rpc

A raw JSON-RPC client instance to communicate with the ETH node

set_default_gaslimit(gas: Optional[int])[source]

Set the default gas limit for transactions

Parameters:gas – default gas limit, or None. If the gas limit is not set either through the default or explicitly in the transaction, web3 will call eth.estimateGas first to determine this value.
set_default_gasprice(gasprice: Optional[int])[source]

Set the default gas price for transactions

Parameters:gasprice – default gas limit, or None. If the gas price is not set, web3 will call eth.gasPrice first to determine this value.
unlock_account(address: str, passphrase: str = '', unlock_duration: int = 300)[source]
update_contracts(contracts: solitude.common.contract_objectlist.ContractObjectList)[source]

Update the collection of contracts known to this client

Parameters:contracts – a collection of contracts (see ContractObjectList)
use(contract_selector: str, address: str, wrapper=<class 'solitude.client.contract.ContractBase'>)[source]

Use a contract at a specific address

Parameters:
  • contract_selector – contract selector string, see solitude.common.ContractObjectList.select(). The contract must be present in the client’s collection and must contain the ABI at least.
  • args – constructor arguments
  • account – deployer account, default is account 0
  • wrapper – wrapper class for contract (see ContractBase)
web3

A raw web3 library client instance connected to the ETH node

class solitude.client.BatchCaller(client: solitude.client.eth_client.ETHClient)[source]

Bases: object

Utility to batch function call requests to the ETH node

__init__(client: solitude.client.eth_client.ETHClient)[source]

Create a BatchCaller

Parameters:client – an ETH client
add_call(contract: solitude.client.contract.ContractBase, func: str, args=()) → None[source]

Add a function call to the batch call

Parameters:
  • contract – a contract object (from EthClient.deploy() or EthClient.use()).
  • func – function name
  • args – function arguments
execute() → list[source]

Execute the call batch

Returns:a list containing the result from each function call, in the same order in which they were added.
class solitude.client.Filter

Bases: tuple

Filter information

contractname

Contract which contains the event definition

event_names

Names of the events to filter

index

Index of the filter on the ETH node

unitname

Source unit of the contract which contains the event definition

valid

Whether the filter is still valid and it should keep being used

class solitude.client.EventLog

Bases: tuple

Event information

address

Address of the contract instance which produced the event

args

Arguments of the emitted event

contractname

Contract which contains the event definition

data

Raw event data from web3

name

Event name

unitname

Source unit of the contract which contains the event definition

class solitude.client.ContractBase(client: solitude.client.eth_client.ETHClient, unitname: str, contractname: str, contract: web3.contract.Contract)[source]

Bases: object

Wrapper around web3 contract object. Allows to define wrapper methods to call contract functions

__init__(client: solitude.client.eth_client.ETHClient, unitname: str, contractname: str, contract: web3.contract.Contract)[source]
Parameters:
  • client – solitude client object which produced this instance
  • unitname – name of the source unit containing the contract
  • contractname – name of the contract
  • contract – web3 contract instance:
abi

Contract ABI

account

Account which is being used as sender

address

Contract address

call(func: str, *args)[source]

Call a function in the contract

Parameters:
  • func – function name
  • *args – function arguments
functions

Functions from web3 contract object

name

Contract name

transact_sync(func: str, *args, value: int = None, gas: int = None, gasprice: int = None) → solitude.common.structures.TransactionInfo[source]

Send a transaction and wait for its receipt

Parameters:
  • func – function name
  • *args – function arguments
  • value – optional amount of ether to send (in wei)
  • gas – optional gas limit
  • gasprice – optional gas price
Returns:

transaction information

unitname

Name of the source unit containing this contract

web3

Raw web3 contract object