conflux_web3.cfx apis

conflux_web3.cfx apis#

class conflux_web3.client.BaseCfx(w3: AsyncWeb3 | Web3) → None[source]#

contract(address: cfx_address.address.Base32Address | str | None = None, *, name: Literal['AdminControl', 'ConfluxContext', 'CrossSpaceCall', 'SponsorWhitelistControl', 'ParamsControl', 'PoSRegister', 'Staking'] | Literal['Faucet', 'cUSDT', 'FC', 'ERC1820', 'ENS'] | Literal['ERC20', 'ERC1820'] | Literal['ENS', 'ETHRegistrarController', 'NameWrapper', 'RESOLVER'] | None = None, with_deployment_info: bool | None = None, **kwargs: Any) → Type[conflux_web3.contract.ConfluxContract] | conflux_web3.contract.ConfluxContract[source]#

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: Base32Address#: default account address, this address will be used as default from address if transaction from field is empty

class conflux_web3.client.ConfluxClient(w3: conflux_web3.main.Web3) → None[source]#

RPC entry defined provides friendlier APIs for users

property accounts: Tuple[Base32Address]#

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: Type[Base32Address]#

property block_number#

Unsupported API, use web3.cfx.epoch_number instead

Type:: # WARNING

call(transaction: cfx_utils.types.LegacyTxDict | cfx_utils.types.TypedTxDict | cfx_utils.types.CIP1559TxDict | Dict[str, Any], block_identifier: Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending'] | cfx_utils.types.EpochNumber | int | None = 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

Return type:

Any

property chain_id: int#

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: cfx_address.address.Base32Address | str, contract_address: cfx_address.address.Base32Address | str, gas_limit: int, gas_price: cfx_utils.token_unit.Drip | cfx_utils.token_unit.AbstractDerivedTokenUnit[cfx_utils.token_unit.Drip] | int, storage_limit: cfx_utils.types.Storage | int, block_identifier: Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending'] | cfx_utils.types.EpochNumber | int | None = None) → conflux_web3.types.TransactionPaymentInfo[source]#

Return type:: conflux_web3.types.TransactionPaymentInfo

property client_version#

property coinbase#

Unsupported API

Type:: # WARNING

property epoch_number: EpochNumber#

Returns latest_mined epoch number

Returns:: latest mined epoch number
Return type:: EpochNumber

epoch_number_by_tag(epoch_tag: Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending']) → cfx_utils.types.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: cfx_utils.types.LegacyTxDict | cfx_utils.types.TypedTxDict | cfx_utils.types.CIP1559TxDict | Dict[str, Any], block_identifier: Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending'] | cfx_utils.types.EpochNumber | int | None = None) → conflux_web3.types.EstimateResult[source]#

Compatibility API for conflux. Equivalent to estimate_gas_and_collateral

Return type:: conflux_web3.types.EstimateResult

estimate_gas_and_collateral(transaction: cfx_utils.types.LegacyTxDict | cfx_utils.types.TypedTxDict | cfx_utils.types.CIP1559TxDict | Dict[str, Any], block_identifier: Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending'] | cfx_utils.types.EpochNumber | int | None = 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

Return type:

EstimateResult

fee_history(epoch_count: int, block_identifier: Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending'] | cfx_utils.types.EpochNumber | int, reward_percentiles: Sequence[float]) → conflux_web3.types.FeeHistory[source]#

Return type:: conflux_web3.types.FeeHistory

property gas_price: Drip#

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: cfx_address.address.Base32Address | str, block_identifier: Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending'] | cfx_utils.types.EpochNumber | int | None = None) → conflux_web3.types.AccountInfo[source]#

Return type:: conflux_web3.types.AccountInfo

get_account_pending_info(address: cfx_address.address.Base32Address | str) → conflux_web3.types.PendingInfo[source]#

Return type:: conflux_web3.types.PendingInfo

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

Return type:: conflux_web3.types.PendingTransactionsInfo

get_accumulate_interest_rate(block_identifier: Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending'] | cfx_utils.types.EpochNumber | int | None = None) → int[source]#

Return type:: int

get_admin(address: str, block_identifier: Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending'] | cfx_utils.types.EpochNumber | int | None = None) → None | cfx_address.address.Base32Address[source]#

Return type:: None | cfx_address.address.Base32Address

get_balance(address: cfx_address.address.Base32Address | str, block_identifier: Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending'] | cfx_utils.types.EpochNumber | int | None = 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: eth_typing.evm.Hash32 | bytes | eth_typing.encoding.HexStr | str | Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending'] | cfx_utils.types.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

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: Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending'] | cfx_utils.types.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: eth_typing.evm.Hash32 | bytes | eth_typing.encoding.HexStr | str, full_transactions: bool = False) → conflux_web3.types.BlockData | None[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]

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: cfx_utils.types.EpochNumber | int | Literal['latest_checkpoint']) → Sequence[conflux_web3.types.BlockRewardInfo][source]#

Return type:: typing.Sequence[conflux_web3.types.BlockRewardInfo]

get_blocks_by_epoch(epoch_number_param: Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending'] | cfx_utils.types.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: cfx_address.address.Base32Address | str, block_identifier: Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending'] | cfx_utils.types.EpochNumber | int | None = 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: cfx_address.address.Base32Address | str, block_identifier: Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending'] | cfx_utils.types.EpochNumber | int | None = None) → cfx_utils.types.Storage[source]#

Return type:: typing.NewType(Storage, int)

get_collateral_info(block_identifier: Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending'] | cfx_utils.types.EpochNumber | int | None = None) → conflux_web3.types.CollateralInfo[source]#

Return type:: conflux_web3.types.CollateralInfo

get_confirmation_risk_by_hash(block_hash: eth_typing.evm.Hash32 | bytes | eth_typing.encoding.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: cfx_address.address.Base32Address | str, block_identifier: Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending'] | cfx_utils.types.EpochNumber | int | None = None) → Sequence[conflux_web3.types.DepositInfo][source]#

Return type:: typing.Sequence[conflux_web3.types.DepositInfo]

get_epoch_receipts(epoch_number: Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending'] | cfx_utils.types.EpochNumber | int, include_espace_receipts: bool | None = False) → Sequence[Sequence[conflux_web3.types.TxReceipt | conflux_web3.types.TxReceiptWithSpace]][source]#

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_fee_burnt() → cfx_utils.token_unit.Drip[source]#

Return type:: cfx_utils.token_unit.Drip

get_filter_changes(filter_id: conflux_web3.types.LogFilterId | conflux_web3.types.BlockFilterId | conflux_web3.types.TxFilterId | str) → Sequence[eth_typing.evm.Hash32] | 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. :rtype: typing.Sequence[typing.NewType(Hash32, bytes)] | typing.Sequence[conflux_web3.types.LogReceipt]

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: conflux_web3.types.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. :rtype: typing.Sequence[conflux_web3.types.LogReceipt]

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: Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending'] | cfx_utils.types.EpochNumber | int | None = None) → int[source]#

Return type:: int

get_logs(filter_params: conflux_web3.types.FilterParams | None = None, **kwargs: typing_extensions.Unpack[conflux_web3.types.FilterParams]) → List[conflux_web3.types.LogReceipt][source]#

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 Conflux-Chain/python-conflux-sdk to know how to process the returned logs
Return type:: List[LogReceipt]

get_next_nonce(address: cfx_address.address.Base32Address | str, block_identifier: Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending'] | cfx_utils.types.EpochNumber | int | None = 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

Return type:

int

get_params_from_vote(block_identifier: Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending'] | cfx_utils.types.EpochNumber | int | None = None) → conflux_web3.types.DAOVoteInfo[source]#

Return type:: conflux_web3.types.DAOVoteInfo

get_pos_economics(block_identifier: Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending'] | cfx_utils.types.EpochNumber | int | None = None) → conflux_web3.types.PoSEconomicsInfo[source]#

Return type:: conflux_web3.types.PoSEconomicsInfo

get_pos_reward_by_epoch(epoch_number: cfx_utils.types.EpochNumber | int) → conflux_web3.types.PoSEpochRewardInfo | None[source]#

Return type:: conflux_web3.types.PoSEpochRewardInfo | None

get_skipped_blocks_by_epoch(epoch_number_param: Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending'] | cfx_utils.types.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: cfx_address.address.Base32Address | str, block_identifier: Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending'] | cfx_utils.types.EpochNumber | int | None = None) → conflux_web3.types.SponsorInfo[source]#

Return type:: conflux_web3.types.SponsorInfo

get_staking_balance(address: cfx_address.address.Base32Address | str, block_identifier: Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending'] | cfx_utils.types.EpochNumber | int | None = 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: cfx_address.address.Base32Address | str, storage_position: int, block_identifier: Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending'] | cfx_utils.types.EpochNumber | int | None = None) → hexbytes.main.HexBytes | None[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: cfx_address.address.Base32Address | str, block_identifier: Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending'] | cfx_utils.types.EpochNumber | int | None = None) → conflux_web3.types.StorageRoot | None[source]#

Return type:: conflux_web3.types.StorageRoot | None

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

Return type:: conflux_web3.types.SupplyInfo

get_transaction(transaction_hash: eth_typing.evm.Hash32 | bytes | eth_typing.encoding.HexStr | str) → conflux_web3.types.TxData[source]#

Alias for get_transaction_by_hash

Return type:: conflux_web3.types.TxData

get_transaction_by_hash(transaction_hash: eth_typing.evm.Hash32 | bytes | eth_typing.encoding.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: cfx_address.address.Base32Address | str, block_identifier: Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending'] | cfx_utils.types.EpochNumber | int | None = None) → int[source]#

Compatibility API for conflux. Equivalent to get_next_nonce

Return type:: int

get_transaction_receipt(transaction_hash: eth_typing.evm.Hash32 | bytes | eth_typing.encoding.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: cfx_address.address.Base32Address | str, block_identifier: Literal['earliest', 'latest_checkpoint', 'latest_finalized', 'latest_confirmed', 'latest_state', 'latest_mined', 'pending'] | cfx_utils.types.EpochNumber | int | None = None) → Sequence[conflux_web3.types.VoteInfo][source]#

Return type:: typing.Sequence[conflux_web3.types.VoteInfo]

property get_work#

Unsupported API

Type:: # WARNING

property hashrate#

Unsupported API

Type:: # WARNING

property max_priority_fee: Drip#: Try to use eth_maxPriorityFeePerGas but, since this is not part of the spec and is only supported by some clients, fall back to an eth_feeHistory calculation with min and max caps.

property mining#

Unsupported API

Type:: # WARNING

new_block_filter() → conflux_web3.types.BlockFilterId[source]#

Return type:: typing.NewType(BlockFilterId, typing.NewType(HexStr, str))

new_filter(filter_params: conflux_web3.types.FilterParams | None = None, **kwargs: typing_extensions.Unpack[conflux_web3.types.FilterParams]) → conflux_web3.types.LogFilterId[source]#

Return type:: typing.NewType(LogFilterId, typing.NewType(HexStr, str))

new_pending_transaction_filter() → conflux_web3.types.TxFilterId[source]#

Return type:: typing.NewType(TxFilterId, typing.NewType(HexStr, str))

send_raw_transaction(raw_transaction: eth_typing.encoding.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: cfx_utils.types.LegacyTxDict | cfx_utils.types.TypedTxDict | cfx_utils.types.CIP1559TxDict | 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

set_gas_price_strategy(strategy: Callable[[conflux_web3.main.Web3, cfx_utils.types.LegacyTxDict | cfx_utils.types.TypedTxDict | cfx_utils.types.CIP1559TxDict | Dict[str, Any]], cfx_utils.token_unit.Drip])[source]#

property syncing#: Unsupported API

uninstall_filter(filter_id: conflux_web3.types.LogFilterId | conflux_web3.types.BlockFilterId | conflux_web3.types.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. :rtype: bool

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: eth_typing.evm.Hash32 | bytes | eth_typing.encoding.HexStr | str, timeout: float = 300, poll_latency: float = 0.5) → conflux_web3.types.TxReceipt[source]#

Alias for wait_till_transaction_executed

Return type:: conflux_web3.types.TxReceipt

wait_till_transaction_confirmed(transaction_hash: eth_typing.evm.Hash32 | bytes | eth_typing.encoding.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: eth_typing.evm.Hash32 | bytes | eth_typing.encoding.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: eth_typing.evm.Hash32 | bytes | eth_typing.encoding.HexStr | str, timeout: float = 1200, poll_latency: float = 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: eth_typing.evm.Hash32 | bytes | eth_typing.encoding.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

conflux_web3.cfx apis

Contents

conflux_web3.cfx apis#