Feat/status

[andreivladbrg]

Linked issues

• Closes Implement a Status #80

Changes

• Add an enum and implement a status function
• Add a mermaid diagrams
• Be more consistent in how to update the contract storage

Diagrams

Statuses

Types

Type	Statuses	Description
Active	Streaming Insolvent, StreamingSolvent	The amount owed to the recipient is increasing over time.
Paused	PauseSolvent, PausedInsolvent	The amount owed to the recipient is not increasing over time.

Status	Description
Streaming Solvent	Active stream when there is no debt.
Streaming Insolvent	Active stream when there is debt.
Paused Solvent	Paused stream when there is no debt.
Paused Insolvent	Paused stream when there is debt.

Statuses diagram

The transition between statuses is done by specific functions, which can be seen in the text on the edges or by the
time.

---

---

Function calls

Notes:

1. The "update" comments refer only to the internal state
2. ltu is always updated to block.timestamp
3. Red lines refers to the function that are doing an ERC20 transfer

flowchart LR
    subgraph Statuses
        NULL((NULL)):::grey
        ACV((ACTIVE)):::green
        INACV((INACTIVE)):::yellow
    end


    subgraph Functions
        CR([CREATE])
        ADJRPS([ADJUST_RPS])
        DP([DEPOSIT])
        WTD([WITHDRAW])
        RFD([REFUND])
        RST([RESTART])
        PS([PAUSE])
        VD([VOID])
    end

    BOTH((  )):::black

    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 black fill:#000000,stroke:#333,stroke-width:2px;

    CR -- "update rps\nupdate ltu" --> NULL
    ADJRPS -- "update ra (+rca)\nupdate rps\nupdate ltu" -->  ACV

    DP -- "update bal (+)" --> BOTH

    RFD -- "update bal (-)" --> BOTH

    VD -- "update ra (bal)\nupdate rps (0)" --> BOTH

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

    PS -- "update ra (+rca)\nupdate rps (0)" --> ACV

    BOTH --> ACV & INACV

    RST -- "update rps \nupdate ltu" --> INACV

    linkStyle 2,3,5 stroke:#ff0000,stroke-width:2px

Loading

The words chosen for the statuses are meant to best express their correct status, but they might be debatable. Feel free to suggest better terminology. While reading the code, it's advise to also real the diagrams.md file.

I’ve decided to add the diagrams here until we have a field in our docs because it is easier to maintain them here instead of having them in github discussions or as gists.

[smol-ninja]

@andreivladbrg really great work on the diagrams. On the statuses of the stream, I have left my comments below. I'd love to know your thoughts on it.

[andreivladbrg]

@PaulRBerg @razgraf tagging you to request your opinions on the naming of statuses (also, you can see the diagrams in the PR's OP - or diagrams.md file for all diagrams):

    /// @notice Enum representing the different statuses of a stream.
    /// @dev There are two types of streams:
    /// - ACTIVE: when the amount owed to the recipient is increasing over time.
    /// - INACTIVE: when the amount owed to the recipient is not increasing over time.
    /// @custom:value0 STREAMING_SOLVENT Active stream when there is no debt.
    /// @custom:value1 STREAMING_INSOLVENT Active stream when there is debt.
    /// @custom:value2 PAUSED_SOLVENT Paused stream when there is no debt.
    /// @custom:value3 PAUSED_INSOLVENT Paused stream when there is debt.
    enum Status {
        // ACTIVE:
        STREAMING_SOLVENT,
        STREAMING_INSOLVENT,
        // INACTIVE:
        PAUSED_SOLVENT,
        PAUSED_INSOLVENT
    }

[andreivladbrg]

@smol-ninja since we softly agreed on the statuses names, the PR is ready to be reviewed

[smol-ninja]

@andreivladbrg I loved the diagrams. Fantastic work on it.

Q: Why not replace INACTIVE keyword with PAUSE and ACTIVE with STREAMING?

[smol-ninja]

Yes kind of. I changed it a bit to show you what I was thinking.

stateDiagram-v2
    direction LR

    state Streaming {
        STREAMING_SOLVENT
        STREAMING_INSOLVENT --> STREAMING_SOLVENT : deposit
        STREAMING_SOLVENT --> STREAMING_INSOLVENT : time
    }

    state Paused {
        # direction BT
        PAUSED_SOLVENT
        PAUSED_INSOLVENT
         PAUSED_INSOLVENT --> PAUSED_SOLVENT : deposit || void
    }

    STREAMING_SOLVENT --> PAUSED_SOLVENT : pause
    STREAMING_INSOLVENT --> PAUSED_INSOLVENT : pause
    STREAMING_INSOLVENT --> PAUSED_SOLVENT : void
    PAUSED_SOLVENT --> STREAMING_SOLVENT : restart
    PAUSED_INSOLVENT --> STREAMING_INSOLVENT : restart

    NULL --> STREAMING_SOLVENT : create

    NULL:::grey
    Streaming:::lightGreen
    Paused:::lightYellow
    STREAMING_SOLVENT:::intenseGreen
    STREAMING_INSOLVENT:::intenseGreen
    PAUSED_INSOLVENT:::intenseYellow
    PAUSED_SOLVENT:::intenseYellow

    classDef grey fill:#b0b0b0,stroke:#333,stroke-width:2px,color:#000,font-weight:bold;
    classDef lightGreen fill:#98FB98,color:#000,font-weight:bold;
    classDef intenseGreen fill:#32cd32,stroke:#333,stroke-width:2px,color:#000,font-weight:bold;
    classDef lightYellow fill:#ffff99,color:#000,font-weight:bold;
    classDef intenseYellow fill:#ffd700,color:#000,font-weight:bold;

Loading

And then replace "Active" and "Inactive" with "Streaming" and "Paused" in the Datatypes.sol and other parts in the code.

[smol-ninja]

LGTM except one small change.