ci: Improve cache implementation (#2780)

Fixes #2413.

.clang-format

@@ -49,6 +49,7 @@ IndentFunctionDeclarationAfterType: false
 IndentWidth: 4
 IndentWrappedFunctionNames: false
 IndentRequiresClause: true
+InsertNewlineAtEOF: true
 RequiresClausePosition: OwnLine
 KeepEmptyLinesAtTheStartOfBlocks: false
 MaxEmptyLinesToKeep: 1

.cmake-format.yaml

@@ -54,7 +54,7 @@ format:
   _help_max_pargs_hwrap:
     - If a positional argument group contains more than this many
     - arguments, then force it to a vertical layout.
-  max_pargs_hwrap: 6
+  max_pargs_hwrap: 5
   _help_max_rows_cmdline:
     - If a cmdline positional group consumes more than this many
     - lines without nesting, then invalidate the layout (and nest)

.github/actions/build-clio/action.yml

@@ -0,0 +1,31 @@
+name: Build clio
+description: Build clio in build directory
+
+inputs:
+  targets:
+    description: Space-separated build target names
+    default: all
+  nproc_subtract:
+    description: The number of processors to subtract when calculating parallelism.
+    required: true
+    default: "0"
+
+runs:
+  using: composite
+  steps:
+    - name: Get number of processors
+      uses: XRPLF/actions/.github/actions/get-nproc@046b1620f6bfd6cd0985dc82c3df02786801fe0a
+      id: nproc
+      with:
+        subtract: ${{ inputs.nproc_subtract }}
+
+    - name: Build targets
+      shell: bash
+      env:
+        CMAKE_TARGETS: ${{ inputs.targets }}
+      run: |
+        cd build
+        cmake \
+          --build . \
+          --parallel "${{ steps.nproc.outputs.nproc }}" \
+          --target ${CMAKE_TARGETS}

.github/actions/build-docker-image/action.yml

@@ -34,25 +34,25 @@ runs:
   steps:
     - name: Login to DockerHub
       if: ${{ inputs.push_image == 'true' && inputs.dockerhub_repo != '' }}
-      uses: docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1 # v3.5.0
+      uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
       with:
         username: ${{ env.DOCKERHUB_USER }}
         password: ${{ env.DOCKERHUB_PW }}
 
     - name: Login to GitHub Container Registry
       if: ${{ inputs.push_image == 'true' }}
-      uses: docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1 # v3.5.0
+      uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
       with:
         registry: ghcr.io
         username: ${{ github.repository_owner }}
         password: ${{ env.GITHUB_TOKEN }}
 
-    - uses: docker/setup-qemu-action@29109295f81e9208d7d86ff1c6c12d2833863392 # v3.6.0
+    - uses: docker/setup-qemu-action@c7c53464625b32c7a7e944ae62b3e17d2b600130 # v3.7.0
       with:
         cache-image: false
     - uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3.11.1
 
-    - uses: docker/metadata-action@c1e51972afc2121e065aed6d45c65596fe445f3f # v5.8.0
+    - uses: docker/metadata-action@318604b99e75e41977312d83839a89be02ca4893 # v5.9.0
       id: meta
       with:
         images: ${{ inputs.images }}

.github/actions/build_clio/action.yml

@@ -1,29 +0,0 @@
-name: Build clio
-description: Build clio in build directory
-
-inputs:
-  targets:
-    description: Space-separated build target names
-    default: all
-  subtract_threads:
-    description: An option for the action get_number_of_threads. See get_number_of_threads
-    required: true
-    default: "0"
-
-runs:
-  using: composite
-  steps:
-    - name: Get number of threads
-      uses: ./.github/actions/get_number_of_threads
-      id: number_of_threads
-      with:
-        subtract_threads: ${{ inputs.subtract_threads }}
-
-    - name: Build targets
-      shell: bash
-      run: |
-        cd build
-        cmake \
-          --build . \
-          --parallel "${{ steps.number_of_threads.outputs.threads_number }}" \
-          --target ${{ inputs.targets }}

.github/actions/cache-key/action.yml

@@ -0,0 +1,36 @@
+name: Cache key
+description: Generate cache key for ccache
+
+inputs:
+  conan_profile:
+    description: Conan profile name
+    required: true
+  build_type:
+    description: Current build type (e.g. Release, Debug)
+    required: true
+    default: Release
+  code_coverage:
+    description: Whether code coverage is on
+    required: true
+    default: "false"
+
+outputs:
+  key:
+    description: Generated cache key for ccache
+    value: ${{ steps.key_without_commit.outputs.key }}-${{ steps.git_common_ancestor.outputs.commit }}
+  restore_keys:
+    description: Cache restore keys for fallback
+    value: ${{ steps.key_without_commit.outputs.key }}
+
+runs:
+  using: composite
+  steps:
+    - name: Find common commit
+      id: git_common_ancestor
+      uses: ./.github/actions/git-common-ancestor
+
+    - name: Set cache key without commit
+      id: key_without_commit
+      shell: bash
+      run: |
+        echo "key=clio-ccache-${{ runner.os }}-${{ inputs.build_type }}${{ inputs.code_coverage == 'true' && '-code_coverage' || '' }}-${{ inputs.conan_profile }}-develop" >> "${GITHUB_OUTPUT}"

.github/actions/cmake/action.yml

@@ -44,6 +44,7 @@ runs:
     - name: Run cmake
       shell: bash
       env:
+        BUILD_DIR: "${{ inputs.build_dir }}"
         BUILD_TYPE: "${{ inputs.build_type }}"
         SANITIZER_OPTION: |-
           ${{ endsWith(inputs.conan_profile, '.asan') && '-Dsan=address' ||
@@ -58,7 +59,7 @@ runs:
         PACKAGE: "${{ inputs.package == 'true' && 'ON' || 'OFF' }}"
       run: |
         cmake \
-          -B ${{inputs.build_dir}} \
+          -B "${BUILD_DIR}" \
           -S . \
           -G Ninja \
           -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake \

.github/actions/code-coverage/action.yml

@@ -24,7 +24,7 @@ runs:
           -j8 --exclude-throw-branches
 
     - name: Archive coverage report
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
       with:
         name: coverage-report.xml
         path: build/coverage_report.xml

.github/actions/conan/action.yml

@@ -28,11 +28,14 @@ runs:
     - name: Run conan
       shell: bash
       env:
+        BUILD_DIR: "${{ inputs.build_dir }}"
         CONAN_BUILD_OPTION: "${{ inputs.force_conan_source_build == 'true' && '*' || 'missing' }}"
+        BUILD_TYPE: "${{ inputs.build_type }}"
+        CONAN_PROFILE: "${{ inputs.conan_profile }}"
       run: |
         conan \
           install . \
-          -of build \
+          -of "${BUILD_DIR}" \
-          -b "$CONAN_BUILD_OPTION" \
+          -b "${CONAN_BUILD_OPTION}" \
-          -s "build_type=${{ inputs.build_type }}" \
+          -s "build_type=${BUILD_TYPE}" \
-          --profile:all "${{ inputs.conan_profile }}"
+          --profile:all "${CONAN_PROFILE}"

.github/actions/create-issue/action.yml

@@ -28,12 +28,17 @@ runs:
     - name: Create an issue
       id: create_issue
       shell: bash
+      env:
+        ISSUE_BODY: ${{ inputs.body }}
+        ISSUE_ASSIGNEES: ${{ inputs.assignees }}
+        ISSUE_LABELS: ${{ inputs.labels }}
+        ISSUE_TITLE: ${{ inputs.title }}
       run: |
-        echo -e '${{ inputs.body }}' > issue.md
+        echo -e "${ISSUE_BODY}" > issue.md
         gh issue create \
-          --assignee '${{ inputs.assignees }}' \
+          --assignee "${ISSUE_ASSIGNEES}" \
-          --label '${{ inputs.labels }}' \
+          --label "${ISSUE_LABELS}" \
-          --title '${{ inputs.title }}' \
+          --title "${ISSUE_TITLE}" \
           --body-file ./issue.md \
           > create_issue.log
         created_issue="$(sed 's|.*/||' create_issue.log)"

.github/actions/get_number_of_threads/action.yml

@@ -1,36 +0,0 @@
-name: Get number of threads
-description: Determines number of threads to use on macOS and Linux
-
-inputs:
-  subtract_threads:
-    description: How many threads to subtract from the calculated number
-    required: true
-    default: "0"
-outputs:
-  threads_number:
-    description: Number of threads to use
-    value: ${{ steps.number_of_threads_export.outputs.num }}
-
-runs:
-  using: composite
-  steps:
-    - name: Get number of threads on mac
-      id: mac_threads
-      if: ${{ runner.os == 'macOS' }}
-      shell: bash
-      run: echo "num=$(($(sysctl -n hw.logicalcpu) - 2))" >> $GITHUB_OUTPUT
-
-    - name: Get number of threads on Linux
-      id: linux_threads
-      if: ${{ runner.os == 'Linux' }}
-      shell: bash
-      run: echo "num=$(($(nproc) - 2))" >> $GITHUB_OUTPUT
-
-    - name: Shift and export number of threads
-      id: number_of_threads_export
-      shell: bash
-      run: |
-        num_of_threads="${{ steps.mac_threads.outputs.num || steps.linux_threads.outputs.num }}"
-        shift_by="${{ inputs.subtract_threads }}"
-        shifted="$((num_of_threads - shift_by))"
-        echo "num=$(( shifted > 1 ? shifted : 1 ))" >> $GITHUB_OUTPUT

.github/actions/restore_cache/action.yml

@@ -1,38 +0,0 @@
-name: Restore cache
-description: Find and restores ccache cache
-
-inputs:
-  conan_profile:
-    description: Conan profile name
-    required: true
-  ccache_dir:
-    description: Path to .ccache directory
-    required: true
-  build_type:
-    description: Current build type (e.g. Release, Debug)
-    required: true
-    default: Release
-  code_coverage:
-    description: Whether code coverage is on
-    required: true
-    default: "false"
-
-outputs:
-  ccache_cache_hit:
-    description: True if ccache cache has been downloaded
-    value: ${{ steps.ccache_cache.outputs.cache-hit }}
-
-runs:
-  using: composite
-  steps:
-    - name: Find common commit
-      id: git_common_ancestor
-      uses: ./.github/actions/git_common_ancestor
-
-    - name: Restore ccache cache
-      uses: actions/cache/restore@v4
-      id: ccache_cache
-      if: ${{ env.CCACHE_DISABLE != '1' }}
-      with:
-        path: ${{ inputs.ccache_dir }}
-        key: clio-ccache-${{ runner.os }}-${{ inputs.build_type }}${{ inputs.code_coverage == 'true' && '-code_coverage' || '' }}-${{ inputs.conan_profile }}-develop-${{ steps.git_common_ancestor.outputs.commit }}

.github/actions/save_cache/action.yml

@@ -1,38 +0,0 @@
-name: Save cache
-description: Save ccache cache for develop branch
-
-inputs:
-  conan_profile:
-    description: Conan profile name
-    required: true
-  ccache_dir:
-    description: Path to .ccache directory
-    required: true
-  build_type:
-    description: Current build type (e.g. Release, Debug)
-    required: true
-    default: Release
-  code_coverage:
-    description: Whether code coverage is on
-    required: true
-    default: "false"
-
-  ccache_cache_hit:
-    description: Whether ccache cache has been downloaded
-    required: true
-  ccache_cache_miss_rate:
-    description: How many ccache cache misses happened
-
-runs:
-  using: composite
-  steps:
-    - name: Find common commit
-      id: git_common_ancestor
-      uses: ./.github/actions/git_common_ancestor
-
-    - name: Save ccache cache
-      if: ${{ inputs.ccache_cache_hit != 'true' || inputs.ccache_cache_miss_rate == '100.0' }}
-      uses: actions/cache/save@v4
-      with:
-        path: ${{ inputs.ccache_dir }}
-        key: clio-ccache-${{ runner.os }}-${{ inputs.build_type }}${{ inputs.code_coverage == 'true' && '-code_coverage' || '' }}-${{ inputs.conan_profile }}-develop-${{ steps.git_common_ancestor.outputs.commit }}

.github/dependabot.yml

@@ -14,7 +14,7 @@ updates:
     target-branch: develop
 
   - package-ecosystem: github-actions
-    directory: .github/actions/build_clio/
+    directory: .github/actions/build-clio/
     schedule:
       interval: weekly
       day: monday
@@ -27,7 +27,7 @@ updates:
     target-branch: develop
 
   - package-ecosystem: github-actions
-    directory: .github/actions/build_docker_image/
+    directory: .github/actions/build-docker-image/
     schedule:
       interval: weekly
       day: monday
@@ -53,7 +53,7 @@ updates:
     target-branch: develop
 
   - package-ecosystem: github-actions
-    directory: .github/actions/code_coverage/
+    directory: .github/actions/code-coverage/
     schedule:
       interval: weekly
       day: monday
@@ -79,7 +79,7 @@ updates:
     target-branch: develop
 
   - package-ecosystem: github-actions
-    directory: .github/actions/create_issue/
+    directory: .github/actions/create-issue/
     schedule:
       interval: weekly
       day: monday
@@ -92,7 +92,7 @@ updates:
     target-branch: develop
 
   - package-ecosystem: github-actions
-    directory: .github/actions/get_number_of_threads/
+    directory: .github/actions/git-common-ancestor/
     schedule:
       interval: weekly
       day: monday
@@ -105,33 +105,7 @@ updates:
     target-branch: develop
 
   - package-ecosystem: github-actions
-    directory: .github/actions/git_common_ancestor/
+    directory: .github/actions/cache-key/
-    schedule:
-      interval: weekly
-      day: monday
-      time: "04:00"
-      timezone: Etc/GMT
-    reviewers:
-      - XRPLF/clio-dev-team
-    commit-message:
-      prefix: "ci: [DEPENDABOT] "
-    target-branch: develop
-
-  - package-ecosystem: github-actions
-    directory: .github/actions/restore_cache/
-    schedule:
-      interval: weekly
-      day: monday
-      time: "04:00"
-      timezone: Etc/GMT
-    reviewers:
-      - XRPLF/clio-dev-team
-    commit-message:
-      prefix: "ci: [DEPENDABOT] "
-    target-branch: develop
-
-  - package-ecosystem: github-actions
-    directory: .github/actions/save_cache/
     schedule:
       interval: weekly
       day: monday

.github/scripts/conan/apple-clang-17.profile

@@ -4,7 +4,7 @@ build_type=Release
 compiler=apple-clang
 compiler.cppstd=20
 compiler.libcxx=libc++
-compiler.version=17
+compiler.version=17.0
 os=Macos
 
 [conf]

.github/scripts/conan/generate_matrix.py

@@ -3,7 +3,9 @@ import itertools
 import json
 
 LINUX_OS = ["heavy", "heavy-arm64"]
-LINUX_CONTAINERS = ['{ "image": "ghcr.io/xrplf/clio-ci:384e79cd32f5f6c0ab9be3a1122ead41c5a7e67d" }']
+LINUX_CONTAINERS = [
+    '{ "image": "ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8" }'
+]
 LINUX_COMPILERS = ["gcc", "clang"]
 
 MACOS_OS = ["macos15"]

.github/scripts/execute-tests-under-sanitizer.sh

@@ -31,15 +31,16 @@ TESTS=$($TEST_BINARY --gtest_list_tests | awk '/^  / {print suite $1} !/^  / {su
 OUTPUT_DIR="./.sanitizer-report"
 mkdir -p "$OUTPUT_DIR"
 
+export TSAN_OPTIONS="die_after_fork=0"
+export MallocNanoZone='0' # for MacOSX
+
 for TEST in $TESTS; do
-  OUTPUT_FILE="$OUTPUT_DIR/${TEST//\//_}"
+  OUTPUT_FILE="$OUTPUT_DIR/${TEST//\//_}.log"
-  export TSAN_OPTIONS="log_path=\"$OUTPUT_FILE\" die_after_fork=0"
+  $TEST_BINARY --gtest_filter="$TEST" > "$OUTPUT_FILE" 2>&1
-  export ASAN_OPTIONS="log_path=\"$OUTPUT_FILE\""
-  export UBSAN_OPTIONS="log_path=\"$OUTPUT_FILE\""
-  export MallocNanoZone='0' # for MacOSX
-  $TEST_BINARY --gtest_filter="$TEST" > /dev/null 2>&1
 
   if [ $? -ne 0 ]; then
     echo "'$TEST' failed a sanitizer check."
+  else
+    rm "$OUTPUT_FILE"
   fi
 done

.github/workflows/build-clio-docker-image.yml

@@ -38,32 +38,37 @@ on:
         description: Whether to strip clio binary
         default: true
 
+defaults:
+  run:
+    shell: bash
+
 jobs:
   build_and_publish_image:
     name: Build and publish image
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
       - name: Download Clio binary from artifact
         if: ${{ inputs.artifact_name != null }}
-        uses: actions/download-artifact@v5
+        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
         with:
           name: ${{ inputs.artifact_name }}
           path: ./docker/clio/artifact/
 
       - name: Download Clio binary from url
         if: ${{ inputs.clio_server_binary_url != null }}
-        shell: bash
+        env:
+          BINARY_URL: ${{ inputs.clio_server_binary_url }}
+          BINARY_SHA256: ${{ inputs.binary_sha256 }}
         run: |
-          wget "${{inputs.clio_server_binary_url}}" -P ./docker/clio/artifact/
+          wget "${BINARY_URL}" -P ./docker/clio/artifact/
-          if [ "$(sha256sum ./docker/clio/clio_server | awk '{print $1}')" != "${{inputs.binary_sha256}}" ]; then
+          if [ "$(sha256sum ./docker/clio/clio_server | awk '{print $1}')" != "${BINARY_SHA256}" ]; then
             echo "Binary sha256 sum doesn't match"
             exit 1
           fi
       - name: Unpack binary
-        shell: bash
         run: |
           sudo apt update && sudo apt install -y tar unzip
           cd docker/clio/artifact
@@ -80,7 +85,6 @@ jobs:
 
       - name: Strip binary
         if: ${{ inputs.strip_binary }}
-        shell: bash
         run: strip ./docker/clio/clio_server
 
       - name: Set GHCR_REPO
@@ -89,7 +93,7 @@ jobs:
           echo "GHCR_REPO=$(echo ghcr.io/${{ github.repository_owner }} | tr '[:upper:]' '[:lower:]')" >> ${GITHUB_OUTPUT}
 
       - name: Build Docker image
-        uses: ./.github/actions/build_docker_image
+        uses: ./.github/actions/build-docker-image
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           DOCKERHUB_USER: ${{ secrets.DOCKERHUB_USER }}

.github/workflows/build.yml

@@ -8,14 +8,14 @@ on:
     paths:
       - .github/workflows/build.yml
 
-      - .github/workflows/build_and_test.yml
+      - .github/workflows/reusable-build-test.yml
-      - .github/workflows/build_impl.yml
+      - .github/workflows/reusable-build.yml
-      - .github/workflows/test_impl.yml
+      - .github/workflows/reusable-test.yml
-      - .github/workflows/upload_coverage_report.yml
+      - .github/workflows/reusable-upload-coverage-report.yml
 
       - ".github/actions/**"
-      - "!.github/actions/build_docker_image/**"
+      - "!.github/actions/build-docker-image/**"
-      - "!.github/actions/create_issue/**"
+      - "!.github/actions/create-issue/**"
 
       - CMakeLists.txt
       - conanfile.py
@@ -33,6 +33,10 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}-${{ github.ref == 'refs/heads/develop' && github.run_number || 'branch' }}
   cancel-in-progress: true
 
+defaults:
+  run:
+    shell: bash
+
 jobs:
   build-and-test:
     name: Build and Test
@@ -45,7 +49,7 @@ jobs:
         build_type: [Release, Debug]
         container:
           [
-            '{ "image": "ghcr.io/xrplf/clio-ci:384e79cd32f5f6c0ab9be3a1122ead41c5a7e67d" }',
+            '{ "image": "ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8" }',
           ]
         static: [true]
 
@@ -56,7 +60,7 @@ jobs:
             container: ""
             static: false
 
-    uses: ./.github/workflows/build_and_test.yml
+    uses: ./.github/workflows/reusable-build-test.yml
     with:
       runs_on: ${{ matrix.os }}
       container: ${{ matrix.container }}
@@ -72,14 +76,14 @@ jobs:
   code_coverage:
     name: Run Code Coverage
 
-    uses: ./.github/workflows/build_impl.yml
+    uses: ./.github/workflows/reusable-build.yml
     with:
       runs_on: heavy
-      container: '{ "image": "ghcr.io/xrplf/clio-ci:384e79cd32f5f6c0ab9be3a1122ead41c5a7e67d" }'
+      container: '{ "image": "ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8" }'
       conan_profile: gcc
       build_type: Debug
       download_ccache: true
-      upload_ccache: false
+      upload_ccache: true
       code_coverage: true
       static: true
       upload_clio_server: false
@@ -91,10 +95,10 @@ jobs:
   package:
     name: Build packages
 
-    uses: ./.github/workflows/build_impl.yml
+    uses: ./.github/workflows/reusable-build.yml
     with:
       runs_on: heavy
-      container: '{ "image": "ghcr.io/xrplf/clio-ci:384e79cd32f5f6c0ab9be3a1122ead41c5a7e67d" }'
+      container: '{ "image": "ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8" }'
       conan_profile: gcc
       build_type: Release
       download_ccache: true
@@ -111,17 +115,16 @@ jobs:
     needs: build-and-test
     runs-on: heavy
     container:
-      image: ghcr.io/xrplf/clio-ci:384e79cd32f5f6c0ab9be3a1122ead41c5a7e67d
+      image: ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
-      - uses: actions/download-artifact@v5
+      - uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
         with:
           name: clio_server_Linux_Release_gcc
 
       - name: Compare Config Description
-        shell: bash
         run: |
           repoConfigFile=docs/config-description.md
           configDescriptionFile=config_description_new.md

.github/workflows/check-libxrpl.yml

@@ -12,31 +12,33 @@ concurrency:
 env:
   CONAN_PROFILE: gcc
 
+defaults:
+  run:
+    shell: bash
+
 jobs:
   build:
     name: Build Clio / `libXRPL ${{ github.event.client_payload.version }}`
     runs-on: heavy
     container:
-      image: ghcr.io/xrplf/clio-ci:384e79cd32f5f6c0ab9be3a1122ead41c5a7e67d
+      image: ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 0
 
       - name: Prepare runner
-        uses: XRPLF/actions/.github/actions/prepare-runner@7951b682e5a2973b28b0719a72f01fc4b0d0c34f
+        uses: XRPLF/actions/.github/actions/prepare-runner@8abb0722cbff83a9a2dc7d06c473f7a4964b7382
         with:
           disable_ccache: true
 
       - name: Update libXRPL version requirement
-        shell: bash
         run: |
           sed -i.bak -E "s|'xrpl/[a-zA-Z0-9\\.\\-]+'|'xrpl/${{ github.event.client_payload.conan_ref }}'|g" conanfile.py
           rm -f conanfile.py.bak
 
       - name: Update conan lockfile
-        shell: bash
         run: |
           conan lock create . --profile:all ${{ env.CONAN_PROFILE }}
 
@@ -51,13 +53,13 @@ jobs:
           conan_profile: ${{ env.CONAN_PROFILE }}
 
       - name: Build Clio
-        uses: ./.github/actions/build_clio
+        uses: ./.github/actions/build-clio
 
       - name: Strip tests
         run: strip build/clio_tests
 
       - name: Upload clio_tests
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         with:
           name: clio_tests_check_libxrpl
           path: build/clio_tests
@@ -67,10 +69,10 @@ jobs:
     needs: build
     runs-on: heavy
     container:
-      image: ghcr.io/xrplf/clio-ci:384e79cd32f5f6c0ab9be3a1122ead41c5a7e67d
+      image: ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8
 
     steps:
-      - uses: actions/download-artifact@v5
+      - uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
         with:
           name: clio_tests_check_libxrpl
 
@@ -90,10 +92,10 @@ jobs:
       issues: write
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
       - name: Create an issue
-        uses: ./.github/actions/create_issue
+        uses: ./.github/actions/create-issue
         env:
           GH_TOKEN: ${{ github.token }}
         with:

.github/workflows/check-pr-title.yml

@@ -5,13 +5,26 @@ on:
     types: [opened, edited, reopened, synchronize]
     branches: [develop]
 
+defaults:
+  run:
+    shell: bash
+
 jobs:
   check_title:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: ytanikin/pr-conventional-commits@b72758283dcbee706975950e96bc4bf323a8d8c0 # v1.4.2
+      - uses: ytanikin/pr-conventional-commits@b72758283dcbee706975950e96bc4bf323a8d8c0 # 1.4.2
         with:
           task_types: '["build","feat","fix","docs","test","ci","style","refactor","perf","chore"]'
           add_label: false
           custom_labels: '{"build":"build", "feat":"enhancement", "fix":"bug", "docs":"documentation", "test":"testability", "ci":"ci", "style":"refactoring", "refactor":"refactoring", "perf":"performance", "chore":"tooling"}'
+
+      - name: Check if message starts with upper-case letter
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          if [[ ! "${PR_TITLE}" =~ ^[a-z]+:\ [\[A-Z] ]]; then
+            echo "Error: PR title must start with an upper-case letter."
+            exit 1
+          fi

.github/workflows/clang-tidy.yml

@@ -22,12 +22,16 @@ env:
   CONAN_PROFILE: clang
   LLVM_TOOLS_VERSION: 20
 
+defaults:
+  run:
+    shell: bash
+
 jobs:
   clang_tidy:
     if: github.event_name != 'push' || contains(github.event.head_commit.message, 'clang-tidy auto fixes')
     runs-on: heavy
     container:
-      image: ghcr.io/xrplf/clio-ci:384e79cd32f5f6c0ab9be3a1122ead41c5a7e67d
+      image: ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8
 
     permissions:
       contents: write
@@ -35,22 +39,15 @@ jobs:
       pull-requests: write
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 0
 
       - name: Prepare runner
-        uses: XRPLF/actions/.github/actions/prepare-runner@7951b682e5a2973b28b0719a72f01fc4b0d0c34f
+        uses: XRPLF/actions/.github/actions/prepare-runner@8abb0722cbff83a9a2dc7d06c473f7a4964b7382
         with:
           disable_ccache: true
 
-      - name: Restore cache
-        uses: ./.github/actions/restore_cache
-        id: restore_cache
-        with:
-          conan_profile: ${{ env.CONAN_PROFILE }}
-          ccache_dir: ${{ env.CCACHE_DIR }}
-
       - name: Run conan
         uses: ./.github/actions/conan
         with:
@@ -61,27 +58,24 @@ jobs:
         with:
           conan_profile: ${{ env.CONAN_PROFILE }}
 
-      - name: Get number of threads
+      - name: Get number of processors
-        uses: ./.github/actions/get_number_of_threads
+        uses: XRPLF/actions/.github/actions/get-nproc@046b1620f6bfd6cd0985dc82c3df02786801fe0a
-        id: number_of_threads
+        id: nproc
 
       - name: Run clang-tidy
         continue-on-error: true
-        shell: bash
         id: run_clang_tidy
         run: |
-          run-clang-tidy-${{ env.LLVM_TOOLS_VERSION }} -p build -j "${{ steps.number_of_threads.outputs.threads_number }}" -fix -quiet 1>output.txt
+          run-clang-tidy-${{ env.LLVM_TOOLS_VERSION }} -p build -j "${{ steps.nproc.outputs.nproc }}" -fix -quiet 1>output.txt
 
       - name: Fix local includes and clang-format style
         if: ${{ steps.run_clang_tidy.outcome != 'success' }}
-        shell: bash
         run: |
           pre-commit run --all-files fix-local-includes || true
           pre-commit run --all-files clang-format || true
 
       - name: Print issues found
         if: ${{ steps.run_clang_tidy.outcome != 'success' }}
-        shell: bash
         run: |
           sed -i '/error\||/!d' ./output.txt
           cat output.txt
@@ -90,7 +84,7 @@ jobs:
       - name: Create an issue
         if: ${{ steps.run_clang_tidy.outcome != 'success' && github.event_name != 'pull_request' }}
         id: create_issue
-        uses: ./.github/actions/create_issue
+        uses: ./.github/actions/create-issue
         env:
           GH_TOKEN: ${{ github.token }}
         with:
@@ -126,5 +120,4 @@ jobs:
 
       - name: Fail the job
         if: ${{ steps.run_clang_tidy.outcome != 'success' }}
-        shell: bash
         run: exit 1

.github/workflows/docs.yml

@@ -10,20 +10,24 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
+defaults:
+  run:
+    shell: bash
+
 jobs:
   build:
     runs-on: ubuntu-latest
     container:
-      image: ghcr.io/xrplf/clio-ci:384e79cd32f5f6c0ab9be3a1122ead41c5a7e67d
+      image: ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           lfs: true
 
       - name: Prepare runner
-        uses: XRPLF/actions/.github/actions/prepare-runner@7951b682e5a2973b28b0719a72f01fc4b0d0c34f
+        uses: XRPLF/actions/.github/actions/prepare-runner@8abb0722cbff83a9a2dc7d06c473f7a4964b7382
         with:
           disable_ccache: true
 
@@ -39,10 +43,10 @@ jobs:
         run: cmake --build . --target docs
 
       - name: Setup Pages
-        uses: actions/configure-pages@v5
+        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
 
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v4
+        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
         with:
           path: build_docs/html
           name: docs-develop
@@ -62,6 +66,6 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5
         with:
           artifact_name: docs-develop

.github/workflows/nightly.yml

@@ -8,14 +8,14 @@ on:
     paths:
       - .github/workflows/nightly.yml
 
-      - .github/workflows/release_impl.yml
+      - .github/workflows/reusable-release.yml
-      - .github/workflows/build_and_test.yml
+      - .github/workflows/reusable-build-test.yml
-      - .github/workflows/build_impl.yml
+      - .github/workflows/reusable-build.yml
-      - .github/workflows/test_impl.yml
+      - .github/workflows/reusable-test.yml
-      - .github/workflows/build_clio_docker_image.yml
+      - .github/workflows/build-clio-docker-image.yml
 
       - ".github/actions/**"
-      - "!.github/actions/code_coverage/**"
+      - "!.github/actions/code-coverage/**"
       - .github/scripts/prepare-release-artifacts.sh
 
 concurrency:
@@ -23,6 +23,10 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
+defaults:
+  run:
+    shell: bash
+
 jobs:
   build-and-test:
     name: Build and Test
@@ -39,19 +43,19 @@ jobs:
             conan_profile: gcc
             build_type: Release
             static: true
-            container: '{ "image": "ghcr.io/xrplf/clio-ci:384e79cd32f5f6c0ab9be3a1122ead41c5a7e67d" }'
+            container: '{ "image": "ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8" }'
           - os: heavy
             conan_profile: gcc
             build_type: Debug
             static: true
-            container: '{ "image": "ghcr.io/xrplf/clio-ci:384e79cd32f5f6c0ab9be3a1122ead41c5a7e67d" }'
+            container: '{ "image": "ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8" }'
           - os: heavy
             conan_profile: gcc.ubsan
             build_type: Release
             static: false
-            container: '{ "image": "ghcr.io/xrplf/clio-ci:384e79cd32f5f6c0ab9be3a1122ead41c5a7e67d" }'
+            container: '{ "image": "ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8" }'
 
-    uses: ./.github/workflows/build_and_test.yml
+    uses: ./.github/workflows/reusable-build-test.yml
     with:
       runs_on: ${{ matrix.os }}
       container: ${{ matrix.container }}
@@ -73,13 +77,13 @@ jobs:
         include:
           - os: heavy
             conan_profile: clang
-            container: '{ "image": "ghcr.io/xrplf/clio-ci:384e79cd32f5f6c0ab9be3a1122ead41c5a7e67d" }'
+            container: '{ "image": "ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8" }'
             static: true
           - os: macos15
             conan_profile: apple-clang
             container: ""
             static: false
-    uses: ./.github/workflows/build_impl.yml
+    uses: ./.github/workflows/reusable-build.yml
     with:
       runs_on: ${{ matrix.os }}
       container: ${{ matrix.container }}
@@ -93,23 +97,34 @@ jobs:
       targets: all
       analyze_build_time: true
 
+  get_date:
+    name: Get Date
+    runs-on: ubuntu-latest
+    outputs:
+      date: ${{ steps.get_date.outputs.date }}
+    steps:
+      - name: Get current date
+        id: get_date
+        run: |
+          echo "date=$(date +'%Y%m%d')" >> $GITHUB_OUTPUT
+
   nightly_release:
-    needs: build-and-test
+    needs: [build-and-test, get_date]
-    uses: ./.github/workflows/release_impl.yml
+    uses: ./.github/workflows/reusable-release.yml
     with:
-      overwrite_release: true
+      delete_pattern: "nightly-*"
       prerelease: true
-      title: "Clio development (nightly) build"
+      title: "Clio development build (nightly-${{ needs.get_date.outputs.date }})"
-      version: nightly
+      version: nightly-${{ needs.get_date.outputs.date }}
       header: >
         > **Note:** Please remember that this is a development release and it is not recommended for production use.
 
-        Changelog (including previous releases): <https://github.com/XRPLF/clio/commits/nightly>
+        Changelog (including previous releases): <https://github.com/XRPLF/clio/commits/nightly-${{ needs.get_date.outputs.date }}>
       generate_changelog: false
       draft: false
 
   build_and_publish_docker_image:
-    uses: ./.github/workflows/build_clio_docker_image.yml
+    uses: ./.github/workflows/build-clio-docker-image.yml
     needs: build-and-test
     secrets: inherit
     with:
@@ -130,10 +145,10 @@ jobs:
       issues: write
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
       - name: Create an issue
-        uses: ./.github/actions/create_issue
+        uses: ./.github/actions/create-issue
         env:
           GH_TOKEN: ${{ github.token }}
         with:

.github/workflows/pre-commit-autoupdate.yml

@@ -1,8 +1,8 @@
 name: Pre-commit auto-update
 
 on:
-  # every first day of the month
   schedule:
+    # every first day of the month
     - cron: "0 0 1 * *"
   pull_request:
     branches: [release/*, develop]

.github/workflows/pre-commit.yml

@@ -8,7 +8,7 @@ on:
 
 jobs:
   run-hooks:
-    uses: XRPLF/actions/.github/workflows/pre-commit.yml@afbcbdafbe0ce5439492fb87eda6441371086386
+    uses: XRPLF/actions/.github/workflows/pre-commit.yml@34790936fae4c6c751f62ec8c06696f9c1a5753a
     with:
       runs_on: heavy
-      container: '{ "image": "ghcr.io/xrplf/clio-ci:384e79cd32f5f6c0ab9be3a1122ead41c5a7e67d" }'
+      container: '{ "image": "ghcr.io/xrplf/clio-pre-commit:c117f470f2ef954520ab5d1c8a5ed2b9e68d6f8a" }'

.github/workflows/release.yml

@@ -29,9 +29,9 @@ jobs:
             conan_profile: gcc
             build_type: Release
             static: true
-            container: '{ "image": "ghcr.io/xrplf/clio-ci:384e79cd32f5f6c0ab9be3a1122ead41c5a7e67d" }'
+            container: '{ "image": "ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8" }'
 
-    uses: ./.github/workflows/build_and_test.yml
+    uses: ./.github/workflows/reusable-build-test.yml
     with:
       runs_on: ${{ matrix.os }}
       container: ${{ matrix.container }}
@@ -47,13 +47,13 @@ jobs:
 
   release:
     needs: build-and-test
-    uses: ./.github/workflows/release_impl.yml
+    uses: ./.github/workflows/reusable-release.yml
     with:
-      overwrite_release: false
+      delete_pattern: ""
       prerelease: ${{ contains(github.ref_name, '-') }}
-      title: "${{ github.ref_name}}"
+      title: "${{ github.ref_name }}"
       version: "${{ github.ref_name }}"
       header: >
         ${{ contains(github.ref_name, '-') && '> **Note:** Please remember that this is a release candidate and it is not recommended for production use.' || '' }}
       generate_changelog: ${{ !contains(github.ref_name, '-') }}
-      draft: true
+      draft: ${{ !contains(github.ref_name, '-') }}

.github/workflows/reusable-build-test.yml

@@ -77,7 +77,7 @@ on:
 
 jobs:
   build:
-    uses: ./.github/workflows/build_impl.yml
+    uses: ./.github/workflows/reusable-build.yml
     with:
       runs_on: ${{ inputs.runs_on }}
       container: ${{ inputs.container }}
@@ -95,7 +95,7 @@ jobs:
 
   test:
     needs: build
-    uses: ./.github/workflows/test_impl.yml
+    uses: ./.github/workflows/reusable-test.yml
     with:
       runs_on: ${{ inputs.runs_on }}
       container: ${{ inputs.container }}

.github/workflows/reusable-build.yml

@@ -75,6 +75,10 @@ on:
       CODECOV_TOKEN:
         required: false
 
+defaults:
+  run:
+    shell: bash
+
 jobs:
   build:
     name: Build
@@ -86,7 +90,7 @@ jobs:
         if: ${{ runner.os == 'macOS' }}
         uses: XRPLF/actions/.github/actions/cleanup-workspace@ea9970b7c211b18f4c8bcdb28c29f5711752029f
 
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 0
           # We need to fetch tags to have correct version in the release
@@ -95,25 +99,32 @@ jobs:
           ref: ${{ github.ref }}
 
       - name: Prepare runner
-        uses: XRPLF/actions/.github/actions/prepare-runner@7951b682e5a2973b28b0719a72f01fc4b0d0c34f
+        uses: XRPLF/actions/.github/actions/prepare-runner@8abb0722cbff83a9a2dc7d06c473f7a4964b7382
         with:
           disable_ccache: ${{ !inputs.download_ccache }}
 
       - name: Setup conan on macOS
         if: ${{ runner.os == 'macOS' }}
-        shell: bash
         run: ./.github/scripts/conan/init.sh
 
-      - name: Restore cache
+      - name: Generate cache key
-        if: ${{ inputs.download_ccache }}
+        uses: ./.github/actions/cache-key
-        uses: ./.github/actions/restore_cache
+        id: cache_key
-        id: restore_cache
         with:
           conan_profile: ${{ inputs.conan_profile }}
-          ccache_dir: ${{ env.CCACHE_DIR }}
           build_type: ${{ inputs.build_type }}
           code_coverage: ${{ inputs.code_coverage }}
 
+      - name: Restore ccache cache
+        if: ${{ inputs.download_ccache }}
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        id: restore_cache
+        with:
+          path: ${{ env.CCACHE_DIR }}
+          key: ${{ steps.cache_key.outputs.key }}
+          restore-keys: |
+            ${{ steps.cache_key.outputs.restore_keys }}
+
       - name: Run conan
         uses: ./.github/actions/conan
         with:
@@ -131,7 +142,7 @@ jobs:
           package: ${{ inputs.package }}
 
       - name: Build Clio
-        uses: ./.github/actions/build_clio
+        uses: ./.github/actions/build-clio
         with:
           targets: ${{ inputs.targets }}
 
@@ -141,18 +152,16 @@ jobs:
           ClangBuildAnalyzer --all build/ build_time_report.bin
           ClangBuildAnalyzer --analyze build_time_report.bin > build_time_report.txt
           cat build_time_report.txt
-        shell: bash
 
       - name: Upload build time analyze report
         if: ${{ inputs.analyze_build_time }}
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         with:
           name: build_time_report_${{ runner.os }}_${{ inputs.build_type }}_${{ inputs.conan_profile }}
           path: build_time_report.txt
 
       - name: Show ccache's statistics
         if: ${{ inputs.download_ccache }}
-        shell: bash
         id: ccache_stats
         run: |
           ccache -s > /tmp/ccache.stats
@@ -160,6 +169,13 @@ jobs:
           echo "miss_rate=${miss_rate}" >> $GITHUB_OUTPUT
           cat /tmp/ccache.stats
 
+      - name: Save ccache cache
+        if: ${{ inputs.upload_ccache && github.ref == 'refs/heads/develop' && (steps.restore_cache.outputs.cache-hit != 'true' || steps.ccache_stats.outputs.miss_rate == '100.0') }}
+        uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: ${{ env.CCACHE_DIR }}
+          key: ${{ steps.cache_key.outputs.key }}
+
       - name: Strip unit_tests
         if: ${{ !endsWith(inputs.conan_profile, 'san') && !inputs.code_coverage && !inputs.analyze_build_time }}
         run: strip build/clio_tests
@@ -170,44 +186,32 @@ jobs:
 
       - name: Upload clio_server
         if: ${{ inputs.upload_clio_server && !inputs.code_coverage && !inputs.analyze_build_time }}
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         with:
           name: clio_server_${{ runner.os }}_${{ inputs.build_type }}_${{ inputs.conan_profile }}
           path: build/clio_server
 
       - name: Upload clio_tests
         if: ${{ !inputs.code_coverage && !inputs.analyze_build_time && !inputs.package }}
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         with:
           name: clio_tests_${{ runner.os }}_${{ inputs.build_type }}_${{ inputs.conan_profile }}
           path: build/clio_tests
 
       - name: Upload clio_integration_tests
         if: ${{ !inputs.code_coverage && !inputs.analyze_build_time && !inputs.package }}
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         with:
           name: clio_integration_tests_${{ runner.os }}_${{ inputs.build_type }}_${{ inputs.conan_profile }}
           path: build/clio_integration_tests
 
       - name: Upload Clio Linux package
         if: ${{ inputs.package }}
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         with:
           name: clio_deb_package_${{ runner.os }}_${{ inputs.build_type }}_${{ inputs.conan_profile }}
           path: build/*.deb
 
-      - name: Save cache
-        if: ${{ inputs.upload_ccache && github.ref == 'refs/heads/develop' }}
-        uses: ./.github/actions/save_cache
-        with:
-          conan_profile: ${{ inputs.conan_profile }}
-          ccache_dir: ${{ env.CCACHE_DIR }}
-          build_type: ${{ inputs.build_type }}
-          code_coverage: ${{ inputs.code_coverage }}
-
-          ccache_cache_hit: ${{ steps.restore_cache.outputs.ccache_cache_hit }}
-          ccache_cache_miss_rate: ${{ steps.ccache_stats.outputs.miss_rate }}
-
       # This is run as part of the build job, because it requires the following:
       # - source code
       # - conan packages
@@ -216,17 +220,18 @@ jobs:
       # It's all available in the build job, but not in the test job
       - name: Run code coverage
         if: ${{ inputs.code_coverage }}
-        uses: ./.github/actions/code_coverage
+        uses: ./.github/actions/code-coverage
 
       - name: Verify expected version
         if: ${{ inputs.expected_version != '' }}
-        shell: bash
+        env:
+          INPUT_EXPECTED_VERSION: ${{ inputs.expected_version }}
         run: |
           set -e
-          EXPECTED_VERSION="clio-${{ inputs.expected_version }}"
+          EXPECTED_VERSION="clio-${INPUT_EXPECTED_VERSION}"
           actual_version=$(./build/clio_server --version)
           if [[ "$actual_version" != "$EXPECTED_VERSION" ]]; then
-            echo "Expected version '$EXPECTED_VERSION', but got '$actual_version'"
+            echo "Expected version '${EXPECTED_VERSION}', but got '${actual_version}'"
             exit 1
           fi
 
@@ -238,6 +243,6 @@ jobs:
     if: ${{ inputs.code_coverage }}
     name: Codecov
     needs: build
-    uses: ./.github/workflows/upload_coverage_report.yml
+    uses: ./.github/workflows/reusable-upload-coverage-report.yml
     secrets:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/reusable-release.yml

@@ -3,10 +3,10 @@ name: Make release
 on:
   workflow_call:
     inputs:
-      overwrite_release:
+      delete_pattern:
-        description: "Overwrite the current release and tag"
+        description: "Pattern to delete previous releases"
         required: true
-        type: boolean
+        type: string
 
       prerelease:
         description: "Create a prerelease"
@@ -38,11 +38,15 @@ on:
         required: true
         type: boolean
 
+defaults:
+  run:
+    shell: bash
+
 jobs:
   release:
     runs-on: heavy
     container:
-      image: ghcr.io/xrplf/clio-ci:384e79cd32f5f6c0ab9be3a1122ead41c5a7e67d
+      image: ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8
     env:
       GH_REPO: ${{ github.repository }}
       GH_TOKEN: ${{ github.token }}
@@ -51,29 +55,29 @@ jobs:
       contents: write
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 0
 
       - name: Prepare runner
-        uses: XRPLF/actions/.github/actions/prepare-runner@7951b682e5a2973b28b0719a72f01fc4b0d0c34f
+        uses: XRPLF/actions/.github/actions/prepare-runner@8abb0722cbff83a9a2dc7d06c473f7a4964b7382
         with:
           disable_ccache: true
 
-      - uses: actions/download-artifact@v5
+      - uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
         with:
           path: release_artifacts
           pattern: clio_server_*
 
       - name: Create release notes
-        shell: bash
+        env:
+          RELEASE_HEADER: ${{ inputs.header }}
         run: |
           echo "# Release notes" > "${RUNNER_TEMP}/release_notes.md"
           echo "" >> "${RUNNER_TEMP}/release_notes.md"
-          printf '%s\n' "${{ inputs.header }}" >> "${RUNNER_TEMP}/release_notes.md"
+          printf '%s\n' "${RELEASE_HEADER}" >> "${RUNNER_TEMP}/release_notes.md"
 
       - name: Generate changelog
-        shell: bash
         if: ${{ inputs.generate_changelog }}
         run: |
           LAST_TAG="$(gh release view --json tagName -q .tagName --repo XRPLF/clio)"
@@ -83,30 +87,39 @@ jobs:
           cat CHANGELOG.md >> "${RUNNER_TEMP}/release_notes.md"
 
       - name: Prepare release artifacts
-        shell: bash
         run: .github/scripts/prepare-release-artifacts.sh release_artifacts
 
       - name: Upload release notes
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         with:
           name: release_notes_${{ inputs.version }}
           path: "${RUNNER_TEMP}/release_notes.md"
 
-      - name: Remove current release and tag
+      - name: Remove previous release with a pattern
-        if: ${{ github.event_name != 'pull_request' && inputs.overwrite_release }}
+        if: ${{ github.event_name != 'pull_request' && inputs.delete_pattern != '' }}
-        shell: bash
+        env:
+          DELETE_PATTERN: ${{ inputs.delete_pattern }}
         run: |
-          gh release delete ${{ inputs.version }} --yes || true
+          RELEASES_TO_DELETE=$(gh release list --limit 50 --repo "${GH_REPO}" | grep -E "${DELETE_PATTERN}" | awk -F'\t' '{print $3}' || true)
-          git push origin :${{ inputs.version }} || true
+          if [ -n "$RELEASES_TO_DELETE" ]; then
+            for RELEASE in $RELEASES_TO_DELETE; do
+              echo "Deleting release: $RELEASE"
+              gh release delete "$RELEASE" --repo "${GH_REPO}" --yes --cleanup-tag
+            done
+          fi
 
       - name: Publish release
         if: ${{ github.event_name != 'pull_request' }}
-        shell: bash
+        env:
+          RELEASE_VERSION: ${{ inputs.version }}
+          PRERELEASE_OPTION: ${{ inputs.prerelease && '--prerelease' || '' }}
+          RELEASE_TITLE: ${{ inputs.title }}
+          DRAFT_OPTION: ${{ inputs.draft && '--draft' || '' }}
         run: |
-          gh release create "${{ inputs.version }}" \
+          gh release create "${RELEASE_VERSION}" \
-            ${{ inputs.prerelease && '--prerelease' || '' }} \
+            ${PRERELEASE_OPTION} \
-            --title "${{ inputs.title }}" \
+            --title "${RELEASE_TITLE}" \
             --target "${GITHUB_SHA}" \
-            ${{ inputs.draft && '--draft' || '' }} \
+            ${DRAFT_OPTION} \
             --notes-file "${RUNNER_TEMP}/release_notes.md" \
             ./release_artifacts/clio_server*

.github/workflows/reusable-test.yml

@@ -33,6 +33,10 @@ on:
         required: true
         type: boolean
 
+defaults:
+  run:
+    shell: bash
+
 jobs:
   unit_tests:
     name: Unit testing
@@ -43,23 +47,22 @@ jobs:
 
     env:
       # TODO: remove completely when we have fixed all currently existing issues with sanitizers
-      SANITIZER_IGNORE_ERRORS: ${{ endsWith(inputs.conan_profile, '.tsan') || inputs.conan_profile == 'clang.asan' || (inputs.conan_profile == 'gcc.asan' && inputs.build_type == 'Release') }}
+      SANITIZER_IGNORE_ERRORS: ${{ endsWith(inputs.conan_profile, '.tsan') }}
 
     steps:
       - name: Cleanup workspace
         if: ${{ runner.os == 'macOS' }}
         uses: XRPLF/actions/.github/actions/cleanup-workspace@ea9970b7c211b18f4c8bcdb28c29f5711752029f
 
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 0
 
-      - uses: actions/download-artifact@v5
+      - uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
         with:
           name: clio_tests_${{ runner.os }}_${{ inputs.build_type }}_${{ inputs.conan_profile }}
 
       - name: Make clio_tests executable
-        shell: bash
         run: chmod +x ./clio_tests
 
       - name: Run clio_tests (regular)
@@ -68,11 +71,10 @@ jobs:
 
       - name: Run clio_tests (sanitizer errors ignored)
         if: ${{ env.SANITIZER_IGNORE_ERRORS == 'true' }}
-        run: ./.github/scripts/execute-tests-under-sanitizer ./clio_tests
+        run: ./.github/scripts/execute-tests-under-sanitizer.sh ./clio_tests
 
       - name: Check for sanitizer report
         if: ${{ env.SANITIZER_IGNORE_ERRORS == 'true' }}
-        shell: bash
         id: check_report
         run: |
           if ls .sanitizer-report/* 1> /dev/null 2>&1; then
@@ -83,7 +85,7 @@ jobs:
 
       - name: Upload sanitizer report
         if: ${{ env.SANITIZER_IGNORE_ERRORS == 'true' && steps.check_report.outputs.found_report == 'true' }}
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         with:
           name: sanitizer_report_${{ runner.os }}_${{ inputs.build_type }}_${{ inputs.conan_profile }}
           path: .sanitizer-report/*
@@ -91,7 +93,7 @@ jobs:
 
       - name: Create an issue
         if: ${{ false && env.SANITIZER_IGNORE_ERRORS == 'true' && steps.check_report.outputs.found_report == 'true' }}
-        uses: ./.github/actions/create_issue
+        uses: ./.github/actions/create-issue
         env:
           GH_TOKEN: ${{ github.token }}
         with:
@@ -144,7 +146,7 @@ jobs:
             sleep 5
           done
 
-      - uses: actions/download-artifact@v5
+      - uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
         with:
           name: clio_integration_tests_${{ runner.os }}_${{ inputs.build_type }}_${{ inputs.conan_profile }}
 

.github/workflows/reusable-upload-coverage-report.yml

@@ -1,24 +1,27 @@
 name: Upload report
 
 on:
-  workflow_dispatch:
   workflow_call:
     secrets:
       CODECOV_TOKEN:
         required: true
 
+defaults:
+  run:
+    shell: bash
+
 jobs:
   upload_report:
     name: Upload report
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 0
 
       - name: Download report artifact
-        uses: actions/download-artifact@v5
+        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
         with:
           name: coverage-report.xml
           path: build

.github/workflows/sanitizers.yml

@@ -8,14 +8,14 @@ on:
     paths:
       - .github/workflows/sanitizers.yml
 
-      - .github/workflows/build_and_test.yml
+      - .github/workflows/reusable-build-test.yml
-      - .github/workflows/build_impl.yml
+      - .github/workflows/reusable-build.yml
-      - .github/workflows/test_impl.yml
+      - .github/workflows/reusable-test.yml
 
       - ".github/actions/**"
-      - "!.github/actions/build_docker_image/**"
+      - "!.github/actions/build-docker-image/**"
-      - "!.github/actions/create_issue/**"
+      - "!.github/actions/create-issue/**"
-      - .github/scripts/execute-tests-under-sanitizer
+      - .github/scripts/execute-tests-under-sanitizer.sh
 
       - CMakeLists.txt
       - conanfile.py
@@ -41,10 +41,10 @@ jobs:
         sanitizer_ext: [.asan, .tsan, .ubsan]
         build_type: [Release, Debug]
 
-    uses: ./.github/workflows/build_and_test.yml
+    uses: ./.github/workflows/reusable-build-test.yml
     with:
       runs_on: heavy
-      container: '{ "image": "ghcr.io/xrplf/clio-ci:384e79cd32f5f6c0ab9be3a1122ead41c5a7e67d" }'
+      container: '{ "image": "ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8" }'
       download_ccache: false
       upload_ccache: false
       conan_profile: ${{ matrix.compiler }}${{ matrix.sanitizer_ext }}

.github/workflows/update-docker-ci.yml

@@ -3,23 +3,23 @@ name: Update CI docker image
 on:
   pull_request:
     paths:
-      - .github/workflows/update_docker_ci.yml
+      - .github/workflows/update-docker-ci.yml
 
-      - ".github/actions/build_docker_image/**"
+      - ".github/actions/build-docker-image/**"
 
-      - "docker/ci/**"
+      - "docker/**"
-      - "docker/compilers/**"
+      - "!docker/clio/**"
-      - "docker/tools/**"
+      - "!docker/develop/**"
   push:
     branches: [develop]
     paths:
-      - .github/workflows/update_docker_ci.yml
+      - .github/workflows/update-docker-ci.yml
 
-      - ".github/actions/build_docker_image/**"
+      - ".github/actions/build-docker-image/**"
 
-      - "docker/ci/**"
+      - "docker/**"
-      - "docker/compilers/**"
+      - "!docker/clio/**"
-      - "docker/tools/**"
+      - "!docker/develop/**"
   workflow_dispatch:
 
 concurrency:
@@ -33,6 +33,10 @@ env:
   GCC_MAJOR_VERSION: 15
   GCC_VERSION: 15.2.0
 
+defaults:
+  run:
+    shell: bash
+
 jobs:
   repo:
     name: Calculate repo name
@@ -52,7 +56,7 @@ jobs:
     needs: repo
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
       - name: Get changed files
         id: changed-files
@@ -60,7 +64,7 @@ jobs:
         with:
           files: "docker/compilers/gcc/**"
 
-      - uses: ./.github/actions/build_docker_image
+      - uses: ./.github/actions/build-docker-image
         if: ${{ steps.changed-files.outputs.any_changed == 'true' }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -90,15 +94,15 @@ jobs:
     needs: repo
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
       - name: Get changed files
         id: changed-files
-        uses: tj-actions/changed-files@24d32ffd492484c1d75e0c0b894501ddb9d30d62 # v47.0.0
+        uses: tj-actions/changed-files@ed68ef82c095e0d48ec87eccea555d944a631a4c # v46.0.5
         with:
           files: "docker/compilers/gcc/**"
 
-      - uses: ./.github/actions/build_docker_image
+      - uses: ./.github/actions/build-docker-image
         if: ${{ steps.changed-files.outputs.any_changed == 'true' }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -128,7 +132,7 @@ jobs:
     needs: [repo, gcc-amd64, gcc-arm64]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
       - name: Get changed files
         id: changed-files
@@ -137,11 +141,11 @@ jobs:
           files: "docker/compilers/gcc/**"
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3.11.1
 
       - name: Login to GitHub Container Registry
         if: ${{ github.event_name != 'pull_request' }}
-        uses: docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1 # v3.5.0
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
         with:
           registry: ghcr.io
           username: ${{ github.repository_owner }}
@@ -149,7 +153,7 @@ jobs:
 
       - name: Login to DockerHub
         if: ${{ github.repository_owner == 'XRPLF' && github.event_name != 'pull_request' }}
-        uses: docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1 # v3.5.0
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
         with:
           username: ${{ secrets.DOCKERHUB_USER }}
           password: ${{ secrets.DOCKERHUB_PW }}
@@ -179,7 +183,7 @@ jobs:
     needs: repo
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
       - name: Get changed files
         id: changed-files
@@ -187,7 +191,7 @@ jobs:
         with:
           files: "docker/compilers/clang/**"
 
-      - uses: ./.github/actions/build_docker_image
+      - uses: ./.github/actions/build-docker-image
         if: ${{ steps.changed-files.outputs.any_changed == 'true' }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -215,7 +219,7 @@ jobs:
     needs: [repo, gcc-merge]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
       - name: Get changed files
         id: changed-files
@@ -223,7 +227,7 @@ jobs:
         with:
           files: "docker/tools/**"
 
-      - uses: ./.github/actions/build_docker_image
+      - uses: ./.github/actions/build-docker-image
         if: ${{ steps.changed-files.outputs.any_changed == 'true' }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -246,15 +250,15 @@ jobs:
     needs: [repo, gcc-merge]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
       - name: Get changed files
         id: changed-files
-        uses: tj-actions/changed-files@24d32ffd492484c1d75e0c0b894501ddb9d30d62 # v47.0.0
+        uses: tj-actions/changed-files@ed68ef82c095e0d48ec87eccea555d944a631a4c # v46.0.5
         with:
           files: "docker/tools/**"
 
-      - uses: ./.github/actions/build_docker_image
+      - uses: ./.github/actions/build-docker-image
         if: ${{ steps.changed-files.outputs.any_changed == 'true' }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -277,7 +281,7 @@ jobs:
     needs: [repo, tools-amd64, tools-arm64]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
       - name: Get changed files
         id: changed-files
@@ -286,11 +290,11 @@ jobs:
           files: "docker/tools/**"
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3.11.1
 
       - name: Login to GitHub Container Registry
         if: ${{ github.event_name != 'pull_request' }}
-        uses: docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1 # v3.5.0
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
         with:
           registry: ghcr.io
           username: ${{ github.repository_owner }}
@@ -306,14 +310,36 @@ jobs:
             $image:arm64-latest \
             $image:amd64-latest
 
+  pre-commit:
+    name: Build and push pre-commit docker image
+    runs-on: heavy
+    needs: [repo, tools-merge]
+
+    steps:
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: ./.github/actions/build-docker-image
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          images: |
+            ${{ needs.repo.outputs.GHCR_REPO }}/clio-pre-commit
+          push_image: ${{ github.event_name != 'pull_request' }}
+          directory: docker/pre-commit
+          tags: |
+            type=raw,value=latest
+            type=raw,value=${{ github.sha }}
+          platforms: linux/amd64,linux/arm64
+          build_args: |
+            GHCR_REPO=${{ needs.repo.outputs.GHCR_REPO }}
+
   ci:
     name: Build and push CI docker image
     runs-on: heavy
     needs: [repo, gcc-merge, clang, tools-merge]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
-      - uses: ./.github/actions/build_docker_image
+      - uses: ./.github/actions/build-docker-image
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           DOCKERHUB_USER: ${{ secrets.DOCKERHUB_USER }}

.github/workflows/upload-conan-deps.yml

@@ -18,7 +18,7 @@ on:
   pull_request:
     branches: [develop]
     paths:
-      - .github/workflows/upload_conan_deps.yml
+      - .github/workflows/upload-conan-deps.yml
 
       - .github/actions/conan/action.yml
       - ".github/scripts/conan/**"
@@ -28,7 +28,7 @@ on:
   push:
     branches: [develop]
     paths:
-      - .github/workflows/upload_conan_deps.yml
+      - .github/workflows/upload-conan-deps.yml
 
       - .github/actions/conan/action.yml
       - ".github/scripts/conan/**"
@@ -40,13 +40,17 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
+defaults:
+  run:
+    shell: bash
+
 jobs:
   generate-matrix:
     runs-on: ubuntu-latest
     outputs:
       matrix: ${{ steps.set-matrix.outputs.matrix }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
       - name: Calculate conan matrix
         id: set-matrix
@@ -69,16 +73,15 @@ jobs:
       CONAN_PROFILE: ${{ matrix.compiler }}${{ matrix.sanitizer_ext }}
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
       - name: Prepare runner
-        uses: XRPLF/actions/.github/actions/prepare-runner@7951b682e5a2973b28b0719a72f01fc4b0d0c34f
+        uses: XRPLF/actions/.github/actions/prepare-runner@8abb0722cbff83a9a2dc7d06c473f7a4964b7382
         with:
           disable_ccache: true
 
       - name: Setup conan on macOS
         if: ${{ runner.os == 'macOS' }}
-        shell: bash
         run: ./.github/scripts/conan/init.sh
 
       - name: Show conan profile
@@ -99,4 +102,6 @@ jobs:
 
       - name: Upload Conan packages
         if: ${{ github.repository_owner == 'XRPLF' && github.event_name != 'pull_request' && github.event_name != 'schedule' }}
-        run: conan upload "*" -r=xrplf --confirm ${{ github.event.inputs.force_upload == 'true' && '--force' || '' }}
+        env:
+          FORCE_OPTION: ${{ github.event.inputs.force_upload == 'true' && '--force' || '' }}
+        run: conan upload "*" -r=xrplf --confirm ${FORCE_OPTION}

.pre-commit-config.yaml

@@ -11,7 +11,10 @@
 #
 # See https://pre-commit.com for more information
 # See https://pre-commit.com/hooks.html for more hooks
-exclude: ^(docs/doxygen-awesome-theme/|conan\.lock$)
+exclude: |
+  (?x)^(
+    docs/doxygen-awesome-theme/.*
+  )$
 
 repos:
   # `pre-commit sample-config` default hooks
@@ -43,7 +46,7 @@ repos:
         # hadolint-docker is a special hook that runs hadolint in a Docker container
         # Docker is not installed in the environment where pre-commit is run
         stages: [manual]
-        entry: hadolint/hadolint:v2.12.1-beta hadolint
+        entry: hadolint/hadolint:v2.14.0 hadolint
 
   - repo: https://github.com/codespell-project/codespell
     rev: 63c8f8312b7559622c0d82815639671ae42132ac # frozen: v2.4.1

CMakeLists.txt

@@ -75,10 +75,11 @@ if (san)
   endif ()
   target_compile_options(clio_options INTERFACE ${SAN_OPTIMIZATION_FLAG} ${SAN_FLAG} -fno-omit-frame-pointer)
 
-  target_compile_definitions(
+  if (san STREQUAL "address")
-    clio_options INTERFACE $<$<STREQUAL:${san},address>:SANITIZER=ASAN> $<$<STREQUAL:${san},thread>:SANITIZER=TSAN>
+    # ASAN needs these definitions as well as correct b2 flags in conan profile for sanitizers
-                           $<$<STREQUAL:${san},memory>:SANITIZER=MSAN> $<$<STREQUAL:${san},undefined>:SANITIZER=UBSAN>
+    target_compile_definitions(clio_options INTERFACE BOOST_USE_ASAN=1 BOOST_USE_UCONTEXT=1)
-  )
+  endif ()
+
   target_link_libraries(clio_options INTERFACE ${SAN_FLAG} ${SAN_LIB})
 endif ()
 

README.md

@@ -34,7 +34,6 @@ Below are some useful docs to learn more about Clio.
 
 - [How to configure Clio and rippled](./docs/configure-clio.md)
 - [How to run Clio](./docs/run-clio.md)
-- [Logging](./docs/logging.md)
 - [Troubleshooting guide](./docs/trouble_shooting.md)
 
 **General reference material:**

conan.lock

@@ -3,7 +3,8 @@
     "requires": [
         "zlib/1.3.1#b8bc2603263cf7eccbd6e17e66b0ed76%1756234269.497",
         "xxhash/0.8.3#681d36a0a6111fc56e5e45ea182c19cc%1756234289.683",
-        "xrpl/2.6.1-rc2#c14c6a4092fb2b97d3a93906dcee87b7%1759161400.392",
+        "xrpl/3.0.0-rc1#f5c8ecd42bdf511ad36f57bc702dacd2%1762975621.294",
+        "xrpl/2.6.1#973af2bf9631f239941dd9f5a100bb84%1759275059.342",
         "sqlite3/3.49.1#8631739a4c9b93bd3d6b753bac548a63%1756234266.869",
         "spdlog/1.15.3#3ca0e9e6b83af4d0151e26541d140c86%1754401846.61",
         "soci/4.0.3#a9f8d773cd33e356b5879a4b0564f287%1756234262.318",
@@ -55,4 +56,4 @@
         ]
     },
     "config_requires": []
-}
+}

conanfile.py

@@ -18,7 +18,7 @@ class ClioConan(ConanFile):
         'protobuf/3.21.12',
         'grpc/1.50.1',
         'openssl/1.1.1w',
-        'xrpl/2.6.1-rc2',
+        'xrpl/3.0.0-rc1',
         'zlib/1.3.1',
         'libbacktrace/cci.20210118',
         'spdlog/1.15.3',

docker/ci/Dockerfile

@@ -43,25 +43,22 @@ RUN apt-get update \
     && rm -rf /var/lib/apt/lists/*
 
 # Install Python tools
-ARG PYTHON_VERSION=3.13
+RUN apt-get update \
-
-RUN add-apt-repository ppa:deadsnakes/ppa \
-    && apt-get update \
     && apt-get install -y --no-install-recommends --no-install-suggests \
-        python${PYTHON_VERSION} \
+        python3 \
-        python${PYTHON_VERSION}-venv \
+        python3-pip \
     && apt-get clean \
-    && rm -rf /var/lib/apt/lists/* \
+    && rm -rf /var/lib/apt/lists/*
-    && curl -sS https://bootstrap.pypa.io/get-pip.py | python${PYTHON_VERSION}
-
-# Create a virtual environment for python tools
-RUN python${PYTHON_VERSION} -m venv /opt/venv
-ENV PATH="/opt/venv/bin:$PATH"
 
 RUN pip install -q --no-cache-dir \
+        # TODO: Remove this once we switch to newer Ubuntu base image
+        # lxml 6.0.0 is not compatible with our image
+        'lxml<6.0.0' \
         cmake \
-        conan==2.20.1 \
+        conan==2.22.1 \
         gcovr \
+        # We're adding pre-commit to this image as well,
+        # because clang-tidy workflow requires it
         pre-commit
 
 # Install LLVM tools

docker/ci/README.md

@@ -5,17 +5,17 @@ It is used in [Clio Github Actions](https://github.com/XRPLF/clio/actions) but c
 
 The image is based on Ubuntu 20.04 and contains:
 
-- ccache 4.11.3
+- ccache 4.12.1
 - Clang 19
 - ClangBuildAnalyzer 1.6.0
-- Conan 2.20.1
+- Conan 2.22.1
-- Doxygen 1.12
+- Doxygen 1.15.0
 - GCC 15.2.0
 - GDB 16.3
-- gh 2.74
+- gh 2.82.1
-- git-cliff 2.9.1
+- git-cliff 2.10.1
-- mold 2.40.1
+- mold 2.40.4
-- Python 3.13
+- Python 3.8
 - and some other useful tools
 
 Conan is set up to build Clio without any additional steps.

docker/ci/conan/sanitizer_template.profile

@@ -3,6 +3,9 @@
 {% set sanitizer_opt_map = {"asan": "address", "tsan": "thread", "ubsan": "undefined"} %}
 {% set sanitizer = sanitizer_opt_map[sani] %}
 
+{% set sanitizer_b2_flags_map = {"address": "define=BOOST_USE_ASAN=1 context-impl=ucontext address-sanitizer=on", "thread": "thread-sanitizer=on", "undefined": "undefined-sanitizer=on"} %}
+{% set sanitizer_b2_flags_str = sanitizer_b2_flags_map[sanitizer] %}
+
 {% set sanitizer_build_flags_str = "-fsanitize=" ~ sanitizer ~ " -g -O1 -fno-omit-frame-pointer" %}
 {% set sanitizer_build_flags = sanitizer_build_flags_str.split(' ') %}
 {% set sanitizer_link_flags_str = "-fsanitize=" ~ sanitizer %}
@@ -11,7 +14,8 @@
 include({{ compiler }})
 
 [options]
-boost/*:extra_b2_flags="cxxflags=\"{{ sanitizer_build_flags_str }}\" linkflags=\"{{ sanitizer_link_flags_str }}\""
+boost/*:extra_b2_flags="{{ sanitizer_b2_flags_str }}"
+boost/*:without_context=False
 boost/*:without_stacktrace=True
 
 [conf]

docker/compilers/gcc/Dockerfile

@@ -8,7 +8,7 @@ ARG UBUNTU_VERSION
 
 ARG GCC_MAJOR_VERSION
 
-ARG BUILD_VERSION=1
+ARG BUILD_VERSION=0
 
 ARG DEBIAN_FRONTEND=noninteractive
 ARG TARGETARCH
@@ -34,6 +34,7 @@ RUN wget --progress=dot:giga https://gcc.gnu.org/pub/gcc/releases/gcc-$GCC_VERSI
 WORKDIR /gcc-$GCC_VERSION
 RUN ./contrib/download_prerequisites
 
+# hadolint ignore=DL3059
 RUN mkdir /gcc-build
 WORKDIR /gcc-build
 RUN /gcc-$GCC_VERSION/configure \

docker/develop/compose.yaml

@@ -1,6 +1,6 @@
 services:
   clio_develop:
-    image: ghcr.io/xrplf/clio-ci:384e79cd32f5f6c0ab9be3a1122ead41c5a7e67d
+    image: ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8
     volumes:
       - clio_develop_conan_data:/root/.conan2/p
       - clio_develop_ccache:/root/.ccache

docker/pre-commit/Dockerfile

@@ -0,0 +1,38 @@
+ARG GHCR_REPO=invalid
+FROM ${GHCR_REPO}/clio-tools:latest AS clio-tools
+
+# We're using Ubuntu 24.04 to have a more recent version of Python
+FROM ubuntu:24.04
+
+ARG DEBIAN_FRONTEND=noninteractive
+
+SHELL ["/bin/bash", "-o", "pipefail", "-c"]
+
+# hadolint ignore=DL3002
+USER root
+WORKDIR /root
+
+# Install common tools and dependencies
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends --no-install-suggests \
+        curl \
+        git \
+        libatomic1 \
+        software-properties-common \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Python tools
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends --no-install-suggests \
+        python3 \
+        python3-pip \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN pip install -q --no-cache-dir --break-system-packages \
+        pre-commit
+
+COPY --from=clio-tools \
+    /usr/local/bin/doxygen \
+    /usr/local/bin/

docker/tools/Dockerfile

@@ -8,7 +8,7 @@ ARG TARGETARCH
 
 SHELL ["/bin/bash", "-o", "pipefail", "-c"]
 
-ARG BUILD_VERSION=2
+ARG BUILD_VERSION=0
 
 RUN apt-get update \
     && apt-get install -y --no-install-recommends --no-install-suggests \
@@ -24,7 +24,7 @@ RUN apt-get update \
 
 WORKDIR /tmp
 
-ARG MOLD_VERSION=2.40.1
+ARG MOLD_VERSION=2.40.4
 RUN wget --progress=dot:giga "https://github.com/rui314/mold/archive/refs/tags/v${MOLD_VERSION}.tar.gz" \
     && tar xf "v${MOLD_VERSION}.tar.gz" \
     && cd "mold-${MOLD_VERSION}" \
@@ -34,7 +34,7 @@ RUN wget --progress=dot:giga "https://github.com/rui314/mold/archive/refs/tags/v
     && ninja install \
     && rm -rf /tmp/* /var/tmp/*
 
-ARG CCACHE_VERSION=4.11.3
+ARG CCACHE_VERSION=4.12.1
 RUN wget --progress=dot:giga "https://github.com/ccache/ccache/releases/download/v${CCACHE_VERSION}/ccache-${CCACHE_VERSION}.tar.gz" \
     && tar xf "ccache-${CCACHE_VERSION}.tar.gz" \
     && cd "ccache-${CCACHE_VERSION}" \
@@ -51,7 +51,7 @@ RUN apt-get update \
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/*
 
-ARG DOXYGEN_VERSION=1.12.0
+ARG DOXYGEN_VERSION=1.15.0
 RUN wget --progress=dot:giga "https://github.com/doxygen/doxygen/releases/download/Release_${DOXYGEN_VERSION//./_}/doxygen-${DOXYGEN_VERSION}.src.tar.gz" \
     && tar xf "doxygen-${DOXYGEN_VERSION}.src.tar.gz" \
     && cd "doxygen-${DOXYGEN_VERSION}" \
@@ -71,13 +71,13 @@ RUN wget --progress=dot:giga "https://github.com/aras-p/ClangBuildAnalyzer/archi
     && ninja install \
     && rm -rf /tmp/* /var/tmp/*
 
-ARG GIT_CLIFF_VERSION=2.9.1
+ARG GIT_CLIFF_VERSION=2.10.1
 RUN wget --progress=dot:giga "https://github.com/orhun/git-cliff/releases/download/v${GIT_CLIFF_VERSION}/git-cliff-${GIT_CLIFF_VERSION}-x86_64-unknown-linux-musl.tar.gz" \
     && tar xf git-cliff-${GIT_CLIFF_VERSION}-x86_64-unknown-linux-musl.tar.gz \
     && mv git-cliff-${GIT_CLIFF_VERSION}/git-cliff /usr/local/bin/git-cliff \
     && rm -rf /tmp/* /var/tmp/*
 
-ARG GH_VERSION=2.74.0
+ARG GH_VERSION=2.82.1
 RUN wget --progress=dot:giga "https://github.com/cli/cli/releases/download/v${GH_VERSION}/gh_${GH_VERSION}_linux_${TARGETARCH}.tar.gz" \
     && tar xf gh_${GH_VERSION}_linux_${TARGETARCH}.tar.gz \
     && mv gh_${GH_VERSION}_linux_${TARGETARCH}/bin/gh /usr/local/bin/gh \

docs/Doxyfile

@@ -15,6 +15,7 @@ EXTRACT_ANON_NSPACES   = NO
 SORT_MEMBERS_CTORS_1ST = YES
 
 INPUT                  = ${SOURCE}/src
+USE_MDFILE_AS_MAINPAGE = ${SOURCE}/src/README.md
 EXCLUDE_SYMBOLS        = ${EXCLUDES}
 RECURSIVE              = YES
 HAVE_DOT               = ${USE_DOT}

docs/build-clio.md

@@ -177,7 +177,7 @@ There are several CMake options you can use to customize the build:
 
 ### Generating API docs for Clio
 
-The API documentation for Clio is generated by [Doxygen](https://www.doxygen.nl/index.html). If you want to generate the API documentation when building Clio, make sure to install Doxygen 1.12.0 on your system.
+The API documentation for Clio is generated by [Doxygen](https://www.doxygen.nl/index.html). If you want to generate the API documentation when building Clio, make sure to install Doxygen 1.14.0 on your system.
 
 To generate the API docs, please use CMake option `-Ddocs=ON` as described above and build the `docs` target.
 
@@ -191,7 +191,7 @@ Open the `index.html` file in your browser to see the documentation pages.
 It is also possible to build Clio using [Docker](https://www.docker.com/) if you don't want to install all the dependencies on your machine.
 
 ```sh
-docker run -it ghcr.io/xrplf/clio-ci:384e79cd32f5f6c0ab9be3a1122ead41c5a7e67d
+docker run -it ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8
 git clone https://github.com/XRPLF/clio
 cd clio
 ```

docs/config-description.md

@@ -89,6 +89,14 @@ This document provides a list of all available Clio configuration properties in
 - **Constraints**: The minimum value is `1`. The maximum value is `4294967295`.
 - **Description**: Represents the number of threads that will be used for database operations.
 
+### database.cassandra.provider
+
+- **Required**: True
+- **Type**: string
+- **Default value**: `cassandra`
+- **Constraints**: The value must be one of the following: `cassandra`, `aws_keyspace`.
+- **Description**: The specific database backend provider we are using.
+
 ### database.cassandra.core_connections_per_host
 
 - **Required**: True
@@ -285,7 +293,7 @@ This document provides a list of all available Clio configuration properties in
 
 - **Required**: True
 - **Type**: int
-- **Default value**: `1`
+- **Default value**: `1000`
 - **Constraints**: The minimum value is `1`. The maximum value is `4294967295`.
 - **Description**: The maximum size of the server's request queue. If set to `0`, this means there is no queue size limit.
 
@@ -433,6 +441,22 @@ This document provides a list of all available Clio configuration properties in
 - **Constraints**: The value must be one of the following: `sync`, `async`, `none`.
 - **Description**: The strategy used for Cache loading.
 
+### cache.file.path
+
+- **Required**: False
+- **Type**: string
+- **Default value**: None
+- **Constraints**: None
+- **Description**: The path to a file where cache will be saved to on shutdown and loaded from on startup. If the file couldn't be read Clio will load cache as usual (from DB or from rippled).
+
+### cache.file.max_sequence_age
+
+- **Required**: True
+- **Type**: int
+- **Default value**: `5000`
+- **Constraints**: None
+- **Description**: Max allowed difference between the latest sequence in DB and in cache file. If the cache file is too old (contains too low latest sequence) Clio will reject using it.
+
 ### log.channels.[].channel
 
 - **Required**: False

docs/doxygen-awesome-theme/doxygen-awesome.css

@@ -951,7 +951,7 @@ span.arrowhead {
     border-color: var(--primary-color);
 }
 
-#nav-tree ul li:first-child > div > a {
+#nav-tree-contents > ul > li:first-child > div > a {
     opacity: 0;
     pointer-events: none;
 }

docs/examples/config/example-config.json

@@ -61,7 +61,7 @@
     "ip": "0.0.0.0",
     "port": 51233,
     // Max number of requests to queue up before rejecting further requests.
-    // Defaults to 0, which disables the limit.
+    // Defaults to 1000 (use 0 to make the queue unbound).
     "max_queue_size": 500,
     // If request contains header with authorization, Clio will check if it matches the prefix 'Password ' + this value's sha256 hash
     // If matches, the request will be considered as admin request
@@ -137,7 +137,11 @@
     // "num_cursors_from_account": 3200, // Read the cursors from the account table until we have enough cursors to partition the ledger to load concurrently.
     "num_markers": 48, // The number of markers is the number of coroutines to load the cache concurrently.
     "page_fetch_size": 512, // The number of rows to load for each page.
-    "load": "async" // "sync" to load cache synchronously  or "async" to load cache asynchronously or "none"/"no" to turn off the cache.
+    "load": "async", // "sync" to load cache synchronously  or "async" to load cache asynchronously or "none"/"no" to turn off the cache.
+    "file": {
+      "path": "./cache.bin",
+      "max_sequence_age": 5000
+    }
   },
   "prometheus": {
     "enabled": true,

docs/run-clio.md

@@ -77,7 +77,7 @@ It's possible to configure `minimum`, `maximum` and `default` version like so:
 
 All of the above are optional.
 
-Clio will fallback to hardcoded defaults when these values are not specified in the config file, or if the configured values are outside of the minimum and maximum supported versions hardcoded in [src/rpc/common/APIVersion.h](../src/rpc/common/APIVersion.hpp).
+Clio will fallback to hardcoded defaults when these values are not specified in the config file, or if the configured values are outside of the minimum and maximum supported versions hardcoded in [src/rpc/common/APIVersion.hpp](../src/rpc/common/APIVersion.hpp).
 
 > [!TIP]
 > See the [example-config.json](../docs/examples/config/example-config.json) for more details.

pre-commit-hooks/check-doxygen-docs.sh

@@ -36,19 +36,19 @@ EOF
     exit 0
 fi
 
-# Check version of doxygen is at least 1.12
+# Check version of doxygen is at least 1.14
 version=$($DOXYGEN --version | grep -o '[0-9\.]*')
 
-if [[ "1.12.0" > "$version" ]]; then
+if [[ "1.14.0" > "$version" ]]; then
     # No hard error if doxygen version is not the one we want - let CI deal with it
     cat <<EOF
 
                                     ERROR
 -----------------------------------------------------------------------------
-        A minimum of version 1.12 of `which doxygen` is required.
+        A minimum of version 1.14 of `which doxygen` is required.
-        Your version is $version. Please upgrade it for next time.
+        Your version is $version. Please upgrade it.
 
-        Your changes may fail to pass CI once pushed.
+        Your changes may fail CI checks.
 -----------------------------------------------------------------------------
 
 EOF

pre-commit-hooks/json_in_cpp.py

@@ -44,8 +44,13 @@ def fix_colon_spacing(cpp_content: str) -> str:
 
 
 def fix_indentation(cpp_content: str) -> str:
+    if "JSON(" not in cpp_content:
+        return cpp_content
+
     lines = cpp_content.splitlines()
 
+    ends_with_newline = cpp_content.endswith('\n')
+
     def find_indentation(line: str) -> int:
         return len(line) - len(line.lstrip())
 
@@ -66,7 +71,11 @@ def fix_indentation(cpp_content: str) -> str:
                         break
                     lines[i] = lines[i][by_how_much:] if by_how_much > 0 else " " * (-by_how_much) + lines[i]
 
-    return "\n".join(lines) + "\n"
+    result = "\n".join(lines)
+
+    if ends_with_newline:
+        result += "\n"
+    return result
 
 
 def process_file(file_path: Path, dry_run: bool) -> bool:

src/CMakeLists.txt

@@ -2,7 +2,6 @@ add_subdirectory(util)
 add_subdirectory(data)
 add_subdirectory(cluster)
 add_subdirectory(etl)
-add_subdirectory(etlng)
 add_subdirectory(feed)
 add_subdirectory(rpc)
 add_subdirectory(web)

src/README.md

@@ -0,0 +1,20 @@
+# Clio API server
+
+## Introduction
+
+Clio is an XRP Ledger API server optimized for RPC calls over WebSocket or JSON-RPC.
+
+It stores validated historical ledger and transaction data in a more space efficient format, and uses up to 4 times
+less space than [rippled](https://github.com/XRPLF/rippled).
+
+Clio can be configured to store data in [Apache Cassandra](https://cassandra.apache.org/_/index.html) or
+[ScyllaDB](https://www.scylladb.com/), enabling scalable read throughput. Multiple Clio nodes can share
+access to the same dataset, which allows for a highly available cluster of Clio nodes without the need for redundant
+data storage or computation.
+
+## Develop
+
+As you prepare to develop code for Clio, please be sure you are aware of our current
+[Contribution guidelines](https://github.com/XRPLF/clio/blob/develop/CONTRIBUTING.md).
+
+Read about @ref "rpc" carefully to know more about writing your own handlers for Clio.

src/app/CMakeLists.txt

@@ -5,10 +5,9 @@ target_link_libraries(
   clio_app
   PUBLIC clio_cluster
          clio_etl
-         clio_etlng
          clio_feed
-         clio_web
-         clio_rpc
          clio_migration
+         clio_rpc
+         clio_web
   PRIVATE Boost::program_options
 )

src/app/ClioApplication.cpp

@@ -28,8 +28,6 @@
 #include "etl/ETLService.hpp"
 #include "etl/LoadBalancer.hpp"
 #include "etl/NetworkValidatedLedgers.hpp"
-#include "etlng/LoadBalancer.hpp"
-#include "etlng/LoadBalancerInterface.hpp"
 #include "feed/SubscriptionManager.hpp"
 #include "migration/MigrationInspectorFactory.hpp"
 #include "rpc/Counters.hpp"
@@ -57,6 +55,7 @@
 #include <cstdlib>
 #include <memory>
 #include <optional>
+#include <string>
 #include <thread>
 #include <utility>
 #include <vector>
@@ -103,7 +102,7 @@ ClioApplication::run(bool const useNgWebServer)
     // This is not the only io context in the application.
     boost::asio::io_context ioc{threads};
 
-    // Similarly we need a context to run ETLng on
+    // Similarly we need a context to run ETL on
     // In the future we can remove the raw ioc and use ctx instead
     util::async::CoroExecutionContext ctx{threads};
 
@@ -112,7 +111,23 @@ ClioApplication::run(bool const useNgWebServer)
     auto const dosguardWeights = web::dosguard::Weights::make(config_);
     auto dosGuard = web::dosguard::DOSGuard{config_, whitelistHandler, dosguardWeights};
     auto sweepHandler = web::dosguard::IntervalSweepHandler{config_, ioc, dosGuard};
+
     auto cache = data::LedgerCache{};
+    appStopper_.setOnStop([&cache, this](auto&&) {
+        // TODO(kuznetsss): move this into Stopper::makeOnStopCallback()
+        auto const cacheFilePath = config_.maybeValue<std::string>("cache.file.path");
+        if (not cacheFilePath.has_value()) {
+            return;
+        }
+
+        LOG(util::LogService::info()) << "Saving ledger cache to " << *cacheFilePath;
+        if (auto const [success, duration_ms] = util::timed([&]() { return cache.saveToFile(*cacheFilePath); });
+            success.has_value()) {
+            LOG(util::LogService::info()) << "Successfully saved ledger cache in " << duration_ms << " ms";
+        } else {
+            LOG(util::LogService::error()) << "Error saving LedgerCache to file";
+        }
+    });
 
     // Interface to the database
     auto backend = data::makeBackend(config_, cache);
@@ -142,20 +157,12 @@ ClioApplication::run(bool const useNgWebServer)
     // ETL uses the balancer to extract data.
     // The server uses the balancer to forward RPCs to a rippled node.
     // The balancer itself publishes to streams (transactions_proposed and accounts_proposed)
-    auto balancer = [&] -> std::shared_ptr<etlng::LoadBalancerInterface> {
+    auto balancer = etl::LoadBalancer::makeLoadBalancer(
-        if (config_.get<bool>("__ng_etl")) {
+        config_, ioc, backend, subscriptions, std::make_unique<util::MTRandomGenerator>(), ledgers
-            return etlng::LoadBalancer::makeLoadBalancer(
+    );
-                config_, ioc, backend, subscriptions, std::make_unique<util::MTRandomGenerator>(), ledgers
-            );
-        }
-
-        return etl::LoadBalancer::makeLoadBalancer(
-            config_, ioc, backend, subscriptions, std::make_unique<util::MTRandomGenerator>(), ledgers
-        );
-    }();
 
     // ETL is responsible for writing and publishing to streams. In read-only mode, ETL only publishes
-    auto etl = etl::ETLService::makeETLService(config_, ioc, ctx, backend, subscriptions, balancer, ledgers);
+    auto etl = etl::ETLService::makeETLService(config_, ctx, backend, subscriptions, balancer, ledgers);
 
     auto workQueue = rpc::WorkQueue::makeWorkQueue(config_);
     auto counters = rpc::Counters::makeCounters(workQueue);

src/app/Stopper.hpp

@@ -20,8 +20,8 @@
 #pragma once
 
 #include "data/BackendInterface.hpp"
-#include "etlng/ETLServiceInterface.hpp"
+#include "etl/ETLServiceInterface.hpp"
-#include "etlng/LoadBalancerInterface.hpp"
+#include "etl/LoadBalancerInterface.hpp"
 #include "feed/SubscriptionManagerInterface.hpp"
 #include "util/CoroutineGroup.hpp"
 #include "util/log/Logger.hpp"
@@ -78,8 +78,8 @@ public:
     static std::function<void(boost::asio::yield_context)>
     makeOnStopCallback(
         ServerType& server,
-        etlng::LoadBalancerInterface& balancer,
+        etl::LoadBalancerInterface& balancer,
-        etlng::ETLServiceInterface& etl,
+        etl::ETLServiceInterface& etl,
         feed::SubscriptionManagerInterface& subscriptions,
         data::BackendInterface& backend,
         boost::asio::io_context& ioc

src/data/AmendmentCenter.hpp

@@ -147,6 +147,11 @@ struct Amendments {
     REGISTER(fixAMMClawbackRounding);
     REGISTER(fixMPTDeliveredAmount);
     REGISTER(fixPriceOracleOrder);
+    REGISTER(DynamicMPT);
+    REGISTER(fixDelegateV1_1);
+    REGISTER(fixDirectoryLimit);
+    REGISTER(fixIncludeKeyletFields);
+    REGISTER(fixTokenEscrowV1);
 
     // Obsolete but supported by libxrpl
     REGISTER(CryptoConditionsSuite);

src/data/BackendFactory.hpp

@@ -21,6 +21,7 @@
 
 #include "data/BackendInterface.hpp"
 #include "data/CassandraBackend.hpp"
+#include "data/KeyspaceBackend.hpp"
 #include "data/LedgerCacheInterface.hpp"
 #include "data/cassandra/SettingsProvider.hpp"
 #include "util/config/ConfigDefinition.hpp"
@@ -45,6 +46,7 @@ namespace data {
 inline std::shared_ptr<BackendInterface>
 makeBackend(util::config::ClioConfigDefinition const& config, data::LedgerCacheInterface& cache)
 {
+    using namespace cassandra::impl;
     static util::Logger const log{"Backend"};  // NOLINT(readability-identifier-naming)
     LOG(log.info()) << "Constructing BackendInterface";
 
@@ -55,9 +57,15 @@ makeBackend(util::config::ClioConfigDefinition const& config, data::LedgerCacheI
 
     if (boost::iequals(type, "cassandra")) {
         auto const cfg = config.getObject("database." + type);
-        backend = std::make_shared<data::cassandra::CassandraBackend>(
+        if (providerFromString(cfg.getValueView("provider").asString()) == Provider::Keyspace) {
-            data::cassandra::SettingsProvider{cfg}, cache, readOnly
+            backend = std::make_shared<data::cassandra::KeyspaceBackend>(
-        );
+                data::cassandra::SettingsProvider{cfg}, cache, readOnly
+            );
+        } else {
+            backend = std::make_shared<data::cassandra::CassandraBackend>(
+                data::cassandra::SettingsProvider{cfg}, cache, readOnly
+            );
+        }
     }
 
     if (!backend)

src/data/BackendInterface.cpp

@@ -270,7 +270,7 @@ BackendInterface::updateRange(uint32_t newMax)
 {
     std::scoped_lock const lck(rngMtx_);
 
-    if (range_.has_value() && newMax < range_->maxSequence) {
+    if (range_.has_value() and newMax < range_->maxSequence) {
         ASSERT(
             false,
             "Range shouldn't exist yet or newMax should be at least range->maxSequence. newMax = {}, "
@@ -280,11 +280,14 @@ BackendInterface::updateRange(uint32_t newMax)
         );
     }
 
-    if (!range_.has_value()) {
+    updateRangeImpl(newMax);
-        range_ = {.minSequence = newMax, .maxSequence = newMax};
+}
-    } else {
+
-        range_->maxSequence = newMax;
+void
-    }
+BackendInterface::forceUpdateRange(uint32_t newMax)
+{
+    std::scoped_lock const lck(rngMtx_);
+    updateRangeImpl(newMax);
 }
 
 void
@@ -410,4 +413,14 @@ BackendInterface::fetchFees(std::uint32_t const seq, boost::asio::yield_context
     return fees;
 }
 
+void
+BackendInterface::updateRangeImpl(uint32_t newMax)
+{
+    if (!range_.has_value()) {
+        range_ = {.minSequence = newMax, .maxSequence = newMax};
+    } else {
+        range_->maxSequence = newMax;
+    }
+}
+
 }  // namespace data

src/data/BackendInterface.hpp

@@ -249,6 +249,15 @@ public:
     void
     updateRange(uint32_t newMax);
 
+    /**
+     * @brief Updates the range of sequences that are stored in the DB without any checks
+     * @note In the most cases you should use updateRange() instead
+     *
+     * @param newMax The new maximum sequence available
+     */
+    void
+    forceUpdateRange(uint32_t newMax);
+
     /**
      * @brief Sets the range of sequences that are stored in the DB.
      *
@@ -295,7 +304,7 @@ public:
      * @param account The account to fetch transactions for
      * @param limit The maximum number of transactions per result page
      * @param forward Whether to fetch the page forwards or backwards from the given cursor
-     * @param cursor The cursor to resume fetching from
+     * @param txnCursor The cursor to resume fetching from
      * @param yield The coroutine context
      * @return Results and a cursor to resume from
      */
@@ -304,7 +313,7 @@ public:
         ripple::AccountID const& account,
         std::uint32_t limit,
         bool forward,
-        std::optional<TransactionsCursor> const& cursor,
+        std::optional<TransactionsCursor> const& txnCursor,
         boost::asio::yield_context yield
     ) const = 0;
 
@@ -776,6 +785,9 @@ private:
      */
     virtual bool
     doFinishWrites() = 0;
+
+    void
+    updateRangeImpl(uint32_t newMax);
 };
 
 }  // namespace data

src/data/CMakeLists.txt

@@ -14,6 +14,9 @@ target_sources(
           cassandra/impl/SslContext.cpp
           cassandra/Handle.cpp
           cassandra/SettingsProvider.cpp
+          impl/InputFile.cpp
+          impl/LedgerCacheFile.cpp
+          impl/OutputFile.cpp
 )
 
 target_link_libraries(clio_data PUBLIC cassandra-cpp-driver::cassandra-cpp-driver clio_util)

src/data/KeyspaceBackend.hpp

@@ -0,0 +1,309 @@
+//------------------------------------------------------------------------------
+/*
+    This file is part of clio: https://github.com/XRPLF/clio
+    Copyright (c) 2025, the clio developers.
+
+    Permission to use, copy, modify, and distribute this software for any
+    purpose with or without fee is hereby granted, provided that the above
+    copyright notice and this permission notice appear in all copies.
+
+    THE  SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+    WITH  REGARD  TO  THIS  SOFTWARE  INCLUDING  ALL  IMPLIED  WARRANTIES  OF
+    MERCHANTABILITY  AND  FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+    ANY  SPECIAL,  DIRECT,  INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+    WHATSOEVER  RESULTING  FROM  LOSS  OF USE, DATA OR PROFITS, WHETHER IN AN
+    ACTION  OF  CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+    OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+*/
+//==============================================================================
+
+#pragma once
+
+#include "data/LedgerHeaderCache.hpp"
+#include "data/Types.hpp"
+#include "data/cassandra/CassandraBackendFamily.hpp"
+#include "data/cassandra/Concepts.hpp"
+#include "data/cassandra/KeyspaceSchema.hpp"
+#include "data/cassandra/SettingsProvider.hpp"
+#include "data/cassandra/Types.hpp"
+#include "data/cassandra/impl/ExecutionStrategy.hpp"
+#include "util/Assert.hpp"
+#include "util/log/Logger.hpp"
+
+#include <boost/asio/spawn.hpp>
+#include <boost/json/object.hpp>
+#include <boost/uuid/string_generator.hpp>
+#include <boost/uuid/uuid.hpp>
+#include <cassandra.h>
+#include <fmt/format.h>
+#include <xrpl/basics/Blob.h>
+#include <xrpl/basics/base_uint.h>
+#include <xrpl/basics/strHex.h>
+#include <xrpl/protocol/AccountID.h>
+#include <xrpl/protocol/Indexes.h>
+#include <xrpl/protocol/LedgerHeader.h>
+#include <xrpl/protocol/nft.h>
+
+#include <cstddef>
+#include <cstdint>
+#include <iterator>
+#include <optional>
+#include <stdexcept>
+#include <utility>
+#include <vector>
+
+namespace data::cassandra {
+
+/**
+ * @brief Implements @ref CassandraBackendFamily for Keyspace
+ *
+ * @tparam SettingsProviderType The settings provider type
+ * @tparam ExecutionStrategyType The execution strategy type
+ * @tparam FetchLedgerCacheType The ledger header cache type
+ */
+template <
+    SomeSettingsProvider SettingsProviderType,
+    SomeExecutionStrategy ExecutionStrategyType,
+    typename FetchLedgerCacheType = FetchLedgerCache>
+class BasicKeyspaceBackend : public CassandraBackendFamily<
+                                 SettingsProviderType,
+                                 ExecutionStrategyType,
+                                 KeyspaceSchema<SettingsProviderType>,
+                                 FetchLedgerCacheType> {
+    using DefaultCassandraFamily = CassandraBackendFamily<
+        SettingsProviderType,
+        ExecutionStrategyType,
+        KeyspaceSchema<SettingsProviderType>,
+        FetchLedgerCacheType>;
+
+    using DefaultCassandraFamily::executor_;
+    using DefaultCassandraFamily::ledgerSequence_;
+    using DefaultCassandraFamily::log_;
+    using DefaultCassandraFamily::range_;
+    using DefaultCassandraFamily::schema_;
+
+public:
+    /**
+     * @brief Inherit the constructors of the base class.
+     */
+    using DefaultCassandraFamily::DefaultCassandraFamily;
+
+    /**
+     * @brief Move constructor is deleted because handle_ is shared by reference with executor
+     */
+    BasicKeyspaceBackend(BasicKeyspaceBackend&&) = delete;
+
+    bool
+    doFinishWrites() override
+    {
+        this->waitForWritesToFinish();
+
+        // !range_.has_value() means the table 'ledger_range' is not populated;
+        // This would be the first write to the table.
+        // In this case, insert both min_sequence/max_sequence range into the table.
+        if (not range_.has_value()) {
+            executor_.writeSync(schema_->insertLedgerRange, /* isLatestLedger =*/false, ledgerSequence_);
+            executor_.writeSync(schema_->insertLedgerRange, /* isLatestLedger =*/true, ledgerSequence_);
+        }
+
+        if (not this->executeSyncUpdate(schema_->updateLedgerRange.bind(ledgerSequence_, true, ledgerSequence_ - 1))) {
+            log_.warn() << "Update failed for ledger " << ledgerSequence_;
+            return false;
+        }
+
+        log_.info() << "Committed ledger " << ledgerSequence_;
+        return true;
+    }
+
+    NFTsAndCursor
+    fetchNFTsByIssuer(
+        ripple::AccountID const& issuer,
+        std::optional<std::uint32_t> const& taxon,
+        std::uint32_t const ledgerSequence,
+        std::uint32_t const limit,
+        std::optional<ripple::uint256> const& cursorIn,
+        boost::asio::yield_context yield
+    ) const override
+    {
+        std::vector<ripple::uint256> nftIDs;
+        if (taxon.has_value()) {
+            // Keyspace and ScyllaDB uses the same logic for taxon-filtered queries
+            nftIDs = fetchNFTIDsByTaxon(issuer, *taxon, limit, cursorIn, yield);
+        } else {
+            // Amazon Keyspaces Workflow for non-taxon queries
+            auto const startTaxon = cursorIn.has_value() ? ripple::nft::toUInt32(ripple::nft::getTaxon(*cursorIn)) : 0;
+            auto const startTokenID = cursorIn.value_or(ripple::uint256(0));
+
+            Statement const firstQuery = schema_->selectNFTIDsByIssuerTaxon.bind(issuer);
+            firstQuery.bindAt(1, startTaxon);
+            firstQuery.bindAt(2, startTokenID);
+            firstQuery.bindAt(3, Limit{limit});
+
+            auto const firstRes = executor_.read(yield, firstQuery);
+            if (firstRes.has_value()) {
+                for (auto const [nftID] : extract<ripple::uint256>(*firstRes))
+                    nftIDs.push_back(nftID);
+            }
+
+            if (nftIDs.size() < limit) {
+                auto const remainingLimit = limit - nftIDs.size();
+                Statement const secondQuery = schema_->selectNFTsAfterTaxonKeyspaces.bind(issuer);
+                secondQuery.bindAt(1, startTaxon);
+                secondQuery.bindAt(2, Limit{remainingLimit});
+
+                auto const secondRes = executor_.read(yield, secondQuery);
+                if (secondRes.has_value()) {
+                    for (auto const [nftID] : extract<ripple::uint256>(*secondRes))
+                        nftIDs.push_back(nftID);
+                }
+            }
+        }
+        return populateNFTsAndCreateCursor(nftIDs, ledgerSequence, limit, yield);
+    }
+
+    /**
+     * @brief (Unsupported in Keyspaces) Fetches account root object indexes by page.
+     * @note Loading the cache by enumerating all accounts is currently unsupported by the AWS Keyspaces backend.
+     * This function's logic relies on "PER PARTITION LIMIT 1", which Keyspaces does not support, and there is
+     * no efficient alternative. This is acceptable as the cache is primarily loaded via diffs. Calling this
+     * function will throw an exception.
+     *
+     * @param number The total number of accounts to fetch.
+     * @param pageSize The maximum number of accounts per page.
+     * @param seq The accounts need to exist at this ledger sequence.
+     * @param yield The coroutine context.
+     * @return A vector of ripple::uint256 representing the account root hashes.
+     */
+    std::vector<ripple::uint256>
+    fetchAccountRoots(
+        [[maybe_unused]] std::uint32_t number,
+        [[maybe_unused]] std::uint32_t pageSize,
+        [[maybe_unused]] std::uint32_t seq,
+        [[maybe_unused]] boost::asio::yield_context yield
+    ) const override
+    {
+        ASSERT(false, "Fetching account roots is not supported by the Keyspaces backend.");
+        std::unreachable();
+    }
+
+private:
+    std::vector<ripple::uint256>
+    fetchNFTIDsByTaxon(
+        ripple::AccountID const& issuer,
+        std::uint32_t const taxon,
+        std::uint32_t const limit,
+        std::optional<ripple::uint256> const& cursorIn,
+        boost::asio::yield_context yield
+    ) const
+    {
+        std::vector<ripple::uint256> nftIDs;
+        Statement const statement = schema_->selectNFTIDsByIssuerTaxon.bind(issuer);
+        statement.bindAt(1, taxon);
+        statement.bindAt(2, cursorIn.value_or(ripple::uint256(0)));
+        statement.bindAt(3, Limit{limit});
+
+        auto const res = executor_.read(yield, statement);
+        if (res.has_value() && res->hasRows()) {
+            for (auto const [nftID] : extract<ripple::uint256>(*res))
+                nftIDs.push_back(nftID);
+        }
+        return nftIDs;
+    }
+
+    std::vector<ripple::uint256>
+    fetchNFTIDsWithoutTaxon(
+        ripple::AccountID const& issuer,
+        std::uint32_t const limit,
+        std::optional<ripple::uint256> const& cursorIn,
+        boost::asio::yield_context yield
+    ) const
+    {
+        std::vector<ripple::uint256> nftIDs;
+
+        auto const startTaxon = cursorIn.has_value() ? ripple::nft::toUInt32(ripple::nft::getTaxon(*cursorIn)) : 0;
+        auto const startTokenID = cursorIn.value_or(ripple::uint256(0));
+
+        Statement firstQuery = schema_->selectNFTIDsByIssuerTaxon.bind(issuer);
+        firstQuery.bindAt(1, startTaxon);
+        firstQuery.bindAt(2, startTokenID);
+        firstQuery.bindAt(3, Limit{limit});
+
+        auto const firstRes = executor_.read(yield, firstQuery);
+        if (firstRes.has_value()) {
+            for (auto const [nftID] : extract<ripple::uint256>(*firstRes))
+                nftIDs.push_back(nftID);
+        }
+
+        if (nftIDs.size() < limit) {
+            auto const remainingLimit = limit - nftIDs.size();
+            Statement secondQuery = schema_->selectNFTsAfterTaxonKeyspaces.bind(issuer);
+            secondQuery.bindAt(1, startTaxon);
+            secondQuery.bindAt(2, Limit{remainingLimit});
+
+            auto const secondRes = executor_.read(yield, secondQuery);
+            if (secondRes.has_value()) {
+                for (auto const [nftID] : extract<ripple::uint256>(*secondRes))
+                    nftIDs.push_back(nftID);
+            }
+        }
+        return nftIDs;
+    }
+
+    /**
+     * @brief Takes a list of NFT IDs, fetches their full data, and assembles the final result with a cursor.
+     */
+    NFTsAndCursor
+    populateNFTsAndCreateCursor(
+        std::vector<ripple::uint256> const& nftIDs,
+        std::uint32_t const ledgerSequence,
+        std::uint32_t const limit,
+        boost::asio::yield_context yield
+    ) const
+    {
+        if (nftIDs.empty()) {
+            LOG(log_.debug()) << "No rows returned";
+            return {};
+        }
+
+        NFTsAndCursor ret;
+        if (nftIDs.size() == limit)
+            ret.cursor = nftIDs.back();
+
+        // Prepare and execute queries to fetch NFT info and URIs in parallel.
+        std::vector<Statement> selectNFTStatements;
+        selectNFTStatements.reserve(nftIDs.size());
+        std::transform(
+            std::cbegin(nftIDs), std::cend(nftIDs), std::back_inserter(selectNFTStatements), [&](auto const& nftID) {
+                return schema_->selectNFT.bind(nftID, ledgerSequence);
+            }
+        );
+
+        std::vector<Statement> selectNFTURIStatements;
+        selectNFTURIStatements.reserve(nftIDs.size());
+        std::transform(
+            std::cbegin(nftIDs), std::cend(nftIDs), std::back_inserter(selectNFTURIStatements), [&](auto const& nftID) {
+                return schema_->selectNFTURI.bind(nftID, ledgerSequence);
+            }
+        );
+
+        auto const nftInfos = executor_.readEach(yield, selectNFTStatements);
+        auto const nftUris = executor_.readEach(yield, selectNFTURIStatements);
+
+        // Combine the results into final NFT objects.
+        for (auto i = 0u; i < nftIDs.size(); ++i) {
+            if (auto const maybeRow = nftInfos[i].template get<uint32_t, ripple::AccountID, bool>();
+                maybeRow.has_value()) {
+                auto [seq, owner, isBurned] = *maybeRow;
+                NFT nft(nftIDs[i], seq, owner, isBurned);
+                if (auto const maybeUri = nftUris[i].template get<ripple::Blob>(); maybeUri.has_value())
+                    nft.uri = *maybeUri;
+                ret.nfts.push_back(nft);
+            }
+        }
+        return ret;
+    }
+};
+
+using KeyspaceBackend = BasicKeyspaceBackend<SettingsProvider, impl::DefaultExecutionStrategy<>>;
+
+}  // namespace data::cassandra

src/data/LedgerCache.cpp

@@ -20,16 +20,22 @@
 #include "data/LedgerCache.hpp"
 
 #include "data/Types.hpp"
-#include "etlng/Models.hpp"
+#include "data/impl/LedgerCacheFile.hpp"
+#include "etl/Models.hpp"
 #include "util/Assert.hpp"
 
 #include <xrpl/basics/base_uint.h>
 
 #include <cstddef>
 #include <cstdint>
+#include <cstdlib>
+#include <cstring>
+#include <map>
 #include <mutex>
 #include <optional>
 #include <shared_mutex>
+#include <string>
+#include <utility>
 #include <vector>
 
 namespace data {
@@ -89,7 +95,7 @@ LedgerCache::update(std::vector<LedgerObject> const& objs, uint32_t seq, bool is
 }
 
 void
-LedgerCache::update(std::vector<etlng::model::Object> const& objs, uint32_t seq)
+LedgerCache::update(std::vector<etl::model::Object> const& objs, uint32_t seq)
 {
     if (disabled_)
         return;
@@ -251,4 +257,34 @@ LedgerCache::getSuccessorHitRate() const
     return static_cast<float>(successorHitCounter_.get().value()) / successorReqCounter_.get().value();
 }
 
+std::expected<void, std::string>
+LedgerCache::saveToFile(std::string const& path) const
+{
+    if (not isFull()) {
+        return std::unexpected{"Ledger cache is not full"};
+    }
+
+    impl::LedgerCacheFile file{path};
+    std::unique_lock const lock{mtx_};
+    impl::LedgerCacheFile::DataView const data{.latestSeq = latestSeq_, .map = map_, .deleted = deleted_};
+    return file.write(data);
+}
+
+std::expected<void, std::string>
+LedgerCache::loadFromFile(std::string const& path, uint32_t minLatestSequence)
+{
+    impl::LedgerCacheFile file{path};
+    auto data = file.read(minLatestSequence);
+    if (not data.has_value()) {
+        return std::unexpected(std::move(data).error());
+    }
+    auto [latestSeq, map, deleted] = std::move(data).value();
+    std::unique_lock const lock{mtx_};
+    latestSeq_ = latestSeq;
+    map_ = std::move(map);
+    deleted_ = std::move(deleted);
+    full_ = true;
+    return {};
+}
+
 }  // namespace data

src/data/LedgerCache.hpp

@@ -21,7 +21,7 @@
 
 #include "data/LedgerCacheInterface.hpp"
 #include "data/Types.hpp"
-#include "etlng/Models.hpp"
+#include "etl/Models.hpp"
 #include "util/prometheus/Bool.hpp"
 #include "util/prometheus/Counter.hpp"
 #include "util/prometheus/Label.hpp"
@@ -37,6 +37,7 @@
 #include <map>
 #include <optional>
 #include <shared_mutex>
+#include <string>
 #include <unordered_set>
 #include <vector>
 
@@ -46,11 +47,16 @@ namespace data {
  * @brief Cache for an entire ledger.
  */
 class LedgerCache : public LedgerCacheInterface {
+public:
+    /** @brief An entry of the cache */
     struct CacheEntry {
         uint32_t seq = 0;
         Blob blob;
     };
 
+    using CacheMap = std::map<ripple::uint256, CacheEntry>;
+
+private:
     // counters for fetchLedgerObject(s) hit rate
     std::reference_wrapper<util::prometheus::CounterInt> objectReqCounter_{PrometheusService::counterInt(
         "ledger_cache_counter_total_number",
@@ -73,8 +79,8 @@ class LedgerCache : public LedgerCacheInterface {
         util::prometheus::Labels({{"type", "cache_hit"}, {"fetch", "successor_key"}})
     )};
 
-    std::map<ripple::uint256, CacheEntry> map_;
+    CacheMap map_;
-    std::map<ripple::uint256, CacheEntry> deleted_;
+    CacheMap deleted_;
 
     mutable std::shared_mutex mtx_;
     std::condition_variable_any cv_;
@@ -98,7 +104,7 @@ public:
     update(std::vector<LedgerObject> const& objs, uint32_t seq, bool isBackground) override;
 
     void
-    update(std::vector<etlng::model::Object> const& objs, uint32_t seq) override;
+    update(std::vector<etl::model::Object> const& objs, uint32_t seq) override;
 
     std::optional<Blob>
     get(ripple::uint256 const& key, uint32_t seq) const override;
@@ -138,6 +144,19 @@ public:
 
     void
     waitUntilCacheContainsSeq(uint32_t seq) override;
+
+    /**
+     * @brief Save the cache to file
+     * @note This operation takes about 7 seconds and it keeps mtx_ exclusively locked
+     *
+     * @param path The file path to save the cache to
+     * @return An error as a string if any
+     */
+    std::expected<void, std::string>
+    saveToFile(std::string const& path) const;
+
+    std::expected<void, std::string>
+    loadFromFile(std::string const& path, uint32_t minLatestSequence) override;
 };
 
 }  // namespace data

src/data/LedgerCacheInterface.hpp

@@ -20,14 +20,16 @@
 #pragma once
 
 #include "data/Types.hpp"
-#include "etlng/Models.hpp"
+#include "etl/Models.hpp"
 
 #include <xrpl/basics/base_uint.h>
 #include <xrpl/basics/hardened_hash.h>
 
 #include <cstddef>
 #include <cstdint>
+#include <expected>
 #include <optional>
+#include <string>
 #include <vector>
 
 namespace data {
@@ -63,7 +65,7 @@ public:
      * @param seq The sequence to update cache for
      */
     virtual void
-    update(std::vector<etlng::model::Object> const& objs, uint32_t seq) = 0;
+    update(std::vector<etl::model::Object> const& objs, uint32_t seq) = 0;
 
     /**
      * @brief Fetch a cached object by its key and sequence number.
@@ -168,6 +170,17 @@ public:
      */
     virtual void
     waitUntilCacheContainsSeq(uint32_t seq) = 0;
+
+    /**
+     * @brief Load the cache from file
+     * @note This operation takes about 7 seconds and it keeps mtx_ exclusively locked
+     *
+     * @param path The file path to load data from
+     * @param minLatestSequence The minimum allowed value of the latestLedgerSequence in cache file
+     * @return An error as a string if any
+     */
+    [[nodiscard]] virtual std::expected<void, std::string>
+    loadFromFile(std::string const& path, uint32_t minLatestSequence) = 0;
 };
 
 }  // namespace data

src/data/README.md

@@ -1,8 +1,10 @@
-# Backend
+# Backend
+
+@page "backend" Backend
 
 The backend of Clio is responsible for handling the proper reading and writing of past ledger data from and to a given database. Currently, Cassandra and ScyllaDB are the only supported databases that are production-ready.
 
-To support additional database types, you can create new classes that implement the virtual methods in [BackendInterface.h](https://github.com/XRPLF/clio/blob/develop/src/data/BackendInterface.hpp). Then, leveraging the Factory Object Design Pattern, modify [BackendFactory.h](https://github.com/XRPLF/clio/blob/develop/src/data/BackendFactory.hpp) with logic that returns the new database interface if the relevant `type` is provided in Clio's configuration file.
+To support additional database types, you can create new classes that implement the virtual methods in [BackendInterface.hpp](https://github.com/XRPLF/clio/blob/develop/src/data/BackendInterface.hpp). Then, leveraging the Factory Object Design Pattern, modify [BackendFactory.hpp](https://github.com/XRPLF/clio/blob/develop/src/data/BackendFactory.hpp) with logic that returns the new database interface if the relevant `type` is provided in Clio's configuration file.
 
 ## Data Model
 

src/data/Types.hpp

@@ -247,6 +247,9 @@ struct MPTHoldersAndCursor {
 struct LedgerRange {
     std::uint32_t minSequence = 0;
     std::uint32_t maxSequence = 0;
+
+    bool
+    operator==(LedgerRange const&) const = default;
 };
 
 /**

src/data/cassandra/CassandraBackendFamily.hpp

@@ -0,0 +1,975 @@
+//------------------------------------------------------------------------------
+/*
+    This file is part of clio: https://github.com/XRPLF/clio
+    Copyright (c) 2025, the clio developers.
+
+    Permission to use, copy, modify, and distribute this software for any
+    purpose with or without fee is hereby granted, provided that the above
+    copyright notice and this permission notice appear in all copies.
+
+    THE  SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+    WITH  REGARD  TO  THIS  SOFTWARE  INCLUDING  ALL  IMPLIED  WARRANTIES  OF
+    MERCHANTABILITY  AND  FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+    ANY  SPECIAL,  DIRECT,  INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+    WHATSOEVER  RESULTING  FROM  LOSS  OF USE, DATA OR PROFITS, WHETHER IN AN
+    ACTION  OF  CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+    OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+*/
+//==============================================================================
+
+#pragma once
+
+#include "data/BackendInterface.hpp"
+#include "data/DBHelpers.hpp"
+#include "data/LedgerCacheInterface.hpp"
+#include "data/LedgerHeaderCache.hpp"
+#include "data/Types.hpp"
+#include "data/cassandra/Concepts.hpp"
+#include "data/cassandra/Handle.hpp"
+#include "data/cassandra/Types.hpp"
+#include "data/cassandra/impl/ExecutionStrategy.hpp"
+#include "util/Assert.hpp"
+#include "util/LedgerUtils.hpp"
+#include "util/Profiler.hpp"
+#include "util/log/Logger.hpp"
+
+#include <boost/asio/spawn.hpp>
+#include <boost/json/object.hpp>
+#include <boost/uuid/string_generator.hpp>
+#include <boost/uuid/uuid.hpp>
+#include <cassandra.h>
+#include <fmt/format.h>
+#include <xrpl/basics/Blob.h>
+#include <xrpl/basics/base_uint.h>
+#include <xrpl/basics/strHex.h>
+#include <xrpl/protocol/AccountID.h>
+#include <xrpl/protocol/Indexes.h>
+#include <xrpl/protocol/LedgerHeader.h>
+#include <xrpl/protocol/nft.h>
+
+#include <algorithm>
+#include <atomic>
+#include <chrono>
+#include <cstddef>
+#include <cstdint>
+#include <iterator>
+#include <limits>
+#include <optional>
+#include <stdexcept>
+#include <string>
+#include <tuple>
+#include <utility>
+#include <vector>
+
+class CacheBackendCassandraTest;
+
+namespace data::cassandra {
+
+/**
+ * @brief Implements @ref BackendInterface for Cassandra/ScyllaDB/Keyspace.
+ *
+ * Note: This is a safer and more correct rewrite of the original implementation of the backend.
+ *
+ * @tparam SettingsProviderType The settings provider type
+ * @tparam ExecutionStrategyType The execution strategy type
+ * @tparam SchemaType The Schema type
+ * @tparam FetchLedgerCacheType The ledger header cache type
+ */
+template <
+    SomeSettingsProvider SettingsProviderType,
+    SomeExecutionStrategy ExecutionStrategyType,
+    typename SchemaType,
+    typename FetchLedgerCacheType = FetchLedgerCache>
+class CassandraBackendFamily : public BackendInterface {
+protected:
+    util::Logger log_{"Backend"};
+
+    SettingsProviderType settingsProvider_;
+    SchemaType schema_;
+    std::atomic_uint32_t ledgerSequence_ = 0u;
+    friend class ::CacheBackendCassandraTest;
+
+    Handle handle_;
+
+    // have to be mutable because BackendInterface constness :(
+    mutable ExecutionStrategyType executor_;
+    // TODO: move to interface level
+    mutable FetchLedgerCacheType ledgerCache_{};
+
+public:
+    /**
+     * @brief Create a new cassandra/scylla backend instance.
+     *
+     * @param settingsProvider The settings provider
+     * @param cache The ledger cache
+     * @param readOnly Whether the database should be in readonly mode
+     */
+    CassandraBackendFamily(SettingsProviderType settingsProvider, data::LedgerCacheInterface& cache, bool readOnly)
+        : BackendInterface(cache)
+        , settingsProvider_{std::move(settingsProvider)}
+        , schema_{settingsProvider_}
+        , handle_{settingsProvider_.getSettings()}
+        , executor_{settingsProvider_.getSettings(), handle_}
+    {
+        if (auto const res = handle_.connect(); not res.has_value())
+            throw std::runtime_error("Could not connect to database: " + res.error());
+
+        if (not readOnly) {
+            if (auto const res = handle_.execute(schema_.createKeyspace); not res.has_value()) {
+                // on datastax, creation of keyspaces can be configured to only be done thru the admin
+                // interface. this does not mean that the keyspace does not already exist tho.
+                if (res.error().code() != CASS_ERROR_SERVER_UNAUTHORIZED)
+                    throw std::runtime_error("Could not create keyspace: " + res.error());
+            }
+
+            if (auto const res = handle_.executeEach(schema_.createSchema); not res.has_value())
+                throw std::runtime_error("Could not create schema: " + res.error());
+        }
+
+        try {
+            schema_.prepareStatements(handle_);
+        } catch (std::runtime_error const& ex) {
+            auto const error = fmt::format(
+                "Failed to prepare the statements: {}; readOnly: {}. ReadOnly should be turned off or another Clio "
+                "node with write access to DB should be started first.",
+                ex.what(),
+                readOnly
+            );
+            LOG(log_.error()) << error;
+            throw std::runtime_error(error);
+        }
+        LOG(log_.info()) << "Created (revamped) CassandraBackend";
+    }
+
+    /*
+     * @brief Move constructor is deleted because handle_ is shared by reference with executor
+     */
+    CassandraBackendFamily(CassandraBackendFamily&&) = delete;
+
+    TransactionsAndCursor
+    fetchAccountTransactions(
+        ripple::AccountID const& account,
+        std::uint32_t const limit,
+        bool forward,
+        std::optional<TransactionsCursor> const& txnCursor,
+        boost::asio::yield_context yield
+    ) const override
+    {
+        auto rng = fetchLedgerRange();
+        if (!rng)
+            return {.txns = {}, .cursor = {}};
+
+        Statement const statement = [this, forward, &account]() {
+            if (forward)
+                return schema_->selectAccountTxForward.bind(account);
+
+            return schema_->selectAccountTx.bind(account);
+        }();
+
+        auto cursor = txnCursor;
+        if (cursor) {
+            statement.bindAt(1, cursor->asTuple());
+            LOG(log_.debug()) << "account = " << ripple::strHex(account) << " tuple = " << cursor->ledgerSequence
+                              << cursor->transactionIndex;
+        } else {
+            auto const seq = forward ? rng->minSequence : rng->maxSequence;
+            auto const placeHolder = forward ? 0u : std::numeric_limits<std::uint32_t>::max();
+
+            statement.bindAt(1, std::make_tuple(placeHolder, placeHolder));
+            LOG(log_.debug()) << "account = " << ripple::strHex(account) << " idx = " << seq
+                              << " tuple = " << placeHolder;
+        }
+
+        // FIXME: Limit is a hack to support uint32_t properly for the time
+        // being. Should be removed later and schema updated to use proper
+        // types.
+        statement.bindAt(2, Limit{limit});
+        auto const res = executor_.read(yield, statement);
+        auto const& results = res.value();
+        if (not results.hasRows()) {
+            LOG(log_.debug()) << "No rows returned";
+            return {};
+        }
+
+        std::vector<ripple::uint256> hashes = {};
+        auto numRows = results.numRows();
+        LOG(log_.info()) << "num_rows = " << numRows;
+
+        for (auto [hash, data] : extract<ripple::uint256, std::tuple<uint32_t, uint32_t>>(results)) {
+            hashes.push_back(hash);
+            if (--numRows == 0) {
+                LOG(log_.debug()) << "Setting cursor";
+                cursor = data;
+            }
+        }
+
+        auto const txns = fetchTransactions(hashes, yield);
+        LOG(log_.debug()) << "Txns = " << txns.size();
+
+        if (txns.size() == limit) {
+            LOG(log_.debug()) << "Returning cursor";
+            return {txns, cursor};
+        }
+
+        return {txns, {}};
+    }
+
+    void
+    waitForWritesToFinish() override
+    {
+        executor_.sync();
+    }
+
+    void
+    writeLedger(ripple::LedgerHeader const& ledgerHeader, std::string&& blob) override
+    {
+        executor_.write(schema_->insertLedgerHeader, ledgerHeader.seq, std::move(blob));
+
+        executor_.write(schema_->insertLedgerHash, ledgerHeader.hash, ledgerHeader.seq);
+
+        ledgerSequence_ = ledgerHeader.seq;
+    }
+
+    std::optional<std::uint32_t>
+    fetchLatestLedgerSequence(boost::asio::yield_context yield) const override
+    {
+        if (auto const res = executor_.read(yield, schema_->selectLatestLedger); res.has_value()) {
+            if (auto const& rows = *res; rows) {
+                if (auto const maybeRow = rows.template get<uint32_t>(); maybeRow.has_value())
+                    return maybeRow;
+
+                LOG(log_.error()) << "Could not fetch latest ledger - no rows";
+                return std::nullopt;
+            }
+
+            LOG(log_.error()) << "Could not fetch latest ledger - no result";
+        } else {
+            LOG(log_.error()) << "Could not fetch latest ledger: " << res.error();
+        }
+
+        return std::nullopt;
+    }
+
+    std::optional<ripple::LedgerHeader>
+    fetchLedgerBySequence(std::uint32_t const sequence, boost::asio::yield_context yield) const override
+    {
+        if (auto const lock = ledgerCache_.get(); lock.has_value() && lock->seq == sequence)
+            return lock->ledger;
+
+        auto const res = executor_.read(yield, schema_->selectLedgerBySeq, sequence);
+        if (res) {
+            if (auto const& result = res.value(); result) {
+                if (auto const maybeValue = result.template get<std::vector<unsigned char>>(); maybeValue) {
+                    auto const header = util::deserializeHeader(ripple::makeSlice(*maybeValue));
+                    ledgerCache_.put(FetchLedgerCache::CacheEntry{header, sequence});
+                    return header;
+                }
+
+                LOG(log_.error()) << "Could not fetch ledger by sequence - no rows";
+                return std::nullopt;
+            }
+
+            LOG(log_.error()) << "Could not fetch ledger by sequence - no result";
+        } else {
+            LOG(log_.error()) << "Could not fetch ledger by sequence: " << res.error();
+        }
+
+        return std::nullopt;
+    }
+
+    std::optional<ripple::LedgerHeader>
+    fetchLedgerByHash(ripple::uint256 const& hash, boost::asio::yield_context yield) const override
+    {
+        if (auto const res = executor_.read(yield, schema_->selectLedgerByHash, hash); res) {
+            if (auto const& result = res.value(); result) {
+                if (auto const maybeValue = result.template get<uint32_t>(); maybeValue)
+                    return fetchLedgerBySequence(*maybeValue, yield);
+
+                LOG(log_.error()) << "Could not fetch ledger by hash - no rows";
+                return std::nullopt;
+            }
+
+            LOG(log_.error()) << "Could not fetch ledger by hash - no result";
+        } else {
+            LOG(log_.error()) << "Could not fetch ledger by hash: " << res.error();
+        }
+
+        return std::nullopt;
+    }
+
+    std::optional<LedgerRange>
+    hardFetchLedgerRange(boost::asio::yield_context yield) const override
+    {
+        auto const res = executor_.read(yield, schema_->selectLedgerRange);
+        if (res) {
+            auto const& results = res.value();
+            if (not results.hasRows()) {
+                LOG(log_.debug()) << "Could not fetch ledger range - no rows";
+                return std::nullopt;
+            }
+
+            // TODO: this is probably a good place to use user type in
+            // cassandra instead of having two rows with bool flag. or maybe at
+            // least use tuple<int, int>?
+            LedgerRange range;
+            std::size_t idx = 0;
+            for (auto [seq] : extract<uint32_t>(results)) {
+                if (idx == 0) {
+                    range.maxSequence = range.minSequence = seq;
+                } else if (idx == 1) {
+                    range.maxSequence = seq;
+                }
+
+                ++idx;
+            }
+
+            if (range.minSequence > range.maxSequence)
+                std::swap(range.minSequence, range.maxSequence);
+
+            LOG(log_.debug()) << "After hardFetchLedgerRange range is " << range.minSequence << ":"
+                              << range.maxSequence;
+            return range;
+        }
+        LOG(log_.error()) << "Could not fetch ledger range: " << res.error();
+
+        return std::nullopt;
+    }
+
+    std::vector<TransactionAndMetadata>
+    fetchAllTransactionsInLedger(std::uint32_t const ledgerSequence, boost::asio::yield_context yield) const override
+    {
+        auto hashes = fetchAllTransactionHashesInLedger(ledgerSequence, yield);
+        return fetchTransactions(hashes, yield);
+    }
+
+    std::vector<ripple::uint256>
+    fetchAllTransactionHashesInLedger(
+        std::uint32_t const ledgerSequence,
+        boost::asio::yield_context yield
+    ) const override
+    {
+        auto start = std::chrono::system_clock::now();
+        auto const res = executor_.read(yield, schema_->selectAllTransactionHashesInLedger, ledgerSequence);
+
+        if (not res) {
+            LOG(log_.error()) << "Could not fetch all transaction hashes: " << res.error();
+            return {};
+        }
+
+        auto const& result = res.value();
+        if (not result.hasRows()) {
+            LOG(log_.warn()) << "Could not fetch all transaction hashes - no rows; ledger = "
+                             << std::to_string(ledgerSequence);
+            return {};
+        }
+
+        std::vector<ripple::uint256> hashes;
+        for (auto [hash] : extract<ripple::uint256>(result))
+            hashes.push_back(std::move(hash));
+
+        auto end = std::chrono::system_clock::now();
+        LOG(log_.debug()) << "Fetched " << hashes.size() << " transaction hashes from database in "
+                          << std::chrono::duration_cast<std::chrono::milliseconds>(end - start).count()
+                          << " milliseconds";
+
+        return hashes;
+    }
+
+    std::optional<NFT>
+    fetchNFT(
+        ripple::uint256 const& tokenID,
+        std::uint32_t const ledgerSequence,
+        boost::asio::yield_context yield
+    ) const override
+    {
+        auto const res = executor_.read(yield, schema_->selectNFT, tokenID, ledgerSequence);
+        if (not res)
+            return std::nullopt;
+
+        if (auto const maybeRow = res->template get<uint32_t, ripple::AccountID, bool>(); maybeRow) {
+            auto [seq, owner, isBurned] = *maybeRow;
+            auto result = std::make_optional<NFT>(tokenID, seq, owner, isBurned);
+
+            // now fetch URI. Usually we will have the URI even for burned NFTs,
+            // but if the first ledger on this clio included NFTokenBurn
+            // transactions we will not have the URIs for any of those tokens.
+            // In any other case not having the URI indicates something went
+            // wrong with our data.
+            //
+            // TODO - in the future would be great for any handlers that use
+            // this could inject a warning in this case (the case of not having
+            // a URI because it was burned in the first ledger) to indicate that
+            // even though we are returning a blank URI, the NFT might have had
+            // one.
+            auto uriRes = executor_.read(yield, schema_->selectNFTURI, tokenID, ledgerSequence);
+            if (uriRes) {
+                if (auto const maybeUri = uriRes->template get<ripple::Blob>(); maybeUri)
+                    result->uri = *maybeUri;
+            }
+
+            return result;
+        }
+
+        LOG(log_.error()) << "Could not fetch NFT - no rows";
+        return std::nullopt;
+    }
+
+    TransactionsAndCursor
+    fetchNFTTransactions(
+        ripple::uint256 const& tokenID,
+        std::uint32_t const limit,
+        bool const forward,
+        std::optional<TransactionsCursor> const& cursorIn,
+        boost::asio::yield_context yield
+    ) const override
+    {
+        auto rng = fetchLedgerRange();
+        if (!rng)
+            return {.txns = {}, .cursor = {}};
+
+        Statement const statement = [this, forward, &tokenID]() {
+            if (forward)
+                return schema_->selectNFTTxForward.bind(tokenID);
+
+            return schema_->selectNFTTx.bind(tokenID);
+        }();
+
+        auto cursor = cursorIn;
+        if (cursor) {
+            statement.bindAt(1, cursor->asTuple());
+            LOG(log_.debug()) << "token_id = " << ripple::strHex(tokenID) << " tuple = " << cursor->ledgerSequence
+                              << cursor->transactionIndex;
+        } else {
+            auto const seq = forward ? rng->minSequence : rng->maxSequence;
+            auto const placeHolder = forward ? 0 : std::numeric_limits<std::uint32_t>::max();
+
+            statement.bindAt(1, std::make_tuple(placeHolder, placeHolder));
+            LOG(log_.debug()) << "token_id = " << ripple::strHex(tokenID) << " idx = " << seq
+                              << " tuple = " << placeHolder;
+        }
+
+        statement.bindAt(2, Limit{limit});
+
+        auto const res = executor_.read(yield, statement);
+        auto const& results = res.value();
+        if (not results.hasRows()) {
+            LOG(log_.debug()) << "No rows returned";
+            return {};
+        }
+
+        std::vector<ripple::uint256> hashes = {};
+        auto numRows = results.numRows();
+        LOG(log_.info()) << "num_rows = " << numRows;
+
+        for (auto [hash, data] : extract<ripple::uint256, std::tuple<uint32_t, uint32_t>>(results)) {
+            hashes.push_back(hash);
+            if (--numRows == 0) {
+                LOG(log_.debug()) << "Setting cursor";
+                cursor = data;
+
+                // forward queries by ledger/tx sequence `>=`
+                // so we have to advance the index by one
+                if (forward)
+                    ++cursor->transactionIndex;
+            }
+        }
+
+        auto const txns = fetchTransactions(hashes, yield);
+        LOG(log_.debug()) << "NFT Txns = " << txns.size();
+
+        if (txns.size() == limit) {
+            LOG(log_.debug()) << "Returning cursor";
+            return {txns, cursor};
+        }
+
+        return {txns, {}};
+    }
+
+    MPTHoldersAndCursor
+    fetchMPTHolders(
+        ripple::uint192 const& mptID,
+        std::uint32_t const limit,
+        std::optional<ripple::AccountID> const& cursorIn,
+        std::uint32_t const ledgerSequence,
+        boost::asio::yield_context yield
+    ) const override
+    {
+        auto const holderEntries = executor_.read(
+            yield, schema_->selectMPTHolders, mptID, cursorIn.value_or(ripple::AccountID(0)), Limit{limit}
+        );
+
+        auto const& holderResults = holderEntries.value();
+        if (not holderResults.hasRows()) {
+            LOG(log_.debug()) << "No rows returned";
+            return {};
+        }
+
+        std::vector<ripple::uint256> mptKeys;
+        std::optional<ripple::AccountID> cursor;
+        for (auto const [holder] : extract<ripple::AccountID>(holderResults)) {
+            mptKeys.push_back(ripple::keylet::mptoken(mptID, holder).key);
+            cursor = holder;
+        }
+
+        auto mptObjects = doFetchLedgerObjects(mptKeys, ledgerSequence, yield);
+
+        auto it = std::remove_if(mptObjects.begin(), mptObjects.end(), [](Blob const& mpt) { return mpt.empty(); });
+
+        mptObjects.erase(it, mptObjects.end());
+
+        ASSERT(mptKeys.size() <= limit, "Number of keys can't exceed the limit");
+        if (mptKeys.size() == limit)
+            return {mptObjects, cursor};
+
+        return {mptObjects, {}};
+    }
+
+    std::optional<Blob>
+    doFetchLedgerObject(
+        ripple::uint256 const& key,
+        std::uint32_t const sequence,
+        boost::asio::yield_context yield
+    ) const override
+    {
+        LOG(log_.debug()) << "Fetching ledger object for seq " << sequence << ", key = " << ripple::to_string(key);
+        if (auto const res = executor_.read(yield, schema_->selectObject, key, sequence); res) {
+            if (auto const result = res->template get<Blob>(); result) {
+                if (result->size())
+                    return result;
+            } else {
+                LOG(log_.debug()) << "Could not fetch ledger object - no rows";
+            }
+        } else {
+            LOG(log_.error()) << "Could not fetch ledger object: " << res.error();
+        }
+
+        return std::nullopt;
+    }
+
+    std::optional<std::uint32_t>
+    doFetchLedgerObjectSeq(
+        ripple::uint256 const& key,
+        std::uint32_t const sequence,
+        boost::asio::yield_context yield
+    ) const override
+    {
+        LOG(log_.debug()) << "Fetching ledger object for seq " << sequence << ", key = " << ripple::to_string(key);
+        if (auto const res = executor_.read(yield, schema_->selectObject, key, sequence); res) {
+            if (auto const result = res->template get<Blob, std::uint32_t>(); result) {
+                auto [_, seq] = result.value();
+                return seq;
+            }
+            LOG(log_.debug()) << "Could not fetch ledger object sequence - no rows";
+        } else {
+            LOG(log_.error()) << "Could not fetch ledger object sequence: " << res.error();
+        }
+
+        return std::nullopt;
+    }
+
+    std::optional<TransactionAndMetadata>
+    fetchTransaction(ripple::uint256 const& hash, boost::asio::yield_context yield) const override
+    {
+        if (auto const res = executor_.read(yield, schema_->selectTransaction, hash); res) {
+            if (auto const maybeValue = res->template get<Blob, Blob, uint32_t, uint32_t>(); maybeValue) {
+                auto [transaction, meta, seq, date] = *maybeValue;
+                return std::make_optional<TransactionAndMetadata>(transaction, meta, seq, date);
+            }
+
+            LOG(log_.debug()) << "Could not fetch transaction - no rows";
+        } else {
+            LOG(log_.error()) << "Could not fetch transaction: " << res.error();
+        }
+
+        return std::nullopt;
+    }
+
+    std::optional<ripple::uint256>
+    doFetchSuccessorKey(
+        ripple::uint256 key,
+        std::uint32_t const ledgerSequence,
+        boost::asio::yield_context yield
+    ) const override
+    {
+        if (auto const res = executor_.read(yield, schema_->selectSuccessor, key, ledgerSequence); res) {
+            if (auto const result = res->template get<ripple::uint256>(); result) {
+                if (*result == kLAST_KEY)
+                    return std::nullopt;
+                return result;
+            }
+
+            LOG(log_.debug()) << "Could not fetch successor - no rows";
+        } else {
+            LOG(log_.error()) << "Could not fetch successor: " << res.error();
+        }
+
+        return std::nullopt;
+    }
+
+    std::vector<TransactionAndMetadata>
+    fetchTransactions(std::vector<ripple::uint256> const& hashes, boost::asio::yield_context yield) const override
+    {
+        if (hashes.empty())
+            return {};
+
+        auto const numHashes = hashes.size();
+        std::vector<TransactionAndMetadata> results;
+        results.reserve(numHashes);
+
+        std::vector<Statement> statements;
+        statements.reserve(numHashes);
+
+        auto const timeDiff = util::timed([this, yield, &results, &hashes, &statements]() {
+            // TODO: seems like a job for "hash IN (list of hashes)" instead?
+            std::transform(
+                std::cbegin(hashes), std::cend(hashes), std::back_inserter(statements), [this](auto const& hash) {
+                    return schema_->selectTransaction.bind(hash);
+                }
+            );
+
+            auto const entries = executor_.readEach(yield, statements);
+            std::transform(
+                std::cbegin(entries),
+                std::cend(entries),
+                std::back_inserter(results),
+                [](auto const& res) -> TransactionAndMetadata {
+                    if (auto const maybeRow = res.template get<Blob, Blob, uint32_t, uint32_t>(); maybeRow)
+                        return *maybeRow;
+
+                    return {};
+                }
+            );
+        });
+
+        ASSERT(numHashes == results.size(), "Number of hashes and results must match");
+        LOG(log_.debug()) << "Fetched " << numHashes << " transactions from database in " << timeDiff
+                          << " milliseconds";
+        return results;
+    }
+
+    std::vector<Blob>
+    doFetchLedgerObjects(
+        std::vector<ripple::uint256> const& keys,
+        std::uint32_t const sequence,
+        boost::asio::yield_context yield
+    ) const override
+    {
+        if (keys.empty())
+            return {};
+
+        auto const numKeys = keys.size();
+        LOG(log_.trace()) << "Fetching " << numKeys << " objects";
+
+        std::vector<Blob> results;
+        results.reserve(numKeys);
+
+        std::vector<Statement> statements;
+        statements.reserve(numKeys);
+
+        // TODO: seems like a job for "key IN (list of keys)" instead?
+        std::transform(
+            std::cbegin(keys), std::cend(keys), std::back_inserter(statements), [this, &sequence](auto const& key) {
+                return schema_->selectObject.bind(key, sequence);
+            }
+        );
+
+        auto const entries = executor_.readEach(yield, statements);
+        std::transform(
+            std::cbegin(entries), std::cend(entries), std::back_inserter(results), [](auto const& res) -> Blob {
+                if (auto const maybeValue = res.template get<Blob>(); maybeValue)
+                    return *maybeValue;
+
+                return {};
+            }
+        );
+
+        LOG(log_.trace()) << "Fetched " << numKeys << " objects";
+        return results;
+    }
+
+    std::vector<LedgerObject>
+    fetchLedgerDiff(std::uint32_t const ledgerSequence, boost::asio::yield_context yield) const override
+    {
+        auto const [keys, timeDiff] = util::timed([this, &ledgerSequence, yield]() -> std::vector<ripple::uint256> {
+            auto const res = executor_.read(yield, schema_->selectDiff, ledgerSequence);
+            if (not res) {
+                LOG(log_.error()) << "Could not fetch ledger diff: " << res.error() << "; ledger = " << ledgerSequence;
+                return {};
+            }
+
+            auto const& results = res.value();
+            if (not results) {
+                LOG(log_.error()) << "Could not fetch ledger diff - no rows; ledger = " << ledgerSequence;
+                return {};
+            }
+
+            std::vector<ripple::uint256> resultKeys;
+            for (auto [key] : extract<ripple::uint256>(results))
+                resultKeys.push_back(key);
+
+            return resultKeys;
+        });
+
+        // one of the above errors must have happened
+        if (keys.empty())
+            return {};
+
+        LOG(log_.debug()) << "Fetched " << keys.size() << " diff hashes from database in " << timeDiff
+                          << " milliseconds";
+
+        auto const objs = fetchLedgerObjects(keys, ledgerSequence, yield);
+        std::vector<LedgerObject> results;
+        results.reserve(keys.size());
+
+        std::transform(
+            std::cbegin(keys),
+            std::cend(keys),
+            std::cbegin(objs),
+            std::back_inserter(results),
+            [](auto const& key, auto const& obj) { return LedgerObject{key, obj}; }
+        );
+
+        return results;
+    }
+
+    std::optional<std::string>
+    fetchMigratorStatus(std::string const& migratorName, boost::asio::yield_context yield) const override
+    {
+        auto const res = executor_.read(yield, schema_->selectMigratorStatus, Text(migratorName));
+        if (not res) {
+            LOG(log_.error()) << "Could not fetch migrator status: " << res.error();
+            return {};
+        }
+
+        auto const& results = res.value();
+        if (not results) {
+            return {};
+        }
+
+        for (auto [statusString] : extract<std::string>(results))
+            return statusString;
+
+        return {};
+    }
+
+    std::expected<std::vector<std::pair<boost::uuids::uuid, std::string>>, std::string>
+    fetchClioNodesData(boost::asio::yield_context yield) const override
+    {
+        auto const readResult = executor_.read(yield, schema_->selectClioNodesData);
+        if (not readResult)
+            return std::unexpected{readResult.error().message()};
+
+        std::vector<std::pair<boost::uuids::uuid, std::string>> result;
+
+        for (auto [uuid, message] : extract<boost::uuids::uuid, std::string>(*readResult)) {
+            result.emplace_back(uuid, std::move(message));
+        }
+
+        return result;
+    }
+
+    void
+    doWriteLedgerObject(std::string&& key, std::uint32_t const seq, std::string&& blob) override
+    {
+        LOG(log_.trace()) << " Writing ledger object " << key.size() << ":" << seq << " [" << blob.size() << " bytes]";
+
+        if (range_)
+            executor_.write(schema_->insertDiff, seq, key);
+
+        executor_.write(schema_->insertObject, std::move(key), seq, std::move(blob));
+    }
+
+    void
+    writeSuccessor(std::string&& key, std::uint32_t const seq, std::string&& successor) override
+    {
+        LOG(log_.trace()) << "Writing successor. key = " << key.size() << " bytes. "
+                          << " seq = " << std::to_string(seq) << " successor = " << successor.size() << " bytes.";
+        ASSERT(!key.empty(), "Key must not be empty");
+        ASSERT(!successor.empty(), "Successor must not be empty");
+
+        executor_.write(schema_->insertSuccessor, std::move(key), seq, std::move(successor));
+    }
+
+    void
+    writeAccountTransactions(std::vector<AccountTransactionsData> data) override
+    {
+        std::vector<Statement> statements;
+        statements.reserve(data.size() * 10);  // assume 10 transactions avg
+
+        for (auto& record : data) {
+            std::ranges::transform(record.accounts, std::back_inserter(statements), [this, &record](auto&& account) {
+                return schema_->insertAccountTx.bind(
+                    std::forward<decltype(account)>(account),
+                    std::make_tuple(record.ledgerSequence, record.transactionIndex),
+                    record.txHash
+                );
+            });
+        }
+
+        executor_.write(std::move(statements));
+    }
+
+    void
+    writeAccountTransaction(AccountTransactionsData record) override
+    {
+        std::vector<Statement> statements;
+        statements.reserve(record.accounts.size());
+
+        std::ranges::transform(record.accounts, std::back_inserter(statements), [this, &record](auto&& account) {
+            return schema_->insertAccountTx.bind(
+                std::forward<decltype(account)>(account),
+                std::make_tuple(record.ledgerSequence, record.transactionIndex),
+                record.txHash
+            );
+        });
+
+        executor_.write(std::move(statements));
+    }
+
+    void
+    writeNFTTransactions(std::vector<NFTTransactionsData> const& data) override
+    {
+        std::vector<Statement> statements;
+        statements.reserve(data.size());
+
+        std::ranges::transform(data, std::back_inserter(statements), [this](auto const& record) {
+            return schema_->insertNFTTx.bind(
+                record.tokenID, std::make_tuple(record.ledgerSequence, record.transactionIndex), record.txHash
+            );
+        });
+
+        executor_.write(std::move(statements));
+    }
+
+    void
+    writeTransaction(
+        std::string&& hash,
+        std::uint32_t const seq,
+        std::uint32_t const date,
+        std::string&& transaction,
+        std::string&& metadata
+    ) override
+    {
+        LOG(log_.trace()) << "Writing txn to database";
+
+        executor_.write(schema_->insertLedgerTransaction, seq, hash);
+        executor_.write(
+            schema_->insertTransaction, std::move(hash), seq, date, std::move(transaction), std::move(metadata)
+        );
+    }
+
+    void
+    writeNFTs(std::vector<NFTsData> const& data) override
+    {
+        std::vector<Statement> statements;
+        statements.reserve(data.size() * 3);
+
+        for (NFTsData const& record : data) {
+            if (!record.onlyUriChanged) {
+                statements.push_back(
+                    schema_->insertNFT.bind(record.tokenID, record.ledgerSequence, record.owner, record.isBurned)
+                );
+
+                // If `uri` is set (and it can be set to an empty uri), we know this
+                // is a net-new NFT. That is, this NFT has not been seen before by
+                // us _OR_ it is in the extreme edge case of a re-minted NFT ID with
+                // the same NFT ID as an already-burned token. In this case, we need
+                // to record the URI and link to the issuer_nf_tokens table.
+                if (record.uri) {
+                    statements.push_back(schema_->insertIssuerNFT.bind(
+                        ripple::nft::getIssuer(record.tokenID),
+                        static_cast<uint32_t>(ripple::nft::getTaxon(record.tokenID)),
+                        record.tokenID
+                    ));
+                    statements.push_back(
+                        schema_->insertNFTURI.bind(record.tokenID, record.ledgerSequence, record.uri.value())
+                    );
+                }
+            } else {
+                // only uri changed, we update the uri table only
+                statements.push_back(
+                    schema_->insertNFTURI.bind(record.tokenID, record.ledgerSequence, record.uri.value())
+                );
+            }
+        }
+
+        executor_.writeEach(std::move(statements));
+    }
+
+    void
+    writeMPTHolders(std::vector<MPTHolderData> const& data) override
+    {
+        std::vector<Statement> statements;
+        statements.reserve(data.size());
+        for (auto [mptId, holder] : data)
+            statements.push_back(schema_->insertMPTHolder.bind(mptId, holder));
+
+        executor_.write(std::move(statements));
+    }
+
+    void
+    startWrites() const override
+    {
+        // Note: no-op in original implementation too.
+        // probably was used in PG to start a transaction or smth.
+    }
+
+    void
+    writeMigratorStatus(std::string const& migratorName, std::string const& status) override
+    {
+        executor_.writeSync(
+            schema_->insertMigratorStatus, data::cassandra::Text{migratorName}, data::cassandra::Text(status)
+        );
+    }
+
+    void
+    writeNodeMessage(boost::uuids::uuid const& uuid, std::string message) override
+    {
+        executor_.writeSync(schema_->updateClioNodeMessage, data::cassandra::Text{std::move(message)}, uuid);
+    }
+
+    bool
+    isTooBusy() const override
+    {
+        return executor_.isTooBusy();
+    }
+
+    boost::json::object
+    stats() const override
+    {
+        return executor_.stats();
+    }
+
+protected:
+    /**
+     * @brief Executes statements and tries to write to DB
+     *
+     * @param statement statement to execute
+     * @return true if successful, false if it fails
+     */
+    bool
+    executeSyncUpdate(Statement statement)
+    {
+        auto const res = executor_.writeSync(statement);
+        auto maybeSuccess = res->template get<bool>();
+        if (not maybeSuccess) {
+            LOG(log_.error()) << "executeSyncUpdate - error getting result - no row";
+            return false;
+        }
+
+        if (not maybeSuccess.value()) {
+            LOG(log_.warn()) << "Update failed. Checking if DB state is what we expect";
+
+            // error may indicate that another writer wrote something.
+            // in this case let's just compare the current state of things
+            // against what we were trying to write in the first place and
+            // use that as the source of truth for the result.
+            auto rng = hardFetchLedgerRangeNoThrow();
+            return rng && rng->maxSequence == ledgerSequence_;
+        }
+
+        return true;
+    }
+};
+
+}  // namespace data::cassandra

src/data/cassandra/CassandraSchema.hpp

@@ -0,0 +1,178 @@
+//------------------------------------------------------------------------------
+/*
+    This file is part of clio: https://github.com/XRPLF/clio
+    Copyright (c) 2025, the clio developers.
+
+    Permission to use, copy, modify, and distribute this software for any
+    purpose with or without fee is hereby granted, provided that the above
+    copyright notice and this permission notice appear in all copies.
+
+    THE  SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+    WITH  REGARD  TO  THIS  SOFTWARE  INCLUDING  ALL  IMPLIED  WARRANTIES  OF
+    MERCHANTABILITY  AND  FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+    ANY  SPECIAL,  DIRECT,  INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+    WHATSOEVER  RESULTING  FROM  LOSS  OF USE, DATA OR PROFITS, WHETHER IN AN
+    ACTION  OF  CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+    OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+*/
+//==============================================================================
+
+#pragma once
+
+#include "data/cassandra/Concepts.hpp"
+#include "data/cassandra/Handle.hpp"
+#include "data/cassandra/Schema.hpp"
+#include "data/cassandra/SettingsProvider.hpp"
+#include "data/cassandra/Types.hpp"
+#include "util/log/Logger.hpp"
+
+#include <boost/json/string.hpp>
+#include <fmt/compile.h>
+
+#include <functional>
+#include <memory>
+
+namespace data::cassandra {
+
+/**
+ * @brief Manages the DB schema and provides access to prepared statements.
+ */
+template <SomeSettingsProvider SettingsProviderType>
+class CassandraSchema : public Schema<SettingsProvider> {
+    using Schema::Schema;
+
+public:
+    /**
+     * @brief Construct a new Cassandra Schema object
+     *
+     * @param settingsProvider The settings provider
+     */
+    struct CassandraStatements : public Schema<SettingsProvider>::Statements {
+        using Schema<SettingsProvider>::Statements::Statements;
+
+        //
+        // Update (and "delete") queries
+        //
+        PreparedStatement updateLedgerRange = [this]() {
+            return handle_.get().prepare(
+                fmt::format(
+                    R"(
+                UPDATE {}
+                   SET sequence = ?
+                 WHERE is_latest = ?
+                    IF sequence IN (?, null)
+                )",
+                    qualifiedTableName(settingsProvider_.get(), "ledger_range")
+                )
+            );
+        }();
+
+        //
+        // Select queries
+        //
+
+        PreparedStatement selectNFTIDsByIssuer = [this]() {
+            return handle_.get().prepare(
+                fmt::format(
+                    R"(
+                SELECT token_id
+                  FROM {}
+                 WHERE issuer = ?
+                   AND (taxon, token_id) > ?
+              ORDER BY taxon ASC, token_id ASC
+                 LIMIT ?
+                )",
+                    qualifiedTableName(settingsProvider_.get(), "issuer_nf_tokens_v2")
+                )
+            );
+        }();
+
+        PreparedStatement selectAccountFromBeginning = [this]() {
+            return handle_.get().prepare(
+                fmt::format(
+                    R"(
+                SELECT account
+                  FROM {}
+                 WHERE token(account) > 0
+                   PER PARTITION LIMIT 1
+                 LIMIT ?
+                )",
+                    qualifiedTableName(settingsProvider_.get(), "account_tx")
+                )
+            );
+        }();
+
+        PreparedStatement selectAccountFromToken = [this]() {
+            return handle_.get().prepare(
+                fmt::format(
+                    R"(
+                SELECT account
+                  FROM {}
+                 WHERE token(account) > token(?)
+                   PER PARTITION LIMIT 1
+                 LIMIT ?
+                )",
+                    qualifiedTableName(settingsProvider_.get(), "account_tx")
+                )
+            );
+        }();
+
+        PreparedStatement selectLedgerPageKeys = [this]() {
+            return handle_.get().prepare(
+                fmt::format(
+                    R"(
+                SELECT key
+                  FROM {}
+                 WHERE TOKEN(key) >= ?
+                   AND sequence <= ?
+         PER PARTITION LIMIT 1
+                 LIMIT ?
+                 ALLOW FILTERING
+                )",
+                    qualifiedTableName(settingsProvider_.get(), "objects")
+                )
+            );
+        }();
+
+        PreparedStatement selectLedgerPage = [this]() {
+            return handle_.get().prepare(
+                fmt::format(
+                    R"(
+                SELECT object, key
+                  FROM {}
+                 WHERE TOKEN(key) >= ?
+                   AND sequence <= ?
+         PER PARTITION LIMIT 1
+                 LIMIT ?
+                 ALLOW FILTERING
+                )",
+                    qualifiedTableName(settingsProvider_.get(), "objects")
+                )
+            );
+        }();
+    };
+
+    void
+    prepareStatements(Handle const& handle) override
+    {
+        LOG(log_.info()) << "Preparing cassandra statements";
+        statements_ = std::make_unique<CassandraStatements>(settingsProvider_, handle);
+        LOG(log_.info()) << "Finished preparing statements";
+    }
+
+    /**
+     * @brief Provides access to statements.
+     *
+     * @return The statements
+     */
+    std::unique_ptr<CassandraStatements> const&
+    operator->() const
+    {
+        return statements_;
+    }
+
+private:
+    std::unique_ptr<CassandraStatements> statements_{nullptr};
+};
+
+}  // namespace data::cassandra

src/data/cassandra/KeyspaceSchema.hpp

@@ -0,0 +1,140 @@
+//------------------------------------------------------------------------------
+/*
+    This file is part of clio: https://github.com/XRPLF/clio
+    Copyright (c) 2025, the clio developers.
+
+    Permission to use, copy, modify, and distribute this software for any
+    purpose with or without fee is hereby granted, provided that the above
+    copyright notice and this permission notice appear in all copies.
+
+    THE  SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+    WITH  REGARD  TO  THIS  SOFTWARE  INCLUDING  ALL  IMPLIED  WARRANTIES  OF
+    MERCHANTABILITY  AND  FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+    ANY  SPECIAL,  DIRECT,  INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+    WHATSOEVER  RESULTING  FROM  LOSS  OF USE, DATA OR PROFITS, WHETHER IN AN
+    ACTION  OF  CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+    OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+*/
+//==============================================================================
+
+#pragma once
+
+#include "data/cassandra/Concepts.hpp"
+#include "data/cassandra/Handle.hpp"
+#include "data/cassandra/Schema.hpp"
+#include "data/cassandra/SettingsProvider.hpp"
+#include "data/cassandra/Types.hpp"
+#include "util/log/Logger.hpp"
+
+#include <boost/json/string.hpp>
+#include <fmt/compile.h>
+
+#include <functional>
+#include <memory>
+
+namespace data::cassandra {
+
+/**
+ * @brief Manages the DB schema and provides access to prepared statements.
+ */
+template <SomeSettingsProvider SettingsProviderType>
+class KeyspaceSchema : public Schema<SettingsProvider> {
+public:
+    using Schema::Schema;
+
+    /**
+     * @brief Construct a new Keyspace Schema object
+     *
+     * @param settingsProvider The settings provider
+     */
+    struct KeyspaceStatements : public Schema<SettingsProvider>::Statements {
+        using Schema<SettingsProvider>::Statements::Statements;
+
+        //
+        // Insert queries
+        //
+        PreparedStatement insertLedgerRange = [this]() {
+            return handle_.get().prepare(
+                fmt::format(
+                    R"(
+                    INSERT INTO {} (is_latest, sequence) VALUES (?, ?) IF NOT EXISTS
+                    )",
+                    qualifiedTableName(settingsProvider_.get(), "ledger_range")
+                )
+            );
+        }();
+
+        //
+        // Update (and "delete") queries
+        //
+        PreparedStatement updateLedgerRange = [this]() {
+            return handle_.get().prepare(
+                fmt::format(
+                    R"(
+                UPDATE {}
+                   SET sequence = ?
+                 WHERE is_latest = ?
+                    IF sequence = ?
+                )",
+                    qualifiedTableName(settingsProvider_.get(), "ledger_range")
+                )
+            );
+        }();
+
+        PreparedStatement selectLedgerRange = [this]() {
+            return handle_.get().prepare(
+                fmt::format(
+                    R"(
+                SELECT sequence
+                  FROM {}
+                 WHERE is_latest in (True, False)
+                )",
+                    qualifiedTableName(settingsProvider_.get(), "ledger_range")
+                )
+            );
+        }();
+
+        //
+        // Select queries
+        //
+        PreparedStatement selectNFTsAfterTaxonKeyspaces = [this]() {
+            return handle_.get().prepare(
+                fmt::format(
+                    R"(
+                        SELECT token_id
+                          FROM {}
+                         WHERE issuer = ?
+                           AND taxon > ?
+                      ORDER BY taxon ASC, token_id ASC
+                         LIMIT ?
+                )",
+                    qualifiedTableName(settingsProvider_.get(), "issuer_nf_tokens_v2")
+                )
+            );
+        }();
+    };
+
+    void
+    prepareStatements(Handle const& handle) override
+    {
+        LOG(log_.info()) << "Preparing aws keyspace statements";
+        statements_ = std::make_unique<KeyspaceStatements>(settingsProvider_, handle);
+        LOG(log_.info()) << "Finished preparing statements";
+    }
+
+    /**
+     * @brief Provides access to statements.
+     *
+     * @return The statements
+     */
+    std::unique_ptr<KeyspaceStatements> const&
+    operator->() const
+    {
+        return statements_;
+    }
+
+private:
+    std::unique_ptr<KeyspaceStatements> statements_{nullptr};
+};
+
+}  // namespace data::cassandra

src/data/cassandra/Schema.hpp

@@ -24,10 +24,10 @@
 #include "data/cassandra/Types.hpp"
 #include "util/log/Logger.hpp"
 
+#include <boost/json/string.hpp>
 #include <fmt/compile.h>
 
 #include <functional>
-#include <memory>
 #include <string>
 #include <string_view>
 #include <vector>
@@ -53,12 +53,15 @@ template <SomeSettingsProvider SettingsProviderType>
  */
 template <SomeSettingsProvider SettingsProviderType>
 class Schema {
+protected:
     util::Logger log_{"Backend"};
     std::reference_wrapper<SettingsProviderType const> settingsProvider_;
 
 public:
+    virtual ~Schema() = default;
+
     /**
-     * @brief Construct a new Schema object
+     * @brief Shared Schema's between all Schema classes (Cassandra and Keyspace)
      *
      * @param settingsProvider The settings provider
      */
@@ -334,6 +337,7 @@ public:
      * @brief Prepared statements holder.
      */
     class Statements {
+    protected:
         std::reference_wrapper<SettingsProviderType const> settingsProvider_;
         std::reference_wrapper<Handle const> handle_;
 
@@ -526,20 +530,6 @@ public:
         // Update (and "delete") queries
         //
 
-        PreparedStatement updateLedgerRange = [this]() {
-            return handle_.get().prepare(
-                fmt::format(
-                    R"(
-                UPDATE {}
-                   SET sequence = ?
-                 WHERE is_latest = ?
-                    IF sequence IN (?, null)
-                )",
-                    qualifiedTableName(settingsProvider_.get(), "ledger_range")
-                )
-            );
-        }();
-
         PreparedStatement deleteLedgerRange = [this]() {
             return handle_.get().prepare(
                 fmt::format(
@@ -654,40 +644,6 @@ public:
             );
         }();
 
-        PreparedStatement selectLedgerPageKeys = [this]() {
-            return handle_.get().prepare(
-                fmt::format(
-                    R"(
-                SELECT key
-                  FROM {}
-                 WHERE TOKEN(key) >= ?
-                   AND sequence <= ?
-         PER PARTITION LIMIT 1
-                 LIMIT ?
-                 ALLOW FILTERING
-                )",
-                    qualifiedTableName(settingsProvider_.get(), "objects")
-                )
-            );
-        }();
-
-        PreparedStatement selectLedgerPage = [this]() {
-            return handle_.get().prepare(
-                fmt::format(
-                    R"(
-                SELECT object, key
-                  FROM {}
-                 WHERE TOKEN(key) >= ?
-                   AND sequence <= ?
-         PER PARTITION LIMIT 1
-                 LIMIT ?
-                 ALLOW FILTERING
-                )",
-                    qualifiedTableName(settingsProvider_.get(), "objects")
-                )
-            );
-        }();
-
         PreparedStatement getToken = [this]() {
             return handle_.get().prepare(
                 fmt::format(
@@ -717,36 +673,6 @@ public:
             );
         }();
 
-        PreparedStatement selectAccountFromBeginning = [this]() {
-            return handle_.get().prepare(
-                fmt::format(
-                    R"(
-                SELECT account
-                  FROM {}
-                 WHERE token(account) > 0
-                   PER PARTITION LIMIT 1
-                 LIMIT ?
-                )",
-                    qualifiedTableName(settingsProvider_.get(), "account_tx")
-                )
-            );
-        }();
-
-        PreparedStatement selectAccountFromToken = [this]() {
-            return handle_.get().prepare(
-                fmt::format(
-                    R"(
-                SELECT account
-                  FROM {}
-                 WHERE token(account) > token(?)
-                   PER PARTITION LIMIT 1
-                 LIMIT ?
-                )",
-                    qualifiedTableName(settingsProvider_.get(), "account_tx")
-                )
-            );
-        }();
-
         PreparedStatement selectAccountTxForward = [this]() {
             return handle_.get().prepare(
                 fmt::format(
@@ -827,22 +753,6 @@ public:
             );
         }();
 
-        PreparedStatement selectNFTIDsByIssuer = [this]() {
-            return handle_.get().prepare(
-                fmt::format(
-                    R"(
-                SELECT token_id
-                  FROM {}
-                 WHERE issuer = ?
-                   AND (taxon, token_id) > ?
-              ORDER BY taxon ASC, token_id ASC
-                 LIMIT ?
-                )",
-                    qualifiedTableName(settingsProvider_.get(), "issuer_nf_tokens_v2")
-                )
-            );
-        }();
-
         PreparedStatement selectNFTIDsByIssuerTaxon = [this]() {
             return handle_.get().prepare(
                 fmt::format(
@@ -960,27 +870,8 @@ public:
      *
      * @param handle The handle to the DB
      */
-    void
+    virtual void
-    prepareStatements(Handle const& handle)
+    prepareStatements(Handle const& handle) = 0;
-    {
-        LOG(log_.info()) << "Preparing cassandra statements";
-        statements_ = std::make_unique<Statements>(settingsProvider_, handle);
-        LOG(log_.info()) << "Finished preparing statements";
-    }
-
-    /**
-     * @brief Provides access to statements.
-     *
-     * @return The statements
-     */
-    std::unique_ptr<Statements> const&
-    operator->() const
-    {
-        return statements_;
-    }
-
-private:
-    std::unique_ptr<Statements> statements_{nullptr};
 };
 
 }  // namespace data::cassandra

src/data/cassandra/SettingsProvider.cpp

@@ -97,6 +97,7 @@ SettingsProvider::parseSettings() const
     settings.coreConnectionsPerHost = config_.get<uint32_t>("core_connections_per_host");
     settings.queueSizeIO = config_.maybeValue<uint32_t>("queue_size_io");
     settings.writeBatchSize = config_.get<std::size_t>("write_batch_size");
+    settings.provider = impl::providerFromString(config_.get<std::string>("provider"));
 
     if (config_.getValueView("connect_timeout").hasValue()) {
         auto const connectTimeoutSecond = config_.get<uint32_t>("connect_timeout");

src/data/cassandra/impl/Batch.cpp

@@ -36,9 +36,18 @@ constexpr auto kBATCH_DELETER = [](CassBatch* ptr) { cass_batch_free(ptr); };
 
 namespace data::cassandra::impl {
 
-// TODO: Use an appropriate value instead of CASS_BATCH_TYPE_LOGGED for different use cases
+/*
+ * There are 2 main batches of Cassandra Statements:
+ * LOGGED: Ensures all updates in the batch succeed together, or none do.
+ * Use this for critical, related changes (e.g., for the same user), but it is slower.
+ *
+ * UNLOGGED: For performance. Sends many separate updates in one network trip to be fast.
+ * Use this for bulk-loading unrelated data, but know there's NO all-or-nothing guarantee.
+ *
+ * More info here: https://docs.datastax.com/en/developer/cpp-driver-dse/1.10/features/basics/batches/index.html
+ */
 Batch::Batch(std::vector<Statement> const& statements)
-    : ManagedObject{cass_batch_new(CASS_BATCH_TYPE_LOGGED), kBATCH_DELETER}
+    : ManagedObject{cass_batch_new(CASS_BATCH_TYPE_UNLOGGED), kBATCH_DELETER}
 {
     cass_batch_set_is_idempotent(*this, cass_true);
 

src/data/cassandra/impl/Cluster.cpp

@@ -60,6 +60,17 @@ Cluster::Cluster(Settings const& settings) : ManagedObject{cass_cluster_new(), k
     cass_cluster_set_connect_timeout(*this, settings.connectionTimeout.count());
     cass_cluster_set_request_timeout(*this, settings.requestTimeout.count());
 
+    // TODO: AWS keyspace reads should be local_one to save cost
+    if (settings.provider == cassandra::impl::Provider::Keyspace) {
+        if (auto const rc = cass_cluster_set_consistency(*this, CASS_CONSISTENCY_LOCAL_QUORUM); rc != CASS_OK) {
+            throw std::runtime_error(fmt::format("Error setting keyspace consistency: {}", cass_error_desc(rc)));
+        }
+    } else {
+        if (auto const rc = cass_cluster_set_consistency(*this, CASS_CONSISTENCY_QUORUM); rc != CASS_OK) {
+            throw std::runtime_error(fmt::format("Error setting cassandra consistency: {}", cass_error_desc(rc)));
+        }
+    }
+
     if (auto const rc = cass_cluster_set_core_connections_per_host(*this, settings.coreConnectionsPerHost);
         rc != CASS_OK) {
         throw std::runtime_error(fmt::format("Could not set core connections per host: {}", cass_error_desc(rc)));

src/data/cassandra/impl/Cluster.hpp

@@ -20,6 +20,7 @@
 #pragma once
 
 #include "data/cassandra/impl/ManagedObject.hpp"
+#include "util/Assert.hpp"
 #include "util/log/Logger.hpp"
 
 #include <cassandra.h>
@@ -35,6 +36,18 @@
 
 namespace data::cassandra::impl {
 
+enum class Provider { Cassandra, Keyspace };
+
+inline Provider
+providerFromString(std::string const& provider)
+{
+    ASSERT(
+        provider == "cassandra" || provider == "aws_keyspace",
+        "Provider type must be one of 'cassandra' or 'aws_keyspace'"
+    );
+    return provider == "cassandra" ? Provider::Cassandra : Provider::Keyspace;
+}
+
 // TODO: move Settings to public interface, not impl
 
 /**
@@ -45,6 +58,7 @@ struct Settings {
     static constexpr uint32_t kDEFAULT_MAX_WRITE_REQUESTS_OUTSTANDING = 10'000;
     static constexpr uint32_t kDEFAULT_MAX_READ_REQUESTS_OUTSTANDING = 100'000;
     static constexpr std::size_t kDEFAULT_BATCH_SIZE = 20;
+    static constexpr Provider kDEFAULT_PROVIDER = Provider::Cassandra;
 
     /**
      * @brief Represents the configuration of contact points for cassandra.
@@ -83,11 +97,14 @@ struct Settings {
     uint32_t maxReadRequestsOutstanding = kDEFAULT_MAX_READ_REQUESTS_OUTSTANDING;
 
     /** @brief The number of connection per host to always have active */
-    uint32_t coreConnectionsPerHost = 1u;
+    uint32_t coreConnectionsPerHost = 3u;
 
     /** @brief Size of batches when writing */
     std::size_t writeBatchSize = kDEFAULT_BATCH_SIZE;
 
+    /** @brief Provider to know if we are using scylladb or keyspace */
+    Provider provider = kDEFAULT_PROVIDER;
+
     /** @brief Size of the IO queue */
     std::optional<uint32_t> queueSizeIO = std::nullopt;  // NOLINT(readability-redundant-member-init)
 

src/data/cassandra/impl/Statement.hpp

@@ -58,14 +58,16 @@ public:
     explicit Statement(std::string_view query, Args&&... args)
         : ManagedObject{cass_statement_new_n(query.data(), query.size(), sizeof...(args)), kDELETER}
     {
-        cass_statement_set_consistency(*this, CASS_CONSISTENCY_QUORUM);
+        // TODO: figure out how to set consistency level in config
+        // NOTE: Keyspace doesn't support QUORUM at write level
+        // cass_statement_set_consistency(*this, CASS_CONSISTENCY_LOCAL_QUORUM);
         cass_statement_set_is_idempotent(*this, cass_true);
         bind<Args...>(std::forward<Args>(args)...);
     }
 
     /* implicit */ Statement(CassStatement* ptr) : ManagedObject{ptr, kDELETER}
     {
-        cass_statement_set_consistency(*this, CASS_CONSISTENCY_QUORUM);
+        // cass_statement_set_consistency(*this, CASS_CONSISTENCY_LOCAL_QUORUM);
         cass_statement_set_is_idempotent(*this, cass_true);
     }
 

src/data/impl/InputFile.cpp

@@ -0,0 +1,58 @@
+//------------------------------------------------------------------------------
+/*
+    This file is part of clio: https://github.com/XRPLF/clio
+    Copyright (c) 2025, the clio developers.
+
+    Permission to use, copy, modify, and distribute this software for any
+    purpose with or without fee is hereby granted, provided that the above
+    copyright notice and this permission notice appear in all copies.
+
+    THE  SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+    WITH  REGARD  TO  THIS  SOFTWARE  INCLUDING  ALL  IMPLIED  WARRANTIES  OF
+    MERCHANTABILITY  AND  FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+    ANY  SPECIAL,  DIRECT,  INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+    WHATSOEVER  RESULTING  FROM  LOSS  OF USE, DATA OR PROFITS, WHETHER IN AN
+    ACTION  OF  CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+    OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+*/
+//==============================================================================
+
+#include "data/impl/InputFile.hpp"
+
+#include <xrpl/basics/base_uint.h>
+
+#include <cstddef>
+#include <cstring>
+#include <ios>
+#include <iosfwd>
+#include <string>
+#include <utility>
+
+namespace data::impl {
+
+InputFile::InputFile(std::string const& path) : file_(path, std::ios::binary | std::ios::in)
+{
+}
+
+bool
+InputFile::isOpen() const
+{
+    return file_.is_open();
+}
+
+bool
+InputFile::readRaw(char* data, size_t size)
+{
+    file_.read(data, size);
+    shasum_.update(data, size);
+    return not file_.fail();
+}
+
+ripple::uint256
+InputFile::hash() const
+{
+    auto sum = shasum_;
+    return std::move(sum).finalize();
+}
+
+}  // namespace data::impl

src/data/impl/InputFile.hpp

@@ -1,7 +1,7 @@
 //------------------------------------------------------------------------------
 /*
     This file is part of clio: https://github.com/XRPLF/clio
-    Copyright (c) 2023, the clio developers.
+    Copyright (c) 2025, the clio developers.
 
     Permission to use, copy, modify, and distribute this software for any
     purpose with or without fee is hereby granted, provided that the above
@@ -19,24 +19,39 @@
 
 #pragma once
 
-#include "etl/impl/LedgerLoader.hpp"
+#include "util/Shasum.hpp"
-#include "util/FakeFetchResponse.hpp"
 
-#include <gmock/gmock.h>
+#include <xrpl/basics/base_uint.h>
-#include <xrpl/protocol/LedgerHeader.h>
 
-#include <cstdint>
+#include <cstddef>
-#include <optional>
+#include <cstring>
+#include <fstream>
+#include <iosfwd>
+#include <string>
 
-struct MockLedgerLoader {
+namespace data::impl {
-    using GetLedgerResponseType = FakeFetchResponse;
-    using RawLedgerObjectType = FakeLedgerObject;
 
-    MOCK_METHOD(
+class InputFile {
-        FormattedTransactionsData,
+    std::ifstream file_;
-        insertTransactions,
+    util::Sha256sum shasum_;
-        (ripple::LedgerHeader const&, GetLedgerResponseType& data),
+
-        ()
+public:
-    );
+    InputFile(std::string const& path);
-    MOCK_METHOD(std::optional<ripple::LedgerHeader>, loadInitialLedger, (uint32_t sequence), ());
+
+    bool
+    isOpen() const;
+
+    template <typename T>
+    bool
+    read(T& t)
+    {
+        return readRaw(reinterpret_cast<char*>(&t), sizeof(T));
+    }
+
+    bool
+    readRaw(char* data, size_t size);
+
+    ripple::uint256
+    hash() const;
 };
+}  // namespace data::impl

src/data/impl/LedgerCacheFile.cpp

@@ -0,0 +1,210 @@
+//------------------------------------------------------------------------------
+/*
+    This file is part of clio: https://github.com/XRPLF/clio
+    Copyright (c) 2025, the clio developers.
+
+    Permission to use, copy, modify, and distribute this software for any
+    purpose with or without fee is hereby granted, provided that the above
+    copyright notice and this permission notice appear in all copies.
+
+    THE  SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+    WITH  REGARD  TO  THIS  SOFTWARE  INCLUDING  ALL  IMPLIED  WARRANTIES  OF
+    MERCHANTABILITY  AND  FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+    ANY  SPECIAL,  DIRECT,  INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+    WHATSOEVER  RESULTING  FROM  LOSS  OF USE, DATA OR PROFITS, WHETHER IN AN
+    ACTION  OF  CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+    OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+*/
+//==============================================================================
+
+#include "data/impl/LedgerCacheFile.hpp"
+
+#include "data/LedgerCache.hpp"
+#include "data/Types.hpp"
+
+#include <fmt/format.h>
+#include <xrpl/basics/base_uint.h>
+
+#include <algorithm>
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <exception>
+#include <filesystem>
+#include <string>
+#include <utility>
+
+namespace data::impl {
+
+using Hash = ripple::uint256;
+using Separator = std::array<char, 16>;
+static constexpr Separator kSEPARATOR = {0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0};
+
+namespace {
+
+std::expected<std::pair<ripple::uint256, LedgerCache::CacheEntry>, std::string>
+readCacheEntry(InputFile& file, size_t i)
+{
+    ripple::uint256 key;
+    if (not file.readRaw(reinterpret_cast<char*>(key.data()), ripple::base_uint<256>::bytes)) {
+        return std::unexpected(fmt::format("Failed to read key at index {}", i));
+    }
+
+    uint32_t seq{};
+    if (not file.read(seq)) {
+        return std::unexpected(fmt::format("Failed to read sequence at index {}", i));
+    }
+
+    size_t blobSize{};
+    if (not file.read(blobSize)) {
+        return std::unexpected(fmt::format("Failed to read blob size at index {}", i));
+    }
+
+    Blob blob(blobSize);
+    if (not file.readRaw(reinterpret_cast<char*>(blob.data()), blobSize)) {
+        return std::unexpected(fmt::format("Failed to read blob data at index {}", i));
+    }
+    return std::make_pair(key, LedgerCache::CacheEntry{.seq = seq, .blob = std::move(blob)});
+}
+
+std::expected<void, std::string>
+verifySeparator(Separator const& s)
+{
+    if (not std::ranges::all_of(s, [](char c) { return c == 0; })) {
+        return std::unexpected{"Separator verification failed - data corruption detected"};
+    }
+    return {};
+}
+
+}  // anonymous namespace
+
+LedgerCacheFile::LedgerCacheFile(std::string path) : path_(std::move(path))
+{
+}
+
+std::expected<void, std::string>
+LedgerCacheFile::write(DataView dataView)
+{
+    auto const newFilePath = fmt::format("{}.new", path_);
+    auto file = OutputFile{newFilePath};
+    if (not file.isOpen()) {
+        return std::unexpected{fmt::format("Couldn't open file: {}", newFilePath)};
+    }
+
+    Header const header{
+        .latestSeq = dataView.latestSeq, .mapSize = dataView.map.size(), .deletedSize = dataView.deleted.size()
+    };
+    file.write(header);
+    file.write(kSEPARATOR);
+
+    for (auto const& [k, v] : dataView.map) {
+        file.write(k.data(), decltype(k)::bytes);
+        file.write(v.seq);
+        file.write(v.blob.size());
+        file.writeRaw(reinterpret_cast<char const*>(v.blob.data()), v.blob.size());
+    }
+    file.write(kSEPARATOR);
+
+    for (auto const& [k, v] : dataView.deleted) {
+        file.write(k.data(), decltype(k)::bytes);
+        file.write(v.seq);
+        file.write(v.blob.size());
+        file.writeRaw(reinterpret_cast<char const*>(v.blob.data()), v.blob.size());
+    }
+    file.write(kSEPARATOR);
+    auto const hash = file.hash();
+    file.write(hash.data(), decltype(hash)::bytes);
+
+    try {
+        std::filesystem::rename(newFilePath, path_);
+    } catch (std::exception const& e) {
+        return std::unexpected{fmt::format("Error moving cache file from {} to {}: {}", newFilePath, path_, e.what())};
+    }
+
+    return {};
+}
+
+std::expected<LedgerCacheFile::Data, std::string>
+LedgerCacheFile::read(uint32_t minLatestSequence)
+{
+    try {
+        auto file = InputFile{path_};
+        if (not file.isOpen()) {
+            return std::unexpected{fmt::format("Couldn't open file: {}", path_)};
+        }
+
+        Data result;
+
+        Header header{};
+        if (not file.read(header)) {
+            return std::unexpected{"Error reading cache header"};
+        }
+        if (header.version != kVERSION) {
+            return std::unexpected{
+                fmt::format("Cache has wrong version: expected {} found {}", kVERSION, header.version)
+            };
+        }
+        if (header.latestSeq < minLatestSequence) {
+            return std::unexpected{fmt::format("Latest sequence ({}) in the cache file is too low.", header.latestSeq)};
+        }
+        result.latestSeq = header.latestSeq;
+
+        Separator separator{};
+        if (not file.readRaw(separator.data(), separator.size())) {
+            return std::unexpected{"Error reading cache header"};
+        }
+        if (auto verificationResult = verifySeparator(separator); not verificationResult.has_value()) {
+            return std::unexpected{std::move(verificationResult).error()};
+        }
+
+        for (size_t i = 0; i < header.mapSize; ++i) {
+            auto cacheEntryExpected = readCacheEntry(file, i);
+            if (not cacheEntryExpected.has_value()) {
+                return std::unexpected{std::move(cacheEntryExpected).error()};
+            }
+            // Using insert with hint here to decrease insert operation complexity to the amortized constant instead of
+            // logN
+            result.map.insert(result.map.end(), std::move(cacheEntryExpected).value());
+        }
+
+        if (not file.readRaw(separator.data(), separator.size())) {
+            return std::unexpected{"Error reading separator"};
+        }
+        if (auto verificationResult = verifySeparator(separator); not verificationResult.has_value()) {
+            return std::unexpected{std::move(verificationResult).error()};
+        }
+
+        for (size_t i = 0; i < header.deletedSize; ++i) {
+            auto cacheEntryExpected = readCacheEntry(file, i);
+            if (not cacheEntryExpected.has_value()) {
+                return std::unexpected{std::move(cacheEntryExpected).error()};
+            }
+            result.deleted.insert(result.deleted.end(), std::move(cacheEntryExpected).value());
+        }
+
+        if (not file.readRaw(separator.data(), separator.size())) {
+            return std::unexpected{"Error reading separator"};
+        }
+        if (auto verificationResult = verifySeparator(separator); not verificationResult.has_value()) {
+            return std::unexpected{std::move(verificationResult).error()};
+        }
+
+        auto const dataHash = file.hash();
+        ripple::uint256 hashFromFile{};
+        if (not file.readRaw(reinterpret_cast<char*>(hashFromFile.data()), decltype(hashFromFile)::bytes)) {
+            return std::unexpected{"Error reading hash"};
+        }
+
+        if (dataHash != hashFromFile) {
+            return std::unexpected{"Hash file corruption detected"};
+        }
+
+        return result;
+    } catch (std::exception const& e) {
+        return std::unexpected{fmt::format(" Error reading cache file: {}", e.what())};
+    } catch (...) {
+        return std::unexpected{fmt::format(" Error reading cache file")};
+    }
+}
+
+}  // namespace data::impl

src/data/impl/LedgerCacheFile.hpp

@@ -0,0 +1,70 @@
+//------------------------------------------------------------------------------
+/*
+    This file is part of clio: https://github.com/XRPLF/clio
+    Copyright (c) 2025, the clio developers.
+
+    Permission to use, copy, modify, and distribute this software for any
+    purpose with or without fee is hereby granted, provided that the above
+    copyright notice and this permission notice appear in all copies.
+
+    THE  SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+    WITH  REGARD  TO  THIS  SOFTWARE  INCLUDING  ALL  IMPLIED  WARRANTIES  OF
+    MERCHANTABILITY  AND  FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+    ANY  SPECIAL,  DIRECT,  INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+    WHATSOEVER  RESULTING  FROM  LOSS  OF USE, DATA OR PROFITS, WHETHER IN AN
+    ACTION  OF  CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+    OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+*/
+//==============================================================================
+
+#pragma once
+
+#include "data/LedgerCache.hpp"
+#include "data/impl/InputFile.hpp"
+#include "data/impl/OutputFile.hpp"
+
+#include <fmt/format.h>
+#include <xrpl/basics/base_uint.h>
+
+#include <cstddef>
+#include <cstdint>
+#include <cstring>
+#include <string>
+
+namespace data::impl {
+
+class LedgerCacheFile {
+public:
+    struct Header {
+        uint32_t version = kVERSION;
+        uint32_t latestSeq{};
+        uint64_t mapSize{};
+        uint64_t deletedSize{};
+    };
+
+private:
+    static constexpr uint32_t kVERSION = 1;
+
+    std::string path_;
+
+public:
+    template <typename T>
+    struct DataBase {
+        uint32_t latestSeq{0};
+        T map;
+        T deleted;
+    };
+
+    using DataView = DataBase<LedgerCache::CacheMap const&>;
+    using Data = DataBase<LedgerCache::CacheMap>;
+
+    LedgerCacheFile(std::string path);
+
+    std::expected<void, std::string>
+    write(DataView dataView);
+
+    std::expected<Data, std::string>
+    read(uint32_t minLatestSequence);
+};
+
+}  // namespace data::impl

src/data/impl/OutputFile.cpp

@@ -0,0 +1,62 @@
+//------------------------------------------------------------------------------
+/*
+    This file is part of clio: https://github.com/XRPLF/clio
+    Copyright (c) 2025, the clio developers.
+
+    Permission to use, copy, modify, and distribute this software for any
+    purpose with or without fee is hereby granted, provided that the above
+    copyright notice and this permission notice appear in all copies.
+
+    THE  SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+    WITH  REGARD  TO  THIS  SOFTWARE  INCLUDING  ALL  IMPLIED  WARRANTIES  OF
+    MERCHANTABILITY  AND  FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+    ANY  SPECIAL,  DIRECT,  INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+    WHATSOEVER  RESULTING  FROM  LOSS  OF USE, DATA OR PROFITS, WHETHER IN AN
+    ACTION  OF  CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+    OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+*/
+//==============================================================================
+
+#include "data/impl/OutputFile.hpp"
+
+#include <xrpl/basics/base_uint.h>
+
+#include <cstddef>
+#include <cstring>
+#include <ios>
+#include <string>
+#include <utility>
+
+namespace data::impl {
+
+OutputFile::OutputFile(std::string const& path) : file_(path, std::ios::binary | std::ios::out)
+{
+}
+
+bool
+OutputFile::isOpen() const
+{
+    return file_.is_open();
+}
+
+void
+OutputFile::writeRaw(char const* data, size_t size)
+{
+    writeToFile(data, size);
+}
+
+void
+OutputFile::writeToFile(char const* data, size_t size)
+{
+    file_.write(data, size);
+    shasum_.update(data, size);
+}
+
+ripple::uint256
+OutputFile::hash() const
+{
+    auto sum = shasum_;
+    return std::move(sum).finalize();
+}
+
+}  // namespace data::impl

src/data/impl/OutputFile.hpp

@@ -0,0 +1,68 @@
+//------------------------------------------------------------------------------
+/*
+    This file is part of clio: https://github.com/XRPLF/clio
+    Copyright (c) 2025, the clio developers.
+
+    Permission to use, copy, modify, and distribute this software for any
+    purpose with or without fee is hereby granted, provided that the above
+    copyright notice and this permission notice appear in all copies.
+
+    THE  SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+    WITH  REGARD  TO  THIS  SOFTWARE  INCLUDING  ALL  IMPLIED  WARRANTIES  OF
+    MERCHANTABILITY  AND  FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+    ANY  SPECIAL,  DIRECT,  INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+    WHATSOEVER  RESULTING  FROM  LOSS  OF USE, DATA OR PROFITS, WHETHER IN AN
+    ACTION  OF  CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+    OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+*/
+//==============================================================================
+
+#pragma once
+
+#include "util/Shasum.hpp"
+
+#include <xrpl/basics/base_uint.h>
+
+#include <cstddef>
+#include <cstring>
+#include <fstream>
+#include <string>
+
+namespace data::impl {
+
+class OutputFile {
+    std::ofstream file_;
+    util::Sha256sum shasum_;
+
+public:
+    OutputFile(std::string const& path);
+
+    bool
+    isOpen() const;
+
+    template <typename T>
+    void
+    write(T&& data)
+    {
+        writeRaw(reinterpret_cast<char const*>(&data), sizeof(T));
+    }
+
+    template <typename T>
+    void
+    write(T const* data, size_t const size)
+    {
+        writeRaw(reinterpret_cast<char const*>(data), size);
+    }
+
+    void
+    writeRaw(char const* data, size_t size);
+
+    ripple::uint256
+    hash() const;
+
+private:
+    void
+    writeToFile(char const* data, size_t size);
+};
+
+}  // namespace data::impl

src/etl/AmendmentBlockHandlerInterface.hpp

@@ -19,7 +19,7 @@
 
 #pragma once
 
-namespace etlng {
+namespace etl {
 
 /**
  * @brief The interface of a handler for amendment blocking
@@ -32,6 +32,12 @@ struct AmendmentBlockHandlerInterface {
      */
     virtual void
     notifyAmendmentBlocked() = 0;
+
+    /**
+     * @brief Stop the block handler from repeatedly executing
+     */
+    virtual void
+    stop() = 0;
 };
 
-}  // namespace etlng
+}  // namespace etl

src/etl/CMakeLists.txt

@@ -7,14 +7,24 @@ target_sources(
           ETLService.cpp
           ETLState.cpp
           LoadBalancer.cpp
+          MPTHelpers.cpp
           NetworkValidatedLedgers.cpp
           NFTHelpers.cpp
           Source.cpp
-          MPTHelpers.cpp
           impl/AmendmentBlockHandler.cpp
+          impl/AsyncGrpcCall.cpp
+          impl/Extraction.cpp
           impl/ForwardingSource.cpp
           impl/GrpcSource.cpp
+          impl/Loading.cpp
+          impl/Monitor.cpp
           impl/SubscriptionSource.cpp
+          impl/TaskManager.cpp
+          impl/ext/Cache.cpp
+          impl/ext/Core.cpp
+          impl/ext/MPT.cpp
+          impl/ext/NFT.cpp
+          impl/ext/Successor.cpp
 )
 
 target_link_libraries(clio_etl PUBLIC clio_data)

src/etl/CacheLoader.hpp

@@ -21,16 +21,20 @@
 
 #include "data/BackendInterface.hpp"
 #include "data/LedgerCacheInterface.hpp"
+#include "data/Types.hpp"
+#include "etl/CacheLoaderInterface.hpp"
 #include "etl/CacheLoaderSettings.hpp"
 #include "etl/impl/CacheLoader.hpp"
 #include "etl/impl/CursorFromAccountProvider.hpp"
 #include "etl/impl/CursorFromDiffProvider.hpp"
 #include "etl/impl/CursorFromFixDiffNumProvider.hpp"
-#include "etlng/CacheLoaderInterface.hpp"
 #include "util/Assert.hpp"
+#include "util/Profiler.hpp"
 #include "util/async/context/BasicExecutionContext.hpp"
+#include "util/config/ConfigDefinition.hpp"
 #include "util/log/Logger.hpp"
 
+#include <algorithm>
 #include <cstdint>
 #include <functional>
 #include <memory>
@@ -48,7 +52,7 @@ namespace etl {
  * @tparam ExecutionContextType The type of the execution context to use
  */
 template <typename ExecutionContextType = util::async::CoroExecutionContext>
-class CacheLoader : public etlng::CacheLoaderInterface {
+class CacheLoader : public CacheLoaderInterface {
     using CacheLoaderType = impl::CacheLoaderImpl<data::LedgerCacheInterface>;
 
     util::Logger log_{"ETL"};
@@ -98,6 +102,10 @@ public:
             return;
         }
 
+        if (loadCacheFromFile()) {
+            return;
+        }
+
         std::shared_ptr<impl::BaseCursorProvider> provider;
         if (settings_.numCacheCursorsFromDiff != 0) {
             LOG(log_.info()) << "Loading cache with cursor from num_cursors_from_diff="
@@ -149,6 +157,36 @@ public:
         if (loader_ != nullptr)
             loader_->wait();
     }
+
+private:
+    bool
+    loadCacheFromFile()
+    {
+        if (not settings_.cacheFileSettings.has_value()) {
+            return false;
+        }
+        LOG(log_.info()) << "Loading ledger cache from " << settings_.cacheFileSettings->path;
+        auto const minLatestSequence =
+            backend_->fetchLedgerRange()
+                .transform([this](data::LedgerRange const& range) {
+                    return std::max(range.maxSequence - settings_.cacheFileSettings->maxAge, range.minSequence);
+                })
+                .value_or(0);
+
+        auto const [success, duration_ms] = util::timed([&]() {
+            return cache_.get().loadFromFile(settings_.cacheFileSettings->path, minLatestSequence);
+        });
+
+        if (not success.has_value()) {
+            LOG(log_.warn()) << "Error loading cache from file: " << success.error();
+            return false;
+        }
+
+        LOG(log_.info()) << "Loaded cache from file in " << duration_ms
+                         << " ms. Latest sequence: " << cache_.get().latestLedgerSequence();
+        backend_->forceUpdateRange(cache_.get().latestLedgerSequence());
+        return true;
+    }
 };
 
 }  // namespace etl

src/etl/CacheLoaderInterface.hpp

@@ -21,7 +21,7 @@
 
 #include <cstdint>
 
-namespace etlng {
+namespace etl {
 
 /**
  * @brief An interface for the Cache Loader
@@ -50,4 +50,4 @@ struct CacheLoaderInterface {
     wait() noexcept = 0;
 };
 
-}  // namespace etlng
+}  // namespace etl

src/etl/CacheLoaderSettings.cpp

@@ -26,6 +26,7 @@
 #include <cstddef>
 #include <cstdint>
 #include <string>
+#include <utility>
 
 namespace etl {
 
@@ -63,6 +64,12 @@ makeCacheLoaderSettings(util::config::ClioConfigDefinition const& config)
     settings.numCacheMarkers = cache.get<std::size_t>("num_markers");
     settings.cachePageFetchSize = cache.get<std::size_t>("page_fetch_size");
 
+    if (auto filePath = cache.maybeValue<std::string>("file.path"); filePath.has_value()) {
+        settings.cacheFileSettings = CacheLoaderSettings::CacheFileSettings{
+            .path = std::move(filePath).value(), .maxAge = cache.get<uint32_t>("file.max_sequence_age")
+        };
+    }
+
     auto const entry = cache.get<std::string>("load");
     if (boost::iequals(entry, "sync"))
         settings.loadStyle = CacheLoaderSettings::LoadStyle::SYNC;

src/etl/CacheLoaderSettings.hpp

@@ -22,6 +22,9 @@
 #include "util/config/ConfigDefinition.hpp"
 
 #include <cstddef>
+#include <cstdint>
+#include <optional>
+#include <string>
 
 namespace etl {
 
@@ -32,6 +35,15 @@ struct CacheLoaderSettings {
     /** @brief Ways to load the cache */
     enum class LoadStyle { ASYNC, SYNC, NONE };
 
+    /** @brief Settings for cache file operations */
+    struct CacheFileSettings {
+        std::string path;       /**< path to the file to load cache from on start and save cache to on shutdown */
+        uint32_t maxAge = 5000; /**< max difference between latest sequence in cache file and DB */
+
+        auto
+        operator<=>(CacheFileSettings const&) const = default;
+    };
+
     size_t numCacheDiffs = 32;             /**< number of diffs to use to generate cursors */
     size_t numCacheMarkers = 48;           /**< number of markers to use at one time to traverse the ledger */
     size_t cachePageFetchSize = 512;       /**< number of ledger objects to fetch concurrently per marker */
@@ -39,7 +51,8 @@ struct CacheLoaderSettings {
     size_t numCacheCursorsFromDiff = 0;    /**< number of cursors to fetch from diff */
     size_t numCacheCursorsFromAccount = 0; /**< number of cursors to fetch from account_tx */
 
-    LoadStyle loadStyle = LoadStyle::ASYNC; /**< how to load the cache */
+    LoadStyle loadStyle = LoadStyle::ASYNC;             /**< how to load the cache */
+    std::optional<CacheFileSettings> cacheFileSettings; /**< optional settings for cache file operations */
 
     auto
     operator<=>(CacheLoaderSettings const&) const = default;

src/etl/CacheUpdaterInterface.hpp

@@ -20,12 +20,12 @@
 #pragma once
 
 #include "data/Types.hpp"
-#include "etlng/Models.hpp"
+#include "etl/Models.hpp"
 
 #include <cstdint>
 #include <vector>
 
-namespace etlng {
+namespace etl {
 
 /**
  * @brief An interface for the Cache Updater
@@ -63,4 +63,4 @@ struct CacheUpdaterInterface {
     setFull() = 0;
 };
 
-}  // namespace etlng
+}  // namespace etl

src/etl/ETLService.cpp

@@ -1,7 +1,7 @@
 //------------------------------------------------------------------------------
 /*
     This file is part of clio: https://github.com/XRPLF/clio
-    Copyright (c) 2023, the clio developers.
+    Copyright (c) 2025, the clio developers.
 
     Permission to use, copy, modify, and distribute this software for any
     purpose with or without fee is hereby granted, provided that the above
@@ -20,371 +20,392 @@
 #include "etl/ETLService.hpp"
 
 #include "data/BackendInterface.hpp"
+#include "data/LedgerCacheInterface.hpp"
+#include "data/Types.hpp"
 #include "etl/CacheLoader.hpp"
+#include "etl/CacheLoaderInterface.hpp"
+#include "etl/CacheUpdaterInterface.hpp"
 #include "etl/CorruptionDetector.hpp"
-#include "etl/LoadBalancer.hpp"
+#include "etl/ETLServiceInterface.hpp"
+#include "etl/ETLState.hpp"
+#include "etl/ExtractorInterface.hpp"
+#include "etl/InitialLoadObserverInterface.hpp"
+#include "etl/LedgerPublisherInterface.hpp"
+#include "etl/LoadBalancerInterface.hpp"
+#include "etl/LoaderInterface.hpp"
+#include "etl/MonitorInterface.hpp"
+#include "etl/MonitorProviderInterface.hpp"
 #include "etl/NetworkValidatedLedgersInterface.hpp"
 #include "etl/SystemState.hpp"
+#include "etl/TaskManagerProviderInterface.hpp"
 #include "etl/impl/AmendmentBlockHandler.hpp"
-#include "etl/impl/ExtractionDataPipe.hpp"
+#include "etl/impl/CacheUpdater.hpp"
-#include "etl/impl/Extractor.hpp"
+#include "etl/impl/Extraction.hpp"
 #include "etl/impl/LedgerFetcher.hpp"
-#include "etl/impl/LedgerLoader.hpp"
 #include "etl/impl/LedgerPublisher.hpp"
-#include "etl/impl/Transformer.hpp"
+#include "etl/impl/Loading.hpp"
-#include "etlng/ETLService.hpp"
+#include "etl/impl/MonitorProvider.hpp"
-#include "etlng/ETLServiceInterface.hpp"
+#include "etl/impl/Registry.hpp"
-#include "etlng/LoadBalancer.hpp"
+#include "etl/impl/Scheduling.hpp"
-#include "etlng/LoadBalancerInterface.hpp"
+#include "etl/impl/TaskManager.hpp"
-#include "etlng/impl/LedgerPublisher.hpp"
+#include "etl/impl/TaskManagerProvider.hpp"
-#include "etlng/impl/MonitorProvider.hpp"
+#include "etl/impl/ext/Cache.hpp"
-#include "etlng/impl/TaskManagerProvider.hpp"
+#include "etl/impl/ext/Core.hpp"
-#include "etlng/impl/ext/Cache.hpp"
+#include "etl/impl/ext/MPT.hpp"
-#include "etlng/impl/ext/Core.hpp"
+#include "etl/impl/ext/NFT.hpp"
-#include "etlng/impl/ext/MPT.hpp"
+#include "etl/impl/ext/Successor.hpp"
-#include "etlng/impl/ext/NFT.hpp"
-#include "etlng/impl/ext/Successor.hpp"
 #include "feed/SubscriptionManagerInterface.hpp"
 #include "util/Assert.hpp"
-#include "util/Constants.hpp"
+#include "util/Profiler.hpp"
 #include "util/async/AnyExecutionContext.hpp"
-#include "util/config/ConfigDefinition.hpp"
 #include "util/log/Logger.hpp"
 
-#include <boost/asio/io_context.hpp>
+#include <boost/json/object.hpp>
-#include <xrpl/beast/core/CurrentThreadName.h>
+#include <boost/signals2/connection.hpp>
 #include <xrpl/protocol/LedgerHeader.h>
 
 #include <chrono>
 #include <cstddef>
 #include <cstdint>
+#include <functional>
 #include <memory>
 #include <optional>
-#include <stdexcept>
+#include <string>
-#include <thread>
 #include <utility>
-#include <vector>
 
 namespace etl {
 
-std::shared_ptr<etlng::ETLServiceInterface>
+std::shared_ptr<ETLServiceInterface>
 ETLService::makeETLService(
     util::config::ClioConfigDefinition const& config,
-    boost::asio::io_context& ioc,
     util::async::AnyExecutionContext ctx,
     std::shared_ptr<BackendInterface> backend,
     std::shared_ptr<feed::SubscriptionManagerInterface> subscriptions,
-    std::shared_ptr<etlng::LoadBalancerInterface> balancer,
+    std::shared_ptr<LoadBalancerInterface> balancer,
     std::shared_ptr<NetworkValidatedLedgersInterface> ledgers
 )
 {
-    std::shared_ptr<etlng::ETLServiceInterface> ret;
+    std::shared_ptr<ETLServiceInterface> ret;
 
-    if (config.get<bool>("__ng_etl")) {
+    auto state = std::make_shared<SystemState>();
-        ASSERT(
+    state->isStrictReadonly = config.get<bool>("read_only");
-            std::dynamic_pointer_cast<etlng::LoadBalancer>(balancer), "LoadBalancer type must be etlng::LoadBalancer"
-        );
 
-        auto state = std::make_shared<etl::SystemState>();
+    auto fetcher = std::make_shared<impl::LedgerFetcher>(backend, balancer);
-        state->isStrictReadonly = config.get<bool>("read_only");
+    auto extractor = std::make_shared<impl::Extractor>(fetcher);
+    auto publisher = std::make_shared<impl::LedgerPublisher>(ctx, backend, subscriptions, *state);
+    auto cacheLoader = std::make_shared<CacheLoader<>>(config, backend, backend->cache());
+    auto cacheUpdater = std::make_shared<impl::CacheUpdater>(backend->cache());
+    auto amendmentBlockHandler = std::make_shared<impl::AmendmentBlockHandler>(ctx, *state);
+    auto monitorProvider = std::make_shared<impl::MonitorProvider>();
 
-        auto fetcher = std::make_shared<etl::impl::LedgerFetcher>(backend, balancer);
+    backend->setCorruptionDetector(CorruptionDetector{*state, backend->cache()});
-        auto extractor = std::make_shared<etlng::impl::Extractor>(fetcher);
-        auto publisher = std::make_shared<etlng::impl::LedgerPublisher>(ioc, backend, subscriptions, *state);
-        auto cacheLoader = std::make_shared<etl::CacheLoader<>>(config, backend, backend->cache());
-        auto cacheUpdater = std::make_shared<etlng::impl::CacheUpdater>(backend->cache());
-        auto amendmentBlockHandler = std::make_shared<etlng::impl::AmendmentBlockHandler>(ctx, *state);
-        auto monitorProvider = std::make_shared<etlng::impl::MonitorProvider>();
 
-        backend->setCorruptionDetector(CorruptionDetector{*state, backend->cache()});
+    auto loader = std::make_shared<impl::Loader>(
+        backend,
+        impl::makeRegistry(
+            *state,
+            impl::CacheExt{cacheUpdater},
+            impl::CoreExt{backend},
+            impl::SuccessorExt{backend, backend->cache()},
+            impl::NFTExt{backend},
+            impl::MPTExt{backend}
+        ),
+        amendmentBlockHandler,
+        state
+    );
 
-        auto loader = std::make_shared<etlng::impl::Loader>(
+    auto taskManagerProvider = std::make_shared<impl::TaskManagerProvider>(*ledgers, extractor, loader);
-            backend,
-            etlng::impl::makeRegistry(
-                *state,
-                etlng::impl::CacheExt{cacheUpdater},
-                etlng::impl::CoreExt{backend},
-                etlng::impl::SuccessorExt{backend, backend->cache()},
-                etlng::impl::NFTExt{backend},
-                etlng::impl::MPTExt{backend}
-            ),
-            amendmentBlockHandler,
-            state
-        );
 
-        auto taskManagerProvider = std::make_shared<etlng::impl::TaskManagerProvider>(*ledgers, extractor, loader);
+    ret = std::make_shared<ETLService>(
-
+        ctx,
-        ret = std::make_shared<etlng::ETLService>(
+        config,
-            ctx,
+        backend,
-            config,
+        balancer,
-            backend,
+        ledgers,
-            balancer,
+        publisher,
-            ledgers,
+        cacheLoader,
-            publisher,
+        cacheUpdater,
-            cacheLoader,
+        extractor,
-            cacheUpdater,
+        loader,  // loader itself
-            extractor,
+        loader,  // initial load observer
-            loader,  // loader itself
+        taskManagerProvider,
-            loader,  // initial load observer
+        monitorProvider,
-            taskManagerProvider,
+        state
-            monitorProvider,
+    );
-            state
-        );
-    } else {
-        ASSERT(std::dynamic_pointer_cast<etl::LoadBalancer>(balancer), "LoadBalancer type must be etl::LoadBalancer");
-        ret = std::make_shared<etl::ETLService>(config, ioc, backend, subscriptions, balancer, ledgers);
-    }
 
     // inject networkID into subscriptions, as transaction feed require it to inject CTID in response
-    if (auto const state = ret->getETLState(); state)
+    if (auto const etlState = ret->getETLState(); etlState)
-        subscriptions->setNetworkID(state->networkID);
+        subscriptions->setNetworkID(etlState->networkID);
 
     ret->run();
     return ret;
 }
 
-// Database must be populated when this starts
+ETLService::ETLService(
-std::optional<uint32_t>
+    util::async::AnyExecutionContext ctx,
-ETLService::runETLPipeline(uint32_t startSequence, uint32_t numExtractors)
+    std::reference_wrapper<util::config::ClioConfigDefinition const> config,
+    std::shared_ptr<data::BackendInterface> backend,
+    std::shared_ptr<LoadBalancerInterface> balancer,
+    std::shared_ptr<NetworkValidatedLedgersInterface> ledgers,
+    std::shared_ptr<LedgerPublisherInterface> publisher,
+    std::shared_ptr<CacheLoaderInterface> cacheLoader,
+    std::shared_ptr<CacheUpdaterInterface> cacheUpdater,
+    std::shared_ptr<ExtractorInterface> extractor,
+    std::shared_ptr<LoaderInterface> loader,
+    std::shared_ptr<InitialLoadObserverInterface> initialLoadObserver,
+    std::shared_ptr<TaskManagerProviderInterface> taskManagerProvider,
+    std::shared_ptr<MonitorProviderInterface> monitorProvider,
+    std::shared_ptr<SystemState> state
+)
+    : ctx_(std::move(ctx))
+    , config_(config)
+    , backend_(std::move(backend))
+    , balancer_(std::move(balancer))
+    , ledgers_(std::move(ledgers))
+    , publisher_(std::move(publisher))
+    , cacheLoader_(std::move(cacheLoader))
+    , cacheUpdater_(std::move(cacheUpdater))
+    , extractor_(std::move(extractor))
+    , loader_(std::move(loader))
+    , initialLoadObserver_(std::move(initialLoadObserver))
+    , taskManagerProvider_(std::move(taskManagerProvider))
+    , monitorProvider_(std::move(monitorProvider))
+    , state_(std::move(state))
+    , startSequence_(config.get().maybeValue<uint32_t>("start_sequence"))
+    , finishSequence_(config.get().maybeValue<uint32_t>("finish_sequence"))
 {
-    if (finishSequence_ && startSequence > *finishSequence_)
+    ASSERT(not state_->isWriting, "ETL should never start in writer mode");
-        return {};
 
-    LOG(log_.debug()) << "Wait for cache containing seq " << startSequence - 1
+    if (startSequence_.has_value())
-                      << " current cache last seq =" << backend_->cache().latestLedgerSequence();
+        LOG(log_.info()) << "Start sequence: " << *startSequence_;
-    backend_->cache().waitUntilCacheContainsSeq(startSequence - 1);
 
-    LOG(log_.debug()) << "Starting etl pipeline";
+    if (finishSequence_.has_value())
-    state_.isWriting = true;
+        LOG(log_.info()) << "Finish sequence: " << *finishSequence_;
 
-    auto const rng = backend_->hardFetchLedgerRangeNoThrow();
+    LOG(log_.info()) << "Starting in " << (state_->isStrictReadonly ? "STRICT READONLY MODE" : "WRITE MODE");
-    ASSERT(rng.has_value(), "Parent ledger range can't be null");
-    ASSERT(
-        rng->maxSequence >= startSequence - 1,
-        "Got not parent ledger. rnd->maxSequence = {}, startSequence = {}",
-        rng->maxSequence,
-        startSequence
-    );
-
-    auto const begin = std::chrono::system_clock::now();
-    auto extractors = std::vector<std::unique_ptr<ExtractorType>>{};
-    auto pipe = DataPipeType{numExtractors, startSequence};
-
-    for (auto i = 0u; i < numExtractors; ++i) {
-        extractors.push_back(
-            std::make_unique<ExtractorType>(
-                pipe, networkValidatedLedgers_, ledgerFetcher_, startSequence + i, finishSequence_, state_
-            )
-        );
-    }
-
-    auto transformer =
-        TransformerType{pipe, backend_, ledgerLoader_, ledgerPublisher_, amendmentBlockHandler_, startSequence, state_};
-    transformer.waitTillFinished();  // suspend current thread until exit condition is met
-    pipe.cleanup();                  // TODO: this should probably happen automatically using destructor
-
-    // wait for all of the extractors to stop
-    for (auto& t : extractors)
-        t->waitTillFinished();
-
-    auto const end = std::chrono::system_clock::now();
-    auto const lastPublishedSeq = ledgerPublisher_.getLastPublishedSequence();
-    static constexpr auto kNANOSECONDS_PER_SECOND = 1'000'000'000.0;
-    LOG(log_.debug()) << "Extracted and wrote " << lastPublishedSeq.value_or(startSequence) - startSequence << " in "
-                      << ((end - begin).count()) / kNANOSECONDS_PER_SECOND;
-
-    state_.isWriting = false;
-
-    LOG(log_.debug()) << "Stopping etl pipeline";
-    return lastPublishedSeq;
 }
 
-// Main loop of ETL.
+ETLService::~ETLService()
-// The software begins monitoring the ledgers that are validated by the network.
-// The member networkValidatedLedgers_ keeps track of the sequences of ledgers validated by the network.
-// Whenever a ledger is validated by the network, the software looks for that ledger in the database. Once the ledger is
-// found in the database, the software publishes that ledger to the ledgers stream. If a network validated ledger is not
-// found in the database after a certain amount of time, then the software attempts to take over responsibility of the
-// ETL process, where it writes new ledgers to the database. The software will relinquish control of the ETL process if
-// it detects that another process has taken over ETL.
-void
-ETLService::monitor()
 {
-    auto rng = backend_->hardFetchLedgerRangeNoThrow();
+    stop();
-    if (!rng) {
+    LOG(log_.debug()) << "Destroying ETL";
-        LOG(log_.info()) << "Database is empty. Will download a ledger from the network.";
-        std::optional<ripple::LedgerHeader> ledger;
-
-        try {
-            if (startSequence_) {
-                LOG(log_.info()) << "ledger sequence specified in config. "
-                                 << "Will begin ETL process starting with ledger " << *startSequence_;
-                ledger = ledgerLoader_.loadInitialLedger(*startSequence_);
-            } else {
-                LOG(log_.info()) << "Waiting for next ledger to be validated by network...";
-                std::optional<uint32_t> mostRecentValidated = networkValidatedLedgers_->getMostRecent();
-
-                if (mostRecentValidated) {
-                    LOG(log_.info()) << "Ledger " << *mostRecentValidated << " has been validated. Downloading...";
-                    ledger = ledgerLoader_.loadInitialLedger(*mostRecentValidated);
-                } else {
-                    LOG(log_.info()) << "The wait for the next validated ledger has been aborted. "
-                                        "Exiting monitor loop";
-                    return;
-                }
-            }
-        } catch (std::runtime_error const& e) {
-            LOG(log_.fatal()) << "Failed to load initial ledger: " << e.what();
-            amendmentBlockHandler_.notifyAmendmentBlocked();
-            return;
-        }
-
-        if (ledger) {
-            rng = backend_->hardFetchLedgerRangeNoThrow();
-        } else {
-            LOG(log_.error()) << "Failed to load initial ledger. Exiting monitor loop";
-            return;
-        }
-    } else {
-        if (startSequence_)
-            LOG(log_.warn()) << "start sequence specified but db is already populated";
-
-        LOG(log_.info()) << "Database already populated. Picking up from the tip of history";
-        cacheLoader_.load(rng->maxSequence);
-    }
-
-    ASSERT(rng.has_value(), "Ledger range can't be null");
-    uint32_t nextSequence = rng->maxSequence + 1;
-
-    LOG(log_.debug()) << "Database is populated. Starting monitor loop. sequence = " << nextSequence;
-
-    while (not isStopping()) {
-        nextSequence = publishNextSequence(nextSequence);
-    }
-}
-
-uint32_t
-ETLService::publishNextSequence(uint32_t nextSequence)
-{
-    if (auto rng = backend_->hardFetchLedgerRangeNoThrow(); rng && rng->maxSequence >= nextSequence) {
-        ledgerPublisher_.publish(nextSequence, {});
-        ++nextSequence;
-    } else if (networkValidatedLedgers_->waitUntilValidatedByNetwork(nextSequence, util::kMILLISECONDS_PER_SECOND)) {
-        LOG(log_.info()) << "Ledger with sequence = " << nextSequence << " has been validated by the network. "
-                         << "Attempting to find in database and publish";
-
-        // Attempt to take over responsibility of ETL writer after 10 failed
-        // attempts to publish the ledger. publishLedger() fails if the
-        // ledger that has been validated by the network is not found in the
-        // database after the specified number of attempts. publishLedger()
-        // waits one second between each attempt to read the ledger from the
-        // database
-        constexpr size_t kTIMEOUT_SECONDS = 10;
-        bool const success = ledgerPublisher_.publish(nextSequence, kTIMEOUT_SECONDS);
-
-        if (!success) {
-            LOG(log_.warn()) << "Failed to publish ledger with sequence = " << nextSequence << " . Beginning ETL";
-
-            // returns the most recent sequence published. empty optional if no sequence was published
-            std::optional<uint32_t> lastPublished = runETLPipeline(nextSequence, extractorThreads_);
-            LOG(log_.info()) << "Aborting ETL. Falling back to publishing";
-
-            // if no ledger was published, don't increment nextSequence
-            if (lastPublished)
-                nextSequence = *lastPublished + 1;
-        } else {
-            ++nextSequence;
-        }
-    }
-    return nextSequence;
-}
-
-void
-ETLService::monitorReadOnly()
-{
-    LOG(log_.debug()) << "Starting reporting in strict read only mode";
-
-    auto const latestSequenceOpt = [this]() -> std::optional<uint32_t> {
-        auto rng = backend_->hardFetchLedgerRangeNoThrow();
-
-        if (!rng) {
-            if (auto net = networkValidatedLedgers_->getMostRecent()) {
-                return net;
-            }
-            return std::nullopt;
-        }
-
-        return rng->maxSequence;
-    }();
-
-    if (!latestSequenceOpt.has_value()) {
-        return;
-    }
-
-    uint32_t latestSequence = *latestSequenceOpt;
-
-    cacheLoader_.load(latestSequence);
-    latestSequence++;
-
-    while (not isStopping()) {
-        if (auto rng = backend_->hardFetchLedgerRangeNoThrow(); rng && rng->maxSequence >= latestSequence) {
-            ledgerPublisher_.publish(latestSequence, {});
-            latestSequence = latestSequence + 1;
-        } else {
-            // if we can't, wait until it's validated by the network, or 1 second passes, whichever occurs
-            // first. Even if we don't hear from rippled, if ledgers are being written to the db, we publish
-            // them.
-            networkValidatedLedgers_->waitUntilValidatedByNetwork(latestSequence, util::kMILLISECONDS_PER_SECOND);
-        }
-    }
 }
 
 void
 ETLService::run()
 {
-    LOG(log_.info()) << "Starting reporting etl";
+    LOG(log_.info()) << "Running ETL...";
-    state_.isStopping = false;
 
-    doWork();
+    mainLoop_.emplace(ctx_.execute([this] {
+        auto const rng = loadInitialLedgerIfNeeded();
+
+        LOG(log_.info()) << "Waiting for next ledger to be validated by network...";
+        std::optional<uint32_t> const mostRecentValidated = ledgers_->getMostRecent();
+
+        if (not mostRecentValidated) {
+            LOG(log_.info()) << "The wait for the next validated ledger has been aborted. "
+                                "Exiting monitor loop";
+            return;
+        }
+
+        if (not rng.has_value()) {
+            LOG(log_.warn()) << "Initial ledger download got cancelled - stopping ETL service";
+            return;
+        }
+
+        auto nextSequence = rng->maxSequence + 1;
+        if (backend_->cache().latestLedgerSequence() != 0) {
+            nextSequence = backend_->cache().latestLedgerSequence();
+        }
+
+        LOG(log_.debug()) << "Database is populated. Starting monitor loop. sequence = " << nextSequence;
+        startMonitor(nextSequence);
+
+        // If we are a writer as the result of loading the initial ledger - start loading
+        if (state_->isWriting)
+            startLoading(nextSequence);
+    }));
 }
 
 void
-ETLService::doWork()
+ETLService::stop()
 {
-    worker_ = std::thread([this]() {
+    LOG(log_.info()) << "Stop called";
-        beast::setCurrentThreadName("ETLService worker");
 
-        if (state_.isStrictReadonly) {
+    if (mainLoop_)
-            monitorReadOnly();
+        mainLoop_->wait();
-        } else {
+    if (taskMan_)
-            monitor();
+        taskMan_->stop();
+    if (monitor_)
+        monitor_->stop();
+}
+
+boost::json::object
+ETLService::getInfo() const
+{
+    boost::json::object result;
+
+    result["etl_sources"] = balancer_->toJson();
+    result["is_writer"] = static_cast<int>(state_->isWriting);
+    result["read_only"] = static_cast<int>(state_->isStrictReadonly);
+    auto last = publisher_->getLastPublish();
+    if (last.time_since_epoch().count() != 0)
+        result["last_publish_age_seconds"] = std::to_string(publisher_->lastPublishAgeSeconds());
+    return result;
+}
+
+bool
+ETLService::isAmendmentBlocked() const
+{
+    return state_->isAmendmentBlocked;
+}
+
+bool
+ETLService::isCorruptionDetected() const
+{
+    return state_->isCorruptionDetected;
+}
+
+std::optional<ETLState>
+ETLService::getETLState() const
+{
+    return balancer_->getETLState();
+}
+
+std::uint32_t
+ETLService::lastCloseAgeSeconds() const
+{
+    return publisher_->lastCloseAgeSeconds();
+}
+
+std::optional<data::LedgerRange>
+ETLService::loadInitialLedgerIfNeeded()
+{
+    auto rng = backend_->hardFetchLedgerRangeNoThrow();
+    if (not rng.has_value()) {
+        ASSERT(
+            not state_->isStrictReadonly,
+            "Database is empty but this node is in strict readonly mode. Can't write initial ledger."
+        );
+
+        LOG(log_.info()) << "Database is empty. Will download a ledger from the network.";
+        state_->isWriting = true;  // immediately become writer as the db is empty
+
+        auto const getMostRecent = [this]() {
+            LOG(log_.info()) << "Waiting for next ledger to be validated by network...";
+            return ledgers_->getMostRecent();
+        };
+
+        if (auto const maybeSeq = startSequence_.or_else(getMostRecent); maybeSeq.has_value()) {
+            auto const seq = *maybeSeq;
+            LOG(log_.info()) << "Starting from sequence " << seq
+                             << ". Initial ledger download and extraction can take a while...";
+
+            auto [ledger, timeDiff] = ::util::timed<std::chrono::duration<double>>([this, seq]() {
+                return extractor_->extractLedgerOnly(seq).and_then(
+                    [this, seq](auto&& data) -> std::optional<ripple::LedgerHeader> {
+                        // TODO: loadInitialLedger in balancer should be called fetchEdgeKeys or similar
+                        auto res = balancer_->loadInitialLedger(seq, *initialLoadObserver_);
+                        if (not res.has_value() and res.error() == InitialLedgerLoadError::Cancelled) {
+                            LOG(log_.debug()) << "Initial ledger load got cancelled";
+                            return std::nullopt;
+                        }
+
+                        ASSERT(res.has_value(), "Initial ledger retry logic failed");
+                        data.edgeKeys = std::move(res).value();
+
+                        return loader_->loadInitialLedger(data);
+                    }
+                );
+            });
+
+            if (not ledger.has_value()) {
+                LOG(log_.error()) << "Failed to load initial ledger. Exiting monitor loop";
+                return std::nullopt;
+            }
+
+            LOG(log_.debug()) << "Time to download and store ledger = " << timeDiff;
+            LOG(log_.info()) << "Finished loadInitialLedger. cache size = " << backend_->cache().size();
+
+            return backend_->hardFetchLedgerRangeNoThrow();
         }
-    });
+
+        LOG(log_.info()) << "The wait for the next validated ledger has been aborted. "
+                            "Exiting monitor loop";
+        return std::nullopt;
+    }
+
+    LOG(log_.info()) << "Database already populated. Picking up from the tip of history";
+    if (not backend_->cache().isFull()) {
+        cacheLoader_->load(rng->maxSequence);
+    }
+
+    return rng;
 }
 
-ETLService::ETLService(
+void
-    util::config::ClioConfigDefinition const& config,
+ETLService::startMonitor(uint32_t seq)
-    boost::asio::io_context& ioc,
-    std::shared_ptr<BackendInterface> backend,
-    std::shared_ptr<feed::SubscriptionManagerInterface> subscriptions,
-    std::shared_ptr<etlng::LoadBalancerInterface> balancer,
-    std::shared_ptr<NetworkValidatedLedgersInterface> ledgers
-)
-    : backend_(backend)
-    , loadBalancer_(balancer)
-    , networkValidatedLedgers_(std::move(ledgers))
-    , cacheLoader_(config, backend, backend->cache())
-    , ledgerFetcher_(backend, balancer)
-    , ledgerLoader_(backend, balancer, ledgerFetcher_, state_)
-    , ledgerPublisher_(ioc, backend, backend->cache(), subscriptions, state_)
-    , amendmentBlockHandler_(ioc, state_)
 {
-    startSequence_ = config.maybeValue<uint32_t>("start_sequence");
+    monitor_ = monitorProvider_->make(ctx_, backend_, ledgers_, seq);
-    finishSequence_ = config.maybeValue<uint32_t>("finish_sequence");
-    state_.isStrictReadonly = config.get<bool>("read_only");
-    extractorThreads_ = config.get<uint32_t>("extractor_threads");
 
-    // This should probably be done in the backend factory but we don't have state available until here
+    monitorNewSeqSubscription_ = monitor_->subscribeToNewSequence([this](uint32_t seq) {
-    backend_->setCorruptionDetector(CorruptionDetector{state_, backend->cache()});
+        LOG(log_.info()) << "ETLService (via Monitor) got new seq from db: " << seq;
+
+        if (state_->writeConflict) {
+            LOG(log_.info()) << "Got a write conflict; Giving up writer seat immediately";
+            giveUpWriter();
+        }
+
+        if (not state_->isWriting) {
+            auto const diff = data::synchronousAndRetryOnTimeout([this, seq](auto yield) {
+                return backend_->fetchLedgerDiff(seq, yield);
+            });
+
+            cacheUpdater_->update(seq, diff);
+            backend_->updateRange(seq);
+        }
+
+        publisher_->publish(seq, {});
+    });
+
+    monitorDbStalledSubscription_ = monitor_->subscribeToDbStalled([this]() {
+        LOG(log_.warn()) << "ETLService received DbStalled signal from Monitor";
+        if (not state_->isStrictReadonly and not state_->isWriting)
+            attemptTakeoverWriter();
+    });
+
+    monitor_->run();
 }
+
+void
+ETLService::startLoading(uint32_t seq)
+{
+    ASSERT(not state_->isStrictReadonly, "This should only happen on writer nodes");
+    taskMan_ = taskManagerProvider_->make(ctx_, *monitor_, seq, finishSequence_);
+
+    // FIXME: this legacy name "extractor_threads" is no longer accurate (we have coroutines now)
+    taskMan_->run(config_.get().get<std::size_t>("extractor_threads"));
+}
+
+void
+ETLService::attemptTakeoverWriter()
+{
+    ASSERT(not state_->isStrictReadonly, "This should only happen on writer nodes");
+    auto rng = backend_->hardFetchLedgerRangeNoThrow();
+    ASSERT(rng.has_value(), "Ledger range can't be null");
+
+    state_->isWriting = true;  // switch to writer
+    LOG(log_.info()) << "Taking over the ETL writer seat";
+    startLoading(rng->maxSequence + 1);
+}
+
+void
+ETLService::giveUpWriter()
+{
+    ASSERT(not state_->isStrictReadonly, "This should only happen on writer nodes");
+    state_->isWriting = false;
+    state_->writeConflict = false;
+    taskMan_ = nullptr;
+}
+
 }  // namespace etl

src/etl/ETLService.hpp

@@ -1,7 +1,7 @@
 //------------------------------------------------------------------------------
 /*
     This file is part of clio: https://github.com/XRPLF/clio
-    Copyright (c) 2023, the clio developers.
+    Copyright (c) 2025, the clio developers.
 
     Permission to use, copy, modify, and distribute this software for any
     purpose with or without fee is hereby granted, provided that the above
@@ -20,57 +20,64 @@
 #pragma once
 
 #include "data/BackendInterface.hpp"
-#include "etl/CacheLoader.hpp"
+#include "data/Types.hpp"
+#include "etl/CacheLoaderInterface.hpp"
+#include "etl/CacheUpdaterInterface.hpp"
+#include "etl/ETLServiceInterface.hpp"
 #include "etl/ETLState.hpp"
+#include "etl/ExtractorInterface.hpp"
+#include "etl/InitialLoadObserverInterface.hpp"
+#include "etl/LedgerPublisherInterface.hpp"
+#include "etl/LoadBalancerInterface.hpp"
+#include "etl/LoaderInterface.hpp"
+#include "etl/MonitorInterface.hpp"
+#include "etl/MonitorProviderInterface.hpp"
 #include "etl/NetworkValidatedLedgersInterface.hpp"
 #include "etl/SystemState.hpp"
+#include "etl/TaskManagerInterface.hpp"
+#include "etl/TaskManagerProviderInterface.hpp"
 #include "etl/impl/AmendmentBlockHandler.hpp"
-#include "etl/impl/ExtractionDataPipe.hpp"
+#include "etl/impl/CacheUpdater.hpp"
-#include "etl/impl/Extractor.hpp"
+#include "etl/impl/Extraction.hpp"
 #include "etl/impl/LedgerFetcher.hpp"
-#include "etl/impl/LedgerLoader.hpp"
 #include "etl/impl/LedgerPublisher.hpp"
-#include "etl/impl/Transformer.hpp"
+#include "etl/impl/Loading.hpp"
-#include "etlng/ETLServiceInterface.hpp"
+#include "etl/impl/Registry.hpp"
-#include "etlng/LoadBalancerInterface.hpp"
+#include "etl/impl/Scheduling.hpp"
-#include "etlng/impl/LedgerPublisher.hpp"
+#include "etl/impl/TaskManager.hpp"
-#include "etlng/impl/TaskManagerProvider.hpp"
+#include "etl/impl/ext/Cache.hpp"
+#include "etl/impl/ext/Core.hpp"
+#include "etl/impl/ext/NFT.hpp"
+#include "etl/impl/ext/Successor.hpp"
 #include "feed/SubscriptionManagerInterface.hpp"
 #include "util/async/AnyExecutionContext.hpp"
+#include "util/async/AnyOperation.hpp"
+#include "util/config/ConfigDefinition.hpp"
 #include "util/log/Logger.hpp"
 
 #include <boost/asio/io_context.hpp>
 #include <boost/json/object.hpp>
-#include <grpcpp/grpcpp.h>
+#include <boost/signals2/connection.hpp>
-#include <org/xrpl/rpc/v1/get_ledger.pb.h>
+#include <fmt/format.h>
-#include <xrpl/proto/org/xrpl/rpc/v1/xrp_ledger.grpc.pb.h>
+#include <xrpl/basics/Blob.h>
+#include <xrpl/basics/base_uint.h>
+#include <xrpl/basics/strHex.h>
+#include <xrpl/proto/org/xrpl/rpc/v1/get_ledger.pb.h>
+#include <xrpl/proto/org/xrpl/rpc/v1/ledger.pb.h>
+#include <xrpl/protocol/LedgerHeader.h>
+#include <xrpl/protocol/STTx.h>
+#include <xrpl/protocol/TxFormats.h>
+#include <xrpl/protocol/TxMeta.h>
 
 #include <cstddef>
 #include <cstdint>
+#include <functional>
 #include <memory>
 #include <optional>
 #include <string>
-#include <thread>
 
-struct AccountTransactionsData;
-struct NFTTransactionsData;
-struct NFTsData;
-
-/**
- * @brief This namespace contains everything to do with the ETL and ETL sources.
- */
 namespace etl {
 
-/**
- * @brief A tag class to help identify ETLService in templated code.
- */
-struct ETLServiceTag {
-    virtual ~ETLServiceTag() = default;
-};
-
-template <typename T>
-concept SomeETLService = std::derived_from<T, ETLServiceTag>;
-
 /**
  * @brief This class is responsible for continuously extracting data from a p2p node, and writing that data to the
  * databases.
@@ -84,71 +91,42 @@ concept SomeETLService = std::derived_from<T, ETLServiceTag>;
  * the others will fall back to monitoring/publishing. In this sense, this class dynamically transitions from monitoring
  * to writing and from writing to monitoring, based on the activity of other processes running on different machines.
  */
-class ETLService : public etlng::ETLServiceInterface, ETLServiceTag {
+class ETLService : public ETLServiceInterface {
-    // TODO: make these template parameters in ETLService
-    using DataPipeType = etl::impl::ExtractionDataPipe<org::xrpl::rpc::v1::GetLedgerResponse>;
-    using CacheLoaderType = etl::CacheLoader<>;
-    using LedgerFetcherType = etl::impl::LedgerFetcher;
-    using ExtractorType = etl::impl::Extractor<DataPipeType, LedgerFetcherType>;
-    using LedgerLoaderType = etl::impl::LedgerLoader<LedgerFetcherType>;
-    using LedgerPublisherType = etl::impl::LedgerPublisher;
-    using AmendmentBlockHandlerType = etl::impl::AmendmentBlockHandler;
-    using TransformerType =
-        etl::impl::Transformer<DataPipeType, LedgerLoaderType, LedgerPublisherType, AmendmentBlockHandlerType>;
-
     util::Logger log_{"ETL"};
 
+    util::async::AnyExecutionContext ctx_;
+    std::reference_wrapper<util::config::ClioConfigDefinition const> config_;
     std::shared_ptr<BackendInterface> backend_;
-    std::shared_ptr<etlng::LoadBalancerInterface> loadBalancer_;
+    std::shared_ptr<LoadBalancerInterface> balancer_;
-    std::shared_ptr<NetworkValidatedLedgersInterface> networkValidatedLedgers_;
+    std::shared_ptr<NetworkValidatedLedgersInterface> ledgers_;
+    std::shared_ptr<LedgerPublisherInterface> publisher_;
+    std::shared_ptr<CacheLoaderInterface> cacheLoader_;
+    std::shared_ptr<CacheUpdaterInterface> cacheUpdater_;
+    std::shared_ptr<ExtractorInterface> extractor_;
+    std::shared_ptr<LoaderInterface> loader_;
+    std::shared_ptr<InitialLoadObserverInterface> initialLoadObserver_;
+    std::shared_ptr<TaskManagerProviderInterface> taskManagerProvider_;
+    std::shared_ptr<MonitorProviderInterface> monitorProvider_;
+    std::shared_ptr<SystemState> state_;
 
-    std::uint32_t extractorThreads_ = 1;
-    std::thread worker_;
-
-    CacheLoaderType cacheLoader_;
-    LedgerFetcherType ledgerFetcher_;
-    LedgerLoaderType ledgerLoader_;
-    LedgerPublisherType ledgerPublisher_;
-    AmendmentBlockHandlerType amendmentBlockHandler_;
-
-    SystemState state_;
-
-    size_t numMarkers_ = 2;
     std::optional<uint32_t> startSequence_;
     std::optional<uint32_t> finishSequence_;
 
+    std::unique_ptr<MonitorInterface> monitor_;
+    std::unique_ptr<TaskManagerInterface> taskMan_;
+
+    boost::signals2::scoped_connection monitorNewSeqSubscription_;
+    boost::signals2::scoped_connection monitorDbStalledSubscription_;
+
+    std::optional<util::async::AnyOperation<void>> mainLoop_;
+
 public:
-    /**
-     * @brief Create an instance of ETLService.
-     *
-     * @param config The configuration to use
-     * @param ioc io context to run on
-     * @param backend BackendInterface implementation
-     * @param subscriptions Subscription manager
-     * @param balancer Load balancer to use
-     * @param ledgers The network validated ledgers datastructure
-     */
-    ETLService(
-        util::config::ClioConfigDefinition const& config,
-        boost::asio::io_context& ioc,
-        std::shared_ptr<BackendInterface> backend,
-        std::shared_ptr<feed::SubscriptionManagerInterface> subscriptions,
-        std::shared_ptr<etlng::LoadBalancerInterface> balancer,
-        std::shared_ptr<NetworkValidatedLedgersInterface> ledgers
-    );
-
-    /**
-     * @brief Move constructor is deleted because ETL service shares its fields by reference
-     */
-    ETLService(ETLService&&) = delete;
-
     /**
      * @brief A factory function to spawn new ETLService instances.
      *
      * Creates and runs the ETL service.
      *
      * @param config The configuration to use
-     * @param ioc io context to run on
      * @param ctx Execution context for asynchronous operations
      * @param backend BackendInterface implementation
      * @param subscriptions Subscription manager
@@ -156,182 +134,89 @@ public:
      * @param ledgers The network validated ledgers datastructure
      * @return A shared pointer to a new instance of ETLService
      */
-    static std::shared_ptr<etlng::ETLServiceInterface>
+    static std::shared_ptr<ETLServiceInterface>
     makeETLService(
         util::config::ClioConfigDefinition const& config,
-        boost::asio::io_context& ioc,
         util::async::AnyExecutionContext ctx,
         std::shared_ptr<BackendInterface> backend,
         std::shared_ptr<feed::SubscriptionManagerInterface> subscriptions,
-        std::shared_ptr<etlng::LoadBalancerInterface> balancer,
+        std::shared_ptr<LoadBalancerInterface> balancer,
         std::shared_ptr<NetworkValidatedLedgersInterface> ledgers
     );
 
     /**
-     * @brief Stops components and joins worker thread.
+     * @brief Create an instance of ETLService.
-     */
-    ~ETLService() override
-    {
-        if (not state_.isStopping)
-            stop();
-    }
-
-    /**
-     * @brief Stop the ETL service.
-     * @note This method blocks until the ETL service has stopped.
-     */
-    void
-    stop() override
-    {
-        LOG(log_.info()) << "Stop called";
-
-        state_.isStopping = true;
-        cacheLoader_.stop();
-
-        if (worker_.joinable())
-            worker_.join();
-
-        LOG(log_.debug()) << "Joined ETLService worker thread";
-    }
-
-    /**
-     * @brief Get time passed since last ledger close, in seconds.
      *
-     * @return Time passed since last ledger close
+     * @param ctx The execution context for asynchronous operations
+     * @param config The Clio configuration definition
+     * @param backend Interface to the backend database
+     * @param balancer Load balancer for distributing work
+     * @param ledgers Interface for accessing network validated ledgers
+     * @param publisher Interface for publishing ledger data
+     * @param cacheLoader Interface for loading cache data
+     * @param cacheUpdater Interface for updating cache data
+     * @param extractor The extractor to use
+     * @param loader Interface for loading data
+     * @param initialLoadObserver The observer for initial data loading
+     * @param taskManagerProvider The provider of the task manager instance
+     * @param monitorProvider The provider of the monitor instance
+     * @param state System state tracking object
      */
-    std::uint32_t
+    ETLService(
-    lastCloseAgeSeconds() const override
+        util::async::AnyExecutionContext ctx,
-    {
+        std::reference_wrapper<util::config::ClioConfigDefinition const> config,
-        return ledgerPublisher_.lastCloseAgeSeconds();
+        std::shared_ptr<data::BackendInterface> backend,
-    }
+        std::shared_ptr<LoadBalancerInterface> balancer,
+        std::shared_ptr<NetworkValidatedLedgersInterface> ledgers,
+        std::shared_ptr<LedgerPublisherInterface> publisher,
+        std::shared_ptr<CacheLoaderInterface> cacheLoader,
+        std::shared_ptr<CacheUpdaterInterface> cacheUpdater,
+        std::shared_ptr<ExtractorInterface> extractor,
+        std::shared_ptr<LoaderInterface> loader,
+        std::shared_ptr<InitialLoadObserverInterface> initialLoadObserver,
+        std::shared_ptr<TaskManagerProviderInterface> taskManagerProvider,
+        std::shared_ptr<MonitorProviderInterface> monitorProvider,
+        std::shared_ptr<SystemState> state
+    );
 
-    /**
+    ~ETLService() override;
-     * @brief Check for the amendment blocked state.
-     *
-     * @return true if currently amendment blocked; false otherwise
-     */
-    bool
-    isAmendmentBlocked() const override
-    {
-        return state_.isAmendmentBlocked;
-    }
 
-    /**
-     * @brief Check whether Clio detected DB corruptions.
-     *
-     * @return true if corruption of DB was detected and cache was stopped.
-     */
-    bool
-    isCorruptionDetected() const override
-    {
-        return state_.isCorruptionDetected;
-    }
-
-    /**
-     * @brief Get state of ETL as a JSON object
-     *
-     * @return The state of ETL as a JSON object
-     */
-    boost::json::object
-    getInfo() const override
-    {
-        boost::json::object result;
-
-        result["etl_sources"] = loadBalancer_->toJson();
-        result["is_writer"] = static_cast<int>(state_.isWriting);
-        result["read_only"] = static_cast<int>(state_.isStrictReadonly);
-        auto last = ledgerPublisher_.getLastPublish();
-        if (last.time_since_epoch().count() != 0)
-            result["last_publish_age_seconds"] = std::to_string(ledgerPublisher_.lastPublishAgeSeconds());
-        return result;
-    }
-
-    /**
-     * @brief Get the etl nodes' state
-     * @return The etl nodes' state, nullopt if etl nodes are not connected
-     */
-    std::optional<etl::ETLState>
-    getETLState() const noexcept override
-    {
-        return loadBalancer_->getETLState();
-    }
-
-    /**
-     * @brief Start all components to run ETL service.
-     */
     void
     run() override;
 
-private:
-    /**
-     * @brief Run the ETL pipeline.
-     *
-     * Extracts ledgers and writes them to the database, until a write conflict occurs (or the server shuts down).
-     * @note database must already be populated when this function is called
-     *
-     * @param startSequence the first ledger to extract
-     * @param numExtractors number of extractors to use
-     * @return The last ledger written to the database, if any
-     */
-    std::optional<uint32_t>
-    runETLPipeline(uint32_t startSequence, uint32_t numExtractors);
-
-    /**
-     * @brief Monitor the network for newly validated ledgers.
-     *
-     * Also monitor the database to see if any process is writing those ledgers.
-     * This function is called when the application starts, and will only return when the application is shutting down.
-     * If the software detects the database is empty, this function will call loadInitialLedger(). If the software
-     * detects ledgers are not being written, this function calls runETLPipeline(). Otherwise, this function publishes
-     * ledgers as they are written to the database.
-     */
     void
-    monitor();
+    stop() override;
 
-    /**
+    boost::json::object
-     * @brief Monitor the network for newly validated ledgers and publish them to the ledgers stream
+    getInfo() const override;
-     *
-     * @param nextSequence the ledger sequence to publish
-     * @return The next ledger sequence to publish
-     */
-    uint32_t
-    publishNextSequence(uint32_t nextSequence);
 
-    /**
-     * @brief Monitor the database for newly written ledgers.
-     *
-     * Similar to the monitor(), except this function will never call runETLPipeline() or loadInitialLedger().
-     * This function only publishes ledgers as they are written to the database.
-     */
-    void
-    monitorReadOnly();
-
-    /**
-     * @return true if stopping; false otherwise
-     */
     bool
-    isStopping() const
+    isAmendmentBlocked() const override;
-    {
+
-        return state_.isStopping;
+    bool
-    }
+    isCorruptionDetected() const override;
+
+    std::optional<ETLState>
+    getETLState() const override;
 
-    /**
-     * @brief Get the number of markers to use during the initial ledger download.
-     *
-     * This is equivalent to the degree of parallelism during the initial ledger download.
-     *
-     * @return The number of markers
-     */
     std::uint32_t
-    getNumMarkers() const
+    lastCloseAgeSeconds() const override;
-    {
+
-        return numMarkers_;
+private:
-    }
+    std::optional<data::LedgerRange>
+    loadInitialLedgerIfNeeded();
 
-    /**
-     * @brief Spawn the worker thread and start monitoring.
-     */
     void
-    doWork();
+    startMonitor(uint32_t seq);
+
+    void
+    startLoading(uint32_t seq);
+
+    void
+    attemptTakeoverWriter();
+
+    void
+    giveUpWriter();
 };
+
 }  // namespace etl

src/etl/ETLServiceInterface.hpp

@@ -26,7 +26,7 @@
 #include <cstdint>
 #include <optional>
 
-namespace etlng {
+namespace etl {
 
 /**
  * @brief This is a base class for any ETL service implementations.
@@ -77,7 +77,7 @@ struct ETLServiceInterface {
      * @brief Get the etl nodes' state
      * @return The etl nodes' state, nullopt if etl nodes are not connected
      */
-    [[nodiscard]] virtual std::optional<etl::ETLState>
+    [[nodiscard]] virtual std::optional<ETLState>
     getETLState() const = 0;
 
     /**
@@ -89,4 +89,4 @@ struct ETLServiceInterface {
     lastCloseAgeSeconds() const = 0;
 };
 
-}  // namespace etlng
+}  // namespace etl

src/etl/ExtractorInterface.hpp

@@ -19,12 +19,12 @@
 
 #pragma once
 
-#include "etlng/Models.hpp"
+#include "etl/Models.hpp"
 
 #include <cstdint>
 #include <optional>
 
-namespace etlng {
+namespace etl {
 
 /**
  * @brief An interface for the Extractor
@@ -51,4 +51,4 @@ struct ExtractorInterface {
     extractLedgerOnly(uint32_t seq) = 0;
 };
 
-}  // namespace etlng
+}  // namespace etl

src/etl/InitialLoadObserverInterface.hpp

@@ -19,7 +19,7 @@
 
 #pragma once
 
-#include "etlng/Models.hpp"
+#include "etl/Models.hpp"
 
 #include <xrpl/protocol/LedgerHeader.h>
 
@@ -28,7 +28,7 @@
 #include <string>
 #include <vector>
 
-namespace etlng {
+namespace etl {
 
 /**
  * @brief The interface for observing the initial ledger load
@@ -51,4 +51,4 @@ struct InitialLoadObserverInterface {
     ) = 0;
 };
 
-}  // namespace etlng
+}  // namespace etl