Merge #315: Add rust-toolchain.toml file

6f140ed ci: add overview documentation to ci workflows (thunderbiscuit)
c6af44b chore: bump rust-toolchain.toml channel to 1.90.0 (stable) (thunderbiscuit)
3ffe0ff ci: remove cron-update-rust workflow (thunderbiscuit)
1589e8e ci: fix code coverage workflow (thunderbiscuit)
2d85143 ci: update actions/checkout to version 5 (thunderbiscuit)
ab5a348 ci: leverage rust-toolchain.toml file in ci workflows (thunderbiscuit)
aa6bea0 build: add rust-toolchain.toml file (thunderbiscuit)

Pull request description:

  This addresses #314. It also incorporates the changes in #299.

  The rust-toolchain.toml file is used to help contributors build, format, and clippy check the codebase using the same version of the Rust compiler. It can easily be overriden, but if no other arguments are supplied to commands like `cargo run`, `cargo fmt`, and `cargo clippy`, they will pick the version defined in this file.

  In order to ensure the CI runs and the default versions devs build the library with (the one defined in `rust-toolchain.toml`) stay in sync, a few changes were made to the `cont_integration.yaml` workflow:

  1. I removed the "prepare" job, which parsed the rust-version file in order to use it throughout the CI jobs.
  2. I split the `Build & Test` job (and the 3-way matrix of (a) OS, (b) compilation features, (c) Rust version) into 2 different jobs. This is IMO easier for the eye to parse when looking at the workflow, and fully separate the testing of the MSRV and Stable into two separate jobs instead of a matrix of jobs with some extra of if/else stuff (for running the pinning script for example). The 2 jobs are now called `Build & Test MSRV` and `Build and Test Stable`. Note that this makes it easier to see and understand the workflow in the GitHub UI.
  3. I picked a new "rust toolchain" action, [setup-rust-toolchain](https://github.com/actions-rust-lang/setup-rust-toolchain). It's the one recommended to me by both ChatGPT and Claude, and has a lot of stars and users (albeit a bit less than the dtolnay action, which its readme cites as its main inspiration). The reason for this is 2-fold: (a) it comes with caching out of the box, and (b) it respects the `toolchain.toml` file by default. [See their docs on this exact feature](https://github.com/actions-rust-lang/setup-rust-toolchain?tab=readme-ov-file#inputs). This makes our workflows easy to work with: in the first job, we explicitly set the toolchain version to our MSRV, in the second we let the action download the toolchain defined in rust-toolchain.toml.

  I also bumped the checkout action to its latest v5 version (last commit).

  close #314
  close #299

  ### Checklists

  #### All Submissions:

  * [x] I've signed all my commits
  * [x] I followed the [contribution guidelines](https://github.com/bitcoindevkit/bdk/blob/master/CONTRIBUTING.md)
  * [x] I ran `just p` before pushing

ACKs for top commit:
  ValuedMammal:
    ACK 6f140ed
  oleonardolima:
    utACK 6f140ed

Tree-SHA512: 3ddd396c9e85a0addc428438747c78b1e576246b7dce47ea1a8c8f724638f9d79e611be986f36600a28daa45af58603bc7e9b76f0e20264f8af231cbaf820251

Author: ValuedMammal

.github/workflows/audit.yml

@@ -1,5 +1,9 @@
 name: Audit
 
+# Performs a security audit of Rust dependencies using cargo-audit through the actions-rust-lang/audit action.
+# Runs nightly on schedule and when Cargo.toml, Cargo.lock, or audit.toml files are modified.
+# Helps identify known security vulnerabilities in the dependency tree.
+
 on:
   push:
     paths:
@@ -23,7 +27,8 @@ jobs:
       contents: read
       issues: write
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
       - uses: actions-rust-lang/audit@v1

.github/workflows/code_coverage.yml

@@ -1,7 +1,11 @@
-on: [push, pull_request]
-
 name: Code Coverage
 
+# Generates code coverage reports using grcov and uploads results to Coveralls.
+# Runs on every push and pull request to track test coverage metrics.
+# Uploads coverage data to Coveralls for tracking and produces an HTML report artifact for download.
+
+on: [push, pull_request]
+
 permissions: {}
 
 jobs:
@@ -15,32 +19,34 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
       - name: Install lcov tools
         run: sudo apt-get install lcov -y
+      # This action automatically reads and applies rust-toolchain.toml
       - name: Install Rust toolchain
-        uses: dtolnay/rust-toolchain@v1
+        uses: actions-rust-lang/setup-rust-toolchain@v1
         with:
-            toolchain: stable
-            components: llvm-tools-preview
-      - name: Rust Cache
-        uses: Swatinem/rust-cache@98c8021b550208e191a6a3145459bfc9fb29c4c0
+          components: llvm-tools-preview
+          cache: true
       - name: Install grcov
         run: if [[ ! -e ~/.cargo/bin/grcov ]]; then cargo install grcov; fi
       - name: Test
         run: cargo test --all-features
       - name: Make coverage directory
         run: mkdir coverage
       - name: Run grcov
-        run: grcov . --binary-path ./target/debug/ -s . -t lcov --branch --ignore-not-existing --keep-only '**/wallet/**' --ignore '**/tests/**' --ignore '**/examples/**' -o ./coverage/lcov.info
+        run: grcov . --binary-path ./target/debug/ -s . -t lcov --branch --ignore-not-existing --keep-only 'src/**' --ignore 'tests/**' --ignore 'examples/**' -o ./coverage/lcov.info
       - name: Generate HTML coverage report
         run: genhtml -o coverage-report.html --ignore-errors unmapped ./coverage/lcov.info
       - name: Coveralls upload
-        uses: coverallsapp/github-action@master
+        # Action pinned at tag 2.3.6
+        uses: coverallsapp/github-action@648a8eb78e6d50909eff900e4ec85cab4524a45b
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
+          file: ./coverage/lcov.info
+          format: lcov
       - name: Upload artifact
         uses: actions/upload-artifact@v4
         with:

.github/workflows/cont_integration.yml

@@ -1,5 +1,9 @@
 on: [push, pull_request]
 
+# Main continuous integration workflow that runs build, test, and code quality checks.
+# Runs on every push and pull request, testing against both MSRV (1.85) and stable Rust.
+# Includes no_std and WASM compatibility checks, formatting validation, and clippy linting.
+
 name: CI
 
 permissions: {}
@@ -8,133 +12,137 @@ env:
   CARGO_TERM_COLOR: always
 
 jobs:
-  prepare:
-    runs-on: ubuntu-latest
-    outputs:
-      rust_version: ${{ steps.read_toolchain.outputs.rust_version }}
+  build-test-msrv:
+    name: Build & Test MSRV
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os:
+          - ubuntu-latest
+          - ubuntu-24.04-arm
+        features:
+          - --no-default-features --features miniscript/no-std,bdk_chain/hashbrown
+          - --all-features
     steps:
-      - name: "Checkout repo"
-        uses: actions/checkout@v4
+      - name: Checkout
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
-      - name: "Read rust version"
-        id: read_toolchain
-        run: echo "rust_version=$(cat rust-version)" >> $GITHUB_OUTPUT
+      # The 'toolchain' argument on this action overrides the Rust compiler version set in rust-toolchain.toml
+      # in order to test our MSRV.
+      - name: Install Rust toolchain
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: 1.85 # MSRV
+          cache: true
+      - name: Pin dependencies for MSRV
+        run: ./ci/pin-msrv.sh
+      - name: Build + Test
+        run: |
+          cargo build --workspace --all-targets ${{ matrix.features }}
+          cargo test --workspace ${{ matrix.features }}
 
-  build-test:
-    needs: prepare
-    name: Build & Test
+  build-test-stable:
+    name: Build & Test Rust Stable
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
         os:
           - ubuntu-latest
           - ubuntu-24.04-arm
-        rust:
-          - version: ${{ needs.prepare.outputs.rust_version }}
-          - version: 1.85.0 # MSRV
         features:
           - --no-default-features --features miniscript/no-std,bdk_chain/hashbrown
           - --all-features
     steps:
-      - name: checkout
-        uses: actions/checkout@v4
+      - name: Checkout
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
+      # This action will honor the Rust compiler version set in rust-toolchain.toml. We aim to keep it in sync with
+      # Rust stable.
       - name: Install Rust toolchain
-        uses: dtolnay/rust-toolchain@v1
+        uses: actions-rust-lang/setup-rust-toolchain@v1
         with:
-            toolchain: ${{ matrix.rust.version }}
-      - name: Rust Cache
-        uses: Swatinem/rust-cache@98c8021b550208e191a6a3145459bfc9fb29c4c0
-      - name: Pin dependencies for MSRV
-        if: matrix.rust.version == '1.85.0'
-        run: ./ci/pin-msrv.sh
+          cache: true
       - name: Build + Test
-        env:
-          MATRIX_RUST_VERSION: ${{ matrix.rust.version }}
         run: |
           cargo build --workspace --all-targets ${{ matrix.features }}
           cargo test --workspace ${{ matrix.features }}
 
   check-no-std:
-    needs: prepare
     name: Check no_std
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
+      # This action automatically reads and applies rust-toolchain.toml
       - name: Install Rust toolchain
-        uses: dtolnay/rust-toolchain@v1
+        uses: actions-rust-lang/setup-rust-toolchain@v1
         with:
-          toolchain: ${{ needs.prepare.outputs.rust_version }}
-          # target: "thumbv6m-none-eabi"
-      - name: Rust Cache
-        uses: Swatinem/rust-cache@98c8021b550208e191a6a3145459bfc9fb29c4c0
+          cache: true
       - name: Check no-std
         # TODO "--target thumbv6m-none-eabi" should work but currently does not
         run: cargo check --no-default-features --features miniscript/no-std,bdk_chain/hashbrown
 
   check-wasm:
-    needs: prepare
     name: Check WASM
     runs-on: ubuntu-latest
     env:
       CC: clang-14
       CFLAGS: -I/usr/include
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
         # Install a recent version of clang that supports wasm32
       - run: wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add - || exit 1
       - run: sudo apt-get update || exit 1
       - run: sudo apt-get install -y libclang-common-14-dev clang-14 libc6-dev-i386 || exit 1
+      # This action automatically reads and applies rust-toolchain.toml
       - name: Install Rust toolchain
-        uses: dtolnay/rust-toolchain@v1
+        uses: actions-rust-lang/setup-rust-toolchain@v1
         with:
-            toolchain: ${{ needs.prepare.outputs.rust_version }}
-            targets: "wasm32-unknown-unknown"
-      - name: Rust Cache
-        uses: Swatinem/rust-cache@98c8021b550208e191a6a3145459bfc9fb29c4c0
+          cache: true
+          target: wasm32-unknown-unknown
       - name: Check WASM
-        run: cargo check --target wasm32-unknown-unknown --no-default-features --features miniscript/no-std,bdk_chain/hashbrown
+        run: |
+          rustup target add wasm32-unknown-unknown
+          cargo check --target wasm32-unknown-unknown --no-default-features --features miniscript/no-std,bdk_chain/hashbrown
 
   fmt:
     name: Rust fmt
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
+      # This action automatically reads and applies rust-toolchain.toml
       - name: Install Rust toolchain
-        uses: dtolnay/rust-toolchain@v1
+        uses: actions-rust-lang/setup-rust-toolchain@v1
         with:
-            toolchain: nightly
-            components: rustfmt
+          cache: true
       - name: Check fmt
         run: cargo fmt --all --check
 
   clippy_check:
-    needs: prepare
     name: Rust clippy
     runs-on: ubuntu-latest
     permissions:
       checks: write
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
-      - uses: dtolnay/rust-toolchain@v1
+      # This action automatically reads and applies rust-toolchain.toml
+      - name: Install Rust toolchain
+        uses: actions-rust-lang/setup-rust-toolchain@v1
         with:
-            toolchain: ${{ needs.prepare.outputs.rust_version }}
-            components: clippy
-      - name: Rust Cache
-        uses: Swatinem/rust-cache@98c8021b550208e191a6a3145459bfc9fb29c4c0
+          cache: true
       - name: Clippy
         run: cargo clippy --all-features --all-targets -- -D warnings
 

.github/workflows/cron-update-rust.yml

@@ -1,5 +1,10 @@
 name: Zizmor Actions Analysis
 
+# Analyzes GitHub Actions workflows for security vulnerabilities using zizmor.
+# Runs on pushes to master and all pull requests to detect potential security issues
+# in workflow configurations. Results are uploaded to GitHub's security dashboard.
+# The .github/zizmor.yml file configures the rules this action will check against.
+
 on:
   push:
     branches: ["master"]
@@ -12,8 +17,8 @@ jobs:
     permissions:
       security-events: write
     steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
+      - name: Checkout
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
 

.github/workflows/zizmor.yml

@@ -4,4 +4,5 @@ rules:
     config:
       policies:
         # Allow pin by ref/tag
-        dtolnay/rust-toolchain: ref-pin
+        actions-rust-lang/setup-rust-toolchain: ref-pin
+        actions/*: ref-pin

.github/zizmor.yml

@@ -0,0 +1,3 @@
+[toolchain]
+channel = "1.90.0"
+components = ["clippy", "rustfmt"]