SQL Tables

This section aims at giving a detailed description of the psql tables in the database and their corresponding helper functions.

../_images/ethereum_state_machine.jpeg

Blocks

As visible from the image above, a blockchain is literally a chain of blocks. A block contains a list of transactions, few features to prove the work done by a miner and a list of uncles.

class ether_sql.models.blocks.Blocks(**kwargs)[source]

Class mapping a block table in the psql database to a block in ethereum node.

Parameters:
  • block_number (int) – Quantity equal to number of blocks behind the current block
  • block_hash (str) – The Keccak 256-bit hash of this block
  • parent_hash (str) – The Keccak 256-bit hash of the parent of this block
  • difficulty (int) – Difficulty level of this block
  • gas_used (int) – Total gas used by the transactions in this block
  • miner (str) – Address to which all block rewards are transferred
  • timestamp (datetime) – Unix time at the at this blocks inception
  • sha3uncles (str) – Keccak 256-bit hash of the uncles portion of this block
  • extra_data (str) – Byte array of 32 bytes or less containing extra data of this block
  • gas_limit (int) – Current maximum gas expenditure per block
  • uncle_count (int) – Number of uncles in this block
  • transaction_count (int) – Number of transactions in this block
classmethod add_block(block_data, iso_timestamp)[source]

Creates a new block object from data received from JSON-RPC call eth_getBlockByNumber.

Parameters:
  • block_data (dict) – data received from the JSON RPC call
  • iso_timestamp (datetime) – timestamp when the block was mined
classmethod missing_blocks(max_block_number=None)[source]

Return missing blocks in the blocks table between 0 to block_number

Parameters:max_block_number (int) – Maximum block number that we want to find missing blocks from

Transactions

A transaction is the basic method for Ethereum accounts to interact with each other. The transaction is a single cryptographically signed instruction sent to the Ethereum network and has the capacity to change the world state.

class ether_sql.models.transactions.Transactions(**kwargs)[source]

Class mapping a transaction table in the psql database to a transaction in ethereum node.

Parameters:
  • transaction_hash (str) – The Keccak 256-bit hash of this transaction
  • block_number (int) – Number of the block containing this transaction
  • nonce (int) – Number of transactions sent by this sender
  • sender (str) – Address of account which initiated this transaction
  • start_gas (int) – Maximum amount of gas to be used while executing this transaction
  • value_wei (int) – Number of wei to be transferred to the receiver of this transaction
  • receiver (str) – Address of the recepient of this transaction, null if transaction creates a smart-contract
  • data (str) – Unlimited size text specifying input data of message call or code of a contract create
  • gas_price (int) – Number of wei to pay the miner per unit of gas
  • timestamp (int) – Unix time at the at this transactions blocks
  • transaction_index (datetime) – Position of this transaction in the transaction list of this block
classmethod add_transaction(transaction_data, block_number, iso_timestamp)[source]

Creates a new transaction object from data received from JSON-RPC call eth_getBlockByNumber.

Parameters:
  • transaction_data (dict) – data received from JSON RPC call
  • iso_timestamp (datetime) – timestamp when the block containing the transaction was mined
  • block_number (int) – block number of the block where this transaction was included

Uncles

Due to ethereum block-chains fast block propagation time (~15 seconds), the probability of a block with sufficient proof-of-work becoming stale becomes quite high. This reduces the security and miner decentralization of block-chain. To rectify this issue ethereum proposes a modified-GHOST protocol by including and rewarding uncles (ommers) or stale blocks not included in the blockchain.

class ether_sql.models.uncles.Uncles(**kwargs)[source]

Class mapping an uncle table in the psql database to an uncle (ommer) in ethereum node.

Parameters:
  • uncle_hash (str) – The Keccak 256-bit hash of this uncle
  • uncle_blocknumber (int) – Number of blocks behind this uncle
  • parent_hash (str) – The Keccak 256-bit hash of the parent of this uncle
  • difficulty (int) – Difficulty level of this block
  • current_blocknumber (int) – Block number where this uncle was included
  • gas_used (int) – Total gas used by the transactions in this uncle
  • miner (str) – Address of account where all corresponding uncle rewards are transferred
  • timestamp (datetime) – Unix time at the at this uncles inception
  • sha3uncles (str) – Keccak 256-bit hash of the uncles portion of this uncle
  • extra_data (str) – Byte array of 32 bytes or less containing extra data of this block
  • gas_limit (int) – Current maximum gas expenditure per block
classmethod add_uncle(uncle_data, block_number, iso_timestamp)[source]

Creates a new block object from data received from JSON-RPC call eth_getUncleByBlockNumberAndIndex.

Parameters:
  • uncle_data (dict) – uncle data received from JSON RPC call
  • block_number (int) – block number where this uncle was included
  • iso_timestamp (datetime) – timestamp when the block was mined

Receipts

Receipts information concerning the execution of a transaction in the block-chain. They can be useful to form a zero-knowledge proof, index and search, and debug transactions. The status column was included after the Byzantinium hardfork.

class ether_sql.models.receipts.Receipts(**kwargs)[source]

Class mapping a log table in the psql database to a log in ethereum node.

Parameters:
  • transaction_hash (str) – The Keccak 256-bit hash of this transaction
  • status (bool) – Success or failure of this transaction, included after the Byzantinium fork
  • gas_used (int) – Amount of gas used by this specific transaction alone
  • cumulative_gas_used (int) – Total amount of gas used after this transaction was included in the block
  • contract_address (str) – Contract address create if transaction was a contract create transaction, else null
  • block_number (int) – Number of the block containing this transaction
  • timestamp (datetime) – Unix time at the at this transactions blocks
  • transaction_index (int) – Position of this transaction in the transaction list of this block
classmethod add_receipt(receipt_data, block_number, timestamp)[source]

Creates a new receipt object from data received from JSON-RPC call eth_getTransactionReceipt.

Parameters:
  • receipt_data (dict) – receipt data received from the JSON RPC callable
  • timestamp (int) – timestamp of the block where this transaction was included
  • block_number (int) – block number of the block where this transaction was included

Logs

The logs table contains the logs which were accrued during the execution of the the transaction, they are helpful in deciphering smart-contract executions or message calls.

class ether_sql.models.logs.Logs(**kwargs)[source]

Class mapping a log table in the psql database to a log in ethereum node.

Parameters:
  • transaction_hash (str) – Hash of the transaction which created this log
  • address (str) – Address from which this log originated
  • data (str) – Contains one or more 32 Bytes non-indexed arguelents of the log
  • block_number (int) – The block number where this transaction was included
  • timestamp (datetime) – Timestamp when the block was mined
  • transaction_index (int) – Position of the transaction in the block
  • log_index (int) – Position of the log in the block
  • topics_count (int) – Total number of topics in this log
  • topic_1 (str) – First topic in the log
  • topic_2 (str) – Second topic in the log
  • topic_3 (str) – Third topic in the log
  • topic_4 (str) – Fourth topic in the log
classmethod add_log(log_data, block_number, iso_timestamp)[source]

Creates a new log object from data received from JSON-RPC call eth_getTransactionReceipt.

Parameters:
  • log_data (dict) – data received from receipt JSON RPC call
  • block_number (int) – block number of the block containing the log
  • iso_timestamp (datetime) – timestamp when the block containing the transaction was mined
classmethod add_log_list(current_session, log_list, block_number, timestamp)[source]

Adds a list of logs in the session

Traces

The trace module is for getting a deeper insight into transaction processing, can be used to debugging transactions and also access the internal transactions which are not included in a block.

class ether_sql.models.traces.Traces(**kwargs)[source]

Class mapping a traces table in the psql database to a trace in ethereum node.

Parameters:
  • block_number (int) – Number of the block containing this trace
  • transaction_hash (str) – The of the transaction containing this trace
  • trace_type (str) – Type of trace available types; ‘call’, ‘create’, ‘suicide’ and ‘reward’
  • trace_address (str) – Array of integers specifying the address of the trace in this transaction
  • subtraces (int) – Number of subsequent traces
  • transaction_index (int) – Position of the transaction in this block
  • sender (str) – Address of account which initiated this trace
  • receiver (str) – Address of recepient of this trace, null for trace_type = ‘create’ or ‘suicide’
  • value (int) – Number of wei to be transferred to the receiver of this trace
  • start_gas (int) – Maximum amount of gas to be used while executing this trace
  • input_data (str) – Unlimited size text specifying input data of message call or code of a contract create
  • gas_used (int) – The amount of gas utilized by this step
  • contract_address (str) – Address of created contract if trace_type = ‘create’ else null
  • output (str) – Output of this trace
  • error (str) – Error message if this step resulted in an error

Note

This needs proper documentation from team parity

classmethod add_trace(dict_trace, transaction_hash, transaction_index, block_number, timestamp)[source]

Creates a new trace object from data received from JSON-RPC call trace_transaction.

Parameters:
  • dict_trace (dict) – trace data received from the JSON RPC callable
  • timestamp (int) – timestamp of the block where this trace was included
  • block_number (int) – block number of the block where this trance was included
classmethod add_trace_list(current_session, trace_list, transaction_hash, transaction_index, block_number, timestamp)[source]

Adds a list of traces in the sql session

StateDiff

The state diff table contains information about the change in state after each transaction or block

class ether_sql.models.state_diff.StateDiff(**kwargs)[source]

Class mapping a state_diff table in psql to a difference in state after transactions

Parameters:
  • block_number (int) – Number of the block containing this StateDiff
  • timestamp (timestamp) – Unix time at the mining of this block
  • transaction_hash (str) – The transaction hash if this was created by a transaction
  • transaction_index (int) – Position of this transaction in the transaction list of the block
  • address (str) – Account address where the change occoured
  • balance_diff (int) – Difference in balance due to this row
  • nonce_diff (int) – Difference in nonce due to this row
  • code_from (str) – Initial code of this account
  • code_to (str) – Final code of this account
classmethod add_mining_rewards(current_session, block, uncle_list)[source]

Adds the mining and uncle rewards to the state_diff table

classmethod add_state_diff(balance_diff, nonce_diff, code_from, code_to, address, transaction_hash, transaction_index, block_number, timestamp, miner=None, fees=None, state_diff_type=None)[source]

Creates a new state_diff object

classmethod add_state_diff_dict(current_session, state_diff_dict, transaction_hash, transaction_index, block_number, timestamp, miner, fees)[source]

Creates a bunch of state_diff objects upon receiving them as a dictionary and adds them to the current db_session

StorageDiff

The storage diff table contains information about the change in storage after each contract execution

class ether_sql.models.storage_diff.StorageDiff(**kwargs)[source]

Class mapping the storage_diff table in psql to difference in storage due to transactions

Parameters:
  • block_number (int) – Number of the block containing this StorageDiff
  • timestamp (timestamp) – Unix time at the mining of this block
  • transaction_hash (str) – The transaction hash if this was created by a transaction
  • transaction_index (int) – Position of this transaction in the transaction list of the block
  • state_diff_id (int) – Id in state_diff table which caused this change in storage
  • address (str) – Contract address where the change occoured
  • position (str) – Position in the contract address where this change occoured
  • storage_from (str) – Initial value of the storage
  • storage_to (str) – Final value of the storage
classmethod add_storage_diff(storage_diff_row, position, address, transaction_hash, transaction_index, block_number, timestamp, state_diff_id)[source]

Creates a new storage_diff object

classmethod add_storage_diff_dict(current_session, storage_diff_dict, address, transaction_hash, transaction_index, block_number, timestamp, state_diff_id)[source]

Creates a bunch of storage_diff objects upon receiving them as a dictionary and adds them to the current db_session