From 03fe921a381726f7e121887b689fc4be0cab9941 Mon Sep 17 00:00:00 2001 From: Ben Westgate Date: Thu, 22 Oct 2026 09:49:55 -0500 Subject: [PATCH 1/3] core: Pin fixtures and tutorials to stable v32.1 Replace the 32.0rc2 fixture archive and RC tutorial links with the published stable 32.1 release. Upstream canceled binary publication for the tagged 32.0 release, so its archive URL cannot be qualified. Pin both previously moving offline-signing links to the same released tag. The Linux archive SHA256 agrees with the valid signed fanquake and achow101 build attestations in bitcoin-core/guix.sigs at fdc0f9635ca5bee7dd46c51f3bcf3afca83b2d5d. Verified the downloaded official archive against that digest and the official signed checksum file. Validation: tools/bitcoin_core_regtest.py passed against the authenticated stable binaries and reported /Satoshi:32.1.0/. Both versioned tutorial files exist, and git diff --check passes. Runtime source and tests are unchanged. Refs #164. --- .github/workflows/bitcoin-core-fixtures.yml | 8 ++++---- docs/developer/api.md | 8 ++++---- docs/user/guide.md | 6 +++--- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/.github/workflows/bitcoin-core-fixtures.yml b/.github/workflows/bitcoin-core-fixtures.yml index 565a47b4..9a1eeacb 100644 --- a/.github/workflows/bitcoin-core-fixtures.yml +++ b/.github/workflows/bitcoin-core-fixtures.yml @@ -18,9 +18,9 @@ permissions: contents: read env: - BITCOIN_CORE_ARCHIVE: bitcoin-32.0rc2-x86_64-linux-gnu.tar.gz - BITCOIN_CORE_SHA256: 0255103718033e6aee15fa944717fc277e047b845bff1e7408af0ea732d8d0c1 - BITCOIN_CORE_URL: https://bitcoincore.org/bin/bitcoin-core-32.0/test.rc2 + BITCOIN_CORE_ARCHIVE: bitcoin-32.1-x86_64-linux-gnu.tar.gz + BITCOIN_CORE_SHA256: 61545c17c3120fb7412f896d248b11993af04ec8817aad3649c55b2afb044963 + BITCOIN_CORE_URL: https://bitcoincore.org/bin/bitcoin-core-32.1 jobs: verify: @@ -41,7 +41,7 @@ jobs: env: PYTHONPATH: ${{ github.workspace }}/src run: | - core="$RUNNER_TEMP/bitcoin-32.0rc2/bin" + core="$RUNNER_TEMP/bitcoin-32.1/bin" "$core/bitcoind" --version | head -1 python tools/bitcoin_core_regtest.py \ --bitcoind "$core/bitcoind" \ diff --git a/docs/developer/api.md b/docs/developer/api.md index 51c9fb5c..fbf02116 100644 --- a/docs/developer/api.md +++ b/docs/developer/api.md @@ -653,10 +653,10 @@ xprv through `bitcoin-cli -stdin`, asks Core to create account-0 descriptors, and relocks an encrypted destination after success, failure, or interruption. It never handles a passphrase. -For offline signing/watch-only and multisig workflows, use Bitcoin Core v32's -maintained procedures. Until the final v32 release, see the versioned -[offline-signing tutorial](https://github.com/bitcoin/bitcoin/blob/v32.0rc1/doc/offline-signing-tutorial.md) -and [multisig tutorial](https://github.com/bitcoin/bitcoin/blob/v32.0rc1/doc/multisig-tutorial.md). +For offline signing/watch-only and multisig workflows, use Bitcoin Core v32.1's +maintained, versioned procedures: +[offline-signing tutorial](https://github.com/bitcoin/bitcoin/blob/v32.1/doc/offline-signing-tutorial.md) +and [multisig tutorial](https://github.com/bitcoin/bitcoin/blob/v32.1/doc/multisig-tutorial.md). The direct `ms32 xprv` primitive remains top-level and carries an explicit secret-root warning. diff --git a/docs/user/guide.md b/docs/user/guide.md index b875ab04..e72466a8 100644 --- a/docs/user/guide.md +++ b/docs/user/guide.md @@ -207,7 +207,7 @@ keys enabled and run `ms32 wallet`. Keep that computer disconnected from every network while recovery text or signing keys are present. After the signer is restored, follow Bitcoin Core v32's maintained -[offline-signing tutorial](https://github.com/bitcoin/bitcoin/blob/master/doc/offline-signing-tutorial.md). +[offline-signing tutorial](https://github.com/bitcoin/bitcoin/blob/v32.1/doc/offline-signing-tutorial.md). That workflow owns the watch-only export/import and PSBT transport steps. In Bitcoin Core v32, `exportwatchonlywallet` creates the watch-only wallet file and `restorewallet` loads it on the online node. Do not improvise a codex32-specific @@ -245,7 +245,7 @@ its public wallet data with the separate wallet record. account-0 descriptors, scans history, and relocks an encrypted wallet. 6. If you need an online watch-only counterpart, keep the restored signer offline and follow Bitcoin Core v32's - [offline-signing tutorial](https://github.com/bitcoin/bitcoin/blob/master/doc/offline-signing-tutorial.md) + [offline-signing tutorial](https://github.com/bitcoin/bitcoin/blob/v32.1/doc/offline-signing-tutorial.md) to export and restore the watch-only wallet. Let the online node synchronize, then compare the account, policy, addresses, balance, and transaction history with the wallet record. @@ -264,7 +264,7 @@ results disagree, or the wallet is multisig or nonstandard. Restore the cosigner's private Bitcoin Core wallet with `ms32 wallet`, then follow Bitcoin Core v32's maintained -[multisig tutorial](https://github.com/bitcoin/bitcoin/blob/v32.0rc1/doc/multisig-tutorial.md). +[multisig tutorial](https://github.com/bitcoin/bitcoin/blob/v32.1/doc/multisig-tutorial.md). ### Card maintenance and damaged writing From 00c824f955b1a77ca000a94a33545a56c3e0d6b8 Mon Sep 17 00:00:00 2001 From: Ben Westgate Date: Mon, 9 Nov 2026 12:42:12 -0600 Subject: [PATCH 2/3] docs: Follow upstream Core tutorials Address peer feedback on #164 by using the maintained upstream master tutorials for offline signing and multisig. Keep the Bitcoin Core v32.1 executable archive and checksum pinned. The upstream documentation links were verified. No runtime code or Core fixture checks changed. --- docs/developer/api.md | 8 ++++---- docs/user/guide.md | 10 +++++----- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/developer/api.md b/docs/developer/api.md index fbf02116..702c5f1f 100644 --- a/docs/developer/api.md +++ b/docs/developer/api.md @@ -653,10 +653,10 @@ xprv through `bitcoin-cli -stdin`, asks Core to create account-0 descriptors, and relocks an encrypted destination after success, failure, or interruption. It never handles a passphrase. -For offline signing/watch-only and multisig workflows, use Bitcoin Core v32.1's -maintained, versioned procedures: -[offline-signing tutorial](https://github.com/bitcoin/bitcoin/blob/v32.1/doc/offline-signing-tutorial.md) -and [multisig tutorial](https://github.com/bitcoin/bitcoin/blob/v32.1/doc/multisig-tutorial.md). +For offline signing/watch-only and multisig workflows, follow Bitcoin Core's +maintained procedures: +[offline-signing tutorial](https://github.com/bitcoin/bitcoin/blob/master/doc/offline-signing-tutorial.md) +and [multisig tutorial](https://github.com/bitcoin/bitcoin/blob/master/doc/multisig-tutorial.md). The direct `ms32 xprv` primitive remains top-level and carries an explicit secret-root warning. diff --git a/docs/user/guide.md b/docs/user/guide.md index e72466a8..c5d49b90 100644 --- a/docs/user/guide.md +++ b/docs/user/guide.md @@ -206,8 +206,8 @@ On the offline signer, create an empty encrypted descriptor wallet with private keys enabled and run `ms32 wallet`. Keep that computer disconnected from every network while recovery text or signing keys are present. -After the signer is restored, follow Bitcoin Core v32's maintained -[offline-signing tutorial](https://github.com/bitcoin/bitcoin/blob/v32.1/doc/offline-signing-tutorial.md). +After the signer is restored, follow Bitcoin Core's maintained +[offline-signing tutorial](https://github.com/bitcoin/bitcoin/blob/master/doc/offline-signing-tutorial.md). That workflow owns the watch-only export/import and PSBT transport steps. In Bitcoin Core v32, `exportwatchonlywallet` creates the watch-only wallet file and `restorewallet` loads it on the online node. Do not improvise a codex32-specific @@ -245,7 +245,7 @@ its public wallet data with the separate wallet record. account-0 descriptors, scans history, and relocks an encrypted wallet. 6. If you need an online watch-only counterpart, keep the restored signer offline and follow Bitcoin Core v32's - [offline-signing tutorial](https://github.com/bitcoin/bitcoin/blob/v32.1/doc/offline-signing-tutorial.md) + [offline-signing tutorial](https://github.com/bitcoin/bitcoin/blob/master/doc/offline-signing-tutorial.md) to export and restore the watch-only wallet. Let the online node synchronize, then compare the account, policy, addresses, balance, and transaction history with the wallet record. @@ -263,8 +263,8 @@ results disagree, or the wallet is multisig or nonstandard. ### Multisig cosigner recovery Restore the cosigner's private Bitcoin Core wallet with `ms32 wallet`, then -follow Bitcoin Core v32's maintained -[multisig tutorial](https://github.com/bitcoin/bitcoin/blob/v32.1/doc/multisig-tutorial.md). +follow Bitcoin Core's maintained +[multisig tutorial](https://github.com/bitcoin/bitcoin/blob/master/doc/multisig-tutorial.md). ### Card maintenance and damaged writing From 7883b5c2d68ea99520a22686900f0d748cce6029 Mon Sep 17 00:00:00 2001 From: Ben Westgate Date: Mon, 9 Nov 2026 22:31:41 -0600 Subject: [PATCH 3/3] docs: Prefer maintained upstream tutorial links Document the reviewer preference established in #164: link upstream tutorials on master, while pinning release-specific references, binaries, checksums, and reproducible fixtures. Documentation-only guidance. Checked target-branch policy, exact insertion and diff; no runtime behavior changes. --- CONTRIBUTING.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a0ab1f96..75b5a40d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -100,6 +100,18 @@ any users mentioned in the description will be annoyingly notified each time a fork copies the merge. Instead, make any username mentions in a subsequent comment to the PR. +### Links to Upstream Documentation + +Link to maintained upstream tutorials and user guides on their `master` branch +rather than pinning them to a release tag. For example, link Bitcoin Core's +offline-signing and multisig tutorials on `master` so readers see updated +instructions. Check that the guidance still applies to supported software. + +Use a tag or commit link when documenting version-specific behavior or +preserving historical/auditable evidence. Keep executable downloads, checksums, +dependencies, and test fixtures pinned and independently verified; live +links to documentation must not weaken those reproducibility requirements. + ### Work in Progress Changes and Requests for Comments If a pull request is not to be considered for merging (yet), please