From 0a1708dbfec5e00ef46bcfdbc4f5985f273738fc Mon Sep 17 00:00:00 2001 From: Mayukha Vadari Date: Tue, 8 Sep 2026 17:05:08 -0400 Subject: [PATCH] docs: Add subsystem AGENTS.md files for transactors, ledger helpers, and READMEs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Round 2 of PR-review mining: found two subsystem-specific, unrecorded conventions (pseudo-account auth/freeze exemption in vault/lending transactors; SLE-type assertion in ledger helpers) that warrant their own nested AGENTS.md rather than more root-level bullets. Also added thin AGENTS.md pointer files (with CLAUDE.md symlinks, matching the existing convention) for subsystems that already have a substantial README.md but no AGENTS.md — agent tooling auto-loads AGENTS.md when working in a directory but not README.md, so those conventions were otherwise invisible to an agent that didn't think to look. --- include/xrpl/consensus/AGENTS.md | 3 +++ include/xrpl/consensus/CLAUDE.md | 1 + include/xrpl/nodestore/AGENTS.md | 3 +++ include/xrpl/nodestore/CLAUDE.md | 1 + include/xrpl/shamap/AGENTS.md | 3 +++ include/xrpl/shamap/CLAUDE.md | 1 + src/libxrpl/ledger/helpers/AGENTS.md | 5 +++++ src/libxrpl/ledger/helpers/CLAUDE.md | 1 + src/libxrpl/tx/transactors/AGENTS.md | 7 +++++++ src/libxrpl/tx/transactors/CLAUDE.md | 1 + src/xrpld/app/consensus/AGENTS.md | 3 +++ src/xrpld/app/consensus/CLAUDE.md | 1 + src/xrpld/app/ledger/AGENTS.md | 3 +++ src/xrpld/app/ledger/CLAUDE.md | 1 + src/xrpld/overlay/AGENTS.md | 3 +++ src/xrpld/overlay/CLAUDE.md | 1 + src/xrpld/peerfinder/AGENTS.md | 3 +++ src/xrpld/peerfinder/CLAUDE.md | 1 + src/xrpld/rpc/AGENTS.md | 2 +- 19 files changed, 43 insertions(+), 1 deletion(-) create mode 100644 include/xrpl/consensus/AGENTS.md create mode 120000 include/xrpl/consensus/CLAUDE.md create mode 100644 include/xrpl/nodestore/AGENTS.md create mode 120000 include/xrpl/nodestore/CLAUDE.md create mode 100644 include/xrpl/shamap/AGENTS.md create mode 120000 include/xrpl/shamap/CLAUDE.md create mode 100644 src/libxrpl/ledger/helpers/AGENTS.md create mode 120000 src/libxrpl/ledger/helpers/CLAUDE.md create mode 100644 src/libxrpl/tx/transactors/AGENTS.md create mode 120000 src/libxrpl/tx/transactors/CLAUDE.md create mode 100644 src/xrpld/app/consensus/AGENTS.md create mode 120000 src/xrpld/app/consensus/CLAUDE.md create mode 100644 src/xrpld/app/ledger/AGENTS.md create mode 120000 src/xrpld/app/ledger/CLAUDE.md create mode 100644 src/xrpld/overlay/AGENTS.md create mode 120000 src/xrpld/overlay/CLAUDE.md create mode 100644 src/xrpld/peerfinder/AGENTS.md create mode 120000 src/xrpld/peerfinder/CLAUDE.md diff --git a/include/xrpl/consensus/AGENTS.md b/include/xrpl/consensus/AGENTS.md new file mode 100644 index 0000000000..bd7f082b18 --- /dev/null +++ b/include/xrpl/consensus/AGENTS.md @@ -0,0 +1,3 @@ +# AGENTS.md — consensus + +See the repo-level [AGENTS.md](../../../AGENTS.md) for general guidance. See [README.md](./README.md) for a short pointer, and [docs/consensus.md](../../../docs/consensus.md) for the full consensus design. diff --git a/include/xrpl/consensus/CLAUDE.md b/include/xrpl/consensus/CLAUDE.md new file mode 120000 index 0000000000..47dc3e3d86 --- /dev/null +++ b/include/xrpl/consensus/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/include/xrpl/nodestore/AGENTS.md b/include/xrpl/nodestore/AGENTS.md new file mode 100644 index 0000000000..61e3818c34 --- /dev/null +++ b/include/xrpl/nodestore/AGENTS.md @@ -0,0 +1,3 @@ +# AGENTS.md — nodestore + +See the repo-level [AGENTS.md](../../../AGENTS.md) for general guidance and [README.md](./README.md) for backend and benchmark design. diff --git a/include/xrpl/nodestore/CLAUDE.md b/include/xrpl/nodestore/CLAUDE.md new file mode 120000 index 0000000000..47dc3e3d86 --- /dev/null +++ b/include/xrpl/nodestore/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/include/xrpl/shamap/AGENTS.md b/include/xrpl/shamap/AGENTS.md new file mode 100644 index 0000000000..2acbb84fc1 --- /dev/null +++ b/include/xrpl/shamap/AGENTS.md @@ -0,0 +1,3 @@ +# AGENTS.md — shamap + +See the repo-level [AGENTS.md](../../../AGENTS.md) for general guidance and [README.md](./README.md) for the SHAMap design. diff --git a/include/xrpl/shamap/CLAUDE.md b/include/xrpl/shamap/CLAUDE.md new file mode 120000 index 0000000000..47dc3e3d86 --- /dev/null +++ b/include/xrpl/shamap/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/src/libxrpl/ledger/helpers/AGENTS.md b/src/libxrpl/ledger/helpers/AGENTS.md new file mode 100644 index 0000000000..decdcd22ae --- /dev/null +++ b/src/libxrpl/ledger/helpers/AGENTS.md @@ -0,0 +1,5 @@ +# AGENTS.md — ledger/helpers + +See the repo-level [AGENTS.md](../../../../AGENTS.md) for general guidance. + +A helper that takes an `SLE`/`std::shared_ptr` should `XRPL_ASSERT` that it's non-null and of the expected ledger-entry type at entry, and keep a real runtime check/error-return alongside the assert (asserts compile out in release builds). Don't invent a new error-handling idiom for this (e.g. `std::unexpected`) — return the existing `tec`/`ter`/`tef` code used elsewhere in the codebase. diff --git a/src/libxrpl/ledger/helpers/CLAUDE.md b/src/libxrpl/ledger/helpers/CLAUDE.md new file mode 120000 index 0000000000..47dc3e3d86 --- /dev/null +++ b/src/libxrpl/ledger/helpers/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/src/libxrpl/tx/transactors/AGENTS.md b/src/libxrpl/tx/transactors/AGENTS.md new file mode 100644 index 0000000000..82d92a3f10 --- /dev/null +++ b/src/libxrpl/tx/transactors/AGENTS.md @@ -0,0 +1,7 @@ +# AGENTS.md — transactors + +See [tx/AGENTS.md](../AGENTS.md) for amendment-gating conventions that apply to all transactors, and the repo-level [AGENTS.md](../../../../AGENTS.md) for general guidance. + +Pseudo-accounts (Vault, LoanBroker, AMM, ...) are exempt from `requireAuth` and freeze/deep-freeze checks as a class, not on a per-asset-type basis. Code that touches a pseudo-account (deposits, withdrawals, clawback, deletion, credential checks) must preserve that exemption rather than re-deriving it for each asset type. + +Prefer a single object-level invariant over duplicating the same delta/balance check in every transactor that touches an object — e.g. one invariant asserting a Vault's pseudo-account balance and `assetsAvailable` always move together, rather than repeating that check in `VaultDeposit`, `VaultWithdraw`, `VaultClawback`, `LoanSet`, etc. diff --git a/src/libxrpl/tx/transactors/CLAUDE.md b/src/libxrpl/tx/transactors/CLAUDE.md new file mode 120000 index 0000000000..47dc3e3d86 --- /dev/null +++ b/src/libxrpl/tx/transactors/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/src/xrpld/app/consensus/AGENTS.md b/src/xrpld/app/consensus/AGENTS.md new file mode 100644 index 0000000000..98e7de4f67 --- /dev/null +++ b/src/xrpld/app/consensus/AGENTS.md @@ -0,0 +1,3 @@ +# AGENTS.md — consensus + +See the repo-level [AGENTS.md](../../../../AGENTS.md) for general guidance. See [README.md](./README.md) for a short pointer, and [docs/consensus.md](../../../../docs/consensus.md) for the full consensus design. diff --git a/src/xrpld/app/consensus/CLAUDE.md b/src/xrpld/app/consensus/CLAUDE.md new file mode 120000 index 0000000000..47dc3e3d86 --- /dev/null +++ b/src/xrpld/app/consensus/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/src/xrpld/app/ledger/AGENTS.md b/src/xrpld/app/ledger/AGENTS.md new file mode 100644 index 0000000000..89d7e46573 --- /dev/null +++ b/src/xrpld/app/ledger/AGENTS.md @@ -0,0 +1,3 @@ +# AGENTS.md — ledger + +See the repo-level [AGENTS.md](../../../../AGENTS.md) for general guidance and [README.md](./README.md) for ledger lifecycle and fetch-pack design. diff --git a/src/xrpld/app/ledger/CLAUDE.md b/src/xrpld/app/ledger/CLAUDE.md new file mode 120000 index 0000000000..47dc3e3d86 --- /dev/null +++ b/src/xrpld/app/ledger/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/src/xrpld/overlay/AGENTS.md b/src/xrpld/overlay/AGENTS.md new file mode 100644 index 0000000000..65df22cf86 --- /dev/null +++ b/src/xrpld/overlay/AGENTS.md @@ -0,0 +1,3 @@ +# AGENTS.md — overlay + +See the repo-level [AGENTS.md](../../../AGENTS.md) for general guidance and [README.md](./README.md) for the peer-protocol handshake, clustering, gossip, and monitoring design. diff --git a/src/xrpld/overlay/CLAUDE.md b/src/xrpld/overlay/CLAUDE.md new file mode 120000 index 0000000000..47dc3e3d86 --- /dev/null +++ b/src/xrpld/overlay/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/src/xrpld/peerfinder/AGENTS.md b/src/xrpld/peerfinder/AGENTS.md new file mode 100644 index 0000000000..f7c5d443b0 --- /dev/null +++ b/src/xrpld/peerfinder/AGENTS.md @@ -0,0 +1,3 @@ +# AGENTS.md — peerfinder + +See the repo-level [AGENTS.md](../../../AGENTS.md) for general guidance and [README.md](./README.md) for the peer-discovery design. diff --git a/src/xrpld/peerfinder/CLAUDE.md b/src/xrpld/peerfinder/CLAUDE.md new file mode 120000 index 0000000000..47dc3e3d86 --- /dev/null +++ b/src/xrpld/peerfinder/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/src/xrpld/rpc/AGENTS.md b/src/xrpld/rpc/AGENTS.md index 1dc26800d5..01354ad2b6 100644 --- a/src/xrpld/rpc/AGENTS.md +++ b/src/xrpld/rpc/AGENTS.md @@ -1,5 +1,5 @@ # AGENTS.md — rpc -See the repo-level [AGENTS.md](../../../AGENTS.md) for general build/test/style guidance, including the [API Changelog](../../../AGENTS.md#api-changelog) rule. +See the repo-level [AGENTS.md](../../../AGENTS.md) for general build/test/style guidance, including the [API Changelog](../../../AGENTS.md#api-changelog) rule, and [README.md](./README.md) for the RPC subsystem design. A change to a public RPC method's behavior (new/changed/removed fields, parameters, or error conditions) is exactly the kind of API-visible change that rule covers — use `### Additions`, `### Deprecations`, etc. under `## Unreleased` as appropriate.