contrib: add ASmap attestation scripts #34842

1. 
   jurraca commented at 12:53 pm on March 17, 2026: contributor

   Before embedding an ASmap in Bitcoin Core, contributors should attest to the ASmap they create with a well-known PGP key. This allows us to verify that the ASmap file was the same across contributors, and that the contributor’s submission This process is analogous to the Guix signing process and the scripts here are heavily inspired from guix-attest and guix-verify.

   The attestation repository is currently under the “asmap” organization.

   The asmap-attest script process is:

   • take an ASmap as input
   • encode it with the asmap-tool python script in this directory
   • produce two encoded files: filled and unfilled binary ASmaps
   • create an attestation file with the hash of the input ASmap and the hashes of both encoded files
   • sign that file with the signer’s PGP key
   • write the attestation and signatures files to the attestation repository

   This process writes 4 files in total: both encoded files to the local directory, an attestation file and its signature to the attestation repository (asmap.sigs) (unless the NO_SIGN env var is set) . The input ASmap file is usually around 33MB, the encoded files around 1.5MB (filled) and 1.8MB (unfilled), and the attestation file and signature are sub 1MB.

   The asmap-verify script validates the signatures in the repo. The user must add the signer’s keys to their GPG keyring before verifying attestations.

   No tests are added here. These scripts don’t interface with any runtime functionality in the codebase.

2. add asmap-attest script

   For a given text ASmap file and a signatures repo, encodes the ASmap to
   binary with asmap-tool.py (both filled and unfilled), and creates an
   attestation in the signatures repo.
   Heavily inspired from guix-attest script.

   5b1b451417
3. add asmap-verify script

   Given a signatures repo for ASmap attestations, checks every
   attestation.
   Optional arguments are EPOCH (only check a given epoch sub-directory)
   and SIGNER (use a specific signer as the compare base for matching
   attestations).

   dd5eb34588
4. update README with section about attestation commands c9f8208532
5. DrahtBot added the label Scripts and tools on Mar 17, 2026
6. 
   DrahtBot commented at 12:54 pm on March 17, 2026: contributor

   The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

   Reviews

   See the guideline for information on the review process.

   Type	Reviewers
   Concept ACK	Bortlesboat, sedited

   If your review is incorrectly listed, please copy-paste <!–meta-tag:bot-skip–> into the comment that the bot should ignore.

7. 
   Bortlesboat commented at 4:17 pm on March 17, 2026: none

   Concept ACK c9f82085328a0cf41ee24c64b76c0d9a2f33b922
8. allow passing GPG program to env var in asmap-verify

   mirrors asmap-attest behavior

   ceae59030c
9. in contrib/asmap/asmap-verify:18 in c9f8208532

   13+            exit 1
   14+        fi
   15+    done
   16+}
   17+
   18+check_tools cat diff gpg basename
   

   ---

   ---

   

   Bortlesboat commented at 4:17 pm on March 17, 2026:

   asmap-attest allows overriding the GPG binary via GPG="${GPG:-gpg}". Here gpg is hardcoded in check_tools and again in verify() (lines 82, 88). Should this script also respect a GPG env var for consistency? Users with gpg2 as default would need it in both scripts.

   ---

   

   jurraca commented at 6:29 pm on March 17, 2026:

   fixed in ceae590
10. in contrib/asmap/asmap-verify:91 in c9f8208532 outdated

    86+
    87+builder_keys_dir="$ASMAP_SIGS_REPO/builder-keys"
    88+
    89+##############
    90+##  Verify  ##
    91+##############
    

    ---

    ---

    

    Bortlesboat commented at 4:17 pm on March 17, 2026:

    --report-identical is a GNU diffutils extension, not supported by macOS/BSD diff. Since Core targets macOS, this will fail on stock macOS without GNU coreutils. A portable alternative: cmp -s to check equality, then echo the result.

    ---

    

    jurraca commented at 5:28 pm on March 17, 2026:

    Thanks, good catch. This was taken from guix-verify which has the same issue. Another portability fix would be to just drop the --report-identical flag, as it doesn’t provide much value since any verified attestation is also printed as Verified.

    I’m surprised this hasn’t come up before!

11. 
    sedited commented at 4:17 pm on March 19, 2026: contributor

    Concept ACK
12. 
    fjahr commented at 4:38 pm on March 19, 2026: contributor

    FWIW, I am ~0 here because I kind of liked having the script with the sigs as we started out. But I guess doing the same as guix is more intuitive for most contributors. No strong feelings either way but I guess the scripts in the asmap.sigs repo should be removed when this is merged to avoid them diverging.
13. 
    fanquake commented at 1:21 am on March 23, 2026: member

    The attestation repository is currently under the “asmap” organization.

    Is the plan to move this under /bitcoin-core, or is it staying under /asmap? If it’s moving under bitcoin-core, then maybe they belong here, if not, I think I’d say they should remain in that repo. Do they need to be beholden to Cores review pipeline / other requirements (linting, formatting, minimum supported versions etc)?

Contributors
jurraca DrahtBot Bortlesboat sedited fjahr fanquake

Labels
Scripts and tools