# ~~Witness~~ Circuit inputs Generation flow (WIP)

NOTE: We start with a block number but always try to query by block hash. Whenever we can't query by block hash, we query by block number and make sure the result matches with the blockData queried by block hash to avoid reading uncle blocks caused by a reorg.

- 1. Pick a block hash $bh_i$ (probably from a block number $bn_i$)
- 2. RPC get block data for block $bh_i$ as blockData
- 3. RPC get block data for block blockData.parentHash as blockData_prev
- 4. for tx in blockData.transactions
- 4.1. RPC get tx data as txData
- 4.2. RPC get tx receipt as txReceipt
- 4.3. RPC get tx EVM trace as txTrace
- 5. First pass on parsing EVM trace
- 5.1. For each tx in blockData.transactions
- Start a new CallContext from tx
- for step in trace.Steps
- Store MemoryOps
- Store StackOps
- Store StorageOps
- 5.2 For all ops in all txs, sort:
- StorageOps by (address, key, gc)
- MemoryOps by (address, gc)
- StackOps by (address, gc)
- 6. Query and build partial Merkle Patricia Tree
- 6.1. For each (address, key) in storage_keys_read | storage_keys_written
- 6.1.1. RPC get storage proof at block $bn_{i-1}$ as storageProof
- 6.1.2. assert(hash(proof.accountProof[0]) == blockData_prev.stateRoot)
- 6.2 For each (address, key) in storage_keys_written
- 6.2.1 RPC get storage proof at block $bn_{i-1}$ as storageProof
- 6.1.2. assert(hash(proof.accountProof[0]) == blockData.stateRoot)
- 6.3 Build a partial MPT from all proofs at $bn_{i-1}$ and new nodes found in proofs at $bn_i$ (via preimage db insertion).
- 7. Second pass on parsing EVM trace. Sort StorageOP by (addr, key, gc)
- For each SLOAD step
- get a proof from the partial MPT and set StorageOp.proof
- For each SSTORE step
- query key from partial MPT and set StorageOp.value_prev
- get proof and set StorageOp.proof_prev
- apply update to the partial MPT
- get proof and set StorageOp.proof

# ~~Witness~~ Circuit inputs layout
- steps `Vec<exec_step::ExecutionSteop>` - ExecutionStep
- memory: `[u8]``
- stack: `[word]`
- instruction: `OpcodeId`
- gas_info: { gas: `u64`, gas_cost: `u64` }
- depth: `u8`
- pc: `usize`
- gc: `usize`
- bus_mapping_instance: `[usize]` Vec of index in container
- block_ctants `exec_trace::BlockConstants`
- hash: `word`
- coinbase: `F`
- timestamp: `F`
- number: `F`
- difficulty: `F`
- gas_limit: `F`
- chain_id: `F`
- base_fee: `F`
- container `Vec<Operation>` - enum Operation
- StackOp `operation::StackOp` { rw, gc, addr, value}
- MemoryOp `operation::MemoryOp` { rw, gc, addr, value}
- StorageOp `operation::StorageOp` { rw, gc, addr, key, value, value_prev, proof, proobf_prev }

# geth RPC API calls

## 2. Get Block data
method: `eth_getBlockByHash`

params: [
   blockHash,
   true
]

{
    "difficulty": "0x4ea3f27bc",
    "extraData": "0x476574682f4c5649562f76312e302e302f6c696e75782f676f312e342e32",
    "gasLimit": "0x1388",
    "gasUsed": "0x0",
    "hash": "0xdc0818cf78f21a8e70579cb46a43643f78291264dda342ae31049421c82d21ae",
    "logsBloom": "0x0000000000000000...",
    "miner": "0xbb7b8287f3f0a933474a79eae42cbca977791171",
    "mixHash": "0x4fffe9ae21f1c9e15207b1f472d5bbdd68c9595d461666602f2be20daf5e7843",
    "nonce": "0x689056015818adbe",
    "number": "0x1b4",
    "parentHash": "0xe99e022112df268087ea7eafaf4790497fd21dbeeb6bd7a1721df161a6657a54",
    "receiptsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
    "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
    "size": "0x220",
    "stateRoot": "0xddc8b0234c2e0cad087c8b389aa7ef01f7d79b2570bccb77ce48648aa61c904d",
    "timestamp": "0x55ba467c",
    "totalDifficulty": "0x78ed983323d",
    "transactions": [
      "0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b"
      ...
    ],
    "transactionsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
    "uncles": [
    ]
}

# 3.1 get tx data
method: `eth_getTransactionByHash`

params: [ txHash ]

{
    "blockHash":"0x1d59ff54b1eb26b013ce3cb5fc9dab3705b415a67127a003c3e61eb445bb8df2",
    "blockNumber":"0x5daf3b", // 6139707
    "from":"0xa7d9ddbe1f17865597fbd27ec712455208b6b76d",
    "gas":"0xc350", // 50000
    "gasPrice":"0x4a817c800", // 20000000000
    "hash":"0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b",
    "input":"0x68656c6c6f21",
    "nonce":"0x15", // 21
    "to":"0xf02c1c8e6114b1dbe8937a39260b5b0a374432bb",
    "transactionIndex":"0x41", // 65
    "value":"0xf3dbb76162000", // 4290000000000000
    "v":"0x25", // 37
    "r":"0x1b5e176d927f8e9ab405058b2d2457392da3e20f328b16ddabcebc33eaac5fea",
    "s":"0x4ba69724e8f69de52f0125ad8b3c5c2cef33019bac3249e2c0a2192766d1721c"
}

## 3.2 get tx receipt
method: ` eth_getTransactionReceipt`

params: [ txHash ]

{
    "blockHash": "0x48d844cbd104d3ff198ba31f43dd8e92f9f446197d4cb9f6f75d7c0c59db0c74",
    "blockNumber": "0x907f46",
    "contractAddress": null,
    "cumulativeGasUsed": "0x6063bc",
    "effectiveGasPrice": "0x3b9aca0b",
    "from": "0x3895d913a9a231d2b215f402c528511b569c676d",
    "gasUsed": "0x8682",
    "logs": [
      {
        "address": "0xb2f5961715bb60fc67004a8ee12d2adfe4ed9156",
        "blockHash": "0x48d844cbd104d3ff198ba31f43dd8e92f9f446197d4cb9f6f75d7c0c59db0c74",
        "blockNumber": "0x907f46",
        "data": "0x000000000000000000000000000000000000000000000000000000000000004...",
        "logIndex": "0x43",
        "removed": false,
        "topics": [
          "0xb20e0717219840fd5684a80bec782e8babb56ea224f677561b791a61192605c1"
        ],
        "transactionHash": "0xeea746adff03283aa8d1296ed23931e000845549912dc8e28bb09affe55f4410",
        "transactionIndex": "0x23"
      }
    ],
    "logsBloom": "0x0000000000000000000000000000000000000000000000000000000000000002...",
    "status": "0x1",
    "to": "0xb2f5961715bb60fc67004a8ee12d2adfe4ed9156",
    "transactionHash": "0xeea746adff03283aa8d1296ed23931e000845549912dc8e28bb09affe55f4410",
    "transactionIndex": "0x23",
    "type": "0x0"
}

## 3.3 get tx EVM trace
method: `debug_traceTransaction`

params: [ txHash ]

{
    "gas": 26809,
    "failed": false,
    "returnValue": "",
    "structLogs": [
      {
        "pc": 0,
        "op": "PUSH1",
        "gas": 5605,
        "gasCost": 3,
        "depth": 1,
        "stack": []
      },
      {
        "pc": 2,
        "op": "PUSH1",
        "gas": 5602,
        "gasCost": 3,
        "depth": 1,
        "stack": [
          "0x80"
        ]
      },
      {
        "pc": 4,
        "op": "MSTORE",
        "gas": 5599,
        "gasCost": 12,
        "depth": 1,
        "stack": [
          "0x80",
          "0x40"
        ]
      }
    ]
}

## 5.* get storage proof at block $bn_{i-1}$
method: `eth_getProof`

params: [
   addr,
   [key0, key1, ...],
   blockNumber
]

{
    "accountProof": [
      "0xf90211a0e204bbdc40d04df778daf50ec70ff980640e2f78270577d3709c16720a1a1afea071b9a28a34c37e0e4888e5d166b4e6dd873d199341d5a7f8fb262f7bddf2ad15a007cc58dc6d09244877a96846c02d53ce2cb642dcf7237b7d04047b459077b138a0295b7ec7ad1175db387496a7a04c9d9d8a8a569b6cfa14e3a6cb6d511e6f7383a0e7f96594730ff2762b4b8b2f1cec35a5d0ad8074c765531a47aaaff93842e1baa0abac2527b2c64835ee6efa6051950f7f294871a0ecf376868be2ea421c855560a0e88b33fbdb64fa2fb2af4099d340717b0a0c911f54280c36654c97883ac49471a04d6d91f1b6172b62b46b43226dea20c47540e4f8e26afb3ca9c3d0bf3a93e035a04a7c6f296cb9e3c209d701e0bd3dd01d2c033730cb099c80dd0f1feb2b2e7172a0285a9a14dd26bc004eab2237c61bcaf1f8ed35a649d711d089efad2d6fd97db4a0555acd2ff345110cb197287d43b9777cf98b6b8615303e72a25f236be5ab58b6a0f44135b950efe692c823e29d6b9984a2f4c9fab3df82fb6f69987f711cf31f7fa069b861cf374304bf0a561c9c43d78899afa5e9637a8ab71ca44f1a4031763773a06abdc15ad307509dc833a8ececffef0c918edd47c602d016308499604c315c86a070fd3f28745c37aa15d1a4394e432016e822c46c7374b4b153fef17b7eb6004fa0741d0bb6fc3cde08af3d2cc305307bc26a54fe2aa0ea913808fe38754ec6961680",
      "0xf90211a08c5128deb933abdd169d8e46efd4d16eb96520db5613438367d385f28c6ef32da0dd1954a5943ab3c6ea8c1f14e8b9ae61fce66cf7d0fabea06aa937d6e545f210a05babdd7bc081fc9e2ae2533e14dfbef981d887cd8dddeb213e5f1dc6add4de75a09fdc897878e90610df7720e93632cf288f269e55ab376694474279f7921d0e34a0772d748251df2ca9244521168299ef2f1300fd065248092b57f957ba64b339d8a01be1e4d466d27551b59eacb26652d9137c9d743010996400fdb77b340014107da0aeb1ebba5b8e3fce2db6545748a6a23655d6273915790ad61f21ca2e851f0979a0e124378ecf168b122817c7e7bcc46e182af4a9adfe003016b99f7a26d1eada28a008588df99badc3627ebb1add5d9730e1dbb6b30cbe8cfb3a006584dabfedae3ca0e102266b180b5c42c3d0fa0f26338035d86dd7b5d893001383e67efa6800bd07a01cc7ee30ed255824a22974554c45e7d2f27e6360e3378d0e4cc5c858bf598d6fa05a61c7a4c8765f17ff2f867da711dc238f7c3bdebe73670647a55bcd056af6fca0b920e34a54ead29fc1f090ed37148d91793c75fd824d0df80afb9ab4e8e5f01aa091f629e2112b03fa2d5e38af716a4a25b0ca3f637d3a141ad8739136fb482656a0736e623a6f289257320ab4ed1cf4c86ba17311960990a16fc81fdd5c9e9ff3c4a07e571f32c9742db162b5130d78125393406ba74629bfabb8f191d64bcdab854680",
      "0xf90211a0da43c0fc2d1eb154eefb11862eff7e6138a87568f0d07fa2607542e7326fd2e5a0b3a44e79c34fef7bf4f0f19ed23ed689534b431e6126ab38142b96b2bf2bcf57a08283cc6bb2ca5285710bca19f0d60bc10020056b6a0f3adcc59cf58b17d9a9dca0a1e5186b825294c5f6604d1114a4c5e3bab7bb0885619b952f1601dcea5bfc34a0d4fd5ad026fac8acddbb31f87abab5766fe9c160f74a7c17ef3ab054837a1646a0d991b95e2f62b359019b2c3a11ab4ef0b0b881307260d9c42d0441d3ed5a5d3da0d5d266011291cbe39b224de138aaa6cb582996ecd32fba2d6f8c231b882de419a08acc4e7417cc7cb7c4409c8e99766d179ae3463abf8162c790c3cba1f24fa50aa06a18a461f017e3329b95440bfa80b80e8b3e695d726135125999729f0797b459a06e97d597ba6280536ec555b084f3680cd216b3cee1f6d885780797f056c30e23a0fefd12194978e91f2d7419a3ed995364a1a40ac9a9f04a65316369de580b0e40a0d4cb1f347f2371bc5f06ed65e025c56a339b8131a061df2c09bbf26f2164a50ca0ffb121605aad4d00ca702c99b5e3a8da7663f43d0a9e53ec6c37d104c4660e99a00f8a0d51ba062f0477233b51a2625946dba63236a6379d958a6444917ae51542a01a00f115c9824e872d20960dc9cc4bc25a581da5b52d572adb0601a59533c160a028e285723d988093d33cbf85a177603c99428b6bcc43b107c53d744c0617cc1b80",
      "0xf90211a089715fd1dff2741ca793e28272099a3921a3ddb3a7ccecca376b332ca5c8f2eca0d19e78f616d10b9c9d89337fde490f0b7f23a64eda20a40ff8d331abb4c9b3faa029937b2d224b3034f232601ac26db6d7a68124de9a0722720b761a58fb7f1255a0a6fdd2ca5b1ae11b649e2ebf9860491f49367378d308ba0e6617bfea47939bb3a065ff3b08b5b7f9e7e6b81ebfe65d0910163400dc68982f707b5fe1033ca3eaa2a0654a1387293908e4263f04dd21adf87d37a76c79aa60e181a2209686eb488f04a0cc61acb4b4a23f322dc7fb043a97a0be7d06039f5db77aa6ae3893152a6227d6a04fb9276a6d009e3833290a35980f98c989e88192607702a32c7a0db8a22aa93fa02eafb47855e37152eba3687abb8c56742d14a35ecb97628439a02e83ef57a208a0fabc3cbe8db7ee9e6f48da71e7ffcae0dca4d038e7a44f4927b8639efe7bb2cda033d0f62ddabcff4fc79d0cbfebc528f34130b200ec88bbcf1509aa6d7edeb88fa0a2eb9841481fbb7be2876c7a09ef35ddebefdd5f2824acbb54ffcd35bc0c4045a095952bb67168788b79b155895a675367d31799d9d6c27b58d475471f99ed8f50a0ad1af868d5308616ac545cbd58993ccbba5cc01808b467e0490f1fd4e7cfe378a0115483b437ea2a007ef8d9d34a0310f58b16c4f49a12e303e18ab03d6b346254a0266cfc2ccd71bedf6e0c23b4cf85d5682007c180694c5febe1680402ce1e45ab80",
      "0xf90211a09cc5d18ad4aed5c63f07c5d0ddf7b0db8a45174f6f4af4010e893037fb48bf1ca0f2b291df0d6737527c404573c627fa60081bf45d4c61d82ade8f7474c5b08795a00a7705b89928ab0417a1b14e117fd3174986edab7bf09acd9c493e57b3776328a02c889bab6c67dddb52ab67228124e7e62bfacaa36d8973cb0e28c361486b88c2a0a40abc56fb1f661adfbe9d6ef29f71ac665d47fb961763e325074dee74d11c69a0a5afdf043af5d16d8d7942bd0fd11e922f85294f1be2007ed56615baad783f12a00e3473b36d754f8c2493a78f75c4916c4959382ae19a6b6fe21b2776f5b67c53a06abb6caccdcbd050b6270f2d912d5c3e4b77a07b63c12f5f4520959e37b986eaa01cc5e709308d2d9db9f056871218ebf228a47ac95dc9c76b192d9fe46740a43aa0cbd188184dc791b9c4f6bd99cd1150cf33726aa3ec106aed309bf4ec2d9cc67ea03009cac510c4cdd0f582240c8d12c3cc5f2f04958a1c6b64b8f2e699a67afd88a0ff0b74ae0c7bf47d3929be5c7ebcf157f0a834b1a43c3c3194a9748193585bd2a01f54d92fa3d5fbae3a437ae3db7409c0619356f05ff64ad07d00be0d751f8168a0d8b0fe914a407e21ee0da143b1e3487d8b390f92d13bf5140d821165fefa7581a052d218e89039d4b46e4784d7e9ecd5e53a508eafda8da3ec4dc8bd0e29780efca091f9670f1fdb35d62f15bdecaa012e822a8d7596544e57e88672eca052820bd480",
      "0xf90171a0d0765d7952a95907335547b4a3324784d501d426b6972ab05317e0b8ac39a70fa0d263a472e39d821e25147083ce92c8b4eddaea73fe66c329a1cfc50b30770513a0a6f3c75c13438692c2b10927564ac4530798e6cec9cb56660c9ba0a9ece16552a054e33569036b2899020e4cb8258f70c32c9f1c27c49f079de6bffd8a7f4af2918080a08808c07d98471b6122c6afe88b2c364a5bd5a67d10bedd163f631db2d6005c8da097fae672c2fb3478a78ae7dde1bf32f7aa20693eb8ea374b7e9311e56d83a05ba0978d588f8ab09634bbb541c15fcc3dc341ea30f186a4edc8cf63fb60a491c9afa0558a4c1f9e3794b9b8db038c896d0be8e82bcd6809c3b819742e0dfbddd72b51a0ab3e788008800383b5ae96c35f390b77b8bf8aa3c318cc4d59378a81a63f96cca08b4872825c26329c7180faa1288260127b20006e239c122e47abb356caa0435a808080a0ec12f380054c34b6a2b8cfb76093c7eec1e6ca4eb1ff088a9cf1ab0406efa7a180",
      "0xe214a00c6aa2e5acac2204c0dd944457aaa9ca013cc5f66697c20bedf5f8675d3e1264",
      "0xf851808080a0f6d02213991df51b8b57876fdc9bece9d92f80840306b9016ecfced50e1b7d7280a0250ac59ce757061351a3899371b1c4f41c51204afc527be944fac4f0e51a54888080808080808080808080",
      "0xf8669d209c3233fbde70adb31c28e9cd2999522adae06aebb24e4d136c1bcacdb846f8440180a07682de052b2d11bd79be673aca6e8cda4cc6d14a82c761733da52def5b4be679a0fe462bb5c2ff1514e2d76e7756ced63bbcb42727c7c05c82a5e40f8f3150015b"
    ],
    "address": "0x133724b41312dfeb3976fec0fdb33eca6cdc4356",
    "balance": "0x0",
    "codeHash": "0xfe462bb5c2ff1514e2d76e7756ced63bbcb42727c7c05c82a5e40f8f3150015b",
    "nonce": "0x1",
    "storageHash": "0x7682de052b2d11bd79be673aca6e8cda4cc6d14a82c761733da52def5b4be679",
    "storageProof": [
      {
        "key": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "proof": [
          "0xf8f1a0df25cace0a65b66d050694345186cc5f6554d3424cbba5a690987a8a394f9ab680a0c9fadd6f088560399d211c7a06ccd8916f130543abf85df86d90447ea26a299980a092f3e83595f6bc1c0bef09ef33b0d7a98f4bd278e95f30f357f7dc91e2c9dda2808080a044776904dfdbb18b6a46dc2ff9aea5b93098c0a259168237463996059e38e7688080a0f4984a11f61a2921456141df88de6e1a710d28681b91af794c5a721e47839cd7a064cf0b3e24ee8dae765a1db1d20e7256f5bb66f58dac6360bad0917fe309ffd38080a027af6c3a525972324bc5a04d755578e7d4754e0c238070075e87d1fc76bcabb480",
          "0xf7a0390decd9548b62a8d60345a988386fc84ba6bc95484008f6362f93160ef3e5639594c468cf662ea8deb47c886e170060cbe76960a04c"
        ],
        "value": "0xc468cf662ea8deb47c886e170060cbe76960a04c"
      },
      {
        "key": "0x0000000000000000000000000000000000000000000000000000000000000001",
        "proof": [
          "0xf8f1a0df25cace0a65b66d050694345186cc5f6554d3424cbba5a690987a8a394f9ab680a0c9fadd6f088560399d211c7a06ccd8916f130543abf85df86d90447ea26a299980a092f3e83595f6bc1c0bef09ef33b0d7a98f4bd278e95f30f357f7dc91e2c9dda2808080a044776904dfdbb18b6a46dc2ff9aea5b93098c0a259168237463996059e38e7688080a0f4984a11f61a2921456141df88de6e1a710d28681b91af794c5a721e47839cd7a064cf0b3e24ee8dae765a1db1d20e7256f5bb66f58dac6360bad0917fe309ffd38080a027af6c3a525972324bc5a04d755578e7d4754e0c238070075e87d1fc76bcabb480",
          "0xe2a0310e2d527612073b26eecdfd717e6a320cf44b4afac2b0732d9fcbe2b7fa0cf601"
        ],
        "value": "0x1"
      }
    ]
}