book(jsonrpc): add section for address namespace

book/SUMMARY.md

@@ -22,6 +22,7 @@
    1. [trace](./jsonrpc/trace.md)
    1. [admin](./jsonrpc/admin.md)
    1. [rpc](./jsonrpc/rpc.md)
+   1. [address](./jsonrpc/address.md)
 1. [CLI Reference](./cli/cli.md)
    1. [reth node](./cli/node.md)
    1. [reth init](./cli/init.md)

book/jsonrpc/address.md

@@ -0,0 +1,86 @@
+# `address` Namespace
+
+The `address` API provides methods to discover transactions relevant to particular addresses.
+
+Once discovered, transactions can be obtained and examined using methods in other namespaces.
+
+## Appearances
+A relevant transaction is called an "appearance" and is defined
+here: <https://github.com/ethereum/execution-apis/pull/456>
+
+A set of appearances is a collection of transactions in which the address is involved in
+an important way. An appearance includes:
+- Sender or recipient of ether or tokens
+- Contract caller or callee
+- Contract deployer or deployed contract
+- Block reward for block producer or miner/uncle
+- Consensus layer withdrawal
+
+An appearance is a transaction identifier consisting of a block number and transaction index.
+
+## Node Size
+> Note: The `address` namespace increases the node database size
+
+The `address` namespace is separate because it involves the creation of additional database
+tables for the index that maps addresses to appearances. Users may opt in to the namespace to
+trigger the creation of the index and enable the associated JSON-RPC methods.
+
+## `address_getAppearances`
+
+Returns a set of transaction identifiers relevant to an address.
+
+See also: <https://github.com/ethereum/execution-apis/pull/453>
+
+| Client | Method invocation                                     |
+|--------|-------------------------------------------------------|
+| RPC    | `{"method": "address_getAppearances", "params": [address, opts]}` |
+
+
+
+The block range can optionally be specified either by block number or tag (`latest`, `finalized`, `safe`, `earliest`, `pending`) as the second argument.
+
+| Client | Method invocation                                     |
+|--------|-------------------------------------------------------|
+| RPC    | `{"method": "address_getAppearances", "params": [address, {"firstBlock": block, "lastBlock": block}}]}` |
+
+### Examples
+
+Discover appearances for address `0x30a4...1382`. Returns multiple transactions, the first is in block `14040913` (index `230`), the last is in block `17572135` (index `43`). Those
+transactions can now be examined more closely using other JSON-RPC methods.
+```js
+// > {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x30a4639850b3ddeaaca4f06280aa751682f11382"]}
+{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "result": [
+    {
+      "blockNumber": "0xd63f51",
+      "transactionIndex": "0xe6"
+    },
+    ... // ommitted
+    {
+      "blockNumber": "0x10c2127",
+      "transactionIndex": "0x2b"
+    }
+  ]
+}
+```
+
+Discover appearances for address `0x30a4...1382`, specifically between blocks `17190873` and `17190889`. Two transactions are returned.
+```js
+// > {"jsonrpc":"2.0","id":1,"method":"address_getAppearances","params":["0x30a4639850b3ddeaaca4f06280aa751682f11382",{"firstBlock":"0x1064fd9","lastBlock":"0x1064fe9"}]}
+{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "result": [
+    {
+      "blockNumber": "0x1064fd9",
+      "transactionIndex": "0x5f"
+    },
+    {
+      "blockNumber": "0x1064fe9",
+      "transactionIndex": "0x59"
+    }
+  ]
+}
+```

book/jsonrpc/debug.md

@@ -57,7 +57,7 @@ The `debug_traceBlock` method will return a full stack trace of all invoked opco
 This expects an RLP-encoded block.
 
 > **Note**
-> 
+>
 > The parent of this block must be present, or it will fail.
 
 | Client | Method invocation                                       |

book/jsonrpc/intro.md

@@ -12,16 +12,17 @@ Each namespace must be explicitly enabled.
 
 The methods are grouped into namespaces, which are listed below:
 
-| Namespace               | Description                                                                                            | Sensitive |
-|-------------------------|--------------------------------------------------------------------------------------------------------|-----------|
-| [`eth`](./eth.md)       | The `eth` API allows you to interact with Ethereum.                                                    | Maybe     |
-| [`web3`](./web3.md)     | The `web3` API provides utility functions for the web3 client.                                         | No        |
-| [`net`](./net.md)       | The `net` API provides access to network information of the node.                                      | No        |
-| [`txpool`](./txpool.md) | The `txpool` API allows you to inspect the transaction pool.                                           | No        |
-| [`debug`](./debug.md)   | The `debug` API provides several methods to inspect the Ethereum state, including Geth-style traces.   | No        |
-| [`trace`](./trace.md)   | The `trace` API provides several methods to inspect the Ethereum state, including Parity-style traces. | No        |
-| [`admin`](./admin.md)   | The `admin` API allows you to configure your node.                                                     | **Yes**   |
-| [`rpc`](./rpc.md)       | The `rpc` API provides information about the RPC server and its modules.                               | No        |
+| Namespace                 | Description                                                                                            | Sensitive |
+|---------------------------|--------------------------------------------------------------------------------------------------------|-----------|
+| [`eth`](./eth.md)         | The `eth` API allows you to interact with Ethereum.                                                    | Maybe     |
+| [`web3`](./web3.md)       | The `web3` API provides utility functions for the web3 client.                                         | No        |
+| [`net`](./net.md)         | The `net` API provides access to network information of the node.                                      | No        |
+| [`txpool`](./txpool.md)   | The `txpool` API allows you to inspect the transaction pool.                                           | No        |
+| [`debug`](./debug.md)     | The `debug` API provides several methods to inspect the Ethereum state, including Geth-style traces.   | No        |
+| [`trace`](./trace.md)     | The `trace` API provides several methods to inspect the Ethereum state, including Parity-style traces. | No        |
+| [`admin`](./admin.md)     | The `admin` API allows you to configure your node.                                                     | **Yes**   |
+| [`rpc`](./rpc.md)         | The `rpc` API provides information about the RPC server and its modules.                               | No        |
+| [`address`](./address.md) | The `address` API provides methods for finding transactions relevant to address. Increases node size.  | No        |
 
 Note that some APIs are sensitive, since they can be used to configure your node (`admin`), or access accounts stored on the node (`eth`).
 
@@ -114,7 +115,7 @@ You can use `curl`, a programming language with a low-level library, or a tool l
 As a reminder, you need to run the command below to enable all of these APIs using an HTTP transport:
 
 ```bash
-RUST_LOG=info reth node --http --http.api "admin,debug,eth,net,trace,txpool,web3,rpc"
+RUST_LOG=info reth node --http --http.api "address,admin,debug,eth,net,trace,txpool,web3,rpc"
 ```
 
 This allows you to then call: