besu-eth · MadelineMurray · Feb 26, 2020 · Feb 17, 2020 · Feb 20, 2020 · Feb 26, 2020
diff --git a/docs/Concepts/Transactions/Trace-Types.md b/docs/Concepts/Transactions/Trace-Types.md
@@ -0,0 +1,146 @@
+description: Tracing transactions
+<!--- END of page meta data -->
+
+# Transaction Trace Types  
+
+When using [`trace_replayBlockTransactions`](../../Reference/API-Methods.md#trace_replayblocktransactions)
+the trace options are [`trace`](#trace), [`vmTrace`](#vmtrace), and [`stateDiff`](#statediff).  
+
+## trace  
+
+Ordered list of calls to other contracts excluding precompiled contracts. 
+
+```json tab="trace Example"
+"trace":[ 
+  { 
+    "action":{ 
+      "callType":"call",
+      "from":"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73",
+      "gas":"0xffadea",
+      "input":"0x",
+      "to":"0x0100000000000000000000000000000000000000",
+      "value":"0x0"
+    },
+    "result":{ 
+      "gasUsed":"0x1e",
+      "output":"0x"
+    },
+    "subtraces":0,
+    "traceAddress":[      
+    ],
+    "type":"call"
+  }
+]
+```
+
+| Key            | Value                                                                                |
+|----------------| --------------------------------------------------------------------------------------|
+| `action`       | Transaction details.    
+| `callType`     | Indicates whether the transaction is `call` or `create`.                 
+| `from`         | Address from which transaction was sent. 
+| `gas`          | Gas provided by sender. 
+| `input`        | Transaction data.  
+| `to`           | Target of the transaction. 
+| `value`        | Value transferred in transaction.   
+| `result`       | Transaction result.  
+| `gasUsed`      | Gas used by the transaction. Includes any refunds of unused gas. 
+| `output`       | Return value of contract call. Contains only the actual value sent by a `RETURN` operation.  If a `RETURN` was not executed, the output is empty bytes.
+| `subTraces`    | Traces of contract calls made by the transaction. 
+| `traceAddress` | Tree list address of where the call occurred, address of the parents, and order of the current sub call. 
+| `type`         | Indicates whether the transaction is a `CALL` or `CREATE` series operation. 
+
+## vmTrace
+
+Ordered list of EVM actions when processing the transaction. 
+
+Besu only reports actual data returned from a `RETURN` opcode. Besu does not 
+return the contents of the reserved output space for the call operations. As a result: 
+
+* Besu reports null when a call operation ends because of a `STOP`, `HALT`, `REVERT`, running out of 
+instructions, or any exceptional halts.
+* When a `RETURN` operation returns data of a different length to the space reserved by the call, only
+the data passed to the `RETURN` operation is reported. Besu does not include pre-existing memory data
+or trim the returned data.
+
+For out of gas operations, Besu reports the operation that caused the out of gas exception including
+the calculated gas cost. No `ex` values are reported because the operation is not executed. 
+
+```json tab="vmTrace Example"
+"vmTrace":{
+  "code":"0x7f3940be4289e4c3587d88c1856cc95352461992db0a584c281226faefe560b3016000527f14c4d2c102bdeb2354bfc3dc96a95e4512cf3a8461e0560e2272dbf884ef3905601052600851",
+  "ops":[ 
+    { 
+    "cost":3,
+    "ex":{ 
+      "mem":null,
+      "push":[ 
+        "0x8"
+      ],
+      "store":null,
+      "used":16756175
+    },
+    "pc":72,
+    "sub":null
+    },
+    ...
+  ]
+}
+```
+
+| Key       | Value                                                                                |
+|-----------| --------------------------------------------------------------------------------------|
+| `code`    | Code executed by the EVM.  
+| `ops`     | Sequence of EVM operations (opcodes) executed in the transaction.                
+| `cost`    | Gas cost of the opcode. Includes memory expansion costs but not gas refunds. For precompiled contract calls, reports only the actual cost. 
+| `ex`      | Executed operations. 
+| `mem`     | Memory read or written by the operation. 
+| `push`    | Adjusted stack items. For swap, includes all intermediate values and end result. Otherwise, is the value pushed onto stack. 
+| `store`   | Account storage written by the operation.  
+| `used`    | Remaining gas taking into account the all but 1/64th rule for calls. 
+| `pc`      | Program counter.
+| `sub`     | Sub call operations. 
+
+## stateDiff
+
+State changes in the requested block for each transaction represented as 
+a map of accounts to an object. The balance, code, nonce, and storage changes are enumerated
+from immediately before the transaction to after the transaction.  For the `key:value` pairs:  
+
+* `+` indicates the field didn’t exist before and now has the specified value
+* `-` indicates the value was deleted
+* `*` has a from and a to value.
+
+An absent value is distinct from zero when accounts or storage are created or cleared.
+
+```json tab="stateDiff Example" 
+"stateDiff":{
+  "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73":{ 
+    "balance":{ 
+      "*":{ 
+        "from":"0xffffffffffffffffffffffffffffffffc3e12a20b",
+        "to":"0xffffffffffffffffffffffffffffffffc3dc5f091"
+      }
+    },
+    "code":"=",
+    "nonce":{ 
+      "*":{ 
+        "from":"0x14",
+        "to":"0x15"
+      }
+    },
+    "storage":{              
+    }
+  }
+}
+``` 
+
+| Key            | Value                                                                                |
+|-----------     | --------------------------------------------------------------------------------------|
+| `balance`      | Change of balance event.
+| `balance.from` | Balance before transaction.
+| `balance.to`   | Balance after transaction. 
+| `code`         | Changes to code. None in this example.   
+| `nonce`        | Change of nonce.  
+| `nonce.from`   | Nonce before transaction.  
+| `nonce.to`     | Nonce after transaction.  
+| `storage`      | Changes to storage. None in this example.   
diff --git a/docs/HowTo/Troubleshoot/Trace-Transactions.md b/docs/HowTo/Troubleshoot/Trace-Transactions.md
@@ -0,0 +1,19 @@
+description: How to trace transactions
+<!--- END of page meta data -->
+
+# Trace Transactions 
+
+Use the [`TRACE` API](../../Reference/API-Methods.md#trace-methods) to get detailed information about 
+transaction processing. Enable the [`TRACE` API](../../Reference/API-Methods.md#trace-methods) using 
+the [`-rpc-http-api`](../../Reference/CLI/CLI-Syntax.md#rpc-http-api) or [`rpc-ws-api`](../../Reference/CLI/CLI-Syntax.md#rpc-ws-api) 
+command line options. 
+
+Use the [`trace_replayBlockTransactions`](../../Reference/API-Methods.md#trace_replayblocktransactions) 
+JSON RPC API method and specify the trace types required. Options are [`trace`, `vmTrace`, or `stateDiff`](../../Concepts/Transactions/Trace-Types.md). 
+
+Your node must be an archive node (that is, synchronised without pruning or fast sync)
+or the requested block must be within the last 1024 blocks. 
+
+!!! important  
+    The `TRACE` API is an early access feature in 1.4. The return values may change between v1.4 and
+    v1.5. 
diff --git a/docs/Reference/API-Methods.md b/docs/Reference/API-Methods.md
@@ -3103,6 +3103,8 @@ If the boolean value is `true`, the proposal is to add a signer. If `false`, the
 !!! note
     The `DEBUG` API methods are not enabled by default for JSON-RPC. Use the [`--rpc-http-api`](CLI/CLI-Syntax.md#rpc-http-api)
     or [`--rpc-ws-api`](CLI/CLI-Syntax.md#rpc-ws-api) options to enable the `DEBUG` API methods.
+
+    The DEBUG API is an more verbose alternative to the [TRACE API](#trace-methods). 
 
 ### debug_accountRange
 
@@ -3825,7 +3827,6 @@ parameter to the latest block.
     }
     ```
 
-
 ## Permissioning Methods
 
 The permissioning API methods are used for [local](../HowTo/Limit-Access/Local-Permissioning.md) permissioning only.
@@ -4142,6 +4143,116 @@ None
     }
     ```
 
+## Trace Methods
+
+!!! note
+    The `TRACE` API methods are not enabled by default for JSON-RPC. Use the [`--rpc-http-api`](CLI/CLI-Syntax.md#rpc-http-api)
+    or [`--rpc-ws-api`](CLI/CLI-Syntax.md#rpc-ws-api) options to enable the `TRACE` API methods.
+
+    The TRACE API is an more concise alternative to the [DEBUG API](#debug-methods).
+
+### trace_replayBlockTransactions
+
+Provides transaction processing tracing.
+
+!!! important 
+    Your node must be an archive node (that is, synchronised without pruning or fast sync)
+    or the requested block must be within the last 1024 blocks. 
+
+**Parameters**
+
+`quantity|tag` - Integer representing a block number or one of the string tags `latest`, `earliest`, 
+or `pending`, as described in [Block Parameter](../HowTo/Interact/APIs/Using-JSON-RPC-API.md#block-parameter).
+
+`array of strings` - Tracing options are [`trace`, `vmTrace`, and `stateDiff`](../Concepts/Transactions/Trace-Types.md). 
+Specify any combination of the three options including none of them.   
+
+**Returns**
+
+`result` - Array of [transaction trace objects](API-Objects.md#transaction-trace-object) containing one object 
+per transaction in the order the transactions were executed. 
+
+!!! example
+    ```bash tab="curl HTTP request"
+    curl -X POST --data '{"jsonrpc": "2.0", "method": "trace_replayBlockTransactions","params": ["0x12",["trace","vmTrace","stateDiff"]],"id": 1}' http://127.0.0.1:8545
+    ```
+
+    ```bash tab="wscat WS request"
+    {"jsonrpc": "2.0", "method": "trace_replayBlockTransactions","params": ["0x12",["trace","vmTrace","stateDiff"]],"id": 1}
+    ```
+
+    ```json tab="JSON result"
+    {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "result":[ 
+          { 
+            "output":"0x",
+            "vmTrace":{
+              "code":"0x7f3940be4289e4c3587d88c1856cc95352461992db0a584c281226faefe560b3016000527f14c4d2c102bdeb2354bfc3dc96a95e4512cf3a8461e0560e2272dbf884ef3905601052600851",
+              "ops":[ 
+                { 
+                  "cost":3,
+                  "ex":{ 
+                    "mem":null,
+                    "push":[ 
+                      "0x8"
+                    ],
+                    "store":null,
+                    "used":16756175
+                  },
+                  "pc":72,
+                  "sub":null
+                },
+                ...
+              ]
+            },
+            "trace":[ 
+              { 
+                "action":{ 
+                  "callType":"call",
+                  "from":"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73",
+                  "gas":"0xffadea",
+                  "input":"0x",
+                  "to":"0x0100000000000000000000000000000000000000",
+                  "value":"0x0"
+                },
+                "result":{ 
+                  "gasUsed":"0x1e",
+                  "output":"0x"
+                },
+                "subtraces":0,
+                "traceAddress":[      
+                ],
+                "type":"call"
+              }
+            ],
+            "stateDiff":{
+              "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73":{ 
+                "balance":{ 
+                  "*":{ 
+                    "from":"0xffffffffffffffffffffffffffffffffc3e12a20b",
+                    "to":"0xffffffffffffffffffffffffffffffffc3dc5f091"
+                  }
+                },
+                "code":"=",
+                "nonce":{ 
+                  "*":{ 
+                    "from":"0x14",
+                    "to":"0x15"
+                  }
+                },
+                "storage":{              
+                }
+              }
+            },
+            "transactionHash":"0x2a5079cc535c429f668f13a7fb9a28bdba6831b5462bd04f781777b332a8fcbd",
+          },
+          {...}
+        ]
+    }
+    ```
+
 ## EEA Methods
 
 !!! note