Merge branch 'pratik/otel-phase9-metric-gap-fill' into pratik/otel-phase10-workload-validation

2026-08-22 14:50:54 +00:00 · 2026-08-20 12:15:09 +01:00
parent 3035d9fc79 5ce2bad4a9
commit 09fdcd2c25
464 changed files with 27964 additions and 14307 deletions
--- a/docs/NodeStoreRefactoringCaseStudy.pdf
+++ b/docs/NodeStoreRefactoringCaseStudy.pdf
--- a/docs/build/environment.md
+++ b/docs/build/environment.md
@@ -6,22 +6,55 @@ This document explains how to set one up.

 ## Tested compiler versions

-`xrpld` is built in the **C++23** dialect by default.
-Make sure your toolchain is recent enough — the compiler versions currently tested in CI are:
+`xrpld` is built in the **C++23** dialect by default, so your toolchain has to
+support it — see [compiler support for C++23][cpp23-support].
+The versions currently tested in CI are:

-| Compiler    | Version |
-| ----------- | ------- |
-| GCC         | 15.2    |
-| Clang       | 22      |
-| Apple Clang | 17      |
-| MSVC        | 19.44   |
+| Compiler    | Version            |
+| ----------- | ------------------ |
+| GCC         | 15.2               |
+| Clang       | 22                 |
+| Apple Clang | 21                 |
+| MSVC        | Visual Studio 2026 |

 LLVM tools (`clang-tidy` and `clang-format`) are also pinned to version 22.

+### Older compilers
+
 Older compilers may fail to build the latest `develop` code: the codebase now
 relies on C++23 features and has been adjusted for `clang-tidy`.
 If the latest code doesn't build for you, update your build toolchain first.

+If updating isn't an option for you, we do accept pull requests that fix builds
+on older compilers, as long as the change is small and doesn't make the code
+harder to read. What we can't promise is that older compilers will keep working:
+only the versions in the table above are tested in CI, and we won't hold back
+the use of C++23 features or add invasive workarounds to keep an untested
+compiler building. Treat support for anything outside the table as best-effort.
+
+## Required tools
+
+Besides a compiler, building `xrpld` requires:
+
+| Tool                                        | Minimum version |
+| ------------------------------------------- | --------------- |
+| [Git](https://git-scm.com/downloads)        | any recent      |
+| [Python](https://www.python.org/downloads/) | 3.11            |
+| [Conan](https://conan.io/downloads.html)    | 2.17            |
+| [CMake](https://cmake.org/download/)        | 3.16            |
+
+On Linux and macOS, the [Nix development shell](./nix.md) provides all of them
+(see below). On Windows they have to be installed manually.
+
+Building with `-Drust=ON` additionally requires a Rust toolchain, see
+[Rust](#rust). A default build does not, so it is not in the table above.
+
+Once they are in place, verify that everything is installed and runnable with:
+
+```bash
+./bin/check-tools.sh
+```
+
 ## Linux and macOS

 The **recommended way** to get a development environment on Linux and macOS is
@@ -39,20 +72,15 @@ Clang. If you instead opt to use your system-wide Apple Clang (via
 below).

 See [Using the Nix development shell](./nix.md) for installation and usage
-details, including how to select a different compiler.
-
-> [!NOTE]
-> Using Nix is not mandatory. Any custom environment (Homebrew packages or
-> anything else) will continue to work, but then it is up to you to keep it in
-> sync with the environment used in CI. Nix unifies the development environment
-> for everyone and synchronizes updates, which is why we recommend it.
+details, including how to select a different compiler and why we recommend Nix
+over a hand-maintained environment.

 ### macOS: managing the Apple Clang version

 If you use your system-wide Apple Clang on macOS (via `nix develop .#apple-clang`),
 the compiler version is whatever your installed Xcode (or Command Line Tools)
 provides. The following command should return a version greater than or equal to
-the [minimum required](#tested-compiler-versions):
+the [tested one](#tested-compiler-versions):

 ```bash
 clang --version
@@ -89,23 +117,42 @@ building xrpld. You may want to install and pin a specific version of Xcode:
 Nix is not available on Windows, so the required tools have to be installed
 manually:

- [Visual Studio 2022](https://visualstudio.microsoft.com/) with the
+- [Visual Studio 2026](https://visualstudio.microsoft.com/) with the
  **"Desktop development with C++"** workload — this provides MSVC and the
-  "x64 Native Tools Command Prompt".
+  "x64 Native Tools Command Prompt". CI configures CMake with the
+  `Visual Studio 18 2026` generator.
 - [Git for Windows](https://git-scm.com/download/win)
- [Python 3.11](https://www.python.org/downloads/), or higher
- [Conan 2.17](https://conan.io/downloads.html), or higher
- [CMake 3.22](https://cmake.org/download/), or higher
+- Python, Conan, and CMake, at the versions listed in
+  [Required tools](#required-tools).
+- a [Rust toolchain](https://rustup.rs) — only needed to build with
+  `-Drust=ON`, see [Rust](#rust)

-> [!NOTE]
-> Windows is used for development only and is not recommended for production.
+## Rust
+
+The repository contains a Rust workspace in [`crates/`](../../crates), whose
+crates are exposed to C++ through [cxx](https://cxx.rs) bindings. It is **not**
+part of a default build: the CMake `rust` option is OFF by default, and with it
+off no Rust toolchain is needed. It is only required when configuring with
+`-Drust=ON` (which is what CI does), see [Options](../../BUILD.md#options).
+
+The toolchain (`cargo`, `rustc`) is pinned to the channel in
+[`rust-toolchain.toml`](../../rust-toolchain.toml) at the repository root. If
+you install Rust with [rustup](https://rustup.rs), that file is picked up
+automatically, and `cargo`/`rustc` in the repository will use the pinned
+version.
+
+Everything else the Rust build needs on the CMake side comes from Conan along
+with the rest of the dependencies, so there is nothing further to install.

 ## Clang-tidy

 `clang-tidy` is required to run static analysis checks locally (see
 [CONTRIBUTING.md](../../CONTRIBUTING.md)). It is not required to build the
-project. This project currently uses `clang-tidy` version 22.
+project. The version this project uses is listed in
+[Tested compiler versions](#tested-compiler-versions).

-On Linux and macOS, the [Nix development shell](./nix.md) provides `clang-tidy`
-22 out of the box — run it via `run-clang-tidy`. No separate installation is
-needed.
+On Linux and macOS, the [Nix development shell](./nix.md) provides that exact
+version out of the box — run it via `run-clang-tidy`. No separate installation
+is needed.
+
+[cpp23-support]: https://en.cppreference.com/w/cpp/compiler_support/23
--- a/docs/build/nix.md
+++ b/docs/build/nix.md
@@ -7,7 +7,7 @@ This guide explains how to use Nix to set up a reproducible development environm
 ## Benefits of Using Nix

 - **Reproducible environment**: Everyone gets the same versions of tools and compilers
- **Matches CI**: The Linux CI runs in Docker images built from this exact Nix environment
+- **Matches CI**: The Linux CI runs in Docker images built from this exact Nix environment, and CI builds some macOS configurations in it as well
 - **No system pollution**: Dependencies are isolated and don't affect your system packages
 - **Consistent compilers**: The GCC and Clang shells use the same versions as CI
 - **Quick setup**: Get started with a single command
@@ -68,7 +68,7 @@ A compiler can be chosen by providing its name with the `.#` prefix, e.g. `nix d

 On Linux, `.#gcc` and `.#clang` provide the exact toolchain CI uses:
 the compiler (pinned in [`nix/packages.nix`](../../nix/packages.nix))
-rebuilt against the pinned custom glibc (see [`nix/compilers.nix`](../../nix/compilers.nix)).
+rebuilt against the pinned custom glibc (see [`nix/linux.nix`](../../nix/linux.nix)).
 Building that toolchain the first time is slow unless it is fetched from a Nix binary cache.
 If you don't need the custom glibc, the Linux-only `.#gcc-plain` and `.#clang-plain`
 give you the stock nixpkgs compilers of the same versions.
@@ -120,7 +120,7 @@ nix develop -c "$SHELL"
 >
 > If it doesn't, either adjust your shell configuration so it doesn't override `$PATH`, or use [direnv](#automatic-activation-with-direnv) (below), which loads the environment _after_ your shell config and so takes precedence regardless of the shell you use.

-## Building xrpld with Nix
+## Building xrpld in the Nix shell

 Once inside the Nix development shell, follow the standard [build instructions](../../BUILD.md#steps). The Nix shell provides all necessary tools (CMake, Ninja, Conan, etc.).

@@ -128,6 +128,100 @@ Coverage builds (`-Dcoverage=ON`) work in the `gcc` shell (and `gcc-plain` on Li
 each ships a `gcov` matching its compiler, since Nix's cc-wrapper does not expose one.
 The `clang` shells do not include `llvm-cov`, so use a `gcc` shell for coverage.

+Builds of the Rust crates (`-Drust=ON`) also work out of the box: every shell
+provides the Rust toolchain pinned in
+[`rust-toolchain.toml`](../../rust-toolchain.toml) (see
+[Rust](./environment.md#rust)), plus the `cargo-audit`, `cargo-llvm-cov` and
+`cargo-nextest` plugins.
+
+## Conan configuration
+
+The shell runs [`conan/init.sh`](../../conan/init.sh) on entry, so
+[Set Up Conan](../../BUILD.md#set-up-conan) is already done for you. It installs
+into the shell's own Conan home: `CONAN_HOME=~/.conan2-nix`.
+
+### Prebuilt packages
+
+On **Linux**, the binaries on the `xrplf` remote are built in this same Nix
+environment — CI runs in Docker images that bundle the dev shell's toolchain (see
+[`nix/docker`](../../nix/docker)) — so `.#gcc` and `.#clang` can reuse them. The
+`-plain` shells do not match that toolchain's glibc, so binaries from the remote
+are not a reliable match there.
+
+On **macOS**, CI also builds in this Nix environment, in Debug and Release (the
+`macos-arm64-*-nix` configurations — Debug because the profile defaults to it).
+The Nix build resolves to `compiler=clang`, so it gets its own package IDs,
+separate from the Apple Clang ones. The
+[dependency upload](../../.github/workflows/upload-conan-deps.yml) publishes them
+on pushes to `develop` and on manual runs — its nightly run rebuilds everything
+from source but uploads nothing — so once a set has been published `nix develop`
+can reuse it instead of compiling every dependency locally. These configurations
+run outside the reduced pull-request matrix, so label a PR `Full CI build` when it
+touches `flake.lock` or `nix/`.
+
+To compile everything from source, add `--build '*'` to the `conan install`
+command.
+
+### Why the nixpkgs revision is not part of the package ID
+
+A Conan package ID records the compiler and its major version, but nothing about
+the nixpkgs revision the toolchain came from — and `flake.lock` moves far more
+often than the toolchain meaningfully changes, so folding it in would rebuild
+every dependency on every bump for nothing.
+
+That is safe as long as no cached artifact resolves a `/nix/store` path at run
+time, because store paths change on every update and the old ones disappear with
+`nix-collect-garbage`. With the `clang` toolchain macOS CI and the dev shell use,
+they do not: it links against `/usr/lib/libc++` and `/usr/lib/libSystem`, and
+store paths reach the `.a` files only through debug info, which nothing resolves
+at link or run time.
+
+> [!WARNING]
+> This does not hold for `nix develop .#gcc` on macOS. There is no system
+> libstdc++, so GCC links its own from the store and every binary keeps a
+> `/nix/store` reference. That shell is fine for tooling, but it is not a build
+> configuration CI covers, and no dependency binaries are published for it.
+
+This is checked rather than assumed.
+[`bin/check-nix-store-refs.sh`](../../bin/check-nix-store-refs.sh) takes one file
+or directory and fails if a binary under it resolves a store path at run time.
+CI runs it over the build output and the Conan cache, and again in the upload job
+before anything is published. You can run it yourself:
+
+```bash
+bin/check-nix-store-refs.sh build
+bin/check-nix-store-refs.sh ~/.conan2-nix
+```
+
+It works on Linux too, but asserts something narrower there: the toolchain always
+writes the store into `PT_INTERP` and `RUNPATH`, and CI builds inside an image
+whose store is fixed for its lifetime, so that is fine. Only the binaries
+[`PatchNixBinary.cmake`](../../cmake/PatchNixBinary.cmake) retargets to the
+system loader have to be clean, and those are what CI checks:
+
+```bash
+bin/check-nix-store-refs.sh build/xrpld
+```
+
+### The libresolv stub
+
+This is not hypothetical: `xrpld` used to be caught by it. The c-ares package
+tells the linker to pass `-lresolv`, and nixpkgs keeps `libresolv` out of the
+macOS SDK and ships it as an ordinary store dylib — so every Nix-built `xrpld`
+recorded a `/nix/store/…-libresolv-93/lib/libresolv.9.dylib` load command and
+stopped running once that path was collected. Nothing in the link uses a single
+symbol from it.
+
+Both environments now put a stub on the linker search path
+(`libresolvSystemStub` in [`nix/darwin.nix`](../../nix/darwin.nix)): the
+same library with its install name set to `/usr/lib/libresolv.9.dylib`, which is
+exactly the load command the Apple Clang build records.
+
+Package IDs did not change, so Conan keeps serving anything built before the
+stub landed. If a binary fails to start with `Library not loaded: /nix/store/…`,
+see [that entry](./nix_troubleshooting.md#library-not-loaded-nixstore-from-a-binary-that-used-to-work)
+in the troubleshooting guide.
+
 ## Automatic Activation with direnv

 [direnv](https://direnv.net/) or [nix-direnv](https://github.com/nix-community/nix-direnv) can automatically activate the Nix development shell when you enter the repository directory.
@@ -142,14 +236,6 @@ The repository already ships an `.envrc` at its root that activates the Nix flak
 > [!NOTE]
 > direnv only caches the `.direnv` directory (already listed in `.gitignore`); no other repository files are affected.

-## Conan and Prebuilt Packages
-
-Please note that there is no guarantee that binaries from conan cache will work when using nix. If you encounter any errors, please use `--build '*'` to force conan to compile everything from source:
-
-```bash
-conan install .. --output-folder . --build '*' --settings build_type=Release
-```
-
 ## Updating `flake.lock` file

 To update `flake.lock` to the latest revision use `nix flake update` command.
--- a/docs/build/nix_troubleshooting.md
+++ b/docs/build/nix_troubleshooting.md
@@ -131,3 +131,91 @@ once it picks up that rebuild, then re-run the `grep libgit2` check above to
 confirm it reports `1.9.4` or newer.

 Until then, prefer the workarounds above.
+
+## `wint_t` / `uint32_t` errors from the Nix libc++ headers
+
+A build that mixes the Nix toolchain with the system SDK fails in libc++ itself,
+with errors that look nothing like your code:
+
+```
+/nix/store/...-libcxx-.../include/c++/v1/cwchar:136:9: error: target of using declaration conflicts with declaration already in scope
+  136 | using ::wint_t _LIBCPP_USING_IF_EXISTS;
+/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include/sys/_types/_wint_t.h:32:25: note: target of using declaration
+...
+error: use of undeclared identifier 'UINT32_C'
+```
+
+The give-away is the second path: Nix's libc++ headers are being combined with
+the **Xcode Command Line Tools** SDK instead of the Nix one.
+
+### Why it happens
+
+`SDKROOT` and `DEVELOPER_DIR` are what point the toolchain at the Nix SDK, and
+they are not baked into the compiler — a dev shell gets them from the
+`apple-sdk` setup hook. CMake, finding neither, asks `xcrun`, which answers with
+the system SDK. Nix's `libc++` and Apple's headers then declare the same types
+twice.
+
+### Fix
+
+Run the build from inside the dev shell (`nix develop`), or from an environment
+that exports both variables. To confirm which SDK a configured build is using:
+
+```bash
+grep -o '\-isysroot [^ ]*' build/compile_commands.json | sort -u
+```
+
+It should print a `/nix/store/...-apple-sdk-*` path. If it prints
+`/Library/Developer/CommandLineTools/...`, re-configure from within the shell —
+CMake caches the sysroot, so an existing `build/` directory keeps the wrong one.
+
+## `Library not loaded: /nix/store/…` from a binary that used to work
+
+A binary stops starting after a `nix flake update`, or after
+`nix-collect-garbage` removes the paths the previous toolchain used:
+
+```
+dyld[57271]: Library not loaded: /nix/store/…-libresolv-93/lib/libresolv.9.dylib
+```
+
+[`bin/check-nix-store-refs.sh`](../../bin/check-nix-store-refs.sh) finds the same
+thing without having to run anything, and names the file:
+
+```
+$ bin/check-nix-store-refs.sh ~/.conan2-nix
+::error file=/Users/you/.conan2-nix/p/b/c-area24ded30c388c/p/bin/adig::references the Nix store at run time
+/Users/you/.conan2-nix/p/b/c-area24ded30c388c/p/bin/adig
+    /nix/store/p4lp3xq4imd1qzqh08x8vcq2zfhi7rca-libresolv-93/lib/libresolv.9.dylib
+/Users/you/.conan2-nix: checked 135, skipped 2495, 1 with Nix store references.
+```
+
+Conan's cache folders are named after a truncated package name plus a hash, so
+ask Conan which package the offending one belongs to — pass the folder holding
+the hash, not the file itself:
+
+```
+$ conan cache ref ~/.conan2-nix/p/b/c-area24ded30c388c
+c-ares/1.34.6#545240bb1c40e2cacd4362d6b8967650:dab5992496abe6d219defb7986ecbf367615a5e5#…
+```
+
+### Why it happens
+
+The binary records a store path that no longer exists. Nothing we build should:
+see [Prebuilt packages](./nix.md#prebuilt-packages) for why, and
+`libresolvSystemStub` in [`nix/darwin.nix`](../../nix/darwin.nix) for the one
+dependency that needed help to comply.
+
+A Conan package ID does not encode the nixpkgs revision, so a package built
+before that stub existed stays in your local cache and keeps being reused. The
+dev shell is also what tends to produce one: it is a slightly _less_ isolated
+build environment than CI's, because `mkShell` puts every tool's headers and
+libraries on the compiler's search path — which is how c-ares found the Nix
+`libresolv` in the first place.
+
+### Fix
+
+Drop that package and let Conan refetch or rebuild it:
+
+```bash
+conan remove 'c-ares/*'
+```
--- a/docs/install-legacy.md
+++ b/docs/install-legacy.md
@@ -1,3 +1,10 @@
+# Installing xrpld 3.3.0 and earlier
+
+> [!IMPORTANT]
+> These instructions apply to xrpld 3.3.0 and earlier, published to
+> repos.ripple.com.
+> For later releases see [install.md](./install.md).
+
 This document contains instructions for installing xrpld.
 The APT package manager is common on Debian-based Linux distributions like
 Ubuntu,
@@ -52,7 +59,7 @@ The default [prefix][1] is typically `/usr/local` on Linux and macOS and

 5.  Add the appropriate XRPL repository for your operating system version:

-        echo "deb [signed-by=/usr/local/share/keyrings/ripple-key.gpg] https://repos.ripple.com/repos/xrpld-deb focal stable" | \
+        echo "deb [signed-by=/usr/local/share/keyrings/ripple-key.gpg] https://repos.ripple.com/repos/rippled-deb focal stable" | \
            sudo tee -a /etc/apt/sources.list.d/ripple.list

    The above example is appropriate for **Ubuntu 20.04 Focal Fossa**. For other operating systems, replace the word `focal` with one of the following:
@@ -106,8 +113,8 @@ The default [prefix][1] is typically `/usr/local` on Linux and macOS and
        enabled=1
        gpgcheck=0
        repo_gpgcheck=1
-        baseurl=https://repos.ripple.com/repos/xrpld-rpm/stable/
-        gpgkey=https://repos.ripple.com/repos/xrpld-rpm/stable/repodata/repomd.xml.key
+        baseurl=https://repos.ripple.com/repos/rippled-rpm/stable/
+        gpgkey=https://repos.ripple.com/repos/rippled-rpm/stable/repodata/repomd.xml.key
        REPOFILE

    _Unstable_
@@ -118,8 +125,8 @@ The default [prefix][1] is typically `/usr/local` on Linux and macOS and
        enabled=1
        gpgcheck=0
        repo_gpgcheck=1
-        baseurl=https://repos.ripple.com/repos/xrpld-rpm/unstable/
-        gpgkey=https://repos.ripple.com/repos/xrpld-rpm/unstable/repodata/repomd.xml.key
+        baseurl=https://repos.ripple.com/repos/rippled-rpm/unstable/
+        gpgkey=https://repos.ripple.com/repos/rippled-rpm/unstable/repodata/repomd.xml.key
        REPOFILE

    _Nightly_
@@ -130,8 +137,8 @@ The default [prefix][1] is typically `/usr/local` on Linux and macOS and
        enabled=1
        gpgcheck=0
        repo_gpgcheck=1
-        baseurl=https://repos.ripple.com/repos/xrpld-rpm/nightly/
-        gpgkey=https://repos.ripple.com/repos/xrpld-rpm/nightly/repodata/repomd.xml.key
+        baseurl=https://repos.ripple.com/repos/rippled-rpm/nightly/
+        gpgkey=https://repos.ripple.com/repos/rippled-rpm/nightly/repodata/repomd.xml.key
        REPOFILE

 2.  Fetch the latest repo updates:
--- a/docs/install.md
+++ b/docs/install.md
@@ -0,0 +1,144 @@
+# Installing xrpld
+
+> [!NOTE]
+> These instructions apply to packages published from 2026-08-19 onwards.
+> For xrpld 3.3.0 and earlier see [install-legacy.md](./install-legacy.md).
+
+`xrpld` is published as DEB and RPM packages for 64-bit x86 Linux.
+Use APT on Debian-based distributions such as Debian and Ubuntu,
+and YUM on Red Hat-based distributions such as RHEL, AlmaLinux, and Rocky Linux.
+To build from source instead, see [BUILD.md](../BUILD.md).
+
+## Release channels
+
+Packages are published to four channels:
+
+- `stable` - the latest production release
+- `unstable` - release candidates
+- `experimental` - beta builds
+- `develop` - every push to the [`develop` branch](https://github.com/XRPLF/rippled/tree/develop)
+
+See [Publishing packages](../package/README.md#publishing-packages) for how channels are produced.
+
+The instructions below use `stable`.
+To follow another channel, replace `stable` with its name
+wherever it appears in the repository configuration.
+
+> [!WARNING]
+> Channels other than `stable` may be broken at any time.
+> Do not use them for production servers.
+
+## Install the xrpld package
+
+### With the APT package manager
+
+1.  Install utilities:
+
+    ```bash
+    sudo apt update -y
+    sudo apt install -y apt-transport-https ca-certificates curl gnupg
+    ```
+
+2.  Add the XRPL Foundation package-signing key to your list of trusted keys:
+
+    ```bash
+    sudo install -d -m 0755 /etc/apt/keyrings
+    sudo curl -fsS https://packages.xrplf.org/xrplf.asc -o /etc/apt/keyrings/xrplf.asc
+    ```
+
+3.  Check the fingerprint of the newly-added key:
+
+    ```bash
+    gpg --show-keys /etc/apt/keyrings/xrplf.asc
+    ```
+
+    The output should be:
+
+    ```text
+    pub   rsa4096 2026-08-18 [SC]
+          B655416741221F780FBCFBC9AA84D41A11D29FA9
+    uid                      XRPLF Packages <distribution@xrplf.org>
+    ```
+
+    In particular, make sure that the fingerprint matches.
+
+4.  Add the repository, using the channel you picked in [Release channels](#release-channels):
+
+    ```bash
+    echo "deb [signed-by=/etc/apt/keyrings/xrplf.asc] https://packages.xrplf.org/repository/deb-stable focal main" | \
+        sudo tee /etc/apt/sources.list.d/xrplf.list
+    ```
+
+5.  Fetch the repository:
+
+    ```bash
+    sudo apt -y update
+    ```
+
+6.  Install the `xrpld` software package:
+
+    ```bash
+    sudo apt -y install xrpld
+    ```
+
+### With the YUM package manager
+
+1.  Add the XRPL Foundation package-signing key:
+
+    ```bash
+    sudo rpm --import https://packages.xrplf.org/xrplf.asc
+    ```
+
+2.  Add the repository, using the channel you picked in [Release channels](#release-channels):
+
+    ```bash
+    cat << REPOFILE | sudo tee /etc/yum.repos.d/xrplf.repo
+    [xrplf-stable]
+    name=XRP Ledger Packages
+    enabled=1
+    baseurl=https://packages.xrplf.org/repository/rpm-stable/
+    gpgcheck=1
+    repo_gpgcheck=0
+    gpgkey=https://packages.xrplf.org/xrplf.asc
+    REPOFILE
+    ```
+
+    `gpgcheck=1` verifies each package against the key above.
+    `repo_gpgcheck` is off because the repository metadata is generated by the server and is not signed.
+
+3.  Install the `xrpld` package:
+
+    ```bash
+    sudo yum install -y xrpld
+    ```
+
+## The xrpld service
+
+Both package managers install a systemd unit and enable it, so `xrpld` starts on boot.
+Check whether it is already running:
+
+```bash
+systemctl status xrpld.service
+```
+
+The APT packages start it immediately as well; the YUM packages do not, so start it yourself:
+
+```bash
+sudo systemctl start xrpld.service
+```
+
+### Optional: binding to privileged ports
+
+To serve incoming API requests on port 80 or 443, grant the service the capability to bind them.
+You must also update the config file's port settings.
+
+```bash
+sudo install -d -m 0755 /etc/systemd/system/xrpld.service.d
+sudo tee /etc/systemd/system/xrpld.service.d/privileged-ports.conf >/dev/null <<'EOF'
+[Service]
+CapabilityBoundingSet=CAP_NET_BIND_SERVICE
+AmbientCapabilities=CAP_NET_BIND_SERVICE
+EOF
+sudo systemctl daemon-reload
+sudo systemctl restart xrpld.service
+```
--- a/docs/sample_chart.doc
+++ b/docs/sample_chart.doc
@@ -1,24 +0,0 @@
-/*!
-    \page somestatechart Example state diagram
-
-    \startuml SomeState "my state diagram"
-    scale 600 width
-
-    [*] -> State1
-    State1 --> State2 : Succeeded
-    State1 --> [*] : Aborted
-    State2 --> State3 : Succeeded
-    State2 --> [*] : Aborted
-    state State3 {
-      state "Accumulate Enough Data\nLong State Name" as long1
-      long1 : Just a test
-      [*] --> long1
-      long1 --> long1 : New Data
-      long1 --> ProcessData : Enough Data
-    }
-    State3 --> State3 : Failed
-    State3 --> [*] : Succeeded / Save Result
-    State3 --> [*] : Aborted
-
-    \enduml
-*/