Utilize BalanceChangeReason in tracing

core/tracing/hooks.go

@@ -232,8 +232,102 @@ const (
 	// account within the same tx (captured at end of tx).
 	// Note it doesn't account for a self-destruct which appoints itself as recipient.
 	BalanceDecreaseSelfdestructBurn BalanceChangeReason = 14
+
+	// Arbitrum specific
+	BalanceIncreaseDeposit           BalanceChangeReason = 15
+	BalanceDecreaseWithdrawToL1      BalanceChangeReason = 16
+	BalanceIncreaseL1PosterFee       BalanceChangeReason = 17
+	BalanceIncreaseInfraFee          BalanceChangeReason = 18
+	BalanceIncreaseNetworkFee        BalanceChangeReason = 19
+	BalanceIncreaseRetryTxPrepaid    BalanceChangeReason = 20
+	BalanceDecreaseRetryTxUndoRefund BalanceChangeReason = 21
+
+	BalanceChangeTransferRetryTxToEscrow   BalanceChangeReason = 22
+	BalanceChangeTransferRetryTxFromEscrow BalanceChangeReason = 23
+
+	BalanceChangeTransferRetryableToFeeRefundAddr BalanceChangeReason = 24
+	BalanceChangeTransferRetryableToEscrow        BalanceChangeReason = 25
+
+	BalanceChangeTransferRetryableToInfra     BalanceChangeReason = 26
+	BalanceChangeTransferRetryableFromInfra   BalanceChangeReason = 27
+	BalanceChangeTransferRetryableToNetwork   BalanceChangeReason = 28
+	BalanceChangeTransferRetryableFromNetwork BalanceChangeReason = 29
+
+	BalanceChangeTransferBatchposterReward BalanceChangeReason = 30
+	BalanceChangeTransferBatchposterRefund BalanceChangeReason = 31
+
+	// Stylus
+	BalanceChangeTransferActivationFee       BalanceChangeReason = 32
+	BalanceChangeTransferActivationReimburse BalanceChangeReason = 33
 )
 
+func (b BalanceChangeReason) String(prev, new *big.Int) string {
+	var reason string
+
+	prependString := func() string {
+		if prev == nil || new == nil {
+			return ""
+		}
+		if new.Cmp(prev) == 1 {
+			return "balance increase due to a "
+		} else if new.Cmp(prev) == -1 {
+			return "balance decrease due to a "
+		}
+		return ""
+	}
+
+	switch b {
+	case BalanceChangeTransfer:
+		reason = prependString() + "transfer via a call"
+	case BalanceIncreaseDeposit:
+		reason = "balance increase via a deposit"
+	case BalanceDecreaseWithdrawToL1:
+		reason = "balance decrease via a withdrawal to L1"
+	case BalanceIncreaseL1PosterFee:
+		reason = "balance increase via a fee collection for L1 posting"
+	case BalanceIncreaseInfraFee:
+		reason = "balance increase via a fee collection by infrastructure fee account"
+	case BalanceIncreaseNetworkFee:
+		reason = "balance increase via a fee collection by network fee account"
+	// ArbitrumRetryTx
+	case BalanceIncreaseRetryTxPrepaid:
+		reason = "balance increase by prepaid value for a tx of ArbitrumRetryTx type"
+	case BalanceDecreaseRetryTxUndoRefund:
+		reason = "balance decrease by undoing Geth's refund for a tx of ArbitrumRetryTx type"
+	case BalanceChangeTransferRetryTxToEscrow:
+		reason = prependString() + "transfer to escrow in a tx of ArbitrumRetryTx type"
+	case BalanceChangeTransferRetryTxFromEscrow:
+		reason = prependString() + "transfer from escrow in a tx of ArbitrumRetryTx type"
+	// ArbitrumSubmitRetryableTx
+	case BalanceChangeTransferRetryableToFeeRefundAddr:
+		reason = prependString() + "transfer to FeeRefundAddr in a tx of ArbitrumSubmitRetryableTx type"
+	case BalanceChangeTransferRetryableToEscrow:
+		reason = prependString() + "transfer to escrow in a tx of ArbitrumSubmitRetryableTx type"
+	case BalanceChangeTransferRetryableToInfra:
+		reason = prependString() + "transfer to infrastructure fee account in a tx of ArbitrumSubmitRetryableTx type"
+	case BalanceChangeTransferRetryableFromInfra:
+		reason = prependString() + "transfer from infrastructure fee account in a tx of ArbitrumSubmitRetryableTx type"
+	case BalanceChangeTransferRetryableToNetwork:
+		reason = prependString() + "transfer to network fee account in a tx of ArbitrumSubmitRetryableTx type"
+	case BalanceChangeTransferRetryableFromNetwork:
+		reason = prependString() + "transfer from network fee account in a tx of ArbitrumSubmitRetryableTx type"
+	// Batchposter
+	case BalanceChangeTransferBatchposterReward:
+		reason = prependString() + "transfer from L1PricerFundsPoolAddress as batchPosterReward"
+	case BalanceChangeTransferBatchposterRefund:
+		reason = prependString() + "transfer from L1PricerFundsPoolAddress as batchPosterRefund"
+	// Stylus
+	case BalanceChangeTransferActivationFee:
+		reason = prependString() + "transfer of activation fee to network fee account"
+	case BalanceChangeTransferActivationReimburse:
+		reason = prependString() + "transfer of reimburse amount after charging the activation fee"
+	default:
+		reason = "unspecified"
+	}
+
+	return reason
+}
+
 // GasChangeReason is used to indicate the reason for a gas change, useful
 // for tracing and reporting.
 //

eth/tracers/internal/tracetest/calltrace_test.go

@@ -53,11 +53,19 @@ type arbitrumTransfer struct {
 	Value   string  `json:"value"`
 }
 
+type balanceChange struct {
+	Addr   string `json:"addr"`
+	Prev   string `json:"prev"`
+	New    string `json:"new"`
+	Reason string `json:"reason"`
+}
+
 // callTrace is the result of a callTracer run.
 type callTrace struct {
 	// Arbitrum: we add these here due to the tracer returning the top frame
 	BeforeEVMTransfers *[]arbitrumTransfer `json:"beforeEVMTransfers,omitempty"`
 	AfterEVMTransfers  *[]arbitrumTransfer `json:"afterEVMTransfers,omitempty"`
+	BalanceChanges     *[]balanceChange    `json:"balanceChanges,omitempty"`
 
 	From         common.Address  `json:"from"`
 	Gas          *hexutil.Uint64 `json:"gas"`
@@ -301,13 +309,13 @@ func TestInternals(t *testing.T) {
 				byte(vm.CALL),
 			},
 			tracer: mkTracer("callTracer", nil),
-			want:   fmt.Sprintf(`{"beforeEVMTransfers":[{"purpose":"feePayment","from":"%s","to":null,"value":"0x13880"}],"afterEVMTransfers":[{"purpose":"gasRefund","from":null,"to":"%s","value":"0xe3a8"},{"purpose":"tip","from":null,"to":"0x0000000000000000000000000000000000000000","value":"0x54d8"}],"from":"%s","gas":"0x13880","gasUsed":"0x54d8","to":"0x00000000000000000000000000000000deadbeef","input":"0x","calls":[{"from":"0x00000000000000000000000000000000deadbeef","gas":"0xe01a","gasUsed":"0x0","to":"0x00000000000000000000000000000000000000ff","input":"0x","value":"0x0","type":"CALL"}],"value":"0x0","type":"CALL"}`, origin.Hex(), origin.Hex(), originHex),
+			want:   fmt.Sprintf(`{"beforeEVMTransfers":[{"purpose":"feePayment","from":"%s","to":null,"value":"0x13880"}],"afterEVMTransfers":[{"purpose":"gasRefund","from":null,"to":"%s","value":"0xe3a8"},{"purpose":"tip","from":null,"to":"0x0000000000000000000000000000000000000000","value":"0x54d8"}],"balanceChanges":[{"addr":"%s","prev":"0x1c6bf52634000","new":"0x1c6bf52620780","reason":"unspecified"},{"addr":"%s","prev":"0x1c6bf52620780","new":"0x1c6bf5262eb28","reason":"unspecified"},{"addr":"0x0000000000000000000000000000000000000000","prev":"0x0","new":"0x54d8","reason":"unspecified"}],"from":"%s","gas":"0x13880","gasUsed":"0x54d8","to":"0x00000000000000000000000000000000deadbeef","input":"0x","calls":[{"from":"0x00000000000000000000000000000000deadbeef","gas":"0xe01a","gasUsed":"0x0","to":"0x00000000000000000000000000000000000000ff","input":"0x","value":"0x0","type":"CALL"}],"value":"0x0","type":"CALL"}`, origin.Hex(), origin.Hex(), origin.Hex(), origin.Hex(), originHex),
 		},
 		{
 			name:   "Stack depletion in LOG0",
 			code:   []byte{byte(vm.LOG3)},
 			tracer: mkTracer("callTracer", json.RawMessage(`{ "withLog": true }`)),
-			want:   fmt.Sprintf(`{"beforeEVMTransfers":[{"purpose":"feePayment","from":"%s","to":null,"value":"0x13880"}],"afterEVMTransfers":[{"purpose":"gasRefund","from":null,"to":"%s","value":"0x0"},{"purpose":"tip","from":null,"to":"0x0000000000000000000000000000000000000000","value":"0x13880"}],"from":"%s","gas":"0x13880","gasUsed":"0x13880","to":"0x00000000000000000000000000000000deadbeef","input":"0x","error":"stack underflow (0 \u003c=\u003e 5)","value":"0x0","type":"CALL"}`, origin.Hex(), origin.Hex(), originHex),
+			want:   fmt.Sprintf(`{"beforeEVMTransfers":[{"purpose":"feePayment","from":"%s","to":null,"value":"0x13880"}],"afterEVMTransfers":[{"purpose":"gasRefund","from":null,"to":"%s","value":"0x0"},{"purpose":"tip","from":null,"to":"0x0000000000000000000000000000000000000000","value":"0x13880"}],"balanceChanges":[{"addr":"%s","prev":"0x1c6bf52634000","new":"0x1c6bf52620780","reason":"unspecified"},{"addr":"0x0000000000000000000000000000000000000000","prev":"0x0","new":"0x13880","reason":"unspecified"}],"from":"%s","gas":"0x13880","gasUsed":"0x13880","to":"0x00000000000000000000000000000000deadbeef","input":"0x","error":"stack underflow (0 \u003c=\u003e 5)","value":"0x0","type":"CALL"}`, origin.Hex(), origin.Hex(), origin.Hex(), originHex),
 		},
 		{
 			name: "Mem expansion in LOG0",
@@ -320,7 +328,7 @@ func TestInternals(t *testing.T) {
 				byte(vm.LOG0),
 			},
 			tracer: mkTracer("callTracer", json.RawMessage(`{ "withLog": true }`)),
-			want:   fmt.Sprintf(`{"beforeEVMTransfers":[{"purpose":"feePayment","from":"%s","to":null,"value":"0x13880"}],"afterEVMTransfers":[{"purpose":"gasRefund","from":null,"to":"%s","value":"0xdce2"},{"purpose":"tip","from":null,"to":"0x0000000000000000000000000000000000000000","value":"0x5b9e"}],"from":"%s","gas":"0x13880","gasUsed":"0x5b9e","to":"0x00000000000000000000000000000000deadbeef","input":"0x","logs":[{"address":"0x00000000000000000000000000000000deadbeef","topics":[],"data":"0x000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000","position":"0x0"}],"value":"0x0","type":"CALL"}`, origin.Hex(), origin.Hex(), originHex),
+			want:   fmt.Sprintf(`{"beforeEVMTransfers":[{"purpose":"feePayment","from":"%s","to":null,"value":"0x13880"}],"afterEVMTransfers":[{"purpose":"gasRefund","from":null,"to":"%s","value":"0xdce2"},{"purpose":"tip","from":null,"to":"0x0000000000000000000000000000000000000000","value":"0x5b9e"}],"balanceChanges":[{"addr":"%s","prev":"0x1c6bf52634000","new":"0x1c6bf52620780","reason":"unspecified"},{"addr":"%s","prev":"0x1c6bf52620780","new":"0x1c6bf5262e462","reason":"unspecified"},{"addr":"0x0000000000000000000000000000000000000000","prev":"0x0","new":"0x5b9e","reason":"unspecified"}],"from":"%s","gas":"0x13880","gasUsed":"0x5b9e","to":"0x00000000000000000000000000000000deadbeef","input":"0x","logs":[{"address":"0x00000000000000000000000000000000deadbeef","topics":[],"data":"0x000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000","position":"0x0"}],"value":"0x0","type":"CALL"}`, origin.Hex(), origin.Hex(), origin.Hex(), origin.Hex(), originHex),
 		},
 		{
 			// Leads to OOM on the prestate tracer

eth/tracers/internal/tracetest/testdata/call_tracer/blob_tx.json

@@ -56,17 +56,15 @@
   },
   "input": "0x03f8b1820539806485174876e800825208940c2c51a0990aee1d73c1228de1586883415575088080c083020000f842a00100c9fbdf97f747e85847b4f3fff408f89c26842f77c882858bf2c89923849aa00138e3896f3c27f2389147507f8bcec52028b0efca6ee842ed83c9158873943880a0dbac3f97a532c9b00e6239b29036245a5bfbb96940b9d848634661abee98b945a03eec8525f261c2e79798f7b45a5d6ccaefa24576d53ba5023e919b86841c0675",
   "result": {
-    "beforeEVMTransfers":
-    [
+    "beforeEVMTransfers": [
       {
         "purpose": "feePayment",
         "from": "0x0c2c51a0990AeE1d73C1228de158688341557508",
         "to": null,
         "value": "0x2de364958"
       }
     ],
-    "afterEVMTransfers":
-    [
+    "afterEVMTransfers": [
       {
         "purpose": "gasRefund",
         "from": null,
@@ -80,6 +78,20 @@
         "value": "0x200b20"
       }
     ],
+    "balanceChanges": [
+      {
+        "addr": "0x0c2c51a0990AeE1d73C1228de158688341557508",
+        "prev": "0xde0b6b3a7640000",
+        "new": "0xde0b6b0c92db6a8",
+        "reason": "unspecified"
+      },
+      {
+        "addr": "0x0000000000000000000000000000000000000000",
+        "prev": "0x272e0528",
+        "new": "0x274e1048",
+        "reason": "unspecified"
+      }
+    ],
     "from": "0x0c2c51a0990aee1d73c1228de158688341557508",
     "gas": "0x5208",
     "gasUsed": "0x5208",
@@ -88,4 +100,4 @@
     "value": "0x0",
     "type": "CALL"
   }
-}
+}

eth/tracers/internal/tracetest/testdata/call_tracer/create.json

@@ -68,6 +68,20 @@
         "value": "0x2a0383e2a65c00"
       }
     ],
+    "balanceChanges": [
+      {
+        "addr": "0x13e4ACeFE6a6700604929946E70E6443E4E73447",
+        "prev": "0xcf3e0938579f000",
+        "new": "0xcc9dd0fa2d39400",
+        "reason": "unspecified"
+      },
+      {
+        "addr": "0xD049bfd667cB46Aa3Ef5Df0dA3e57DB3Be39E511",
+        "prev": "0x0",
+        "new": "0x2a0383e2a65c00",
+        "reason": "unspecified"
+      }
+    ],
     "from": "0x13e4acefe6a6700604929946e70e6443e4e73447",
     "gas": "0x897be",
     "gasUsed": "0x897be",
@@ -77,4 +91,4 @@
     "type": "CREATE",
     "value": "0x0"
   }
-}
+}

eth/tracers/internal/tracetest/testdata/call_tracer/deep_calls.json

@@ -131,7 +131,27 @@
         "value": "0x700fefccd9800"
       }
     ],
-	"calls": [
+    "balanceChanges": [
+      {
+        "addr": "0x70C9217D814985faEF62B124420F8dFbdDD96433",
+        "prev": "0x4ef436dcbda6cd4a",
+        "new": "0x4ee2736385c64d4a",
+        "reason": "unspecified"
+      },
+      {
+        "addr": "0x70C9217D814985faEF62B124420F8dFbdDD96433",
+        "prev": "0x4ee2736385c64d4a",
+        "new": "0x4eed35ddc0d9354a",
+        "reason": "unspecified"
+      },
+      {
+        "addr": "0x1977C248e1014Cc103929Dd7f154199C916E39Ec",
+        "prev": "0x0",
+        "new": "0x700fefccd9800",
+        "reason": "unspecified"
+      }
+    ],
+    "calls": [
       {
         "from": "0xc212e03b9e060e36facad5fd8f4435412ca22e6b",
         "gas": "0x31217",
@@ -428,4 +448,4 @@
     "type": "CALL",
     "value": "0x0"
   }
-}
+}

eth/tracers/internal/tracetest/testdata/call_tracer/delegatecall.json

@@ -84,6 +84,26 @@
         "value": "0x371a55e8d6800"
       }
     ],
+    "balanceChanges": [
+      {
+        "addr": "0xA529806c67cc6486d4D62024471772F47F6FD672",
+        "prev": "0x67820e39ac8fe9800",
+        "new": "0x6774bb9ec2a789800",
+        "reason": "unspecified"
+      },
+      {
+        "addr": "0xA529806c67cc6486d4D62024471772F47F6FD672",
+        "prev": "0x6774bb9ec2a789800",
+        "new": "0x6781d71f56a713000",
+        "reason": "unspecified"
+      },
+      {
+        "addr": "0x5659922cE141EedBC2733678f9806c77b4eEBEE8",
+        "prev": "0x0",
+        "new": "0x371a55e8d6800",
+        "reason": "unspecified"
+      }
+    ],
     "calls": [
       {
         "calls": [
@@ -116,4 +136,4 @@
     "type": "CALL",
     "value": "0x0"
   }
-}
+}

eth/tracers/internal/tracetest/testdata/call_tracer/inner_create_oog_outer_throw.json

@@ -76,7 +76,21 @@
         "value": "0x2aa1efb94e0000"
       }
     ],
-	"calls": [
+    "balanceChanges": [
+      {
+        "addr": "0xE4A13Bc304682a903e9472F469C33801dd18d9E8",
+        "prev": "0x33c763c929f62c4f",
+        "new": "0x339cc1d970a82c4f",
+        "reason": "unspecified"
+      },
+      {
+        "addr": "0x1585936b53834b021f68CC13eEeFdEc2EfC8e724",
+        "prev": "0x0",
+        "new": "0x2aa1efb94e0000",
+        "reason": "unspecified"
+      }
+    ],
+    "calls": [
       {
         "error": "contract creation code storage out of gas",
         "from": "0x1d3ddf7caf024f253487e18bc4a15b1a360c170a",
@@ -96,4 +110,4 @@
     "type": "CALL",
     "value": "0x0"
   }
-}
+}

eth/tracers/internal/tracetest/testdata/call_tracer/inner_instafail.json

@@ -72,22 +72,44 @@
         "value": "0x216e3433f7200"
       }
     ],
-	"type": "CALL",
+    "balanceChanges": [
+      {
+        "addr": "0x66fdfd05e46126A07465aD24e40cc0597BC1ef31",
+        "prev": "0x229ebbb36c3e0f20",
+        "new": "0x229589d6991e3d20",
+        "reason": "unspecified"
+      },
+      {
+        "addr": "0x66fdfd05e46126A07465aD24e40cc0597BC1ef31",
+        "prev": "0x229589d6991e3d20",
+        "new": "0x229ca4d028fe9d20",
+        "reason": "unspecified"
+      },
+      {
+        "addr": "0xc822ef32e6d26E170B70Cf761e204c1806265914",
+        "prev": "0x0",
+        "new": "0x216e3433f7200",
+        "reason": "unspecified"
+      }
+    ],
+    "type": "CALL",
     "from": "0x66fdfd05e46126a07465ad24e40cc0597bc1ef31",
     "to": "0x6c06b16512b332e6cd8293a2974872674716ce18",
     "value": "0x0",
     "gas": "0x1f97e",
     "gasUsed": "0x72de",
     "input": "0x2e1a7d4d00000000000000000000000000000000000000000000000014d1120d7b160000",
-    "calls": [{
-      "from":"0x6c06b16512b332e6cd8293a2974872674716ce18",
-      "gas":"0x8fc",
-      "gasUsed":"0x0",
-      "to":"0x66fdfd05e46126a07465ad24e40cc0597bc1ef31",
-      "input":"0x",
-      "error":"insufficient balance for transfer",
-      "value":"0x14d1120d7b160000",
-      "type":"CALL"
-    }]
+    "calls": [
+      {
+        "from": "0x6c06b16512b332e6cd8293a2974872674716ce18",
+        "gas": "0x8fc",
+        "gasUsed": "0x0",
+        "to": "0x66fdfd05e46126a07465ad24e40cc0597bc1ef31",
+        "input": "0x",
+        "error": "insufficient balance for transfer",
+        "value": "0x14d1120d7b160000",
+        "type": "CALL"
+      }
+    ]
   }
-}
+}