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
-
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)
- contract_selector – contract selector string,
see
-
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)
-
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
-
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.
-
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)
- contract_selector – contract selector string,
see
-
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
-
-
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
-