cfx_address.address module

class cfx_address.address.Base32AddressMeta

Bases: type

This is the metaclass of Base32Address to add a setter to class variable Base32Address.default_network_id

property default_network_id: int | None: Refer to Base32Address.default_network_id for the document

class cfx_address.address.Base32Address(address: ~cfx_address.address.Base32Address | ~eth_typing.evm.HexAddress | str, network_id: int | None = <object object>, verbose: bool | None = None, *, _from_trust: bool = False, _ignore_invalid_type: bool = False)

Bases: str

This class can be used to create Base32Address instances and provides useful class methods to deal with base32 format addresses. Base32Address inherits from str, so the Base32Address can be trivially used as strings

Examples:

>>> address = Base32Address("0x1ecde7223747601823f7535d7968ba98b4881e09", network_id=1)
>>> address
'cfxtest:aatp533cg7d0agbd87kz48nj1mpnkca8be1rz695j4'
>>> [
...     address.address_type,
...     address.network_id,
...     address.hex_address,
...     address.verbose_address,
...     address.abbr,
...     address.mapped_evm_space_address,
... ]
['user', 1, '0x1ECdE7223747601823f7535d7968Ba98b4881E09', 'CFXTEST:TYPE.USER:AATP533CG7D0AGBD87KZ48NJ1MPNKCA8BE1RZ695J4', 'cfxtest:aat...95j4', '0x349f086998cF4a0C5a00b853a0E93239D81A97f6']

Parameters:

address (Union[Base32Address,HexAddress,str]) – a base32-or-hex format address
network_id (Optional[int]) – target network_id of the address, defaults to default_network_id. Can be None if first argument is a base32 address, which means don’t change network id
verbose (Optional[bool]) – whether the return value will be encoded in verbose mode, defaults to None (will be viewed as None)
_from_trust (bool) – whether the value is a verified Base32Address, if true, network_id and verbose option should be None, and the verification and encoding process will be skipped. Not recommended to set unless preformance is critical. Defaults to False
_ignore_invalid_type (bool) – whether the address type is validated, defaults to False

Raises:

InvalidAddress – address is neither base32 address nor hex address
InvalidNetworkId – network_id argument is not a positive integer or is None when address argument is a hex address

Return Base32Address:

an encoded base32 object, which can be trivially used as python str, specially, if from_trusted_source is true, the input value will be directly used as the encoded value

Examples:

>>> address = Base32Address("0x1ecde7223747601823f7535d7968ba98b4881e09", network_id=1)
>>> address
'cfxtest:aatp533cg7d0agbd87kz48nj1mpnkca8be1rz695j4'
>>> address_ = Base32Address(address, network_id=1029, verbose=True)
>>> address_
'CFX:TYPE.USER:AATP533CG7D0AGBD87KZ48NJ1MPNKCA8BE7GGP3VPU'
>>> isinstance(address_, str)
True

default_network_id: ClassVar[int | None] = None

Default network id of Base32Address. Base32Address(), encode(), 
and zero_address() will use this variable if network_id parameter is not specified.
For most cases, it is recommended not to directly set this variable but use 
get_base32_address_factory() to set Base32Address.default_network_id
The setter is implemented in the metaclass cfx_address.address.Base32AddressMeta

Parameters:: new_default (Union[None,int]) – new default network id, could be None or positive int
Raises:: InvalidNetworkId – the new_default value is not a positive integer
Examples:

>>> Base32Address.zero_address()
Traceback (most recent call last):
    ...
cfx_utils.exceptions.InvalidNetworkId: Expected network_id to be a positive integer. Receives None of type <class 'NoneType'>
>>> from cfx_address.address import get_base32_address_factory
>>> base32_address_factory = get_base32_address_factory(default_network_id=1)
>>> base32_address_factory.zero_address()
'cfxtest:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa6f0vrcsw'
>>> base32_address_factory.default_network_id = 1029
>>> base32_address_factory.zero_address()
'cfx:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0sfbnjm2'
>>> base32_address_factory.default_network_id = 2.5
Traceback (most recent call last):
    ...
cfx_utils.exceptions.InvalidNetworkId: Expected network_id to be a positive integer. Receives 2.5 of type <class 'float'>

__eq__(_address: object) → bool

invoked when a base32 address is compared to another object (or Base32Address typed object),

Parameters:: _address (str) – value compared to, which is supposed to be encoded in Base32 format (else return false)
Return bool:: True if self and _address are of same hex_address and network_id
Examples:

>>> address = Base32Address("cfxtest:aatp533cg7d0agbd87kz48nj1mpnkca8be1rz695j4")
>>> assert address == "CFXTEST:TYPE.USER:AATP533CG7D0AGBD87KZ48NJ1MPNKCA8BE1RZ695J4"
>>> assert "CFXTEST:TYPE.USER:AATP533CG7D0AGBD87KZ48NJ1MPNKCA8BE1RZ695J4" == address
>>> assert "cfxtest:aatp533cg7d0agbd87kz48nj1mpnkca8be1rz695j4" == address

classmethod from_public_key(public_key: str | bytes, network_id: int = <object object>, verbose: bool = False) → Base32Address

create a Base32Address from public key

Parameters:

public_key (Union[str,bytes]) – str or bytes representation of public key
network_id (int) – network id of the return Base32Address, defaults to class variable default_network_id
verbose (bool) – whether the address will be represented in verbose mode, defaults to False

Return Base32Address:

Base32 representation of the address

>>> Base32Address.from_public_key("0xdacdaeba8e391e7649d3ac4b5329ca0e202d38facd928d88b5f729b89a497e43cc4ad3816fcfdb241497b3b43862afb4c899bc284bf60feca4ee66ff868d1feb", 1)
'cfxtest:aamw4kj6g41pgedw1efjnsm59fbz0b9r1awbp8k2p2'

property network_id: int

Return int:: network_id of the address
Examples:

>>> address = Base32Address("cfxtest:aatp533cg7d0agbd87kz48nj1mpnkca8be1rz695j4")
>>> address.network_id
1

property hex_address: ChecksumAddress

Return ChecksumAddress:: hex address of the address, will be encoded in ethereum checksum format

>>> address = Base32Address("cfxtest:aatp533cg7d0agbd87kz48nj1mpnkca8be1rz695j4")
>>> address.hex_address
'0x1ECdE7223747601823f7535d7968Ba98b4881E09'

property address_type: Literal['null', 'builtin', 'user', 'contract', 'invalid']

Return Literal[“null”, “builtin”, “user”, “contract”, “invalid”]:: address type of an address.
Examples:

>>> address = Base32Address("cfx:aatp533cg7d0agbd87kz48nj1mpnkca8be7ggp3vpu")
>>> address.address_type
'user'

property eth_checksum_address: ChecksumAddress

Return ChecksumAddress:: alias for hex_address. This API will be deprecated in a future version

>>> address = Base32Address("cfxtest:aatp533cg7d0agbd87kz48nj1mpnkca8be1rz695j4")
>>> address.eth_checksum_address
'0x1ECdE7223747601823f7535d7968Ba98b4881E09'

property verbose_address: Base32Address

Return Base32Address:: self presented in verbose mode

>>> address = Base32Address("cfxtest:aatp533cg7d0agbd87kz48nj1mpnkca8be1rz695j4")
>>> address.verbose_address
'CFXTEST:TYPE.USER:AATP533CG7D0AGBD87KZ48NJ1MPNKCA8BE1RZ695J4'

property abbr: str

Return str:: abbreviation of the address, as mentioned in https://forum.conflux.fun/t/voting-results-for-new-address-abbreviation-standard/7131
Examples:

>>> Base32Address("cfxtest:aatp533cg7d0agbd87kz48nj1mpnkca8be1rz695j4").abbr
'cfxtest:aat...95j4'
>>> Base32Address("cfx:aatp533cg7d0agbd87kz48nj1mpnkca8be7ggp3vpu").abbr
'cfx:aat...7ggp3vpu'

property compressed_abbr: str

Return str:: compressed abbreviation of the address, as mentioned in https://forum.conflux.fun/t/voting-results-for-new-address-abbreviation-standard/7131
Examples:

>>> address = Base32Address("cfx:aatp533cg7d0agbd87kz48nj1mpnkca8be7ggp3vpu")
>>> address.abbr
'cfx:aat...7ggp3vpu'
>>> address.compressed_abbr
'cfx:aat...3vpu'

property mapped_evm_space_address: ChecksumAddress

Return ChecksumAddress:: the address of mapped account for EVM space as defined in https://github.com/Conflux-Chain/CIPs/blob/master/CIPs/cip-90.md#mapped-account

>>> address = Base32Address("cfx:aatp533cg7d0agbd87kz48nj1mpnkca8be7ggp3vpu")
>>> address.mapped_evm_space_address
'0x349f086998cF4a0C5a00b853a0E93239D81A97f6'

classmethod encode_base32(hex_address: str, network_id: int = <object object>, verbose: bool = False, *, _ignore_invalid_type: bool = False) → Base32Address

Encode hex address to base32 address

Parameters:

hex_address (str) – hex address begins with 0x
network_id (int) – address network id, e.g., 1 for testnet and 1029 for mainnet, defaults to class variable default_network_id
verbose (bool) – whether the address will be presented in verbose mode, defaults to False
_ignore_invalid_type (bool) – whether the address type is validated, defaults to False

Return Base32Address:

an encoded base32 object, which can be trivially used as python str

Examples:

>>> Base32Address.encode_base32("0x1ecde7223747601823f7535d7968ba98b4881e09", 1)
'cfxtest:aatp533cg7d0agbd87kz48nj1mpnkca8be1rz695j4'
>>> Base32Address.encode_base32("0x1ecde7223747601823f7535d7968ba98b4881e09", 1029, verbose=True)
'CFX:TYPE.USER:AATP533CG7D0AGBD87KZ48NJ1MPNKCA8BE7GGP3VPU'

classmethod decode(base32_address: str) → Base32AddressParts

Decode a base32 address string and get its hex_address, address_type, and network_id

Parameters:: base32_address (str) – address encoded in base32 format
Raises:: InvalidBase32Address – the parameter is not a valid CIP-37 address
Return Base32AddressParts:: a dict object with field “hex_address”, “address_type” and “network_id”
Examples:

>>> Base32Address.decode("cfxtest:aatp533cg7d0agbd87kz48nj1mpnkca8be1rz695j4")
{'network_id': 1, 'hex_address': '0x1ECdE7223747601823f7535d7968Ba98b4881E09', 'address_type': 'user'}

classmethod is_valid_base32(value: Any) → bool

Whether a value is a valid string-typed base32 address

Return bool:: True if valid, else False

classmethod validate(value: Any) → Literal[True]

Validate if a value is a valid string-typed base32_address, raises an exception if not

Parameters:: value (str) – value to validate
Raises:: InvalidBase32Address – raises an exception if the address is not a valid base32 address
Return Literal[True]:: returns True only if address is valid

classmethod equals(address1: str, address2: str) → bool

Check if two addresses share same hex_address and network_id

It will throw an error if any param is not in CIP-37 format while __eq__() doesn’t

Parameters:

address1 (str) – base32 address to compare
address2 (str) – base32 address to compare

Raises:

InvalidBase32Address – either address is not a valid base32 address

Return bool:

whether two addresses share same hex_address and network_id

classmethod zero_address(network_id: int = <object object>, verbose: bool = False) → Base32Address

Get zero address of the target network.

Parameters:

network_id (int) – target network_id, defaults to Base32Address.default_network_id
verbose (bool) – whether the zero address is presented in verbose mode, defaults to False

Return Base32Address:

base32 format zero address of the target network

Examples:

>>> Base32Address.zero_address(network_id=1)
'cfxtest:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa6f0vrcsw'

classmethod shorten_base32_address(base32_address: str, compressed: bool = False) → str

Returns the abbreviation of the address

Parameters:

base32_address (str) – address to shorten
compressed (bool) – whether the abbreviation will be presented in compressed form, which only affects mainnet addresses, defaults to False

Raises:

InvalidBase32Address – raised if address is invalid

Return str:

the abbreviation string

>>> Base32Address.shorten_base32_address("cfx:aatp533cg7d0agbd87kz48nj1mpnkca8be7ggp3vpu")
'cfx:aat...7ggp3vpu'
>>> Base32Address.shorten_base32_address("cfx:aatp533cg7d0agbd87kz48nj1mpnkca8be7ggp3vpu", compressed=True)
'cfx:aat...3vpu'

classmethod calculate_mapped_evm_space_address(base32_address: str) → ChecksumAddress

Calculate the address of mapped account for EVM space as defined in https://github.com/Conflux-Chain/CIPs/blob/master/CIPs/cip-90.md#mapped-account

Raises:: InvalidBase32Address – raised when address is not a valid base32 address
Examples:

>>> Base32Address.calculate_mapped_evm_space_address("CFXTEST:TYPE.USER:AATP533CG7D0AGBD87KZ48NJ1MPNKCA8BE1RZ695J4")
'0x349f086998cF4a0C5a00b853a0E93239D81A97f6'

cfx_address.address.get_base32_address_factory(default_network_id: int) → Type[Base32Address]

Generate a new Base32Address class object with default_network_id so the class variable will not influence the global default_network_id setting

>>> base32_address_factory = get_base32_address_factory(default_network_id=1)
>>> base32_address_factory.zero_address()
'cfxtest:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa6f0vrcsw'

Parameters:: default_network_id (int) – default network
Return Type[Base32Address]:: a Class object of Base32Address with default_network_id