feat(core): state journal wrapper #30441 #33978

core/genesis.go

@@ -113,7 +113,7 @@ func hashAlloc(ga *types.GenesisAlloc) (common.Hash, error) {
 			statedb.AddBalance(addr, account.Balance, tracing.BalanceIncreaseGenesisBalance)
 		}
 		statedb.SetCode(addr, account.Code)
-		statedb.SetNonce(addr, account.Nonce)
+		statedb.SetNonce(addr, account.Nonce, tracing.NonceChangeGenesis)
 		for key, value := range account.Storage {
 			statedb.SetState(addr, key, value)
 		}
@@ -134,7 +134,7 @@ func flushAlloc(ga *types.GenesisAlloc, db ethdb.Database, blockhash common.Hash
 			statedb.AddBalance(addr, account.Balance, tracing.BalanceIncreaseGenesisBalance)
 		}
 		statedb.SetCode(addr, account.Code)
-		statedb.SetNonce(addr, account.Nonce)
+		statedb.SetNonce(addr, account.Nonce, tracing.NonceChangeGenesis)
 		for key, value := range account.Storage {
 			statedb.SetState(addr, key, value)
 		}

core/state/statedb.go

@@ -450,7 +450,7 @@ func (s *StateDB) SetBalance(addr common.Address, amount *big.Int, _ tracing.Bal
 	}
 }
 
-func (s *StateDB) SetNonce(addr common.Address, nonce uint64) {
+func (s *StateDB) SetNonce(addr common.Address, nonce uint64, _ tracing.NonceChangeReason) {
 	stateObject := s.GetOrNewStateObject(addr)
 	if stateObject != nil {
 		stateObject.SetNonce(nonce)

core/state/statedb_fuzz_test.go

@@ -67,7 +67,7 @@ func newStateTestAction(addr common.Address, r *rand.Rand, index int) testAction
 		{
 			name: "SetNonce",
 			fn: func(a testAction, s *StateDB) {
-				s.SetNonce(addr, uint64(a.args[0]))
+				s.SetNonce(addr, uint64(a.args[0]), tracing.NonceChangeUnspecified)
 			},
 			args: make([]int64, 1),
 		},

core/state/statedb_hooked.go

@@ -166,10 +166,12 @@ func (s *hookedStateDB) AddBalance(addr common.Address, amount *big.Int, reason
 	return prev
 }
 
-func (s *hookedStateDB) SetNonce(address common.Address, nonce uint64) {
+func (s *hookedStateDB) SetNonce(address common.Address, nonce uint64, reason tracing.NonceChangeReason) {
 	prev := s.inner.GetNonce(address)
-	s.inner.SetNonce(address, nonce)
-	if s.hooks.OnNonceChange != nil {
+	s.inner.SetNonce(address, nonce, reason)
+	if s.hooks.OnNonceChangeV2 != nil {
+		s.hooks.OnNonceChangeV2(address, prev, nonce, reason)
+	} else if s.hooks.OnNonceChange != nil {
 		s.hooks.OnNonceChange(address, prev, nonce)
 	}
 }

core/state/statedb_hooked_test.go

@@ -112,7 +112,7 @@ func TestHooks(t *testing.T) {
 	})
 	sdb.AddBalance(common.Address{0xaa}, big.NewInt(100), tracing.BalanceChangeUnspecified)
 	sdb.SubBalance(common.Address{0xaa}, big.NewInt(50), tracing.BalanceChangeTransfer)
-	sdb.SetNonce(common.Address{0xaa}, 1337)
+	sdb.SetNonce(common.Address{0xaa}, 1337, tracing.NonceChangeGenesis)
 	sdb.SetCode(common.Address{0xaa}, []byte{0x13, 37})
 	sdb.SetState(common.Address{0xaa}, common.HexToHash("0x01"), common.HexToHash("0x11"))
 	sdb.SetState(common.Address{0xaa}, common.HexToHash("0x01"), common.HexToHash("0x22"))

core/state/statedb_test.go

@@ -46,7 +46,7 @@ func TestUpdateLeaks(t *testing.T) {
 	for i := byte(0); i < 255; i++ {
 		addr := common.BytesToAddress([]byte{i})
 		state.AddBalance(addr, big.NewInt(int64(11*i)), tracing.BalanceChangeUnspecified)
-		state.SetNonce(addr, uint64(42*i))
+		state.SetNonce(addr, uint64(42*i), tracing.NonceChangeUnspecified)
 		if i%2 == 0 {
 			state.SetState(addr, common.BytesToHash([]byte{i, i, i}), common.BytesToHash([]byte{i, i, i, i}))
 		}
@@ -79,7 +79,7 @@ func TestIntermediateLeaks(t *testing.T) {
 
 	modify := func(state *StateDB, addr common.Address, i, tweak byte) {
 		state.SetBalance(addr, big.NewInt(int64(11*i)+int64(tweak)), tracing.BalanceChangeUnspecified)
-		state.SetNonce(addr, uint64(42*i+tweak))
+		state.SetNonce(addr, uint64(42*i+tweak), tracing.NonceChangeUnspecified)
 		if i%2 == 0 {
 			state.SetState(addr, common.Hash{i, i, i, 0}, common.Hash{})
 			state.SetState(addr, common.Hash{i, i, i, tweak}, common.Hash{i, i, i, i, tweak})
@@ -336,7 +336,7 @@ func newTestAction(addr common.Address, r *rand.Rand) testAction {
 		{
 			name: "SetNonce",
 			fn: func(a testAction, s *StateDB) {
-				s.SetNonce(addr, uint64(a.args[0]))
+				s.SetNonce(addr, uint64(a.args[0]), tracing.NonceChangeUnspecified)
 			},
 			args: make([]int64, 1),
 		},

core/state/statedb_utils.go

@@ -4,6 +4,7 @@ import (
 	"math/big"
 
 	"github.com/XinFinOrg/XDPoSChain/common"
+	"github.com/XinFinOrg/XDPoSChain/core/tracing"
 	"github.com/XinFinOrg/XDPoSChain/core/types"
 	"github.com/XinFinOrg/XDPoSChain/crypto"
 )
@@ -154,7 +155,7 @@ func (s *StateDB) GetVoterCap(candidate, voter common.Address) *big.Int {
 
 func (s *StateDB) IncrementMintedRecordNonce() {
 	nonce := s.GetNonce(common.MintedRecordAddressBinary)
-	s.SetNonce(common.MintedRecordAddressBinary, nonce+1)
+	s.SetNonce(common.MintedRecordAddressBinary, nonce+1, tracing.NonceChangeUnspecified)
 }
 
 var (

core/state_processor.go

@@ -570,7 +570,7 @@ func ApplySignTransaction(msg *Message, config *params.ChainConfig, statedb *sta
 			return nil, 0, false, ErrNonceTooLow
 		}
 		// Only increment the nonce for real transactions.
-		statedb.SetNonce(from, nonce+1)
+		statedb.SetNonce(from, nonce+1, tracing.NonceChangeEoACall)
 	}
 	// Create a new receipt for the transaction, storing the intermediate root and gas used by the tx
 	// based on the eip phase, we're passing whether the root touch-delete accounts.
@@ -675,7 +675,7 @@ func ProcessParentBlockHash(prevHash common.Hash, evm *vm.EVM) {
 			evm.StateDB.CreateAccount(params.HistoryStorageAddress)
 		}
 		if evm.StateDB.GetNonce(params.HistoryStorageAddress) == 0 {
-			evm.StateDB.SetNonce(params.HistoryStorageAddress, 1)
+			evm.StateDB.SetNonce(params.HistoryStorageAddress, 1, tracing.NonceChangeUnspecified)
 		}
 		evm.StateDB.SetCode(params.HistoryStorageAddress, params.HistoryStorageCode)
 

core/state_processor_test.go

@@ -608,7 +608,7 @@ func TestProcessParentBlockHash(t *testing.T) {
 		coinbase    = common.Address{}
 	)
 	test := func(statedb *state.StateDB) {
-		statedb.SetNonce(params.HistoryStorageAddress, 1)
+		statedb.SetNonce(params.HistoryStorageAddress, 1, tracing.NonceChangeUnspecified)
 		statedb.SetCode(params.HistoryStorageAddress, params.HistoryStorageCode)
 		statedb.IntermediateRoot(true)
 

core/state_transition.go

@@ -459,7 +459,7 @@ func (st *StateTransition) TransitionDb(owner common.Address) (*ExecutionResult,
 		ret, _, st.gasRemaining, vmerr = st.evm.Create(msg.From, msg.Data, st.gasRemaining, value)
 	} else {
 		// Increment the nonce for the next transaction
-		st.state.SetNonce(msg.From, st.state.GetNonce(msg.From)+1)
+		st.state.SetNonce(msg.From, st.state.GetNonce(msg.From)+1, tracing.NonceChangeEoACall)
 
 		// Apply EIP-7702 authorizations.
 		if msg.SetCodeAuthorizations != nil {
@@ -567,7 +567,7 @@ func (st *StateTransition) applyAuthorization(msg *Message, auth *types.SetCodeA
 	}
 
 	// Update nonce and account code.
-	st.state.SetNonce(authority, auth.Nonce+1)
+	st.state.SetNonce(authority, auth.Nonce+1, tracing.NonceChangeAuthorization)
 	if auth.Address == (common.Address{}) {
 		// Delegation to zero address means clear.
 		st.state.SetCode(authority, nil)

core/tracing/CHANGELOG.md

@@ -2,7 +2,59 @@
 
 All notable changes to the tracing interface will be documented in this file.
 
-## [Unreleased]
+## Unreleased
+
+## [v1.15.0](https://github.com/ethereum/go-ethereum/releases/tag/v1.15.0)
+
+The tracing interface has been extended with backwards-compatible changes to support more use-cases and simplify tracer code. The most notable change is a state journaling library which emits reverse events when a call is reverted.
+
+### Deprecated methods
+
+- `OnSystemCallStart()`: This hook is deprecated in favor of `OnSystemCallStartV2(vm *VMContext)`.
+- `OnNonceChange(addr common.Address, prev, new uint64)`: This hook is deprecated in favor of `OnNonceChangeV2(addr common.Address, prev, new uint64, reason NonceChangeReason)`.
+
+### Added methods
+
+- `OnBlockHashRead(blockNum uint64, hash common.Hash)`: This hook is called when a block hash is read by EVM.
+- `OnSystemCallStartV2(vm *VMContext)`: This allows access to EVM context during system calls. It is a successor to `OnSystemCallStart`.
+- `OnNonceChangeV2(addr common.Address, prev, new uint64, reason NonceChangeReason)`: This hook is called when a nonce change occurs. It is a successor to `OnNonceChange`.
+
+### New types
+
+- `NonceChangeReason` is a new type used to provide a reason for nonce changes. Notably it includes `NonceChangeRevert` which will be emitted by the state journaling library when a nonce change is due to a revert.
+
+### Modified types
+
+- `VMContext.StateDB` has been extended with the following method:
+  - `GetCodeHash(addr common.Address) common.Hash` method used to retrieve the code hash of an account.
+- `BalanceChangeReason` has been extended with the `BalanceChangeRevert` reason. More on that below.
+- `GasChangeReason` has been extended with the following reason:
+  - `GasChangeTxDataFloor` is the amount of extra gas the transaction has to pay to reach the minimum gas requirement for the transaction data. This change will always be a negative change.
+
+### State journaling
+
+Tracers receive state changes events from the node. The tracer was so far expected to keep track of modified accounts and slots and revert those changes when a call frame failed. Now a utility tracer wrapper is provided which will emit "reverse change" events when a call frame fails. To use this feature the hooks have to be wrapped prior to registering the tracer. The following example demonstrates how to use the state journaling library:
+
+```go
+func init() {
+    tracers.LiveDirectory.Register("test", func(cfg json.RawMessage) (*tracing.Hooks, error) {
+        hooks, err := newTestTracer(cfg)
+        if err != nil {
+            return nil, err
+        }
+        return tracing.WrapWithJournal(hooks)
+    })
+}
+```
+
+The state changes that are covered by the journaling library are:
+
+- `OnBalanceChange`. Note that `OnBalanceChange` will carry the `BalanceChangeRevert` reason.
+- `OnNonceChange`, `OnNonceChangeV2`
+- `OnCodeChange`
+- `OnStorageChange`
+
+## [v1.14.3](https://github.com/ethereum/go-ethereum/releases/tag/v1.14.3)
 
 There have been minor backwards-compatible changes to the tracing interface to explicitly mark the execution of **system** contracts. As of now the only system call updates the parent beacon block root as per [EIP-4788](https://eips.ethereum.org/EIPS/eip-4788). Other system calls are being considered for the future hardfork.
 
@@ -11,47 +63,46 @@ There have been minor backwards-compatible changes to the tracing interface to e
 - `OnSystemCallStart()`: This hook is called when EVM starts processing a system call. Note system calls happen outside the scope of a transaction. This event will be followed by normal EVM execution events.
 - `OnSystemCallEnd()`: This hook is called when EVM finishes processing a system call.
 
-## [v1.14.0]
+## [v1.14.0](https://github.com/ethereum/go-ethereum/releases/tag/v1.14.0)
 
 There has been a major breaking change in the tracing interface for custom native tracers. JS and built-in tracers are not affected by this change and tracing API methods may be used as before. This overhaul has been done as part of the new live tracing feature ([#29189](https://github.com/ethereum/go-ethereum/pull/29189)). To learn more about live tracing please refer to the [docs](https://geth.ethereum.org/docs/developers/evm-tracing/live-tracing).
 
 **The `EVMLogger` interface which the tracers implemented has been removed.** It has been replaced by a new struct `tracing.Hooks`. `Hooks` keeps pointers to event listening functions. Internally the EVM will use these function pointers to emit events and can skip an event if the tracer has opted not to implement it. In fact this is the main reason for this change of approach. Another benefit is the ease of adding new hooks in future, and dynamically assigning event receivers.
 
-The consequence of this change can be seen in the constructor of a tracer. Let's take the 4byte tracer as an example. Previously the constructor return an instance which satisfied the interface. Now it should return a pointer to `tracers.Tracer` (which is now also a struct as opposed to an interface) and explicitly assign the event listeners. As a side-benefit the tracers will not have to provide empty implementation of methods just to satisfy the interface:
+The consequence of this change can be seen in the constructor of a tracer. Let's take the 4byte tracer as an example. Previously the constructor returned an instance which satisfied the interface. Now it should return a pointer to `tracers.Tracer` (which is now also a struct as opposed to an interface) and explicitly assign the event listeners. As a side-benefit the tracers will not have to provide empty implementations of methods just to satisfy the interface:
 
 ```go
 func newFourByteTracer(ctx *tracers.Context, _ json.RawMessage) (tracers.Tracer, error) {
- t := &fourByteTracer{
-  ids: make(map[string]int),
- }
- return t, nil
-
+    t := &fourByteTracer{
+        ids: make(map[string]int),
+    }
+    return t, nil
 }
 ```
 
 And now:
 
 ```go
 func newFourByteTracer(ctx *tracers.Context, _ json.RawMessage) (*tracers.Tracer, error) {
- t := &fourByteTracer{
-  ids: make(map[string]int),
- }
- return &tracers.Tracer{
-  Hooks: &tracing.Hooks{
-   OnTxStart: t.onTxStart,
-   OnEnter:   t.onEnter,
-  },
-  GetResult: t.getResult,
-  Stop:      t.stop,
- }, nil
+    t := &fourByteTracer{
+        ids: make(map[string]int),
+    }
+    return &tracers.Tracer{
+        Hooks: &tracing.Hooks{
+            OnTxStart: t.onTxStart,
+            OnEnter:   t.onEnter,
+        },
+        GetResult: t.getResult,
+        Stop:      t.stop,
+    }, nil
 }
 ```
 
 ### Event listeners
 
 If you have sharp eyes you might have noticed the new names for `OnTxStart` and `OnEnter`, previously called `CaptureTxStart` and `CaptureEnter`. Indeed there have been various modifications to the signatures of the event listeners. All method names now follow the `On*` pattern instead of `Capture*`. However the modifications are not limited to the names.
 
-#### New methods
+#### Added listener methods
 
 The live tracing feature was half about adding more observability into the state of the blockchain. As such there have been a host of method additions. Please consult the [Hooks](./hooks.go) struct for the full list of methods. Custom tracers which are invoked through the API (as opposed to "live" tracers) can benefit from the following new methods:
 
@@ -60,7 +111,7 @@ The live tracing feature was half about adding more observability into the state
 - `OnNonceChange(addr common.Address, prev, new uint64)`: This hook tracks the nonce changes of accounts.
 - `OnCodeChange(addr common.Address, prevCodeHash common.Hash, prevCode []byte, codeHash common.Hash, code []byte)`: This hook tracks the code changes of accounts.
 - `OnStorageChange(addr common.Address, slot common.Hash, prev, new common.Hash)`: This hook tracks the storage changes of accounts.
-- `OnLogChange(log *types.Log)`: This hook tracks the logs emitted by the EVM.
+- `OnLog(log *types.Log)`: This hook tracks the logs emitted by the EVM.
 
 #### Removed methods
 
@@ -70,10 +121,7 @@ The hooks `CaptureStart` and `CaptureEnd` have been removed. These hooks signale
 
 - `CaptureTxStart` -> `OnTxStart(vm *VMContext, tx *types.Transaction, from common.Address)`. It now emits the full transaction object as well as `from` which should be used to get the sender address. The `*VMContext` is a replacement for the `*vm.EVM` object previously passed to `CaptureStart`.
 - `CaptureTxEnd` -> `OnTxEnd(receipt *types.Receipt, err error)`. It now returns the full receipt object.
-- `CaptureEnter` -> `OnEnter(depth int, typ byte, from common.Address, to common.Address, input []byte, gas uint64, value *big.Int)`. The new `depth int` parameter indicates the call stack depth. It is 0 for the top-level call. Furthermore, the location where `OnEnter` is called in the EVM is now made a soon as a call is started. This means some specific error cases that were not before calling `OnEnter/OnExit` will now do so, leading some transaction to have an extra call traced.
+- `CaptureEnter` -> `OnEnter(depth int, typ byte, from common.Address, to common.Address, input []byte, gas uint64, value *big.Int)`. The new `depth int` parameter indicates the call stack depth. It is 0 for the top-level call. Furthermore, the location where `OnEnter` is called in the EVM is now made as soon as a call is started. This means some specific error cases that were not before calling `OnEnter/OnExit` will now do so, leading some transactions to have an extra call traced.
 - `CaptureExit` -> `OnExit(depth int, output []byte, gasUsed uint64, err error, reverted bool)`. It has the new `depth` parameter, same as `OnEnter`. The new `reverted` parameter indicates whether the call frame was reverted.
 - `CaptureState` -> `OnOpcode(pc uint64, op byte, gas, cost uint64, scope tracing.OpContext, rData []byte, depth int, err error)`. `op` is of type `byte` which can be cast to `vm.OpCode` when necessary. A `*vm.ScopeContext` is not passed anymore. It is replaced by `tracing.OpContext` which offers access to the memory, stack and current contract.
 - `CaptureFault` -> `OnFault(pc uint64, op byte, gas, cost uint64, scope tracing.OpContext, depth int, err error)`. Similar to above.
-
-[unreleased]: https://github.com/ethereum/go-ethereum/compare/v1.14.0...master
-[v1.14.0]: https://github.com/ethereum/go-ethereum/releases/tag/v1.14.0