Protocol Canary
Protocol Canary is a command-line tool that checks whether a Stellar application or piece of infrastructure remains compatible with a target Stellar protocol version. It runs a set of explicit, declared compatibility assertions (“fixtures”) against three surfaces a Stellar project typically depends on: XDR encoding/decoding, Stellar RPC responses, and Soroban transaction simulation.
It is developer infrastructure — a CLI and a GitHub Action, not a frontend application, not a smart contract, not a wallet, and not a hosted service. It does not certify that an arbitrary application is completely compatible with a Stellar protocol version; it reports whether the compatibility assertions currently implemented in its fixture packs pass against your configured dependencies and RPC endpoint.
What it checks
| Surface | What it verifies |
|---|---|
| XDR | Decode, encode, and round-trip fixtures against the official stellar-xdr crate. Runs fully offline — no network call. |
| RPC | getNetwork/getLatestLedger response-shape and protocol-identity assertions against a configured Stellar RPC endpoint. |
| Soroban | Unsigned transaction construction and simulateTransaction behavior. Never submits a transaction and never requires a private key. |
Who this is for
- New to Protocol Canary? Start with What Problem Does It Solve? and How It Works.
- Evaluating Protocol 28 compatibility? Go straight to Protocol 28.
- Wiring this into CI? See the GitHub Action guide.
- Adding a compatibility fixture or engine check? See Fixtures and Authoring a Fixture.
- Reviewing this project? Architecture, Security, and Limitations are the three pages written specifically for that.
Quick example
cargo install --git https://github.com/StellarCanary/Protocol-Canary --tag v0.1.1 --locked
stellar-canary check --fixtures-dir <checkout-of-ProtocolCanary-Fixtures>/protocol-28 --protocol 28
Stellar Protocol Canary
────────────────────────────────────────
Project: Protocol-Canary (unknown)
Target protocol: 28
Network: testnet (observed protocol 28)
XDR
3/3 PASS
RPC
1/1 PASS
Soroban
1/1 PASS
────────────────────────────────────────
5/5 applicable checks passed.
Status: PASS
This is a real run’s output (not illustrative text) — see Your First Check to reproduce it yourself.
Current support
| CLI release | Protocol-Canary v0.1.1 |
| GitHub Action | ProtocolCanary-Action v1 (currently resolves to v0.1.1) |
| Fixture pack | ProtocolCanary-Fixtures protocol-28/ — 5 currently implemented checks |
| Protocol coverage | Protocol 28 only. CAP-0086 is a documented gap, not silently skipped. |
Ecosystem
Three repositories make up Protocol Canary:
| Repository | Purpose |
|---|---|
StellarCanary/Protocol-Canary | The compatibility engine — the stellar-canary CLI. |
StellarCanary/ProtocolCanary-Fixtures | Canonical, versioned compatibility fixtures (declarative TOML data, no executable code). |
StellarCanary/ProtocolCanary-Action | The GitHub Actions integration that installs a pinned CLI release and turns its report into a job summary, annotations, and an artifact. |
See Architecture for how they fit together, CLI Reference for every command, and Contributing to work on any of the three.