Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create mermaid diagram for FRAME section #280

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Create mermaid diagram for FRAME section #280

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cad1ac4
adds draft mermaid for runtime vs client
dawnkelly09 Dec 19, 2024
8181727
creates base diagram to demonstrate adding select FRAME pallets to cr…
dawnkelly09 Jan 15, 2025
81874f1
fix: mermaid diagram styles and simplifying it a bit
nhussein11 Jan 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions develop/parachains/intro-polkadot-sdk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,23 @@ Every blockchain platform relies on a decentralized network of computers—calle

FRAME provides the core modular and extensible components that make the Substrate SDK flexible and adaptable to different use cases. FRAME includes Rust-based libraries that simplify the development of application-specific logic. Most of the functionality that FRAME provides takes the form of plug-in modules called [pallets](/polkadot-protocol/glossary#pallet){target=\_blank} that you can add and configure to suit your requirements.

```mermaid
graph LR
subgraph SP["<b style='font-size:18px;'>Runtime</b>"]
direction LR
S1[Timestamp]~~~S2[Aura]~~~S3[GRANDPA]
S4[Balances]~~~S5[Transaction\nPayment]~~~S6[Sudo]
end

subgraph AP["<b style='font-size:18px;'>FRAME Pallets</b>"]
direction LR
A1[Aura]~~~A2[BABE]~~~A3[GRANDPA]~~~A4[Transaction\nPayment]
B1[Identity]~~~B2[Balances]~~~B3[Sudo]~~~B4[EVM]
C1[Timestamp]~~~C2[Assets]~~~C3[Contracts]~~~C4[and more...]
end
AP --> SP
```

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks okay but it is missing the configurable aspect of pallets. Maybe something like:

graph TD
    subgraph "FRAME Pallets"
        B[Balances Pallet]
        S[Staking Pallet]
        G[Governance Pallet]
        T[Treasury Pallet]
        C[Contracts Pallet]
        style B fill:#99ccff,stroke:#333,color:#000
        style S fill:#99ccff,stroke:#333,color:#000
        style G fill:#99ccff,stroke:#333,color:#000
        style T fill:#99ccff,stroke:#333,color:#000
        style C fill:#99ccff,stroke:#333,color:#000
    end

    subgraph "Custom Runtime"
        R[Your Runtime] --> MB[Modified Balances]
        R --> MS[Modified Staking]
        R --> CP[Custom Pallet]
        
        MB -.-> B
        MS -.-> S
        
        style R fill:#ff9966,stroke:#333,stroke-width:2px,color:#000
        style MB fill:#cce6ff,stroke:#333,color:#000
        style MS fill:#cce6ff,stroke:#333,color:#000
        style CP fill:#ffcccc,stroke:#333,color:#000
    end

    subgraph "Configuration"
        MB --> C1["Custom Config:
        - Modified weights
        - Custom parameters
        - Added features"]
        
        MS --> C2["Custom Config:
        - Modified rewards
        - Custom rules
        - Added validations"]
        
        style C1 fill:#f2f2f2,stroke:#333,color:#000
        style C2 fill:#f2f2f2,stroke:#333,color:#000
    end
Loading

Copy link
Collaborator

@nhussein11 nhussein11 Jan 20, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@UtkarshBhardwaj007 I like this! Maybe we can add this diagram as a complement to the one we have now and follow up on that in a new PR. Since this is the introduction to the Polkadot SDK, I think explaining it at a high level is a good idea, especially since the diagrams are easy to understand and digest for those onboarding to Polkadot. This iteration was trying to address this comment: #280 (comment)

Long story short, I'd suggest we use your diagram in another section (maybe on the same page but below) and keep the diagram as simple as possible at first, then get into more technical details as the documentation progresses. WDYT?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure I don't mind. However, the 2 diagrams are not so different. This is the diagram you have in the PR:

graph LR
    subgraph SP["<b style='font-size:18px;'>Runtime</b>"]
        direction LR
        S1[Timestamp]~~~S2[Aura]~~~S3[GRANDPA]
        S4[Balances]~~~S5[Transaction\nPayment]~~~S6[Sudo]
    end
    subgraph AP["<b style='font-size:18px;'>FRAME Pallets</b>"]
        direction LR
        A1[Aura]~~~A2[BABE]~~~A3[GRANDPA]~~~A4[Transaction\nPayment]
        B1[Identity]~~~B2[Balances]~~~B3[Sudo]~~~B4[EVM]
        C1[Timestamp]~~~C2[Assets]~~~C3[Contracts]~~~C4[and more...]
    end
    AP --> SP
Loading

The only additions I am proposing is to somehow indicate that the pallets are customisable. A simple line over the arrow (--->) or a change in colour in your diagram should do the trick.

I'd suggest we use your diagram in another section (maybe on the same page but below)

You don't need to keep my diagram. It is the same thing just a different representation. I'd recommend to chose one and add some text and/or colours to annotate the diagrams.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perfect, we talked with Luca and see that maybe we can do something like this to showcase the customizable aspect:

image

@UtkarshBhardwaj007 WDYT?

The code of the diagram would be like:

graph LR
    subgraph SP["<b style='font-size:18px;'>Runtime</b>"]
        direction LR
        Timestamp ~~~ Aura ~~~ GRANDPA
        Balances ~~~ TransactionPayment ~~~ Sudo
        subgraph Timestamp["Timestamp"]
            SS1[Custom Config]
        end
        subgraph Aura["Aura"]
            SS2[Custom Config]
        end
        subgraph GRANDPA["GRANDPA"]
            SS3[Custom Config]
        end
        subgraph Balances["Balances"]
            SS4[Custom Config]
        end
        subgraph TransactionPayment["Transaction Payment"]
            SS5[Custom Config]
        end
        subgraph Sudo["Sudo"]
            SS6[Custom Config]
        end
        style Timestamp stroke:#FF69B4
        style Aura stroke:#FF69B4
        style GRANDPA stroke:#FF69B4
        style Balances stroke:#FF69B4
        style TransactionPayment stroke:#FF69B4
        style Sudo stroke:#FF69B4
        style SS1 stroke-dasharray: 5
        style SS2 stroke-dasharray: 5
        style SS3 stroke-dasharray: 5
        style SS4 stroke-dasharray: 5
        style SS5 stroke-dasharray: 5
        style SS6 stroke-dasharray: 5

    end
    subgraph AP["<b style='font-size:18px;'>FRAME Pallets</b>"]
        direction LR
        A1[Aura]~~~A2[BABE]~~~A3[GRANDPA]~~~A4[Transaction\nPayment]
        B1[Identity]~~~B2[Balances]~~~B3[Sudo]~~~B4[EVM]
        C1[Timestamp]~~~C2[Assets]~~~C3[Contracts]~~~C4[and more...]
    end
    AP --> SP

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. Although the colours from the code snippet look a bit different from the image you shared (See below).

graph LR
    subgraph SP["<b style='font-size:18px;'>Runtime</b>"]
        direction LR
        Timestamp ~~~ Aura ~~~ GRANDPA
        Balances ~~~ TransactionPayment ~~~ Sudo
        subgraph Timestamp["Timestamp"]
            SS1[Custom Config]
        end
        subgraph Aura["Aura"]
            SS2[Custom Config]
        end
        subgraph GRANDPA["GRANDPA"]
            SS3[Custom Config]
        end
        subgraph Balances["Balances"]
            SS4[Custom Config]
        end
        subgraph TransactionPayment["Transaction Payment"]
            SS5[Custom Config]
        end
        subgraph Sudo["Sudo"]
            SS6[Custom Config]
        end
        style Timestamp stroke:#FF69B4
        style Aura stroke:#FF69B4
        style GRANDPA stroke:#FF69B4
        style Balances stroke:#FF69B4
        style TransactionPayment stroke:#FF69B4
        style Sudo stroke:#FF69B4
        style SS1 stroke-dasharray: 5
        style SS2 stroke-dasharray: 5
        style SS3 stroke-dasharray: 5
        style SS4 stroke-dasharray: 5
        style SS5 stroke-dasharray: 5
        style SS6 stroke-dasharray: 5

    end
    subgraph AP["<b style='font-size:18px;'>FRAME Pallets</b>"]
        direction LR
        A1[Aura]~~~A2[BABE]~~~A3[GRANDPA]~~~A4[Transaction\nPayment]
        B1[Identity]~~~B2[Balances]~~~B3[Sudo]~~~B4[EVM]
        C1[Timestamp]~~~C2[Assets]~~~C3[Contracts]~~~C4[and more...]
    end
    AP --> SP
Loading

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, that's likely because the gh processor doesn't have the same css settings as we do in the polkadot-mkdocs repo. If you copy and paste the diagram into the develop/parachains/intro-polkadot-sdk.md page, you should see all the styles applied.

### Cumulus

Cumulus provides utilities and libraries to turn FRAME-based runtimes into runtimes that can be a parachain on Polkadot. Cumulus runtimes are still FRAME runtimes but contain the necessary functionality that allows that runtime to become a parachain on a relay chain.
Expand Down