Replace BIP 77 mermaid diagrams with ascii diagrams

DanGould commented at 10:11 am on December 18, 2025: contributor

Updated sequence diagrams to use text format instead of mermaid syntax responding to @achow101’s comment

I cargo cult’d the RFC Rules:

“How are images handled for the plain text version of an RFC?” The RFC Editor will accept both ASCII art and SVG. If only ASCII art is provided, it will be included in all publication formats. If ASCII art and SVG are both provided, ASCII art will be included in the plain text, and SVG in all other outputs. A note indicating alternative artwork is available is strongly advised. If only SVG is provided, a URI will be included in the plain-text publication format pointing to the HTML version. All artwork and figures should have a complete written description to support assisted reader technology.

see: https://www.rfc-editor.org/rse/format-faq/

Since BIPs don’t publish html/pdf renders, ASCII art seems like the right choice to render everywhere. Since normative prose is already provided, I chose not to include a written description of the diagrams to support assisted reader tech.

cc @nothingmuch

Change sequence diagrams to text format

Updated sequence diagrams to use text format instead of mermaid syntax.

I cargo cult'd the RFC Rules:

> “How are images handled for the plain text version of an RFC?”
> The RFC Editor will accept both ASCII art and SVG. If only ASCII art is provided, it will be included in all publication formats. If ASCII art and SVG are both provided, ASCII art will be included in the plain text, and SVG in all other outputs. A note indicating alternative artwork is available is strongly advised. If only SVG is provided, a URI will be included in the plain-text publication format pointing to the HTML version. All artwork and figures should have a complete written description to support assisted reader technology.

see: https://www.rfc-editor.org/rse/format-faq/

Since BIPs don't publish html/pdf renders, ASCII art seems like the right choice to render everywhere. Since normative prose is already provided, I chose not to include a written description of the diagrams to support assisted reader tech.

8d66a06d62

DanGould force-pushed on Dec 18, 2025

ajtowns commented at 11:43 pm on December 18, 2025: contributor

Rather than downgrading to ascii art, maybe include the mermaid source in a bip-0077 directory and generate an svg from it (either using mermaid-cli or copy/pasting into the live editor and exporting?) At the very least, mermaid source is easier to edit than ascii art.

DanGould commented at 5:26 am on December 19, 2025: contributor

This was something we bikeshedded even in the original PR and is not the most consequential. I am revisiting only because of a request. ascii art is about as simple as possible, and these diagrams are ancient at this point and really don’t need to change. LLMs will produce ascii art from mermaid source, which is now in the commit history. I’d like to go ahead with this as-is for simplicity unless there’s a really really good reason to change again.

DanGould commented at 5:30 am on January 9, 2026: contributor

I’m not sure when the unanimous agreement on @ajtowns ’s suggestion came through via “👍” because I don’t get notified by emojis. I would have addressed this earlier if someone reinforced that my prior approach was unacceptable by comment. Should be good to go now.

DanGould force-pushed on Jan 9, 2026

achow101 commented at 5:52 am on January 9, 2026: member

(non blocking comment)

I liked the ascii art better. The svg is not sized correctly and doesn’t have a transparent background for those of us using dark mode.

Also I can’t figure out which settings I had turned on that caused the rendering issue in the first place.

DanGould commented at 6:02 am on January 9, 2026: contributor

sizing is fixable in github with progressive css (is that really what we want here) but transparent background likely won’t work because I’d have to use custom theme to render the svg with diagram lines that look ok on every possible background.

This is major bikeshedding. ASCII “just works” all the time and you can really tell a free LLM “add this line” “remove x part” these days. editing ascii art is a non-issue in 2026.

DanGould commented at 6:07 am on January 9, 2026: contributor

Ok after discussing with Ava I pushed the mermaid stuff here if you really want to look, but I promise it’s a bigger pain in the hiney https://github.com/DanGould/bips/commits/mermaid-bip77/

I guess everyone just checked out for the holidays like myself. I’m re force-pushing ascii art to the pr and would appreciate a simple go-ahead as the original author editing his own bip with identical content in a different format. Thank you for your attention to this matter.

DanGould force-pushed on Jan 9, 2026

ajtowns commented at 10:46 pm on January 10, 2026: contributor

Two “thumbs up” responses doesn’t seem very unanimous to me fwiw. If you’ve considered the comment and rejected it, that’s fine.

katesalazar commented at 3:12 pm on January 13, 2026: contributor

Thanks Dan.

Bi-color elements are highly visible in both light and dark themes: https://github.com/bitcoin/bips/commit/3248581928b5299525b32979c8a569ce9107fdfc

Yeah if the interactions or diagrams are simple enough, there is no reason for adding SVG figures.

murchandamus added the label Proposed BIP modification on Jan 13, 2026

murchandamus commented at 8:50 pm on January 13, 2026: contributor

ACK 8d66a06d62ad5975a0815c5444302936e0929c13

I caught up on the conversation, compared the diagrams to the prior diagrams in BIP 77. It seems that Dan made a decision and this seems ready to go. Merging.

murchandamus merged this on Jan 13, 2026

murchandamus closed this on Jan 13, 2026

Replace BIP 77 mermaid diagrams with ascii diagrams #2064