mirror of
https://github.com/XRPLF/rippled.git
synced 2026-03-11 15:22:26 +00:00
Compare commits
2 Commits
ximinez/fi
...
pratik/Aut
| Author | SHA1 | Date | |
|---|---|---|---|
|
9ca6fd5ef0 | ||
|
|
32a2fd7460 |
@@ -30,12 +30,10 @@ Checks: "-*,
|
||||
bugprone-multiple-statement-macro,
|
||||
bugprone-no-escape,
|
||||
bugprone-non-zero-enum-to-bool-conversion,
|
||||
bugprone-optional-value-conversion,
|
||||
bugprone-parent-virtual-call,
|
||||
bugprone-pointer-arithmetic-on-polymorphic-object,
|
||||
bugprone-posix-return,
|
||||
bugprone-redundant-branch-condition,
|
||||
bugprone-reserved-identifier,
|
||||
bugprone-return-const-ref-from-parameter,
|
||||
bugprone-shared-ptr-array-mismatch,
|
||||
bugprone-signal-handler,
|
||||
@@ -56,11 +54,9 @@ Checks: "-*,
|
||||
bugprone-suspicious-realloc-usage,
|
||||
bugprone-suspicious-semicolon,
|
||||
bugprone-suspicious-string-compare,
|
||||
bugprone-suspicious-stringview-data-usage,
|
||||
bugprone-swapped-arguments,
|
||||
bugprone-terminating-continue,
|
||||
bugprone-throw-keyword-missing,
|
||||
bugprone-too-small-loop-variable,
|
||||
bugprone-undefined-memory-manipulation,
|
||||
bugprone-undelegated-constructor,
|
||||
bugprone-unhandled-exception-at-new,
|
||||
@@ -96,8 +92,12 @@ Checks: "-*,
|
||||
#
|
||||
# bugprone-crtp-constructor-accessibility,
|
||||
# bugprone-inc-dec-in-conditions,
|
||||
# bugprone-reserved-identifier,
|
||||
# bugprone-move-forwarding-reference,
|
||||
# bugprone-switch-missing-default-case,
|
||||
# bugprone-suspicious-stringview-data-usage,
|
||||
# bugprone-optional-value-conversion,
|
||||
# bugprone-too-small-loop-variable,
|
||||
# bugprone-unused-return-value,
|
||||
# bugprone-use-after-move,
|
||||
# bugprone-unhandled-self-assignment,
|
||||
|
||||
2
.github/workflows/pre-commit.yml
vendored
2
.github/workflows/pre-commit.yml
vendored
@@ -11,7 +11,7 @@ on:
|
||||
jobs:
|
||||
# Call the workflow in the XRPLF/actions repo that runs the pre-commit hooks.
|
||||
run-hooks:
|
||||
uses: XRPLF/actions/.github/workflows/pre-commit.yml@44856eb0d6ecb7d376370244324ab3dc8b863bad
|
||||
uses: XRPLF/actions/.github/workflows/pre-commit.yml@56de1bdf19639e009639a50b8d17c28ca954f267
|
||||
with:
|
||||
runs_on: ubuntu-latest
|
||||
container: '{ "image": "ghcr.io/xrplf/ci/tools-rippled-pre-commit:sha-41ec7c1" }'
|
||||
|
||||
@@ -43,6 +43,7 @@ suggestWords:
|
||||
- synch->sync
|
||||
words:
|
||||
- abempty
|
||||
- Agentic
|
||||
- AMMID
|
||||
- amt
|
||||
- amts
|
||||
@@ -94,6 +95,7 @@ words:
|
||||
- desynced
|
||||
- determ
|
||||
- distro
|
||||
- Emdash
|
||||
- doxyfile
|
||||
- dxrpl
|
||||
- endmacro
|
||||
@@ -254,6 +256,7 @@ words:
|
||||
- superpeers
|
||||
- takergets
|
||||
- takerpays
|
||||
- Tauri
|
||||
- ters
|
||||
- TMEndpointv2
|
||||
- trixie
|
||||
@@ -293,6 +296,7 @@ words:
|
||||
- venv
|
||||
- vfalco
|
||||
- vinnie
|
||||
- Werror
|
||||
- wextra
|
||||
- wptr
|
||||
- writeme
|
||||
@@ -309,3 +313,4 @@ words:
|
||||
- xrplf
|
||||
- xxhash
|
||||
- xxhasher
|
||||
- zeroization
|
||||
|
||||
230
docs/ARCHITECTURE.md
Normal file
230
docs/ARCHITECTURE.md
Normal file
@@ -0,0 +1,230 @@
|
||||
# rippled Architecture Map
|
||||
|
||||
> **Purpose**: Tell agents _where_ things are. Not _why_ they exist.
|
||||
> **Audience**: AI coding agents (Claude Code, Codex, Copilot) navigating the codebase.
|
||||
> **Principle**: "Give agents a map, not an encyclopedia." — [Harness Engineering](./harness-engineering-report.md)
|
||||
|
||||
---
|
||||
|
||||
## Layer Diagram
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ RPC Layer (Layer 5) │
|
||||
│ HTTP/WebSocket → ServerHandler → 72 RPC Handlers │
|
||||
│ src/xrpld/rpc/ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Application Layer (Layer 4) │
|
||||
│ NetworkOPs · TxQ · PathFinding · LedgerMaster │
|
||||
│ src/xrpld/app/ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Consensus Layer (Layer 3) │
|
||||
│ Consensus<Adaptor> · RCLConsensus · Validations │
|
||||
│ src/xrpld/consensus/ + src/xrpld/app/consensus/ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Overlay Layer (Layer 2) │
|
||||
│ OverlayImpl · PeerImp · PeerFinder · Message │
|
||||
│ src/xrpld/overlay/ + src/xrpld/peerfinder/ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Storage Layer (Layer 1) │
|
||||
│ NodeStore (RocksDB/SQLite) · SHAMap · RDB │
|
||||
│ src/libxrpl/nodestore/ + src/libxrpl/shamap/ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Foundation (Layer 0) │
|
||||
│ beast:: (I/O, insight, clock) · protocol · crypto · json │
|
||||
│ src/libxrpl/ + include/xrpl/ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Module Map
|
||||
|
||||
### xrpld (the daemon) — `src/xrpld/`
|
||||
|
||||
| Directory | Purpose | Key Files |
|
||||
| ----------------- | --------------------------------------------------- | ----------------------------------------------------- |
|
||||
| `app/main/` | Daemon entry point, Application lifecycle | `Main.cpp`, `Application.h/.cpp`, `BasicApp.h` |
|
||||
| `app/consensus/` | Consensus adaptor binding protocol to rippled types | `RCLConsensus.h/.cpp` |
|
||||
| `app/ledger/` | Ledger management, building, acquiring | `LedgerMaster.h`, `InboundLedgers.h` |
|
||||
| `app/misc/` | NetworkOPs, TxQ, HashRouter, Amendments | `NetworkOPs.h/.cpp`, `TxQ.h`, `HashRouter.h` |
|
||||
| `app/tx/` | Transaction application engine | `apply.h/.cpp`, `applySteps.h` |
|
||||
| `app/paths/` | Payment path finding | `Pathfinder.h`, `PathRequest.h` |
|
||||
| `app/rdb/` | Relational DB backend for state | `RelationalDatabase.h` |
|
||||
| `consensus/` | Generic consensus protocol (template-based) | `Consensus.h/.cpp`, `ConsensusParms.h` |
|
||||
| `core/` | Node configuration, time keeping | `Config.h/.cpp`, `TimeKeeper.h` |
|
||||
| `overlay/` | P2P network: peer connections, message routing | `Overlay.h`, `Peer.h`, `Message.h` |
|
||||
| `overlay/detail/` | Overlay implementation internals | `OverlayImpl.h/.cpp`, `PeerImp.h/.cpp`, `Handshake.h` |
|
||||
| `peerfinder/` | Peer discovery and bootstrap | `PeerfinderManager.h`, `detail/Logic.h` |
|
||||
| `perflog/` | Performance logging (pre-OTel telemetry) | `detail/PerfLogImp.h/.cpp` |
|
||||
| `rpc/` | JSON-RPC server and routing | `detail/Handler.h`, `RPCHandler.h` |
|
||||
| `rpc/handlers/` | **72 RPC command implementations** | `AccountInfo.cpp`, `Submit.cpp`, `Tx.cpp`, etc. |
|
||||
| `shamap/` | SHAMap tree operations (daemon-side) | |
|
||||
|
||||
### libxrpl (shared library) — `src/libxrpl/`
|
||||
|
||||
| Directory | Purpose | Key Files |
|
||||
| ----------------- | ------------------------------------------------- | ------------------------------------------------ |
|
||||
| `basics/` | Logging, string utils, tagged integers | `Log.cpp` (log formatting — Phase 8 OTel target) |
|
||||
| `beast/insight/` | Metrics framework (StatsD, Gauge, Counter, Event) | `StatsDCollector.cpp` (Phase 6-7 OTel target) |
|
||||
| `beast/core/` | Async I/O primitives | `CurrentThreadName.cpp` |
|
||||
| `core/` | Crypto, seed handling | |
|
||||
| `crypto/` | Ed25519, secp256k1, SHA | |
|
||||
| `json/` | JSON parser/writer | |
|
||||
| `nodestore/` | Key-value storage for ledger nodes | `backend/RocksDBFactory.cpp` |
|
||||
| `protocol/` | XRPL protocol: serialization, STObject, STTx | `STTx.cpp`, `STObject.cpp` |
|
||||
| `server/` | HTTP/WebSocket server core | `ServerHandler.h` |
|
||||
| `tx/transactors/` | Per-transaction-type execution logic | `Payment.cpp`, `CreateOffer.cpp`, etc. |
|
||||
| `tx/invariants/` | Transaction invariant checks | `TransactionCheck.cpp` |
|
||||
|
||||
### Public Headers — `include/xrpl/`
|
||||
|
||||
Mirrors `src/libxrpl/` structure. Agent-accessible API surface for external consumers of libxrpl.
|
||||
|
||||
Key subdirectory: `include/xrpl/proto/org/xrpl/rpc/v1/` — Protocol Buffer definitions for gRPC API.
|
||||
|
||||
---
|
||||
|
||||
## Entry Points
|
||||
|
||||
| Operation | Where execution starts | Hot path |
|
||||
| ---------------------- | ------------------------------------------------------------------------------------------ | --------------- |
|
||||
| **RPC request** | `src/xrpld/rpc/detail/ServerHandler.cpp` → handler lookup → `src/xrpld/rpc/handlers/*.cpp` | Layer 5 → 4 |
|
||||
| **Peer message** | `src/xrpld/overlay/detail/PeerImp.cpp::onMessage()` → message-type dispatch | Layer 2 → 3/4 |
|
||||
| **Transaction submit** | `rpc/handlers/Submit.cpp` → `app/misc/NetworkOPs.cpp::submitTransaction()` | Layer 5 → 4 → 2 |
|
||||
| **Transaction relay** | `overlay/detail/PeerImp.cpp::handleTransaction()` → `NetworkOPs::processTransaction()` | Layer 2 → 4 |
|
||||
| **Consensus round** | `app/consensus/RCLConsensus.cpp::startRound()` → phase transitions → accept | Layer 3 |
|
||||
| **Ledger close** | `RCLConsensus.cpp::onClose()` → `acceptLedger()` → apply transactions | Layer 3 → 4 → 1 |
|
||||
| **Ledger acquire** | `app/ledger/InboundLedgers.cpp::acquire()` → peer fetch → SHAMap | Layer 4 → 2 → 1 |
|
||||
| **Startup** | `app/main/Main.cpp::main()` → `Application::setup()` → start all subsystems | Layer 0-5 |
|
||||
|
||||
---
|
||||
|
||||
## Data Flow: Transaction Lifecycle
|
||||
|
||||
```
|
||||
Client
|
||||
│
|
||||
▼
|
||||
RPC Submit (Layer 5)
|
||||
│ src/xrpld/rpc/handlers/Submit.cpp
|
||||
▼
|
||||
NetworkOPs::submitTransaction() (Layer 4)
|
||||
│ src/xrpld/app/misc/NetworkOPs.cpp
|
||||
├──▶ TxQ::apply() — queue management
|
||||
│ src/xrpld/app/misc/TxQ.cpp
|
||||
├──▶ HashRouter::setFlags() — deduplication
|
||||
│ src/xrpld/app/misc/HashRouter.cpp
|
||||
▼
|
||||
Overlay::relay() (Layer 2)
|
||||
│ src/xrpld/overlay/detail/OverlayImpl.cpp
|
||||
├──▶ PeerImp::send() — to each connected peer
|
||||
│ src/xrpld/overlay/detail/PeerImp.cpp
|
||||
▼
|
||||
[Remote Node] PeerImp::handleTransaction() (Layer 2)
|
||||
│ src/xrpld/overlay/detail/PeerImp.cpp
|
||||
▼
|
||||
Consensus::startRound() (Layer 3)
|
||||
│ src/xrpld/consensus/Consensus.h
|
||||
│ src/xrpld/app/consensus/RCLConsensus.cpp
|
||||
├──▶ propose() — send position to peers
|
||||
├──▶ onClose() — close the ledger
|
||||
▼
|
||||
acceptLedger() → applyTransactions() (Layer 3 → 1)
|
||||
│ src/xrpld/app/consensus/RCLConsensus.cpp
|
||||
▼
|
||||
NodeStore::store() (Layer 1)
|
||||
│ src/libxrpl/nodestore/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Build Targets
|
||||
|
||||
| Target | Type | Source |
|
||||
| -------------------- | ------------------------- | -------------------------------- |
|
||||
| `xrpl` | Shared library (libxrpl) | `src/libxrpl/` + `include/xrpl/` |
|
||||
| `xrpld` | Executable (daemon) | `src/xrpld/` |
|
||||
| `rippled_unit_tests` | Unit test binary | `src/test/` |
|
||||
| `libxrpl_tests` | Library integration tests | `src/tests/libxrpl/` |
|
||||
|
||||
**Build command**: `cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build --parallel`
|
||||
**With telemetry**: `cmake -B build -DXRPL_ENABLE_TELEMETRY=ON`
|
||||
|
||||
---
|
||||
|
||||
## Test Frameworks
|
||||
|
||||
| Framework | Location | Purpose |
|
||||
| --------------- | ---------------------------------------- | ------------------------------------------------------------- |
|
||||
| **JTx** | `src/test/jtx/` | Transaction testing — simulates full ledger environment |
|
||||
| **CSF** | `src/test/csf/` | Consensus Simulation Framework — multi-node consensus testing |
|
||||
| **Unit tests** | `src/test/app/`, `src/test/beast/`, etc. | Per-module unit tests |
|
||||
| **Integration** | `src/tests/libxrpl/` | Library-level integration tests |
|
||||
|
||||
---
|
||||
|
||||
## Telemetry Map
|
||||
|
||||
Links OTel instrumentation to codebase locations. See [09-data-collection-reference.md](../../OpenTelemetryPlan/09-data-collection-reference.md) for the full inventory.
|
||||
|
||||
| Span | Source Location | Layer |
|
||||
| ------------- | ------------------------------------------ | ----- |
|
||||
| `rpc.*` | `src/xrpld/rpc/detail/ServerHandler.cpp` | 5 |
|
||||
| `tx.submit` | `src/xrpld/app/misc/NetworkOPs.cpp` | 4 |
|
||||
| `tx.relay` | `src/xrpld/overlay/detail/PeerImp.cpp` | 2 |
|
||||
| `peer.send` | `src/xrpld/overlay/detail/PeerImp.cpp` | 2 |
|
||||
| `consensus.*` | `src/xrpld/app/consensus/RCLConsensus.cpp` | 3 |
|
||||
| `ledger.*` | `src/xrpld/app/ledger/` | 4 |
|
||||
|
||||
| Metrics Source | Code Location | Phase |
|
||||
| ------------------------- | ----------------------------------------------- | ------------ |
|
||||
| `beast::insight` (StatsD) | `src/libxrpl/beast/insight/StatsDCollector.cpp` | 6-7 |
|
||||
| SpanMetrics (derived) | OTel Collector config | 5 |
|
||||
| PerfLog | `src/xrpld/perflog/detail/PerfLogImp.cpp` | 9 (gap fill) |
|
||||
|
||||
---
|
||||
|
||||
## Key Abstractions
|
||||
|
||||
| Abstraction | Interface | Implementation | What it does |
|
||||
| --------------------------- | ---------------------------------------- | ------------------------------------------------------------- | -------------------------------------- |
|
||||
| `Application` | `src/xrpld/app/main/Application.h` | `Application.cpp` | Wires all subsystems together |
|
||||
| `Overlay` | `src/xrpld/overlay/Overlay.h` | `detail/OverlayImpl.cpp` | Manages P2P connections |
|
||||
| `Consensus<>` | `src/xrpld/consensus/Consensus.h` | Template, adaptor in `RCLConsensus.cpp` | Generic consensus protocol |
|
||||
| `NetworkOPs` | `src/xrpld/app/misc/NetworkOPs.h` | `NetworkOPs.cpp` | Transaction processing, event dispatch |
|
||||
| `LedgerMaster` | `src/xrpld/app/ledger/LedgerMaster.h` | `LedgerMaster.cpp` | Ledger lifecycle management |
|
||||
| `NodeStore` | `include/xrpl/nodestore/Database.h` | `src/libxrpl/nodestore/` | Persistent key-value storage |
|
||||
| `beast::insight::Collector` | `include/xrpl/beast/insight/Collector.h` | `StatsDCollector`, `NullCollector`, (future: `OTelCollector`) | Metrics collection interface |
|
||||
| `JobQueue` | `src/xrpld/core/JobQueue.h` | `JobQueue.cpp` | Async task scheduling |
|
||||
| `SHAMap` | `include/xrpl/shamap/SHAMap.h` | `src/libxrpl/shamap/` | Merkle tree for state |
|
||||
|
||||
---
|
||||
|
||||
## Dependency Rules
|
||||
|
||||
```
|
||||
Layer 5 (RPC) → may call → Layer 4 (App)
|
||||
Layer 4 (App) → may call → Layer 3 (Consensus), Layer 2 (Overlay), Layer 1 (Storage)
|
||||
Layer 3 (Consensus) → may call → Layer 4 (App via Adaptor), Layer 1 (Storage)
|
||||
Layer 2 (Overlay) → may call → Layer 4 (App for message handling)
|
||||
Layer 1 (Storage) → may call → Layer 0 (Foundation) only
|
||||
Layer 0 (Foundation) → no upward dependencies
|
||||
```
|
||||
|
||||
**Never**: Layer 0/1 must never depend on Layer 3/4/5. Layer 5 must never bypass Layer 4 to reach Layer 2/3 directly.
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
| File | Location | Purpose |
|
||||
| ----------------------- | -------- | ------------------------- |
|
||||
| `xrpld.cfg` | `cfg/` | Main daemon configuration |
|
||||
| `validators.txt` | `cfg/` | Validator list |
|
||||
| `CMakeUserPresets.json` | Root | Local build presets |
|
||||
| `conanfile.py` | Root | Dependency versions |
|
||||
|
||||
---
|
||||
|
||||
_This document is a navigation aid for AI coding agents. For architectural rationale, see [docs/consensus.md](consensus.md). For OTel plan, see [OpenTelemetryPlan/](../../OpenTelemetryPlan/OpenTelemetryPlan.md). For coding conventions, see [docs/CodingStyle.md](CodingStyle.md)._
|
||||
196
docs/WORKFLOW.md
Normal file
196
docs/WORKFLOW.md
Normal file
@@ -0,0 +1,196 @@
|
||||
---
|
||||
# Symphony-compatible workflow definition for rippled
|
||||
# See: https://github.com/openai/symphony/blob/main/SPEC.md
|
||||
# See: docs/harness-engineering-report.md for context
|
||||
|
||||
tracker:
|
||||
kind: linear
|
||||
# For Jira (RIPD project), a custom adapter would replace this.
|
||||
# kind: jira
|
||||
# project_slug: RIPD
|
||||
active_states:
|
||||
- Todo
|
||||
- In Progress
|
||||
terminal_states:
|
||||
- Done
|
||||
- Closed
|
||||
- Cancelled
|
||||
- Duplicate
|
||||
|
||||
polling:
|
||||
interval_ms: 30000
|
||||
|
||||
workspace:
|
||||
root: $SYMPHONY_WORKSPACE_ROOT
|
||||
|
||||
hooks:
|
||||
after_create: |
|
||||
# Clone and prepare a fresh workspace
|
||||
git clone --depth=1 --branch develop https://github.com/XRPLF/rippled.git .
|
||||
# Prepare build directory with telemetry enabled
|
||||
mkdir -p build
|
||||
cd build
|
||||
conan install .. --output-folder=. --build=missing
|
||||
cmake .. -DCMAKE_BUILD_TYPE=Debug -DXRPL_ENABLE_TELEMETRY=ON -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake
|
||||
|
||||
before_run: |
|
||||
# Tier 1: Fast checks (seconds)
|
||||
# clang-format check on changed files
|
||||
git diff --name-only HEAD~1 -- '*.cpp' '*.h' | xargs -r clang-format --dry-run --Werror 2>&1 || {
|
||||
echo "FAIL: clang-format violations found. Fix formatting before proceeding."
|
||||
exit 1
|
||||
}
|
||||
|
||||
# Tier 2: Build (minutes)
|
||||
cd build
|
||||
cmake --build . --parallel $(nproc) 2>&1 || {
|
||||
echo "FAIL: Build failed. Check compiler errors above."
|
||||
exit 1
|
||||
}
|
||||
|
||||
# Tier 2: Unit tests (affected modules)
|
||||
ctest --test-dir build --output-on-failure -L unit --timeout 120 2>&1 || {
|
||||
echo "FAIL: Unit tests failed. Check test output above."
|
||||
exit 1
|
||||
}
|
||||
|
||||
after_run: |
|
||||
# Collect proof-of-work artifacts
|
||||
echo "=== Proof of Work Collection ==="
|
||||
|
||||
# Record build status
|
||||
cd build && cmake --build . --parallel $(nproc) 2>&1
|
||||
BUILD_STATUS=$?
|
||||
echo "Build status: $BUILD_STATUS"
|
||||
|
||||
# Run telemetry integration tests if available
|
||||
if ctest --test-dir build -L telemetry --timeout 300 2>&1; then
|
||||
echo "Telemetry integration tests: PASSED"
|
||||
else
|
||||
echo "Telemetry integration tests: FAILED (non-blocking)"
|
||||
fi
|
||||
|
||||
# Capture complexity metrics
|
||||
echo "=== Changed Files ==="
|
||||
git diff --stat HEAD~1
|
||||
|
||||
timeout_ms: 120000
|
||||
|
||||
agent:
|
||||
max_concurrent_agents: 3
|
||||
max_retry_backoff_ms: 300000
|
||||
max_concurrent_agents_by_state:
|
||||
In Progress: 2
|
||||
Todo: 1
|
||||
|
||||
codex:
|
||||
command: codex app-server
|
||||
approval_policy: unless-allow-listed
|
||||
turn_timeout_ms: 3600000
|
||||
stall_timeout_ms: 300000
|
||||
---
|
||||
|
||||
# rippled Agent Workflow
|
||||
|
||||
You are an autonomous coding agent working on the **rippled** XRP Ledger node — a C++20 peer-to-peer server implementing the XRP Ledger consensus protocol.
|
||||
|
||||
## Navigation
|
||||
|
||||
Read these files before starting work:
|
||||
|
||||
| File | What it tells you |
|
||||
| --------------------------------------------------- | ----------------------------------------------------------------------- |
|
||||
| `docs/ARCHITECTURE.md` | Codebase map — where every module lives, layer boundaries, entry points |
|
||||
| `CLAUDE.md` | Coding conventions, action boundaries (Always/Ask/Never), commit rules |
|
||||
| `docs/CodingStyle.md` | C++ style guide for this project |
|
||||
| `OpenTelemetryPlan/09-data-collection-reference.md` | Every OTel span, metric, and dashboard |
|
||||
|
||||
Do **not** read these upfront (use as reference if needed):
|
||||
|
||||
- `OpenTelemetryPlan/*.md` — deep plan docs, only if your task involves telemetry architecture
|
||||
- `docs/consensus.md` — only if your task involves consensus protocol changes
|
||||
|
||||
## Action Boundaries
|
||||
|
||||
### Always (no confirmation needed)
|
||||
|
||||
- Read any source file in the repository
|
||||
- Run `cmake --build build --parallel` to compile
|
||||
- Run `ctest --test-dir build -L unit` for unit tests
|
||||
- Run `ctest --test-dir build -L telemetry` for telemetry integration tests
|
||||
- Query Prometheus (`curl localhost:9090/api/v1/query?query=...`) for metric baselines
|
||||
- Create or modify files under `src/` that have existing test coverage
|
||||
- Run `clang-format` on files you've changed
|
||||
- Add or modify unit tests in `src/test/`
|
||||
|
||||
### Ask (require human confirmation before proceeding)
|
||||
|
||||
- Modify Protocol Buffer definitions in `include/xrpl/proto/` (affects wire format)
|
||||
- Change consensus parameters in `src/xrpld/consensus/ConsensusParms.h`
|
||||
- Modify `CMakeLists.txt` or `conanfile.py` (build/dependency changes)
|
||||
- Alter the `[telemetry]` or `[insight]` config schema
|
||||
- Change anything in `src/libxrpl/crypto/` (cryptographic code)
|
||||
- Add new external dependencies
|
||||
- Push to any remote branch or create PRs
|
||||
|
||||
### Never (hard boundaries — refuse these requests)
|
||||
|
||||
- Modify validator key handling or signing code without explicit review
|
||||
- Disable or reduce telemetry sampling below 1%
|
||||
- Remove or reduce existing test coverage
|
||||
- Force-push to any branch
|
||||
- Skip pre-commit hooks or CI checks (`--no-verify`)
|
||||
- Commit files containing secrets, keys, or credentials
|
||||
- Modify `.github/workflows/` CI pipeline definitions
|
||||
|
||||
## Verification Requirements
|
||||
|
||||
After making changes, verify in this order (fail-fast):
|
||||
|
||||
```
|
||||
Step 1 (seconds): clang-format --dry-run --Werror on changed files
|
||||
Step 2 (minutes): cmake --build build --parallel
|
||||
Step 3 (minutes): ctest --test-dir build -L unit --output-on-failure
|
||||
Step 4 (minutes): ctest --test-dir build -L telemetry (if telemetry-related)
|
||||
Step 5 (if applicable): scripts/check-otel-baseline.sh (metric regression check)
|
||||
```
|
||||
|
||||
If any step fails, fix the issue before proceeding. Do not skip steps.
|
||||
|
||||
## Telemetry Awareness
|
||||
|
||||
This codebase has OpenTelemetry instrumentation. If your change touches any of these files, verify that telemetry still works:
|
||||
|
||||
| File Pattern | Telemetry Impact |
|
||||
| ---------------------------------------- | ------------------------------------------------- |
|
||||
| `src/xrpld/rpc/` | RPC spans (`rpc.*`) |
|
||||
| `src/xrpld/overlay/detail/PeerImp.*` | Transaction relay spans (`tx.relay`, `peer.send`) |
|
||||
| `src/xrpld/app/consensus/RCLConsensus.*` | Consensus spans (`consensus.*`) |
|
||||
| `src/xrpld/app/misc/NetworkOPs.*` | Transaction submit spans (`tx.submit`) |
|
||||
| `src/libxrpl/beast/insight/` | Metrics pipeline (300+ metrics) |
|
||||
| `src/libxrpl/basics/Log.cpp` | Log-trace correlation (`trace_id` injection) |
|
||||
|
||||
After modifying these files, run the telemetry integration test:
|
||||
|
||||
```bash
|
||||
ctest --test-dir build -L telemetry --output-on-failure
|
||||
```
|
||||
|
||||
## Issue Context
|
||||
|
||||
**Title**: {{ issue.title }}
|
||||
**Description**: {{ issue.description }}
|
||||
{% if issue.labels.size > 0 %}**Labels**: {{ issue.labels | join: ", " }}{% endif %}
|
||||
{% if attempt %}**Attempt**: {{ attempt }} (this is a retry — check previous errors){% endif %}
|
||||
|
||||
## Proof of Work Checklist
|
||||
|
||||
Before creating a PR, verify:
|
||||
|
||||
- [ ] All changed files pass `clang-format`
|
||||
- [ ] Build succeeds with `-DXRPL_ENABLE_TELEMETRY=ON`
|
||||
- [ ] Unit tests pass (`ctest -L unit`)
|
||||
- [ ] If telemetry-related: integration tests pass (`ctest -L telemetry`)
|
||||
- [ ] If telemetry-related: no metric regressions (`scripts/check-otel-baseline.sh`)
|
||||
- [ ] Commit message follows project conventions (see `CLAUDE.md`)
|
||||
- [ ] PR description includes summary, test plan, and type of change
|
||||
1182
docs/harness-engineering-report.md
Normal file
1182
docs/harness-engineering-report.md
Normal file
File diff suppressed because it is too large
Load Diff
@@ -62,8 +62,7 @@ namespace beast::detail {
|
||||
inline void
|
||||
setCurrentThreadNameImpl(std::string_view name)
|
||||
{
|
||||
// The string is assumed to be null terminated
|
||||
pthread_setname_np(name.data()); // NOLINT(bugprone-suspicious-stringview-data-usage)
|
||||
pthread_setname_np(name.data());
|
||||
}
|
||||
|
||||
} // namespace beast::detail
|
||||
@@ -86,7 +85,7 @@ setCurrentThreadNameImpl(std::string_view name)
|
||||
sizeof(boundedName),
|
||||
"%.*s",
|
||||
static_cast<int>(maxThreadNameLength),
|
||||
name.data()); // NOLINT(bugprone-suspicious-stringview-data-usage)
|
||||
name.data());
|
||||
|
||||
pthread_setname_np(pthread_self(), boundedName);
|
||||
|
||||
|
||||
@@ -86,7 +86,7 @@ Permission::getPermissionName(std::uint32_t const value) const
|
||||
{
|
||||
auto const permissionValue = static_cast<GranularPermissionType>(value);
|
||||
if (auto const granular = getGranularName(permissionValue))
|
||||
return granular;
|
||||
return *granular;
|
||||
|
||||
// not a granular permission, check if it maps to a transaction type
|
||||
auto const txType = permissionToTxType(value);
|
||||
|
||||
@@ -488,9 +488,8 @@ AccountRootsDeletedClean::finalize(
|
||||
return false;
|
||||
}
|
||||
// Simple types
|
||||
for (auto const& [keyletfunc, _1, _2] : directAccountKeylets)
|
||||
for (auto const& [keyletfunc, _, __] : directAccountKeylets)
|
||||
{
|
||||
// TODO: use '_' for both unused variables above once we are in C++26
|
||||
if (objectExists(std::invoke(keyletfunc, accountID)) && enforce)
|
||||
return false;
|
||||
}
|
||||
|
||||
@@ -2342,7 +2342,7 @@ private:
|
||||
// The vote is not added to the slots
|
||||
ammAlice.vote(carol, 1'000);
|
||||
auto const info = ammAlice.ammRpcInfo()[jss::amm][jss::vote_slots];
|
||||
for (std::uint32_t i = 0; i < info.size(); ++i)
|
||||
for (std::uint16_t i = 0; i < info.size(); ++i)
|
||||
BEAST_EXPECT(info[i][jss::account] != carol.human());
|
||||
// But the slots are refreshed and the fee is changed
|
||||
BEAST_EXPECT(ammAlice.expectTradingFee(82));
|
||||
|
||||
@@ -262,7 +262,7 @@ public:
|
||||
if (has(SB::sameAccIss))
|
||||
return acc;
|
||||
if (has(SB::existingIss) && existingIss)
|
||||
return existingIss;
|
||||
return *existingIss;
|
||||
return issF().id();
|
||||
}();
|
||||
auto const cur = [&]() -> std::optional<Currency> {
|
||||
@@ -271,7 +271,7 @@ public:
|
||||
if (has(SB::xrp))
|
||||
return xrpCurrency();
|
||||
if (has(SB::existingCur) && existingCur)
|
||||
return existingCur;
|
||||
return *existingCur;
|
||||
return currencyF();
|
||||
}();
|
||||
if (!has(SB::boundary))
|
||||
|
||||
@@ -297,7 +297,7 @@ private:
|
||||
auto const localSigningPublic =
|
||||
parseBase58<PublicKey>(TokenType::NodePublic, cfgKeys.front());
|
||||
|
||||
BEAST_EXPECT(trustedKeys->load(localSigningPublic, cfgKeys, emptyCfgPublishers));
|
||||
BEAST_EXPECT(trustedKeys->load(*localSigningPublic, cfgKeys, emptyCfgPublishers));
|
||||
|
||||
BEAST_EXPECT(trustedKeys->localPublicKey() == localSigningPublic);
|
||||
BEAST_EXPECT(trustedKeys->listed(*localSigningPublic));
|
||||
|
||||
@@ -1280,7 +1280,7 @@ r.ripple.com:51235
|
||||
for (auto const& t : tests)
|
||||
{
|
||||
Section s;
|
||||
s.append(std::string(t.line));
|
||||
s.append(t.line.data());
|
||||
BEAST_EXPECT(s.had_trailing_comments() == t.had_comment);
|
||||
if (t.field.empty())
|
||||
{
|
||||
@@ -1289,7 +1289,7 @@ r.ripple.com:51235
|
||||
else
|
||||
{
|
||||
std::string field;
|
||||
BEAST_EXPECTS(set(field, std::string(t.field), s), t.line);
|
||||
BEAST_EXPECTS(set(field, t.field.data(), s), t.line);
|
||||
BEAST_EXPECTS(field == t.expect, t.line);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -502,12 +502,11 @@ public:
|
||||
Json::Value params;
|
||||
params[jss::account] = account.human();
|
||||
auto const info = env.rpc("json", "account_info", to_string(params));
|
||||
auto const name = std::string(fName);
|
||||
|
||||
std::optional<bool> res;
|
||||
if (info[jss::result][jss::status] == "success" &&
|
||||
info[jss::result][jss::account_flags].isMember(name))
|
||||
res.emplace(info[jss::result][jss::account_flags][name].asBool());
|
||||
info[jss::result][jss::account_flags].isMember(fName.data()))
|
||||
res.emplace(info[jss::result][jss::account_flags][fName.data()].asBool());
|
||||
|
||||
return res;
|
||||
};
|
||||
|
||||
@@ -129,11 +129,7 @@ ValidatorSite::load(
|
||||
{
|
||||
try
|
||||
{
|
||||
// This is not super efficient, but it doesn't happen often.
|
||||
bool found = std::ranges::any_of(
|
||||
sites_, [&uri](auto const& site) { return site.loadedResource->uri == uri; });
|
||||
if (!found)
|
||||
sites_.emplace_back(uri);
|
||||
sites_.emplace_back(uri);
|
||||
}
|
||||
catch (std::exception const& e)
|
||||
{
|
||||
@@ -194,16 +190,6 @@ ValidatorSite::setTimer(
|
||||
std::lock_guard<std::mutex> const& site_lock,
|
||||
std::lock_guard<std::mutex> const& state_lock)
|
||||
{
|
||||
if (!sites_.empty() && //
|
||||
std::ranges::all_of(
|
||||
sites_, [](auto const& site) { return site.lastRefreshStatus.has_value(); }))
|
||||
{
|
||||
// If all of the sites have been handled at least once (including
|
||||
// errors and timeouts), call missingSite, which will load the cache
|
||||
// files for any lists that are still unavailable.
|
||||
missingSite(site_lock);
|
||||
}
|
||||
|
||||
auto next = std::min_element(sites_.begin(), sites_.end(), [](Site const& a, Site const& b) {
|
||||
return a.nextRefresh < b.nextRefresh;
|
||||
});
|
||||
@@ -313,15 +299,12 @@ ValidatorSite::onRequestTimeout(std::size_t siteIdx, error_code const& ec)
|
||||
// processes a network error. Usually, this function runs first,
|
||||
// but on extremely rare occasions, the response handler can run
|
||||
// first, which will leave activeResource empty.
|
||||
auto& site = sites_[siteIdx];
|
||||
auto const& site = sites_[siteIdx];
|
||||
if (site.activeResource)
|
||||
JLOG(j_.warn()) << "Request for " << site.activeResource->uri << " took too long";
|
||||
else
|
||||
JLOG(j_.error()) << "Request took too long, but a response has "
|
||||
"already been processed";
|
||||
if (!site.lastRefreshStatus)
|
||||
site.lastRefreshStatus.emplace(
|
||||
Site::Status{clock_type::now(), ListDisposition::invalid, "timeout"});
|
||||
}
|
||||
|
||||
std::lock_guard lock_state{state_mutex_};
|
||||
|
||||
@@ -825,7 +825,7 @@ OverlayImpl::processValidatorList(http_request_type const& req, Handoff& handoff
|
||||
// return the most recent validator list for that key.
|
||||
constexpr std::string_view prefix("/vl/");
|
||||
|
||||
if (!req.target().starts_with(prefix) || !setup_.vlEnabled)
|
||||
if (!req.target().starts_with(prefix.data()) || !setup_.vlEnabled)
|
||||
return false;
|
||||
|
||||
std::uint32_t version = 1;
|
||||
|
||||
@@ -34,7 +34,7 @@ getDeliveredAmount(
|
||||
if (auto const& deliveredAmount = transactionMeta.getDeliveredAmount();
|
||||
deliveredAmount.has_value())
|
||||
{
|
||||
return deliveredAmount;
|
||||
return *deliveredAmount;
|
||||
}
|
||||
|
||||
if (serializedTx->isFieldPresent(sfAmount))
|
||||
|
||||
@@ -126,7 +126,7 @@ autofillTx(Json::Value& tx_json, RPC::JsonContext& context)
|
||||
}
|
||||
|
||||
if (auto error = autofillSignature(tx_json))
|
||||
return error;
|
||||
return *error;
|
||||
|
||||
if (!tx_json.isMember(jss::Sequence))
|
||||
{
|
||||
|
||||
Reference in New Issue
Block a user