Release Checklist

Fork height set (rebooted chain: all features at HF 1 from genesis)

Shekyl announcement mailer / notice
Twitter announcement
Reddit announcement
Project website announcement

Notify wallets (placeholder -- replace with actual Shekyl-compatible wallets pre-launch)

Shekyl GUI Wallet (first-party)
Shekyl CLI (first-party)
(third-party wallet integrations TBD)

Notify exchanges (placeholder -- replace with actual exchange partners pre-launch)

(exchange integrations TBD)

Notify 3rd party payment processors (placeholder)

(payment gateway integrations TBD)

Notify mining pools (placeholder)

(mining pool partnerships TBD)

Release tagged

Update src/version.cpp.in with new version AND new name (if necessary)
Update Gitian YML files in contrib/gitian/ to the new version number
Update README.md with new fork table entry (or recommended Shekyl version)
Update contrib/gitian/README.md so that the instructions reflect the current version
Update src/checkpoints/checkpoints.cpp with a recent hardcoded checkpoint

Testnet forked

Testnet testing/verification

CLI reproducible builds validated

Rust/PQC reproducible build inputs documented

Bundled Tor pin current (2d-2 archival firewall, SP-T0c; TOR_BUNDLE_DISTRIBUTION.md TB-6…TB-10 — the pin of record is config/tor_pins.json)

Every managed tor launch, the daemon's and the wallet's, is gated on the pin: rust/shekyl-tor-control-client/src/binary.rs mints the VerifiedTorBinary witness a launch requires only when tor's directory holds exactly the pinned files and each hashes to its pin. Release artifacts carry that bundle. A stale or unverified pin is a mission-#1 (security-precondition) gap, so this is a recurring duty, not a one-time step.
Watch https://www.torproject.org/download/tor/ for a new stable Tor Expert Bundle or a security advisory since the recorded pin (and the alpha line, for linux-aarch64).
Ensure the signing key is in your keyring (fresh machine): gpg --auto-key-locate nodefault,wkd --locate-keys [email protected], then confirm the primary fingerprint is EF6E286DDA85EA2A4BA7DE684E2C6E8793298290 (signing_key_fingerprint in config/tor_pins.json, compiled as TOR_SIGNING_KEY_FPR).
On a new stable / advisory, per pinned target: download the Expert Bundle tarball and its .asc, then gpg --status-fd 1 --verify <file>.asc <file> — require a VALIDSIG line whose last field, the primary key, is that fingerprint; GOODSIG alone matches any key the keyring happens to hold (the durable pin is this key, not any single hash).
Record, in that target's row of config/tor_pins.json: bundle_version, tor_version, the tarball's sha256sum as tarball_sha256, and the sha256sum of each file Shekyl ships from the tarball's tor/ directory under files (on Linux tor, libevent-2.1.so.7, libssl.so.3, libcrypto.so.3; on Windows tor.exe). On Windows also re-derive imports from the new tor.exe itself, never from the old list: the DLL Name lines of objdump -p tor.exe, and its Delay Import Directory must be empty. tor_bundle.py refuses a DLL the list does not name and any delay-load import, so a changed set is a stop: say what changed and why it is safe before recording it. On macOS, files are the Developer ID-signed copies and Tor's own go under upstream: see the macOS step below. If the new bundle's tor needs a library the old one did not ship, it is a new files entry: the daemon refuses a tor directory that holds anything unlisted, and one that lacks anything listed. Nothing else in the tree carries a digest — build.rs compiles the row and scripts/release/tor_bundle.py packages from it.
macOS: sign once, then upload (TB-11; Rick, 2026-10-23). A Developer ID signature carries a secure timestamp, so signing twice gives different bytes: the pair is signed once per re-pin and those files ship in every build. (1) On the signing host, the maintainer who holds the Developer ID unlocks its keychain and signs each target's tor and libevent-2.1.7.dylib together, hardened runtime on, with a secure timestamp and no entitlements (the signed tor refuses a libevent signed by another team). (2) python3 scripts/release/tor_bundle.py tie --tarball <the GPG-verified tarball> --signed <dir> must exit 0: it proves every byte outside each signature is Tor's and prints files (signed) and upstream (Tor's) for the row. (3) Check that each signed tor runs: --version and --library-versions exit 0. (4) Upload the four files to a release on this repository named tor-macos-<bundle_version>-signed, assets <bundle_target>-<file name> (the signed_url template in config/tor_pins.json), marked not latest; download each back and compare its SHA-256 with the row. The digest in the row is the integrity check, not the hosting. The release build's fetch puts the assets in the sources cache (tor-signed-<bundle_target>-<bundle_version>/). stage reads that directory and no other; it re-checks the tie before packing. The files are never committed and are not a CI artifact.
Update the two prose records that point at the pin: the "Current pin" paragraphs in docs/design/ARCHIVAL_BOND_2D2_SP_T0_TOR.md (move the old pin to its "Superseded pins" note with its tarball hash) and the "Current pin" lines below. scripts/ci/check_tor_pin_targets.py fails until the lines below name the new versions.
Re-verify locally: python3 scripts/release/tor_bundle.py stage --host <gitian-host> --sources <dir holding the verified tarball> --dest <fresh>/tor --licenses <fresh>/tor-licenses, then SHEKYL_TEST_PINNED_TOR_BINARY=<fresh>/tor/tor cargo test -p shekyl-tor-control-client --lib binary -- --ignored — bundled_tor_matches_recorded_pin must pass. (The test is not cfg-gated: on a target with no pin it fails loudly instead of reporting a vacuous 0-test green. Pointing it at the raw extracted bundle fails by design: that directory carries pluggable_transports/.)
Re-check the bootstrap-problem reason the managed Tor's supervisor reads as a clock difference, not a blocked link (TOR_SUPERVISOR.md §5, "Clock skew"): control_event_bootstrap_problem(warn, "CLOCK_SKEW", …) beside the CLOCK_SKEW SKEW= status event in clock_skew_warning, in the new tor's src/core/mainloop/connection.c (line 6022 at tor-0.4.9.14). A renamed reason fails a_clock_skew_bootstrap_problem_is_not_a_blocked_link only once its line is re-captured, so read the source.
Re-check the certificate lines the supervisor reads as the clock (TOR_SUPERVISOR.md §4.2, §5 "Certificates out of date"; CERTIFICATE_OUT_OF_DATE in rust/shekyl-tor-control-client/src/supervisor/events.rs) in the new tor's source: ERR("At least one certificate expired.") under "Received a bad CERTS cell: %s" in or_handshake_certs_ed25519_ok, src/feature/relay/torcert.c; and "Certificate %s. Either their clock is set wrong, or your clock is wrong." with "not yet valid" and "already expired" in log_cert_lifetime / tor_x509_check_cert_lifetime_internal, src/lib/tls/x509_openssl.c (all three at tor-0.4.9.14). Also that a closed handshake's bootstrap problem still reports REASON=DONE with the relay's HOSTID (control_event_bootstrap_problem, src/feature/control/control_bootstrap.c). A reword fails the_certificate_lines_are_tors_own_text; update the constant and that test together.
Re-check the onion-service descriptor upload cadence and lifetime in the new tor's source: HS_SERVICE_NEXT_UPLOAD_TIME_MIN and HS_SERVICE_NEXT_UPLOAD_TIME_MAX in src/feature/hs/hs_service.h (60 and 120 minutes at tor-0.4.9.13 and tor-0.4.9.14), and HS_DESC_DEFAULT_LIFETIME in src/feature/hs/hs_descriptor.h (3 hours at tor-0.4.9.14). The daemon's reachability probe runs once per upload round, so a changed cadence changes how long an unnoticed failure can last (TOR_SUPERVISOR.md TSR-Q5); it also publishes the onion again when no round begins within the lifetime, so a changed lifetime moves DESCRIPTOR_LIFETIME in shekyl-tor-control-client, whose test the_descriptor_lifetime_is_tors_three_hours pins it (§4.5, "Overdue").
Dispatch the tor-pin-verify workflow (.github/workflows/tor-pin-verify.yml). It takes no version input — it reads the pin file — and for each pinned target, Linux, Windows and macOS, runs fetch → GPG-verify → stage → pin-match, then the SP-T0 --lib live lifecycle tests against the staged bundle.
Current pin: Expert Bundle 15.0.25 (tor 0.4.9.14) for linux-x86_64 and windows-x86_64, verified and recorded 2026-10-17 (see config/tor_pins.json for the gate values — the file is canonical; this line is a pointer, not a second source of truth).
Current linux-aarch64 pin: Expert Bundle 16.0a14 (tor 0.4.9.14), verified and recorded 2026-10-17. This is an alpha, and it is pinned on purpose. The stable line publishes only linux-i686 and linux-x86_64 (the aarch64 builds are android- and macos-), so the alpha line is the only linux-aarch64 build there is, and the rule-76 floor device needs a VerifiedTorBinary to run the managed posture at all. Verified the same way as the stable pin: a VALIDSIG under the key above. Reopen: re-pin to the first stable bundle that ships linux-aarch64, and until then the alpha-line advisories are part of the watch above — see docs/design/ARCHIVAL_BOND_2D2_SP_T0_TOR.md.
Current macOS pin: Expert Bundle 15.0.26 (tor 0.4.9.14) for macos-aarch64 and macos-x86_64, recorded 2026-10-23 (Rick: pin macOS now). Its Tor files are byte-identical to 15.0.25's; the shipped files are the Developer ID-signed pair in the tor-macos-15.0.26-signed release. Not pinned: FreeBSD and riscv64 Linux.

CLI released

Project downloads page updated
Update hashes.txt on website
Update downloads.yml on website
Update auto-update DNS records on all 5 TLDs (see shekyl-dev/docs/DNS_CONFIG.md)
Update redirects on downloads box
Update seed nodes

GUI released (if applicable)

Project downloads page updated
Update hashes.txt on website
Update hashes.txt.sig on website
Update downloads.yml on website
Update auto-update DNS records on all 5 TLDs (see shekyl-dev/docs/DNS_CONFIG.md)
Update redirects on downloads box

Release Announcements

Shekyl announcement mailer notice
Twitter announcement
Reddit announcement
Project website announcement

Shekyl Stats

Network

Chain

Rewards

Supply

Economics

Staking

Protocol

Node

Release Checklist