substreams_base_main

noslav

v0.1.4/4 downloads/Repository

Package ref

substreams-base-main@v0.1.4

Download .spkg

Run package

CLI

Run map_block_meta from the command line.

substreams run substreams-base-main@v0.1.4 map_block_meta -e base-mainnet --start-block -1

Authenticate by running substreams auth or directly on thegraph.market (see docs).

README

base_mainnet substreams modules

This package was initialized via substreams init and is being updated with custom modules to support the Base Mainnet blockchain streaming service using substreams.

Nodes available for streaming:

https://docs.substreams.dev/reference-material/chains-and-endpoints

Usage

substreams build
substreams auth
substreams gui       			  # Get streaming!

Optionally, the substreams package can be published to the Substreams Registry

substreams registry login         # Login to substreams.dev
substreams registry publish       # Publish your Substreams to substreams.dev

Data

graph TD;
  map_block_meta[map: map_block_meta];
  sf.ethereum.type.v2.Block[source: sf.ethereum.type.v2.Block] --> map_block_meta;
  map_block_metadata[map: map_block_metadata];
  sf.ethereum.type.v2.Block[source: sf.ethereum.type.v2.Block] --> map_block_metadata;
  map_block_full[map: map_block_full];
  sf.ethereum.type.v2.Block[source: sf.ethereum.type.v2.Block] --> map_block_full;
  map_transactions_all[map: map_transactions_all];
  sf.ethereum.type.v2.Block[source: sf.ethereum.type.v2.Block] --> map_transactions_all;
  map_transactions_filter[map: map_transactions_filter];
  sf.ethereum.type.v2.Block[source: sf.ethereum.type.v2.Block] --> map_transactions_filter;
  map_transaction_traces[map: map_transaction_traces];
  sf.ethereum.type.v2.Block[source: sf.ethereum.type.v2.Block] --> map_transaction_traces;

Running Modules

`map_block_meta`

Basic block metadata without extended fields. Use this for lightweight pipelines that don't need withdrawal counts.

> substreams run -e base-mainnet.streamingfast.io:443 substreams.yaml map_block_meta --start-block 31229579 --stop-block +1

----------- BLOCK #31,229,579 (8384034397f8c979d3c385f87e3d2568a8409a21fb162eb42250d3d3bb54f20c) ---------------
{
  "@module": "map_block_meta",
  "@block": 31229579,
  "@type": "base.mainnet.block_meta.v1.Meta",
  "@data": {
    "blockHash": "8384034397f8c979d3c385f87e3d2568a8409a21fb162eb42250d3d3bb54f20c",
    "blockNumber": "31229579",
    "blockTimestamp": "2025-06-06T22:21:45Z",
    "transactionsLen": "37",
    "parentHash": "2db56e9532ad11f6671fcd0c48e35a5e3983078264cfbb78478d27cc7be8e9ca"
  }
}

`map_block_metadata`

Extended block metadata including withdrawals_len — the count of EIP-4895 validator withdrawal balance changes in the block. On L1 Ethereum (post-Shanghai) this reflects actual withdrawal events; on L2s like Base it will be 0.

> substreams run -e base-mainnet.streamingfast.io:443 substreams.yaml map_block_metadata --start-block 31229579 --stop-block +1

----------- BLOCK #31,229,579 (8384034397f8c979d3c385f87e3d2568a8409a21fb162eb42250d3d3bb54f20c) ---------------
{
  "@module": "map_block_metadata",
  "@block": 31229579,
  "@type": "base.mainnet.block_metadata.v1.Metadata",
  "@data": {
    "blockHash": "8384034397f8c979d3c385f87e3d2568a8409a21fb162eb42250d3d3bb54f20c",
    "blockNumber": "31229579",
    "blockTimestamp": "2025-06-06T22:21:45Z",
    "transactionsLen": "37",
    "parentHash": "2db56e9532ad11f6671fcd0c48e35a5e3983078264cfbb78478d27cc7be8e9ca",
    "withdrawalsLen": "16"
  }
}

`map_transactions_all`

This module extracts all transactions from a block.

> substreams run -e base-mainnet.streamingfast.io:443 substreams.yaml map_transactions_all --start-block 31229579 --stop-block +1

----------- BLOCK #31,229,579 (8384034397f8c979d3c385f87e3d2568a8409a21fb162eb42250d3d3bb54f20c) age=59m28.801967s ---------------
{
  "@module": "map_transactions_all",
  "@block": 31229579,
  "@type": "base.mainnet.transaction.v1.Transactions",
  "@data": {
    "transactions": [
      {
        "from": "deaddeaddeaddeaddeaddeaddeaddeaddead0001",
        "to": "4200000000000000000000000000000000000015",
        "hash": "88dc9a999755edd21eddab0b5e70c145cd7de2b3782ac50d70771e4558a937f7"
      },
      {
        "from": "ecb55e5ccfc128a1eca67e48dbe2f299e4366d0e",
        "to": "e1e00b084b71b23741be7f5e01dae04c5383834a",
        "hash": "b455b814651f048e0966a7adeed84e0d68745b657452f2e0948e031330bd96a4"
      }....

`map_transactions_filter`

This module allows you to filter transactions by specifying either to or from value in the parameters.

> substreams run -e base-mainnet.streamingfast.io:443 substreams.yaml map_transactions_filter --params='{"to":"0x4200000000000000000000000000000000000015"}' --start-block 31229579 --stop-block +1

`map_transaction_traces`

This module extracts all transaction traces from a block in their original format.

> substreams run -e base-mainnet.streamingfast.io:443 substreams.yaml map_transaction_traces --start-block 31229579 --stop-block +1
----------- BLOCK #31,229,579 (8384034397f8c979d3c385f87e3d2568a8409a21fb162eb42250d3d3bb54f20c) age=51m36.729194s ---------------
{
  "@module": "map_transaction_traces",
  "@block": 31229579,
  "@type": "base.mainnet.transaction_traces.v1.TransactionTraces",
  "@data": {
    "traces": [
      {
        "to": "0x4200000000000000000000000000000000000015",
        "nonce": "31229581",
        "gasLimit": "1000000",
        "input": "0x098999be000008dd00101c120000000000000001000000006843694700000000015996a2000000000000000000000000000000000000000000000000000000032aceca4800000000000000000000000000000000000000000000000000000000000000010aaab98d5166ac87729ccadd8d709f1a5f06a234dc80376234669eda2bf436f80000000000000000000000005050f69a9786f081509234f1a7f4684b5e5b76c9000000000000000000000000",
        "gasUsed": "46168",
        "hash": "0x88dc9a999755edd21eddab0b5e70c145cd7de2b3782ac50d70771e4558a937f7",
        "from": "0xdeaddeaddeaddeaddeaddeaddeaddeaddead0001",
        "beginOrdinal": "12",
        "endOrdinal": "30",
        "status": "TRANSACTION_STATUS_SUCCEEDED",
        "receipt": {
          "cumulativeGasUsed": "46168",
          "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
        },
        "calls": [
          {
            "index": 1,
            "callType": "CALL_TYPE_CALL",
            "caller": "0xdeaddeaddeaddeaddeaddeaddeaddeaddead0001",
            "address": "0x4200000000000000000000000000000000000015",
            "gasLimit": "977384",
            "gasConsumed": "23552",
            "input": "0x098999be000008dd00101c120000000000000001000000006843694700000000015996a2000000000000000000000000000000000000000000000000000000032aceca4800000000000000000000000000000000000000000000000000000000000000010aaab98d5166ac87729ccadd8d709f1a5f06a234dc80376234669eda2bf436f80000000000000000000000005050f69a9786f081509234f1a7f4684b5e5b76c9000000000000000000000000",
            "executedCode": true,
            "executedCode": true,
            "nonceChanges": [
              {
                "address": "0xdeaddeaddeaddeaddeaddeaddeaddeaddead0001",
                "oldValue": "31229581",
                "newValue": "31229582",
                "ordinal": "14"
              }
            ],
            "gasChanges": [...

This module extracts small bits of block data, and does simple computations over the number of transactions in each block.

`map_block_full`

This module extracts the entire block, as received by the Substreams module.

> substreams run -e base-mainnet.streamingfast.io:443 substreams.yaml map_block_full --start-block 31229579 --stop-block +1

...

----------- BLOCK #99 (c3fa67326430e97a263f8dc0e423d7c6a9f6a244390286b1ba32b80f208b271e) age=17280h9m54.073506s ---------------
{
  "@module": "map_block_full",
  "@block": 99,
  "@type": "sf.ethereum.type.v2.Block",
  "@data": {
    "ver": 4,
    "hash": "0xc3fa67326430e97a263f8dc0e423d7c6a9f6a244390286b1ba32b80f208b271e",
    "number": "99",
    "size": "870",
    "header": {
      "parentHash": "0xa0d20e58a8ec1e43a4eb58c3b2e24d602ff093c4b5bec2815e8abb809dcbf83c",
      "uncleHash": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
      "coinbase": "0x4200000000000000000000000000000000000011",
      "stateRoot": "0xe63d6228a77da20a1f19a604decbd5ce8f1739e24fba9aec52f32ac3ad839c8f",
      "transactionsRoot": "0x387c7f8b287f25fbb3f4e955fcdb98020da4c4aa1002bfa82a4d1feb1f083dfc",
      "receiptRoot": "0x3f71ebd8822765e8146170b0f930f55f753dbb867f55e4e605894016cd32f1e2",
      "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
      "difficulty": {
        "bytes": "0x00"
      },
      "number": "99",
      "gasLimit": "30000000",
      "gasUsed": "46913",
      "timestamp": "2023-06-15T00:39:05Z",
      "mixHash": "0xa2eef66a2a5cf6a3ee6c2da4e6b2cc64ecb77bc057572ef14df0bce5b95b206b",
      "hash": "0xc3fa67326430e97a263f8dc0e423d7c6a9f6a244390286b1ba32b80f208b271e",
      "baseFeePerGas": {
        "bytes": "0x083b038f"
      }
    },
    "transactionTraces": [
      {
        "to": "0x4200000000000000000000000000000000000015",
        "nonce": "98",
        "gasLimit": "1000000",
        "input": "0x015d8eb900000000000000000000000000000000000000000000000000000000010ac03800000000000000000000000000000000000000000000000000000000648a5da3000000000000000000000000000000000000000000000000000000036c55c1de12abd36b698fc225a0a7b895cb61dc803111b48d2cbcc97a45fbeeb9c35e014700000000000000000000000000000000000000000000000000000000000000030000000000000000000000005050f69a9786f081509234f1a7f4684b5e5b76c900000000000000000000000000000000000000000000000000000000000000bc00000000000000000000000000000000000000000000000000000000000a6fe0",
        "gasUsed": "46913",
        "type": 126,
        "hash": "0xda7e89e01361bec751e202c385a71b63d33093041d40f4a419a35c79ea28f39f",
        "from": "0xdeaddeaddeaddeaddeaddeaddeaddeaddead0001",
        "beginOrdinal": "1",
        "endOrdinal": "19",
        "status": "SUCCEEDED",
        "receipt": {
          "cumulativeGasUsed": "46913",
          "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
        },
        "calls": [
          {
            "index": 1,
            "callType": "CALL",
            "caller": "0xdeaddeaddeaddeaddeaddeaddeaddeaddead0001",
            "address": "0x4200000000000000000000000000000000000015",
            "gasLimit": "977072",
            "gasConsumed": "23985",
            "input": "0x015d8eb900000000000000000000000000000000000000000000000000000000010ac03800000000000000000000000000000000000000000000000000000000648a5da3000000000000000000000000000000000000000000000000000000036c55c1de12abd36b698fc225a0a7b895cb61dc803111b48d2cbcc97a45fbeeb9c35e014700000000000000000000000000000000000000000000000000000000000000030000000000000000000000005050f69a9786f081509234f1a7f4684b5e5b76c900000000000000000000000000000000000000000000000000000000000000bc00000000000000000000000000000000000000000000000000000000000a6fe0",
            "executedCode": true,
            "nonceChanges": [
              {
                "address": "0xdeaddeaddeaddeaddeaddeaddeaddeaddead0001",
                "oldValue": "98",
                "newValue": "99",
                "ordinal": "3"
              }
            ],
            "gasChanges": [
              {
                "oldValue": "1000000",
                "newValue": "977072",
                "reason": "REASON_INTRINSIC_GAS",
                "ordinal": "2"
              },
              {
                "newValue": "977072",
                "reason": 24,
                "ordinal": "5"
              },
              {
                "oldValue": "974770",
                "newValue": "974722",
                "reason": "REASON_CALL_DATA_COPY",
                "ordinal": "6"
              },
              {
                "oldValue": "974606",
                "newValue": "972106",
                "reason": "REASON_STATE_COLD_ACCESS",
                "ordinal": "7"
              },
              {
                "oldValue": "974706",
                "newValue": "15189",
                "reason": "REASON_DELEGATE_CALL",
                "ordinal": "8"
              },
              {
                "oldValue": "15189",
                "newValue": "953122",
                "reason": "REASON_REFUND_AFTER_EXECUTION",
                "ordinal": "14"
              },
              {
                "oldValue": "953114",
                "newValue": "953111",
                "reason": "REASON_RETURN_DATA_COPY",
                "ordinal": "15"
              },
              {
                "oldValue": "953087",
                "reason": 25,
                "ordinal": "16"
              },
              {
                "oldValue": "953087",
                "reason": 23,
                "ordinal": "18"
              }
            ],
            "beginOrdinal": "4",
            "endOrdinal": "17"
          },
          {
            "index": 2,
            "parentIndex": 1,
            "depth": 1,
            "callType": "DELEGATE",
            "caller": "0x4200000000000000000000000000000000000015",
            "address": "0xc0d3c0d3c0d3c0d3c0d3c0d3c0d3c0d3c0d30015",
            "gasLimit": "956917",
            "gasConsumed": "18984",
            "input": "0x015d8eb900000000000000000000000000000000000000000000000000000000010ac03800000000000000000000000000000000000000000000000000000000648a5da3000000000000000000000000000000000000000000000000000000036c55c1de12abd36b698fc225a0a7b895cb61dc803111b48d2cbcc97a45fbeeb9c35e014700000000000000000000000000000000000000000000000000000000000000030000000000000000000000005050f69a9786f081509234f1a7f4684b5e5b76c900000000000000000000000000000000000000000000000000000000000000bc00000000000000000000000000000000000000000000000000000000000a6fe0",
            "executedCode": true,
            "storageChanges": [
              {
                "address": "0x4200000000000000000000000000000000000015",
                "key": "0x0000000000000000000000000000000000000000000000000000000000000003",
                "oldValue": "0x0000000000000000000000000000000000000000000000000000000000000002",
                "newValue": "0x0000000000000000000000000000000000000000000000000000000000000003",
                "ordinal": "11"
              }
            ],
            "gasChanges": [
              {
                "newValue": "956917",
                "reason": 24,
                "ordinal": "10"
              },
              {
                "oldValue": "937933",
                "reason": 25,
                "ordinal": "12"
              }
            ],
            "beginOrdinal": "9",
            "endOrdinal": "13"
          }
        ]
      }
    ]
  }
}

Saving Output to Files

To save the output of a substreams module to a file, you can redirect the output to a log file:

> substreams run -e base-mainnet.streamingfast.io:443 substreams.yaml map_transaction_traces --start-block 90 --stop-block +10 > traces.log

For Mac/Linux users, you can also use the script command to capture all terminal output:

> script -q /dev/null substreams run -e base-mainnet.streamingfast.io:443 substreams.yaml map_transaction_traces --start-block 90 --stop-block +10 | tee traces.log

base.mainnet.transaction_traces.v1.TransactionTraces

Inputs

sf.ethereum.type.v2.Block

Protobuf

sf.ethereum.type.v2

Blockmain

sf.ethereum.type.v2.Block

int32ver = 1

Ver represents that data model version of the block, it is used internally by Firehose on Ethereum as a validation that we are reading the correct version.

byteshash = 2

Hash is the block's hash.

uint64number = 3

Number is the block's height at which this block was mined.

uint64size = 4

Size is the size in bytes of the RLP encoding of the block according to Ethereum rules.

BlockHeaderheader = 5

Header contain's the block's header information like its parent hash, the merkel root hash and all other information the form a block.

BlockHeader[]uncles = 6

Uncles represents block produced with a valid solution but were not actually choosen as the canonical block for the given height so they are mostly "forked" blocks.

If the Block has been produced using the Proof of Stake consensus algorithm, this field will actually be always empty.

TransactionTrace[]transaction_traces = 10

TransactionTraces hold the execute trace of all the transactions that were executed in this block. In in there that you will find most of the Ethereum data model.

BalanceChange[]balance_changes = 11

BalanceChanges here is the array of ETH transfer that happened at the block level outside of the normal transaction flow of a block. The best example of this is mining reward for the block mined, the transfer of ETH to the miner happens outside the normal transaction flow of the chain and is recorded as a BalanceChange here since we cannot attached it to any transaction.

CodeChange[]code_changes = 20

CodeChanges here is the array of smart code change that happened that happened at the block level outside of the normal transaction flow of a block. Some Ethereum's fork like BSC and Polygon has some capabilities to upgrade internal smart contracts used usually to track the validator list.

On hard fork, some procedure runs to upgrade the smart contract code to a new version. In those network, a CodeChange for each modified smart contract on upgrade would be present here. Note that this happen rarely, so the vast majority of block will have an empty list here.

AccessTuple

sf.ethereum.type.v2.AccessTuple

AccessTuple represents a list of storage keys for a given contract's address and is used for AccessList construction.

bytesaddress = 1

bytes[]storage_keys = 2

AccountCreation

sf.ethereum.type.v2.AccountCreation

bytesaccount = 1

uint64ordinal = 2

BalanceChange

sf.ethereum.type.v2.BalanceChange

bytesaddress = 1

BigIntold_value = 2

BigIntnew_value = 3

BalanceChange.Reasonreason = 4

uint64ordinal = 5

BigInt

sf.ethereum.type.v2.BigInt

bytesbytes = 1

BlockHeader

sf.ethereum.type.v2.BlockHeader

bytesparent_hash = 1

bytesuncle_hash = 2

Uncle hash of the block, some reference it as sha3Uncles, but sha3`` is badly worded, so we prefer uncle_hash, also referred as ommers` in EIP specification.

If the Block containing this BlockHeader has been produced using the Proof of Stake consensus algorithm, this field will actually be constant and set to 0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347.

bytescoinbase = 3

bytesstate_root = 4

bytestransactions_root = 5

bytesreceipt_root = 6

byteslogs_bloom = 7

BigIntdifficulty = 8

Difficulty is the difficulty of the Proof of Work algorithm that was required to compute a solution.

If the Block containing this BlockHeader has been produced using the Proof of Stake consensus algorithm, this field will actually be constant and set to 0x00.

uint64number = 9

uint64gas_limit = 10

uint64gas_used = 11

Timestamptimestamp = 12

bytesextra_data = 13

ExtraData is free-form bytes included in the block by the "miner". While on Yellow paper of Ethereum this value is maxed to 32 bytes, other consensus algorithm like Clique and some other forks are using bigger values to carry special consensus data.

If the Block containing this BlockHeader has been produced using the Proof of Stake consensus algorithm, this field is strictly enforced to be <= 32 bytes.

bytesmix_hash = 14

MixHash is used to prove, when combined with the nonce that sufficient amount of computation has been achieved and that the solution found is valid.

uint64nonce = 15

Nonce is used to prove, when combined with the mix_hash that sufficient amount of computation has been achieved and that the solution found is valid.

If the Block containing this BlockHeader has been produced using the Proof of Stake consensus algorithm, this field will actually be constant and set to 0.

byteshash = 16

Hash is the hash of the block which is actually the computation:

Keccak256(rlp([ parent_hash, uncle_hash, coinbase, state_root, transactions_root, receipt_root, logs_bloom, difficulty, number, gas_limit, gas_used, timestamp, extra_data, mix_hash, nonce, base_fee_per_gas (to be included, only if London Fork is active) withdrawals_root (to be included, only if Shangai Fork is active) ]))

BigInttotal_difficulty = 17

TotalDifficulty is the sum of all previous blocks difficulty including this block difficulty.

If the Block containing this BlockHeader has been produced using the Proof of Stake consensus algorithm, this field will actually be constant and set to the terminal total difficulty that was required to transition to Proof of Stake algorithm, which varies per network. It is set to 58 750 000 000 000 000 000 000 on Ethereum Mainnet and to 10 790 000 on Ethereum Testnet Goerli.

BigIntbase_fee_per_gas = 18

Base fee per gas according to EIP-1559 (e.g. London Fork) rules, only set if London is present/active on the chain.

byteswithdrawals_root = 19

Withdrawals root hash according to EIP-4895 (e.g. Shangai Fork) rules, only set if Shangai is present/active on the chain.

Uint64NestedArraytx_dependency = 20

BlockRef

sf.ethereum.type.v2.BlockRef

byteshash = 1

uint64number = 2

BlockWithRefs

sf.ethereum.type.v2.BlockWithRefs

BlockWithRefs is a lightweight block, with traces and transactions purged from the block within, and only. It is used in transports to pass block data around.

stringid = 1

Blockblock = 2

TransactionRefstransaction_trace_refs = 3

boolirreversible = 4

Call

sf.ethereum.type.v2.Call

uint32index = 1

uint32parent_index = 2

uint32depth = 3

CallTypecall_type = 4

bytescaller = 5

bytesaddress = 6

BigIntvalue = 7

uint64gas_limit = 8

uint64gas_consumed = 9

boolstatus_failed = 10

In Ethereum, a call can be either:

Successfull, execution passes without any problem encountered
Failed, execution failed, and remaining gas should be consumed
Reverted, execution failed, but only gas consumed so far is billed, remaining gas is refunded

When a call is either failed or reverted, the status_failed field below is set to true. If the status is reverted, then both status_failed and status_reverted are going to be set to true.

stringfailure_reason = 11

Populated when a call either failed or reverted, so when status_failed == true, see above for details about those flags.

boolstatus_reverted = 12

bytesreturn_data = 13

bytesinput = 14

boolexecuted_code = 15

boolsuicide = 16

map<string, string>keccak_preimages = 20

hex representation of the hash -> preimage

StorageChange[]storage_changes = 21

BalanceChange[]balance_changes = 22

NonceChange[]nonce_changes = 24

Log[]logs = 25

CodeChange[]code_changes = 26

GasChange[]gas_changes = 28

boolstate_reverted = 30

This field represents wheter or not the state changes performed by this call were correctly recorded by the blockchain.

On Ethereum, a transaction can record state changes even if some of its inner nested calls failed. This is problematic however since a call will invalidate all its state changes as well as all state changes performed by its child call. This means that even if a call has a status of SUCCESS, the chain might have reverted all the state changes it performed.

  Trx 1
   Call #1 <Failed>
     Call #2 <Execution Success>
     Call #3 <Execution Success>
     |--- Failure here
   Call #4

In the transaction above, while Call #2 and Call #3 would have the status EXECUTED.

If you check all calls and check only state_reverted flag, you might be missing some balance changes and nonce changes. This is because when a full transaction fails in ethereum (e.g. calls.all(x.state_reverted == true)), there is still the transaction fee that are recorded to the chain.

Refer to [TransactionTrace#status] field for more details about the handling you must perform.

uint64begin_ordinal = 31

uint64end_ordinal = 32

AccountCreation[]account_creations = 33

CodeChange

sf.ethereum.type.v2.CodeChange

bytesaddress = 1

bytesold_hash = 2

bytesold_code = 3

bytesnew_hash = 4

bytesnew_code = 5

uint64ordinal = 6

GasChange

sf.ethereum.type.v2.GasChange

The gas change model represents the reason why some gas cost has occurred. The gas is computed per actual op codes. Doing them completely might prove overwhelming in most cases.

Hence, we only index some of them, those that are costy like all the calls one, log events, return data, etc.

uint64old_value = 1

uint64new_value = 2

GasChange.Reasonreason = 3

uint64ordinal = 4

HeaderOnlyBlock

sf.ethereum.type.v2.HeaderOnlyBlock

HeaderOnlyBlock is used to optimally unpack the [Block] structure (note the corresponding message number for the header field) while consuming less memory, when only the header is desired.

WARN: this is a client-side optimization pattern and should be moved in the consuming code.

BlockHeaderheader = 5

Log

sf.ethereum.type.v2.Log

bytesaddress = 1

bytes[]topics = 2

bytesdata = 3

uint32index = 4

Index is the index of the log relative to the transaction. This index is always populated regardless of the state revertion of the the call that emitted this log.

uint32blockIndex = 6

BlockIndex represents the index of the log relative to the Block.

An important notice is that this field will be 0 when the call that emitted the log has been reverted by the chain.

Currently, there is two locations where a Log can be obtained:

block.transaction_traces[].receipt.logs[]
block.transaction_traces[].calls[].logs[]

In the receipt case, the logs will be populated only when the call that emitted them has not been reverted by the chain and when in this position, the blockIndex is always populated correctly.

In the case of calls case, for call where stateReverted == true, the blockIndex value will always be 0.

uint64ordinal = 7

NonceChange

sf.ethereum.type.v2.NonceChange

bytesaddress = 1

uint64old_value = 2

uint64new_value = 3

uint64ordinal = 4

StorageChange

sf.ethereum.type.v2.StorageChange

bytesaddress = 1

byteskey = 2

bytesold_value = 3

bytesnew_value = 4

uint64ordinal = 5

TransactionReceipt

sf.ethereum.type.v2.TransactionReceipt

bytesstate_root = 1

State root is an intermediate state_root hash, computed in-between transactions to make sure you could build a proof and point to state in the middle of a block. Geth client uses PostState + root + PostStateOrStatus`` while Parity used status_code, root...`` this piles hardforks, see (read the EIPs first):

https://github.com/ethereum/EIPs/blob/master/EIPS/eip-658.md

Moreover, the notion of Outcome`` in parity, which segregates the two concepts, which are stored in the same field status_code`` can be computed based on such a hack of the state_root field, following EIP-658.

Before Byzantinium hard fork, this field is always empty.

uint64cumulative_gas_used = 2

byteslogs_bloom = 3

Log[]logs = 4

TransactionRefs

sf.ethereum.type.v2.TransactionRefs

bytes[]hashes = 1

TransactionTrace

sf.ethereum.type.v2.TransactionTrace

bytesto = 1

consensus

uint64nonce = 2

BigIntgas_price = 3

GasPrice represents the effective price that has been paid for each gas unit of this transaction. Over time, the Ethereum rules changes regarding GasPrice field here. Before London fork, the GasPrice was always set to the fixed gas price. After London fork, this value has different meaning depending on the transaction type (see Type field).

In cases where TransactionTrace.Type == TRX_TYPE_LEGACY || TRX_TYPE_ACCESS_LIST, then GasPrice has the same meaning as before the London fork.

In cases where TransactionTrace.Type == TRX_TYPE_DYNAMIC_FEE, then GasPrice is the effective gas price paid for the transaction which is equals to BlockHeader.BaseFeePerGas + TransactionTrace.

uint64gas_limit = 4

GasLimit is the maximum of gas unit the sender of the transaction is willing to consume when perform the EVM execution of the whole transaction

BigIntvalue = 5

Value is the amount of Ether transferred as part of this transaction.

bytesinput = 6

Input data the transaction will receive for execution of EVM.

bytesv = 7

V is the recovery ID value for the signature Y point.

bytesr = 8

R is the signature's X point on the elliptic curve (32 bytes).

bytess = 9

S is the signature's Y point on the elliptic curve (32 bytes).

uint64gas_used = 10

GasUsed is the total amount of gas unit used for the whole execution of the transaction.

BigIntmax_fee_per_gas = 11

MaxFeePerGas is the maximum fee per gas the user is willing to pay for the transaction gas used.

This will is populated only if TransactionTrace.Type == TRX_TYPE_DYNAMIC_FEE which is possible only if Londong fork is active on the chain.

TransactionTrace.Typetype = 12

Type represents the Ethereum transaction type, available only since EIP-2718 & EIP-2930 activation which happened on Berlin fork. The value is always set even for transaction before Berlin fork because those before the fork are still legacy transactions.

BigIntmax_priority_fee_per_gas = 13

MaxPriorityFeePerGas is priority fee per gas the user to pay in extra to the miner on top of the block's base fee.

This will is populated only if TransactionTrace.Type == TRX_TYPE_DYNAMIC_FEE which is possible only if Londong fork is active on the chain.

AccessTuple[]access_list = 14

AcccessList represents the storage access this transaction has agreed to do in which case those storage access cost less gas unit per access.

This will is populated only if TransactionTrace.Type == TRX_TYPE_ACCESS_LIST || TRX_TYPE_DYNAMIC_FEE which is possible only if Berlin (TRX_TYPE_ACCESS_LIST) nor London (TRX_TYPE_DYNAMIC_FEE) fork are active on the chain.

uint32index = 20

meta

byteshash = 21

bytesfrom = 22

bytesreturn_data = 23

bytespublic_key = 24

uint64begin_ordinal = 25

uint64end_ordinal = 26

TransactionTraceStatusstatus = 30

TransactionTraceStatus is the status of the transaction execution and will let you know if the transaction was successful or not.

A successful transaction has been recorded to the blockchain's state for calls in it that were successful. This means it's possible only a subset of the calls were properly recorded, refer to [calls[].state_reverted] field to determine which calls were reverted.

A quirks of the Ethereum protocol is that a transaction FAILED or REVERTED still affects the blockchain's state for some of the state changes. Indeed, in those cases, the transactions fees are still paid to the miner which means there is a balance change for the transaction's emitter (e.g. from) to pay the gas fees, an optional balance change for gas refunded to the transaction's emitter (e.g. from) and a balance change for the miner who received the transaction fees. There is also a nonce change for the transaction's emitter (e.g. from).

This means that to properly record the state changes for a transaction, you need to conditionally procees the transaction's status.

For a SUCCEEDED transaction, you iterate over the calls array and record the state changes for each call for which state_reverted == false (if a transaction succeeded, the call at #0 will always state_reverted == false because it aligns with the transaction).

For a FAILED or REVERTED transaction, you iterate over the root call (e.g. at #0, will always exist) for balance changes you process those where reason is either REASON_GAS_BUY, REASON_GAS_REFUND or REASON_REWARD_TRANSACTION_FEE and for nonce change, still on the root call, you pick the nonce change which the smallest ordinal (if more than one).

TransactionReceiptreceipt = 31

Call[]calls = 32

TransactionTraceWithBlockRef

sf.ethereum.type.v2.TransactionTraceWithBlockRef

TransactionTracetrace = 1

BlockRefblock_ref = 2

Uint64Array

sf.ethereum.type.v2.Uint64Array

uint64[]val = 1

Uint64NestedArray

sf.ethereum.type.v2.Uint64NestedArray

Uint64Array[]val = 1

Reasonenum

sf.ethereum.type.v2.BalanceChange.Reason

REASON_UNKNOWN = 0

REASON_REWARD_MINE_UNCLE = 1

REASON_REWARD_MINE_BLOCK = 2

REASON_DAO_REFUND_CONTRACT = 3

REASON_DAO_ADJUST_BALANCE = 4

REASON_TRANSFER = 5

REASON_GENESIS_BALANCE = 6

REASON_GAS_BUY = 7

REASON_REWARD_TRANSACTION_FEE = 8

REASON_REWARD_FEE_RESET = 14

REASON_GAS_REFUND = 9

REASON_TOUCH_ACCOUNT = 10

REASON_SUICIDE_REFUND = 11

REASON_SUICIDE_WITHDRAW = 13

REASON_CALL_BALANCE_OVERRIDE = 12

REASON_BURN = 15

Used on chain(s) where some Ether burning happens

REASON_WITHDRAWAL = 16

CallTypeenum

sf.ethereum.type.v2.CallType

UNSPECIFIED = 0

CALL = 1

direct? what's the name for Call alone?

CALLCODE = 2

DELEGATE = 3

STATIC = 4

CREATE = 5

create2 ? any other form of calls?

Reasonenum

sf.ethereum.type.v2.GasChange.Reason

REASON_UNKNOWN = 0

REASON_CALL = 1

REASON_CALL_CODE = 2

REASON_CALL_DATA_COPY = 3

REASON_CODE_COPY = 4

REASON_CODE_STORAGE = 5

REASON_CONTRACT_CREATION = 6

REASON_CONTRACT_CREATION2 = 7

REASON_DELEGATE_CALL = 8

REASON_EVENT_LOG = 9

REASON_EXT_CODE_COPY = 10

REASON_FAILED_EXECUTION = 11

REASON_INTRINSIC_GAS = 12

REASON_PRECOMPILED_CONTRACT = 13

REASON_REFUND_AFTER_EXECUTION = 14

REASON_RETURN = 15

REASON_RETURN_DATA_COPY = 16

REASON_REVERT = 17

REASON_SELF_DESTRUCT = 18

REASON_STATIC_CALL = 19

REASON_STATE_COLD_ACCESS = 20

Added in Berlin fork (Geth 1.10+)

Typeenum

sf.ethereum.type.v2.TransactionTrace.Type

TRX_TYPE_LEGACY = 0

All transactions that ever existed prior Berlin fork before EIP-2718 was implemented.

TRX_TYPE_ACCESS_LIST = 1

Transaction that specicy an access list of contract/storage_keys that is going to be used in this transaction.

Added in Berlin fork (EIP-2930).

TRX_TYPE_DYNAMIC_FEE = 2

Transaction that specifis an access list just like TRX_TYPE_ACCESS_LIST but in addition defines the max base gas gee and max priority gas fee to pay for this transaction. Transaction's of those type are executed against EIP-1559 rules which dictates a dynamic gas cost based on the congestion of the network.

TransactionTraceStatusenum

sf.ethereum.type.v2.TransactionTraceStatus

UNKNOWN = 0

SUCCEEDED = 1

FAILED = 2

REVERTED = 3

base.mainnet.block_meta.v1

Metamain

base.mainnet.block_meta.v1.Meta

stringblock_hash = 1

uint64block_number = 2

Timestampblock_timestamp = 3

uint64transactions_len = 4

stringparent_hash = 5

base.mainnet.block_metadata.v1

Metadatamain

base.mainnet.block_metadata.v1.Metadata

stringblock_hash = 1

uint64block_number = 2

Timestampblock_timestamp = 3

uint64transactions_len = 4

stringparent_hash = 5

uint64withdrawals_len = 6

base.mainnet.transaction.v1

Transactionsmain

base.mainnet.transaction.v1.Transactions

Transaction[]transactions = 1

Transaction

base.mainnet.transaction.v1.Transaction

stringfrom = 1

stringto = 2

stringhash = 3

base.mainnet.transaction_traces.v1

TransactionTracesmain

base.mainnet.transaction_traces.v1.TransactionTraces

TransactionTrace[]traces = 1

AccessTuple

base.mainnet.transaction_traces.v1.AccessTuple

bytesaddress = 1

bytes[]storage_keys = 2

AccountCreation

base.mainnet.transaction_traces.v1.AccountCreation

bytesaccount = 1

uint64ordinal = 2

BalanceChange

base.mainnet.transaction_traces.v1.BalanceChange

bytesaddress = 1

BigIntold_value = 2

BigIntnew_value = 3

BalanceChange.BalanceChangeReasonreason = 4

uint64ordinal = 5

BigInt

base.mainnet.transaction_traces.v1.BigInt

bytesbytes = 1

Call

base.mainnet.transaction_traces.v1.Call

uint32index = 1

uint32parent_index = 2

uint32depth = 3

CallTypecall_type = 4

bytescaller = 5

bytesaddress = 6

BigIntvalue = 7

uint64gas_limit = 8

uint64gas_consumed = 9

bytesreturn_data = 10

bytesinput = 11

boolexecuted_code = 12

boolsuicide = 13

map<string, string>keccak_preimages = 14

StorageChange[]storage_changes = 15

BalanceChange[]balance_changes = 16

NonceChange[]nonce_changes = 17

Log[]logs = 18

CodeChange[]code_changes = 19

GasChange[]gas_changes = 20

boolstatus_failed = 21

boolstatus_reverted = 22

stringfailure_reason = 23

boolstate_reverted = 24

uint64begin_ordinal = 25

uint64end_ordinal = 26

AccountCreation[]account_creations = 27

CodeChange

base.mainnet.transaction_traces.v1.CodeChange

bytesaddress = 1

bytesold_hash = 2

bytesold_code = 3

bytesnew_hash = 4

bytesnew_code = 5

uint64ordinal = 6

GasChange

base.mainnet.transaction_traces.v1.GasChange

uint64old_value = 1

uint64new_value = 2

GasChange.GasChangeReasonreason = 3

uint64ordinal = 4

Log

base.mainnet.transaction_traces.v1.Log

bytesaddress = 1

bytes[]topics = 2

bytesdata = 3

uint32index = 4

uint32block_index = 5

uint64ordinal = 6

NonceChange

base.mainnet.transaction_traces.v1.NonceChange

bytesaddress = 1

uint64old_value = 2

uint64new_value = 3

uint64ordinal = 4

StorageChange

base.mainnet.transaction_traces.v1.StorageChange

bytesaddress = 1

byteskey = 2

bytesold_value = 3

bytesnew_value = 4

uint64ordinal = 5

TransactionReceipt

base.mainnet.transaction_traces.v1.TransactionReceipt

bytesstate_root = 1

uint64cumulative_gas_used = 2

byteslogs_bloom = 3

Log[]logs = 4

TransactionTrace

base.mainnet.transaction_traces.v1.TransactionTrace

bytesto = 1

uint64nonce = 2

BigIntgas_price = 3

uint64gas_limit = 4

BigIntvalue = 5

bytesinput = 6

bytesv = 7

bytesr = 8

bytess = 9

uint64gas_used = 10

TransactionTypetype = 11

AccessTuple[]access_list = 12

BigIntmax_fee_per_gas = 13

BigIntmax_priority_fee_per_gas = 14

uint32index = 15

byteshash = 16

bytesfrom = 17

bytesreturn_data = 18

bytespublic_key = 19

uint64begin_ordinal = 20

uint64end_ordinal = 21

TransactionStatusstatus = 22

TransactionReceiptreceipt = 23

Call[]calls = 24

BalanceChangeReasonenum

base.mainnet.transaction_traces.v1.BalanceChange.BalanceChangeReason

BALANCE_CHANGE_REASON_UNKNOWN = 0

BALANCE_CHANGE_REASON_REWARD_MINE_UNCLE = 1

BALANCE_CHANGE_REASON_REWARD_MINE_BLOCK = 2

BALANCE_CHANGE_REASON_DAO_REFUND_CONTRACT = 3

BALANCE_CHANGE_REASON_DAO_ADJUST_BALANCE = 4

BALANCE_CHANGE_REASON_TRANSFER = 5

BALANCE_CHANGE_REASON_GENESIS_BALANCE = 6

BALANCE_CHANGE_REASON_GAS_BUY = 7

BALANCE_CHANGE_REASON_REWARD_TRANSACTION_FEE = 8

BALANCE_CHANGE_REASON_REWARD_FEE_RESET = 9

BALANCE_CHANGE_REASON_GAS_REFUND = 10

BALANCE_CHANGE_REASON_TOUCH_ACCOUNT = 11

BALANCE_CHANGE_REASON_SUICIDE_REFUND = 12

BALANCE_CHANGE_REASON_SUICIDE_WITHDRAW = 13

BALANCE_CHANGE_REASON_CALL_BALANCE_OVERRIDE = 14

BALANCE_CHANGE_REASON_BURN = 15

BALANCE_CHANGE_REASON_WITHDRAWAL = 16

CallTypeenum

base.mainnet.transaction_traces.v1.CallType

CALL_TYPE_UNSPECIFIED = 0

CALL_TYPE_CALL = 1

CALL_TYPE_CALLCODE = 2

CALL_TYPE_DELEGATE = 3

CALL_TYPE_STATIC = 4

CALL_TYPE_CREATE = 5

GasChangeReasonenum

base.mainnet.transaction_traces.v1.GasChange.GasChangeReason

GAS_CHANGE_REASON_UNKNOWN = 0

GAS_CHANGE_REASON_CALL = 1

GAS_CHANGE_REASON_CALL_CODE = 2

GAS_CHANGE_REASON_CALL_DATA_COPY = 3

GAS_CHANGE_REASON_CODE_COPY = 4

GAS_CHANGE_REASON_CODE_STORAGE = 5

GAS_CHANGE_REASON_CONTRACT_CREATION = 6

GAS_CHANGE_REASON_CONTRACT_CREATION2 = 7

GAS_CHANGE_REASON_DELEGATE_CALL = 8

GAS_CHANGE_REASON_EVENT_LOG = 9

GAS_CHANGE_REASON_EXT_CODE_COPY = 10

GAS_CHANGE_REASON_FAILED_EXECUTION = 11

GAS_CHANGE_REASON_INTRINSIC_GAS = 12

GAS_CHANGE_REASON_PRECOMPILED_CONTRACT = 13

GAS_CHANGE_REASON_REFUND_AFTER_EXECUTION = 14

GAS_CHANGE_REASON_RETURN = 15

GAS_CHANGE_REASON_RETURN_DATA_COPY = 16

GAS_CHANGE_REASON_REVERT = 17

GAS_CHANGE_REASON_SELF_DESTRUCT = 18

GAS_CHANGE_REASON_STATIC_CALL = 19

GAS_CHANGE_REASON_STATE_COLD_ACCESS = 20

TransactionStatusenum

base.mainnet.transaction_traces.v1.TransactionStatus

TRANSACTION_STATUS_UNKNOWN = 0

TRANSACTION_STATUS_SUCCEEDED = 1

TRANSACTION_STATUS_FAILED = 2

TRANSACTION_STATUS_REVERTED = 3

TransactionTypeenum

base.mainnet.transaction_traces.v1.TransactionType

TRANSACTION_TYPE_LEGACY = 0

TRANSACTION_TYPE_ACCESS_LIST = 1

TRANSACTION_TYPE_DYNAMIC_FEE = 2

Show 4 dependencies

sf.ethereum.substreams.v1

RpcCall

sf.ethereum.substreams.v1.RpcCall

bytesto_addr = 1

bytesdata = 2

RpcCalls

sf.ethereum.substreams.v1.RpcCalls

RpcCall[]calls = 1

RpcResponse

sf.ethereum.substreams.v1.RpcResponse

bytesraw = 1

boolfailed = 2

RpcResponses

sf.ethereum.substreams.v1.RpcResponses

RpcResponse[]responses = 1