Open ended state machine diagram

[smol-ninja]

I hope it helps to visualize the open-ended streams as per the current implementation. if you think there could be some improvements in the diagram, please let me know and I will be happy to make those changes.

Click here to view in Stately Studio

• The rectangular boxes represent the states.
• The elliptical boxes represent the functions that can be called during a particular state.

[andreivladbrg]

Thank you Shub for the diagram, since NFT PR has changed how things work I have created a new version of diagrams (they include cancel --> pause change):

State diagram

---

Calculation diagrams

---

I’ve put effort into these and would appreciate your feedback. Tagging @sablier-labs/solidity @razgraf

Drive links:

• State: https://drive.google.com/file/d/1C9gvhF0OtEsRY6Q68c4Wc4JUUR4TcxS0/view?usp=drive_link
• Amount calculations: https://drive.google.com/file/d/14VU6elpmk2CbpjD1SEAhRt3YFBnmiqjC/view?usp=drive_link

[smol-ninja]

OK I will.

[razgraf]

the new versions with colors help a lot to understand how the protocol works

Completely agree that the colors help a lot with understanding the flow. Unfortunately, the design is very... Windows 95-ish 😅 Stately looks stylish, so maybe we can use the color coding from Andrei's version for a new state diagram? Looks like it should be possible.

[andreivladbrg]

Ok. Will make a new version as I am wokring on the cancel -> pause PR and the diagrams will change.

[razgraf]

Thank you! I've also checked the diagrams, but will wait for the final version to perform a more thorough read. In any case, great job with them both of you!

[PaulRBerg]

Yeah nice work with the diagram - this should definitely also goes in the docs once we get to that stage.

I will review later once it's updated.

[andreivladbrg]

@razgraf @PaulRBerg @smol-ninja just wanted to let you know that I've updated the .drawio diagrams

And I've also created a mermaid version. Please let me know which version you prefer ( I am also working on a Stately version but it's WIP) After we have all three, we can decide.

(Note: sometimes mermaid doesn't work inside details block, please see gist below)

Later edit: After seeing the mermaid diagrams in dark mode, I noticed that the colors are not well chosen. I will edit them tomorrow

Mermaid diagrams

flowchart LR
    stream[(Stream Internal State)]:::green
    bal([Balance - bal]):::green
    rps([RatePerSecond - rps]):::green
    ra([RemainingAmount - ra]):::green
    ltu([Last Time Update - ltu]):::green

    stream --> bal
    stream --> rps
    stream --> ra
    stream --> ltu

    classDef green fill:#32cd32,stroke:#333,stroke-width:2px;

Loading

flowchart LR
    erc_transfers[(ERC20 Transfer Actions)]:::red
    dep([Deposit - add]):::red
    ref([Refund - extract]):::red
    wtd([Withdraw - extract]):::red

    erc_transfers --> dep
    erc_transfers --> ref
    erc_transfers --> wtd

    classDef red fill:#ff4e4e,stroke:#333,stroke-width:2px;

Loading

---

State diagram

Notes:

1. The "update" comments refer only to the internal state
2. ltu is always updated to block.timestamp
3. Blue functions can be called by anyone
4. Purple functions can be called only by the sender

flowchart TD
    %% Functions
    ADJRPS([ADJUST_RPS]):::purple
    CR([CREATE]):::blue
    DP([DEPOSIT]):::blue
    PS([PAUSE]):::purple
    RFD([REFUND]):::purple
    RST([RESTART]):::purple
    WTD([WITHDRAW]):::blue

    %% Statuses
    NULL((NULL)):::grey
    STR((STREAMING)):::green
    PSD((PAUSED)):::yellow

    classDef grey fill:#b0b0b0,stroke:#333,stroke-width:2px;
    classDef green fill:#32cd32,stroke:#333,stroke-width:2px;
    classDef yellow fill:#ffff99,stroke:#333,stroke-width:2px;
    classDef blue fill:#99ccff,stroke:#333,stroke-width:2px;
    classDef purple fill:#D0CEE2,stroke:#333,stroke-width:2px;

    %% ltu is always updated to block.timestamp
    %% the "update" comments refer only to the internal state

    NULL --> CR
    CR -- "update rps\nupdate ltu" --> STR
    ADJRPS -- "update ltu\nupdate ra (+sa)\nupdate rps" -->  STR
    
    DP -- "update bal (+)" --> STR:::red
    DP -- "update bal (+)" --> PSD:::red
    
    RFD -- "update bal (-)" --> STR:::red
    RFD -- "update bal (-)" --> PSD:::red

    WTD -- "update ltu\nupdate bal (-)\nupdate ra (-)" --> STR
    WTD -- "update ltu\nupdate bal (-)\nupdate ra (-)" --> PSD

    STR --> PS
    PS -- "update ra (+sa)\nupdate rps (0)" --> PSD
    PSD --> RST
    RST -- "update ltu\nupdate rps" --> STR

    linkStyle 3,4,5,6,7,8 stroke:#ff0000,stroke-width:2px

Loading

---

Streamed Amount

flowchart TD
sa([Streamed Amount - ra]):::green
res_sa(["rps*(block.timestamp - ltu)"]):::green
sa --> res_sa

classDef green fill:#32cd32,stroke:#333,stroke-width:2px;

Loading

Withdrawable Amount

Notes: Debt greater than zero means:

1. ra > bal
2. ra + sa > bal

flowchart TD
    di0{ }:::blue0
    di1{ }:::blue0
    di2{ }:::blue0
    wa([Withdrawable Amount - wa]):::blue0
    res_0([0 ]):::blue1
    res_bal([bal]):::blue1
    res_ra([ra]):::blue1
    res_sum([sa + ra]):::blue1


    wa --> di0
    di0 -- "bal = 0" --> res_0
    di0 -- "bal > 0" --> di1
    di1 -- "debt > 0" --> res_bal
    di1 -- "debt = 0" --> di2
    di2 -- "isPaused" --> res_ra
    di2 -- "isNotPaused" --> res_sum

    classDef blue0 fill:#DAE8FC,stroke:#333,stroke-width:2px;
    classDef blue1 fill:#1BA1E2,stroke:#333,stroke-width:2px;
    linkStyle 1,2,3,4,5,6 stroke:#1BA1E2,stroke-width:2px

Loading

Refundable Amount

    flowchart TD
    rfa([Refundable Amount - rfa]):::orange0
    res_rfa((bal - wa)):::orange1
    rfa --> res_rfa

    classDef orange0 fill:#FFA500,stroke:#333,stroke-width:2px;
    classDef orange1 fill:#FFCD28,stroke:#333,stroke-width:2px;

Loading

Stream Debt

flowchart TD
    di0{ }:::red1
    sd([Stream Debt - sd]):::red0
    res_sd(("sa + ra - bal")):::red1
    res_zero([0]):::red1

    sd --> di0
    di0 -- "bal < sa + ra" --> res_sd
    di0 -- "bal >= sa + ra" --> res_zero

    classDef red0 fill:#EA6B66,stroke:#333,stroke-width:2px;
    classDef red1 fill:#FFCCCC,stroke:#333,stroke-width:2px;

Loading

Drawio diagrams

State diagram

---

Calculation diagrams

Gist version: https://gist.github.com/andreivladbrg/e5a0cf2120521e1d8ab429c35abcac14

[smol-ninja]

Great work on diagrams @andreivladbrg. Between these two, I prefer Drawio, the straight lines make it more organized and easier to understand.

There are a suggestion on the state diagram:

1. refund should now be connected to both the states.

[andreivladbrg]

you are damn right, i missed this, will edit tomorrow

also, deposit #113 (comment)

[PaulRBerg]

"damn right" 😆

[andreivladbrg]

@smol-ninja since we have DIAGRAMS.md file should we close this?

[smol-ninja]

Yes.