API#

Clients#

Providers#

Fallback providers#

Errors#

class pons._provider.RPCError(code: ErrorCode, message: str, data: None | bytes = None)[source]#: A wrapper for a call execution error returned as a proper RPC response.

class pons._client.ContractPanicReason(value)[source]#

Reasons leading to a contract call panicking.

ASSERTION = 1#: If you call assert with an argument that evaluates to false.

COMPILER = 0#: Used for generic compiler inserted panics.

DIVISION_BY_ZERO = 18#: If you divide or modulo by zero (e.g. 5 / 0 or 23 % 0).

EMPTY_ARRAY = 49#: If you call .pop() on an empty array.

INVALID_ENCODING = 34#: If you access a storage byte array that is incorrectly encoded.

INVALID_ENUM_VALUE = 33#: If you convert a value that is too big or negative into an enum type.

OUT_OF_BOUNDS = 50#: If you access an array, bytesN or an array slice at an out-of-bounds or negative index (i.e. x[i] where i >= x.length or i < 0).

OUT_OF_MEMORY = 65#: If you allocate too much memory or create an array that is too large.

OVERFLOW = 17#: If an arithmetic operation results in underflow or overflow outside of an unchecked { ... } block.

UNKNOWN = -1#: Unknown panic code.

ZERO_DEREFERENCE = 81#: If you call a zero-initialized variable of internal function type.

Signers#

Contract ABI#

Testing utilities#

pons exposes several types useful for testing applications that connect to Ethereum RPC servers. Not intended for the production environment.

Secondary classes#

The instances of these classes are not created by the user directly, but rather found as return values, or attributes of other objects.

Utility classes#

class pons._contract_abi.Methods[source]#

Bases: Generic [MethodType].

A holder for named methods which can be accessed as attributes, or iterated over.

__getattr__(method_name: str) → MethodType[source]#: Returns the method by name.

__iter__() → Iterator[MethodType][source]#: Returns the iterator over all methods.

class pons._contract_abi.MethodType#: Generic method type parameter.

class pons._contract_abi.Signature[source]#

Generalized signature of either inputs or outputs of a method.

property canonical_form: str#: Returns the signature serialized in the canonical form as a string.

class pons._contract_abi.Method(name: str, mutability: Mutability, inputs: Mapping[str, Type] | Sequence[Type], outputs: None | Mapping[str, Type] | Sequence[Type] | Type = None)[source]#

A contract method.

Note

If the name of a parameter (input or output) given to the constructor matches a Python keyword, _ will be appended to it.

decode_output(output_bytes: bytes) → Any[source]#: Decodes the output from ABI-packed bytes.

classmethod from_json(method_entry: dict[str, Any]) → Method[source]#: Creates this object from a JSON ABI method entry.

property inputs: Signature#: The input signature of this method.

mutating: bool#: Whether this method may mutate the contract state.

property name: str#: The name of this method.

outputs: Signature#: Method’s output signature.

payable: bool#: Whether this method is marked as payable.

property selector: bytes#: Method’s selector.

Compiled and deployed contracts#

Entities#

class pons._entities.CustomAmount#: A type derived from Amount.

class pons._entities.CustomAddress#: A type derived from Address.

class pons._entities.TxReceipt[source]#

Transaction receipt.

block_hash: BlockHash#: Hash of the block including this transaction.

block_number: int#: Block number including this transaction.

contract_address: None | Address#: If it was a successful deployment transaction, contains the address of the deployed contract.

cumulative_gas_used: int#: The total amount of gas used when this transaction was executed in the block.

effective_gas_price: Amount#: The actual value per gas deducted from the sender’s account.

from_: Address#: Address of the sender.

gas_used: int#: The amount of gas used by the transaction.

logs: tuple[LogEntry, ...]#: An array of log objects generated by this transaction.

status: int#: 1 if the transaction was successful, 0 otherwise.

property succeeded: bool#: True if the transaction succeeded.

to: None | Address#: Address of the receiver. None when the transaction is a contract creation transaction.

transaction_hash: TxHash#: Hash of the transaction.

transaction_index: int#: Integer of the transaction’s index position in the block.

type_: int#: Transaction type: 0 for legacy transactions, 2 for EIP1559 transactions.

class pons._entities.BlockInfo[source]#

Block info.

base_fee_per_gas: Amount#: Base fee per gas in this block.

difficulty: int#: Block’s difficulty.

gas_limit: int#: Block’s gas limit.

gas_used: int#: Gas used for the block.

hash_: None | BlockHash#: Block hash. None for pending blocks.

miner: None | Address#: Block’s miner. None for pending blocks.

nonce: None | int#: Block’s nonce. None for pending blocks.

number: int#: Block number.

parent_hash: BlockHash#: Parent block’s hash.

size: int#: Block size.

timestamp: int#: Block’s timestamp.

total_difficulty: None | int#: Block’s totat difficulty. None for pending blocks.

transactions: tuple[TxInfo, ...] | tuple[TxHash, ...]#: A list of transaction hashes in this block, or a list of details of transactions in this block, depending on what was requested.

class pons._entities.TxInfo[source]#

Transaction info.

block_hash: None | BlockHash#: The hash of the block this transaction belongs to. None for pending transactions.

block_number: int#: The number of the block this transaction belongs to. May be a pending block.

from_: Address#: Transaction sender.

gas: int#: Gas used by the transaction.

gas_price: Amount#: Gas price used by the transaction.

hash_: TxHash#: Transaction hash.

input_: None | bytes#: The data sent along with the transaction.

max_fee_per_gas: None | Amount#: maxFeePerGas value specified by the sender. Only for EIP1559 transactions.

max_priority_fee_per_gas: None | Amount#: maxPriorityFeePerGas value specified by the sender. Only for EIP1559 transactions.

nonce: int#: Transaction nonce.

to: None | Address#: Transaction recipient. None when it’s a contract creation transaction.

transaction_index: None | int#: Transaction index. None for pending transactions.

type_: int#: Transaction type: 0 for legacy transactions, 2 for EIP1559 transactions.

value: Amount#: Associated funds.

class pons._entities.BlockFilter[source]#: BlockFilter(id_: pons._entities.BlockFilterId, provider_path: tuple[int, …])

class pons._entities.PendingTransactionFilter[source]#: PendingTransactionFilter(id_: pons._entities.PendingTransactionFilterId, provider_path: tuple[int, …])

class pons._entities.LogFilter[source]#: LogFilter(id_: pons._entities.LogFilterId, provider_path: tuple[int, …])

class pons._entities.LogTopic[source]#: A log topic for log filtering.

class pons._entities.LogEntry[source]#

Log entry metadata.

address: Address#: The contract address from which this log originated.

block_hash: BlockHash#: Hash of the block where this log was in.

block_number: int#: The block number where this log was.

data: bytes#: ABI-packed non-indexed arguments of the event.

log_index: int#: Log’s position in the block.

removed: bool#: True if log was removed, due to a chain reorganization. False if it is a valid log.

topics: tuple[LogTopic, ...]#: Values of indexed event fields. For a named event, the first topic is the event’s selector.

transaction_hash: TxHash#: Hash of the transactions this log was created from.

transaction_index: int#: Transaction’s position in the block.

class JSON#: A JSON-ifiable object (bool, int, float, str, None, iterable of JSON, or mapping of str to JSON).

Solidity types#

Type aliases are exported from the abi submodule. Arrays can be obtained from Type objects by indexing them (either with an integer for a fixed-size array, or with ... for a variable-sized array).

Helper aliases are exported from pons.abi submodule:

pons.abi.uint(bits: int) → UInt[source]#: Returns the uint<bits> type.

pons.abi.int(bits: int) → Int[source]#: Returns the int<bits> type.

pons.abi.bytes(size: None | int = None) → Bytes[source]#: Returns the bytes<size> type, or bytes if size is None.

pons.abi.address: AddressType#: address type.

pons.abi.string: String#: string type.

pons.abi.bool: Bool#: bool type.

pons.abi.struct(**kwargs: Type) → Struct[source]#: Returns the structure type with given fields.

Actual type objects, for reference:

class pons._abi_types.Type[source]#: The base type for Solidity types.

class pons._abi_types.UInt(bits: int)[source]#: Corresponds to the Solidity uint<bits> type.

class pons._abi_types.Int(bits: int)[source]#: Corresponds to the Solidity int<bits> type.

class pons._abi_types.Bytes(size: None | int = None)[source]#: Corresponds to the Solidity bytes<size> type.

class pons._abi_types.AddressType[source]#: Corresponds to the Solidity address type. Not to be confused with Address which represents an address value.

class pons._abi_types.String[source]#: Corresponds to the Solidity string type.

class pons._abi_types.Bool[source]#: Corresponds to the Solidity bool type.

class pons._abi_types.Struct(fields: Mapping[str, Type])[source]#: Corresponds to the Solidity struct type.