Skip to content

Commit

Permalink
autobot fixes
Browse files Browse the repository at this point in the history
  • Loading branch information
@shemnon
shemnon committed Aug 13, 2024
1 parent f61a73e commit c19d96f
Showing 1 changed file with 37 additions and 22 deletions.
59 changes: 37 additions & 22 deletions EIPS/eip-3155.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
eip: 3155
title: EVM trace specification
description: A standard JSON format for EVM traces

Check failure on line 4 in EIPS/eip-3155.md

View workflow job for this annotation

GitHub Actions / EIP Walidator

preamble header `description` should not contain `standard` (or similar words.) 

error[preamble-re-description]: preamble header `description` should not contain `standard` (or similar words.)
 --> EIPS/eip-3155.md:4:13
  |
4 | description: A standard JSON format for EVM traces
  |             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ prohibited pattern was matched
  |
  = info: the pattern in question: `(?i)standar\w*\b`
  = help: see https://ethereum.github.io/eipw/preamble-re-description/
author: Martin Holst Swende (@holiman), Marius van der Wijden (@MariusVanDerWijden)
discussions-to: https://ethereum-magicians.org/t/eip-3155-create-evm-trace-specification/5007
status: Last Call
Expand All @@ -10,16 +11,19 @@ category: Interface
created: 2020-12-07
---

## Simple Summary
Introduce a new JSON standard for EVM traces during execution of state tests.
## Abstract

Introduce a new JSON standard for EVM traces during execution of state tests.

## Motivation
The Ethereum Virtual Machine executes all smart contract code on ethereum.
In order to debug smart contracts and state tests better, a common format was introduced to log every execution step of the EVM.
This format was implemented by Go-Ethereum, Parity-Ethereum, Nethermind and Besu.

The Ethereum Virtual Machine executes all smart contract code on ethereum.
In order to debug smart contracts and state tests better, a common format was introduced to log every execution step of the EVM.
This format was implemented by Go-Ethereum, Parity-Ethereum, Nethermind and Besu.
Since the common format was not well-defined, the implementations differed slightly, making it hard to develop adequate tooling which reduces the usefulness of tracing significantly.

This EIP has multiple objectives:
This EIP has multiple goals:

- Move the specification to a more visible place to encourage new clients to implement it
- Strictly define corner cases that were not addressed in the previous version
- Allow for updates to the specification in case new fields are introduced during execution
Expand All @@ -28,11 +32,13 @@ This EIP has multiple objectives:
Implementing this EIP in all major clients allows us to create meaningful differential fuzzers that fuzz EVM implementations for the mainnet and all upcoming hardforks.
It also helps to find differences in execution quickly in the case of a chain split.

This EIP will enable users to create better differential fuzzing infrastructure to compare the EVM implementations of all major Ethereum clients against each other.
This could help to find bugs that are currently present in the client implementations.
This EIP will enable users to create better differential fuzzing infrastructure to compare the EVM implementations of all major Ethereum clients against each other.
This could help to find bugs that are currently present in the client implementations.

## Specification
Clients should be able to execute simple transactions as well as code and return traces. In the following, we will call this client CUT (client under test) and use go-ethereum's `evm` binary for code examples.

Clients should be able to execute simple transactions as well as code and return traces. In the following, we will call this client CUT (client under test) and use go-ethereum's
`evm` binary for code examples.

### Datatypes

Expand All @@ -48,9 +54,9 @@ Clients should be able to execute simple transactions as well as code and return

### Output

The CUT MUST output a `json` object for EACH operation.
The CUT MUST output a `json` object for EACH operation.

#### Required Fields
#### Required Fields

| Name | Type | Explanation |
|--------------|----------------------|------------------------------------------|
Expand All @@ -64,7 +70,7 @@ The CUT MUST output a `json` object for EACH operation.
| `returnData` | Hex-String | Data returned by function call |
| `refund` | Hex-Number | Amount of **global** gas refunded |

#### Optional Fields
#### Optional Fields

| Name | Type | Explanation |
|---------------|----------------------|---------------------------------------------------------------------|
Expand All @@ -74,21 +80,24 @@ The CUT MUST output a `json` object for EACH operation.
| `storage` | Key-Value | Array of all stored values |
| `returnStack` | Array of Hex-Numbers | Array of values, Stack of the called function |

*Example:*
*Example:*

```
{"pc":0,"op":96,"gas":"0x2540be400","gasCost":"0x3","memory":"0x","memSize":0,"stack":[],"depth":1,"error":null,"opName":"PUSH1"}
```

- The `stack`, `memory` and `memSize` are the values _before_ execution of the op.
- The `stack`, `memory` and `memSize` are the values *before* execution of the op.
- All array attributes (`stack`, `returnStack`, `memory`) MUST be initialized to empty arrays (`"stack":[]`) NOT to null.
- If the CUT will not be outputting values for `memory` or `storage` then the `memory` and `storage` fields are omitted.
This can happen either because the CUT does not support tracing these fields or it has been configured not to trace it.
- The `memSize` field MUST be present regardless of `memory` support.
- Clients SHOULD implement a way to disable recording the storage as the stateroot includes all storage updates.
- Clients SHOULD output the fields in the same order as listed in this EIP.

- The CUT MUST NOT output a line for the `STOP` operation if an error occurred:
*Example:*
The CUT MUST NOT output a line for the `STOP` operation if an error occurred:

*Example:*

```
{"pc":2,"op":0,"gas":"0x2540be3fd","gasCost":"0x0","memory":"0x","memSize":0,"stack":["0x40"],"depth":1,"error":null,"opName":"STOP"}
```
Expand All @@ -98,7 +107,7 @@ The CUT MUST output a `json` object for EACH operation.
At the end of execution, the CUT MUST print summary info; this info SHOULD have the following fields.
The summary should be a single `jsonl` object.

#### Required Fields
#### Required Fields

| Name | Type | Explanation |
|-------------|------------|--------------------------------------------------------|
Expand All @@ -115,20 +124,26 @@ The summary should be a single `jsonl` object.
| `fork` | String | Name of the fork rules used for execution |

*Example*:

```
{"stateRoot":"0xd4c577737f5d20207d338c360c42d3af78de54812720e3339f7b27293ef195b7","output":"","gasUsed":"0x3","pass":"true","time":141485}
```

## Rationale
This EIP is largely based on the previous non-official documentation for EVM tracing.

This EIP is largely based on the previous non-official documentation for EVM tracing.
It tries to cover as many corner cases as possible to enable true client compatibility.
The datatypes and if a field is optional is chosen to be as compatible with current implementations as possible.

## Backwards Compatibility

This EIP is fully backward compatible with ethereum as it only introduces a better tracing infrastructure that is optional for clients to implement.

### Clients
This EIP is fully backward compatible with go-ethereum. OpenEthereum, Besu and Nethermind clients would have to change their JSON output of `openethereum-evm` `evmtool` and `nethtest` slightly do adhere to the new and stricter specs. New clients would need to implement this change if they want to be part of the differential fuzzing group.

This EIP is fully backward compatible with go-ethereum. OpenEthereum, Besu and Nethermind clients would have to change their JSON output of
`openethereum-evm` `evmtool` and
`nethtest` slightly do adhere to the new and stricter specs. New clients would need to implement this change if they want to be part of the differential fuzzing group.

## Test Cases

Expand All @@ -151,14 +166,14 @@ ${BESU_HOME}/bin/evmtool --code 0x604080536040604055604060006040600060025afa6040
{"stateRoot":"0x8fa0dcc7f1d2383c89e5737c2843632db881c0946e80b71fe7175365e6538797","output":"0x40","gasUsed":"0x515c","pass":true,"fork":"Istanbul"}
```


## Security Considerations

Tracing is expensive.
Tracing is expensive.

Exposing an endpoint for creating traces publicly could open up a denial of service vector.
Exposing an endpoint for creating traces publicly could open up a denial of service vector.

Clients should consider putting trace endpoints behind a separate flag from other endpoints.

## Copyright

Copyright and related rights waived via [CC0](../LICENSE.md).

0 comments on commit c19d96f

Please sign in to comment.