doc: clarify Taproot tweak semantics in tr() and rawtr() #35791

pull Bortlesboat wants to merge 4 commits into bitcoin:master from Bortlesboat:doc-descriptors-tr-clarify-clean changing 1 files +5 −5
  1. Bortlesboat commented at 10:06 AM on July 24, 2026: contributor

    What

    Clarify that tr() descriptors use their argument as a Taproot internal key and apply the BIP341 tweak, while rawtr() expects an already-tweaked output key.

    The examples for tr(...) and tr(musig(...)) now say explicitly that the resulting output key is tweaked, and the rawtr(KEY) reference now makes clear that no extra tweak is applied by the descriptor itself.

    Why

    The current wording can be read as if tr(KEY) and rawtr(KEY) both take a final output key directly. In the implementation, TRDescriptor::MakeScripts() finalizes a TaprootBuilder with the internal key, while RawTRDescriptor::MakeScripts() wraps the provided x-only key directly as the witness program.

    Making that distinction explicit should help descriptor readers avoid misunderstanding Taproot key derivation, especially in the musig() example where the aggregate key is still an internal key before the BIP341 tweak.

    Validation

    • Compared the doc updates against TRDescriptor::MakeScripts() and RawTRDescriptor::MakeScripts() in src/script/descriptor.cpp
    • Ran git diff --check upstream/master...HEAD
    • No code or test behavior changed (docs-only)
  2. doc: clarify that tr() tweaks the internal key per BIP 341
    The tr(KEY) descriptor documentation says "with the specified key as
    internal key" without mentioning that the output key is the tweaked
    version per BIP 341. This can be confusing especially in contrast
    with rawtr(KEY) which uses the key directly as the output key.
    
    Add an explicit reference to BIP 341 tweaking to make the distinction
    clear.
    
    Addresses #30279
    5378a80c6e
  3. doc: mention BIP341 tweak in tr() examples 3ea29df033
  4. doc: clarify rawtr uses an already tweaked output key 619a5b2c4c
  5. doc: clarify tr(musig(...)) output key tweak step 821c1927da
  6. DrahtBot added the label Docs on Jul 24, 2026
  7. DrahtBot commented at 10:06 AM on July 24, 2026: contributor

    <!--e57a25ab6845829454e8d69fc972939a-->

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

    <!--006a51241073e994b41acfe9ec718e94-->

    Code Coverage & Benchmarks

    For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/35791.

    <!--021abf342d371248e50ceaed478a90ca-->

    Reviews

    See the guideline and AI policy for information on the review process. A summary of reviews will appear here.

    <!--5faf32d7da4f0f540f40219e4f7537a3-->

  8. sedited commented at 3:30 PM on July 24, 2026: contributor

    This pull request and its description was clearly written by AI, which is against the AI policy. Closing this again.

  9. sedited closed this on Jul 24, 2026

  10. Bortlesboat deleted the branch on Jul 27, 2026
Labels

github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin/bitcoin. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2026-07-31 20:50 UTC

This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me