feat(bitcoin): Recommend Graviton4 (r8g) instance types

CHANGELOG.md

@@ -13,6 +13,24 @@
 
 ### Changed
 
+- **Bitcoin**: switched the recommended and sample instance types from x86 `r7i` to Graviton4.
+  - Mainnet single-node and HA samples now use `r8g.2xlarge`; testnet uses `r8g.xlarge`. All samples set `CPU_TYPE="ARM_64"`.
+  - In side-by-side mainnet tests (Bitcoin Core v31.1), `r8g.2xlarge` beat `r7i.2xlarge` on every measure while costing 11% less per hour:
+    - 4–14% faster sync from block 400k to tip (two syncs)
+    - 1.5–1.7× RPC throughput under concurrent load (full blocks, transaction lookups and a mixed workload)
+    - with a single client: 4% faster full-block `getblock` and 2.8× transaction-lookup throughput
+  - The README adds a "Choosing an instance type" guide: `r8g` primary; `r7g.2xlarge` secondary, for regions without r8g or the lowest hourly price, covering all tested workloads; `r7i` for hosts that need x86, including where it beats r7g.
+    - It explains that r7i's slower light-RPC results come from its default C6 idle state, with tuning guidance.
+    - It also updates the measured IBD time (about 8–10 h).
+  - No `node.sh` changes are needed: it already installs the aarch64 Bitcoin Core build when `CPU_TYPE="ARM_64"`.
+  - Existing `.env` files are unaffected. To move a deployed node to Graviton, deploy a new stack: redeploying an existing single-node stack with a new `CPU_TYPE` replaces the instance, and the stack rolls back because the data volume is still attached to the old instance.
+  - The README adds an "Under concurrent load" section: peak throughput and latency for 2xlarge and xlarge on both architectures, and the network-baseline limit on sustained full-block serving.
+  - The README adds post-sync right-sizing guidance: `r8g.xlarge` matched `r8g.2xlarge` on single-client RPC after sync, and reaches about half its throughput under load. It also explains how to resize in place by changing `INSTANCE_TYPE` and running `cdk deploy`, which stops and starts the same instance and keeps the chain data (verified on mainnet).
+  - It corrects the mainnet size and growth rate (~970 GB total; ~100 GB/year, measured from the last year of blocks).
+  - It corrects the HA `cdk destroy` stack name, warns that `cdk destroy` deletes the data volume, and documents deleting the RPC credentials secret, which `cdk destroy` leaves behind (both verified on teardown).
+  - It corrects the RPC credentials secret name in the RPC Authentication and Troubleshooting sections: `node.sh` stores it as `<stack-name>/bitcoin_rpc_credentials`, not `bitcoin_rpc_credentials`.
+  - It adds a troubleshooting entry for a node that crash-loops after an interrupted first boot (re-run `node.sh`).
+  - It corrects "Upgrading Client Versions". Redeploying a single-node stack with a new `CLIENT_CONFIG` stops and starts the same instance without re-running node setup, so the node stays on the previous version; the README previously said the instance is replaced and upgraded (tracked in #340).
 - **Ethereum**: upgraded Nethermind `1.39.3` → `2.0.0` in the Nethermind + Teku configuration (`nethermind-2.0.0-teku-26.8.0-full.yml`). New nodes sync into the flat state database, the 2.0 default. Upstream benchmarks show higher, more consistent block-processing throughput at chain tip and 15–27% faster `eth_call` than `1.39.3`, with the largest throughput gain (+36%) on arm64, the architecture of the blueprint's default Graviton instances. The configuration now also pins HTTP RPC to `8545` and WebSocket to `8546` (matching the blueprint's declared ports; Nethermind previously served WebSocket on `8545`), enables the `debug` and `admin` RPC modules to match the other execution clients, turns on the `/health` endpoint (usable as the HA ALB health-check path) and Prometheus metrics on the internal IP (`6060`), and binds the Engine API to `127.0.0.1` instead of `0.0.0.0`. Upstream 2.0 breaking changes that do not affect this blueprint's flags: `Db.FlushOnExit` became an enum and numeric config keys are now unsigned. Behaviour changes to note: `eth_getLogs` is limited to a 1,000-block range by default (`Receipt.MaxBlockDepth`), and fresh nodes serve snap data to peers (`Sync.SnapServingEnabled`). Added a `samples/.env-mainnet-nethermind-teku-full` sample and documented the configuration in the blueprint README. Smoke-tested on Sepolia with Teku `26.8.0`: Engine API handshake, RPC modules, WebSocket upgrade, `/health`, and metrics verified. Per the replace-the-instance upgrade model, upgrading means deploying a new node, which syncs from scratch.
 - **Ethereum**: bumped Reth `2.4.1` → `2.5.2` (Reth + Lighthouse archive), Besu `26.7.1` → `26.8.1`, and Teku `26.7.1` → `26.8.0` (Besu + Teku and Nethermind + Teku). Besu `26.8.1` carries breaking changes (a 1000-address cap on `eth_newFilter`/`eth_subscribe`, a 128 KiB tx-pool admission limit, removal of already-deprecated flags, and an `eth_estimateGas` result change) — none of the removed flags are used by the blueprint, and a mainnet smoke test confirmed it starts and syncs with the existing flag set. Teku `26.8.0` removes the long-deprecated `GetDepositSnapshot` Beacon API endpoint, which does not affect node operation. Configuration file names and matching `samples/` were updated accordingly.
 - **Solana**: bumped the default Agave configuration `4.2.1` → `4.2.2` (same stable `4.2.x` mainnet-beta line) and Frankendancer `0.1105.40200` → `0.1106.40201` (latest Frankendancer **Mainnet** release on the `0.x` line; bundled Agave submodule updated to `v4.2.1`, adds v1-transaction support). The `3.1.14`, `4.0.3`, and `4.1.2` Agave configurations remain available for pinning. Both clients build from source at the tag parsed from the configuration file name; both were smoke-tested on mainnet-beta.
@@ -32,6 +50,9 @@
 
 ### Fixed
 
+- **Bitcoin**: aligned the documented mainnet data volume with the shipped samples. The README (architecture diagram, instance and storage tables, cost notes) and the blueprint's `defaultDataVolumes` in `package.json` said 1 TB / 1000 GiB, while every mainnet `samples/` file provisions 1500 GiB; they now all say 1.5 TB / 1500 GiB.
+- **AI deploy workflow**: `docs/ageai-deploy-prompt.md` omitted `bitcoin` from the built-in blueprint list in Step 2.5, so an assistant following it would demand an external-blueprint security review for the built-in Bitcoin blueprint. Bitcoin is now listed, matching `docs/ageai-blueprint-security-review.md`.
+
 - **BNB Chain**: corrected the BSC Reth snapshot type. The `bsc-reth` sample (`.env-mainnet-bsc-reth-full`) set `BNB_SNAPSHOT_TYPE="local"` (a geth-only type) and the config script defaulted to `"full"`, but 48Club now publishes only `reth.fast` for the reth client — so a deploy silently fell back to a genesis sync. The sample now sets `BNB_SNAPSHOT_TYPE="fast"` and the script defaults to `"fast"`; the staging volume was right-sized `10000` → `600` GiB to match the ~458 GiB `reth.fast` archive. Verified on mainnet (snapshot downloads, extracts, and loads).
 - **Solana**: corrected the Frankendancer entry in the README "Client Release Channels" table. `releases/latest` for `firedancer-io/firedancer` resolves to the full **Firedancer** product (calendar `v26.x`), not Frankendancer; the table now instructs querying `/releases` for the highest non-prerelease named `Frankendancer Mainnet` on the `0.x` line, with a note explaining the two products share one release feed.
 - **BNB Chain**: the `bsc-reth` config script sourced the Rust environment via `"$HOME/.cargo/env"`, but cloud-init runs user-data as `root` with `HOME` unset, so it resolved to `/.cargo/env` and aborted the build (`No such file or directory`) before `reth-bsc` could compile. The script now pins `HOME` (`export HOME="${HOME:-/root}"`) before installing the Rust toolchain. Without this, the BSC Reth node never builds.