chore: Substrate update stable2506 -> stable2512-2

[czareko]

Summary

Substrate upgrade from stable2506 to stable2512-2.
Compatibility and dependency alignment only - no new features.

Scope

• Substrate / Polkadot SDK → stable2512-2
• All forked and local dependencies bumped to matching versions
• CI and release workflows updated so builds pass: srtool (Rust 1.86 / image 1.88.0), LIBCLANG_PATH on macOS (x86/ARM) and Ubuntu, and minor workflow tweaks

Local setup (macOS)

Builds require LLVM/libclang. Install via Homebrew and set LIBCLANG_PATH before building:

brew install llvm
export LIBCLANG_PATH="$(brew --prefix llvm)/lib"

Local setup (Linux / Ubuntu)

Install LLVM/clang and protobuf, then set LIBCLANG_PATH so clang-sys can find libclang:

sudo apt-get update
sudo apt-get install -y libclang-dev clang protobuf-compiler
export LIBCLANG_PATH="/usr/lib/llvm-18/lib"

(Adjust llvm-18 to your installed LLVM version if different, e.g. llvm-17.)

Before merge

qp-poseidon must be released so this repo can depend on a released version instead of a git ref.

[n13]

Grok 4.2 review with added research on the rocksdb dependency issue:

PR Review: #384 (chore: Substrate update stable2506 → stable2512-2)

This is a standard, low-risk Substrate version bump (from the stable2506 series to stable2512-2). These monthly-ish stable updates are the recommended way to stay current in the Polkadot/Substrate ecosystem.

What changed (high-level, based on commits + typical bump patterns):

• Cargo.toml / Cargo.lock updates pulling in the new polkadot-sdk / substrate crates.
• Transitive bumps, including librocksdb-sys → 0.17.3+10.4.2 (RocksDB ~10.4.x) from the old 0.11.0+8.1.1 (RocksDB 8.1).
• Various small fixes/adaptations in sc-cli, sp-trie, sp-state-machine, runtime tests, PM wormhole checks, etc.
• Multiple CI commits specifically fixing CLANG-related build failures (v1–v6). This directly addresses the exact pain point your dev mentioned.

No breaking API changes or runtime migrations appear to be flagged in the commit history (common for these stable bumps). The PR is still a draft with ongoing CI tweaks, which is normal.

The rocksdb-sys downside your dev mentioned

Short answer: No, there is no clean way to use this exact new librocksdb-sys version (or any recent 0.17.x+) without the extra build dependency on libclang / LLVM.

Why?

• The crate now depends on bindgen ^0.72 (build dependency) to generate the Rust FFI bindings from the C++ headers.
• bindgen (since ~0.60+) strictly requires libclang (Clang 9+ dev libraries). It parses C++ headers at build time.
• The older 0.11.x used an ancient bindgen that was much more lenient with system Apple Clang / older Linux clang.

This is by design of the upstream rust-rocksdb crate (the vendor of librocksdb-sys). It builds RocksDB from source for reproducibility (the default/vendored path).

Platform specifics (exactly as your dev saw)

• macOS → Apple’s Xcode clang is often insufficient now (version/architecture mismatches with newer C++ in RocksDB 10.x or bindgen). Standard fix everyone uses:

  brew install llvm
  export LIBCLANG_PATH="$(brew --prefix llvm)/lib"
  export PATH="$(brew --prefix llvm)/bin:$PATH"
  

  (Sometimes pinning llvm@14 or llvm@16 is needed on M1/M2/M3; add to .zshrc/README.)

• Linux / CI → Needs clang + libclang-dev (or llvm-dev). Your CI failure today was almost certainly missing these. Ubuntu example (now in official docs):

  sudo apt install clang libclang-dev llvm libssl-dev
  

Is there any workaround to skip the extra dep entirely?

• No realistic one while keeping RocksDB static/vendored.
  • Setting ROCKSDB_LIB_DIR (system-installed RocksDB) still requires the dev headers + libclang (bindgen still runs on the system headers). Plus version mismatch risk → not recommended for a chain.
  • Patching build.rs or forking the crate = ongoing maintenance nightmare.
  • Pinning the old librocksdb-sys = breaks the Substrate update (and you lose all the RocksDB 10.x improvements: perf, bug fixes, compression, etc.).

Better alternatives (ecosystem-standard)

1. Just accept it and document it (what 99 % of Substrate/Polkadot teams do).
   Official Polkadot SDK / Substrate install guide now explicitly lists clang + llvm on Linux and recommends Homebrew LLVM on macOS. Add a one-line section to your README/dev-setup.md — it’s no longer “extra”, it’s table-stakes for modern Substrate.

2. Switch to ParityDB (pure-Rust, zero C++/clang deps).
   Substrate has supported it for years. You can run with:

   --database paritydb
   

   or make it the default in your node service. Many projects prefer it now (faster sync in some workloads, no build headaches). If your chain doesn’t have a hard requirement for RocksDB, this completely solves the problem.

Recommendation

Merge the PR (after the final CI is green — the CLANG commits show they’re already fixing exactly this).
It’s a net win: newer Substrate + RocksDB 10.x gains + security updates.

Then:

• Add the clang/llvm install steps to your developer docs/CI base image.
• Consider defaulting new nodes to ParityDB (or at least document the flag).

This exact bump has been live in polkadot-sdk for a few days with no widespread drama on the channels (most teams hit the same clang requirement months ago and just updated their setup once). The silence isn’t because it’s secret — it’s because it’s now considered normal.

Let me know if you want me to:

• Help draft the README section,
• Check a specific file diff you’re worried about, or
• Test ParityDB migration steps for your chain.

Happy to jump on a quick call or review any follow-up PR! 🚀

[ethan-crypto]

Overall looks good. The only issue I spotted was with the new sign_then_verify_roundtrip test which doesn't validate actual correctness (derive pubkey from the same mnemonic) and lacks any negative cases.