Share one conceptual description of payjoin across the package READMEs

[chavic]

Each language package README describes what payjoin is in its own words. The descriptions drift apart. A correction to one README does not correct the others. The review of #1764 found two examples: "payment" where the BIP 77 register says "transfer", and "improves privacy" where the correct frame is "preserves privacy by heuristic poisoning".

Proposal: keep the conceptual text in one shared file. The conceptual text contains three parts:

1. What payjoin does, in the BIP 77 register.
2. The privacy frame.
3. Pointers to BIP 78, BIP 77, and payjoindevkit.org.

Each package README then includes this text and keeps only its language-specific content: install steps, platform table, and sample pointers.

From the #1764 review discussion.

Disclosure: co-authored by Claude Code.

[lntutor]

I would like to take this after #1764 lands so the shared section is added to the accepted C# package README instead of conflicting with its active rewrite.

Proposed mechanism: keep the conceptual copy in one canonical Markdown fragment, place generated regions between explicit markers in the Python, Dart, JavaScript, and C# package READMEs, and add a deterministic sync/check script to the existing lint workflow. This keeps the text visible on GitHub and every package registry while making CI reject drift. The copy will follow the BIP 77 register, frame privacy as heuristic poisoning rather than an unquantified improvement, and link BIP 78, BIP 77, and payjoindevkit.org.

AI assistance was used to inspect the package and registry constraints and draft this proposed approach.

[Hamza1610]

Hi @lntutor are you still going to working on this? I will like to work on this if what you are working on is not dependent

[xstoicunicornx]

@chavic I was thinking about this more an was wondering whether it might be better to have the conceptual payjoin text just be linked in each individual language binding's README.md? So conceptual payjoin text would live somewhere that makes sense within the repo and then each README.md would say "visit here for an overview of payjoin" and it would link to the conceptual payjoin text, then each would list its own usage information and so on.

This seems much less complicated and I don't think its too much of a burden on those looking for the conceptual documentation.

[chavic]

@chavic I was thinking about this more an was wondering whether it might be better to have the conceptual payjoin text just be linked in each individual language binding's README.md? So conceptual payjoin text would live somewhere that makes sense within the repo and then each README.md would say "visit here for an overview of payjoin" and it would link to the conceptual payjoin text, then each would list its own usage information and so on.

This seems much less complicated and I don't think its too much of a burden on those looking for the conceptual documentation.

Yeah, that's probably simpler

[chavic]

@lntutor @Hamza1610 Thanks for the interest in this. I guess I'd better define a solid plan for this before handing it off. Also open to suggestions and thoughts like from @xstoicunicornx

[Christopherdominic]

Hey! @chavic @lntutor I'd love to pick this up.

I can extract the shared Payjoin background—using proper BIP 77 terminology ("transfer") and the correct privacy framing ("preserves privacy by heuristic poisoning") along with the specs/site pointers—into a central doc. Then I'll strip the duplicate intro text from each language package README so they only hold install instructions, platform tables, and code snippets.

Let me know if I can go ahead with this!