conflux_web3.cfx apis¶

class conflux_web3.client.BaseCfx(w3: Union[AsyncWeb3, Web3])[source]¶

contract(address: Union[cfx_address.address.Base32Address, str], *, name: Optional[str] = 'None', with_deployment_info: Optional[bool] = 'None', **kwargs: Any) → conflux_web3.contract.ConfluxContract[source]¶

contract(address: None = None, *, name: None = 'None', with_deployment_info: Optional[bool] = 'None', **kwargs: Any) → Type[conflux_web3.contract.ConfluxContract]

contract(address: None = None, *, name: str = None, with_deployment_info: None = 'None', **kwargs: Any) → Union[Type[conflux_web3.contract.ConfluxContract], conflux_web3.contract.ConfluxContract]

contract(address: None = None, *, name: str = None, with_deployment_info: typing_extensions.Literal[False] = None, **kwargs: Any) → Type[conflux_web3.contract.ConfluxContract]

contract(address: None = None, *, name: str = None, with_deployment_info: typing_extensions.Literal[True] = None, **kwargs: Any) → conflux_web3.contract.ConfluxContract

Produce a contract factory (address is not specified) or a contract(address is not specified). Address is specified by:

explicitly using address param

embedded contract deployment info if

“name” parameter specified and corresponding contract has deployment info

with_deployment_info is not False

>>> from conflux_web3.dev import get_mainnet_web3
>>> w3 = get_mainnet_web3()
>>> from conflux_web3.contract import get_contract_metadata
>>> abi = get_contract_metadata("ERC20")["abi"]
>>> bytecode = get_contract_metadata("ERC20")["bytecode"]
>>> erc20_factory = w3.cfx.contract(abi=abi, bytecode=bytecode)

>>> c1 = w3.cfx.contract(name="AdminControl")
>>> assert c1.address # address is added by default
>>> c2 = w3.cfx.contract(name="AdminControl", with_deployment_info=False)
>>> assert not c2.address # address is not added by explicitly specified

Parameters

address (Optional[Union[Base32Address, str]], optional) – the address of the contract, by default None
name (Optional[str], optional) – the name of the contract, which is used to specify abi, bytecode, or deployed contract address, by default None
with_deployment_info (Optional[bool], optional) – whether address will be specified if name parameter is provided, if True, the address will always be specified if name argument is provided if False, the address will never be specified if name argument is provided if None, the address will be specified depending on if corresponding address exists by default None
**kwargs (Dict[str, Any]) – used to specify abi and bytecode argument

Returns

returns a contract factory or contract

Return type

Union[Type[ConfluxContract], ConfluxContract]

property default_account¶: default account address, this address will be used as default from address if transaction from field is empty

class conflux_web3.client.ConfluxClient(w3: Web3)[source]¶

RPC entry defined provides friendlier APIs for users

property accounts¶

Returns the accounts controlled by the provider ## this method is not supported by public rpcs

Returns: a Tuple containing the address of the accounts
Return type: Tuple[Base32Address]

property address¶

property block_number¶

Unsupported API, use web3.cfx.epoch_number instead

Type: # WARNING

call(transaction: Union[cfx_utils.types.TxDict, Dict[str, Any]], block_identifier: Optional[Union[typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending], EpochNumber, int]] = None, **kwargs: Dict[str, Any]) → Any[source]¶

Virtually calls a contract, returns the output data. The transaction will not be added to the blockchain.

Parameters

transaction (TxParam) –
block_identifier (Optional[EpochNumberParam], optional) – integer epoch number, or the string “latest_state”, “latest_confirmed”, “latest_checkpoint” or “earliest”, by default None

Returns

Return type

Any

property chain_id¶

Get the chain id of the current network. This property is cached and won’t be changed unless it is deleted

Returns: chain id of the blockchain, 1 for conflux testnet and 1029 for conflux mainnet
Return type: int

check_balance_against_transaction(account_address: Union[cfx_address.address.Base32Address, str], contract_address: Union[cfx_address.address.Base32Address, str], gas_limit: int, gas_price: Union[cfx_utils.token_unit.Drip, cfx_utils.token_unit.AbstractDerivedTokenUnit[cfx_utils.token_unit.Drip], int], storage_limit: Union[Storage, int], block_identifier: Optional[Union[typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending], EpochNumber, int]] = None) → conflux_web3.types.TransactionPaymentInfo [source]¶

property client_version¶

property coinbase¶

Unsupported API

Type: # WARNING

property epoch_number¶

Returns latest_mined epoch number

Returns: latest mined epoch number
Return type: EpochNumber

epoch_number_by_tag(epoch_tag: typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending]) → EpochNumber[source]¶

Returns the epoch numebr with the provided epoch tag

Parameters: epoch_tag (EpochLiteral) – String “latest_mined”, “latest_state”, “latest_confirmed”, “latest_checkpoint” or “earliest”
Returns: the epoch number corrensponding to the epoch tag
Return type: EpochNumber

estimate_gas(transaction: Union[cfx_utils.types.TxDict, Dict[str, Any]], block_identifier: Optional[Union[typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending], EpochNumber, int]] = None) → conflux_web3.types.EstimateResult [source]¶: Compatibility API for conflux. Equivalent to estimate_gas_and_collateral

estimate_gas_and_collateral(transaction: Union[cfx_utils.types.TxDict, Dict[str, Any]], block_identifier: Optional[Union[typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending], EpochNumber, int]] = None) → conflux_web3.types.EstimateResult [source]¶

Virtually executes a transaction, returns an estimate for the size of storage collateralized and the gas used by the transaction. The transaction will not be added to the blockchain. For most cases, you don’t need to invoke this api to fill the transaction fields unless you need to manually sign the transactions.

>>> w3.cfx.estimate_gas_and_collateral({"to": "cfx:type.contract:acc7uawf5ubtnmezvhu9dhc6sghea0403y2dgpyfjp"})
>>> {"gasLimit": 21000, "gasUsed": 21000, "storageCollateralized": 0}

Parameters

transaction (TxParam) –
block_identifier (Optional[EpochNumberParam], optional) – integer epoch number, or the string “latest_state”, “latest_confirmed”, “latest_checkpoint” or “earliest”, by default None

Returns

Return type

EstimateResult

property gas_price¶

Get the current gas price

>>> w3.cfx.gas_price
1000000000 Drip
>>> w3.cfx.gas_price.value
1000000000
>>> w3.cfx.gas_price.to("GDrip")
1 GDrip

Returns: gas price wrapped by Drip, which can be used as transaction value or gas price
Return type: Drip

get_account(address: Union[cfx_address.address.Base32Address, str], block_identifier: Optional[Union[typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending], EpochNumber, int]] = None) → conflux_web3.types.AccountInfo [source]¶

get_account_pending_info(address: Union[cfx_address.address.Base32Address, str]) → conflux_web3.types.PendingInfo [source]¶

get_account_pending_transactions(address: Union[cfx_address.address.Base32Address, str], start_nonce: Optional[int] = None, limit: Optional[int] = None) → conflux_web3.types.PendingTransactionsInfo [source]¶

get_accumulate_interest_rate(block_identifier: Optional[Union[typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending], EpochNumber, int]] = None) → int[source]¶

get_admin(address: Union[cfx_address.address.Base32Address, str], block_identifier: Optional[Union[typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending], EpochNumber, int]] = None) → Union[None, cfx_address.address.Base32Address][source]¶

get_balance(address: Union[cfx_address.address.Base32Address, str], block_identifier: Optional[Union[typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending], EpochNumber, int]] = None) → cfx_utils.token_unit.Drip [source]¶

Returns the balance of the given account, identified by its address.

>>> balance = w3.cfx.get_balance("cfx:type.user:aarc9abycue0hhzgyrr53m6cxedgccrmmyybjgh4xg")
>>> balance
"1000000000000000000 Drip"
>>> balance.value
1000000000000000000
>>> balance.to("CFX")
"1 CFX"

Parameters

address (Union[Base32Address, str]) – the address of the account
block_identifier (Optional[EpochNumberParam], optional) – integer epoch number, or the string “latest_state”, “latest_confirmed”, “latest_checkpoint” or “earliest”, by default None

Returns

balance wrapped by Drip

Return type

Drip

get_best_block_hash() → hexbytes.main.HexBytes[source]¶

Returns the best block hash, which is the block hash of the latest pivot block

Returns: best block hash in bytes
Return type: HexBytes

get_block(block_identifier: Union[Hash32, bytes, HexStr, str, typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending], EpochNumber, int], full_transactions: bool = False) → conflux_web3.types.BlockData [source]¶

a simple wrapper combining get_block_by_hash and get_block_by_epoch_number # note: DON’T USE BLOCK NUMBER as the parameter. A number will be considered as epoch number

>>> block_data = w3.cfx.get_block(97112003)
>>> block_data_ = w3.cfx.get_block("0x1aa5c0d8d6778bd72ac842a52fd26042458b4f70a4d969dfa0d80f81f5eac790")
>>> assert block_data == block_data_

Parameters

block_identifier (Union[_Hash32, EpochNumberParam]) – block hash or epoch number parameter(e.g. string “latest_state” or epoch number)
full_transactions (bool, optional) – whether the return block data contains full transaction info or just transaction hash, by default False

Returns

Return type

BlockData

get_block_by_block_number(block_number: int, full_transactions: bool = False) → conflux_web3.types.BlockData [source]¶

Returns information about a block, identified by its block number.

>>> w3.cfx.get_block_by_block_number(124302546)
AttributeDict({'hash': HexBytes('0x4752f93f61b43e3b09bcbcd36871d4894ac64254df367fa9d7a6253cfb618ece'),
    'parentHash': HexBytes('0x06a695ab273255341f24f955ce696d45007df4df66f0c61b1818965926c2e808'),
    'height': 97111729,
    'miner': 'cfxtest:aanpu16mtgc7dke5xhuktyfyef8f00pz8a2z5mc14g',
    'deferredStateRoot': HexBytes('0xeaf792fff684ce3f04c84614442ab38e8bb4622bacba1c01e857449ef97425f2'),
    'deferredReceiptsRoot': HexBytes('0x09f8709ea9f344a810811a373b30861568f5686e649d6177fd92ea2db7477508'),
    'deferredLogsBloomHash': HexBytes('0xd397b3b043d87fcd6fad1291ff0bfd16401c274896d8c63a923727f077b8e0b5'),
    'blame': 0,
    'transactionsRoot': HexBytes('0x6058a7cf739d94882638cada6e15a4f3b53b757c7195c5cafd04c2061f6de00d'),
    'epochNumber': 97111729,
    'blockNumber': 124302546,
    'gasLimit': 30000000,
    'gasUsed': 75291,
    'timestamp': 1666755747,
    'difficulty': 57822922,
    'powQuality': HexBytes('0x04ebbe82'),
    'refereeHashes': [],
    'adaptive': False,
    'nonce': HexBytes('0x14b30ccfa7cf95b2'),
    'size': 311,
    'custom': [HexBytes('0x02')],
    'posReference': HexBytes('0x2bac96d8e4205badeab4138d1f7b671a436a68ab50c54e7b154243cbf0c9205b'),
    'transactions': [HexBytes('0x70d17ef32c0544075078cb1ca777dab3728d443f00826cf3d05b9c01b76b5f5c')]})

Parameters

epoch_number_param (EpochNumberParam) – the epoch number, or the string “latest_mined”, “latest_state”, “latest_confirmed”, “latest_checkpoint” or “earliest”
full_transactions (bool, optional) – if true, it returns the full transaction objects. If false, only the hashes of the transactions are returned, by default False

Returns

the block data as a dict

Return type

BlockData

get_block_by_epoch_number(epoch_number_param: Union[typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending], EpochNumber, int], full_transactions: bool = False) → conflux_web3.types.BlockData [source]¶

Returns information about a pivot block, identified by its epoch number.

>>> w3.cfx.get_block_by_epoch_number(97111729)
AttributeDict({'hash': HexBytes('0x4752f93f61b43e3b09bcbcd36871d4894ac64254df367fa9d7a6253cfb618ece'),
    'parentHash': HexBytes('0x06a695ab273255341f24f955ce696d45007df4df66f0c61b1818965926c2e808'),
    'height': 97111729,
    'miner': 'cfxtest:aanpu16mtgc7dke5xhuktyfyef8f00pz8a2z5mc14g',
    'deferredStateRoot': HexBytes('0xeaf792fff684ce3f04c84614442ab38e8bb4622bacba1c01e857449ef97425f2'),
    'deferredReceiptsRoot': HexBytes('0x09f8709ea9f344a810811a373b30861568f5686e649d6177fd92ea2db7477508'),
    'deferredLogsBloomHash': HexBytes('0xd397b3b043d87fcd6fad1291ff0bfd16401c274896d8c63a923727f077b8e0b5'),
    'blame': 0,
    'transactionsRoot': HexBytes('0x6058a7cf739d94882638cada6e15a4f3b53b757c7195c5cafd04c2061f6de00d'),
    'epochNumber': 97111729,
    'blockNumber': 124302546,
    'gasLimit': 30000000,
    'gasUsed': 75291,
    'timestamp': 1666755747,
    'difficulty': 57822922,
    'powQuality': HexBytes('0x04ebbe82'),
    'refereeHashes': [],
    'adaptive': False,
    'nonce': HexBytes('0x14b30ccfa7cf95b2'),
    'size': 311,
    'custom': [HexBytes('0x02')],
    'posReference': HexBytes('0x2bac96d8e4205badeab4138d1f7b671a436a68ab50c54e7b154243cbf0c9205b'),
    'transactions': [HexBytes('0x70d17ef32c0544075078cb1ca777dab3728d443f00826cf3d05b9c01b76b5f5c')]})

Parameters

epoch_number_param (EpochNumberParam) – the epoch number, or the string “latest_mined”, “latest_state”, “latest_confirmed”, “latest_checkpoint” or “earliest”
full_transactions (bool, optional) – if true, it returns the full transaction objects. If false, only the hashes of the transactions are returned, by default False

Returns

the block data as a dict

Return type

BlockData

get_block_by_hash(block_hash: Union[Hash32, bytes, HexStr, str], full_transactions: bool = False) → Optional[conflux_web3.types.BlockData][source]¶

Returns information about a block, identified by its hash.

>>> w3.cfx.get_block_by_hash("0x4752f93f61b43e3b09bcbcd36871d4894ac64254df367fa9d7a6253cfb618ece")
AttributeDict({'hash': HexBytes('0x4752f93f61b43e3b09bcbcd36871d4894ac64254df367fa9d7a6253cfb618ece'),
    'parentHash': HexBytes('0x06a695ab273255341f24f955ce696d45007df4df66f0c61b1818965926c2e808'),
    'height': 97111729,
    'miner': 'cfxtest:aanpu16mtgc7dke5xhuktyfyef8f00pz8a2z5mc14g',
    'deferredStateRoot': HexBytes('0xeaf792fff684ce3f04c84614442ab38e8bb4622bacba1c01e857449ef97425f2'),
    'deferredReceiptsRoot': HexBytes('0x09f8709ea9f344a810811a373b30861568f5686e649d6177fd92ea2db7477508'),
    'deferredLogsBloomHash': HexBytes('0xd397b3b043d87fcd6fad1291ff0bfd16401c274896d8c63a923727f077b8e0b5'),
    'blame': 0,
    'transactionsRoot': HexBytes('0x6058a7cf739d94882638cada6e15a4f3b53b757c7195c5cafd04c2061f6de00d'),
    'epochNumber': 97111729,
    'blockNumber': 124302546,
    'gasLimit': 30000000,
    'gasUsed': 75291,
    'timestamp': 1666755747,
    'difficulty': 57822922,
    'powQuality': HexBytes('0x04ebbe82'),
    'refereeHashes': [],
    'adaptive': False,
    'nonce': HexBytes('0x14b30ccfa7cf95b2'),
    'size': 311,
    'custom': [HexBytes('0x02')],
    'posReference': HexBytes('0x2bac96d8e4205badeab4138d1f7b671a436a68ab50c54e7b154243cbf0c9205b'),
    'transactions': [HexBytes('0x70d17ef32c0544075078cb1ca777dab3728d443f00826cf3d05b9c01b76b5f5c')]})

Parameters

block_hash (_Hash32) – hash of a block
full_transactions (bool, optional) – if true, it returns the full transaction objects. If false, only the hashes of the transactions are returned, by default False

Returns

the block data as a dict, or None if no block was found

Return type

Union[BlockData, None]

get_block_by_hash_with_pivot_assumptions(block_hash: Union[Hash32, bytes, HexStr, str], assumed_pivot_hash: Union[Hash32, bytes, HexStr, str], epoch_number: int) → conflux_web3.types.BlockData [source]¶

Returns the requested block if the provided pivot hash is correct, returns an error otherwise.

Parameters

block_hash (_Hash32) – block hash
assumed_pivot_hash (_Hash32) – assumed pivot hash
epoch_number (int) – integer epoch number

Returns

returns block data if pivot hash is correct

Return type

BlockData

get_block_reward_info(block_identifier: Union[EpochNumber, int, typing_extensions.Literal[latest_checkpoint]]) → Sequence[conflux_web3.types.BlockRewardInfo][source]¶

get_blocks_by_epoch(epoch_number_param: Union[typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending], EpochNumber, int]) → Sequence[hexbytes.main.HexBytes][source]¶

Returns the block hashes in the specified epoch.

Parameters: epoch_number_param (EpochNumberParam) – the epoch number, or the string “latest_mined”, “latest_state”, “latest_confirmed”, “latest_checkpoint” or “earliest”
Returns: a list of block hash in bytes
Return type: Sequence[HexBytes]

get_code(address: Union[cfx_address.address.Base32Address, str], block_identifier: Optional[Union[typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending], EpochNumber, int]] = None) → hexbytes.main.HexBytes[source]¶

Returns the code of the specified contract. If contract does not exist will return 0x0

Parameters

address (Union[Base32Address, str]) – address of the contract
block_identifier (Optional[EpochNumberParam], optional) – integer epoch number, or the string “latest_state”, “latest_confirmed”, “latest_checkpoint” or “earliest”, by default None

Returns

byte code of the contract, or 0x if the account has no code

Return type

HexBytes

get_collateral_for_storage(address: Union[cfx_address.address.Base32Address, str], block_identifier: Optional[Union[typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending], EpochNumber, int]] = None) → Storage[source]¶

get_collateral_info(block_identifier: Optional[Union[typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending], EpochNumber, int]] = None) → conflux_web3.types.CollateralInfo [source]¶

get_confirmation_risk_by_hash(block_hash: Union[Hash32, bytes, HexStr, str]) → float[source]¶

Returns the confirmation risk of a given block, identified by its hash

Parameters: block_hash (_Hash32) – block hash
Returns: the confirmation risk in float
Return type: float

get_deposit_list(address: Union[cfx_address.address.Base32Address, str], block_identifier: Optional[Union[typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending], EpochNumber, int]] = None) → Sequence[conflux_web3.types.DepositInfo][source]¶

get_epoch_receipts(epoch_number: Union[typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending], EpochNumber, int], include_espace_receipts: typing_extensions.Literal[True]) → Sequence[Sequence[conflux_web3.types.TxReceiptWithSpace]][source]¶

get_epoch_receipts(epoch_number: Union[typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending], EpochNumber, int], include_espace_receipts: Optional[typing_extensions.Literal[False]]) → Sequence[Sequence[conflux_web3.types.TxReceipt]]

Returns the transaction receipts in every block of the specific epoch. Returns

Parameters

epoch_number (EpochNumberParam) – the epoch to query, should be earlier than latest_state
include_espace_receipts (Optional[bool]) – Defaults to False. Determines if the returned receipts will include eSpace receipts.

Returns

returns a 2-dimension array containing block receipts, where transaction receipts are contained

Return type

Sequence[Sequence[TxReceipt]]

get_filter_changes(filter_id: LogFilterId) → Sequence[conflux_web3.types.LogReceipt][source]¶

get_filter_changes(filter_id: Union[TxFilterId, BlockFilterId]) → Sequence[Hash32]

get_filter_changes(filter_id: str) → Union[Sequence[Hash32], Sequence[conflux_web3.types.LogReceipt]]

Method object for web3 module methods

Calls to the Method go through these steps:

1. input munging - includes normalization, parameter checking, early parameter formatting. Any processing on the input parameters that need to happen before json_rpc method string selection occurs.

A note about mungers: The first (root) munger should reflect the desired

api function arguments. In other words, if the api function wants to behave as: get_balance(account, block_identifier=None), the root munger should accept these same arguments, with the addition of the module as the first argument e.g.:

``` def get_balance_root_munger(module, account, block_identifier=None):

if block_identifier is None:
block_identifier = DEFAULT_BLOCK

return module, [account, block_identifier]

```

all mungers should return an argument list.

if no munger is provided, a default munger expecting no method arguments will be used.

2. method selection - The json_rpc_method argument can be method string or a function that returns a method string. If a callable is provided the processed method inputs are passed to the method selection function, and the returned method string is used.

3. request and response formatters are set - formatters are retrieved using the json rpc method string.

4. After the parameter processing from steps 1-3 the request is made using the calling function returned by the module attribute retrieve_caller_fn and the response formatters are applied to the output.

get_filter_logs(log_filter_id: Union[LogFilterId, str]) → Sequence[conflux_web3.types.LogReceipt][source]¶

Method object for web3 module methods

Calls to the Method go through these steps:

1. input munging - includes normalization, parameter checking, early parameter formatting. Any processing on the input parameters that need to happen before json_rpc method string selection occurs.

A note about mungers: The first (root) munger should reflect the desired

api function arguments. In other words, if the api function wants to behave as: get_balance(account, block_identifier=None), the root munger should accept these same arguments, with the addition of the module as the first argument e.g.:

``` def get_balance_root_munger(module, account, block_identifier=None):

if block_identifier is None:
block_identifier = DEFAULT_BLOCK

return module, [account, block_identifier]

```

all mungers should return an argument list.

if no munger is provided, a default munger expecting no method arguments will be used.

2. method selection - The json_rpc_method argument can be method string or a function that returns a method string. If a callable is provided the processed method inputs are passed to the method selection function, and the returned method string is used.

3. request and response formatters are set - formatters are retrieved using the json rpc method string.

4. After the parameter processing from steps 1-3 the request is made using the calling function returned by the module attribute retrieve_caller_fn and the response formatters are applied to the output.

get_interest_rate(block_identifier: Optional[Union[typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending], EpochNumber, int]] = None) → int[source]¶

get_logs(filter_params: conflux_web3.types.FilterParams) → List[conflux_web3.types.LogReceipt][source]¶

get_logs(filter_params: None = None, **kwargs: Any) → List[conflux_web3.types.LogReceipt]

Returns logs matching the filter provided. It is accepted to pass filter_params as a dict or by direclty specifying field name (but cannot mix)

>>> logs = w3.cfx.get_logs({"fromEpoch": 97134060, "toEpoch: 97134160"})
>>> assert logs == w3.cfx.get_logs(fromEpoch=97134060, toEpoch=97134160})

Parameters: filter_params (Optional[FilterParams], optional) – visit https://developer.confluxnetwork.org/conflux-doc/docs/json_rpc/#cfx_getlogs for more information
Returns: a list of LogReceipt. It is recommended to read https://github.com/Conflux-Chain/python-conflux-sdk/blob/v1/examples/04-interact_with_contracts_and_logs.py to know how to process the returned logs
Return type: List[LogReceipt]

get_next_nonce(address: Union[cfx_address.address.Base32Address, str], block_identifier: Optional[Union[typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending], EpochNumber, int]] = None) → int[source]¶

Returns the next nonce that should be used by the given account when sending a transaction.

Parameters

address (Union[Base32Address, str]) – the address of the account
block_identifier (Optional[EpochNumberParam], optional) – integer epoch number, or the string “latest_state”, “latest_confirmed”, “latest_checkpoint” or “earliest”, by default None

Returns

Return type

int

get_params_from_vote(block_identifier: Optional[Union[typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending], EpochNumber, int]] = None) → conflux_web3.types.DAOVoteInfo [source]¶

get_pos_economics(block_identifier: Optional[Union[typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending], EpochNumber, int]] = None) → conflux_web3.types.PoSEconomicsInfo [source]¶

get_pos_reward_by_epoch(epoch_number: Union[EpochNumber, int]) → Optional[conflux_web3.types.PoSEpochRewardInfo][source]¶

get_skipped_blocks_by_epoch(epoch_number_param: Union[typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending], EpochNumber, int]) → Sequence[hexbytes.main.HexBytes][source]¶

Returns the list of non-executed blocks in an epoch. By default, Conflux only executes the last 200 blocks in each epoch (note that under normal circumstances, epochs should be much smaller).

Parameters: epoch_number_param (EpochNumberParam) – the epoch number, or the string “latest_mined”, “latest_state”, “latest_confirmed”, “latest_checkpoint” or “earliest”
Returns: a list of block hash in bytes
Return type: Sequence[HexBytes]

get_sponsor_info(address: Union[cfx_address.address.Base32Address, str], block_identifier: Optional[Union[typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending], EpochNumber, int]] = None) → conflux_web3.types.SponsorInfo [source]¶

get_staking_balance(address: Union[cfx_address.address.Base32Address, str], block_identifier: Optional[Union[typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending], EpochNumber, int]] = None) → cfx_utils.token_unit.Drip [source]¶

Returns the staking balance of the given account, identified by its address.

Parameters

address (Union[Base32Address, str]) – the address of the account
block_identifier (Optional[EpochNumberParam], optional) – integer epoch number, or the string “latest_state”, “latest_confirmed”, “latest_checkpoint” or “earliest”, by default None

Returns

balance wrapped by Drip

Return type

Drip

get_status() → conflux_web3.types.NodeStatus [source]¶

get the blockchain status from the provider

>>> w3.cfx.get_status()
AttributeDict({'bestHash': HexBytes('0xb91109cc301209921b33533f8ae228615016b9104e8229ddaad55b370fe586d3'),
    'chainId': 1,
    'ethereumSpaceChainId': 71,
    'networkId': 1,
    'epochNumber': 97105091,
    'blockNumber': 124293823,
    'pendingTxNumber': 69,
    'latestCheckpoint': 97000000,
    'latestConfirmed': 97105034,
    'latestState': 97105087,
    'latestFinalized': 97104660})
>>> w3.cfx.get_status().chainId # support but not recommended because of missing type hints
1
>>> w3.cfx.get_status()['chainId'] # recommended
1

Returns: a dict representing node status
Return type: NodeStatus

get_storage_at(address: Union[cfx_address.address.Base32Address, str], storage_position: int, block_identifier: Optional[Union[typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending], EpochNumber, int]] = None) → Optional[hexbytes.main.HexBytes][source]¶

Returns storage entries from a given contract.

Parameters

address (Union[Base32Address, str]) – address of the contract
storage_position (int) – a storage position (refer to https://solidity.readthedocs.io/en/v0.7.1/internals/layout_in_storage.html for more info)
block_identifier (Optional[EpochNumberParam], optional) – integer epoch number, or the string “latest_state”, “latest_confirmed”, “latest_checkpoint” or “earliest”, by default None

Returns

32 Bytes - the contents of the storage position, or None if the contract does not exist

Return type

Union[HexBytes, None]

get_storage_root(address: Union[cfx_address.address.Base32Address, str], block_identifier: Optional[Union[typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending], EpochNumber, int]] = None) → Optional[conflux_web3.types.StorageRoot][source]¶

get_supply_info() → conflux_web3.types.SupplyInfo [source]¶

get_transaction(transaction_hash: Union[Hash32, bytes, HexStr, str]) → conflux_web3.types.TxData[source]¶: Alias for get_transaction_by_hash

get_transaction_by_hash(transaction_hash: Union[Hash32, bytes, HexStr, str]) → conflux_web3.types.TxData[source]¶

Returns information about a transaction, identified by its hash. ## Note: the transaction is not mined if blockHash field is None

>>> w3.cfx.get_transaction_by_hash('0x5ffa11a44c6db42cc30967d4de5949b17ee319c4aba72f3380c60136993a8980')
AttributeDict({'hash': HexBytes('0x5ffa11a44c6db42cc30967d4de5949b17ee319c4aba72f3380c60136993a8980'),
    'nonce': 8230,
    'blockHash': HexBytes('0xceda961d541c78fa2c99907620bb2b13707f72b004b7c70362a5642177e6aae2'),
    'transactionIndex': 227,
    'from': 'cfxtest:aaksxj04phv0hp02jh3cbym9vghwkzap867jagb043',
    'to': 'cfxtest:aaksxj04phv0hp02jh3cbym9vghwkzap867jagb043',
    'value': 0 Drip,
    'gasPrice': 1000000000 Drip,
    'gas': 21000,
    'contractCreated': None,
    'data': HexBytes('0x'),
    'storageLimit': 0,
    'epochHeight': 97108719,
    'chainId': 1,
    'status': 0,
    'v': 1,
    'r': HexBytes('0x1d16cb28acf3973df4f4cc29ffffdba5d36ca1e38f1904f64780fa505691c1b7'),
    's': HexBytes('0x1549267bc4f60af38d23112b47a54dc36481e77eb44dd5ee2c3277810c1c6297')})

Parameters: transaction_hash (_Hash32) – the hash of the transaction, could be byte or hex string
Returns: transaction data as a dict
Return type: TxData

get_transaction_count(address: Union[cfx_address.address.Base32Address, str], block_identifier: Optional[Union[typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending], EpochNumber, int]] = None) → int[source]¶: Compatibility API for conflux. Equivalent to get_next_nonce

get_transaction_receipt(transaction_hash: Union[Hash32, bytes, HexStr, str]) → conflux_web3.types.TxReceipt [source]¶

Returns a transaction receipt, identified by the corresponding transaction hash.

>>> w3.cfx.get_transaction_receipt("0x5ffa11a44c6db42cc30967d4de5949b17ee319c4aba72f3380c60136993a8980")
AttributeDict({'transactionHash': HexBytes('0x5ffa11a44c6db42cc30967d4de5949b17ee319c4aba72f3380c60136993a8980'),
    'index': 227,
    'blockHash': HexBytes('0xceda961d541c78fa2c99907620bb2b13707f72b004b7c70362a5642177e6aae2'),
    'epochNumber': 97108737,
    'from': 'cfxtest:aaksxj04phv0hp02jh3cbym9vghwkzap867jagb043',
    'to': 'cfxtest:aaksxj04phv0hp02jh3cbym9vghwkzap867jagb043',
    'gasUsed': 21000,
    'gasFee': 21000000000000 Drip,
    'contractCreated': None,
    'logs': [],
    'logsBloom': HexBytes('0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000'),
    'stateRoot': HexBytes('0x89dd70006e4714eb81a210a20badf4c37adc7fcbe992b8458460876fcac38ea3'),
    'outcomeStatus': 0,
    'txExecErrorMsg': None,
    'gasCoveredBySponsor': False,
    'storageCoveredBySponsor': False,
    'storageCollateralized': 0,
    'storageReleased': []})

Parameters: transaction_hash (_Hash32) – the hash of the transaction, could be byte or hex string
Returns: the receipt of the transaction
Return type: TxReceipt

get_vote_list(address: Union[cfx_address.address.Base32Address, str], block_identifier: Optional[Union[typing_extensions.Literal[earliest, latest_checkpoint, latest_finalized, latest_confirmed, latest_state, latest_mined, pending], EpochNumber, int]] = None) → Sequence[conflux_web3.types.VoteInfo][source]¶

property get_work¶

Unsupported API

Type: # WARNING

property hashrate¶

Unsupported API

Type: # WARNING

property max_priority_fee¶

Unsupported API

Type: # WARNING

property mining¶

Unsupported API

Type: # WARNING

new_block_filter() → BlockFilterId[source]¶

new_pending_transaction_filter() → TxFilterId[source]¶

send_raw_transaction(raw_transaction: Union[HexStr, bytes]) → conflux_web3.types.transaction_hash.TransactionHash[source]¶

Sends a signed transaction into the network for processing

>>> tx_hash = w3.cfx.send_raw_transaction("0xf86eea8201a28207d0830f4240943838197c0c88d0d5b13b67e1bfdbdc132d4842e389056bc75e2d631000008080a017b8b26f473820475edc49bd153660e56b973b5985bbdb2828fceacb4c91f389a03452f9a69da34ef35acc9c554d7b1d63e9041141674b42c3abb1b57b9f83a2d3")
>>> tx_hash.executed() # equivalent to w3.cfx.wait_for_transaction_receipt(tx_hash)

Parameters: raw_transaction (Union[HexStr, bytes]) – a signed transaction as hex string or bytes
Returns: the hash of the transaction in bytes and wrapped by TransactionHash object which provides chained operations
Return type: TransactionHash

send_transaction(transaction: Union[cfx_utils.types.TxDict, Dict[str, Any]]) → conflux_web3.types.transaction_hash.TransactionHash[source]¶

Send a transaction by using transaction params. ## The node MUST support cfx_sendTransaction rpc (which is typically not supported by public rpc services) ## or account is added to w3.wallet

>>> account = w3.account.create()
>>> w3.wallet.add_account(account)
>>> w3.cfx.send_transaction({
...    "to": w3.address.zero_address(),
...    "from": account.address,
...    "value": 100,
... }).executed()

Parameters: transaction (TxParam) –
Returns: the hash of the transaction in bytes and wrapped by TransactionHash object which provides chained operations
Return type: TransactionHash

property syncing¶: Unsupported API

uninstall_filter(filter_id: Union[LogFilterId, BlockFilterId, TxFilterId, str]) → bool[source]¶

Method object for web3 module methods

Calls to the Method go through these steps:

1. input munging - includes normalization, parameter checking, early parameter formatting. Any processing on the input parameters that need to happen before json_rpc method string selection occurs.

A note about mungers: The first (root) munger should reflect the desired

api function arguments. In other words, if the api function wants to behave as: get_balance(account, block_identifier=None), the root munger should accept these same arguments, with the addition of the module as the first argument e.g.:

``` def get_balance_root_munger(module, account, block_identifier=None):

if block_identifier is None:
block_identifier = DEFAULT_BLOCK

return module, [account, block_identifier]

```

all mungers should return an argument list.

if no munger is provided, a default munger expecting no method arguments will be used.

2. method selection - The json_rpc_method argument can be method string or a function that returns a method string. If a callable is provided the processed method inputs are passed to the method selection function, and the returned method string is used.

3. request and response formatters are set - formatters are retrieved using the json rpc method string.

4. After the parameter processing from steps 1-3 the request is made using the calling function returned by the module attribute retrieve_caller_fn and the response formatters are applied to the output.

wait_for_transaction_receipt(transaction_hash: Union[Hash32, bytes, HexStr, str], timeout: float = 300, poll_latency: float = 0.5) → conflux_web3.types.TxReceipt [source]¶: Alias for wait_till_transaction_executed

wait_till_transaction_confirmed(transaction_hash: Union[Hash32, bytes, HexStr, str], timeout: float = 600, poll_latency: float = 0.5) → conflux_web3.types.TxReceipt [source]¶

Returns transaction receipt after a transaction is confirmed. If TxReceipt is returned, the chances that the transaction execution result to be reverted is tiny. But there are still chances that the transaction might be reverted. ## Developers should use wait_till_transaction_finalized if the transaction is REALLY IMPORTANT.

>>> w3.cfx.get_transaction_receipt("0x5ffa11a44c6db42cc30967d4de5949b17ee319c4aba72f3380c60136993a8980")
AttributeDict({'transactionHash': HexBytes('0x5ffa11a44c6db42cc30967d4de5949b17ee319c4aba72f3380c60136993a8980'),
    'index': 227,
    'blockHash': HexBytes('0xceda961d541c78fa2c99907620bb2b13707f72b004b7c70362a5642177e6aae2'),
    'epochNumber': 97108737,
    'from': 'cfxtest:aaksxj04phv0hp02jh3cbym9vghwkzap867jagb043',
    'to': 'cfxtest:aaksxj04phv0hp02jh3cbym9vghwkzap867jagb043',
    'gasUsed': 21000,
    'gasFee': 21000000000000 Drip,
    'contractCreated': None,
    'logs': [],
    'logsBloom': HexBytes('0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000'),
    'stateRoot': HexBytes('0x89dd70006e4714eb81a210a20badf4c37adc7fcbe992b8458460876fcac38ea3'),
    'outcomeStatus': 0,
    'txExecErrorMsg': None,
    'gasCoveredBySponsor': False,
    'storageCoveredBySponsor': False,
    'storageCollateralized': 0,
    'storageReleased': []})

Parameters

transaction_hash (_Hash32) – the hash of the transaction, could be byte or hex string
timeout (float, optional) – maximum wait time before timeout in seconds, by default 600
poll_latency (float, optional) – time interval to query transaction status in seconds, by default 0.5

Returns

transaction receipt as a dict

Return type

TxReceipt

Raises

TimeExhausted – if timeout
RuntimeError – if transaction is not executed successfully

wait_till_transaction_executed(transaction_hash: Union[Hash32, bytes, HexStr, str], timeout: float = 300, poll_latency: float = 0.5) → conflux_web3.types.TxReceipt [source]¶

Returns transaction receipt after it is executed. If TxReceipt is returned, the transaction is found executed successfully

>>> w3.cfx.wait_till_transaction_executed("0x5ffa11a44c6db42cc30967d4de5949b17ee319c4aba72f3380c60136993a8980")
AttributeDict({'transactionHash': HexBytes('0x5ffa11a44c6db42cc30967d4de5949b17ee319c4aba72f3380c60136993a8980'),
    'index': 227,
    'blockHash': HexBytes('0xceda961d541c78fa2c99907620bb2b13707f72b004b7c70362a5642177e6aae2'),
    'epochNumber': 97108737,
    'from': 'cfxtest:aaksxj04phv0hp02jh3cbym9vghwkzap867jagb043',
    'to': 'cfxtest:aaksxj04phv0hp02jh3cbym9vghwkzap867jagb043',
    'gasUsed': 21000,
    'gasFee': 21000000000000 Drip,
    'contractCreated': None,
    'logs': [],
    'logsBloom': HexBytes('0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000'),
    'stateRoot': HexBytes('0x89dd70006e4714eb81a210a20badf4c37adc7fcbe992b8458460876fcac38ea3'),
    'outcomeStatus': 0,
    'txExecErrorMsg': None,
    'gasCoveredBySponsor': False,
    'storageCoveredBySponsor': False,
    'storageCollateralized': 0,
    'storageReleased': []})

Parameters

transaction_hash (_Hash32) – the hash of the transaction, could be byte or hex string
timeout (float, optional) – maximum wait time before timeout in seconds, by default 300
poll_latency (float, optional) – time interval to query transaction status in seconds, by default 0.5

Returns

transaction receipt as a dict

Return type

TxReceipt

Raises

TimeExhausted – if timeout
RuntimeError – if transaction is not executed successfully

wait_till_transaction_finalized(transaction_hash: Union[Hash32, bytes, HexStr, str], timeout: float = 1200, poll_latency: float = 0.5) → conflux_web3.types.TxReceipt [source]¶

Returns transaction receipt after a transaction is finalized by PoS chain. It will take 4 ～ 6 minutes to finalize a transaction but the finalized transaction won’t be reverted. It is recommended for developers to use this api to confirm important transactions.

Parameters

transaction_hash (_Hash32) – the hash of the transaction, could be byte or hex string
timeout (float, optional) – maximum wait time before timeout in seconds, by default 1200
poll_latency (float, optional) – time interval to query transaction status in seconds, by default 0.5

Returns

transaction receipt as a dict

Return type

TxReceipt

Raises

TimeExhausted – If timeout

wait_till_transaction_mined(transaction_hash: Union[Hash32, bytes, HexStr, str], timeout: float = 60, poll_latency: float = 0.5) → conflux_web3.types.TxData[source]¶

Returns information about a transaction when it is mined. If TxData is returned, the transaction is found contained in a block, but might not be executed. (Transaction will only be executed after 5 epochs)

>>> w3.cfx.wait_till_transaction_mined("0x5ffa11a44c6db42cc30967d4de5949b17ee319c4aba72f3380c60136993a8980")
AttributeDict({'hash': HexBytes('0x5ffa11a44c6db42cc30967d4de5949b17ee319c4aba72f3380c60136993a8980'),
    'nonce': 8230,
    'blockHash': HexBytes('0xceda961d541c78fa2c99907620bb2b13707f72b004b7c70362a5642177e6aae2'),
    'transactionIndex': 227,
    'from': 'cfxtest:aaksxj04phv0hp02jh3cbym9vghwkzap867jagb043',
    'to': 'cfxtest:aaksxj04phv0hp02jh3cbym9vghwkzap867jagb043',
    'value': 0 Drip,
    'gasPrice': 1000000000 Drip,
    'gas': 21000,
    'contractCreated': None,
    'data': HexBytes('0x'),
    'storageLimit': 0,
    'epochHeight': 97108719,
    'chainId': 1,
    'status': 0,
    'v': 1,
    'r': HexBytes('0x1d16cb28acf3973df4f4cc29ffffdba5d36ca1e38f1904f64780fa505691c1b7'),
    's': HexBytes('0x1549267bc4f60af38d23112b47a54dc36481e77eb44dd5ee2c3277810c1c6297')})

Parameters

transaction_hash (_Hash32) – the hash of the transaction, could be byte or hex string
timeout (float, optional) – maximum wait time before timeout in seconds, by default 60
poll_latency (float, optional) – time interval to query transaction status in seconds, by default 0.5

Returns

the transaction data as a dict

Return type

TxData

Raises

TimeExhausted – if timeout

python-conflux-sdk

conflux_web3.cfx apis

conflux_web3.cfx apis¶