From 8185b34dc9ba512b27d20925500d9b15fe694f8e Mon Sep 17 00:00:00 2001
From: Samet <chainsmt@gmail.com>
Date: Thu, 22 Oct 2026 16:20:10 +0300
Subject: [PATCH] ci(bindings): pin the Stellar CLI version

---
 .github/workflows/bindings-check.yml | 10 ++++++-
 docs/CI.md                           | 24 ++++++++++++++++
 scripts/check-bindings-cli.test.mjs  | 42 ++++++++++++++++++++++++++++
 3 files changed, 75 insertions(+), 1 deletion(-)
 create mode 100644 scripts/check-bindings-cli.test.mjs

diff --git a/.github/workflows/bindings-check.yml b/.github/workflows/bindings-check.yml
index 89e6e531..31366661 100644
--- a/.github/workflows/bindings-check.yml
+++ b/.github/workflows/bindings-check.yml
@@ -21,6 +21,9 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Assert pinned Stellar CLI workflow
+        run: node --test scripts/check-bindings-cli.test.mjs
+
       - name: Install Rust toolchain
         uses: dtolnay/rust-toolchain@stable
         with:
@@ -34,7 +37,12 @@ jobs:
         run: sudo apt-get update && sudo apt-get install -y build-essential pkg-config libssl-dev libdbus-1-dev libudev-dev libsodium-dev
 
       - name: Install stellar CLI
-        run: cargo install stellar-cli --locked
+        # 22.8.2 is the latest stable stellar-cli that still supports soroban-sdk 22.
+        # CLI 23.0.0 and newer require soroban-sdk 23.
+        run: cargo install stellar-cli --version 22.8.2 --locked
+
+      - name: Print Stellar CLI version
+        run: stellar --version
 
       - uses: pnpm/action-setup@v4
         with:
diff --git a/docs/CI.md b/docs/CI.md
index 84cc72ae..08553dbb 100644
--- a/docs/CI.md
+++ b/docs/CI.md
@@ -50,3 +50,27 @@ in the PR. The default is calibrated against the **weighted** covered/total
 ratio after including unexecuted `src/` files. Lower the threshold only when
 the existing codebase cannot meet a higher bar yet; prefer adding tests instead
 of weakening the gate.
+
+## Bindings check
+
+GitHub Actions workflow: `.github/workflows/bindings-check.yml`
+
+Generated contract bindings are built with Stellar CLI **22.8.2**. That is the
+latest stable 22.x release on crates.io, and it is the newest CLI that still
+supports this repo's `soroban-sdk` 22 (`Cargo.lock` resolves 22.0.11).
+`stellar-cli` 23.0.0 and newer depend on `soroban-sdk` 23, so they are not
+used for this contract.
+
+CI installs that release with:
+
+```bash
+cargo install stellar-cli --version 22.8.2 --locked
+stellar --version
+```
+
+`stellar --version` runs before `pnpm bindings:check`. The pin, `--locked`, and
+print order are asserted by:
+
+```bash
+node --test scripts/check-bindings-cli.test.mjs
+```
diff --git a/scripts/check-bindings-cli.test.mjs b/scripts/check-bindings-cli.test.mjs
new file mode 100644
index 00000000..b8e031d0
--- /dev/null
+++ b/scripts/check-bindings-cli.test.mjs
@@ -0,0 +1,42 @@
+// Copyright (c) 2026 Sub Rosa contributors
+import { readFileSync } from "node:fs";
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { fileURLToPath } from "node:url";
+
+const WORKFLOW_PATH = fileURLToPath(
+  new URL("../.github/workflows/bindings-check.yml", import.meta.url),
+);
+const DOCS_PATH = fileURLToPath(new URL("../docs/CI.md", import.meta.url));
+
+const PINNED_VERSION = "22.8.2";
+const INSTALL_COMMAND = `cargo install stellar-cli --version ${PINNED_VERSION} --locked`;
+
+describe("bindings-check Stellar CLI pin", () => {
+  it("installs an explicit stellar-cli version with --locked", () => {
+    const workflow = readFileSync(WORKFLOW_PATH, "utf8");
+    assert.match(workflow, new RegExp(INSTALL_COMMAND.replace(/[.]/g, "\\.")));
+    assert.doesNotMatch(
+      workflow,
+      /cargo install stellar-cli --locked(?!\s*--version)/,
+    );
+  });
+
+  it("prints stellar --version before pnpm bindings:check", () => {
+    const workflow = readFileSync(WORKFLOW_PATH, "utf8");
+    const versionAt = workflow.indexOf("stellar --version");
+    const checkAt = workflow.indexOf("pnpm bindings:check");
+    assert.ok(versionAt >= 0, "workflow must print stellar --version");
+    assert.ok(checkAt >= 0, "workflow must run pnpm bindings:check");
+    assert.ok(
+      versionAt < checkAt,
+      "stellar --version must run before pnpm bindings:check",
+    );
+  });
+
+  it("documents the pinned CLI version", () => {
+    const docs = readFileSync(DOCS_PATH, "utf8");
+    assert.match(docs, new RegExp(`Stellar CLI \\*\\*${PINNED_VERSION}\\*\\*`));
+    assert.match(docs, new RegExp(INSTALL_COMMAND.replace(/[.]/g, "\\.")));
+  });
+});