Add draft road-to-ecosystem doc

[KyrylR]

No description provided.

[schoen]

Thanks @KyrylR! This is a helpful document.

I have three thoughts (at very different levels of abstraction):

(1) In American English "I understand for what I am paying" sounds somewhat formal (even though it would probably be accepted by grammar books and language teachers). The more informal and usual form would be "I understand what I am paying for" (which would be proscribed by some grammar books and language teachers because there is a controversy about prepositions at the ends of clauses). However, changing the word order might mess up some of your structure because the words would no longer be side-by-side as you need them.

(2)

The ecosystem becomes useful only if applications can innovate without waiting for every wallet to hard-code their protocol. But the ecosystem becomes safe only if wallets can reject unknown, ambiguous, or misleading signing requests.

Can we get some more suggestions in the document about how this specific tension might be handled? The document implies that third-party protocols can be supported somehow but doesn't seem to say what paths can help create trust or assurance for those protocols. Is that meant to be wallet-specific rather than an ecosystem-wide standard? So the principle is just that the wallet should find some mechanism for ensuring that protocols are trustworthy enough to present their signing requests to users, even if different wallets use different mechanisms?

(3) Could we potentially post this on the (very) new community forum instead of the docs web site?

https://community.simplicity-lang.org/

I am hoping to jumpstart discussion on the forum (although it is so new as of now that this URL has only been available for the past few minutes and I'm the only registered user).

[schoen]

(I don't think "for what I am paying" will be difficult to understand at all, but some readers might consider it unidiomatic.)

[schoen]

@imaginator suggested that

(1) the docs website is actually a good place for this, but we should also have a forum thread about it
(2) we should probably change the diagrams to Mermaid instead of ASCII art for greater readability

[schoen]

For point (2) above, I made this Mermaid version in collaboration with Gemini. However, the resulting text is really small, possibly too small to be usable to a reader.

flowchart TD
    %% Main vertical flow nodes
    Protocols["<b>Third-party protocols</b><br/>Payments | Saving | Lending | Options | DEX<br/>Insurance | Bridges | Tokenization | Other contracts"]
    TxFlow["<b>Transaction flow</b><br/>1. Web-to-wallet communication<br/>2. Transaction construction<br/>&nbsp;&nbsp;&nbsp;↳ Wallet ABI<br/>&nbsp;&nbsp;&nbsp;↳ wallet-owned coin selection<br/>3. Transaction interpretation<br/>&nbsp;&nbsp;&nbsp;↳ clear signing<br/>4. User approval<br/>5. Signing<br/>6. Broadcast"]

    %% Subgraph forcing Left-to-Right rendering for the sentence
    subgraph Horizontal_Sentence [" "]
        direction LR
        I((I)) -- "I (the user)" --- Wallet["<b>Wallet</b>"]
        Wallet --- Core["<b>[ I understand for what I am paying ]</b>"]
        Core -- "understand" --- Explanation["<b>Explanation</b>"]
    end

    %% Vertical cross-axis connections
    Protocols -- "for what" --- Core
    Core -- "am paying" --- TxFlow

    %% Attach the collapsed sub-trees below the horizontal nodes
    W_Features["<b>Wallet Functions</b><br/>• Displays balances<br/>• Sends / receives funds<br/>• Syncs with blockchain<br/>• Keeps funds secure<br/>• Decides if safe to sign"]
    W_Priv["<b>Owns private state</b><br/>• UTXOs<br/>• balances<br/>• blinding keys<br/>• signing keys"]
    
    Wallet --> W_Features
    Wallet --> W_Priv

    E_Clear["<b>Clear signing</b><br/>• Parses transaction<br/>• Interprets inputs / outputs<br/>• Validates assets / amounts<br/>• Explains fees<br/>• Explains protocol metadata<br/>• Explains Simplicity covenants<br/>• Rejects what it cannot understand"]
    E_UI["<b>User interface</b><br/>• Shows what will happen<br/>• Shows what user gives<br/>• Shows what user receives<br/>• Shows why transaction is needed"]

    Explanation --> E_Clear
    Explanation --> E_UI

    %% Styling
    classDef highlight fill:#e1f5fe,stroke:#0277bd,stroke-width:3px,color:#000;
    class Core highlight;
    classDef default fill:#f4f4f9,stroke:#555,stroke-width:1px;
    
    %% Hide the subgraph border so it appears completely seamless
    style Horizontal_Sentence fill:none,stroke:none,color:none;

Loading

[imaginator]

This is good - let's get it live and then continue to iterate.

[schoen]

I merged @KyrylR's commit and then did some work to add the Mermaid diagram and link this document into the "roadmap" part of the menu structure.

@KyrylR Thanks for the document! You're welcome to close this PR now or keep it open to keep discussing revisions or edits (including possible ways to make the tree diagram look better, maybe replacing it with a static SVG file).