cmd/evm: add more docs for t8n, t9n, and b11r #26111
Conversation
| // Map of address to account definition. | ||
| type Alloc map[common.Address]Account | ||
|
|
||
| // Genesis account. Each field is optional. | ||
| type Account struct { | ||
| Code []byte `json:"code"` | ||
| Storage map[common.Hash]common.Hash `json:"storage"` | ||
| Balance *big.Int `json:"balance"` | ||
| Nonce uint64 `json:"nonce"` | ||
| SecretKey []byte `json:"secretKey"` | ||
| } |
There was a problem hiding this comment.
For those of us that don't speak go as fluently, how do these get translated into JSON? Especially the big.Int fields.
There was a problem hiding this comment.
I added a note on encoding at the bottom, but basically we use a intermediary type math.HexOrDecimalN which can decode json strings that are either hex format or decimal format.
|
A little-known and, to be honest, pretty hidden fact, is that the README.md here can be/is fully generated from the script That way, if the input or output changes, those changes will be reflected in the documentation, as long as we just remember to regenerate it from time to time. |
|
And also, another idea I had was that the exact same script, when executed against a different but spec-compliant I always wanted the framework around |
|
Ah shoot didn't realize that existed! I was thinking of doing something similar, but decided to just do it manually to save time 😅. Okay, let me look into that and update. |
| The encoding of values for `evm` utility attempts to be relatively flexible. It | ||
| generally supports hex-encoded or decimal-encoded numeric values, and | ||
| hex-encoded byte values (like `common.Address`, `common.Hash`, etc). When in | ||
| doubt, the [`execution-apis`](https://github.com/ethereum/execution-apis) way |
There was a problem hiding this comment.
Do you know why the receipt in the output of evm t8n is different to the receipt in the output of eth_getTransactionReceipt?
For a simple transfer, I'm getting:
evm t8n
"logs": null,
"contractAddress": "0x0000000000000000000000000000000000000000",
eth_getTransactionReceipt:
"logs":[],
"contractAddress":null,
For eth_getTransactionReceipt, I tried a local erigon node and alchemy.io. I don't have a geth node to try against. execution-apis would consider the evm t8n output to be invalid.
There was a problem hiding this comment.
I don't think there is a particular reason, it's just that the way we marshal the receipt for RPC uses a custom marshaller in internal/ethapi/api.go#L1626 and here we just use the default golang json marshaller.
| * transaction tool (t9n) : a transaction validation utility | ||
| * block builder tool (b11r): a block assembler utility | ||
|
|
||
| ## State transition tool (t8n) |
There was a problem hiding this comment.
You should add a discussion of how t8n handles invalid transactions. I found the fact it skips them and keeps going somewhat surprising.
There was a problem hiding this comment.
I think this choice of behavior is because t8n is a filler tool and if you ask to fill and invalid state transition for a test, it will do the best it can (just in case the client it eventually tests against also fails to process the tx, but somehow doesn't cause the whole block to fail).
| @@ -45,27 +54,175 @@ Command line params that has to be supported are | |||
|
|
|||
| ``` | |||
|
|
|||
| ### Error codes and output | |||
| #### Objects | |||
There was a problem hiding this comment.
You haven't described the rejected section for transactions that are rejected. Also are other implementations required the reproduce the error strings exactly? If so, we need a comprehensive list of possible strings.
There was a problem hiding this comment.
As long as the tx is correctly rejected, that is enough I think. If you want a (I think) a full list of possible errors, see core/errors.go.
|
I've incorporated half of these changes into #26314, since I had to update the script and some docs anyway. Will keep this PR open until we've migrated the rest of the content too. |
|
Closing in favour of #26385 |
The EELS team is getting ready to implement
t8nandb11rso they can join in on the test-filling-fun. I tried to include some more information about that actual structure of the different objects used as input and returned as output from the various tools. I also wanted to make a note of where to look for conformance tests as other clients look to implement theevmutility.