Skip to content

Commit efb4dca

Browse files
holimanshekhirin
holiman
authored and
shekhirin
committed
cmd/evm: update documentation (ethereum#26385)
1 parent f608e59 commit efb4dca

File tree

2 files changed

+295
-9
lines changed

2 files changed

+295
-9
lines changed

‎cmd/evm/README.md

Lines changed: 158 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -439,11 +439,11 @@ to use the evm to go from `json` input to `rlp` input.
439439
The following command takes **json** the transactions in `./testdata/13/txs.json` and signs them. After execution, they are output to `signed_txs.rlp`.:
440440
```
441441
./evm t8n --state.fork=London --input.alloc=./testdata/13/alloc.json --input.txs=./testdata/13/txs.json --input.env=./testdata/13/env.json --output.result=alloc_jsontx.json --output.body=signed_txs.rlp
442-
INFO [12-07|04:30:12.380] Trie dumping started root=e4b924..6aef61
443-
INFO [12-07|04:30:12.380] Trie dumping complete accounts=3 elapsed="85.765µs"
444-
INFO [12-07|04:30:12.380] Wrote file file=alloc.json
445-
INFO [12-07|04:30:12.380] Wrote file file=alloc_jsontx.json
446-
INFO [12-07|04:30:12.380] Wrote file file=signed_txs.rlp
442+
INFO [12-27|09:25:11.102] Trie dumping started root=e4b924..6aef61
443+
INFO [12-27|09:25:11.102] Trie dumping complete accounts=3 elapsed="275.66µs"
444+
INFO [12-27|09:25:11.102] Wrote file file=alloc.json
445+
INFO [12-27|09:25:11.103] Wrote file file=alloc_jsontx.json
446+
INFO [12-27|09:25:11.103] Wrote file file=signed_txs.rlp
447447
```
448448

449449
The `output.body` is the rlp-list of transactions, encoded in hex and placed in a string a'la `json` encoding rules:
@@ -463,10 +463,10 @@ rlpdump -hex $(cat signed_txs.rlp | jq -r )
463463
Now, we can now use those (or any other already signed transactions), as input, like so:
464464
```
465465
./evm t8n --state.fork=London --input.alloc=./testdata/13/alloc.json --input.txs=./signed_txs.rlp --input.env=./testdata/13/env.json --output.result=alloc_rlptx.json
466-
INFO [12-07|04:30:12.425] Trie dumping started root=e4b924..6aef61
467-
INFO [12-07|04:30:12.425] Trie dumping complete accounts=3 elapsed="70.684µs"
468-
INFO [12-07|04:30:12.425] Wrote file file=alloc.json
469-
INFO [12-07|04:30:12.425] Wrote file file=alloc_rlptx.json
466+
INFO [12-27|09:25:11.187] Trie dumping started root=e4b924..6aef61
467+
INFO [12-27|09:25:11.187] Trie dumping complete accounts=3 elapsed="123.676µs"
468+
INFO [12-27|09:25:11.187] Wrote file file=alloc.json
469+
INFO [12-27|09:25:11.187] Wrote file file=alloc_rlptx.json
470470
```
471471
You might have noticed that the results from these two invocations were stored in two separate files.
472472
And we can now finally check that they match.
@@ -475,3 +475,152 @@ cat alloc_jsontx.json | jq .stateRoot && cat alloc_rlptx.json | jq .stateRoot
475475
"0xe4b924a6adb5959fccf769d5b7bb2f6359e26d1e76a2443c5a91a36d826aef61"
476476
"0xe4b924a6adb5959fccf769d5b7bb2f6359e26d1e76a2443c5a91a36d826aef61"
477477
```
478+
479+
## Transaction tool
480+
481+
The transaction tool is used to perform static validity checks on transactions such as:
482+
* intrinsic gas calculation
483+
* max values on integers
484+
* fee semantics, such as `maxFeePerGas < maxPriorityFeePerGas`
485+
* newer tx types on old forks
486+
487+
### Examples
488+
489+
```
490+
./evm t9n --state.fork Homestead --input.txs testdata/15/signed_txs.rlp
491+
[
492+
{
493+
"error": "transaction type not supported",
494+
"hash": "0xa98a24882ea90916c6a86da650fbc6b14238e46f0af04a131ce92be897507476"
495+
},
496+
{
497+
"error": "transaction type not supported",
498+
"hash": "0x36bad80acce7040c45fd32764b5c2b2d2e6f778669fb41791f73f546d56e739a"
499+
}
500+
]
501+
```
502+
```
503+
./evm t9n --state.fork London --input.txs testdata/15/signed_txs.rlp
504+
[
505+
{
506+
"address": "0xd02d72e067e77158444ef2020ff2d325f929b363",
507+
"hash": "0xa98a24882ea90916c6a86da650fbc6b14238e46f0af04a131ce92be897507476",
508+
"intrinsicGas": "0x5208"
509+
},
510+
{
511+
"address": "0xd02d72e067e77158444ef2020ff2d325f929b363",
512+
"hash": "0x36bad80acce7040c45fd32764b5c2b2d2e6f778669fb41791f73f546d56e739a",
513+
"intrinsicGas": "0x5208"
514+
}
515+
]
516+
```
517+
## Block builder tool (b11r)
518+
519+
The `evm b11r` tool is used to assemble and seal full block rlps.
520+
521+
### Specification
522+
523+
#### Command line params
524+
525+
Command line params that need to be supported are:
526+
527+
```
528+
--input.header value `stdin` or file name of where to find the block header to use. (default: "header.json")
529+
--input.ommers value `stdin` or file name of where to find the list of ommer header RLPs to use.
530+
--input.txs value `stdin` or file name of where to find the transactions list in RLP form. (default: "txs.rlp")
531+
--output.basedir value Specifies where output files are placed. Will be created if it does not exist.
532+
--output.block value Determines where to put the alloc of the post-state. (default: "block.json")
533+
<file> - into the file <file>
534+
`stdout` - into the stdout output
535+
`stderr` - into the stderr output
536+
--seal.clique value Seal block with Clique. `stdin` or file name of where to find the Clique sealing data.
537+
--seal.ethash Seal block with ethash. (default: false)
538+
--seal.ethash.dir value Path to ethash DAG. If none exists, a new DAG will be generated.
539+
--seal.ethash.mode value Defines the type and amount of PoW verification an ethash engine makes. (default: "normal")
540+
--verbosity value Sets the verbosity level. (default: 3)
541+
```
542+
543+
#### Objects
544+
545+
##### `header`
546+
547+
The `header` object is a consensus header.
548+
549+
```go=
550+
type Header struct {
551+
ParentHash common.Hash `json:"parentHash"`
552+
OmmerHash *common.Hash `json:"sha3Uncles"`
553+
Coinbase *common.Address `json:"miner"`
554+
Root common.Hash `json:"stateRoot" gencodec:"required"`
555+
TxHash *common.Hash `json:"transactionsRoot"`
556+
ReceiptHash *common.Hash `json:"receiptsRoot"`
557+
Bloom types.Bloom `json:"logsBloom"`
558+
Difficulty *big.Int `json:"difficulty"`
559+
Number *big.Int `json:"number" gencodec:"required"`
560+
GasLimit uint64 `json:"gasLimit" gencodec:"required"`
561+
GasUsed uint64 `json:"gasUsed"`
562+
Time uint64 `json:"timestamp" gencodec:"required"`
563+
Extra []byte `json:"extraData"`
564+
MixDigest common.Hash `json:"mixHash"`
565+
Nonce *types.BlockNonce `json:"nonce"`
566+
BaseFee *big.Int `json:"baseFeePerGas"`
567+
}
568+
```
569+
#### `ommers`
570+
571+
The `ommers` object is a list of RLP-encoded ommer blocks in hex
572+
representation.
573+
574+
```go=
575+
type Ommers []string
576+
```
577+
578+
#### `txs`
579+
580+
The `txs` object is a list of RLP-encoded transactions in hex representation.
581+
582+
```go=
583+
type Txs []string
584+
```
585+
586+
#### `clique`
587+
588+
The `clique` object provides the neccesary information to complete a clique
589+
seal of the block.
590+
591+
```go=
592+
var CliqueInfo struct {
593+
Key *common.Hash `json:"secretKey"`
594+
Voted *common.Address `json:"voted"`
595+
Authorize *bool `json:"authorize"`
596+
Vanity common.Hash `json:"vanity"`
597+
}
598+
```
599+
600+
#### `output`
601+
602+
The `output` object contains two values, the block RLP and the block hash.
603+
604+
```go=
605+
type BlockInfo struct {
606+
Rlp []byte `json:"rlp"`
607+
Hash common.Hash `json:"hash"`
608+
}
609+
```
610+
611+
## A Note on Encoding
612+
613+
The encoding of values for `evm` utility attempts to be relatively flexible. It
614+
generally supports hex-encoded or decimal-encoded numeric values, and
615+
hex-encoded byte values (like `common.Address`, `common.Hash`, etc). When in
616+
doubt, the [`execution-apis`](https://github.com/ethereum/execution-apis) way
617+
of encoding should always be accepted.
618+
619+
## Testing
620+
621+
There are many test cases in the [`cmd/evm/testdata`](./testdata) directory.
622+
These fixtures are used to power the `t8n` tests in
623+
[`t8n_test.go`](./t8n_test.go). The best way to verify correctness of new `evm`
624+
implementations is to execute these and verify the output and error codes match
625+
the expected values.
626+

‎cmd/evm/transition-test.sh

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -379,3 +379,140 @@ echo "$ticks"
379379
echo "cat alloc_jsontx.json | jq .stateRoot && cat alloc_rlptx.json | jq .stateRoot"
380380
cat alloc_jsontx.json | jq .stateRoot && cat alloc_rlptx.json | jq .stateRoot
381381
echo "$ticks"
382+
383+
cat << "EOF"
384+
385+
## Transaction tool
386+
387+
The transaction tool is used to perform static validity checks on transactions such as:
388+
* intrinsic gas calculation
389+
* max values on integers
390+
* fee semantics, such as `maxFeePerGas < maxPriorityFeePerGas`
391+
* newer tx types on old forks
392+
393+
### Examples
394+
395+
EOF
396+
397+
cmd="./evm t9n --state.fork Homestead --input.txs testdata/15/signed_txs.rlp"
398+
tick;echo "$cmd";
399+
$cmd 2>/dev/null
400+
tick
401+
402+
cmd="./evm t9n --state.fork London --input.txs testdata/15/signed_txs.rlp"
403+
tick;echo "$cmd";
404+
$cmd 2>/dev/null
405+
tick
406+
407+
cat << "EOF"
408+
## Block builder tool (b11r)
409+
410+
The `evm b11r` tool is used to assemble and seal full block rlps.
411+
412+
### Specification
413+
414+
#### Command line params
415+
416+
Command line params that need to be supported are:
417+
418+
```
419+
--input.header value `stdin` or file name of where to find the block header to use. (default: "header.json")
420+
--input.ommers value `stdin` or file name of where to find the list of ommer header RLPs to use.
421+
--input.txs value `stdin` or file name of where to find the transactions list in RLP form. (default: "txs.rlp")
422+
--output.basedir value Specifies where output files are placed. Will be created if it does not exist.
423+
--output.block value Determines where to put the alloc of the post-state. (default: "block.json")
424+
<file> - into the file <file>
425+
`stdout` - into the stdout output
426+
`stderr` - into the stderr output
427+
--seal.clique value Seal block with Clique. `stdin` or file name of where to find the Clique sealing data.
428+
--seal.ethash Seal block with ethash. (default: false)
429+
--seal.ethash.dir value Path to ethash DAG. If none exists, a new DAG will be generated.
430+
--seal.ethash.mode value Defines the type and amount of PoW verification an ethash engine makes. (default: "normal")
431+
--verbosity value Sets the verbosity level. (default: 3)
432+
```
433+
434+
#### Objects
435+
436+
##### `header`
437+
438+
The `header` object is a consensus header.
439+
440+
```go=
441+
type Header struct {
442+
ParentHash common.Hash `json:"parentHash"`
443+
OmmerHash *common.Hash `json:"sha3Uncles"`
444+
Coinbase *common.Address `json:"miner"`
445+
Root common.Hash `json:"stateRoot" gencodec:"required"`
446+
TxHash *common.Hash `json:"transactionsRoot"`
447+
ReceiptHash *common.Hash `json:"receiptsRoot"`
448+
Bloom types.Bloom `json:"logsBloom"`
449+
Difficulty *big.Int `json:"difficulty"`
450+
Number *big.Int `json:"number" gencodec:"required"`
451+
GasLimit uint64 `json:"gasLimit" gencodec:"required"`
452+
GasUsed uint64 `json:"gasUsed"`
453+
Time uint64 `json:"timestamp" gencodec:"required"`
454+
Extra []byte `json:"extraData"`
455+
MixDigest common.Hash `json:"mixHash"`
456+
Nonce *types.BlockNonce `json:"nonce"`
457+
BaseFee *big.Int `json:"baseFeePerGas"`
458+
}
459+
```
460+
#### `ommers`
461+
462+
The `ommers` object is a list of RLP-encoded ommer blocks in hex
463+
representation.
464+
465+
```go=
466+
type Ommers []string
467+
```
468+
469+
#### `txs`
470+
471+
The `txs` object is a list of RLP-encoded transactions in hex representation.
472+
473+
```go=
474+
type Txs []string
475+
```
476+
477+
#### `clique`
478+
479+
The `clique` object provides the neccesary information to complete a clique
480+
seal of the block.
481+
482+
```go=
483+
var CliqueInfo struct {
484+
Key *common.Hash `json:"secretKey"`
485+
Voted *common.Address `json:"voted"`
486+
Authorize *bool `json:"authorize"`
487+
Vanity common.Hash `json:"vanity"`
488+
}
489+
```
490+
491+
#### `output`
492+
493+
The `output` object contains two values, the block RLP and the block hash.
494+
495+
```go=
496+
type BlockInfo struct {
497+
Rlp []byte `json:"rlp"`
498+
Hash common.Hash `json:"hash"`
499+
}
500+
```
501+
502+
## A Note on Encoding
503+
504+
The encoding of values for `evm` utility attempts to be relatively flexible. It
505+
generally supports hex-encoded or decimal-encoded numeric values, and
506+
hex-encoded byte values (like `common.Address`, `common.Hash`, etc). When in
507+
doubt, the [`execution-apis`](https://github.com/ethereum/execution-apis) way
508+
of encoding should always be accepted.
509+
510+
## Testing
511+
512+
There are many test cases in the [`cmd/evm/testdata`](./testdata) directory.
513+
These fixtures are used to power the `t8n` tests in
514+
[`t8n_test.go`](./t8n_test.go). The best way to verify correctness of new `evm`
515+
implementations is to execute these and verify the output and error codes match
516+
the expected values.
517+
518+
EOF

0 commit comments

Comments
 (0)