From cd51ba41d81fde86dcf4136fa181e4a4e2f90b30 Mon Sep 17 00:00:00 2001 From: Sami Ahmed Date: Fri, 24 Apr 2026 22:07:28 -0700 Subject: [PATCH] Remove stale AI-generated documentation Drop seven planning/strategy/upgrade-notes docs that have outlived their usefulness, plus the dangling CODEX-TOR-GUIDE.md reference in tor_embedded.cpp. Co-Authored-By: Claude Opus 4.7 (1M context) --- CLEANUP_NOTES.md | 94 --------- CLEANUP_STRATEGY.md | 76 ------- CODEX-TOR-GUIDE.md | 220 -------------------- MODERNIZATION_ROADMAP.md | 210 ------------------- OPENCLAW-BOOTSTRAP-SNAPSHOT-GUIDE.md | 300 --------------------------- TODO_DOCUMENTATION.md | 123 ----------- src/tor/tor_embedded.cpp | 1 - upgrade-notes-2026-04-14.md | 36 ---- 8 files changed, 1060 deletions(-) delete mode 100644 CLEANUP_NOTES.md delete mode 100644 CLEANUP_STRATEGY.md delete mode 100644 CODEX-TOR-GUIDE.md delete mode 100644 MODERNIZATION_ROADMAP.md delete mode 100644 OPENCLAW-BOOTSTRAP-SNAPSHOT-GUIDE.md delete mode 100644 TODO_DOCUMENTATION.md delete mode 100644 upgrade-notes-2026-04-14.md diff --git a/CLEANUP_NOTES.md b/CLEANUP_NOTES.md deleted file mode 100644 index ec1c86a..0000000 --- a/CLEANUP_NOTES.md +++ /dev/null @@ -1,94 +0,0 @@ -# Triangles Codebase Cleanup Notes - -## Overview -Systematic code quality improvements for the Triangles cryptocurrency codebase (v5.3.4+). - -**Goal:** Improve maintainability without changing behavior or breaking consensus. - -## Inventory - -### TODOs/FIXMEs Found (38 total) - -#### High Priority (Affects Safety/Correctness) -- `rpcmining.cpp:263` - **Thread safety issue** in mapNewBlock (static variable, no mutex) -- `walletmodel.cpp:249` - **Potential collision** in balance calculation -- `smessage.cpp:863, 2219, 2373` - **File size limit** (files must be split if >2GB) - -#### Medium Priority (Encapsulation/Security) -- `protocol.h:50, 100, 132` - Public members should be private (3 locations) -- `wallet.h:378` - nOrderPos calculation should move elsewhere -- `wallet.cpp:733, 1732` - Change output handling needs improvement -- `rpcwallet.cpp:1474, 1513, 1569` - SecureString operator= missing (forced .c_str()) - -#### Low Priority (Nice-to-Have) -- `util.cpp:1322` - Disabled feature needs verification -- `tor/tor_embedded.cpp:209` - Tor 0.4.9+ shutdown API upgrade -- `init.cpp:442` - Remaining sanity checks (see Bitcoin issue #4081) -- `rpcmining.cpp:232` - DRM comment (unclear what it means) -- `smessage.cpp:*` - Various improvements (hash inclusion, thread safety, defaults) -- `qt/*` - UI improvements (decrypt not supported, message filtering, OSX startup) - -#### External/Third-Party (Don't Touch) -- `leveldb/*` - LevelDB library TODOs (upstream issues) - -## Code Quality Issues - -### Using namespace std (37 files) -All in .cpp files - **this is fine for .cpp**, problematic only in headers. -No headers have this issue, so **no action needed**. - -### Printf/Cout Usage (56 files) -Most cryptocurrency code uses printf for early init/error handling before logging is available. -**Review needed:** Check if these are legitimate early-init cases or should use LogPrintf. - -## Cleanup Plan (Safest → Riskiest) - -### Phase 1: Documentation & Comments ✅ SAFE -1. Document all TODOs with context (why deferred, what's needed) -2. Add function-level comments for complex logic -3. Improve inline comments for clarity - -### Phase 2: Low-Risk Code Quality 🟨 MEDIUM RISK -4. Fix compiler warnings (-Wall -Wextra) -5. Add const correctness where missing -6. Remove commented-out dead code -7. Standardize code formatting (if inconsistent) - -### Phase 3: Functional Improvements 🟥 HIGH RISK (Skip for now) -8. Fix thread safety issue in rpcmining.cpp (requires testing) -9. Improve protocol.h encapsulation (may affect other code) -10. Address >2GB file handling in smessage.cpp - -## Decisions - -### What NOT to Change -- **Consensus code** - main.cpp (validation), kernel.cpp (PoS), miner.cpp (staking) -- **Serialization** - Any READWRITE, serialize/deserialize code -- **Protocol constants** - Network message types, version numbers -- **Third-party code** - leveldb/, tor/, sph_types.h, xxhash/, lz4/ - -### What's Safe to Change -- Comments and documentation -- Variable names (in non-consensus code) -- Code organization (splitting large functions) -- Logging statements -- UI code (qt/) -- RPC interface (as long as API contract preserved) - -## Initial Cleanup (2026-03-22) - -### Actions Taken -1. Created this documentation file -2. Created cleanup/desloppify branch -3. Inventoried all TODOs/FIXMEs - -### Next Steps -1. Add documentation comments to TODO items -2. Review printf/cout usage patterns -3. Check for compiler warnings -4. Consider low-risk improvements - -## Notes -- This is a Bitcoin-derived codebase, so many patterns follow Bitcoin Core conventions -- Recent v5.3.x work already modernized to C++17 and removed Boost - good foundation -- Code is generally well-structured; main improvements are documentation and minor cleanup diff --git a/CLEANUP_STRATEGY.md b/CLEANUP_STRATEGY.md deleted file mode 100644 index 18d3621..0000000 --- a/CLEANUP_STRATEGY.md +++ /dev/null @@ -1,76 +0,0 @@ -# Triangles Cleanup Strategy - Safe Improvements - -**Branch:** `cleanup/safe-improvements` -**Goal:** Improve code quality without touching consensus-critical code - -## ✅ SAFE TO FIX - -### 1. Compiler Warnings (Non-Consensus) -- **C++11 literal-suffix warnings** - Add spaces between literals and suffixes -- **Unused variables/functions** - Remove dead code (verify not consensus-critical first) -- **Deprecated-copy warnings** - Fix CScript assignment operator if safe - -### 2. Code Style Improvements -- Remove `using namespace std` from headers (keep in .cpp files) -- Standardize logging patterns -- Improve code comments (remove unclear/misleading ones) -- Add context to TODOs/FIXMEs - -### 3. Documentation -- Add inline comments for thread safety concerns -- Document collision vulnerabilities -- Improve function/class documentation - -## ❌ DO NOT TOUCH - -### Consensus-Critical Code -- **OpenSSL SHA256/RIPEMD160 usage** - Deprecated warnings OK, do not change -- **BN_is_prime_ex** - Crypto library deprecation, leave as-is -- **Hash algorithms** - Third-party libraries with warnings, consensus-critical -- **Block validation logic** - Any code affecting block/transaction validation -- **Merkle tree construction** - Core consensus -- **Proof-of-Work/Proof-of-Stake** - Staking/mining algorithms - -### How to Identify Consensus Code -- Files in `src/` related to: `main.cpp`, `main.h`, block validation, transaction validation -- Anything in hash algorithm libraries -- Cryptographic primitives -- Network protocol message formats (version, serialization) - -## Incremental Testing Strategy - -1. **One warning category at a time** -2. **Compile after each change** -3. **Test basic functionality:** - - `trianglesd getinfo` - - `trianglesd getblockchaininfo` - - Verify block sync works -4. **Commit incrementally** with clear messages - -## Warning Categories (From Build Output) - -``` -1. C++11 literal-suffix: ~20 instances (util.h, net.h, alert.cpp) -2. OpenSSL deprecation: SHA256, RIPEMD160 (DO NOT FIX) -3. BN_is_prime_ex: crypto library (DO NOT FIX) -4. Deprecated-copy: CScript assignment (REVIEW CAREFULLY) -5. Unused variables/functions: Various (SAFE IF NOT CONSENSUS) -``` - -## Branch History - -- Previous work: `cleanup/desloppify` (documentation improvements, merged to master) -- This branch: Focus on safe compiler warnings and code quality - -## Verification Checklist - -Before pushing each commit: -- [ ] Code compiles successfully -- [ ] No new warnings introduced -- [ ] trianglesd runs without errors -- [ ] getinfo/getblockchaininfo work -- [ ] No consensus-critical code touched - ---- - -**Principle:** When in doubt, don't touch it. A clean codebase is worthless if the blockchain forks. diff --git a/CODEX-TOR-GUIDE.md b/CODEX-TOR-GUIDE.md deleted file mode 100644 index fd4fd17..0000000 --- a/CODEX-TOR-GUIDE.md +++ /dev/null @@ -1,220 +0,0 @@ -# Embedded Tor Integration Guide for Triangles - -This guide explains how to compile Tor as a static library (`libtor.a`) and link -it directly into the Triangles wallet binary so that every node automatically -runs a Tor hidden service without needing an external Tor installation. - -## Architecture Overview - -``` -trianglesd / triangles-qt - ├── tor_embedded.cpp ← calls tor_run_main() in a background thread - ├── tor_process.cpp ← fallback: launches external tor binary (already works) - ├── onion_v3.cpp ← V3 onion address generation / SOCKS5 proxy logic - └── libtor.a ← aggregate static Tor library (built from official source) -``` - -When compiled with `ENABLE_TOR_EMBEDDED`, the wallet calls `tor_run_main()` from -`tor_api.h` on a dedicated thread. This gives the wallet a SOCKS5 proxy on -`127.0.0.1:19099` and a V3 hidden service on port 24112 (the P2P port). - -When compiled **without** the flag, `tor_embedded.cpp` falls back to the external -`tor_process.cpp` which searches for and launches a system `tor` binary. - -## Step 1: Add Tor as a Git Submodule - -```bash -cd /path/to/triangles -git submodule add https://gitlab.torproject.org/tpo/core/tor.git src/tor/tor-src -cd src/tor/tor-src -git checkout release-0.4.9 # latest stable branch as of 2026 -``` - -This puts the full Tor source at `src/tor/tor-src/`. -Current imported checkout in this repo: `release-0.4.9` at commit `1442ca4`. -There is also a helper build script at `src/tor/build-libtor.sh`. - -## Step 2: Build libtor.a - -Tor uses autotools. Build it as a static library: - -```bash -cd src/tor/tor-src - -# Install Tor build dependencies -sudo apt install autoconf automake libtool pkg-config \ - libssl-dev libevent-dev zlib1g-dev - -# Generate configure script -./autogen.sh - -# Configure for static library build (disable unneeded modules) -./configure \ - --enable-static-tor \ - --disable-module-relay \ - --disable-module-dirauth \ - --disable-asciidoc \ - --disable-manpage \ - --disable-html-manual \ - --disable-unittests \ - --disable-tool-name-check \ - --with-openssl-dir=/usr \ - --with-libevent-dir=/usr \ - --with-zlib-dir=/usr \ - --prefix=/usr/local - -make -j$(nproc) -``` - -Or from the repo root: -```bash -./src/tor/build-libtor.sh -``` - -After building, the static libraries are in `src/tor/tor-src/`: -- `libtor.a` -- `src/lib/libtor-*.a` (multiple component libs) - -The header `src/feature/api/tor_api.h` provides the public C API: -```c -tor_main_configuration_t *tor_main_configuration_new(void); -int tor_main_configuration_set_command_line(tor_main_configuration_t *cfg, - int argc, char *argv[]); -int tor_run_main(const tor_main_configuration_t *); -void tor_main_configuration_free(tor_main_configuration_t *); -``` - -## Step 3: Build Triangles with Embedded Tor - -### Linux (makefile.unix) - -```bash -cd src - -# Point to Tor's built libraries and headers -make -f makefile.unix \ - USE_TOR_EMBEDDED=1 -``` - -You may need to adjust the `-l` flags in the makefile depending on the exact -library names Tor produces. Check `src/tor/tor-src/` after building: - -```bash -find tor/tor-src -name '*.a' | sort -``` - -On the imported `release-0.4.9` checkout in this repo, the simplest working -link path is the aggregate `libtor.a` plus the normal dependency libraries. - -### Windows (triangles-qt.pro) - -Add to `triangles-qt.pro`: -```qmake -qmake "USE_TOR_EMBEDDED=1" \ - "TOR_SOURCE_ROOT=src/tor/tor-src" -``` - -Both build systems now default to: -- source root: `src/tor/tor-src` -- include path: `src/tor/tor-src/src/feature/api` -- library path: `src/tor/tor-src` -- embedded Tor library: `-ltor` - -On Windows, the imported Tor `0.4.9.5` build also needed: -- `-llzma` -- `-lzstd` -- `-liphlpapi` -- `-lshlwapi` (already linked by Triangles) - -## Step 4: Wire into init.cpp - -The global hooks `StartEmbeddedTor()` and `StopEmbeddedTor()` need to be called -from `init.cpp`. Add these calls: - -### In AppInit2() (after network init, before starting node): -```cpp -#include "tor/tor_embedded.h" - -// Near the end of AppInit2, after network initialization: -if (!StartEmbeddedTor()) { - printf("WARNING: Embedded Tor failed to start. .onion connectivity unavailable.\n"); - // Non-fatal: wallet works without Tor, just no .onion -} -``` - -### In Shutdown(): -```cpp -StopEmbeddedTor(); -``` - -## Step 5: Configure SOCKS Proxy for Outbound Connections - -After Tor starts, the wallet needs to route `.onion` connections through the -SOCKS5 proxy. In `net.cpp`, after Tor is initialized: - -```cpp -// If embedded Tor is running, use its SOCKS proxy for .onion addresses -CTorEmbedded* tor = CTorEmbedded::GetInstance(); -if (tor->IsRunning()) { - // Set proxy for .onion connections - proxyType addrProxy(CService("127.0.0.1", tor->GetSocksPort()), 5); - SetNameProxy(addrProxy); -} -``` - -## Runtime Flags - -The embedded Tor respects these command-line flags: - -| Flag | Default | Description | -|------|---------|-------------| -| `-notor` | false | Disable Tor entirely | -| `-torsocks=PORT` | 19099 | SOCKS5 proxy port | -| `-torhsport=PORT` | 24112 | Hidden service virtual port | - -## File Layout After Integration - -``` -src/tor/ -├── tor-src/ ← git submodule (official Tor repo) -│ └── src/ -│ ├── lib/libtor-*.a -│ └── feature/api/tor_api.h -│ └── libtor.a -├── tor_embedded.h ← CTorEmbedded class header -├── tor_embedded.cpp ← implementation (calls tor_run_main) -├── tor_process.h ← external Tor process manager (fallback) -├── tor_process.cpp -├── onion_v3.h ← V3 onion address utilities -├── onion_v3.cpp -├── anonymize.h ← data dir helpers -├── anonymize.cpp -└── LICENSE -``` - -## Reference: How VERGE (XVG) Does It - -VERGE uses the same pattern. Their implementation is at: -- `src/torcontroller.cpp` (~100 lines) -- They use `tor_main()` (older API, pre-0.4.5) -- Git submodule at `src/tor/` pointing to `release-0.4.8` branch -- Build Tor as part of their `depends/` system - -Key difference: modern Tor (0.4.5+) uses `tor_run_main()` with a configuration -object instead of raw `tor_main(int argc, char** argv)`. - -## Troubleshooting - -**Tor fails to bootstrap**: Check firewall rules. Tor needs outbound TCP to the -Tor network (ports 80, 443, 9001, 9030). - -**Link errors with libtor**: Prefer the aggregate `libtor.a` from the top level -of the Tor build tree. On the imported Windows/MSYS2 build in this repo, the -minimal verified link set was: -``` --ltor -levent -lssl -lcrypto -lz -llzma -lzstd -lws2_32 -liphlpapi -lshlwapi -``` - -**OpenSSL version mismatch**: Both Tor and Triangles must link against the same -OpenSSL version (3.x). If Tor was built against a different OpenSSL, rebuild it -with the same `--with-openssl-dir`. diff --git a/MODERNIZATION_ROADMAP.md b/MODERNIZATION_ROADMAP.md deleted file mode 100644 index a92c71b..0000000 --- a/MODERNIZATION_ROADMAP.md +++ /dev/null @@ -1,210 +0,0 @@ -# Triangles Modernization Roadmap - -**Goal:** Make TRI faster to sync, safer for wallets, and more useful as a currency — without breaking consensus. - -**Invariant:** Any change that modifies block validation, stake modifier computation, transaction format, or signature verification MUST preserve exact consensus with existing v5.x nodes. When in doubt, test against a synced v5.8.1 node. - ---- - -## Priority 1: Faster Syncing (High Impact, Low Risk) - -### 1.1 Update Checkpoints (Easy, Immediate) -**Problem:** Last hardcoded checkpoint is at block 2,186,940. `IsInitialBlockDownload()` returns false past this point, causing orphan limit to drop from 4000 to 750 — exactly what caused the fork deadlock. - -**Fix:** Add checkpoints every ~50,000 blocks up to current height (~2,207,000+). -```cpp -// src/checkpoints.cpp - add recent checkpoints -{2190000, uint256("...")}, -{2195000, uint256("...")}, -{2200000, uint256("...")}, -{2205000, uint256("...")}, -{2210000, uint256("...")}, -``` -**Risk:** None — checkpoints are only used for IBD detection and quick rejection of clearly wrong chains. - -### 1.2 Increase Post-Checkpoint Orphan Limit (Easy) -**Problem:** 750 orphans after IBD is too low for a low-peer network. During the fork incident, 750 orphans filled up and the node deadlocked. - -**Fix:** -```cpp -// src/main.h -static const unsigned int MAX_ORPHAN_BLOCKS = 2000; // was 750 -``` -**Risk:** Slightly more memory usage during forks. Worth it for resilience. - -### 1.3 Parallel Block Download (Medium Effort) -**Problem:** Current implementation downloads blocks sequentially from one peer at a time during IBD. - -**Fix:** Increase batch sizes and allow concurrent block downloads from multiple peers: -```cpp -// src/main.cpp -// During IBD, request blocks from multiple peers simultaneously -unsigned int nGetDataBatchSize = IsInitialBlockDownload() ? 8000 : 1000; // was 4000 -``` -**Risk:** Low — larger batch sizes are already proven in Bitcoin forks. - -### 1.4 Header-First Sync (Medium Effort) -**Problem:** Node downloads full blocks before validating headers. A bad peer can waste bandwidth. - -**Fix:** Download and validate all headers first (compact ~80 bytes each), then download full blocks only for the best chain. -- Separate `getheaders`/`headers` message handling -- Download blocks only for the best header chain -- Reduces wasted bandwidth during forks by 95%+ - -### 1.5 Bootstrap Over HTTPS with Resume (Easy) -**Problem:** Built-in bootstrap (`-bootstrap`) uses raw TCP and can't resume interrupted downloads. - -**Fix:** The existing `bootstrap.cpp` already supports downloading. Add: -- Resume support (Range headers) -- SHA256 verification of downloaded archive -- Better progress reporting -- Fallback mirrors - ---- - -## Priority 2: Wallet Safety (Critical) - -### 2.1 Automatic Wallet Backup Before Dangerous Operations (Easy) -**Problem:** Corrupt wallet = lost funds. No automatic backup before risky operations. - -**Fix:** In `walletdb.cpp`, before any rewrite: -```cpp -// Before wallet.dat rewrite, copy to wallet.dat.bak -if (boost::filesystem::exists(pathWallet)) { - boost::filesystem::copy_file(pathWallet, pathWallet + ".bak", - boost::filesystem::copy_option::overwrite_if_exists); -} -``` - -### 2.2 Detect and Report BDB Corruption (Easy) -**Problem:** BDB corruption silently corrupts wallet. User doesn't know until it's too late. - -**Fix:** Add wallet integrity check on load: -```cpp -// In CWallet::LoadWallet() -// After opening, verify BDB environment is healthy -// If DB_RUNRECOVERY, auto-salvage and warn user -``` - -### 2.3 Wallet.dat Versioning (Medium Effort) -**Problem:** Single wallet.dat file. If it corrupts during write, funds are lost. - -**Fix:** Implement copy-on-write wallet saves: -- Write new wallet data to `wallet.dat.new` -- Atomically rename `wallet.dat` → `wallet.dat.old`, `wallet.dat.new` → `wallet.dat` -- Keep last 3 wallet revisions -- On load, try wallet.dat first, fall back to wallet.dat.old if corrupt - -### 2.4 Seed Phrase / HD Wallet (High Effort, High Impact) -**Problem:** Losing wallet.dat = losing everything. No recovery mechanism. - -**Fix:** Implement BIP39/BIP44 HD wallet as optional upgrade: -- Generate 12/24-word seed phrase on new wallet creation -- Derive all keys from seed deterministically -- Import seed on any device to recover wallet -- Keep backward compatibility with existing non-HD wallets - ---- - -## Priority 3: Network Resilience (Medium Impact) - -### 3.1 Better Peer Management (Medium Effort) -**Problem:** Low peer counts (2-6) lead to fork divergence. No prioritization of reliable peers. - -**Fix:** -- Peer reliability scoring (track which peers provide valid blocks) -- Prefer peers that are ahead and on the same chain -- Automatic disconnection of stale/forked peers -- Increase default `maxconnections` from 64 to 128 - -### 3.2 Compact Block Relay (High Effort) -**Problem:** Full blocks are sent even when the receiver likely already has most transactions. - -**Fix:** Implement BIP 152 compact blocks: -- Send block header + short transaction IDs -- Receiver fills in from mempool, only requests missing transactions -- Reduces bandwidth by ~90% during normal operation - -### 3.3 DNS Seed Infrastructure (Easy) -**Problem:** `dnsseed=0` when Tor-only means no automatic peer discovery. - -**Fix:** Run a DNS seed server that resolves to known reliable onion addresses: -``` -seed.cryptographic-triangles.org → returns onion addresses of healthy nodes -``` - ---- - -## Priority 4: User Experience (Medium Impact) - -### 4.1 Progress Reporting for IBD (Easy) -**Problem:** Users see "downloading blocks..." with no useful progress indicator. - -**Fix:** -- Report `headers` vs `blocks` progress separately -- Show estimated time remaining based on download speed -- Log progress every 1000 blocks (currently every 5000) -- Qt wallet: update progress bar more frequently - -### 4.2 Staking Dashboard Improvements (Easy) -**Problem:** Qt wallet shows staking info but not clearly. - -**Fix:** -- Show expected time to stake more prominently -- Display staking weight as percentage of network -- Notify when stake is found (system notification) -- Show "staking" indicator in system tray - -### 4.3 Transaction Fee Estimation (Medium Effort) -**Problem:** No fee estimation. Users guess. - -**Fix:** Track recent block inclusion rates by fee level, provide fee recommendations. - ---- - -## Priority 5: Code Modernization (Low Urgency, Good Hygiene) - -### 5.1 C++17/20 Features -- Replace raw pointers with smart pointers where safe -- Use `std::optional`, `std::string_view`, `std::filesystem` -- Replace boost::filesystem with std::filesystem (C++17) - -### 5.2 Build System -- CMake is already in place (good) -- Add sanitizers (ASAN, UBSAN) to CI -- Static analysis with clang-tidy - -### 5.3 Testing -- Current test coverage is thin -- Add unit tests for: - - Checkpoint validation - - Stake modifier computation - - Bootstrap download/resume - - Wallet BDB recovery - - Orphan block handling - ---- - -## What NOT to Change - -These are consensus-critical and must remain identical: -- Block validation rules -- Stake modifier computation (`ComputeNextStakeModifier`) -- Transaction signature verification -- Block reward schedule -- PoW/PoS target computation -- Chain trust / difficulty adjustment -- Message serialization format -- Protocol version handshaking - -Any change to these requires a coordinated network upgrade (hard fork). - ---- - -## Implementation Order - -1. **This week:** Update checkpoints (1.1), increase orphan limit (1.2), wallet backup before save (2.1) -2. **Next week:** Better progress reporting (4.1), increase batch size (1.3) -3. **Month 1:** Wallet versioning (2.3), bootstrap resume (1.5) -4. **Month 2:** Header-first sync (1.4), peer reliability (3.1) -5. **Month 3+:** HD wallet (2.4), compact blocks (3.2) diff --git a/OPENCLAW-BOOTSTRAP-SNAPSHOT-GUIDE.md b/OPENCLAW-BOOTSTRAP-SNAPSHOT-GUIDE.md deleted file mode 100644 index fa8fad4..0000000 --- a/OPENCLAW-BOOTSTRAP-SNAPSHOT-GUIDE.md +++ /dev/null @@ -1,300 +0,0 @@ -# OpenClaw Bootstrap Snapshot Guide - -## Purpose - -This document tells OpenClaw exactly how to update the existing Triangles bootstrap server so new wallets download a ready-to-use snapshot instead of downloading `blk0001.dat` and rebuilding the index locally. - -This guide matches the current wallet code in: - -- `src/bootstrap.cpp` -- `src/bootstrap.h` -- `src/checkpoints.cpp` -- `src/version.h` - -## What The Wallet Actually Does - -When a fresh wallet bootstraps, it: - -1. Downloads `http://bootstrap.cryptographic-triangles.org/bootstrap.tar.gz` -2. Extracts it into the data directory -3. Requires `blk0001.dat` to exist after extraction -4. Looks for `txleveldb/` and `snapshot.manifest` -5. Keeps `txleveldb/` only if `snapshot.manifest` passes verification -6. Deletes `txleveldb/` if verification fails, then rebuilds from `blk0001.dat` -7. Always deletes `database/` from the extracted snapshot - -The verification rules are strict: - -- `format` must be `1` -- `network` must be `main` on mainnet -- `dbversion` must be `70509` -- `height` and `hash` must exactly match a hardcoded checkpoint - -If any of those checks fail, the wallet throws away the shipped `txleveldb/`. - -## Current Hardcoded Mainnet Checkpoint - -As of the current codebase, the latest hardcoded mainnet checkpoint is: - -- Height: `2186940` -- Hash: `bd952e8d4a612e336d840ad924a7e09395e36bcd9d929b302e47e60b5c3098c0` - -OpenClaw must not generate a manifest with an arbitrary tip hash. The manifest only survives if it matches a hardcoded checkpoint from `src/checkpoints.cpp`. - -## Important Limitation - -If the live chain tip is past the latest hardcoded checkpoint, OpenClaw has two valid options: - -1. Publish a snapshot taken exactly at the latest hardcoded checkpoint -2. Publish `blk0001.dat` only, without `txleveldb/`, and let clients rebuild locally - -OpenClaw must not publish a `snapshot.manifest` for a height/hash that is not compiled into the wallet. - -## Files OpenClaw Should Publish - -The preferred `bootstrap.tar.gz` should contain: - -- `blk0001.dat` -- `txleveldb/` -- `snapshot.manifest` -- optionally `peers.dat` - -It must not contain: - -- `wallet.dat` -- `database/` -- `.lock` -- pid files -- logs -- Tor state - -Legacy fallback files should still exist on the web root: - -- `blk0001.dat` -- `filelist.txt` - -## Requirements For The Source Node - -Before building a snapshot, the source node should be: - -- fully synced -- cleanly shut down before copying files -- built from the same code/version expected by clients -- using the same LevelDB schema as the client (`DATABASE_VERSION=70509`) - -Recommended node config for the source snapshot node: - -```ini -txindex=1 -addressindex=1 -daemon=1 -server=1 -``` - -`addressindex=1` is recommended so clients that enable address index can benefit from faster indexed wallet rescans and address RPCs immediately. - -## OpenClaw Workflow - -### Step 1: Decide Whether A Prebuilt Index Is Allowed - -OpenClaw must first decide whether it can ship `txleveldb/`. - -Rules: - -- If the snapshot node is exactly at checkpoint `2186940`, shipping `txleveldb/` is allowed -- If the snapshot node is above `2186940` and the code has not been updated with a newer checkpoint, do not ship `txleveldb/` -- In that case, publish a blocks-only bootstrap instead - -### Step 2: Stop The Source Node Cleanly - -Never copy a live LevelDB directory. - -```bash -trianglesd stop -sleep 10 -pgrep -af trianglesd || true -``` - -OpenClaw should confirm the daemon is fully stopped before copying `txleveldb/`. - -### Step 3: Create A Staging Directory - -```bash -rm -rf /tmp/triangles-bootstrap-stage -mkdir -p /tmp/triangles-bootstrap-stage -``` - -### Step 4: Copy Snapshot Files - -For a verified snapshot: - -```bash -cp ~/.triangles/blk0001.dat /tmp/triangles-bootstrap-stage/ -cp -a ~/.triangles/txleveldb /tmp/triangles-bootstrap-stage/ -test -f ~/.triangles/peers.dat && cp ~/.triangles/peers.dat /tmp/triangles-bootstrap-stage/ -``` - -Do not copy: - -```bash -rm -rf /tmp/triangles-bootstrap-stage/database -rm -f /tmp/triangles-bootstrap-stage/wallet.dat -rm -f /tmp/triangles-bootstrap-stage/.lock -rm -f /tmp/triangles-bootstrap-stage/*.pid -rm -f /tmp/triangles-bootstrap-stage/debug.log -``` - -### Step 5: Write `snapshot.manifest` - -If OpenClaw is publishing a verified prebuilt index, write: - -```bash -cat > /tmp/triangles-bootstrap-stage/snapshot.manifest << 'EOF' -format=1 -network=main -height=2186940 -hash=bd952e8d4a612e336d840ad924a7e09395e36bcd9d929b302e47e60b5c3098c0 -dbversion=70509 -EOF -``` - -Rules: - -- `hash` must not include `0x` -- `network` must be `main` -- `dbversion` must be `70509` -- If OpenClaw is publishing blocks-only bootstrap, it should omit `snapshot.manifest` entirely - -### Step 6: Build The Tarball - -```bash -cd /tmp/triangles-bootstrap-stage -tar czf /tmp/bootstrap.tar.gz . -``` - -### Step 7: Publish To The Existing Bootstrap Server - -This guide assumes the existing nginx root is: - -- `/var/www/triangles-bootstrap` - -Publish the preferred tarball and the legacy fallback files: - -```bash -sudo mkdir -p /var/www/triangles-bootstrap -sudo mv /tmp/bootstrap.tar.gz /var/www/triangles-bootstrap/bootstrap.tar.gz -sudo cp ~/.triangles/blk0001.dat /var/www/triangles-bootstrap/blk0001.dat -printf "blk0001.dat\n" | sudo tee /var/www/triangles-bootstrap/filelist.txt > /dev/null -sudo chown -R www-data:www-data /var/www/triangles-bootstrap -``` - -If OpenClaw is publishing a blocks-only bootstrap, the commands are the same except the tarball should contain only `blk0001.dat` and optional `peers.dat`. - -## Validation Checklist - -Before marking the update complete, OpenClaw should verify: - -### Tarball contents - -```bash -tar tzf /var/www/triangles-bootstrap/bootstrap.tar.gz | sort -``` - -Expected for verified snapshot: - -- `./blk0001.dat` -- `./txleveldb/...` -- `./snapshot.manifest` - -Expected not to exist: - -- `wallet.dat` -- `database/` - -### HTTP responses - -```bash -curl -I http://localhost/bootstrap.tar.gz -curl -I http://localhost/blk0001.dat -curl http://localhost/filelist.txt -``` - -Expected: - -- HTTP `200` -- `filelist.txt` contains `blk0001.dat` - -### Manifest sanity - -```bash -tar xOf /var/www/triangles-bootstrap/bootstrap.tar.gz ./snapshot.manifest -``` - -Expected: - -- `format=1` -- `network=main` -- `height=2186940` -- `hash=bd952e8d4a612e336d840ad924a7e09395e36bcd9d929b302e47e60b5c3098c0` -- `dbversion=70509` - -## Fresh-Client Test - -OpenClaw should test the artifact on a clean machine or clean data directory: - -```bash -mv ~/.triangles ~/.triangles.backup.$(date +%s) -mkdir -p ~/.triangles -trianglesd -bootstrap -``` - -Then inspect startup logs. - -Successful verified snapshot behavior should include: - -- snapshot downloaded -- `snapshot.manifest found` -- `manifest verified - keeping pre-built index` -- no message about removing extracted `txleveldb/` - -Failure behavior will include: - -- manifest parse or verification failure -- `removing extracted txleveldb/` -- slow rebuild from `blk0001.dat` - -## Safe Publish Procedure - -OpenClaw should use this order: - -1. Build snapshot in `/tmp` -2. Validate tarball contents -3. Replace `/var/www/triangles-bootstrap/bootstrap.tar.gz` -4. Replace `/var/www/triangles-bootstrap/blk0001.dat` -5. Replace `/var/www/triangles-bootstrap/filelist.txt` -6. Confirm HTTP `200` - -This avoids serving a half-written tarball. - -## Example Bot Prompt - -Use this exact tasking for OpenClaw: - -```text -Update the existing Triangles bootstrap server on bootstrap.cryptographic-triangles.org. - -Rules: -- Build the snapshot from a cleanly stopped source node -- If the source node is exactly at hardcoded checkpoint 2186940 / bd952e8d4a612e336d840ad924a7e09395e36bcd9d929b302e47e60b5c3098c0, publish a verified snapshot containing blk0001.dat, txleveldb/, and snapshot.manifest -- If the source node is above the latest hardcoded checkpoint, publish a blocks-only bootstrap and do not ship txleveldb/ -- Do not ship wallet.dat, database/, .lock, pid files, logs, or Tor state -- Publish bootstrap.tar.gz, blk0001.dat, and filelist.txt to /var/www/triangles-bootstrap -- Verify curl HTTP 200 for bootstrap.tar.gz and blk0001.dat -- Report the tarball contents and whether the snapshot is verified or blocks-only -``` - -## Recommended Next Improvement - -This workflow will stay constrained until the next checkpoint is updated in `src/checkpoints.cpp`. - -If you want OpenClaw to keep shipping prebuilt `txleveldb/` snapshots as the chain advances, the software needs periodic checkpoint updates. Without that, the verified snapshot path will stop at the latest compiled checkpoint and clients will fall back to rebuilds. diff --git a/TODO_DOCUMENTATION.md b/TODO_DOCUMENTATION.md deleted file mode 100644 index 322c402..0000000 --- a/TODO_DOCUMENTATION.md +++ /dev/null @@ -1,123 +0,0 @@ -# TODO/FIXME Documentation - -Detailed context for each TODO/FIXME in the codebase. - -## Critical (Needs Attention) - -### src/rpcmining.cpp:263 - Thread Safety Issue -```cpp -static mapNewBlock_t mapNewBlock; // FIXME: thread safety -``` -**Issue:** Static variable accessed by multiple RPC threads without mutex protection. -**Impact:** Potential race condition in getwork RPC (used for mining). -**Status:** Low priority - PoW mining ended at block 9000, this code path rarely used. -**Fix:** Add std::mutex and lock_guard if getwork usage increases. - -### src/qt/walletmodel.cpp:249 - Collision Risk -```cpp -if((total + nFeeRequired) > nBalance) // FIXME: could cause collisions in the future -``` -**Issue:** Balance check may have edge case causing transaction collisions. -**Context:** In createTransaction fee calculation loop. -**Status:** Needs investigation - unclear what "collisions" means here. -**Fix:** Review Bitcoin Core's current implementation of this logic. - -### src/smessage.cpp - File Size Limits -```cpp -// Lines 863, 2219, 2373: "TODO files must be split if > 2GB" -``` -**Issue:** Secure message storage files not split when exceeding 2GB. -**Impact:** May fail on 32-bit systems or with large message volumes. -**Status:** Low priority - unlikely to reach 2GB in practice. -**Fix:** Implement file rotation when approaching 2GB limit. - -## Medium Priority (Encapsulation/API) - -### src/protocol.h - Make Members Private -```cpp -// Lines 50, 100, 132: "TODO: make private (improves encapsulation)" -``` -**Issue:** CAddress, CInv, CMessageHeader have public data members. -**Impact:** Poor encapsulation, harder to maintain invariants. -**Status:** Deferred - would require extensive refactoring. -**Fix:** Add getter/setter methods, make members private, update all call sites. - -### src/wallet.h:378 - nOrderPos Calculation -```cpp -nOrderPos = -1; // TODO: calculate elsewhere -``` -**Issue:** Transaction ordering position calculated in constructor. -**Impact:** Minor - works but not ideal separation of concerns. -**Status:** Deferred - no functional issue. -**Fix:** Move calculation to WalletDB when transaction is added. - -### src/rpcwallet.cpp / src/qt/askpassphrasedialog.cpp - SecureString Conversion -**Issue:** Password-handling paths were converting through `.c_str()` because `SecureString` -did not have a convenient conversion helper from `std::string`. -**Impact:** Unnecessary C-string shims in sensitive code paths. -**Status:** Resolved. -**Fix:** Added `MakeSecureString(const std::string&)` in `src/allocators.h` and updated -the wallet RPC and passphrase dialog call sites to use it directly. - -## Low Priority (Nice-to-Have) - -### src/util.cpp:1322 - Disabled Feature -```cpp -// TODO: This is currently disabled because it needs to be verified to work -``` -**Context:** File descriptor management code. -**Status:** Intentionally disabled pending verification. -**Fix:** Test thoroughly, then enable if needed. - -### src/tor/tor_embedded.cpp:209 - Tor Shutdown API -```cpp -// TODO: Tor 0.4.9+ may add tor_api_shutdown(), use it when available -``` -**Context:** Embedded Tor cleanup. -**Status:** Waiting for upstream Tor API. -**Fix:** Check Tor 0.4.9+ releases for new API, integrate when stable. - -### src/init.cpp:442 - Sanity Checks -```cpp -// TODO: remaining sanity checks, see #4081 -``` -**Context:** Bitcoin Core issue #4081 - additional startup sanity checks. -**Status:** Deferred - core checks already in place. -**Fix:** Review Bitcoin Core's current sanity check implementation. - -### src/rpcmining.cpp:232 - DRM Comment -```cpp -CDataStream(coinbase, SER_NETWORK, PROTOCOL_VERSION) >> pblock->vtx[0]; // FIXME - DRM! -``` -**Issue:** Unclear what "DRM" means here - likely "Data Race Maybe"? -**Status:** Needs clarification from original author. -**Fix:** Investigate if there's an actual issue, otherwise remove comment. - -## Deferred (External/Low Impact) - -### LevelDB TODOs (src/leveldb/*) -**Status:** Upstream LevelDB issues - don't modify embedded library. -**Action:** None - track upstream LevelDB project. - -### Qt TODOs (src/qt/*) -**Status:** UI improvements, not critical. -**Action:** Track as nice-to-have enhancements. - -### Secure Message TODOs (src/smessage.cpp) -Multiple minor improvements suggested: -- Include hash in certain operations -- Improve thread shutdown -- Set default recv/recvAnon behavior -- Update outbox after PoW completes - -**Status:** Non-critical enhancements. -**Action:** Consider for future encrypted messaging upgrades. - -## Summary - -**Critical:** 3 items (thread safety, balance collision, file limits) -**Medium:** 6 items (encapsulation, SecureString) -**Low:** 5 items (disabled features, upstream APIs) -**Deferred:** ~24 items (external libs, minor enhancements) - -**Recommendation:** Focus on documenting critical items in code comments, defer fixes until specific issues arise. diff --git a/src/tor/tor_embedded.cpp b/src/tor/tor_embedded.cpp index a39ae80..c5a4986 100644 --- a/src/tor/tor_embedded.cpp +++ b/src/tor/tor_embedded.cpp @@ -3,7 +3,6 @@ // Distributed under the MIT/X11 software license // // BUILD REQUIREMENT: Link against libtor.a built from the official Tor source. -// See CODEX-TOR-GUIDE.md for submodule setup and build instructions. // // This file compiles in two modes: // 1. ENABLE_TOR_EMBEDDED defined: full embedded Tor via tor_api.h diff --git a/upgrade-notes-2026-04-14.md b/upgrade-notes-2026-04-14.md deleted file mode 100644 index a46692b..0000000 --- a/upgrade-notes-2026-04-14.md +++ /dev/null @@ -1,36 +0,0 @@ -## TRI Node Upgrade to v5.8.0 - April 14, 2026 - -This document outlines the process and results of upgrading the TRI network nodes to version 5.8.0. - -### Initial State - -- **DNS2:** `v5.7.9` @ block `2,203,611` -- **DNS3:** `v5.7.5` @ block `2,204,954` -- **Contabo Seeds:** `v5.7.9` @ block `2,203,594` - -Nodes were on multiple versions and forks. - -### Upgrade Process - -1. **Version Confirmation:** Verified `v5.8.0` was available on GitHub. -2. **Upgrades:** - - DNS2 upgraded to `v5.8.0` via `dpkg`. - - DNS3 upgraded to `v5.8.0` via `dpkg`. - - Contabo seeds (`tri-seed-1` to `4`) upgraded to `v5.8.0` via `dpkg` inside their containers. -3. **Chain Reset:** To resolve forks, the chain data (blocks, chainstate, peers) was wiped on DNS2 and all Contabo seeds. Wallets and configs were preserved. DNS3 was left as the canonical chain source. - -### Current Status - -- All nodes are now running `v5.8.0`. -- Nodes are currently re-syncing to the canonical chain. Monitoring is in progress. - -### DNS2 Wallet Corruption and Recovery - -- **Symptom:** `triangles.service` on DNS2 was in a crash loop. Logs showed a recurring `CDB() : can't open database file wallet.dat, error -30973` error. -- **Diagnosis:** `wallet.dat` file was corrupted. -- **Recovery:** - 1. The corrupted wallet was moved to `wallet.dat.corrupted` for safety. - 2. The latest wallet backup (`dns2-wallet_20260414_031501.dat`) was restored from Dropbox. - 3. The `triangles.service` was restarted. - -This restored the wallet to a healthy state.