From 318c4faf27aeae35d6fcd8e12bbcacaf4ca347e3 Mon Sep 17 00:00:00 2001
From: Marco Peereboom <marco@peereboom.us>
Date: Thu, 18 Apr 2024 16:48:12 +0100
Subject: [PATCH 01/39] Add some more meat to the tbcd README

---
 cmd/tbcd/README.md | 57 ++++++++++++++++++++++++++++++++--------------
 1 file changed, 40 insertions(+), 17 deletions(-)

diff --git a/cmd/tbcd/README.md b/cmd/tbcd/README.md
index a529863a..55e5f37a 100644
--- a/cmd/tbcd/README.md
+++ b/cmd/tbcd/README.md
@@ -2,22 +2,30 @@
 
 ## Hemi Tiny Bitcoin Daemon
 
-tbcd is a very minimal bitcoin block downloader and indexer meant for embedding in other applications that require access to bitcoin data (blocks and txes).
+`tbcd` is a very minimal bitcoin block downloader and indexer daemon. It wraps the `tbc` service which is meant for embedding in other applications that require access to bitcoin data (blocks and txes). The daemon is primarily used as a network RPC endpoint.
 
-tbcd requires sufficient disk space for a full download of bitcoin block data on a fast (preferably ssd or better disk.
+The `tbc` downloads all bitcoin blocks and generates various indexes and thus requires a sufficiently large machine. Count on needing >8G of RAM, 4CPUs and using NVME disk.
 
-tbcd is build with the heminetwork makefile,  To build standalone (requires `go 1.21+`), type:
+As of April 18 2024, `testnet3` uses ~40G and `mainnet` >300G (XXX add exact number here)
+
+## Building
+
+tbcd is build with the heminetwork makefile,  To build standalone (requires `go 1.22+`), type:
 
 ``` sh
-cd heminetowkr/cmd/tbcd
+cd heminetwork/cmd/tbcd
 go build
 ```
 
-On some linux systems you may need to increase the number of open files allowed (particularly with slower disks) and the maximum stack size.  If you run into open file or OOM errors, in the shell you are going to run tbcd, run:
+## Environment
+
+On some systems you may need to increase the number of open files, memory and the maximum stack size.  If you run into open file or OOM errors, in the shell you are going to run tbcd, run:
 
 ```sh
 ulimit -n 8192
-ulimit -s 8192
+ulimit -s 16384
+ulimit -m unlimited
+ulimit -d unlimited
 ```
 
 You can confirm these settings wiht:
@@ -25,31 +33,46 @@ You can confirm these settings wiht:
 ```sh
 ulimit -a
 ```
+## Runtime settings
 
-For a full list of options:
+`tbcd` is meant to be run in the cloud and as such it only uses environment variables for runtime settings. They can be either be exported or included on the evocation of the binary.
+
+For a full list of runtime settings:
 
 ``` sh
 ./bin/tbcd --help
-```
-
-You can change the file storage with:
+Hemi Tiny Bitcoin Daemon: v0.1.0-pre+3eb1bab15
+Usage:
+        help (this help)
+Environment:
+        TBC_ADDRESS           : address port to listen on (default: localhost:8082)
+        TBC_AUTO_INDEX        : enable auto utxo and tx indexes (default: true)
+        TBC_BLOCK_SANITY      : enable/disable block sanity checks before inserting (default: false)
+        TBC_LEVELDB_HOME      : data directory for leveldb (default: ~/.tbcd)
+        TBC_LOG_LEVEL         : loglevel for various packages; INFO, DEBUG and TRACE (default: tbcd=INFO;tbc=INFO;level=INFO)
+        TBC_MAX_CACHED_TXS    : maximum cached utxos and/or txs during indexing (default: 1000000)
+        TBC_NETWORK           : bitcoin network; mainnet or testnet3 (default: testnet3)
+        TBC_PROMETHEUS_ADDRESS: address and port tbcd prometheus listens on 
 
-``` sh
-export TBC_LEVELDB_HOME=/path/to/files
 ```
 
-Specify the network with
+Run with:
 
 ``` sh
-export TBC_NETWORK=mainnet
+./bin/tbcd
 ```
 
-Then run with:
+## RPC endpoints
 
-``` sh
-./bin/tbcd
+When `TBC_ADDRESS` is specified the daemon listen on the provided URI. The RPC is websockets based that uses a standard request/response driven model.
+
+The RPC endpoints are:
+``` Go
+XXX point to api or write it in human langiage here?
 ```
 
+`./cmd/hemictl` is the reference implementation of the websocket RPC.
+
 ### License
 
 This project is licensed under the [MIT License](../../LICENSE).

From 52bdf3435303b01edcc4e0d7e7ae60ba6f5afda3 Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Fri, 19 Apr 2024 03:06:45 +1000
Subject: [PATCH 02/39] Tidy up wording and sections in tbcd readme

---
 cmd/tbcd/README.md | 114 ++++++++++++++++++++++++++++-----------------
 1 file changed, 72 insertions(+), 42 deletions(-)

diff --git a/cmd/tbcd/README.md b/cmd/tbcd/README.md
index 55e5f37a..c1d8c7b4 100644
--- a/cmd/tbcd/README.md
+++ b/cmd/tbcd/README.md
@@ -1,79 +1,109 @@
-# tbcd
+# Hemi Tiny Bitcoin Daemon
 
-## Hemi Tiny Bitcoin Daemon
+`tbcd` is a very minimal Bitcoin block downloader and indexer daemon. It wraps the `tbc` service which is meant for
+embedding in other applications that require access to Bitcoin data (blocks and TXes). The daemon is primarily used as a
+network RPC endpoint.
 
-`tbcd` is a very minimal bitcoin block downloader and indexer daemon. It wraps the `tbc` service which is meant for embedding in other applications that require access to bitcoin data (blocks and txes). The daemon is primarily used as a network RPC endpoint.
+## System requirements
 
-The `tbc` downloads all bitcoin blocks and generates various indexes and thus requires a sufficiently large machine. Count on needing >8G of RAM, 4CPUs and using NVME disk.
+The `tbc` server downloads all Bitcoin blocks and generates various indexes and thus requires a large amount of
+available disk space.
 
-As of April 18 2024, `testnet3` uses ~40G and `mainnet` >300G (XXX add exact number here)
+Running `tbc` will likely require at least:
+ - 4 CPU cores
+ - 8 GiB RAM
+ - NVMe disk
+
+As of April 18, 2024, `testnet3` uses ~40 GiB and `mainnet` >300 GiB of disk space. <!-- XXX: add exact number here -->
 
 ## Building
 
-tbcd is build with the heminetwork makefile,  To build standalone (requires `go 1.22+`), type:
+To build `tbcd`, you must have the following installed:
+ - Go v1.22 or newer
+
+### Makefile
+
+To build `tbcd` with the heminetwork Makefile (requires `make` to be installed):
+
+```shell
+cd heminetwork
 
-``` sh
-cd heminetwork/cmd/tbcd
-go build
+# Build (output binary will be written to bin/tbcd or bin/tbcd.exe)
+make tbcd
+```
+
+### Standalone
+
+To build `tbcd` without using the heminetwork Makefile:
+
+```shell
+cd heminetwork
+
+# Build (output binary will be called tbcd or tbcd.exe)
+go build ./cmd/tbcd/
+
+# Install (output binary will be written to your GOBIN directory)
+go install ./cmd/tbcd/
 ```
 
 ## Environment
 
-On some systems you may need to increase the number of open files, memory and the maximum stack size.  If you run into open file or OOM errors, in the shell you are going to run tbcd, run:
+On some systems, you may need to increase the limits for the number of open files, memory and the maximum stack size.
 
-```sh
+If you run into open file or OOM errors while running `tbcd`, run the following commands in the shell that you will
+run `tbcd` in:
+
+```shell
 ulimit -n 8192
 ulimit -s 16384
 ulimit -m unlimited
 ulimit -d unlimited
 ```
 
-You can confirm these settings wiht:
+You can confirm these settings with:
 
-```sh
+```shell
 ulimit -a
 ```
-## Runtime settings
 
-`tbcd` is meant to be run in the cloud and as such it only uses environment variables for runtime settings. They can be either be exported or included on the evocation of the binary.
-
-For a full list of runtime settings:
-
-``` sh
-./bin/tbcd --help
-Hemi Tiny Bitcoin Daemon: v0.1.0-pre+3eb1bab15
-Usage:
-        help (this help)
-Environment:
-        TBC_ADDRESS           : address port to listen on (default: localhost:8082)
-        TBC_AUTO_INDEX        : enable auto utxo and tx indexes (default: true)
-        TBC_BLOCK_SANITY      : enable/disable block sanity checks before inserting (default: false)
-        TBC_LEVELDB_HOME      : data directory for leveldb (default: ~/.tbcd)
-        TBC_LOG_LEVEL         : loglevel for various packages; INFO, DEBUG and TRACE (default: tbcd=INFO;tbc=INFO;level=INFO)
-        TBC_MAX_CACHED_TXS    : maximum cached utxos and/or txs during indexing (default: 1000000)
-        TBC_NETWORK           : bitcoin network; mainnet or testnet3 (default: testnet3)
-        TBC_PROMETHEUS_ADDRESS: address and port tbcd prometheus listens on 
+## Runtime settings
 
+`tbcd` is designed to be run in cloud environments, as such it only uses environment variables for runtime settings.
+They can be either be exported or included on the evocation of the binary.
+
+To see a full list of runtime settings, execute `tbcd` with the `--help` flag:
+
+```shell
+/path/to/tbcd --help
+# Hemi Tiny Bitcoin Daemon: v0.1.0-pre+3eb1bab15
+# Usage:
+#         help (this help)
+# Environment:
+#         TBC_ADDRESS           : address port to listen on (default: localhost:8082)
+#         TBC_AUTO_INDEX        : enable auto utxo and tx indexes (default: true)
+#         TBC_BLOCK_SANITY      : enable/disable block sanity checks before inserting (default: false)
+#         TBC_LEVELDB_HOME      : data directory for leveldb (default: ~/.tbcd)
+#         TBC_LOG_LEVEL         : loglevel for various packages; INFO, DEBUG and TRACE (default: tbcd=INFO;tbc=INFO;level=INFO)
+#         TBC_MAX_CACHED_TXS    : maximum cached utxos and/or txs during indexing (default: 1000000)
+#         TBC_NETWORK           : bitcoin network; mainnet or testnet3 (default: testnet3)
+#         TBC_PROMETHEUS_ADDRESS: address and port tbcd prometheus listens on
 ```
 
-Run with:
+You can start the `tbcd` server by running:
 
-``` sh
-./bin/tbcd
+```shell
+/path/to/tbcd
 ```
 
 ## RPC endpoints
 
-When `TBC_ADDRESS` is specified the daemon listen on the provided URI. The RPC is websockets based that uses a standard request/response driven model.
+When the `TBC_ADDRESS` environment variable is set, the daemon listen on the provided address.
+The RPC protocol is WebSocket-based and uses a standard request/response model.
 
-The RPC endpoints are:
-``` Go
-XXX point to api or write it in human langiage here?
-```
+<!-- TODO -->
 
-`./cmd/hemictl` is the reference implementation of the websocket RPC.
+[`hemictl`](../../cmd/hemictl) is a reference implementation of an RPC client.
 
 ### License
 
 This project is licensed under the [MIT License](../../LICENSE).
-

From b9da4fdaa5d9ba78a28ec22325020664f0ee5e64 Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Fri, 19 Apr 2024 03:37:06 +1000
Subject: [PATCH 03/39] tbcd: add initial RPC docs

---
 cmd/tbcd/README.md | 115 +++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 111 insertions(+), 4 deletions(-)

diff --git a/cmd/tbcd/README.md b/cmd/tbcd/README.md
index c1d8c7b4..ff504c90 100644
--- a/cmd/tbcd/README.md
+++ b/cmd/tbcd/README.md
@@ -95,15 +95,122 @@ You can start the `tbcd` server by running:
 /path/to/tbcd
 ```
 
-## RPC endpoints
+## RPC commands
 
-When the `TBC_ADDRESS` environment variable is set, the daemon listen on the provided address.
-The RPC protocol is WebSocket-based and uses a standard request/response model.
+*Last updated April 19th, 2024.*
 
-<!-- TODO -->
+When the `TBC_ADDRESS` environment variable is set, the `tbcd` daemon listens on the provided address.
+The RPC protocol is WebSocket-based and uses a standard request/response model.
 
 [`hemictl`](../../cmd/hemictl) is a reference implementation of an RPC client.
 
+### Protocol
+
+The RPC protocol is WebSocket-based and uses JSON-encoded request/responses.
+The JSON data sent over WebSocket connections are called a "messages".
+
+A message has the format:
+```json
+{
+  "header": {
+    "command": "command-name",
+    "id": "request-id"
+  },
+  "payload": null
+}
+```
+
+#### Header
+
+The message header contains metadata:
+
+ - `command` is the name of the command being called.
+ - `id` is a string used to uniquely identify each request. Responses will have the same `id` as the request,
+    making it possible to match requests to responses. Message IDs should be randomly generated.
+
+#### Payload
+
+The payload type depends on the command being called.
+
+### Block Headers by Height
+
+#### Raw data
+
+| Type     | `command` value                              |
+|----------|----------------------------------------------|
+| Request  | tbcapi-block-headers-by-height-raw-request`  |
+| Response | tbcapi-block-headers-by-height-raw-response` |
+
+Example request message:
+
+```json
+{
+  "header": {
+    "command": "tbcapi-block-headers-best-raw-request",
+    "id": "68656d69"
+  }
+}
+```
+
+Example response message:
+
+```json
+{
+  "header": {
+    "command": "tbcapi-block-headers-best-raw-response",
+    "id": "68656d69"
+  },
+  "payload": {
+    "height": 2182000,
+    "block_headers": [
+      "0420002075089ac1ab1cab70cf6e6b774a86703a8d7127c0ebed1d3dfa2c00000000000086105509ec4a79457a400451290ad2a019fec4c76b47512623f1bb17a0ced76f38d82662bef4001b07d86700"
+    ]
+  }
+}
+```
+
+#### Serialised 
+
+| Type     | `command` value                          |
+|----------|------------------------------------------|
+| Request  | tbcapi-block-headers-by-height-request`  |
+| Response | tbcapi-block-headers-by-height-response` |
+
+Example request message:
+
+```json
+{
+  "header": {
+    "command": "tbcapi-block-headers-best-request",
+    "id": "68656d69"
+  }
+}
+```
+
+Example response message:
+
+```json
+{
+  "header": {
+    "command": "tbcapi-block-headers-best-response",
+    "id": "68656d69"
+  },
+  "payload": {
+    "height": 2587400,
+    "block_headers": [
+      {
+        "version": 536887296,
+        "prev_hash": "000000000000002bbbbec8f126dc76a82109d898383bca5013a2386c8675ce34",
+        "merkle_root": "b9d74efdafb5436330b47478b2df28251057da5a9bc11c5509410950253d4f0e",
+        "timestamp": 1713461092,
+        "bits": "192e17d5",
+        "nonce": 3365605040
+      }
+    ]
+  }
+}
+```
+
 ### License
 
 This project is licensed under the [MIT License](../../LICENSE).

From 9e6716625da59d7e1ee5ee8679d8f57e58dae850 Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Fri, 19 Apr 2024 03:38:55 +1000
Subject: [PATCH 04/39] Fix command table formatting

---
 cmd/tbcd/README.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/cmd/tbcd/README.md b/cmd/tbcd/README.md
index ff504c90..2904afbf 100644
--- a/cmd/tbcd/README.md
+++ b/cmd/tbcd/README.md
@@ -136,10 +136,10 @@ The payload type depends on the command being called.
 
 #### Raw data
 
-| Type     | `command` value                              |
-|----------|----------------------------------------------|
-| Request  | tbcapi-block-headers-by-height-raw-request`  |
-| Response | tbcapi-block-headers-by-height-raw-response` |
+| Type     | `command` value                               |
+|----------|-----------------------------------------------|
+| Request  | `tbcapi-block-headers-by-height-raw-request`  |
+| Response | `tbcapi-block-headers-by-height-raw-response` |
 
 Example request message:
 
@@ -171,10 +171,10 @@ Example response message:
 
 #### Serialised 
 
-| Type     | `command` value                          |
-|----------|------------------------------------------|
-| Request  | tbcapi-block-headers-by-height-request`  |
-| Response | tbcapi-block-headers-by-height-response` |
+| Type     | `command` value                           |
+|----------|-------------------------------------------|
+| Request  | `tbcapi-block-headers-by-height-request`  |
+| Response | `tbcapi-block-headers-by-height-response` |
 
 Example request message:
 

From e2782f8acef5afb339b60970d825287e9b54b792 Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Fri, 19 Apr 2024 03:49:04 +1000
Subject: [PATCH 05/39] Move RPC docs into separate files

---
 api/protocol/README.md |  30 +++++++++++
 api/tbcapi/README.md   |  91 ++++++++++++++++++++++++++++++++
 cmd/tbcd/README.md     | 116 -----------------------------------------
 3 files changed, 121 insertions(+), 116 deletions(-)
 create mode 100644 api/protocol/README.md
 create mode 100644 api/tbcapi/README.md

diff --git a/api/protocol/README.md b/api/protocol/README.md
new file mode 100644
index 00000000..ccb1deca
--- /dev/null
+++ b/api/protocol/README.md
@@ -0,0 +1,30 @@
+# RPC Protocol
+
+The RPC protocol used by Hemi's daemons is WebSocket-based and uses JSON-encoded request/responses.
+The JSON data sent over WebSocket connections are called a "messages".
+
+## Message format
+
+An RPC message has the format:
+
+```json
+{
+  "header": {
+    "command": "command-name",
+    "id": "request-id"
+  },
+  "payload": null
+}
+```
+
+### Header
+
+The message header contains metadata:
+
+- `command` is the name of the command being called.
+- `id` is a string used to uniquely identify each request. Responses will have the same `id` as the request,
+  making it possible to match requests to responses. Message IDs should be randomly generated.
+
+### Payload
+
+The payload type depends on the command being called. Please refer to the documentation for specific API you wish to use.
diff --git a/api/tbcapi/README.md b/api/tbcapi/README.md
new file mode 100644
index 00000000..eda24691
--- /dev/null
+++ b/api/tbcapi/README.md
@@ -0,0 +1,91 @@
+# Hemi Tiny Bitcoin Daemon RPC
+
+*Last updated April 19th, 2024.*
+
+When the `TBC_ADDRESS` environment variable is set, the `tbcd` daemon listens on the provided address.
+The RPC protocol is WebSocket-based and uses a standard request/response model.
+
+[`hemictl`](../../cmd/hemictl) is a reference implementation of an RPC client.
+
+## Protocol
+
+Please see [protocol/README.md](../protocol/README.md) for more information about the underlying RPC protocol.
+
+## Block Headers by Height
+
+### Raw data
+
+| Type     | `command` value                               |
+|----------|-----------------------------------------------|
+| Request  | `tbcapi-block-headers-by-height-raw-request`  |
+| Response | `tbcapi-block-headers-by-height-raw-response` |
+
+Example request message:
+
+```json
+{
+  "header": {
+    "command": "tbcapi-block-headers-best-raw-request",
+    "id": "68656d69"
+  }
+}
+```
+
+Example response message:
+
+```json
+{
+  "header": {
+    "command": "tbcapi-block-headers-best-raw-response",
+    "id": "68656d69"
+  },
+  "payload": {
+    "height": 2182000,
+    "block_headers": [
+      "0420002075089ac1ab1cab70cf6e6b774a86703a8d7127c0ebed1d3dfa2c00000000000086105509ec4a79457a400451290ad2a019fec4c76b47512623f1bb17a0ced76f38d82662bef4001b07d86700"
+    ]
+  }
+}
+```
+
+### Serialised
+
+| Type     | `command` value                           |
+|----------|-------------------------------------------|
+| Request  | `tbcapi-block-headers-by-height-request`  |
+| Response | `tbcapi-block-headers-by-height-response` |
+
+Example request message:
+
+```json
+{
+  "header": {
+    "command": "tbcapi-block-headers-best-request",
+    "id": "68656d69"
+  }
+}
+```
+
+Example response message:
+
+```json
+{
+  "header": {
+    "command": "tbcapi-block-headers-best-response",
+    "id": "68656d69"
+  },
+  "payload": {
+    "height": 2587400,
+    "block_headers": [
+      {
+        "version": 536887296,
+        "prev_hash": "000000000000002bbbbec8f126dc76a82109d898383bca5013a2386c8675ce34",
+        "merkle_root": "b9d74efdafb5436330b47478b2df28251057da5a9bc11c5509410950253d4f0e",
+        "timestamp": 1713461092,
+        "bits": "192e17d5",
+        "nonce": 3365605040
+      }
+    ]
+  }
+}
+```
diff --git a/cmd/tbcd/README.md b/cmd/tbcd/README.md
index 2904afbf..12ee0e0b 100644
--- a/cmd/tbcd/README.md
+++ b/cmd/tbcd/README.md
@@ -95,122 +95,6 @@ You can start the `tbcd` server by running:
 /path/to/tbcd
 ```
 
-## RPC commands
-
-*Last updated April 19th, 2024.*
-
-When the `TBC_ADDRESS` environment variable is set, the `tbcd` daemon listens on the provided address.
-The RPC protocol is WebSocket-based and uses a standard request/response model.
-
-[`hemictl`](../../cmd/hemictl) is a reference implementation of an RPC client.
-
-### Protocol
-
-The RPC protocol is WebSocket-based and uses JSON-encoded request/responses.
-The JSON data sent over WebSocket connections are called a "messages".
-
-A message has the format:
-```json
-{
-  "header": {
-    "command": "command-name",
-    "id": "request-id"
-  },
-  "payload": null
-}
-```
-
-#### Header
-
-The message header contains metadata:
-
- - `command` is the name of the command being called.
- - `id` is a string used to uniquely identify each request. Responses will have the same `id` as the request,
-    making it possible to match requests to responses. Message IDs should be randomly generated.
-
-#### Payload
-
-The payload type depends on the command being called.
-
-### Block Headers by Height
-
-#### Raw data
-
-| Type     | `command` value                               |
-|----------|-----------------------------------------------|
-| Request  | `tbcapi-block-headers-by-height-raw-request`  |
-| Response | `tbcapi-block-headers-by-height-raw-response` |
-
-Example request message:
-
-```json
-{
-  "header": {
-    "command": "tbcapi-block-headers-best-raw-request",
-    "id": "68656d69"
-  }
-}
-```
-
-Example response message:
-
-```json
-{
-  "header": {
-    "command": "tbcapi-block-headers-best-raw-response",
-    "id": "68656d69"
-  },
-  "payload": {
-    "height": 2182000,
-    "block_headers": [
-      "0420002075089ac1ab1cab70cf6e6b774a86703a8d7127c0ebed1d3dfa2c00000000000086105509ec4a79457a400451290ad2a019fec4c76b47512623f1bb17a0ced76f38d82662bef4001b07d86700"
-    ]
-  }
-}
-```
-
-#### Serialised 
-
-| Type     | `command` value                           |
-|----------|-------------------------------------------|
-| Request  | `tbcapi-block-headers-by-height-request`  |
-| Response | `tbcapi-block-headers-by-height-response` |
-
-Example request message:
-
-```json
-{
-  "header": {
-    "command": "tbcapi-block-headers-best-request",
-    "id": "68656d69"
-  }
-}
-```
-
-Example response message:
-
-```json
-{
-  "header": {
-    "command": "tbcapi-block-headers-best-response",
-    "id": "68656d69"
-  },
-  "payload": {
-    "height": 2587400,
-    "block_headers": [
-      {
-        "version": 536887296,
-        "prev_hash": "000000000000002bbbbec8f126dc76a82109d898383bca5013a2386c8675ce34",
-        "merkle_root": "b9d74efdafb5436330b47478b2df28251057da5a9bc11c5509410950253d4f0e",
-        "timestamp": 1713461092,
-        "bits": "192e17d5",
-        "nonce": 3365605040
-      }
-    ]
-  }
-}
-```
-
 ### License
 
 This project is licensed under the [MIT License](../../LICENSE).

From 4e649e591ff59b03c15412f32bdd677c0faffbdb Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Fri, 19 Apr 2024 04:01:32 +1000
Subject: [PATCH 06/39] Add RPC commands link to tbcd readme

---
 cmd/tbcd/README.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/cmd/tbcd/README.md b/cmd/tbcd/README.md
index 12ee0e0b..ca8de129 100644
--- a/cmd/tbcd/README.md
+++ b/cmd/tbcd/README.md
@@ -95,6 +95,13 @@ You can start the `tbcd` server by running:
 /path/to/tbcd
 ```
 
+## RPC commands
+
+When the `TBC_ADDRESS` environment variable is set, the `tbcd` daemon listens on the provided address.
+The RPC protocol is WebSocket-based and uses a standard request/response model.
+
+[Read more about the RPC protocol and available commands](../../api/tbcapi/README.md).
+
 ### License
 
 This project is licensed under the [MIT License](../../LICENSE).

From 379979de0c16beb9b1b47e0819cb1d846cf76e84 Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Fri, 19 Apr 2024 04:54:14 +1000
Subject: [PATCH 07/39] Add docs for block-headers-by-height, add more details

---
 api/tbcapi/README.md | 166 ++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 158 insertions(+), 8 deletions(-)

diff --git a/api/tbcapi/README.md b/api/tbcapi/README.md
index eda24691..90676994 100644
--- a/api/tbcapi/README.md
+++ b/api/tbcapi/README.md
@@ -11,6 +11,19 @@ The RPC protocol is WebSocket-based and uses a standard request/response model.
 
 Please see [protocol/README.md](../protocol/README.md) for more information about the underlying RPC protocol.
 
+### Serialised types
+
+#### Block Header
+
+A serialised block header has the following data:
+
+- `version` is the version of the block.
+- `prev_hash` is the hash of the previous block header in the blockchain.
+- `merkle_root` is the merkle tree reference to hash of all transactions for the block.
+- `timestamp` is the time the block was created, represented in Unix seconds.
+- `bits` is the difficulty target for the block.
+- `nonce` is the nonce used to generate the block.
+
 ## Block Headers by Height
 
 ### Raw data
@@ -20,29 +33,47 @@ Please see [protocol/README.md](../protocol/README.md) for more information abou
 | Request  | `tbcapi-block-headers-by-height-raw-request`  |
 | Response | `tbcapi-block-headers-by-height-raw-response` |
 
-Example request message:
+#### Request
+
+##### Payload
+
+- `height` is the height to at which block headers should be retrieved.
+
+##### Example
+
+An example request to retrieve block headers at height `43111`:
 
 ```json
 {
   "header": {
-    "command": "tbcapi-block-headers-best-raw-request",
+    "command": "tbcapi-block-headers-by-height-raw-request",
     "id": "68656d69"
+  },
+  "payload": {
+    "height": 43111
   }
 }
 ```
 
-Example response message:
+#### Response
+
+##### Payload
+
+- `block_headers` is an array of raw block headers encoded as hexadecimal strings.
+
+##### Example
+
+An example response for a request with id `68656d69` and height `43111`:
 
 ```json
 {
   "header": {
-    "command": "tbcapi-block-headers-best-raw-response",
+    "command": "tbcapi-block-headers-by-height-raw-response",
     "id": "68656d69"
   },
   "payload": {
-    "height": 2182000,
     "block_headers": [
-      "0420002075089ac1ab1cab70cf6e6b774a86703a8d7127c0ebed1d3dfa2c00000000000086105509ec4a79457a400451290ad2a019fec4c76b47512623f1bb17a0ced76f38d82662bef4001b07d86700"
+      "02000000cf31d5156c8ab752b91874d1072d4673b83ee3ed718d3cb4f461c410000000000ca43abadf59bee614186d30da42f56932dc2a53e6d920169b8577207f7b11fcfec3d750c0ff3f1c4f428f6a"
     ]
   }
 }
@@ -55,7 +86,117 @@ Example response message:
 | Request  | `tbcapi-block-headers-by-height-request`  |
 | Response | `tbcapi-block-headers-by-height-response` |
 
-Example request message:
+#### Request
+
+##### Payload
+
+- `height` is the height to at which block headers should be retrieved.
+
+##### Example
+
+An example request to retrieve the block headers at height `43111`:
+
+```json
+{
+  "header": {
+    "command": "tbcapi-block-headers-by-height-request",
+    "id": "68656d69"
+  },
+  "payload": {
+    "height": 43111
+  }
+}
+```
+
+#### Response
+
+##### Payload
+
+- `block_headers` is an array of [block headers](#block-header).
+
+##### Example
+
+An example response for a request with id `68656d69` and height `43111`:
+
+```json
+{
+  "header": {
+    "command": "tbcapi-block-headers-by-height-response",
+    "id": "68656d69"
+  },
+  "payload": {
+    "block_headers": [
+      {
+        "version": 2,
+        "prev_hash": "0000000010c461f4b43c8d71ede33eb873462d07d17418b952b78a6c15d531cf",
+        "merkle_root": "fc117b7f2077859b1620d9e6532adc3269f542da306d1814e6be59dfba3aa40c",
+        "timestamp": 1356317694,
+        "bits": "1c3fffc0",
+        "nonce": 1787773519
+      }
+    ]
+  }
+}
+```
+
+## Best Block Headers
+
+### Raw data
+
+| Type     | `command` value                          |
+|----------|------------------------------------------|
+| Request  | `tbcapi-block-headers-best-raw-request`  |
+| Response | `tbcapi-block-headers-best-raw-response` |
+
+#### Request
+
+An example request to retrieve the best block headers:
+
+```json
+{
+  "header": {
+    "command": "tbcapi-block-headers-best-raw-request",
+    "id": "68656d69"
+  }
+}
+```
+
+#### Response
+
+##### Payload
+
+- `height` is the best known height.
+- `block_headers` is an array of the best known block headers encoded as hexadecimal strings.
+
+##### Example
+
+An example response for a request with id `68656d69`, if the best height was `2182000`:
+
+```json
+{
+  "header": {
+    "command": "tbcapi-block-headers-best-raw-response",
+    "id": "68656d69"
+  },
+  "payload": {
+    "height": 2182000,
+    "block_headers": [
+      "0420002075089ac1ab1cab70cf6e6b774a86703a8d7127c0ebed1d3dfa2c00000000000086105509ec4a79457a400451290ad2a019fec4c76b47512623f1bb17a0ced76f38d82662bef4001b07d86700"
+    ]
+  }
+}
+```
+
+### Serialised
+
+| Type     | `command` value                      |
+|----------|--------------------------------------|
+| Request  | `tbcapi-block-headers-best-request`  |
+| Response | `tbcapi-block-headers-best-response` |
+
+#### Request
+
+An example request to retrieve the best block headers:
 
 ```json
 {
@@ -66,7 +207,16 @@ Example request message:
 }
 ```
 
-Example response message:
+#### Response
+
+##### Payload
+
+- `height` is the best known height.
+- `block_headers` is an array of best known [block headers](#block-header).
+
+##### Example
+
+An example response for a request with id `68656d69`, if the best height was `2587400`:
 
 ```json
 {

From 97b543dd934e270e0d1f325c6df63dcf376cc318 Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Tue, 23 Apr 2024 00:34:22 +1000
Subject: [PATCH 08/39] Add docs for balance-by-address

---
 api/tbcapi/README.md | 60 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/api/tbcapi/README.md b/api/tbcapi/README.md
index 90676994..f698b995 100644
--- a/api/tbcapi/README.md
+++ b/api/tbcapi/README.md
@@ -150,6 +150,8 @@ An example response for a request with id `68656d69` and height `43111`:
 
 #### Request
 
+##### Example
+
 An example request to retrieve the best block headers:
 
 ```json
@@ -196,6 +198,8 @@ An example response for a request with id `68656d69`, if the best height was `21
 
 #### Request
 
+##### Example
+
 An example request to retrieve the best block headers:
 
 ```json
@@ -239,3 +243,59 @@ An example response for a request with id `68656d69`, if the best height was `25
   }
 }
 ```
+
+## Balance by Address
+
+Retrieve the balance for an address.
+
+### Raw
+
+| Type     | `command` value                      |
+|----------|--------------------------------------|
+| Request  | `tbcapi-balance-by-address-request`  |
+| Response | `tbcapi-balance-by-address-response` |
+
+#### Request
+
+##### Payload
+
+- `address` is the address to retrieve the balance for.
+  Supported address types are P2PKH, P2SH, P2WPKH, P2WSH, and P2TR.
+
+##### Example
+
+An example request to retrieve the balance for the address `mhAfMWDjd8YV3RoWcpHSzqjkWi6q5Bfixa`:
+
+```json
+{
+  "header": {
+    "command": "tbcapi-balance-by-address-request",
+    "id": "68656d69"
+  },
+  "payload": {
+    "address": "mhAfMWDjd8YV3RoWcpHSzqjkWi6q5Bfixa"
+  }
+}
+```
+
+#### Response
+
+##### Payload
+
+- `balance` is the known balance of the address, in satoshis.
+
+##### Example
+
+An example response for a request with id `68656d69`, if the address's balance is zero:
+
+```json
+{
+  "header": {
+    "command": "tbcapi-balance-by-address-response",
+    "id": "68656d69"
+  },
+  "payload": {
+    "balance": 0
+  }
+}
+```

From 70077d0e076b0e30964a17f4968e534c7be613d3 Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Wed, 24 Apr 2024 02:52:27 +1000
Subject: [PATCH 09/39] Add docs for utxos-by-address

---
 api/tbcapi/README.md | 119 +++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 115 insertions(+), 4 deletions(-)

diff --git a/api/tbcapi/README.md b/api/tbcapi/README.md
index f698b995..3d6e29eb 100644
--- a/api/tbcapi/README.md
+++ b/api/tbcapi/README.md
@@ -24,6 +24,19 @@ A serialised block header has the following data:
 - `bits` is the difficulty target for the block.
 - `nonce` is the nonce used to generate the block.
 
+#### Address
+
+An address is an encoded Bitcoin address.
+Supported address types are P2PKH, P2SH, P2WPKH, P2WSH, and P2TR.
+
+#### UTXO
+
+A serialised UTXO has the following data:
+
+- `tx_id` is the transaction ID encoded as a hexadecimal string.
+- `value` is the value of the UTXO.
+- `out_index` is the output index for the UTXO.
+
 ## Block Headers by Height
 
 ### Raw data
@@ -90,7 +103,7 @@ An example response for a request with id `68656d69` and height `43111`:
 
 ##### Payload
 
-- `height` is the height to at which block headers should be retrieved.
+- `height` is the height at which block headers should be retrieved.
 
 ##### Example
 
@@ -259,12 +272,11 @@ Retrieve the balance for an address.
 
 ##### Payload
 
-- `address` is the address to retrieve the balance for.
-  Supported address types are P2PKH, P2SH, P2WPKH, P2WSH, and P2TR.
+- `address` is the [address](#address) the balance should be retrieved for.
 
 ##### Example
 
-An example request to retrieve the balance for the address `mhAfMWDjd8YV3RoWcpHSzqjkWi6q5Bfixa`:
+An example request to retrieve the balance for the address `myqzZmRvoXmrhsrM5STiMGtNRxCFArHWRd`:
 
 ```json
 {
@@ -299,3 +311,102 @@ An example response for a request with id `68656d69`, if the address's balance i
   }
 }
 ```
+
+## UTXOs by Address
+
+### Raw data
+
+| Type     | `command` value                        |
+|----------|----------------------------------------|
+| Request  | `tbcapi-utxos-by-address-raw-request`  |
+| Response | `tbcapi-utxos-by-address-raw-response` |
+
+#### Request
+
+##### Payload
+
+- `address` is the [address](#address) to retrieve the UTXOs for.
+- `start` is the start index for the UTXOs that should be included in the response (or the number of UTXOs that should be skipped).
+- `count` is the maximum number of UTXOs that should be included in the response.
+
+##### Example
+
+An example request to retrieve five UTXOs for the address `mhAfMWDjd8YV3RoWcpHSzqjkWi6q5Bfixa`:
+
+```json
+{
+  "header": {
+    "command": "tbcapi-utxos-by-address-raw-request",
+    "id": "68656d69"
+  },
+  "payload": {
+    "address": "mhAfMWDjd8YV3RoWcpHSzqjkWi6q5Bfixa",
+    "start": 0,
+    "count": 5
+  }
+}
+```
+
+#### Response
+
+##### Payload
+
+- `utxos` is an array of the best known block headers encoded as hexadecimal strings, or `null` if there are no UTXOs
+  for the address.
+
+##### Example
+
+An example response for a request with id `68656d69`, requesting five UTXOs for the
+address `mhAfMWDjd8YV3RoWcpHSzqjkWi6q5Bfixa`:
+
+```json
+TODO
+```
+
+### Serialised
+
+| Type     | `command` value                    |
+|----------|------------------------------------|
+| Request  | `tbcapi-utxos-by-address-request`  |
+| Response | `tbcapi-utxos-by-address-response` |
+
+#### Request
+
+##### Payload
+
+- `address` is the [address](#address) to retrieve the UTXOs for.
+- `start` is the start index for the UTXOs that should be included in the response (or the number of UTXOs that should be skipped).
+- `count` is the maximum number of UTXOs that should be included in the response.
+
+##### Example
+
+An example request to retrieve five UTXOs for the address `mhAfMWDjd8YV3RoWcpHSzqjkWi6q5Bfixa`:
+
+```json
+{
+  "header": {
+    "command": "tbcapi-utxos-by-address-raw-request",
+    "id": "68656d69"
+  },
+  "payload": {
+    "address": "mhAfMWDjd8YV3RoWcpHSzqjkWi6q5Bfixa",
+    "start": 0,
+    "count": 5
+  }
+}
+```
+
+#### Response
+
+##### Payload
+
+- `utxos` is an array of known [UTXOs](#utxo). The maximum number of items in this array can be changed
+  with `count` in the request.
+
+##### Example
+
+An example response for a request with id `68656d69`, if the best height was `2587400`:
+
+```json
+TODO
+```

From 16d72a8c04573d96f443e532f2d1d7c057299b8d Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Wed, 24 Apr 2024 03:27:25 +1000
Subject: [PATCH 10/39] Add docs for tx-by-id

---
 api/tbcapi/README.md | 128 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 125 insertions(+), 3 deletions(-)

diff --git a/api/tbcapi/README.md b/api/tbcapi/README.md
index 3d6e29eb..04e8ba9d 100644
--- a/api/tbcapi/README.md
+++ b/api/tbcapi/README.md
@@ -15,7 +15,7 @@ Please see [protocol/README.md](../protocol/README.md) for more information abou
 
 #### Block Header
 
-A serialised block header has the following data:
+A serialised block header contains the following data:
 
 - `version` is the version of the block.
 - `prev_hash` is the hash of the previous block header in the blockchain.
@@ -31,12 +31,44 @@ Supported address types are P2PKH, P2SH, P2WPKH, P2WSH, and P2TR.
 
 #### UTXO
 
-A serialised UTXO has the following data:
+A serialised UTXO contains the following data:
 
 - `tx_id` is the transaction ID encoded as a hexadecimal string.
 - `value` is the value of the UTXO.
 - `out_index` is the output index for the UTXO.
 
+#### Transaction
+
+A serialised transaction contains the following data:
+
+- `version` is the transaction version.
+- `lock_time` is the block height or timestamp at which the transaction becomes final.
+- `tx_in` is an array of [transaction inputs](#transaction-input).
+- `tx_out` is an array of [transaction outputs](#transaction-output).
+
+#### Transaction Input
+
+A serialised transaction input contains the following data:
+
+- `outpoint` is the [outpoint](#outpoint) for the previous transaction output.
+- `signature_script` is the signature script for the transaction.
+- `witness` is an array of the transaction witnesses, encoded as hexadecimal strings.
+- `sequence` is the transaction sequence number.
+
+#### Transaction Output
+
+A serialised transaction output contains the following data:
+
+- `value` is the value of the transaction output in satoshis.
+- `pk_script` is the pubkey script of the transaction output, encoded as a hexadecimal string.
+
+#### Outpoint
+
+A serialised outpoint contains the following data:
+
+- `hash` is the ID of the transaction holding the output to be spent.
+- `index` is the index of the specific output to spend from the transaction.
+
 ## Block Headers by Height
 
 ### Raw data
@@ -351,7 +383,7 @@ An example request to retrieve five UTXOs for the address `mhAfMWDjd8YV3RoWcpHSz
 
 ##### Payload
 
-- `utxos` is an array of the best known block headers encoded as hexadecimal strings, or `null` if there are no UTXOs
+- `utxos` is an array of known UTXOs for the address, encoded as hexadecimal strings, or `null` if there are no UTXOs
   for the address.
 
 ##### Example
@@ -410,3 +442,93 @@ An example response for a request with id `68656d69`, if the best height was `25
 ```json
 TODO
 ```
+
+## Transaction by ID
+
+### Raw data
+
+| Type     | `command` value                 |
+|----------|---------------------------------|
+| Request  | `tbcapi-tx-by-id-raw-request`   |
+| Response | `ttbcapi-tx-by-id-raw-response` |
+
+#### Request
+
+##### Payload
+
+- `tx_id` is the ID of the transaction to retrieve, encoded as a hexadecimal string.
+
+##### Example
+
+An example request to retrieve the transaction `ac583148a532c94132adc09572ee075dab86c9f72620952b703819bf53ad8405`:
+
+```json
+{
+  "header": {
+    "command": "tbcapi-tx-by-id-raw-request",
+    "id": "68656d69"
+  },
+  "payload": {
+    "tx_id": "ac583148a532c94132adc09572ee075dab86c9f72620952b703819bf53ad8405"
+  }
+}
+```
+
+#### Response
+
+##### Payload
+
+- `tx` is the transaction, encoded as a hexadecimal string.
+
+##### Example
+
+An example response for a request with id `68656d69`, requesting the
+transaction `ac583148a532c94132adc09572ee075dab86c9f72620952b703819bf53ad8405`:
+
+```json
+TODO
+```
+
+### Serialised
+
+| Type     | `command` value            |
+|----------|----------------------------|
+| Request  | `tbcapi-tx-by-id-request`  |
+| Response | `tbcapi-tx-by-id-response` |
+
+#### Request
+
+##### Payload
+
+- `tx_id` is the ID of the transaction to retrieve, encoded as a hexadecimal string.
+
+##### Example
+
+An example request to retrieve the transaction `ac583148a532c94132adc09572ee075dab86c9f72620952b703819bf53ad8405`:
+
+```json
+{
+  "header": {
+    "command": "tbcapi-tx-by-id-request",
+    "id": "68656d69"
+  },
+  "payload": {
+    "tx_id": "ac583148a532c94132adc09572ee075dab86c9f72620952b703819bf53ad8405"
+  }
+}
+```
+
+#### Response
+
+##### Payload
+
+- `tx` is the requested [transaction](#transaction), if found, otherwise `null`.
+
+##### Example
+
+An example response for a request with id `68656d69`, requesting the
+transaction `ac583148a532c94132adc09572ee075dab86c9f72620952b703819bf53ad8405`:
+
+```json
+TODO
+```

From 1f77c9f64191ae3f81560aae82ddef8668a6167a Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Wed, 24 Apr 2024 03:30:54 +1000
Subject: [PATCH 11/39] Add a link to tbcapi.go

---
 api/tbcapi/README.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/api/tbcapi/README.md b/api/tbcapi/README.md
index 04e8ba9d..9829c9af 100644
--- a/api/tbcapi/README.md
+++ b/api/tbcapi/README.md
@@ -1,12 +1,14 @@
 # Hemi Tiny Bitcoin Daemon RPC
 
-*Last updated April 19th, 2024.*
+*Last updated April 24th, 2024.*
 
 When the `TBC_ADDRESS` environment variable is set, the `tbcd` daemon listens on the provided address.
 The RPC protocol is WebSocket-based and uses a standard request/response model.
 
 [`hemictl`](../../cmd/hemictl) is a reference implementation of an RPC client.
 
+[View the raw Go types used in TBC's RPC commands `api/tbcapi/tbcapi.go`](tbcapi.go).
+
 ## Protocol
 
 Please see [protocol/README.md](../protocol/README.md) for more information about the underlying RPC protocol.

From 673f9f2de9ea8ca3a2ecb8883afc8db75f095b43 Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Wed, 24 Apr 2024 03:34:03 +1000
Subject: [PATCH 12/39] Add errors section

---
 api/tbcapi/README.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/api/tbcapi/README.md b/api/tbcapi/README.md
index 9829c9af..9b3d59c3 100644
--- a/api/tbcapi/README.md
+++ b/api/tbcapi/README.md
@@ -13,6 +13,14 @@ The RPC protocol is WebSocket-based and uses a standard request/response model.
 
 Please see [protocol/README.md](../protocol/README.md) for more information about the underlying RPC protocol.
 
+### Errors
+
+If an error occurs during a request, the payload of the response contain an `error` value with the following data:
+
+- `timestamp` is the time at which the error occurred, represented in Unix seconds.
+- `trace` (internal errors only) is a unique string which can be used to trace errors between a server and client.
+- `message` is the error message. If the error was an internal server error, this will be `internal error`.
+
 ### Serialised types
 
 #### Block Header

From 5c5d973ba898221945d39e2e420ade216f03e7dc Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Wed, 24 Apr 2024 03:46:13 +1000
Subject: [PATCH 13/39] Add table of contents

---
 api/tbcapi/README.md | 84 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)

diff --git a/api/tbcapi/README.md b/api/tbcapi/README.md
index 9b3d59c3..4a1fe0c5 100644
--- a/api/tbcapi/README.md
+++ b/api/tbcapi/README.md
@@ -1,5 +1,89 @@
 # Hemi Tiny Bitcoin Daemon RPC
 
+<details>
+  <summary>Table of Contents</summary>
+
+<!-- TOC -->
+* [Hemi Tiny Bitcoin Daemon RPC](#hemi-tiny-bitcoin-daemon-rpc)
+  * [Protocol](#protocol)
+    * [Errors](#errors)
+    * [Serialised types](#serialised-types)
+      * [Block Header](#block-header)
+      * [Address](#address)
+      * [UTXO](#utxo)
+      * [Transaction](#transaction)
+      * [Transaction Input](#transaction-input)
+      * [Transaction Output](#transaction-output)
+      * [Outpoint](#outpoint)
+  * [Block Headers by Height](#block-headers-by-height)
+    * [Raw data](#raw-data)
+      * [Request](#request)
+        * [Payload](#payload)
+        * [Example](#example)
+      * [Response](#response)
+        * [Payload](#payload-1)
+        * [Example](#example-1)
+    * [Serialised](#serialised)
+      * [Request](#request-1)
+        * [Payload](#payload-2)
+        * [Example](#example-2)
+      * [Response](#response-1)
+        * [Payload](#payload-3)
+        * [Example](#example-3)
+  * [Best Block Headers](#best-block-headers)
+    * [Raw data](#raw-data-1)
+      * [Request](#request-2)
+        * [Example](#example-4)
+      * [Response](#response-2)
+        * [Payload](#payload-4)
+        * [Example](#example-5)
+    * [Serialised](#serialised-1)
+      * [Request](#request-3)
+        * [Example](#example-6)
+      * [Response](#response-3)
+        * [Payload](#payload-5)
+        * [Example](#example-7)
+  * [Balance by Address](#balance-by-address)
+    * [Raw](#raw)
+      * [Request](#request-4)
+        * [Payload](#payload-6)
+        * [Example](#example-8)
+      * [Response](#response-4)
+        * [Payload](#payload-7)
+        * [Example](#example-9)
+  * [UTXOs by Address](#utxos-by-address)
+    * [Raw data](#raw-data-2)
+      * [Request](#request-5)
+        * [Payload](#payload-8)
+        * [Example](#example-10)
+      * [Response](#response-5)
+        * [Payload](#payload-9)
+        * [Example](#example-11)
+    * [Serialised](#serialised-2)
+      * [Request](#request-6)
+        * [Payload](#payload-10)
+        * [Example](#example-12)
+      * [Response](#response-6)
+        * [Payload](#payload-11)
+        * [Example](#example-13)
+  * [Transaction by ID](#transaction-by-id)
+    * [Raw data](#raw-data-3)
+      * [Request](#request-7)
+        * [Payload](#payload-12)
+        * [Example](#example-14)
+      * [Response](#response-7)
+        * [Payload](#payload-13)
+        * [Example](#example-15)
+    * [Serialised](#serialised-3)
+      * [Request](#request-8)
+        * [Payload](#payload-14)
+        * [Example](#example-16)
+      * [Response](#response-8)
+        * [Payload](#payload-15)
+        * [Example](#example-17)
+<!-- TOC -->
+</details>
+
 *Last updated April 24th, 2024.*
 
 When the `TBC_ADDRESS` environment variable is set, the `tbcd` daemon listens on the provided address.

From d671abd94bcace0dc6280d3da61ed623ea6098ed Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Wed, 24 Apr 2024 23:26:55 +1000
Subject: [PATCH 14/39] Better describe block header merkle_root, timestamp and
 nonce

Co-authored-by: ClaytonNorthey92 <clayton.northey@gmail.com>
---
 api/tbcapi/README.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/api/tbcapi/README.md b/api/tbcapi/README.md
index 4a1fe0c5..c8cd858c 100644
--- a/api/tbcapi/README.md
+++ b/api/tbcapi/README.md
@@ -113,10 +113,10 @@ A serialised block header contains the following data:
 
 - `version` is the version of the block.
 - `prev_hash` is the hash of the previous block header in the blockchain.
-- `merkle_root` is the merkle tree reference to hash of all transactions for the block.
-- `timestamp` is the time the block was created, represented in Unix seconds.
+- `merkle_root` is the hash derived from the hashes of all transactions included in the block.
+- `timestamp` is the time the miner began hashing the header, represented in Unix seconds.
 - `bits` is the difficulty target for the block.
-- `nonce` is the nonce used to generate the block.
+- `nonce` is the nonce used to create the hash that is less than or equal to the target threshold.
 
 #### Address
 

From 37dd31881c3d57c00b010d77e9573cd6fe4c5114 Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Thu, 25 Apr 2024 00:58:57 +1000
Subject: [PATCH 15/39] Add TBC_ADDRESS example and move protocol comment to
 protocol section

---
 api/tbcapi/README.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/api/tbcapi/README.md b/api/tbcapi/README.md
index c8cd858c..63bd709f 100644
--- a/api/tbcapi/README.md
+++ b/api/tbcapi/README.md
@@ -86,8 +86,8 @@
 
 *Last updated April 24th, 2024.*
 
-When the `TBC_ADDRESS` environment variable is set, the `tbcd` daemon listens on the provided address.
-The RPC protocol is WebSocket-based and uses a standard request/response model.
+When the `TBC_ADDRESS` environment variable is set (e.g. `TBC_ADDRESS=localhost:8082`), the `tbcd` daemon listens on the
+provided address.
 
 [`hemictl`](../../cmd/hemictl) is a reference implementation of an RPC client.
 
@@ -95,6 +95,8 @@ The RPC protocol is WebSocket-based and uses a standard request/response model.
 
 ## Protocol
 
+The RPC protocol is WebSocket-based and uses a standard request/response model.
+
 Please see [protocol/README.md](../protocol/README.md) for more information about the underlying RPC protocol.
 
 ### Errors

From b9620f64db40de9d3d6be7be26805893aa534aee Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Thu, 25 Apr 2024 03:13:05 +1000
Subject: [PATCH 16/39] Add request/response examples for UTXOs by Address

---
 api/tbcapi/README.md | 64 ++++++++++++++++++++++++++++++++++++++------
 1 file changed, 56 insertions(+), 8 deletions(-)

diff --git a/api/tbcapi/README.md b/api/tbcapi/README.md
index 63bd709f..86f3653d 100644
--- a/api/tbcapi/README.md
+++ b/api/tbcapi/README.md
@@ -459,7 +459,7 @@ An example response for a request with id `68656d69`, if the address's balance i
 
 ##### Example
 
-An example request to retrieve five UTXOs for the address `mhAfMWDjd8YV3RoWcpHSzqjkWi6q5Bfixa`:
+An example request to retrieve five UTXOs for the address `mxVFsFW5N4mu1HPkxPttorvocvzeZ7KZyk`:
 
 ```json
 {
@@ -468,7 +468,7 @@ An example request to retrieve five UTXOs for the address `mhAfMWDjd8YV3RoWcpHSz
     "id": "68656d69"
   },
   "payload": {
-    "address": "mhAfMWDjd8YV3RoWcpHSzqjkWi6q5Bfixa",
+    "address": "mxVFsFW5N4mu1HPkxPttorvocvzeZ7KZyk",
     "start": 0,
     "count": 5
   }
@@ -485,10 +485,24 @@ An example request to retrieve five UTXOs for the address `mhAfMWDjd8YV3RoWcpHSz
 ##### Example
 
 An example response for a request with id `68656d69`, requesting five UTXOs for the
-address `mhAfMWDjd8YV3RoWcpHSzqjkWi6q5Bfixa`:
+address `mxVFsFW5N4mu1HPkxPttorvocvzeZ7KZyk`:
 
 ```json
-TODO
+{
+  "header": {
+    "command": "tbcapi-utxos-by-address-raw-response",
+    "id": "68656d69"
+  },
+  "payload": {
+    "utxos": [
+      "0073700282db1dcc4853dc64e5da5c8595d1204ea7d036b04ea6b8ba41093a770000000000000cab00000002",
+      "0073700282db1dcc4853dc64e5da5c8595d1204ea7d036b04ea6b8ba41093a770000000000000cab00000002",
+      "0073700282db1dcc4853dc64e5da5c8595d1204ea7d036b04ea6b8ba41093a770000000000000cab00000002",
+      "0073700282db1dcc4853dc64e5da5c8595d1204ea7d036b04ea6b8ba41093a770000000000000cab00000002",
+      "0073700282db1dcc4853dc64e5da5c8595d1204ea7d036b04ea6b8ba41093a770000000000000cab00000002"
+    ]
+  }
+}
 ```
 
 ### Serialised
@@ -508,16 +522,16 @@ TODO
 
 ##### Example
 
-An example request to retrieve five UTXOs for the address `mhAfMWDjd8YV3RoWcpHSzqjkWi6q5Bfixa`:
+An example request to retrieve five UTXOs for the address `mxVFsFW5N4mu1HPkxPttorvocvzeZ7KZyk`:
 
 ```json
 {
   "header": {
-    "command": "tbcapi-utxos-by-address-raw-request",
+    "command": "tbcapi-utxos-by-address-request",
     "id": "68656d69"
   },
   "payload": {
-    "address": "mhAfMWDjd8YV3RoWcpHSzqjkWi6q5Bfixa",
+    "address": "mxVFsFW5N4mu1HPkxPttorvocvzeZ7KZyk",
     "start": 0,
     "count": 5
   }
@@ -536,7 +550,41 @@ An example request to retrieve five UTXOs for the address `mhAfMWDjd8YV3RoWcpHSz
 An example response for a request with id `68656d69`, if the best height was `2587400`:
 
 ```json
-TODO
+{
+  "header": {
+    "command": "tbcapi-utxos-by-address-response",
+    "id": "68656d69"
+  },
+  "payload": {
+    "utxos": [
+      {
+        "tx_id": "0012a33f3c301c90427d81f256d8a4848dcbfc289e8325725e7657e9a643d6fd",
+        "value": 2026,
+        "out_index": 1
+      },
+      {
+        "tx_id": "0066c9f87d012e75e390adb490794a746fefe05eb16d220515788f33d5b6b336",
+        "value": 10000,
+        "out_index": 1
+      },
+      {
+        "tx_id": "0066c9f87d012e75e390adb490794a746fefe05eb16d220515788f33d5b6b336",
+        "value": 10000,
+        "out_index": 2
+      },
+      {
+        "tx_id": "0073700282db1dcc4853dc64e5da5c8595d1204ea7d036b04ea6b8ba41093a77",
+        "value": 3243,
+        "out_index": 1
+      },
+      {
+        "tx_id": "0073700282db1dcc4853dc64e5da5c8595d1204ea7d036b04ea6b8ba41093a77",
+        "value": 3243,
+        "out_index": 2
+      }
+    ]
+  }
+}
 ```
 
 ## Transaction by ID

From c836ba4f34713c38dfae86d31ce0c9c0887a4b76 Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Thu, 25 Apr 2024 03:46:38 +1000
Subject: [PATCH 17/39] Update limits information in tbc readme

---
 cmd/tbcd/README.md | 18 ++++++------------
 1 file changed, 6 insertions(+), 12 deletions(-)

diff --git a/cmd/tbcd/README.md b/cmd/tbcd/README.md
index ca8de129..b5582615 100644
--- a/cmd/tbcd/README.md
+++ b/cmd/tbcd/README.md
@@ -50,22 +50,16 @@ go install ./cmd/tbcd/
 
 On some systems, you may need to increase the limits for the number of open files, memory and the maximum stack size.
 
-If you run into open file or OOM errors while running `tbcd`, run the following commands in the shell that you will
-run `tbcd` in:
+At startup, TBC will attempt to verify these limits on supported platforms, to ensure that they are set to values that
+will allow TBC to run without failing.
 
-```shell
-ulimit -n 8192
-ulimit -s 16384
-ulimit -m unlimited
-ulimit -d unlimited
+If you see an error similar to the following, you will need to adjust the limits on your system in order to run TBC.
 ```
-
-You can confirm these settings with:
-
-```shell
-ulimit -a
+ulimit: memory: limit too low got X, want X
 ```
 
+Changing limits is OS-specific, but can usually be done using the `ulimit` command.
+
 ## Runtime settings
 
 `tbcd` is designed to be run in cloud environments, as such it only uses environment variables for runtime settings.

From d1a83f8911f11e50a4e9a329cb3f5bc53c9956e7 Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Sat, 27 Apr 2024 00:31:48 +1000
Subject: [PATCH 18/39] Add example request/responses for tx-by-id

---
 api/tbcapi/README.md | 52 +++++++++++++++++++++++++++++++++++++-------
 1 file changed, 44 insertions(+), 8 deletions(-)

diff --git a/api/tbcapi/README.md b/api/tbcapi/README.md
index 86f3653d..ef64624e 100644
--- a/api/tbcapi/README.md
+++ b/api/tbcapi/README.md
@@ -604,7 +604,7 @@ An example response for a request with id `68656d69`, if the best height was `25
 
 ##### Example
 
-An example request to retrieve the transaction `ac583148a532c94132adc09572ee075dab86c9f72620952b703819bf53ad8405`:
+An example request to retrieve the transaction `0584ad53bf1938702b952026f7c986ab5d07ee7295c0ad3241c932a5483158ac`:
 
 ```json
 {
@@ -613,7 +613,7 @@ An example request to retrieve the transaction `ac583148a532c94132adc09572ee075d
     "id": "68656d69"
   },
   "payload": {
-    "tx_id": "ac583148a532c94132adc09572ee075dab86c9f72620952b703819bf53ad8405"
+    "tx_id": "0584ad53bf1938702b952026f7c986ab5d07ee7295c0ad3241c932a5483158ac"
   }
 }
 ```
@@ -627,10 +627,18 @@ An example request to retrieve the transaction `ac583148a532c94132adc09572ee075d
 ##### Example
 
 An example response for a request with id `68656d69`, requesting the
-transaction `ac583148a532c94132adc09572ee075dab86c9f72620952b703819bf53ad8405`:
+transaction `0584ad53bf1938702b952026f7c986ab5d07ee7295c0ad3241c932a5483158ac`:
 
 ```json
-TODO
+{
+  "header": {
+    "command": "tbcapi-tx-by-id-raw-response",
+    "id": "68656d69"
+  },
+  "payload": {
+    "tx": "02000000019554a7eb8bc903ea957c87964ab04a58d177692f15d7271cccb95258202f14b5bd00000000fdffffff014a010000000000002251208ec88237b5978e75e93feaeeb1343ff86ae2f2c348a903c9c9c4ad081926773500000000"
+  }
+}
 ```
 
 ### Serialised
@@ -648,7 +656,7 @@ TODO
 
 ##### Example
 
-An example request to retrieve the transaction `ac583148a532c94132adc09572ee075dab86c9f72620952b703819bf53ad8405`:
+An example request to retrieve the transaction `0584ad53bf1938702b952026f7c986ab5d07ee7295c0ad3241c932a5483158ac`:
 
 ```json
 {
@@ -657,7 +665,7 @@ An example request to retrieve the transaction `ac583148a532c94132adc09572ee075d
     "id": "68656d69"
   },
   "payload": {
-    "tx_id": "ac583148a532c94132adc09572ee075dab86c9f72620952b703819bf53ad8405"
+    "tx_id": "0584ad53bf1938702b952026f7c986ab5d07ee7295c0ad3241c932a5483158ac"
   }
 }
 ```
@@ -671,8 +679,36 @@ An example request to retrieve the transaction `ac583148a532c94132adc09572ee075d
 ##### Example
 
 An example response for a request with id `68656d69`, requesting the
-transaction `ac583148a532c94132adc09572ee075dab86c9f72620952b703819bf53ad8405`:
+transaction `0584ad53bf1938702b952026f7c986ab5d07ee7295c0ad3241c932a5483158ac`:
 
 ```json
-TODO
+{
+  "header": {
+    "command": "tbcapi-tx-by-id-response",
+    "id": "68656d69"
+  },
+  "payload": {
+    "tx": {
+      "version": 2,
+      "lock_time": 0,
+      "tx_in": [
+        {
+          "outpoint": {
+            "hash": "9554a7eb8bc903ea957c87964ab04a58d177692f15d7271cccb95258202f14b5",
+            "index": 189
+          },
+          "signature_script": "",
+          "tx_witness": null,
+          "sequence": 4294967293
+        }
+      ],
+      "tx_out": [
+        {
+          "value": 330,
+          "pk_script": "51208ec88237b5978e75e93feaeeb1343ff86ae2f2c348a903c9c9c4ad0819267735"
+        }
+      ]
+    }
+  }
+}
 ```

From 62808a1238f59d7c27a0d53c10c1e1d259f11c62 Mon Sep 17 00:00:00 2001
From: Jane <32560576+jsorkin24@users.noreply.github.com>
Date: Fri, 26 Apr 2024 09:15:01 -0700
Subject: [PATCH 19/39] readme-docs: protocol & tbc api, tbcd cmd, and hemi

---
 README.md              | 240 ++++++++++-------
 api/protocol/README.md |  29 +-
 api/tbcapi/README.md   | 593 ++++++++++++++++++++++-------------------
 cmd/tbcd/README.md     |  92 +++----
 database/.DS_Store     | Bin 0 -> 6148 bytes
 5 files changed, 540 insertions(+), 414 deletions(-)
 create mode 100644 database/.DS_Store

diff --git a/README.md b/README.md
index c1f69bb3..3028702d 100644
--- a/README.md
+++ b/README.md
@@ -1,156 +1,212 @@
-# Hemi Network
+# 🌐 The Hemi Network
 
-<details>
-  <summary>Table of Contents</summary>
-
-* [What is the Hemi Network?](#what-is-the-hemi-network)
-  * [Services](#services)
-  * [License](#license)
-* [Getting Started](#getting-started)
-  * [Building from Source](#building-from-source)
-  * [Downloading Binaries from Releases](#downloading-binaries-from-releases)
-  * [Running](#running)
-  * [Running popmd](#running-popmd)
-    * [CLI](#cli)
-    * [Web](#web)
-  * [Running bfgd](#running-bfgd)
-  * [Running bssd](#running-bssd)
 
+***Last updated:** April 25th, 2024*
+
+Hemi is an EVM-compatible L2 blockchain that combines the security of Bitcoin with the programmability of Ethereum.
+
+<details>
+  <summary style="color: #FF5F00; font-weight: 500; font-size: 1.5rem;"> Table of Contents</summary>
+
+- [🌐 The Hemi Network](#-the-hemi-network)
+  - [🔧 Services](#-services)
+  - [📜 TL;DR:](#-tldr)
+  - [⚡️ Getting Started](#️-getting-started)
+    - [🏁 Prerequisites](#-prerequisites)
+    - [📚 Tutorial](#-tutorial)
+  - [📦 Downloading Binaries from Releases](#-downloading-binaries-from-releases)
+- [🛠 Running the Services](#-running-the-services)
+  - [▶️ Running popmd](#️-running-popmd)
+    - [🏁 Prerequisites:](#-prerequisites-1)
+    - [CLI:](#cli)
+    - [Web:](#web)
+  - [▶️ Running bfgd](#️-running-bfgd)
+    - [🏁 Prerequisites:](#-prerequisites-2)
+  - [▶️ Running bssd](#️-running-bssd)
+    - [🏁 Prerequisites:](#-prerequisites-3)
+  - [▶️ Running Network](#️-running-network)
+    - [🏁 Prerequisites:](#-prerequisites-4)
+    - [📚 Tutorial](#-tutorial-1)
+  - [🧪 Running Full Network Tests](#-running-full-network-tests)
+    - [🏁 Prerequisites:](#-prerequisites-5)
+    - [📚 Tutorial](#-tutorial-2)
+  - [📄 License](#-license)
 </details>
 
-## What is the Hemi Network?
+---
+## 🔧 Services
 
-Hemi is an EVM compatible L2 blockchain that brings Bitcoin security and Ethereum programability together.
+The Hemi Network comprises three key services, each serving a unique function within the network:
 
-### Services
+| Service | Description |
+|---------|-------------|
+| [**PoP Miner (popmd)**](https://github.com/hemilabs/heminetwork/blob/main/service/popm) | **Mines** L2 Keystones into Bitcoin blocks for Proof-of-Proof. |
+| [**Bitcoin Finality Governor (bfgd)**](https://github.com/hemilabs/heminetwork/blob/main/service/bfg) | Acts as the gateway to the Bitcoin network. |
+| [**Bitcoin Secure Sequencer (bssd)**](https://github.com/hemilabs/heminetwork/blob/main/service/bss) | Acts as a gateway to the Bitcoin Finality Governor (BFG) forked from Optimism, managing the consensus mechanisms of the Hemi Network.
 
-Hemi Network consists of 3 services:
 
-* [PoP Miner (popmd)](service/popm): "mines" L2 Keystones into BTC blocks for proof-of-proof
-* [Bitcoin Finality Governor (bfgd)](service/bfg): Hemi's gateway to the BTC network.
-* [Bitcoin Secure Sequencer (bssd)](service/bss): Optimism's gateway to BFG, manages Hemi Network's consensus
+---
+## 📜 TL;DR:
 
-### License
+- **extool**: A utility tool for extracting and processing data from various file formats, tailored for blockchain data analysis.
+- **hemictl**: The command-line interface for controlling and managing all Hemi Network services.
+- **keygen**: Generates and manages cryptographic keys used within the Hemi network, ensuring secure operations.
+- **popmd (Proof of Proof Miner Daemon)**: Embeds L2 Keystones into Bitcoin blocks for proof-of-proof, integral to the network's security.
+- **bfgd (Bitcoin Finality Governor Daemon)**: Manages connections and data transfers between the Hemi Network and the Bitcoin blockchain, ensuring finality.
+- **bssd (Bitcoin Secure Sequencer Daemon)**: Coordinates and sequences blockchain operations, serving as a bridge to the Bitcoin Finality Governor.
 
-This project is licensed under the [MIT License](LICENSE).
 
-## Getting Started
+---
 
-### Building from Source
+## ⚡️ Getting Started
 
-To build, you must have the following installed:
+### 🏁 Prerequisites
 
-* `git`
-* `make`
-* [Go v1.22+](https://go.dev/dl/)
+- `git`
+- `make`
+- [Go v1.22+](https://go.dev/dl/)
 
-First, clone the repository:
+---
 
-```shell
-git clone https://github.com/hemilabs/heminetwork.git
-```
+### 📚 Tutorial
 
-Then build:
 
-```shell
-cd heminetwork
-make deps
-make
-```
+1. Clone the Repository:
+   ```bash
+   git clone https://github.com/hemilabs/heminetwork.git
+   ```
+2. Build:
+   ```bash
+   cd heminetwork
+   make deps
+   make
+   ```
 
-This will put built binaries in `<path-to-repo>/bin/`
+Binaries will be located in `<path-to-repo>/bin/`.
 
-### Downloading Binaries from Releases
+---
 
-You can find releases on the [Releases Page](https://github.com/hemilabs/heminetwork/releases)
+## 📦 Downloading Binaries from Releases
 
-### Running
+Pre-built binaries are available on the [Releases Page](https://github.com/hemilabs/heminetwork/releases).
 
-To view options for any of the services, you may run the following
+---
 
-```shell
-./bin/popmd --help
-```
+# 🛠 Running the Services
 
-```shell
-./bin/bfgd --help
-```
+For any service, you can view configuration options by running:
 
-```shell
+```bash
+./bin/popmd --help
+./bin/bfgd --help
 ./bin/bssd --help
 ```
 
-### Running popmd
+## ▶️ Running popmd
 
-popmd has a few crucial requirements to run:
+### 🏁 Prerequisites:
 
-* a BTC private key that is funded, this can be a testnet address if you configure popmd as such
-* a BFG URL to connect to
+- A funded BTC private key. This can be a testnet address if configured for test environments.
+- A BFG URL to establish a connection.
 
-if configured correctly and running, then popmd will start "mining" L2 Keystones by adding them to btc blocks that make
-it into the chain
+Once properly configured and running, `popmd` will start **mining** L2 Keystones by adding them to Bitcoin blocks that make it into the chain.
 
-#### CLI
+### CLI:
 
-```shell
+Set up and start popmd using:
+
+```bash
 ./bin/popmd
 ```
 
-#### Web
+### Web:
+
+Or initialize the web interface:
 
-```shell
+```bash
 cd ./web
 make
 go run ./integrationtest
 ```
 
-### Running bfgd
 
-bfgd has a few crucial requirements to run:
+## ▶️ Running bfgd
 
-* a postgres database, bfgd expects the sql scripts in `./database/bfgd/scripts/` to be run to set up your schema
-* an electrumx node connected to the proper bitcoin network (testnet vs mainnet, etc.)
+### 🏁 Prerequisites:
 
-### Running bssd
+- A **PostgreSQL database**, bfgd expects the sql scripts in `./database/bfgd/scripts/` to be run to set up your schema.
+- A **connection to an ElectrumX node** on the proper Bitcoin network (testnet or mainnet).
 
-bssd has a few crucial requirements to run:
 
-* a bfgd instance running to connect to
 
-### Running Network
+## ▶️ Running bssd
 
-Prerequisites: `docker`
+### 🏁 Prerequisites:
+-  Connect to a live [bfgd](#running-bfgd) instance.
 
-To run the full network locally, you can run the following.  Note that this will create
-L2Keystones and BTC Blocks at a high rate.  
 
-note: the `--build` flag is optional if you want to rebuild your code
 
-```
-docker compose -f ./e2e/docker-compose.yml up --build
-```
+## ▶️ Running Network
 
-This will take a while upon first build, but following builds should be cached.  
-When rebuilding, popmd, bssd, and bfgd will rebuild (due to `COPY` command breaking
- the cache).  However if you want to break the cache for the op-stack, use the following args:
+### 🏁 Prerequisites:
 
-For op-geth + optimism (op-node)
-```
-docker compose -f ./e2e/docker-compose.yml build --build-arg OP_GETH_CACHE_BREAK="$(date)"
-```
+- `docker`
+### 📚 Tutorial
 
-For optimism cache break only:
-```
-docker compose -f ./e2e/docker-compose.yml build --build-arg OPTIMISM_CACHE_BREAK="$(date)"
-```
+1. **Start the Network:** Launch the entire Hemi network locally using Docker, which will generate L2 Keystones and BTC Blocks at a **high rate**:
 
-**IMPORTANT:** make sure you run the following to tear down, this will remove
-data and give you a fresh start
+   ```bash
+   docker compose -f ./e2e/docker-compose.yml up --build
+   ```
 
-```
+    > [!NOTE]
+    > The `--build` flag is optional if you wish to rebuild your code.
+
+1. **Manage Caching:**
+   This initial build may take some time, but subsequent builds should benefit from caching.
+
+     > [!NOTE]
+    > During rebuilding, `popmd`, `bssd`, and `bfgd` may force a rebuild due to the `COPY` command, which can break the cache. If you need to deliberately break the cache for the op-stack, use the following arguments:
+
+- For op-geth + optimism (op-node):
+  ```bash
+  docker compose -f ./e2e/docker-compose.yml build --build-arg OP_GETH_CACHE_BREAK="$(date)"
+  ```
+
+- For optimism cache break only:
+  ```bash
+  docker compose -f ./e2e/docker-compose.yml build --build-arg OPTIMISM_CACHE_BREAK="$(date)"
+  ```
+
+> [!IMPORTANT]
+> Make sure you run the cleanup command to remove data and ensure a fresh start.
+```bash
 docker compose -f ./e2e/docker-compose.yml down -v --remove-orphans
 ```
 
 **NOTE:** The `--remove-orphans` flag should remove other containers not defined
 in the docker compose file. This is mainly here to help ensure you start with a
 clean environment.  It can be omitted.
+
+---
+
+## 🧪 Running Full Network Tests
+
+For a comprehensive local test of the Hemi network, this setup uses `bitcoind` in **regtest mode**:
+
+### 🏁 Prerequisites:
+
+- `docker`
+
+### 📚 Tutorial
+
+1. Run the Test Command:
+   ```make
+   networktest
+   ```
+
+---
+
+## 📄 License
+
+This project is licensed under the [MIT License](https://github.com/hemilabs/heminetwork/blob/main/LICENSE).
diff --git a/api/protocol/README.md b/api/protocol/README.md
index ccb1deca..8aa2b7cc 100644
--- a/api/protocol/README.md
+++ b/api/protocol/README.md
@@ -1,11 +1,13 @@
-# RPC Protocol
+# 👉 RPC Protocol
 
-The RPC protocol used by Hemi's daemons is WebSocket-based and uses JSON-encoded request/responses.
-The JSON data sent over WebSocket connections are called a "messages".
+The **RPC protocol** used by Hemi's daemons is WebSocket-based and uses **JSON-encoded requests/responses**.
 
-## Message format
+The JSON data sent over WebSocket connections are referred to as **"messages"**.
 
-An RPC message has the format:
+---
+## 📩 Message Format
+
+Every RPC message has the following format:
 
 ```json
 {
@@ -19,12 +21,19 @@ An RPC message has the format:
 
 ### Header
 
-The message header contains metadata:
+The message header includes metadata crucial for processing the message:
+
+- **`command`**: Specifies the command being executed.
+- **`id`**: A string used to uniquely identify each request. Responses will have the same `id` as the request, making it possible to match requests to responses.
 
-- `command` is the name of the command being called.
-- `id` is a string used to uniquely identify each request. Responses will have the same `id` as the request,
-  making it possible to match requests to responses. Message IDs should be randomly generated.
+  > [!NOTE]
+  > Message IDs should be randomly generated.
 
 ### Payload
 
-The payload type depends on the command being called. Please refer to the documentation for specific API you wish to use.
+The payload type depends on the command being called. Please refer to the documentation for more details on the specific API you wish to use.
+
+---
+## 📄 License
+
+This project is licensed under the [MIT License](../../LICENSE).
diff --git a/api/tbcapi/README.md b/api/tbcapi/README.md
index ef64624e..3799e08d 100644
--- a/api/tbcapi/README.md
+++ b/api/tbcapi/README.md
@@ -1,188 +1,237 @@
-# Hemi Tiny Bitcoin Daemon RPC
+# 📡 Hemi Tiny Bitcoin Daemon RPC
+
+***Last updated:** April 25th, 2024*
+
+This document provides details on the RPC setup and client implementation for the Hemi Tiny Bitcoin Daemon **(`tbcd`).**
 
 <details>
-  <summary>Table of Contents</summary>
+  <summary style="color: #FF5F00; font-weight: 500; font-size: 1.5rem;">📜 Table of Contents</summary>
 
 <!-- TOC -->
-* [Hemi Tiny Bitcoin Daemon RPC](#hemi-tiny-bitcoin-daemon-rpc)
-  * [Protocol](#protocol)
-    * [Errors](#errors)
-    * [Serialised types](#serialised-types)
-      * [Block Header](#block-header)
-      * [Address](#address)
-      * [UTXO](#utxo)
-      * [Transaction](#transaction)
-      * [Transaction Input](#transaction-input)
-      * [Transaction Output](#transaction-output)
-      * [Outpoint](#outpoint)
-  * [Block Headers by Height](#block-headers-by-height)
-    * [Raw data](#raw-data)
-      * [Request](#request)
-        * [Payload](#payload)
-        * [Example](#example)
-      * [Response](#response)
-        * [Payload](#payload-1)
-        * [Example](#example-1)
-    * [Serialised](#serialised)
-      * [Request](#request-1)
-        * [Payload](#payload-2)
-        * [Example](#example-2)
-      * [Response](#response-1)
-        * [Payload](#payload-3)
-        * [Example](#example-3)
-  * [Best Block Headers](#best-block-headers)
-    * [Raw data](#raw-data-1)
-      * [Request](#request-2)
-        * [Example](#example-4)
-      * [Response](#response-2)
-        * [Payload](#payload-4)
-        * [Example](#example-5)
-    * [Serialised](#serialised-1)
-      * [Request](#request-3)
-        * [Example](#example-6)
-      * [Response](#response-3)
-        * [Payload](#payload-5)
-        * [Example](#example-7)
-  * [Balance by Address](#balance-by-address)
-    * [Raw](#raw)
-      * [Request](#request-4)
-        * [Payload](#payload-6)
-        * [Example](#example-8)
-      * [Response](#response-4)
-        * [Payload](#payload-7)
-        * [Example](#example-9)
-  * [UTXOs by Address](#utxos-by-address)
-    * [Raw data](#raw-data-2)
-      * [Request](#request-5)
-        * [Payload](#payload-8)
-        * [Example](#example-10)
-      * [Response](#response-5)
-        * [Payload](#payload-9)
-        * [Example](#example-11)
-    * [Serialised](#serialised-2)
-      * [Request](#request-6)
-        * [Payload](#payload-10)
-        * [Example](#example-12)
-      * [Response](#response-6)
-        * [Payload](#payload-11)
-        * [Example](#example-13)
-  * [Transaction by ID](#transaction-by-id)
-    * [Raw data](#raw-data-3)
-      * [Request](#request-7)
-        * [Payload](#payload-12)
-        * [Example](#example-14)
-      * [Response](#response-7)
-        * [Payload](#payload-13)
-        * [Example](#example-15)
-    * [Serialised](#serialised-3)
-      * [Request](#request-8)
-        * [Payload](#payload-14)
-        * [Example](#example-16)
-      * [Response](#response-8)
-        * [Payload](#payload-15)
-        * [Example](#example-17)
+- [📡 Hemi Tiny Bitcoin Daemon RPC](#-hemi-tiny-bitcoin-daemon-rpc)
+  - [⚙️ Configuration](#️-configuration)
+  - [👉 RPC Client](#-rpc-client)
+  - [📚 Resources](#-resources)
+  - [📡 Protocol](#-protocol)
+    - [🚫 Errors](#-errors)
+    - [🗄️ Serialized Types](#️-serialized-types)
+      - [Block Header](#block-header)
+      - [Address](#address)
+      - [UTXO](#utxo)
+      - [Transaction](#transaction)
+      - [Transaction Input](#transaction-input)
+      - [Transaction Output](#transaction-output)
+      - [Outpoint](#outpoint)
+  - [👉 Block Headers by Height](#-block-headers-by-height)
+    - [🗂 Raw Data](#-raw-data)
+    - [📤 Request](#-request)
+      - [Payload:](#payload)
+      - [Example Request:](#example-request)
+    - [📥 Response](#-response)
+      - [Payload:](#payload-1)
+      - [Example Response:](#example-response)
+    - [🗂 Serialized Data](#-serialized-data)
+    - [📤 Request](#-request-1)
+      - [Payload](#payload-2)
+      - [Example Request](#example-request-1)
+    - [📥 Response](#-response-1)
+      - [Payload](#payload-3)
+      - [Example Response](#example-response-1)
+  - [👉 Best Block Headers](#-best-block-headers)
+    - [🗂 Raw Data](#-raw-data-1)
+    - [📤 Request](#-request-2)
+      - [Example Request](#example-request-2)
+    - [📥 Response](#-response-2)
+      - [Payload](#payload-4)
+      - [Example Response](#example-response-2)
+    - [🗂 Serialized Data](#-serialized-data-1)
+    - [📤 Request](#-request-3)
+      - [Example Request](#example-request-3)
+    - [📥 Response](#-response-3)
+      - [Payload](#payload-5)
+      - [Example Response](#example-response-3)
+  - [👉 Balance by Address](#-balance-by-address)
+    - [🗂 Raw Data](#-raw-data-2)
+    - [📤 Request](#-request-4)
+      - [Payload](#payload-6)
+      - [Example Request](#example-request-4)
+    - [📥 Response](#-response-4)
+      - [Payload](#payload-7)
+      - [Example Response](#example-response-4)
+  - [👉 UTXOs by Address](#-utxos-by-address)
+    - [🗂 Raw Data](#-raw-data-3)
+    - [📤 Request](#-request-5)
+      - [Payload:](#payload-8)
+      - [Example Request:](#example-request-5)
+    - [📥 Response](#-response-5)
+      - [Payload:](#payload-9)
+      - [Example Response:](#example-response-5)
+    - [🗂 Serialized Data](#-serialized-data-2)
+    - [📤 Request](#-request-6)
+      - [Payload:](#payload-10)
+      - [Example Request:](#example-request-6)
+    - [📥 Response](#-response-6)
+      - [Payload:](#payload-11)
+      - [Example Response:](#example-response-6)
+  - [👉 Transaction by ID](#-transaction-by-id)
+    - [🗂 Raw Data](#-raw-data-4)
+    - [📤 Request](#-request-7)
+      - [Payload](#payload-12)
+      - [Example Request](#example-request-7)
+    - [📥 Response](#-response-7)
+      - [Payload](#payload-13)
+      - [Example Response](#example-response-7)
+    - [🗂 Serialized Data](#-serialized-data-3)
+    - [📤 Request](#-request-8)
+      - [Payload](#payload-14)
+      - [Example Request](#example-request-8)
+    - [📥 Response](#-response-8)
+      - [Payload](#payload-15)
+      - [Example Response](#example-response-8)
+  - [📄 License](#-license)
 <!-- TOC -->
 </details>
 
-*Last updated April 24th, 2024.*
+---
+
+## ⚙️ Configuration
+To configure the daemon, set the `TBC_ADDRESS` environment variable. For example:
+
+```
+TBC_ADDRESS=localhost:8082
+```
+
+When set, `tbcd` listens on the provided address, allowing for RPC communications.
+
+---
 
-When the `TBC_ADDRESS` environment variable is set (e.g. `TBC_ADDRESS=localhost:8082`), the `tbcd` daemon listens on the
-provided address.
+## 👉 RPC Client
+[`hemictl`](../../cmd/hemictl) serves as a reference implementation of an RPC client tailored for interacting with `tbcd`.
 
-[`hemictl`](../../cmd/hemictl) is a reference implementation of an RPC client.
+---
 
-[View the raw Go types used in TBC's RPC commands `api/tbcapi/tbcapi.go`](tbcapi.go).
+## 📚 Resources
+For developers looking to integrate or extend functionality, view the raw Go types used in TBC's RPC commands:
+[View `tbcapi.go`](tbcapi.go).
 
-## Protocol
+---
 
-The RPC protocol is WebSocket-based and uses a standard request/response model.
+## 📡 Protocol
 
-Please see [protocol/README.md](../protocol/README.md) for more information about the underlying RPC protocol.
+The **RPC protocol** is WebSocket-based and follows a standard request/response model. For more detailed information, refer to the [protocol documentation.](../protocol/README.md)
 
-### Errors
+---
+### 🚫 Errors
 
-If an error occurs during a request, the payload of the response contain an `error` value with the following data:
+If an error occurs during a request, the response payload will include an `error` value containing the following details:
 
-- `timestamp` is the time at which the error occurred, represented in Unix seconds.
-- `trace` (internal errors only) is a unique string which can be used to trace errors between a server and client.
-- `message` is the error message. If the error was an internal server error, this will be `internal error`.
 
-### Serialised types
+|Field      |Description                                                                             |
+|-----------|----------------------------------------------------------------------------------------|
+|`timestamp`|The time at which the error occurred, in Unix seconds.                                  |
+|`trace`    |A unique string for tracing errors between server and client (internal errors only).|
+|`message`  |The error message. For internal server errors, this will read `internal error`.         |
 
-#### Block Header
+---
+### 🗄️ Serialized Types
 
-A serialised block header contains the following data:
+####  Block Header
 
-- `version` is the version of the block.
-- `prev_hash` is the hash of the previous block header in the blockchain.
-- `merkle_root` is the hash derived from the hashes of all transactions included in the block.
-- `timestamp` is the time the miner began hashing the header, represented in Unix seconds.
-- `bits` is the difficulty target for the block.
-- `nonce` is the nonce used to create the hash that is less than or equal to the target threshold.
+A serialized block header includes:
+
+|Field        |Description                                                                    |
+|-------------|-------------------------------------------------------------------------------|
+|`version`    |The version of the block.                                                      |
+|`prev_hash`  |The hash of the previous block header in the blockchain.                       |
+|`merkle_root`|The hash derived from the hashes of all transactions in the block.             |
+|`timestamp`  |The time the miner began hashing the header, represented in Unix seconds.      |
+|`bits`       |The difficulty target for the block.                                           |
+|`nonce`      |The nonce used to create the hash that is **less than or equal to** the target threshold.|
 
 #### Address
 
-An address is an encoded Bitcoin address.
-Supported address types are P2PKH, P2SH, P2WPKH, P2WSH, and P2TR.
+Represents an encoded Bitcoin address, supporting these types:
+
+- `P2PKH`
+- `P2SH`
+- `P2WPKH`
+- `P2WSH`
+- `P2TR`
 
-#### UTXO
+####  UTXO
 
-A serialised UTXO contains the following data:
+A serialized UTXO includes:
 
-- `tx_id` is the transaction ID encoded as a hexadecimal string.
-- `value` is the value of the UTXO.
-- `out_index` is the output index for the UTXO.
+| Field       | Description                                |
+|-------------|--------------------------------------------|
+| `tx_id`     | The transaction ID, encoded as a hexadecimal string.|
+| `value`     | The value of the UTXO.                     |
+| `out_index` | The output index of the UTXO.              |
 
 #### Transaction
 
-A serialised transaction contains the following data:
+A serialized transaction contains the following data:
+
+| Field   | Description |
+|------------|----------------------------------------------------------------------------|
+| `version`  | The transaction version.                                                   |
+| `lock_time`| The block height or timestamp after which the transaction becomes final.   |
+| `tx_in`    | An array of [**transaction inputs**](#transaction-input).|
+| `tx_out`   | An array of [**transaction outputs**](#transaction-output).|
+
 
-- `version` is the transaction version.
-- `lock_time` is the block height or timestamp at which the transaction becomes final.
-- `tx_in` is an array of [transaction inputs](#transaction-input).
-- `tx_out` is an array of [transaction outputs](#transaction-output).
 
 #### Transaction Input
 
-A serialised transaction input contains the following data:
+A serialized transaction input contains the following data:
+
+| Field             | Description                                                      |
+|-------------------|------------------------------------------------------------------|
+| `outpoint`        | The [**outpoint**](#outpoint) for the previous transaction output.   |
+| `signature_script`| The signature script for the transaction.                        |
+| `witness`         | An array of the transaction witnesses, encoded as hexadecimal strings. |
+| `sequence`        | The transaction sequence number.                                 |
 
-- `outpoint` is the [outpoint](#outpoint) for the previous transaction output.
-- `signature_script` is the signature script for the transaction.
-- `witness` is an array of the transaction witnesses, encoded as hexadecimal strings.
-- `sequence` is the transaction sequence number.
 
 #### Transaction Output
 
-A serialised transaction output contains the following data:
+A serialized transaction output contains the following data:
+
+| Field      | Description                                                            |
+|------------|------------------------------------------------------------------------|
+| `value`    | The value of the transaction output in satoshis.                       |
+| `pk_script`| The pubkey script of the transaction output, encoded as a hexadecimal string. |
 
-- `value` is the value of the transaction output in satoshis.
-- `pk_script` is the pubkey script of the transaction output, encoded as a hexadecimal string.
 
 #### Outpoint
 
-A serialised outpoint contains the following data:
+A serialized outpoint contains the following data:
 
-- `hash` is the ID of the transaction holding the output to be spent.
-- `index` is the index of the specific output to spend from the transaction.
+| Field  | Description                                                  |
+|--------|--------------------------------------------------------------|
+| `hash` | The **ID** of the transaction holding the output to be spent.    |
+| `index`| The index of the specific output to spend from the transaction. |
 
-## Block Headers by Height
+---
+## 👉 Block Headers by Height
+Retrieve the block headers by height.
 
-### Raw data
+### 🗂 Raw Data
 
-| Type     | `command` value                               |
-|----------|-----------------------------------------------|
-| Request  | `tbcapi-block-headers-by-height-raw-request`  |
-| Response | `tbcapi-block-headers-by-height-raw-response` |
+| Type     | `command` value                              |
+|----------|---------------------------------------------|
+| Request  | `tbcapi-block-headers-by-height-raw-request`|
+| Response | `tbcapi-block-headers-by-height-raw-response`|
 
-#### Request
+### 📤 Request
 
-##### Payload
+#### Payload:
 
-- `height` is the height to at which block headers should be retrieved.
+- **`height`**: The height at which block headers should be retrieved.
 
-##### Example
+#### Example Request:
 
-An example request to retrieve block headers at height `43111`:
+Retrieve block headers at height `43111`:
 
 ```json
 {
@@ -196,15 +245,15 @@ An example request to retrieve block headers at height `43111`:
 }
 ```
 
-#### Response
+### 📥 Response
 
-##### Payload
+#### Payload:
 
-- `block_headers` is an array of raw block headers encoded as hexadecimal strings.
+- **`block_headers`**: An array of raw block headers encoded as hexadecimal strings.
 
-##### Example
+#### Example Response:
 
-An example response for a request with id `68656d69` and height `43111`:
+Response for a request with **id** `68656d69` and **height** `43111`:
 
 ```json
 {
@@ -220,22 +269,23 @@ An example response for a request with id `68656d69` and height `43111`:
 }
 ```
 
-### Serialised
 
-| Type     | `command` value                           |
-|----------|-------------------------------------------|
-| Request  | `tbcapi-block-headers-by-height-request`  |
-| Response | `tbcapi-block-headers-by-height-response` |
+### 🗂 Serialized Data
 
-#### Request
+| Type     | `command` value                              |
+|----------|---------------------------------------------|
+| Request  | `tbcapi-block-headers-by-height-request`    |
+| Response | `tbcapi-block-headers-by-height-response`   |
 
-##### Payload
+### 📤 Request
 
-- `height` is the height at which block headers should be retrieved.
+#### Payload
 
-##### Example
+- **`height`**: The height at which block headers should be retrieved.
 
-An example request to retrieve the block headers at height `43111`:
+#### Example Request
+
+Retrieve block headers at height `43111`:
 
 ```json
 {
@@ -249,15 +299,15 @@ An example request to retrieve the block headers at height `43111`:
 }
 ```
 
-#### Response
+### 📥 Response
 
-##### Payload
+#### Payload
 
-- `block_headers` is an array of [block headers](#block-header).
+- **`block_headers`**: An array of [block headers](#block-header).
 
-##### Example
+#### Example Response
 
-An example response for a request with id `68656d69` and height `43111`:
+Response for a request with **id** `68656d69` and **height** `43111`:
 
 ```json
 {
@@ -280,20 +330,24 @@ An example response for a request with id `68656d69` and height `43111`:
 }
 ```
 
-## Best Block Headers
+---
 
-### Raw data
+## 👉 Best Block Headers
 
-| Type     | `command` value                          |
-|----------|------------------------------------------|
-| Request  | `tbcapi-block-headers-best-raw-request`  |
-| Response | `tbcapi-block-headers-best-raw-response` |
+Retrieve the best block headers.
+
+### 🗂 Raw Data
 
-#### Request
+| Type     | `command` value                              |
+|----------|----------------------------------------------|
+| Request  | `tbcapi-block-headers-best-raw-request`      |
+| Response | `tbcapi-block-headers-best-raw-response`     |
 
-##### Example
+### 📤 Request
 
-An example request to retrieve the best block headers:
+#### Example Request
+
+Retrieve the best block headers:
 
 ```json
 {
@@ -304,16 +358,16 @@ An example request to retrieve the best block headers:
 }
 ```
 
-#### Response
+### 📥 Response
 
-##### Payload
+#### Payload
 
-- `height` is the best known height.
-- `block_headers` is an array of the best known block headers encoded as hexadecimal strings.
+- **`height`**: The best-known height.
+- **`block_headers`**: An array of the best-known block headers encoded as hexadecimal strings.
 
-##### Example
+#### Example Response
 
-An example response for a request with id `68656d69`, if the best height was `2182000`:
+Response for a request with **id** `68656d69` and **best height** `2182000`:
 
 ```json
 {
@@ -330,18 +384,18 @@ An example response for a request with id `68656d69`, if the best height was `21
 }
 ```
 
-### Serialised
+### 🗂 Serialized Data
 
-| Type     | `command` value                      |
-|----------|--------------------------------------|
-| Request  | `tbcapi-block-headers-best-request`  |
-| Response | `tbcapi-block-headers-best-response` |
+| Type     | `command` value                          |
+|----------|------------------------------------------|
+| Request  | `tbcapi-block-headers-best-request`      |
+| Response | `tbcapi-block-headers-best-response`     |
 
-#### Request
+### 📤 Request
 
-##### Example
+#### Example Request
 
-An example request to retrieve the best block headers:
+Retrieve the best block headers:
 
 ```json
 {
@@ -352,16 +406,16 @@ An example request to retrieve the best block headers:
 }
 ```
 
-#### Response
+### 📥 Response
 
-##### Payload
+#### Payload
 
-- `height` is the best known height.
-- `block_headers` is an array of best known [block headers](#block-header).
+- **`height`**: The best-known height.
+- **`block_headers`**: An array of best-known [block headers](#block-header).
 
-##### Example
+#### Example Response
 
-An example response for a request with id `68656d69`, if the best height was `2587400`:
+Response for a request with **id** `68656d69` and **height** `2587400`:
 
 ```json
 {
@@ -385,26 +439,25 @@ An example response for a request with id `68656d69`, if the best height was `25
 }
 ```
 
-## Balance by Address
-
+## 👉 Balance by Address
 Retrieve the balance for an address.
 
-### Raw
+### 🗂 Raw Data
 
-| Type     | `command` value                      |
-|----------|--------------------------------------|
-| Request  | `tbcapi-balance-by-address-request`  |
-| Response | `tbcapi-balance-by-address-response` |
+| Type     | `command` value                               |
+|----------|-----------------------------------------------|
+| Request  | `tbcapi-balance-by-address-request`           |
+| Response | `tbcapi-balance-by-address-response`          |
 
-#### Request
+### 📤 Request
 
-##### Payload
+#### Payload
 
-- `address` is the [address](#address) the balance should be retrieved for.
+- **`address`**: The [address](#address) for which the balance should be retrieved.
 
-##### Example
+#### Example Request
 
-An example request to retrieve the balance for the address `myqzZmRvoXmrhsrM5STiMGtNRxCFArHWRd`:
+Retrieve the balance for the address `myqzZmRvoXmrhsrM5STiMGtNRxCFArHWRd`:
 
 ```json
 {
@@ -418,48 +471,52 @@ An example request to retrieve the balance for the address `myqzZmRvoXmrhsrM5STi
 }
 ```
 
-#### Response
+### 📥 Response
 
-##### Payload
+#### Payload
 
-- `balance` is the known balance of the address, in satoshis.
+- **`balance`**: The known balance of the address, in satoshis.
 
-##### Example
+#### Example Response
 
-An example response for a request with id `68656d69`, if the address's balance is zero:
+Response for a request with **id** `68656d69`, if the address's **balance** is `0`:
 
 ```json
 {
   "header": {
     "command": "tbcapi-balance-by-address-response",
     "id": "68656d69"
-  },
+ },
   "payload": {
     "balance": 0
   }
 }
 ```
 
-## UTXOs by Address
+---
+
+## 👉 UTXOs by Address
 
-### Raw data
+Retrieve UTXOs by address.
 
-| Type     | `command` value                        |
-|----------|----------------------------------------|
-| Request  | `tbcapi-utxos-by-address-raw-request`  |
-| Response | `tbcapi-utxos-by-address-raw-response` |
+### 🗂 Raw Data
 
-#### Request
+| Type     | `command` value                         |
+|----------|-----------------------------------------|
+| Request  | `tbcapi-utxos-by-address-raw-request`   |
+| Response | `tbcapi-utxos-by-address-raw-response`  |
 
-##### Payload
+### 📤 Request
 
-- `address` is the [address](#address) to retrieve the UTXOs for.
-- `start` is the start index for the UTXOs that should be included in the response (or the number of UTXOs that should be skipped).
-- `count` is the maximum number of UTXOs that should be included in the response.
+#### Payload:
 
-##### Example
+- **`address`**: The [address](#address) to retrieve the UTXOs for.
+- **`start`**: The start index for the UTXOs that should be included in the response (or the number of UTXOs that should be skipped).
+- **`count`**: The maximum number of UTXOs that should be included in the response.
 
-An example request to retrieve five UTXOs for the address `mxVFsFW5N4mu1HPkxPttorvocvzeZ7KZyk`:
+#### Example Request:
+
+Retrieve five UTXOs for the address `mxVFsFW5N4mu1HPkxPttorvocvzeZ7KZyk`:
 
 ```json
 {
@@ -475,17 +532,15 @@ An example request to retrieve five UTXOs for the address `mxVFsFW5N4mu1HPkxPtto
 }
 ```
 
-#### Response
+### 📥 Response
 
-##### Payload
+#### Payload:
 
-- `utxos` is an array of known UTXOs for the address, encoded as hexadecimal strings, or `null` if there are no UTXOs
-  for the address.
+- **`utxos`**: An array of **known UTXOs** for the address, encoded as hexadecimal strings, or **`null`** if there are **no UTXOs** for the address.
 
-##### Example
+#### Example Response:
 
-An example response for a request with id `68656d69`, requesting five UTXOs for the
-address `mxVFsFW5N4mu1HPkxPttorvocvzeZ7KZyk`:
+Response for a request with **id** `68656d69`, **requesting 5 UTXOs** for the address `mxVFsFW5N4mu1HPkxPttorvocvzeZ7KZyk`:
 
 ```json
 {
@@ -505,24 +560,24 @@ address `mxVFsFW5N4mu1HPkxPttorvocvzeZ7KZyk`:
 }
 ```
 
-### Serialised
+### 🗂 Serialized Data
 
-| Type     | `command` value                    |
-|----------|------------------------------------|
-| Request  | `tbcapi-utxos-by-address-request`  |
-| Response | `tbcapi-utxos-by-address-response` |
+| Type     | `command` value                   |
+|----------|-----------------------------------|
+| Request  | `tbcapi-utxos-by-address-request` |
+| Response | `tbcapi-utxos-by-address-response`|
 
-#### Request
+### 📤 Request
 
-##### Payload
+#### Payload:
 
-- `address` is the [address](#address) to retrieve the UTXOs for.
-- `start` is the start index for the UTXOs that should be included in the response (or the number of UTXOs that should be skipped).
-- `count` is the maximum number of UTXOs that should be included in the response.
+- **`address`**: The [address](#address) to retrieve the UTXOs for.
+- **`start`**: The start index for the UTXOs that should be included in the response (or the number of UTXOs that should be skipped).
+- **`count`**: The maximum number of UTXOs that should be included in the response.
 
-##### Example
+#### Example Request:
 
-An example request to retrieve five UTXOs for the address `mxVFsFW5N4mu1HPkxPttorvocvzeZ7KZyk`:
+**Retrieve 5 UTXOs** for the address `mxVFsFW5N4mu1HPkxPttorvocvzeZ7KZyk`:
 
 ```json
 {
@@ -538,16 +593,15 @@ An example request to retrieve five UTXOs for the address `mxVFsFW5N4mu1HPkxPtto
 }
 ```
 
-#### Response
+### 📥 Response
 
-##### Payload
+#### Payload:
 
-- `utxos` is an array of known [UTXOs](#utxo). The maximum number of items in this array can be changed
-  with `count` in the request.
+- **`utxos`**: An array of known [**UTXOs**](#utxo). The maximum number of items in this array can be changed with **`count`** in the request.
 
-##### Example
+#### Example Response:
 
-An example response for a request with id `68656d69`, if the best height was `2587400`:
+Response for a request with **id** `68656d69`, **showing 5 UTXOs** for the address:
 
 ```json
 {
@@ -586,23 +640,23 @@ An example response for a request with id `68656d69`, if the best height was `25
   }
 }
 ```
+---
 
-## Transaction by ID
 
-### Raw data
+## 👉 Transaction by ID
 
-| Type     | `command` value                 |
-|----------|---------------------------------|
-| Request  | `tbcapi-tx-by-id-raw-request`   |
-| Response | `ttbcapi-tx-by-id-raw-response` |
+### 🗂 Raw Data
 
-#### Request
+| Type     | `command` value                     |
+|----------|-------------------------------------|
+| Request  | `tbcapi-tx-by-id-raw-request`       |
+| Response | `ttbcapi-tx-by-id-raw-response`     |
 
-##### Payload
+### 📤 Request
 
-- `tx_id` is the ID of the transaction to retrieve, encoded as a hexadecimal string.
+#### Payload
 
-##### Example
+- **`tx_id`**: The ID of the transaction to retrieve, encoded as a hexadecimal string.
 
 An example request to retrieve the transaction `0584ad53bf1938702b952026f7c986ab5d07ee7295c0ad3241c932a5483158ac`:
 
@@ -618,13 +672,13 @@ An example request to retrieve the transaction `0584ad53bf1938702b952026f7c986ab
 }
 ```
 
-#### Response
+### 📥 Response
 
-##### Payload
+#### Payload
 
-- `tx` is the transaction, encoded as a hexadecimal string.
+- **`tx`**: The transaction (encoded as a hexadecimal string).
 
-##### Example
+#### Example Response
 
 An example response for a request with id `68656d69`, requesting the
 transaction `0584ad53bf1938702b952026f7c986ab5d07ee7295c0ad3241c932a5483158ac`:
@@ -641,20 +695,20 @@ transaction `0584ad53bf1938702b952026f7c986ab5d07ee7295c0ad3241c932a5483158ac`:
 }
 ```
 
-### Serialised
+### 🗂 Serialized Data
 
-| Type     | `command` value            |
-|----------|----------------------------|
-| Request  | `tbcapi-tx-by-id-request`  |
-| Response | `tbcapi-tx-by-id-response` |
+| Type     | `command` value                |
+|----------|--------------------------------|
+| Request  | `tbcapi-tx-by-id-request`      |
+| Response | `tbcapi-tx-by-id-response`     |
 
-#### Request
+### 📤 Request
 
-##### Payload
+#### Payload
 
-- `tx_id` is the ID of the transaction to retrieve, encoded as a hexadecimal string.
+- **`tx_id`**: The ID of the transaction to retrieve, encoded as a hexadecimal string.
 
-##### Example
+#### Example Request
 
 An example request to retrieve the transaction `0584ad53bf1938702b952026f7c986ab5d07ee7295c0ad3241c932a5483158ac`:
 
@@ -670,13 +724,13 @@ An example request to retrieve the transaction `0584ad53bf1938702b952026f7c986ab
 }
 ```
 
-#### Response
+### 📥 Response
 
-##### Payload
+#### Payload
 
-- `tx` is the requested [transaction](#transaction), if found, otherwise `null`.
+- **`tx`**: The requested [transaction](#transaction), if found, otherwise **`null`**.
 
-##### Example
+#### Example Response
 
 An example response for a request with id `68656d69`, requesting the
 transaction `0584ad53bf1938702b952026f7c986ab5d07ee7295c0ad3241c932a5483158ac`:
@@ -712,3 +766,8 @@ transaction `0584ad53bf1938702b952026f7c986ab5d07ee7295c0ad3241c932a5483158ac`:
   }
 }
 ```
+
+--
+## 📄 License
+
+This project is licensed under the [MIT License](../../LICENSE).
diff --git a/cmd/tbcd/README.md b/cmd/tbcd/README.md
index b5582615..224ab8de 100644
--- a/cmd/tbcd/README.md
+++ b/cmd/tbcd/README.md
@@ -1,71 +1,71 @@
-# Hemi Tiny Bitcoin Daemon
+# 🌐 Hemi Tiny Bitcoin Daemon (`tbcd`)
 
-`tbcd` is a very minimal Bitcoin block downloader and indexer daemon. It wraps the `tbc` service which is meant for
-embedding in other applications that require access to Bitcoin data (blocks and TXes). The daemon is primarily used as a
-network RPC endpoint.
+`tbcd` is a **minimal Bitcoin block downloader** and **indexer daemon**. It is designed to wrap the `tbc` service, which provides Bitcoin data **(blocks and transactions)** for other applications. Primarily, **it functions as a network RPC endpoint.**
 
-## System requirements
 
-The `tbc` server downloads all Bitcoin blocks and generates various indexes and thus requires a large amount of
-available disk space.
 
-Running `tbc` will likely require at least:
- - 4 CPU cores
- - 8 GiB RAM
- - NVMe disk
+## 🖥️ System Requirements
+`tbcd` requires significant system resources due to its functionality:
 
-As of April 18, 2024, `testnet3` uses ~40 GiB and `mainnet` >300 GiB of disk space. <!-- XXX: add exact number here -->
+| Requirement     | Specification    |
+|-----------------|------------------|
+| **CPU Cores**   | 4                |
+| **RAM**         | 8 GiB            |
+| **Disk**        | NVMe recommended |
 
-## Building
+**As of April 18, 2024:**
+- **`testnet3`** requires approximately 40 GiB of disk space.
+- **`mainnet`** requires over 300 GiB of disk space. <!-- XXX: add exact number here -->
 
-To build `tbcd`, you must have the following installed:
- - Go v1.22 or newer
+---
+## 🛠️ Building `tbcd`
 
-### Makefile
+### 🏁 Prerequisites:
 
-To build `tbcd` with the heminetwork Makefile (requires `make` to be installed):
+Ensure Go v1.22 or newer is installed on your system.
+
+### Using Makefile
+
+To build `tbcd` using the provided Makefile
+
+  > [!NOTE]
+  > 🏁 Prerequisites: Install **`make`**
 
 ```shell
 cd heminetwork
-
-# Build (output binary will be written to bin/tbcd or bin/tbcd.exe)
-make tbcd
+make tbcd  # Output binary will be written to bin/tbcd or bin/tbcd.exe
 ```
 
-### Standalone
+### Standalone Build
 
-To build `tbcd` without using the heminetwork Makefile:
+If you prefer not to use the Makefile:
 
 ```shell
 cd heminetwork
-
-# Build (output binary will be called tbcd or tbcd.exe)
-go build ./cmd/tbcd/
-
-# Install (output binary will be written to your GOBIN directory)
-go install ./cmd/tbcd/
+go build ./cmd/tbcd/      # Build the binary (output will be tbcd or tbcd.exe)
+go install ./cmd/tbcd/    # Install the binary (output will be in your GOBIN directory)
 ```
+---
+## 🌐 Environment Settings
 
-## Environment
-
-On some systems, you may need to increase the limits for the number of open files, memory and the maximum stack size.
+`tbcd` **checks system limits at startup on supported platforms** to ensure that they are set to values that will allow TBC to run without failing.
 
-At startup, TBC will attempt to verify these limits on supported platforms, to ensure that they are set to values that
-will allow TBC to run without failing.
-
-If you see an error similar to the following, you will need to adjust the limits on your system in order to run TBC.
+  > [!WARNING]
+  > If you see an error similar to the following, you will need to adjust the limits for the number of open files, memory and the maximum stack size on your system to run TBC.
 ```
 ulimit: memory: limit too low got X, want X
 ```
 
 Changing limits is OS-specific, but can usually be done using the `ulimit` command.
 
-## Runtime settings
+## ⚙️ Runtime Settings
+
+
+`tbcd` is **designed to be run in cloud environments**, as such it only uses environment variables for runtime settings.
 
-`tbcd` is designed to be run in cloud environments, as such it only uses environment variables for runtime settings.
-They can be either be exported or included on the evocation of the binary.
+They can either be exported or included in the evocation of the binary.
 
-To see a full list of runtime settings, execute `tbcd` with the `--help` flag:
+To see a full list of runtime settings, execute `tbcd` with the **`--help`** flag:
 
 ```shell
 /path/to/tbcd --help
@@ -83,19 +83,21 @@ To see a full list of runtime settings, execute `tbcd` with the `--help` flag:
 #         TBC_PROMETHEUS_ADDRESS: address and port tbcd prometheus listens on
 ```
 
-You can start the `tbcd` server by running:
-
+Start the server by running:
 ```shell
 /path/to/tbcd
 ```
 
-## RPC commands
+## 👉 RPC Commands
+
+When the `TBC_ADDRESS` is set (e.g., `localhost:8082`), the`tbcd` daemon listens on the provided address.
 
-When the `TBC_ADDRESS` environment variable is set, the `tbcd` daemon listens on the provided address.
-The RPC protocol is WebSocket-based and uses a standard request/response model.
+The RPC protocol is **WebSocket-based** and **uses a standard request/response model.**
 
 [Read more about the RPC protocol and available commands](../../api/tbcapi/README.md).
 
-### License
+---
+
+## 📄 License
 
 This project is licensed under the [MIT License](../../LICENSE).
diff --git a/database/.DS_Store b/database/.DS_Store
new file mode 100644
index 0000000000000000000000000000000000000000..81ecdcd31e10caa3ca75a20ee4936bf72b6184d2
GIT binary patch
literal 6148
zcmeH~F$w}f3`G;&La^D=avBfd4F=H@>;*)`ZA3xPdXDZ-CJ2t!BJu;tpJXO1`-+{7
zi0JxuSc&u^GJ~7S(n4d3ypz2gWt78xxSmg!^N5<&Cvn!+@Lrnz*rt#G36KB@kN^q%
z5COZlVY7KvMiL+a5_l4@??Zx{=Fn2rKOG1@0zf;I-LUpq0-CG<&7q|#Dlm=dL8DcD
z46(YmLsOi~p`~hV7meXV<H>4M3`}dgXhH(h?7~0-B+w9;*1Wg-e+&OK|2Hj6Nq_|Y
zjDU8VVY9|d#ohY$dRE^>)z$?L_2URHKLJSWDqg_du%B!J&7q|#Dlq;CI0gn1_$q-1
D;=2;2

literal 0
HcmV?d00001


From 3b38daf72a60b297f756bbf4bef17458bc4eb270 Mon Sep 17 00:00:00 2001
From: Jane <32560576+jsorkin24@users.noreply.github.com>
Date: Fri, 26 Apr 2024 11:26:53 -0700
Subject: [PATCH 20/39] Issues Addressed (minor grammar changes)

---
 api/protocol/README.md | 14 ++++----------
 1 file changed, 4 insertions(+), 10 deletions(-)

diff --git a/api/protocol/README.md b/api/protocol/README.md
index 8aa2b7cc..86867715 100644
--- a/api/protocol/README.md
+++ b/api/protocol/README.md
@@ -4,10 +4,9 @@ The **RPC protocol** used by Hemi's daemons is WebSocket-based and uses **JSON-e
 
 The JSON data sent over WebSocket connections are referred to as **"messages"**.
 
----
 ## 📩 Message Format
 
-Every RPC message has the following format:
+An RPC message has the following format:
 
 ```json
 {
@@ -23,17 +22,12 @@ Every RPC message has the following format:
 
 The message header includes metadata crucial for processing the message:
 
-- **`command`**: Specifies the command being executed.
+- **`command`**: The name of the command being executed.
 - **`id`**: A string used to uniquely identify each request. Responses will have the same `id` as the request, making it possible to match requests to responses.
 
-  > [!NOTE]
-  > Message IDs should be randomly generated.
+> [!NOTE]
+> Request message IDs should be randomly generated.
 
 ### Payload
 
 The payload type depends on the command being called. Please refer to the documentation for more details on the specific API you wish to use.
-
----
-## 📄 License
-
-This project is licensed under the [MIT License](../../LICENSE).

From c14ddad38e922a202cd9bb921756266dc69367cd Mon Sep 17 00:00:00 2001
From: Jane <32560576+jsorkin24@users.noreply.github.com>
Date: Wed, 1 May 2024 09:48:08 -0700
Subject: [PATCH 21/39] Changes Updated

---
 README.md          | 34 +++++++++++++++++-----------------
 cmd/tbcd/README.md |  7 +------
 2 files changed, 18 insertions(+), 23 deletions(-)

diff --git a/README.md b/README.md
index 3028702d..f19d2e3f 100644
--- a/README.md
+++ b/README.md
@@ -1,23 +1,21 @@
-# 🌐 The Hemi Network
-
-
-***Last updated:** April 25th, 2024*
+# ⚡️ The Hemi Network
 
 Hemi is an EVM-compatible L2 blockchain that combines the security of Bitcoin with the programmability of Ethereum.
 
 <details>
-  <summary style="color: #FF5F00; font-weight: 500; font-size: 1.5rem;"> Table of Contents</summary>
+  <summary> Table of Contents</summary>
 
-- [🌐 The Hemi Network](#-the-hemi-network)
+- [⚡️ The Hemi Network](#️-the-hemi-network)
   - [🔧 Services](#-services)
-  - [📜 TL;DR:](#-tldr)
-  - [⚡️ Getting Started](#️-getting-started)
+  - [🌐 Overview:](#-overview)
+- [⚡️ Getting Started](#️-getting-started)
+  - [🏗 Building from Source](#-building-from-source)
     - [🏁 Prerequisites](#-prerequisites)
     - [📚 Tutorial](#-tutorial)
-  - [📦 Downloading Binaries from Releases](#-downloading-binaries-from-releases)
+  - [📦 Downloading Release Binaries](#-downloading-release-binaries)
 - [🛠 Running the Services](#-running-the-services)
   - [▶️ Running popmd](#️-running-popmd)
-    - [🏁 Prerequisites:](#-prerequisites-1)
+    - [🏁 Prerequisites](#-prerequisites-1)
     - [CLI:](#cli)
     - [Web:](#web)
   - [▶️ Running bfgd](#️-running-bfgd)
@@ -46,7 +44,7 @@ The Hemi Network comprises three key services, each serving a unique function wi
 
 
 ---
-## 📜 TL;DR:
+## 🌐 Overview:
 
 - **extool**: A utility tool for extracting and processing data from various file formats, tailored for blockchain data analysis.
 - **hemictl**: The command-line interface for controlling and managing all Hemi Network services.
@@ -58,7 +56,9 @@ The Hemi Network comprises three key services, each serving a unique function wi
 
 ---
 
-## ⚡️ Getting Started
+# ⚡️ Getting Started
+
+## 🏗 Building from Source
 
 ### 🏁 Prerequisites
 
@@ -72,11 +72,11 @@ The Hemi Network comprises three key services, each serving a unique function wi
 
 
 1. Clone the Repository:
-   ```bash
+   ```shell
    git clone https://github.com/hemilabs/heminetwork.git
    ```
 2. Build:
-   ```bash
+   ```shell
    cd heminetwork
    make deps
    make
@@ -86,7 +86,7 @@ Binaries will be located in `<path-to-repo>/bin/`.
 
 ---
 
-## 📦 Downloading Binaries from Releases
+## 📦 Downloading Release Binaries
 
 Pre-built binaries are available on the [Releases Page](https://github.com/hemilabs/heminetwork/releases).
 
@@ -104,12 +104,12 @@ For any service, you can view configuration options by running:
 
 ## ▶️ Running popmd
 
-### 🏁 Prerequisites:
+### 🏁 Prerequisites
 
 - A funded BTC private key. This can be a testnet address if configured for test environments.
 - A BFG URL to establish a connection.
 
-Once properly configured and running, `popmd` will start **mining** L2 Keystones by adding them to Bitcoin blocks that make it into the chain.
+Once properly configured and running, `popmd` will start mining L2 Keystones by adding them to Bitcoin blocks that make it into the chain.
 
 ### CLI:
 
diff --git a/cmd/tbcd/README.md b/cmd/tbcd/README.md
index 224ab8de..61038186 100644
--- a/cmd/tbcd/README.md
+++ b/cmd/tbcd/README.md
@@ -90,14 +90,9 @@ Start the server by running:
 
 ## 👉 RPC Commands
 
-When the `TBC_ADDRESS` is set (e.g., `localhost:8082`), the`tbcd` daemon listens on the provided address.
+When the `TBC_ADDRESS` is set to an address (e.g., `localhost:8082`), the `tbcd` daemon listens on the provided address.
 
 The RPC protocol is **WebSocket-based** and **uses a standard request/response model.**
 
 [Read more about the RPC protocol and available commands](../../api/tbcapi/README.md).
 
----
-
-## 📄 License
-
-This project is licensed under the [MIT License](../../LICENSE).

From 3ec162e797e0a6b9e468aa575dc9ad58858e4d91 Mon Sep 17 00:00:00 2001
From: Jane <32560576+jsorkin24@users.noreply.github.com>
Date: Wed, 1 May 2024 09:49:37 -0700
Subject: [PATCH 22/39] Remove Styling

---
 README.md            | 2 +-
 api/tbcapi/README.md | 5 ++---
 2 files changed, 3 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index f19d2e3f..cdf8d75f 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,7 @@
 Hemi is an EVM-compatible L2 blockchain that combines the security of Bitcoin with the programmability of Ethereum.
 
 <details>
-  <summary> Table of Contents</summary>
+  <summary>Table of Contents</summary>
 
 - [⚡️ The Hemi Network](#️-the-hemi-network)
   - [🔧 Services](#-services)
diff --git a/api/tbcapi/README.md b/api/tbcapi/README.md
index 3799e08d..ea0201b9 100644
--- a/api/tbcapi/README.md
+++ b/api/tbcapi/README.md
@@ -5,7 +5,7 @@
 This document provides details on the RPC setup and client implementation for the Hemi Tiny Bitcoin Daemon **(`tbcd`).**
 
 <details>
-  <summary style="color: #FF5F00; font-weight: 500; font-size: 1.5rem;">📜 Table of Contents</summary>
+  <summary>📜 Table of Contents</summary>
 
 <!-- TOC -->
 - [📡 Hemi Tiny Bitcoin Daemon RPC](#-hemi-tiny-bitcoin-daemon-rpc)
@@ -77,14 +77,13 @@ This document provides details on the RPC setup and client implementation for th
     - [🗂 Raw Data](#-raw-data-4)
     - [📤 Request](#-request-7)
       - [Payload](#payload-12)
-      - [Example Request](#example-request-7)
     - [📥 Response](#-response-7)
       - [Payload](#payload-13)
       - [Example Response](#example-response-7)
     - [🗂 Serialized Data](#-serialized-data-3)
     - [📤 Request](#-request-8)
       - [Payload](#payload-14)
-      - [Example Request](#example-request-8)
+      - [Example Request](#example-request-7)
     - [📥 Response](#-response-8)
       - [Payload](#payload-15)
       - [Example Response](#example-response-8)

From 817181abb98624a2a96fd2a855a2e247a44cbefb Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Wed, 15 May 2024 22:48:28 +1000
Subject: [PATCH 23/39] docs: reformat tbcapi readme

---
 api/tbcapi/README.md | 360 ++++++++++++++++++++++---------------------
 1 file changed, 182 insertions(+), 178 deletions(-)

diff --git a/api/tbcapi/README.md b/api/tbcapi/README.md
index ea0201b9..1ccc69d5 100644
--- a/api/tbcapi/README.md
+++ b/api/tbcapi/README.md
@@ -5,95 +5,95 @@
 This document provides details on the RPC setup and client implementation for the Hemi Tiny Bitcoin Daemon **(`tbcd`).**
 
 <details>
-  <summary>📜 Table of Contents</summary>
+  <summary>Table of Contents</summary>
 
 <!-- TOC -->
-- [📡 Hemi Tiny Bitcoin Daemon RPC](#-hemi-tiny-bitcoin-daemon-rpc)
-  - [⚙️ Configuration](#️-configuration)
-  - [👉 RPC Client](#-rpc-client)
-  - [📚 Resources](#-resources)
-  - [📡 Protocol](#-protocol)
-    - [🚫 Errors](#-errors)
-    - [🗄️ Serialized Types](#️-serialized-types)
-      - [Block Header](#block-header)
-      - [Address](#address)
-      - [UTXO](#utxo)
-      - [Transaction](#transaction)
-      - [Transaction Input](#transaction-input)
-      - [Transaction Output](#transaction-output)
-      - [Outpoint](#outpoint)
-  - [👉 Block Headers by Height](#-block-headers-by-height)
-    - [🗂 Raw Data](#-raw-data)
-    - [📤 Request](#-request)
-      - [Payload:](#payload)
-      - [Example Request:](#example-request)
-    - [📥 Response](#-response)
-      - [Payload:](#payload-1)
-      - [Example Response:](#example-response)
-    - [🗂 Serialized Data](#-serialized-data)
-    - [📤 Request](#-request-1)
-      - [Payload](#payload-2)
-      - [Example Request](#example-request-1)
-    - [📥 Response](#-response-1)
-      - [Payload](#payload-3)
-      - [Example Response](#example-response-1)
-  - [👉 Best Block Headers](#-best-block-headers)
-    - [🗂 Raw Data](#-raw-data-1)
-    - [📤 Request](#-request-2)
-      - [Example Request](#example-request-2)
-    - [📥 Response](#-response-2)
-      - [Payload](#payload-4)
-      - [Example Response](#example-response-2)
-    - [🗂 Serialized Data](#-serialized-data-1)
-    - [📤 Request](#-request-3)
-      - [Example Request](#example-request-3)
-    - [📥 Response](#-response-3)
-      - [Payload](#payload-5)
-      - [Example Response](#example-response-3)
-  - [👉 Balance by Address](#-balance-by-address)
-    - [🗂 Raw Data](#-raw-data-2)
-    - [📤 Request](#-request-4)
-      - [Payload](#payload-6)
-      - [Example Request](#example-request-4)
-    - [📥 Response](#-response-4)
-      - [Payload](#payload-7)
-      - [Example Response](#example-response-4)
-  - [👉 UTXOs by Address](#-utxos-by-address)
-    - [🗂 Raw Data](#-raw-data-3)
-    - [📤 Request](#-request-5)
-      - [Payload:](#payload-8)
-      - [Example Request:](#example-request-5)
-    - [📥 Response](#-response-5)
-      - [Payload:](#payload-9)
-      - [Example Response:](#example-response-5)
-    - [🗂 Serialized Data](#-serialized-data-2)
-    - [📤 Request](#-request-6)
-      - [Payload:](#payload-10)
-      - [Example Request:](#example-request-6)
-    - [📥 Response](#-response-6)
-      - [Payload:](#payload-11)
-      - [Example Response:](#example-response-6)
-  - [👉 Transaction by ID](#-transaction-by-id)
-    - [🗂 Raw Data](#-raw-data-4)
-    - [📤 Request](#-request-7)
-      - [Payload](#payload-12)
-    - [📥 Response](#-response-7)
-      - [Payload](#payload-13)
-      - [Example Response](#example-response-7)
-    - [🗂 Serialized Data](#-serialized-data-3)
-    - [📤 Request](#-request-8)
-      - [Payload](#payload-14)
-      - [Example Request](#example-request-7)
-    - [📥 Response](#-response-8)
-      - [Payload](#payload-15)
-      - [Example Response](#example-response-8)
-  - [📄 License](#-license)
+* [📡 Hemi Tiny Bitcoin Daemon RPC](#-hemi-tiny-bitcoin-daemon-rpc)
+  * [⚙️ Configuration](#-configuration)
+  * [👉 RPC Client](#-rpc-client)
+  * [📚 Resources](#-resources)
+  * [📡 Protocol](#-protocol)
+    * [🚫 Errors](#-errors)
+    * [🗄️ Serialized Types](#-serialized-types)
+      * [Block Header](#block-header)
+      * [Address](#address)
+      * [UTXO](#utxo)
+      * [Transaction](#transaction)
+      * [Transaction Input](#transaction-input)
+      * [Transaction Output](#transaction-output)
+      * [Outpoint](#outpoint)
+  * [👉 Block Headers by Height](#-block-headers-by-height)
+    * [🗂 Raw Data](#-raw-data)
+    * [📤 Request](#-request)
+      * [Payload:](#payload)
+      * [Example Request:](#example-request)
+    * [📥 Response](#-response)
+      * [Payload:](#payload-1)
+      * [Example Response:](#example-response)
+    * [🗂 Serialized Data](#-serialized-data)
+    * [📤 Request](#-request-1)
+      * [Payload](#payload-2)
+      * [Example Request](#example-request-1)
+    * [📥 Response](#-response-1)
+      * [Payload](#payload-3)
+      * [Example Response](#example-response-1)
+  * [👉 Best Block Headers](#-best-block-headers)
+    * [🗂 Raw Data](#-raw-data-1)
+    * [📤 Request](#-request-2)
+      * [Example Request](#example-request-2)
+    * [📥 Response](#-response-2)
+      * [Payload](#payload-4)
+      * [Example Response](#example-response-2)
+    * [🗂 Serialized Data](#-serialized-data-1)
+    * [📤 Request](#-request-3)
+      * [Example Request](#example-request-3)
+    * [📥 Response](#-response-3)
+      * [Payload](#payload-5)
+      * [Example Response](#example-response-3)
+  * [👉 Balance by Address](#-balance-by-address)
+    * [🗂 Raw Data](#-raw-data-2)
+    * [📤 Request](#-request-4)
+      * [Payload](#payload-6)
+      * [Example Request](#example-request-4)
+    * [📥 Response](#-response-4)
+      * [Payload](#payload-7)
+      * [Example Response](#example-response-4)
+  * [👉 UTXOs by Address](#-utxos-by-address)
+    * [🗂 Raw Data](#-raw-data-3)
+    * [📤 Request](#-request-5)
+      * [Payload:](#payload-8)
+      * [Example Request:](#example-request-5)
+    * [📥 Response](#-response-5)
+      * [Payload:](#payload-9)
+      * [Example Response:](#example-response-5)
+    * [🗂 Serialized Data](#-serialized-data-2)
+    * [📤 Request](#-request-6)
+      * [Payload:](#payload-10)
+      * [Example Request:](#example-request-6)
+    * [📥 Response](#-response-6)
+      * [Payload:](#payload-11)
+      * [Example Response:](#example-response-6)
+  * [👉 Transaction by ID](#-transaction-by-id)
+    * [🗂 Raw Data](#-raw-data-4)
+    * [📤 Request](#-request-7)
+      * [Payload](#payload-12)
+    * [📥 Response](#-response-7)
+      * [Payload](#payload-13)
+      * [Example Response](#example-response-7)
+    * [🗂 Serialized Data](#-serialized-data-3)
+    * [📤 Request](#-request-8)
+      * [Payload](#payload-14)
+      * [Example Request](#example-request-7)
+    * [📥 Response](#-response-8)
+      * [Payload](#payload-15)
+      * [Example Response](#example-response-8)
 <!-- TOC -->
 </details>
 
 ---
 
 ## ⚙️ Configuration
+
 To configure the daemon, set the `TBC_ADDRESS` environment variable. For example:
 
 ```
@@ -105,11 +105,14 @@ When set, `tbcd` listens on the provided address, allowing for RPC communication
 ---
 
 ## 👉 RPC Client
-[`hemictl`](../../cmd/hemictl) serves as a reference implementation of an RPC client tailored for interacting with `tbcd`.
+
+[`hemictl`](../../cmd/hemictl) serves as a reference implementation of an RPC client tailored for interacting
+with `tbcd`.
 
 ---
 
 ## 📚 Resources
+
 For developers looking to integrate or extend functionality, view the raw Go types used in TBC's RPC commands:
 [View `tbcapi.go`](tbcapi.go).
 
@@ -117,35 +120,38 @@ For developers looking to integrate or extend functionality, view the raw Go typ
 
 ## 📡 Protocol
 
-The **RPC protocol** is WebSocket-based and follows a standard request/response model. For more detailed information, refer to the [protocol documentation.](../protocol/README.md)
+The **RPC protocol** is WebSocket-based and follows a standard request/response model. For more detailed information,
+refer to the [protocol documentation.](../protocol/README.md)
 
 ---
-### 🚫 Errors
 
-If an error occurs during a request, the response payload will include an `error` value containing the following details:
+### 🚫 Errors
 
+If an error occurs during a request, the response payload will include an `error` value containing the following
+details:
 
-|Field      |Description                                                                             |
-|-----------|----------------------------------------------------------------------------------------|
-|`timestamp`|The time at which the error occurred, in Unix seconds.                                  |
-|`trace`    |A unique string for tracing errors between server and client (internal errors only).|
-|`message`  |The error message. For internal server errors, this will read `internal error`.         |
+| Field       | Description                                                                          |
+|-------------|--------------------------------------------------------------------------------------|
+| `timestamp` | The time at which the error occurred, in Unix seconds.                               |
+| `trace`     | A unique string for tracing errors between server and client (internal errors only). |
+| `message`   | The error message. For internal server errors, this will read `internal error`.      |
 
 ---
+
 ### 🗄️ Serialized Types
 
-####  Block Header
+#### Block Header
 
 A serialized block header includes:
 
-|Field        |Description                                                                    |
-|-------------|-------------------------------------------------------------------------------|
-|`version`    |The version of the block.                                                      |
-|`prev_hash`  |The hash of the previous block header in the blockchain.                       |
-|`merkle_root`|The hash derived from the hashes of all transactions in the block.             |
-|`timestamp`  |The time the miner began hashing the header, represented in Unix seconds.      |
-|`bits`       |The difficulty target for the block.                                           |
-|`nonce`      |The nonce used to create the hash that is **less than or equal to** the target threshold.|
+| Field         | Description                                                                               |
+|---------------|-------------------------------------------------------------------------------------------|
+| `version`     | The version of the block.                                                                 |
+| `prev_hash`   | The hash of the previous block header in the blockchain.                                  |
+| `merkle_root` | The hash derived from the hashes of all transactions in the block.                        |
+| `timestamp`   | The time the miner began hashing the header, represented in Unix seconds.                 |
+| `bits`        | The difficulty target for the block.                                                      |
+| `nonce`       | The nonce used to create the hash that is **less than or equal to** the target threshold. |
 
 #### Address
 
@@ -157,70 +163,68 @@ Represents an encoded Bitcoin address, supporting these types:
 - `P2WSH`
 - `P2TR`
 
-####  UTXO
+#### UTXO
 
 A serialized UTXO includes:
 
-| Field       | Description                                |
-|-------------|--------------------------------------------|
-| `tx_id`     | The transaction ID, encoded as a hexadecimal string.|
-| `value`     | The value of the UTXO.                     |
-| `out_index` | The output index of the UTXO.              |
+| Field       | Description                                          |
+|-------------|------------------------------------------------------|
+| `tx_id`     | The transaction ID, encoded as a hexadecimal string. |
+| `value`     | The value of the UTXO.                               |
+| `out_index` | The output index of the UTXO.                        |
 
 #### Transaction
 
 A serialized transaction contains the following data:
 
-| Field   | Description |
-|------------|----------------------------------------------------------------------------|
-| `version`  | The transaction version.                                                   |
-| `lock_time`| The block height or timestamp after which the transaction becomes final.   |
-| `tx_in`    | An array of [**transaction inputs**](#transaction-input).|
-| `tx_out`   | An array of [**transaction outputs**](#transaction-output).|
-
-
+| Field       | Description                                                              |
+|-------------|--------------------------------------------------------------------------|
+| `version`   | The transaction version.                                                 |
+| `lock_time` | The block height or timestamp after which the transaction becomes final. |
+| `tx_in`     | An array of [**transaction inputs**](#transaction-input).                |
+| `tx_out`    | An array of [**transaction outputs**](#transaction-output).              |
 
 #### Transaction Input
 
 A serialized transaction input contains the following data:
 
-| Field             | Description                                                      |
-|-------------------|------------------------------------------------------------------|
-| `outpoint`        | The [**outpoint**](#outpoint) for the previous transaction output.   |
-| `signature_script`| The signature script for the transaction.                        |
-| `witness`         | An array of the transaction witnesses, encoded as hexadecimal strings. |
-| `sequence`        | The transaction sequence number.                                 |
-
+| Field              | Description                                                            |
+|--------------------|------------------------------------------------------------------------|
+| `outpoint`         | The [**outpoint**](#outpoint) for the previous transaction output.     |
+| `signature_script` | The signature script for the transaction.                              |
+| `witness`          | An array of the transaction witnesses, encoded as hexadecimal strings. |
+| `sequence`         | The transaction sequence number.                                       |
 
 #### Transaction Output
 
 A serialized transaction output contains the following data:
 
-| Field      | Description                                                            |
-|------------|------------------------------------------------------------------------|
-| `value`    | The value of the transaction output in satoshis.                       |
-| `pk_script`| The pubkey script of the transaction output, encoded as a hexadecimal string. |
-
+| Field       | Description                                                                   |
+|-------------|-------------------------------------------------------------------------------|
+| `value`     | The value of the transaction output in satoshis.                              |
+| `pk_script` | The pubkey script of the transaction output, encoded as a hexadecimal string. |
 
 #### Outpoint
 
 A serialized outpoint contains the following data:
 
-| Field  | Description                                                  |
-|--------|--------------------------------------------------------------|
-| `hash` | The **ID** of the transaction holding the output to be spent.    |
-| `index`| The index of the specific output to spend from the transaction. |
+| Field   | Description                                                     |
+|---------|-----------------------------------------------------------------|
+| `hash`  | The **ID** of the transaction holding the output to be spent.   |
+| `index` | The index of the specific output to spend from the transaction. |
 
 ---
+
 ## 👉 Block Headers by Height
+
 Retrieve the block headers by height.
 
 ### 🗂 Raw Data
 
-| Type     | `command` value                              |
-|----------|---------------------------------------------|
-| Request  | `tbcapi-block-headers-by-height-raw-request`|
-| Response | `tbcapi-block-headers-by-height-raw-response`|
+| Type     | `command` value                               |
+|----------|-----------------------------------------------|
+| Request  | `tbcapi-block-headers-by-height-raw-request`  |
+| Response | `tbcapi-block-headers-by-height-raw-response` |
 
 ### 📤 Request
 
@@ -268,13 +272,12 @@ Response for a request with **id** `68656d69` and **height** `43111`:
 }
 ```
 
-
 ### 🗂 Serialized Data
 
-| Type     | `command` value                              |
-|----------|---------------------------------------------|
-| Request  | `tbcapi-block-headers-by-height-request`    |
-| Response | `tbcapi-block-headers-by-height-response`   |
+| Type     | `command` value                           |
+|----------|-------------------------------------------|
+| Request  | `tbcapi-block-headers-by-height-request`  |
+| Response | `tbcapi-block-headers-by-height-response` |
 
 ### 📤 Request
 
@@ -337,10 +340,10 @@ Retrieve the best block headers.
 
 ### 🗂 Raw Data
 
-| Type     | `command` value                              |
-|----------|----------------------------------------------|
-| Request  | `tbcapi-block-headers-best-raw-request`      |
-| Response | `tbcapi-block-headers-best-raw-response`     |
+| Type     | `command` value                          |
+|----------|------------------------------------------|
+| Request  | `tbcapi-block-headers-best-raw-request`  |
+| Response | `tbcapi-block-headers-best-raw-response` |
 
 ### 📤 Request
 
@@ -385,10 +388,10 @@ Response for a request with **id** `68656d69` and **best height** `2182000`:
 
 ### 🗂 Serialized Data
 
-| Type     | `command` value                          |
-|----------|------------------------------------------|
-| Request  | `tbcapi-block-headers-best-request`      |
-| Response | `tbcapi-block-headers-best-response`     |
+| Type     | `command` value                      |
+|----------|--------------------------------------|
+| Request  | `tbcapi-block-headers-best-request`  |
+| Response | `tbcapi-block-headers-best-response` |
 
 ### 📤 Request
 
@@ -439,14 +442,15 @@ Response for a request with **id** `68656d69` and **height** `2587400`:
 ```
 
 ## 👉 Balance by Address
+
 Retrieve the balance for an address.
 
 ### 🗂 Raw Data
 
-| Type     | `command` value                               |
-|----------|-----------------------------------------------|
-| Request  | `tbcapi-balance-by-address-request`           |
-| Response | `tbcapi-balance-by-address-response`          |
+| Type     | `command` value                      |
+|----------|--------------------------------------|
+| Request  | `tbcapi-balance-by-address-request`  |
+| Response | `tbcapi-balance-by-address-response` |
 
 ### 📤 Request
 
@@ -485,7 +489,7 @@ Response for a request with **id** `68656d69`, if the address's **balance** is `
   "header": {
     "command": "tbcapi-balance-by-address-response",
     "id": "68656d69"
- },
+  },
   "payload": {
     "balance": 0
   }
@@ -500,17 +504,18 @@ Retrieve UTXOs by address.
 
 ### 🗂 Raw Data
 
-| Type     | `command` value                         |
-|----------|-----------------------------------------|
-| Request  | `tbcapi-utxos-by-address-raw-request`   |
-| Response | `tbcapi-utxos-by-address-raw-response`  |
+| Type     | `command` value                        |
+|----------|----------------------------------------|
+| Request  | `tbcapi-utxos-by-address-raw-request`  |
+| Response | `tbcapi-utxos-by-address-raw-response` |
 
 ### 📤 Request
 
 #### Payload:
 
 - **`address`**: The [address](#address) to retrieve the UTXOs for.
-- **`start`**: The start index for the UTXOs that should be included in the response (or the number of UTXOs that should be skipped).
+- **`start`**: The start index for the UTXOs that should be included in the response (or the number of UTXOs that should
+  be skipped).
 - **`count`**: The maximum number of UTXOs that should be included in the response.
 
 #### Example Request:
@@ -535,11 +540,13 @@ Retrieve five UTXOs for the address `mxVFsFW5N4mu1HPkxPttorvocvzeZ7KZyk`:
 
 #### Payload:
 
-- **`utxos`**: An array of **known UTXOs** for the address, encoded as hexadecimal strings, or **`null`** if there are **no UTXOs** for the address.
+- **`utxos`**: An array of **known UTXOs** for the address, encoded as hexadecimal strings, or **`null`** if there are *
+  *no UTXOs** for the address.
 
 #### Example Response:
 
-Response for a request with **id** `68656d69`, **requesting 5 UTXOs** for the address `mxVFsFW5N4mu1HPkxPttorvocvzeZ7KZyk`:
+Response for a request with **id** `68656d69`, **requesting 5 UTXOs** for the
+address `mxVFsFW5N4mu1HPkxPttorvocvzeZ7KZyk`:
 
 ```json
 {
@@ -561,17 +568,18 @@ Response for a request with **id** `68656d69`, **requesting 5 UTXOs** for the ad
 
 ### 🗂 Serialized Data
 
-| Type     | `command` value                   |
-|----------|-----------------------------------|
-| Request  | `tbcapi-utxos-by-address-request` |
-| Response | `tbcapi-utxos-by-address-response`|
+| Type     | `command` value                    |
+|----------|------------------------------------|
+| Request  | `tbcapi-utxos-by-address-request`  |
+| Response | `tbcapi-utxos-by-address-response` |
 
 ### 📤 Request
 
 #### Payload:
 
 - **`address`**: The [address](#address) to retrieve the UTXOs for.
-- **`start`**: The start index for the UTXOs that should be included in the response (or the number of UTXOs that should be skipped).
+- **`start`**: The start index for the UTXOs that should be included in the response (or the number of UTXOs that should
+  be skipped).
 - **`count`**: The maximum number of UTXOs that should be included in the response.
 
 #### Example Request:
@@ -596,7 +604,8 @@ Response for a request with **id** `68656d69`, **requesting 5 UTXOs** for the ad
 
 #### Payload:
 
-- **`utxos`**: An array of known [**UTXOs**](#utxo). The maximum number of items in this array can be changed with **`count`** in the request.
+- **`utxos`**: An array of known [**UTXOs**](#utxo). The maximum number of items in this array can be changed with *
+  *`count`** in the request.
 
 #### Example Response:
 
@@ -639,17 +648,17 @@ Response for a request with **id** `68656d69`, **showing 5 UTXOs** for the addre
   }
 }
 ```
----
 
+---
 
 ## 👉 Transaction by ID
 
 ### 🗂 Raw Data
 
-| Type     | `command` value                     |
-|----------|-------------------------------------|
-| Request  | `tbcapi-tx-by-id-raw-request`       |
-| Response | `ttbcapi-tx-by-id-raw-response`     |
+| Type     | `command` value                 |
+|----------|---------------------------------|
+| Request  | `tbcapi-tx-by-id-raw-request`   |
+| Response | `ttbcapi-tx-by-id-raw-response` |
 
 ### 📤 Request
 
@@ -696,10 +705,10 @@ transaction `0584ad53bf1938702b952026f7c986ab5d07ee7295c0ad3241c932a5483158ac`:
 
 ### 🗂 Serialized Data
 
-| Type     | `command` value                |
-|----------|--------------------------------|
-| Request  | `tbcapi-tx-by-id-request`      |
-| Response | `tbcapi-tx-by-id-response`     |
+| Type     | `command` value            |
+|----------|----------------------------|
+| Request  | `tbcapi-tx-by-id-request`  |
+| Response | `tbcapi-tx-by-id-response` |
 
 ### 📤 Request
 
@@ -765,8 +774,3 @@ transaction `0584ad53bf1938702b952026f7c986ab5d07ee7295c0ad3241c932a5483158ac`:
   }
 }
 ```
-
---
-## 📄 License
-
-This project is licensed under the [MIT License](../../LICENSE).

From bc6d0ef16bccda5190b2f9fb5a445f69c788d58b Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Wed, 15 May 2024 23:28:02 +1000
Subject: [PATCH 24/39] docs: fix inconsistencies in tbcapi readme

---
 api/tbcapi/README.md | 214 +++++++++++++++++++++----------------------
 1 file changed, 105 insertions(+), 109 deletions(-)

diff --git a/api/tbcapi/README.md b/api/tbcapi/README.md
index 1ccc69d5..24aa0851 100644
--- a/api/tbcapi/README.md
+++ b/api/tbcapi/README.md
@@ -24,69 +24,69 @@ This document provides details on the RPC setup and client implementation for th
       * [Outpoint](#outpoint)
   * [👉 Block Headers by Height](#-block-headers-by-height)
     * [🗂 Raw Data](#-raw-data)
-    * [📤 Request](#-request)
-      * [Payload:](#payload)
-      * [Example Request:](#example-request)
-    * [📥 Response](#-response)
-      * [Payload:](#payload-1)
-      * [Example Response:](#example-response)
+      * [📤 Request](#-request)
+        * [Payload](#payload)
+        * [Example Request](#example-request)
+      * [📥 Response](#-response)
+        * [Payload](#payload-1)
+        * [Example Response](#example-response)
     * [🗂 Serialized Data](#-serialized-data)
-    * [📤 Request](#-request-1)
-      * [Payload](#payload-2)
-      * [Example Request](#example-request-1)
-    * [📥 Response](#-response-1)
-      * [Payload](#payload-3)
-      * [Example Response](#example-response-1)
+      * [📤 Request](#-request-1)
+        * [Payload](#payload-2)
+        * [Example Request](#example-request-1)
+      * [📥 Response](#-response-1)
+        * [Payload](#payload-3)
+        * [Example Response](#example-response-1)
   * [👉 Best Block Headers](#-best-block-headers)
     * [🗂 Raw Data](#-raw-data-1)
-    * [📤 Request](#-request-2)
-      * [Example Request](#example-request-2)
-    * [📥 Response](#-response-2)
-      * [Payload](#payload-4)
-      * [Example Response](#example-response-2)
-    * [🗂 Serialized Data](#-serialized-data-1)
-    * [📤 Request](#-request-3)
-      * [Example Request](#example-request-3)
-    * [📥 Response](#-response-3)
-      * [Payload](#payload-5)
-      * [Example Response](#example-response-3)
+      * [📤 Request](#-request-2)
+        * [Example Request](#example-request-2)
+      * [📥 Response](#-response-2)
+        * [Payload](#payload-4)
+        * [Example Response](#example-response-2)
+      * [🗂 Serialized Data](#-serialized-data-1)
+      * [📤 Request](#-request-3)
+        * [Example Request](#example-request-3)
+      * [📥 Response](#-response-3)
+        * [Payload](#payload-5)
+        * [Example Response](#example-response-3)
   * [👉 Balance by Address](#-balance-by-address)
     * [🗂 Raw Data](#-raw-data-2)
-    * [📤 Request](#-request-4)
-      * [Payload](#payload-6)
-      * [Example Request](#example-request-4)
-    * [📥 Response](#-response-4)
-      * [Payload](#payload-7)
-      * [Example Response](#example-response-4)
+      * [📤 Request](#-request-4)
+        * [Payload](#payload-6)
+        * [Example Request](#example-request-4)
+      * [📥 Response](#-response-4)
+        * [Payload](#payload-7)
+        * [Example Response](#example-response-4)
   * [👉 UTXOs by Address](#-utxos-by-address)
     * [🗂 Raw Data](#-raw-data-3)
-    * [📤 Request](#-request-5)
-      * [Payload:](#payload-8)
-      * [Example Request:](#example-request-5)
-    * [📥 Response](#-response-5)
-      * [Payload:](#payload-9)
-      * [Example Response:](#example-response-5)
+      * [📤 Request](#-request-5)
+        * [Payload](#payload-8)
+        * [Example Request](#example-request-5)
+      * [📥 Response](#-response-5)
+        * [Payload](#payload-9)
+        * [Example Response](#example-response-5)
     * [🗂 Serialized Data](#-serialized-data-2)
-    * [📤 Request](#-request-6)
-      * [Payload:](#payload-10)
-      * [Example Request:](#example-request-6)
-    * [📥 Response](#-response-6)
-      * [Payload:](#payload-11)
-      * [Example Response:](#example-response-6)
+      * [📤 Request](#-request-6)
+        * [Payload](#payload-10)
+        * [Example Request](#example-request-6)
+      * [📥 Response](#-response-6)
+        * [Payload](#payload-11)
+        * [Example Response](#example-response-6)
   * [👉 Transaction by ID](#-transaction-by-id)
     * [🗂 Raw Data](#-raw-data-4)
-    * [📤 Request](#-request-7)
-      * [Payload](#payload-12)
-    * [📥 Response](#-response-7)
-      * [Payload](#payload-13)
-      * [Example Response](#example-response-7)
+      * [📤 Request](#-request-7)
+        * [Payload](#payload-12)
+      * [📥 Response](#-response-7)
+        * [Payload](#payload-13)
+        * [Example Response](#example-response-7)
     * [🗂 Serialized Data](#-serialized-data-3)
-    * [📤 Request](#-request-8)
-      * [Payload](#payload-14)
-      * [Example Request](#example-request-7)
-    * [📥 Response](#-response-8)
-      * [Payload](#payload-15)
-      * [Example Response](#example-response-8)
+      * [📤 Request](#-request-8)
+        * [Payload](#payload-14)
+        * [Example Request](#example-request-7)
+      * [📥 Response](#-response-8)
+        * [Payload](#payload-15)
+        * [Example Response](#example-response-8)
 <!-- TOC -->
 </details>
 
@@ -121,9 +121,7 @@ For developers looking to integrate or extend functionality, view the raw Go typ
 ## 📡 Protocol
 
 The **RPC protocol** is WebSocket-based and follows a standard request/response model. For more detailed information,
-refer to the [protocol documentation.](../protocol/README.md)
-
----
+refer to the [protocol documentation](../protocol/README.md).
 
 ### 🚫 Errors
 
@@ -136,8 +134,6 @@ details:
 | `trace`     | A unique string for tracing errors between server and client (internal errors only). |
 | `message`   | The error message. For internal server errors, this will read `internal error`.      |
 
----
-
 ### 🗄️ Serialized Types
 
 #### Block Header
@@ -226,13 +222,13 @@ Retrieve the block headers by height.
 | Request  | `tbcapi-block-headers-by-height-raw-request`  |
 | Response | `tbcapi-block-headers-by-height-raw-response` |
 
-### 📤 Request
+#### 📤 Request
 
-#### Payload:
+##### Payload
 
 - **`height`**: The height at which block headers should be retrieved.
 
-#### Example Request:
+##### Example Request
 
 Retrieve block headers at height `43111`:
 
@@ -248,13 +244,13 @@ Retrieve block headers at height `43111`:
 }
 ```
 
-### 📥 Response
+#### 📥 Response
 
-#### Payload:
+##### Payload
 
 - **`block_headers`**: An array of raw block headers encoded as hexadecimal strings.
 
-#### Example Response:
+##### Example Response
 
 Response for a request with **id** `68656d69` and **height** `43111`:
 
@@ -279,13 +275,13 @@ Response for a request with **id** `68656d69` and **height** `43111`:
 | Request  | `tbcapi-block-headers-by-height-request`  |
 | Response | `tbcapi-block-headers-by-height-response` |
 
-### 📤 Request
+#### 📤 Request
 
-#### Payload
+##### Payload
 
 - **`height`**: The height at which block headers should be retrieved.
 
-#### Example Request
+##### Example Request
 
 Retrieve block headers at height `43111`:
 
@@ -301,13 +297,13 @@ Retrieve block headers at height `43111`:
 }
 ```
 
-### 📥 Response
+#### 📥 Response
 
-#### Payload
+##### Payload
 
 - **`block_headers`**: An array of [block headers](#block-header).
 
-#### Example Response
+##### Example Response
 
 Response for a request with **id** `68656d69` and **height** `43111`:
 
@@ -345,9 +341,9 @@ Retrieve the best block headers.
 | Request  | `tbcapi-block-headers-best-raw-request`  |
 | Response | `tbcapi-block-headers-best-raw-response` |
 
-### 📤 Request
+#### 📤 Request
 
-#### Example Request
+##### Example Request
 
 Retrieve the best block headers:
 
@@ -360,14 +356,14 @@ Retrieve the best block headers:
 }
 ```
 
-### 📥 Response
+#### 📥 Response
 
-#### Payload
+##### Payload
 
 - **`height`**: The best-known height.
 - **`block_headers`**: An array of the best-known block headers encoded as hexadecimal strings.
 
-#### Example Response
+##### Example Response
 
 Response for a request with **id** `68656d69` and **best height** `2182000`:
 
@@ -386,16 +382,16 @@ Response for a request with **id** `68656d69` and **best height** `2182000`:
 }
 ```
 
-### 🗂 Serialized Data
+#### 🗂 Serialized Data
 
 | Type     | `command` value                      |
 |----------|--------------------------------------|
 | Request  | `tbcapi-block-headers-best-request`  |
 | Response | `tbcapi-block-headers-best-response` |
 
-### 📤 Request
+#### 📤 Request
 
-#### Example Request
+##### Example Request
 
 Retrieve the best block headers:
 
@@ -408,14 +404,14 @@ Retrieve the best block headers:
 }
 ```
 
-### 📥 Response
+#### 📥 Response
 
-#### Payload
+##### Payload
 
 - **`height`**: The best-known height.
 - **`block_headers`**: An array of best-known [block headers](#block-header).
 
-#### Example Response
+##### Example Response
 
 Response for a request with **id** `68656d69` and **height** `2587400`:
 
@@ -452,13 +448,13 @@ Retrieve the balance for an address.
 | Request  | `tbcapi-balance-by-address-request`  |
 | Response | `tbcapi-balance-by-address-response` |
 
-### 📤 Request
+#### 📤 Request
 
-#### Payload
+##### Payload
 
 - **`address`**: The [address](#address) for which the balance should be retrieved.
 
-#### Example Request
+##### Example Request
 
 Retrieve the balance for the address `myqzZmRvoXmrhsrM5STiMGtNRxCFArHWRd`:
 
@@ -474,13 +470,13 @@ Retrieve the balance for the address `myqzZmRvoXmrhsrM5STiMGtNRxCFArHWRd`:
 }
 ```
 
-### 📥 Response
+#### 📥 Response
 
-#### Payload
+##### Payload
 
 - **`balance`**: The known balance of the address, in satoshis.
 
-#### Example Response
+##### Example Response
 
 Response for a request with **id** `68656d69`, if the address's **balance** is `0`:
 
@@ -509,16 +505,16 @@ Retrieve UTXOs by address.
 | Request  | `tbcapi-utxos-by-address-raw-request`  |
 | Response | `tbcapi-utxos-by-address-raw-response` |
 
-### 📤 Request
+#### 📤 Request
 
-#### Payload:
+##### Payload
 
 - **`address`**: The [address](#address) to retrieve the UTXOs for.
 - **`start`**: The start index for the UTXOs that should be included in the response (or the number of UTXOs that should
   be skipped).
 - **`count`**: The maximum number of UTXOs that should be included in the response.
 
-#### Example Request:
+##### Example Request
 
 Retrieve five UTXOs for the address `mxVFsFW5N4mu1HPkxPttorvocvzeZ7KZyk`:
 
@@ -536,14 +532,14 @@ Retrieve five UTXOs for the address `mxVFsFW5N4mu1HPkxPttorvocvzeZ7KZyk`:
 }
 ```
 
-### 📥 Response
+#### 📥 Response
 
-#### Payload:
+##### Payload
 
 - **`utxos`**: An array of **known UTXOs** for the address, encoded as hexadecimal strings, or **`null`** if there are *
   *no UTXOs** for the address.
 
-#### Example Response:
+##### Example Response
 
 Response for a request with **id** `68656d69`, **requesting 5 UTXOs** for the
 address `mxVFsFW5N4mu1HPkxPttorvocvzeZ7KZyk`:
@@ -573,16 +569,16 @@ address `mxVFsFW5N4mu1HPkxPttorvocvzeZ7KZyk`:
 | Request  | `tbcapi-utxos-by-address-request`  |
 | Response | `tbcapi-utxos-by-address-response` |
 
-### 📤 Request
+#### 📤 Request
 
-#### Payload:
+##### Payload
 
 - **`address`**: The [address](#address) to retrieve the UTXOs for.
 - **`start`**: The start index for the UTXOs that should be included in the response (or the number of UTXOs that should
   be skipped).
 - **`count`**: The maximum number of UTXOs that should be included in the response.
 
-#### Example Request:
+##### Example Request
 
 **Retrieve 5 UTXOs** for the address `mxVFsFW5N4mu1HPkxPttorvocvzeZ7KZyk`:
 
@@ -600,14 +596,14 @@ address `mxVFsFW5N4mu1HPkxPttorvocvzeZ7KZyk`:
 }
 ```
 
-### 📥 Response
+#### 📥 Response
 
-#### Payload:
+##### Payload
 
 - **`utxos`**: An array of known [**UTXOs**](#utxo). The maximum number of items in this array can be changed with *
   *`count`** in the request.
 
-#### Example Response:
+##### Example Response
 
 Response for a request with **id** `68656d69`, **showing 5 UTXOs** for the address:
 
@@ -660,9 +656,9 @@ Response for a request with **id** `68656d69`, **showing 5 UTXOs** for the addre
 | Request  | `tbcapi-tx-by-id-raw-request`   |
 | Response | `ttbcapi-tx-by-id-raw-response` |
 
-### 📤 Request
+#### 📤 Request
 
-#### Payload
+##### Payload
 
 - **`tx_id`**: The ID of the transaction to retrieve, encoded as a hexadecimal string.
 
@@ -680,13 +676,13 @@ An example request to retrieve the transaction `0584ad53bf1938702b952026f7c986ab
 }
 ```
 
-### 📥 Response
+#### 📥 Response
 
-#### Payload
+##### Payload
 
 - **`tx`**: The transaction (encoded as a hexadecimal string).
 
-#### Example Response
+##### Example Response
 
 An example response for a request with id `68656d69`, requesting the
 transaction `0584ad53bf1938702b952026f7c986ab5d07ee7295c0ad3241c932a5483158ac`:
@@ -710,13 +706,13 @@ transaction `0584ad53bf1938702b952026f7c986ab5d07ee7295c0ad3241c932a5483158ac`:
 | Request  | `tbcapi-tx-by-id-request`  |
 | Response | `tbcapi-tx-by-id-response` |
 
-### 📤 Request
+#### 📤 Request
 
-#### Payload
+##### Payload
 
 - **`tx_id`**: The ID of the transaction to retrieve, encoded as a hexadecimal string.
 
-#### Example Request
+##### Example Request
 
 An example request to retrieve the transaction `0584ad53bf1938702b952026f7c986ab5d07ee7295c0ad3241c932a5483158ac`:
 
@@ -732,13 +728,13 @@ An example request to retrieve the transaction `0584ad53bf1938702b952026f7c986ab
 }
 ```
 
-### 📥 Response
+#### 📥 Response
 
-#### Payload
+##### Payload
 
 - **`tx`**: The requested [transaction](#transaction), if found, otherwise **`null`**.
 
-#### Example Response
+##### Example Response
 
 An example response for a request with id `68656d69`, requesting the
 transaction `0584ad53bf1938702b952026f7c986ab5d07ee7295c0ad3241c932a5483158ac`:

From ae854aed5f628ba00205d23aa4744e175cd0040f Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Thu, 16 May 2024 03:22:03 +1000
Subject: [PATCH 25/39] docs: update tbcapi docs and fix a few errors

---
 api/tbcapi/README.md | 66 ++++++++++++++++++++++----------------------
 1 file changed, 33 insertions(+), 33 deletions(-)

diff --git a/api/tbcapi/README.md b/api/tbcapi/README.md
index 24aa0851..ce0ee88e 100644
--- a/api/tbcapi/README.md
+++ b/api/tbcapi/README.md
@@ -1,16 +1,17 @@
 # 📡 Hemi Tiny Bitcoin Daemon RPC
 
-***Last updated:** April 25th, 2024*
+***Last updated:** May 16th, 2024*
 
-This document provides details on the RPC setup and client implementation for the Hemi Tiny Bitcoin Daemon **(`tbcd`).**
+This document provides details on the RPC protocol and commands for the Hemi Tiny Bitcoin Daemon (`tbcd`).
 
 <details>
   <summary>Table of Contents</summary>
 
 <!-- TOC -->
 * [📡 Hemi Tiny Bitcoin Daemon RPC](#-hemi-tiny-bitcoin-daemon-rpc)
-  * [⚙️ Configuration](#-configuration)
-  * [👉 RPC Client](#-rpc-client)
+  * [⚙️ Implementations](#-implementations)
+    * [⚙️ `tbcd` Daemon](#-tbcd-daemon)
+    * [👉 RPC Client](#-rpc-client)
   * [📚 Resources](#-resources)
   * [📡 Protocol](#-protocol)
     * [🚫 Errors](#-errors)
@@ -92,22 +93,21 @@ This document provides details on the RPC setup and client implementation for th
 
 ---
 
-## ⚙️ Configuration
+## ⚙️ Implementations
 
-To configure the daemon, set the `TBC_ADDRESS` environment variable. For example:
+### ⚙️ `tbcd` Daemon
 
-```
-TBC_ADDRESS=localhost:8082
-```
-
-When set, `tbcd` listens on the provided address, allowing for RPC communications.
+The `tbcd` daemon runs an RPC server that listens on the address provided by the `TBC_ADDRESS` environment variable.
+You can run the `tbcd` daemon with the RPC server enabled with the following command:
 
----
+```shell
+TBC_ADDRESS=localhost:8082 /path/to/tbcd
+```
 
-## 👉 RPC Client
+### 👉 RPC Client
 
 [`hemictl`](../../cmd/hemictl) serves as a reference implementation of an RPC client tailored for interacting
-with `tbcd`.
+with the `tbcd` daemon.
 
 ---
 
@@ -138,16 +138,16 @@ details:
 
 #### Block Header
 
-A serialized block header includes:
+A serialized block header contains the following data:
 
-| Field         | Description                                                                               |
-|---------------|-------------------------------------------------------------------------------------------|
-| `version`     | The version of the block.                                                                 |
-| `prev_hash`   | The hash of the previous block header in the blockchain.                                  |
-| `merkle_root` | The hash derived from the hashes of all transactions in the block.                        |
-| `timestamp`   | The time the miner began hashing the header, represented in Unix seconds.                 |
-| `bits`        | The difficulty target for the block.                                                      |
-| `nonce`       | The nonce used to create the hash that is **less than or equal to** the target threshold. |
+| Field         | Description                                                                                                                   |
+|---------------|-------------------------------------------------------------------------------------------------------------------------------|
+| `version`     | The version of the block.                                                                                                     |
+| `prev_hash`   | The hash of the previous block header in the blockchain, in reverse byte order and encoded as a hexadecimal string.           |
+| `merkle_root` | The hash derived from the hashes of all transactions in the block, in reverse byte order and encoded as a hexadecimal string. |
+| `timestamp`   | The time the miner began hashing the header, represented in Unix seconds.                                                     |
+| `bits`        | The difficulty target for the block.                                                                                          |
+| `nonce`       | The nonce used to create the hash that is less than or equal to the target threshold.                                         |
 
 #### Address
 
@@ -161,13 +161,13 @@ Represents an encoded Bitcoin address, supporting these types:
 
 #### UTXO
 
-A serialized UTXO includes:
+A serialized UTXO contains the following data:
 
-| Field       | Description                                          |
-|-------------|------------------------------------------------------|
-| `tx_id`     | The transaction ID, encoded as a hexadecimal string. |
-| `value`     | The value of the UTXO.                               |
-| `out_index` | The output index of the UTXO.                        |
+| Field       | Description                                                                    |
+|-------------|--------------------------------------------------------------------------------|
+| `tx_id`     | The transaction ID, in reverse byte order and encoded as a hexadecimal string. |
+| `value`     | The value of the UTXO.                                                         |
+| `out_index` | The output index of the UTXO.                                                  |
 
 #### Transaction
 
@@ -204,10 +204,10 @@ A serialized transaction output contains the following data:
 
 A serialized outpoint contains the following data:
 
-| Field   | Description                                                     |
-|---------|-----------------------------------------------------------------|
-| `hash`  | The **ID** of the transaction holding the output to be spent.   |
-| `index` | The index of the specific output to spend from the transaction. |
+| Field   | Description                                                                                                          |
+|---------|----------------------------------------------------------------------------------------------------------------------|
+| `hash`  | The ID of the transaction holding the output to be spent, in reverse byte order and encoded as a hexadecimal string. |
+| `index` | The index of the specific output to spend from the transaction.                                                      |
 
 ---
 

From a42cc5ddd72a0e883abe2af991bdbc4d5a925683 Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Thu, 16 May 2024 03:24:46 +1000
Subject: [PATCH 26/39] docs: fix error in tbcapi docs

---
 api/tbcapi/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/api/tbcapi/README.md b/api/tbcapi/README.md
index ce0ee88e..738e79cc 100644
--- a/api/tbcapi/README.md
+++ b/api/tbcapi/README.md
@@ -710,7 +710,7 @@ transaction `0584ad53bf1938702b952026f7c986ab5d07ee7295c0ad3241c932a5483158ac`:
 
 ##### Payload
 
-- **`tx_id`**: The ID of the transaction to retrieve, encoded as a hexadecimal string.
+- **`tx_id`**: The ID of the transaction to retrieve, in reverse byte order and encoded as a hexadecimal string.
 
 ##### Example Request
 

From 3c358292c7bce8aea011fde6b104a2016e14c154 Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Thu, 16 May 2024 04:28:15 +1000
Subject: [PATCH 27/39] docs: tidy up protocol docs

---
 api/protocol/README.md | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/api/protocol/README.md b/api/protocol/README.md
index 86867715..47d500df 100644
--- a/api/protocol/README.md
+++ b/api/protocol/README.md
@@ -20,14 +20,16 @@ An RPC message has the following format:
 
 ### Header
 
-The message header includes metadata crucial for processing the message:
+The message header contains metadata required for processing the message:
 
 - **`command`**: The name of the command being executed.
-- **`id`**: A string used to uniquely identify each request. Responses will have the same `id` as the request, making it possible to match requests to responses.
+- **`id`**: A string used to uniquely identify each request. Responses will have the same `id` as the request, making it
+  possible to match requests to responses.
 
 > [!NOTE]
-> Request message IDs should be randomly generated.
+> Request message IDs should be randomly generated or sequential.
 
 ### Payload
 
-The payload type depends on the command being called. Please refer to the documentation for more details on the specific API you wish to use.
+The payload type depends on the command being called. Please refer to the documentation for more details on the specific
+API you wish to use.

From 40e0897d1ace1730d7ff730e38048ef2ac5ed894 Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Thu, 16 May 2024 04:37:36 +1000
Subject: [PATCH 28/39] Add .DS_Store to gitignore

---
 .gitignore         |   4 ++++
 database/.DS_Store | Bin 6148 -> 0 bytes
 2 files changed, 4 insertions(+)
 delete mode 100644 database/.DS_Store

diff --git a/.gitignore b/.gitignore
index ef04addd..7e864381 100644
--- a/.gitignore
+++ b/.gitignore
@@ -71,3 +71,7 @@ flycheck_*.el
 ## Visual Studio Code
 .vscode/
 .history/
+
+### Other files
+## macOS
+.DS_Store
diff --git a/database/.DS_Store b/database/.DS_Store
deleted file mode 100644
index 81ecdcd31e10caa3ca75a20ee4936bf72b6184d2..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 6148
zcmeH~F$w}f3`G;&La^D=avBfd4F=H@>;*)`ZA3xPdXDZ-CJ2t!BJu;tpJXO1`-+{7
zi0JxuSc&u^GJ~7S(n4d3ypz2gWt78xxSmg!^N5<&Cvn!+@Lrnz*rt#G36KB@kN^q%
z5COZlVY7KvMiL+a5_l4@??Zx{=Fn2rKOG1@0zf;I-LUpq0-CG<&7q|#Dlm=dL8DcD
z46(YmLsOi~p`~hV7meXV<H>4M3`}dgXhH(h?7~0-B+w9;*1Wg-e+&OK|2Hj6Nq_|Y
zjDU8VVY9|d#ohY$dRE^>)z$?L_2URHKLJSWDqg_du%B!J&7q|#Dlq;CI0gn1_$q-1
D;=2;2


From b2a0e569eabaeb603877674bda6fbc2f13511b49 Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Thu, 16 May 2024 22:00:40 +1000
Subject: [PATCH 29/39] docs: tidy up tbcd readme

---
 api/tbcapi/README.md |  2 +-
 cmd/tbcd/README.md   | 61 +++++++++++++++++++++++++++-----------------
 2 files changed, 39 insertions(+), 24 deletions(-)

diff --git a/api/tbcapi/README.md b/api/tbcapi/README.md
index 738e79cc..b5b4bd36 100644
--- a/api/tbcapi/README.md
+++ b/api/tbcapi/README.md
@@ -2,7 +2,7 @@
 
 ***Last updated:** May 16th, 2024*
 
-This document provides details on the RPC protocol and commands for the Hemi Tiny Bitcoin Daemon (`tbcd`).
+This document provides details on the RPC protocol and available commands for the Hemi Tiny Bitcoin Daemon (`tbcd`).
 
 <details>
   <summary>Table of Contents</summary>
diff --git a/cmd/tbcd/README.md b/cmd/tbcd/README.md
index 61038186..b8fb6105 100644
--- a/cmd/tbcd/README.md
+++ b/cmd/tbcd/README.md
@@ -1,24 +1,27 @@
 # 🌐 Hemi Tiny Bitcoin Daemon (`tbcd`)
 
-`tbcd` is a **minimal Bitcoin block downloader** and **indexer daemon**. It is designed to wrap the `tbc` service, which provides Bitcoin data **(blocks and transactions)** for other applications. Primarily, **it functions as a network RPC endpoint.**
-
-
+`tbcd` is a **minimal Bitcoin block downloader** and **indexer daemon**. It is designed to wrap the `tbc` service, which
+provides Bitcoin data **(blocks and transactions)** for other applications. Primarily, **it functions as a network RPC
+endpoint.**
 
 ## 🖥️ System Requirements
+
 `tbcd` requires significant system resources due to its functionality:
 
-| Requirement     | Specification    |
-|-----------------|------------------|
-| **CPU Cores**   | 4                |
-| **RAM**         | 8 GiB            |
-| **Disk**        | NVMe recommended |
+| Requirement   | Specification    |
+|---------------|------------------|
+| **CPU Cores** | 4                |
+| **RAM**       | 8 GiB            |
+| **Disk**      | NVMe recommended |
 
 **As of April 18, 2024:**
+
 - **`testnet3`** requires approximately 40 GiB of disk space.
 - **`mainnet`** requires over 300 GiB of disk space. <!-- XXX: add exact number here -->
 
 ---
-## 🛠️ Building `tbcd`
+
+## 🛠️ Building `tbcd` from source
 
 ### 🏁 Prerequisites:
 
@@ -28,30 +31,44 @@ Ensure Go v1.22 or newer is installed on your system.
 
 To build `tbcd` using the provided Makefile
 
-  > [!NOTE]
-  > 🏁 Prerequisites: Install **`make`**
+#### 🏁 Prerequisites
+
+Ensure `make` is installed on your system.
+
+#### Build `tbcd` binary
 
 ```shell
 cd heminetwork
-make tbcd  # Output binary will be written to bin/tbcd or bin/tbcd.exe
+
+# Output binary will be written to bin/tbcd or bin/tbcd.exe
+make tbcd
 ```
 
-### Standalone Build
+### Standalone build
 
 If you prefer not to use the Makefile:
 
 ```shell
 cd heminetwork
-go build ./cmd/tbcd/      # Build the binary (output will be tbcd or tbcd.exe)
-go install ./cmd/tbcd/    # Install the binary (output will be in your GOBIN directory)
+
+# Build the binary (output will be tbcd or tbcd.exe)
+go build ./cmd/tbcd/
+
+# Install the binary (output will be in your GOBIN directory)
+go install ./cmd/tbcd/
 ```
+
 ---
+
 ## 🌐 Environment Settings
 
-`tbcd` **checks system limits at startup on supported platforms** to ensure that they are set to values that will allow TBC to run without failing.
+`tbcd` **checks system limits at startup on supported platforms** to ensure that they are set to values that will allow
+TBC to run without failing.
+
+> [!WARNING]
+> If you see an error similar to the following, you will need to adjust the limits for the number of open files, memory
+> and the maximum stack size on your system to run TBC.
 
-  > [!WARNING]
-  > If you see an error similar to the following, you will need to adjust the limits for the number of open files, memory and the maximum stack size on your system to run TBC.
 ```
 ulimit: memory: limit too low got X, want X
 ```
@@ -60,10 +77,7 @@ Changing limits is OS-specific, but can usually be done using the `ulimit` comma
 
 ## ⚙️ Runtime Settings
 
-
-`tbcd` is **designed to be run in cloud environments**, as such it only uses environment variables for runtime settings.
-
-They can either be exported or included in the evocation of the binary.
+`tbcd` is **designed to be run in cloud environments**, as such it uses environment variables for runtime settings.
 
 To see a full list of runtime settings, execute `tbcd` with the **`--help`** flag:
 
@@ -84,13 +98,14 @@ To see a full list of runtime settings, execute `tbcd` with the **`--help`** fla
 ```
 
 Start the server by running:
+
 ```shell
 /path/to/tbcd
 ```
 
 ## 👉 RPC Commands
 
-When the `TBC_ADDRESS` is set to an address (e.g., `localhost:8082`), the `tbcd` daemon listens on the provided address.
+The `tbcd` daemon runs an RPC server that listens on the address provided by the `TBC_ADDRESS` environment variable.
 
 The RPC protocol is **WebSocket-based** and **uses a standard request/response model.**
 

From 0d587e2331dcfcf0b0fce115d6b69eac68bf4774 Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Thu, 16 May 2024 22:01:25 +1000
Subject: [PATCH 30/39] docs: clarify minimums for tbcd

---
 cmd/tbcd/README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/cmd/tbcd/README.md b/cmd/tbcd/README.md
index b8fb6105..85bf45b6 100644
--- a/cmd/tbcd/README.md
+++ b/cmd/tbcd/README.md
@@ -10,8 +10,8 @@ endpoint.**
 
 | Requirement   | Specification    |
 |---------------|------------------|
-| **CPU Cores** | 4                |
-| **RAM**       | 8 GiB            |
+| **CPU Cores** | 4 minimum        |
+| **RAM**       | 8 GiB minimum    |
 | **Disk**      | NVMe recommended |
 
 **As of April 18, 2024:**

From 9c26db076dd60f5b6815060f37fca4615fe1f839 Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Thu, 16 May 2024 23:15:23 +1000
Subject: [PATCH 31/39] docs: tidy up readme, update parts and fix a few errors

---
 README.md | 190 ++++++++++++++++++++++++++----------------------------
 1 file changed, 90 insertions(+), 100 deletions(-)

diff --git a/README.md b/README.md
index cdf8d75f..6e399038 100644
--- a/README.md
+++ b/README.md
@@ -5,58 +5,65 @@ Hemi is an EVM-compatible L2 blockchain that combines the security of Bitcoin wi
 <details>
   <summary>Table of Contents</summary>
 
-- [⚡️ The Hemi Network](#️-the-hemi-network)
-  - [🔧 Services](#-services)
-  - [🌐 Overview:](#-overview)
-- [⚡️ Getting Started](#️-getting-started)
-  - [🏗 Building from Source](#-building-from-source)
-    - [🏁 Prerequisites](#-prerequisites)
-    - [📚 Tutorial](#-tutorial)
-  - [📦 Downloading Release Binaries](#-downloading-release-binaries)
-- [🛠 Running the Services](#-running-the-services)
-  - [▶️ Running popmd](#️-running-popmd)
-    - [🏁 Prerequisites](#-prerequisites-1)
-    - [CLI:](#cli)
-    - [Web:](#web)
-  - [▶️ Running bfgd](#️-running-bfgd)
-    - [🏁 Prerequisites:](#-prerequisites-2)
-  - [▶️ Running bssd](#️-running-bssd)
-    - [🏁 Prerequisites:](#-prerequisites-3)
-  - [▶️ Running Network](#️-running-network)
-    - [🏁 Prerequisites:](#-prerequisites-4)
-    - [📚 Tutorial](#-tutorial-1)
-  - [🧪 Running Full Network Tests](#-running-full-network-tests)
-    - [🏁 Prerequisites:](#-prerequisites-5)
-    - [📚 Tutorial](#-tutorial-2)
-  - [📄 License](#-license)
+<!-- TOC -->
+* [⚡️ The Hemi Network](#-the-hemi-network)
+  * [🔧 Services](#-services)
+  * [🌐 Binaries](#-binaries)
+* [⚡️ Getting Started](#-getting-started)
+  * [📦 Downloading Release Binaries](#-downloading-release-binaries)
+  * [🏗 Building from Source](#-building-from-source)
+    * [🏁 Prerequisites](#-prerequisites)
+    * [Building with Makefile](#building-with-makefile)
+* [🛠 Running the Services](#-running-the-services)
+  * [▶️ Running popmd](#-running-popmd)
+    * [🏁 Prerequisites](#-prerequisites-1)
+    * [CLI](#cli)
+    * [Web](#web)
+  * [▶️ Running bfgd](#-running-bfgd)
+    * [🏁 Prerequisites](#-prerequisites-2)
+  * [▶️ Running bssd](#-running-bssd)
+    * [🏁 Prerequisites](#-prerequisites-3)
+  * [▶️ Running the localnet network](#-running-the-localnet-network)
+    * [🏁 Prerequisites](#-prerequisites-4)
+    * [📚 Tutorial](#-tutorial)
+  * [📄 License](#-license)
+<!-- TOC -->
 </details>
 
 ---
+
 ## 🔧 Services
 
 The Hemi Network comprises three key services, each serving a unique function within the network:
 
-| Service | Description |
-|---------|-------------|
-| [**PoP Miner (popmd)**](https://github.com/hemilabs/heminetwork/blob/main/service/popm) | **Mines** L2 Keystones into Bitcoin blocks for Proof-of-Proof. |
-| [**Bitcoin Finality Governor (bfgd)**](https://github.com/hemilabs/heminetwork/blob/main/service/bfg) | Acts as the gateway to the Bitcoin network. |
-| [**Bitcoin Secure Sequencer (bssd)**](https://github.com/hemilabs/heminetwork/blob/main/service/bss) | Acts as a gateway to the Bitcoin Finality Governor (BFG) forked from Optimism, managing the consensus mechanisms of the Hemi Network.
-
+| Service                                                                                               | Description                                                                                                      |
+|-------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
+| [**PoP Miner (popmd)**](https://github.com/hemilabs/heminetwork/blob/main/service/popm)               | **Mines** L2 Keystones into Bitcoin blocks for Proof-of-Proof.                                                   |
+| [**Bitcoin Finality Governor (bfgd)**](https://github.com/hemilabs/heminetwork/blob/main/service/bfg) | Acts as the gateway to the Bitcoin network.                                                                      |
+| [**Bitcoin Secure Sequencer (bssd)**](https://github.com/hemilabs/heminetwork/blob/main/service/bss)  | Acts as a gateway to the Bitcoin Finality Governor (BFG), managing the consensus mechanisms of the Hemi Network. |
+
+## 🌐 Binaries
+
+- [**bfgd (Bitcoin Finality Governor Daemon)**](cmd/bfgd): Manages connections and data transfers between the Hemi
+  Network and the Bitcoin blockchain, ensuring finality.
+- [**bssd (Bitcoin Secure Sequencer Daemon)**](cmd/bssd): Coordinates and sequences blockchain operations, serving as a
+  bridge to the Bitcoin Finality Governor.
+- [**extool**](cmd/extool): A utility tool for extracting and processing data from various file formats, tailored for
+  blockchain data analysis.
+- [**hemictl**](cmd/hemictl): The command-line interface for controlling and managing all Hemi Network services.
+- [**keygen**](cmd/keygen): Generates and manages cryptographic keys used within the Hemi network, ensuring secure
+  operations.
+- [**popmd (Proof-of-Proof Miner Daemon)**](cmd/popmd): Embeds L2 Keystones into Bitcoin blocks for proof-of-proof,
+  integral to the network's security.
+- [**tbcd (Tiny Bitcoin Daemon)**](cmd/tbcd): A minimal Bitcoin block downloader and indexer daemon.
 
 ---
-## 🌐 Overview:
-
-- **extool**: A utility tool for extracting and processing data from various file formats, tailored for blockchain data analysis.
-- **hemictl**: The command-line interface for controlling and managing all Hemi Network services.
-- **keygen**: Generates and manages cryptographic keys used within the Hemi network, ensuring secure operations.
-- **popmd (Proof of Proof Miner Daemon)**: Embeds L2 Keystones into Bitcoin blocks for proof-of-proof, integral to the network's security.
-- **bfgd (Bitcoin Finality Governor Daemon)**: Manages connections and data transfers between the Hemi Network and the Bitcoin blockchain, ensuring finality.
-- **bssd (Bitcoin Secure Sequencer Daemon)**: Coordinates and sequences blockchain operations, serving as a bridge to the Bitcoin Finality Governor.
 
+# ⚡️ Getting Started
 
----
+## 📦 Downloading Release Binaries
 
-# ⚡️ Getting Started
+Pre-built binaries are available on the [Releases Page](https://github.com/hemilabs/heminetwork/releases).
 
 ## 🏗 Building from Source
 
@@ -66,29 +73,21 @@ The Hemi Network comprises three key services, each serving a unique function wi
 - `make`
 - [Go v1.22+](https://go.dev/dl/)
 
----
-
-### 📚 Tutorial
+### Building with Makefile
 
-
-1. Clone the Repository:
+1. Clone the `heminetwork` repository:
    ```shell
    git clone https://github.com/hemilabs/heminetwork.git
-   ```
-2. Build:
-   ```shell
    cd heminetwork
-   make deps
-   make
    ```
 
-Binaries will be located in `<path-to-repo>/bin/`.
-
----
-
-## 📦 Downloading Release Binaries
+2. Setup and build binaries:
+   ```shell
+   make deps    # Download and install dependencies
+   make install # Build binaries
+   ```
 
-Pre-built binaries are available on the [Releases Page](https://github.com/hemilabs/heminetwork/releases).
+Output binaries will be written to the `bin/` directory.
 
 ---
 
@@ -109,9 +108,10 @@ For any service, you can view configuration options by running:
 - A funded BTC private key. This can be a testnet address if configured for test environments.
 - A BFG URL to establish a connection.
 
-Once properly configured and running, `popmd` will start mining L2 Keystones by adding them to Bitcoin blocks that make it into the chain.
+Once properly configured and running, `popmd` will start mining L2 Keystones by adding them to Bitcoin blocks that make
+it into the chain.
 
-### CLI:
+### CLI
 
 Set up and start popmd using:
 
@@ -119,9 +119,13 @@ Set up and start popmd using:
 ./bin/popmd
 ```
 
-### Web:
+### Web
 
-Or initialize the web interface:
+There is also a web interface that can be used to run a PoP miner.
+Build and run the web interface with:
+
+> [!NOTE]
+> The web PoP Miner is currently a proof-of-concept.
 
 ```bash
 cd ./web
@@ -129,81 +133,67 @@ make
 go run ./integrationtest
 ```
 
-
 ## ▶️ Running bfgd
 
-### 🏁 Prerequisites:
+### 🏁 Prerequisites
 
 - A **PostgreSQL database**, bfgd expects the sql scripts in `./database/bfgd/scripts/` to be run to set up your schema.
 - A **connection to an ElectrumX node** on the proper Bitcoin network (testnet or mainnet).
 
-
-
 ## ▶️ Running bssd
 
-### 🏁 Prerequisites:
--  Connect to a live [bfgd](#running-bfgd) instance.
+### 🏁 Prerequisites
 
+- Connect to a live [bfgd](#-running-bfgd) instance.
 
+## ▶️ Running the localnet network
 
-## ▶️ Running Network
+> [!WARNING]
+> This is designed for use in testing and development environments only.
 
-### 🏁 Prerequisites:
+### 🏁 Prerequisites
 
 - `docker`
+
 ### 📚 Tutorial
 
-1. **Start the Network:** Launch the entire Hemi network locally using Docker, which will generate L2 Keystones and BTC Blocks at a **high rate**:
+1. **Start the Network:** Launch the entire Hemi network locally using Docker, which will generate L2 Keystones and BTC
+   Blocks at a **high rate**:
 
    ```bash
    docker compose -f ./e2e/docker-compose.yml up --build
    ```
 
-    > [!NOTE]
-    > The `--build` flag is optional if you wish to rebuild your code.
+   > [!NOTE]
+   > The `--build` flag is optional if you wish to rebuild your code.
 
-1. **Manage Caching:**
+2. **Manage Caching:**
    This initial build may take some time, but subsequent builds should benefit from caching.
 
-     > [!NOTE]
-    > During rebuilding, `popmd`, `bssd`, and `bfgd` may force a rebuild due to the `COPY` command, which can break the cache. If you need to deliberately break the cache for the op-stack, use the following arguments:
+   > [!NOTE]
+   > During rebuilding, `popmd`, `bssd`, and `bfgd` may force a rebuild due to the `COPY` command, which can break the
+   cache. If you need to deliberately break the cache for the op-stack, use the following arguments:
 
-- For op-geth + optimism (op-node):
-  ```bash
-  docker compose -f ./e2e/docker-compose.yml build --build-arg OP_GETH_CACHE_BREAK="$(date)"
-  ```
+   - For op-geth + optimism (op-node):
+     ```bash
+     docker compose -f ./e2e/docker-compose.yml build --build-arg OP_GETH_CACHE_BREAK="$(date)"
+     ```
 
-- For optimism cache break only:
-  ```bash
-  docker compose -f ./e2e/docker-compose.yml build --build-arg OPTIMISM_CACHE_BREAK="$(date)"
-  ```
+   - For optimism cache break only:
+     ```bash
+     docker compose -f ./e2e/docker-compose.yml build --build-arg OPTIMISM_CACHE_BREAK="$(date)"
+     ```
 
 > [!IMPORTANT]
 > Make sure you run the cleanup command to remove data and ensure a fresh start.
+
 ```bash
 docker compose -f ./e2e/docker-compose.yml down -v --remove-orphans
 ```
 
 **NOTE:** The `--remove-orphans` flag should remove other containers not defined
 in the docker compose file. This is mainly here to help ensure you start with a
-clean environment.  It can be omitted.
-
----
-
-## 🧪 Running Full Network Tests
-
-For a comprehensive local test of the Hemi network, this setup uses `bitcoind` in **regtest mode**:
-
-### 🏁 Prerequisites:
-
-- `docker`
-
-### 📚 Tutorial
-
-1. Run the Test Command:
-   ```make
-   networktest
-   ```
+clean environment. It can be omitted.
 
 ---
 

From 17d53464345dabaefcf1be7f248c3ab01b7668f5 Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Thu, 16 May 2024 23:20:38 +1000
Subject: [PATCH 32/39] docs: fix formatting for notes in readme

---
 README.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 6e399038..6e3e25ad 100644
--- a/README.md
+++ b/README.md
@@ -164,15 +164,15 @@ go run ./integrationtest
    docker compose -f ./e2e/docker-compose.yml up --build
    ```
 
-   > [!NOTE]
-   > The `--build` flag is optional if you wish to rebuild your code.
+> [!NOTE]
+> The `--build` flag is optional and should only be used if you want to rebuild the binaries.
 
 2. **Manage Caching:**
    This initial build may take some time, but subsequent builds should benefit from caching.
 
-   > [!NOTE]
-   > During rebuilding, `popmd`, `bssd`, and `bfgd` may force a rebuild due to the `COPY` command, which can break the
-   cache. If you need to deliberately break the cache for the op-stack, use the following arguments:
+> [!NOTE]
+> During rebuilding, `popmd`, `bssd`, and `bfgd` may force a rebuild due to the `COPY` command, which can break the 
+> cache. If you need to deliberately break the cache for the op-stack, use the following arguments:
 
    - For op-geth + optimism (op-node):
      ```bash

From 03c0fcbe239720b5b13089693e492e882f25d283 Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Tue, 21 May 2024 02:15:58 +1000
Subject: [PATCH 33/39] docs: feedback from Jane

---
 cmd/tbcd/README.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/cmd/tbcd/README.md b/cmd/tbcd/README.md
index 85bf45b6..26098be9 100644
--- a/cmd/tbcd/README.md
+++ b/cmd/tbcd/README.md
@@ -21,9 +21,9 @@ endpoint.**
 
 ---
 
-## 🛠️ Building `tbcd` from source
+## 🛠️ Building `tbcd` From Source
 
-### 🏁 Prerequisites:
+### 🏁 Prerequisites
 
 Ensure Go v1.22 or newer is installed on your system.
 
@@ -44,7 +44,7 @@ cd heminetwork
 make tbcd
 ```
 
-### Standalone build
+### Standalone Build
 
 If you prefer not to use the Makefile:
 

From 10aef518bde34ab5d362f545be978911c16264e0 Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Thu, 30 May 2024 03:15:50 +1000
Subject: [PATCH 34/39] readme: specify Go v1.22.2 for building from source

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 6e3e25ad..9475936c 100644
--- a/README.md
+++ b/README.md
@@ -71,7 +71,7 @@ Pre-built binaries are available on the [Releases Page](https://github.com/hemil
 
 - `git`
 - `make`
-- [Go v1.22+](https://go.dev/dl/)
+- [Go v1.22.2+](https://go.dev/dl/)
 
 ### Building with Makefile
 

From ba4fd887decf2f429c4ebd6e2e94f26057b9eb2d Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Thu, 30 May 2024 03:16:46 +1000
Subject: [PATCH 35/39] readme: use `shell` syntax instead of `bash`

---
 README.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 9475936c..55160d34 100644
--- a/README.md
+++ b/README.md
@@ -95,7 +95,7 @@ Output binaries will be written to the `bin/` directory.
 
 For any service, you can view configuration options by running:
 
-```bash
+```shell
 ./bin/popmd --help
 ./bin/bfgd --help
 ./bin/bssd --help
@@ -115,7 +115,7 @@ it into the chain.
 
 Set up and start popmd using:
 
-```bash
+```shell
 ./bin/popmd
 ```
 
@@ -127,7 +127,7 @@ Build and run the web interface with:
 > [!NOTE]
 > The web PoP Miner is currently a proof-of-concept.
 
-```bash
+```shell
 cd ./web
 make
 go run ./integrationtest
@@ -160,7 +160,7 @@ go run ./integrationtest
 1. **Start the Network:** Launch the entire Hemi network locally using Docker, which will generate L2 Keystones and BTC
    Blocks at a **high rate**:
 
-   ```bash
+   ```shell
    docker compose -f ./e2e/docker-compose.yml up --build
    ```
 
@@ -175,19 +175,19 @@ go run ./integrationtest
 > cache. If you need to deliberately break the cache for the op-stack, use the following arguments:
 
    - For op-geth + optimism (op-node):
-     ```bash
+     ```shell
      docker compose -f ./e2e/docker-compose.yml build --build-arg OP_GETH_CACHE_BREAK="$(date)"
      ```
 
    - For optimism cache break only:
-     ```bash
+     ```shell
      docker compose -f ./e2e/docker-compose.yml build --build-arg OPTIMISM_CACHE_BREAK="$(date)"
      ```
 
 > [!IMPORTANT]
 > Make sure you run the cleanup command to remove data and ensure a fresh start.
 
-```bash
+```shell
 docker compose -f ./e2e/docker-compose.yml down -v --remove-orphans
 ```
 

From 814efb65976d76920234efa0044b8ca58d02ff43 Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Thu, 30 May 2024 03:18:15 +1000
Subject: [PATCH 36/39] tbcd/readme: specify Go v1.22.2 for building from
 source

---
 cmd/tbcd/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/cmd/tbcd/README.md b/cmd/tbcd/README.md
index 26098be9..6e93d227 100644
--- a/cmd/tbcd/README.md
+++ b/cmd/tbcd/README.md
@@ -25,7 +25,7 @@ endpoint.**
 
 ### 🏁 Prerequisites
 
-Ensure Go v1.22 or newer is installed on your system.
+Ensure Go v1.22.2 or newer is installed on your system.
 
 ### Using Makefile
 

From d8caaf1c905492210e807b203dae70c1672d1c9c Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Thu, 30 May 2024 03:19:11 +1000
Subject: [PATCH 37/39] tbcd/readme: use ./bin/tbcd for help example

---
 cmd/tbcd/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/cmd/tbcd/README.md b/cmd/tbcd/README.md
index 6e93d227..c199ca02 100644
--- a/cmd/tbcd/README.md
+++ b/cmd/tbcd/README.md
@@ -82,7 +82,7 @@ Changing limits is OS-specific, but can usually be done using the `ulimit` comma
 To see a full list of runtime settings, execute `tbcd` with the **`--help`** flag:
 
 ```shell
-/path/to/tbcd --help
+./bin/tbcd --help
 # Hemi Tiny Bitcoin Daemon: v0.1.0-pre+3eb1bab15
 # Usage:
 #         help (this help)

From 564dfef523ae98ba2d5c5b4ccb08606a56a5a287 Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Thu, 30 May 2024 03:33:50 +1000
Subject: [PATCH 38/39] readme: reword services paragraph

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 55160d34..f50e939b 100644
--- a/README.md
+++ b/README.md
@@ -34,7 +34,7 @@ Hemi is an EVM-compatible L2 blockchain that combines the security of Bitcoin wi
 
 ## 🔧 Services
 
-The Hemi Network comprises three key services, each serving a unique function within the network:
+The Hemi Network consists of three key services, each serving a unique and important function within the network:
 
 | Service                                                                                               | Description                                                                                                      |
 |-------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|

From caa82872848bf87f4e783bd7cb6b8345d32ec07f Mon Sep 17 00:00:00 2001
From: Joshua Sing <joshua@bloq.com>
Date: Thu, 30 May 2024 03:39:55 +1000
Subject: [PATCH 39/39] protocol: remove id note from readme

---
 api/protocol/README.md | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/api/protocol/README.md b/api/protocol/README.md
index 47d500df..0361a119 100644
--- a/api/protocol/README.md
+++ b/api/protocol/README.md
@@ -26,9 +26,6 @@ The message header contains metadata required for processing the message:
 - **`id`**: A string used to uniquely identify each request. Responses will have the same `id` as the request, making it
   possible to match requests to responses.
 
-> [!NOTE]
-> Request message IDs should be randomly generated or sequential.
-
 ### Payload
 
 The payload type depends on the command being called. Please refer to the documentation for more details on the specific