Skip to content

Commit

Permalink
Add PRECISION.md file (#267)
Browse files Browse the repository at this point in the history 
* test: daily withdraw for an rps with 100 tokens monthly

* test: add a demonstrative delay tests

docs: add precision.md file

* test: change MAY_1_2024 with OCT_1_2024

test: use the graph examples in the withdraw delay tests
docs: improve precision file
docs: add note in diagrams file
docs: use cdot in readme

* docs: furthur polishes in precision file

test: move at the bottom the monthly withdraw test

* feat: add images dir with plot graphs

* docs: fix delay formula

* docs: point to precision.md file in readme

* docs(precision): correct latex variable name

* capitalize precision file

* docs(precision): correct grammar

docs(precision): use abbreviation for unlock time solidity

* docs(precision): shub feedback

* docs(precision): use "interval" over "time"

* docs: rename file

* docs: improve first part of the precision file

* docs: remove extra dollar signs

* docs(diagrams): update diagrams with voided status   (#274)

* capitalize diagrams file name

* docs(diagrams): update diagrams with voided status

some polishes

* docs: polish

---------

Co-authored-by: smol-ninja <[email protected]>

* docs: update create flow

* docs(precision): polish grammar

Co-authored-by: Iaroslav Mazur <[email protected]>

* test: update block number forked

* docs(precision): furthur polish grammar

* iaro feedback

Co-authored-by: Iaroslav Mazur <[email protected]>

* docs: polish presision-issue file

* docs: fix latex error

* docs: fix latex error

* docs: correct grammar and polishes

* docs: polish docs

* docs: polish docs

* docs: polish docs

* docs: fix latex

* docs: fix latex in footer

* docs: fix latext

* docs: fix math block

* docs: polish

* docs: andrei feedback

* docs: andrei feedback

* docs: andrei feedback

* docs: update plot graphs

test: polish longest delay test

* docs: last polishes

---------

Co-authored-by: smol-ninja <[email protected]>
Co-authored-by: Iaroslav Mazur <[email protected]>
  • Loading branch information
@andreivladbrg @smol-ninja @IaroslavMazur
3 people authored Oct 5, 2024
1 parent 5ffb5d9 commit d7b4d17
Show file tree
Hide file tree
Showing 16 changed files with 520 additions and 107 deletions.
142 changes: 78 additions & 64 deletions diagrams.md → DIAGRAMS.md
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,20 @@
## Statuses
> [!NOTE]
>
> Below sections assume you've gone through the
> [abbreviations table](https://github.com/sablier-labs/flow/?tab=readme-ov-file#abbreviations) and
> [core components](https://github.com/sablier-labs/flow/?tab=readme-ov-file#core-components)
### Types
## Statuses

| Type | Statuses | Description |
| :-------- | :----------------------------------------- | :-------------------- |
| Streaming | `STREAMING_SOLVENT`, `STREAMING_INSOLVENT` | Debt is accruing. |
| Paused | `PAUSED_SOLVENT`, `PAUSED_INSOLVENT` | Debt is not accruing. |
There are two types of streams: `STREAMING`, when debt is actively accruing, and `PAUSED`, when debt is not accruing:

| Status | Description |
| --------------------- | ------------------------------------------------- |
| `STREAMING_SOLVENT` | Streaming stream when there is no uncovered debt. |
| `STREAMING_INSOLVENT` | Streaming stream when there is no uncovered debt. |
| `PAUSED_SOLVENT` | Paused stream when there is no uncovered debt. |
| `PAUSED_INSOLVENT` | Paused stream when there is uncovered debt. |
| Type | Status | Description |
| ----------- | --------------------- | ----------------------------------------------------------------------- |
| `STREAMING` | `STREAMING_SOLVENT` | Streaming stream when there is no uncovered debt. |
| `STREAMING` | `STREAMING_INSOLVENT` | Streaming stream when there is uncovered debt. |
| `PAUSED` | `PAUSED_SOLVENT` | Paused stream when there is no uncovered debt. |
| `PAUSED` | `PAUSED_INSOLVENT` | Paused stream when there is uncovered debt. |
| `PAUSED` | `VOIDED` | Paused stream with forfeited uncovered debt and it cannot be restarted. |

### Statuses diagram

Expand All @@ -33,16 +35,19 @@ stateDiagram-v2
# direction BT
PAUSED_SOLVENT
PAUSED_INSOLVENT
PAUSED_INSOLVENT --> PAUSED_SOLVENT : deposit || void
PAUSED_INSOLVENT --> PAUSED_SOLVENT : deposit
PAUSED_INSOLVENT --> VOIDED : void
VOIDED
}
STREAMING_SOLVENT --> PAUSED_SOLVENT : pause
STREAMING_INSOLVENT --> PAUSED_INSOLVENT : pause
STREAMING_INSOLVENT --> PAUSED_SOLVENT : void
PAUSED_SOLVENT --> STREAMING_SOLVENT : restart
STREAMING_INSOLVENT --> VOIDED : void
PAUSED_INSOLVENT --> STREAMING_INSOLVENT : restart
NULL --> STREAMING_SOLVENT : create
NULL --> STREAMING_SOLVENT : create (rps > 0)
NULL --> PAUSED_SOLVENT : create (rps = 0)
NULL:::grey
Streaming:::lightGreen
Expand All @@ -51,6 +56,7 @@ stateDiagram-v2
STREAMING_INSOLVENT:::intenseGreen
PAUSED_INSOLVENT:::intenseYellow
PAUSED_SOLVENT:::intenseYellow
VOIDED:::intenseYellow
classDef grey fill:#b0b0b0,stroke:#333,stroke-width:2px,color:#000,font-weight:bold;
classDef lightGreen fill:#98FB98,color:#000,font-weight:bold;
Expand All @@ -63,56 +69,60 @@ stateDiagram-v2

**Notes:**

1. The arrows point to the status on which the function can be called
2. The "update" comments refer only to the internal state
3. `st` is always updated to `block.timestamp`, except for `withdraw`
4. Red lines refers to the function that are doing an ERC-20 transfer
1. The arrows point to the status on which the function can be called.
2. The "update" comments refer only to the stream internal state.
3. `st` is always updated to `block.timestamp`.
4. Red lines refers to the function that are doing an `ERC-20` transfer

```mermaid
flowchart LR
subgraph Statuses
NULL((NULL)):::grey
STR((STREAMING)):::green
PSED((PAUSED)):::yellow
VOID((VOIDED)):::red
end
subgraph Functions
CR([CREATE])
ADJRPS([ADJUST_RPS])
DP([DEPOSIT])
WTD([WITHDRAW])
RFD([REFUND])
RST([RESTART])
PS([PAUSE])
RST([RESTART])
VD([VOID])
WTD([WITHDRAW])
end
BOTH(( )):::black
classDef grey fill:#b0b0b0,stroke:#333,stroke-width:2px;
classDef black fill:#000000,stroke:#333,stroke-width:2px;
classDef green fill:#32cd32,stroke:#333,stroke-width:2px;
classDef grey fill:#b0b0b0,stroke:#333,stroke-width:2px;
classDef yellow fill:#ffff99,stroke:#333,stroke-width:2px;
classDef black fill:#000000,stroke:#333,stroke-width:2px;
classDef red fill:#ff4e4e,stroke:#333,stroke-width:2px;
CR -- "update rps\nupdate st" --> NULL
ADJRPS -- "update sd (+od)\nupdate rps\nupdate st" --> STR
CR -- "update rps<br/>update st" --> NULL
ADJRPS -- "update sd (+od)<br/>update rps<br/>update st" --> STR
DP -- "update bal (+)" --> BOTH
RFD -- "update bal (-)" --> BOTH
WTD -- "update sd (-) \nupdate st\nupdate bal (-)" --> BOTH
PS -- "update sd (+od)<br/>update rps (0)<br/>update st" --> STR
VD -- "update sd (bal)\nupdate rps (0)" --> BOTH
BOTH --> STR & PSED
PS -- "update sd (+od)\nupdate rps (0)" --> STR
RST -- "update rps<br/>update st" --> PSED
BOTH --> STR & PSED
VD -- "update sd (bal)<br/>update rps (0)<br/>update st" --> BOTH
RST -- "update rps \nupdate st" --> PSED
WTD -- "update sd (-)<br/>update st<br/>update bal (-)" --> BOTH
WTD -- "update sd (-)" --> VOID
linkStyle 2,3,4 stroke:#ff0000,stroke-width:2px
linkStyle 2,3,9,10 stroke:#ff0000,stroke-width:2px
```

## Access Control
Expand All @@ -130,6 +140,9 @@ flowchart LR

### Internal State

The [stream struct](https://github.com/sablier-labs/flow/?tab=readme-ov-file#motivation) has more fields than the ones
shown here, but these are the most relevant ones.

```mermaid
flowchart LR
stream[(Stream Internal State)]:::green
Expand All @@ -146,12 +159,14 @@ flowchart LR
classDef green fill:#32cd32,stroke:#333,stroke-width:2px;
```

### ERC-20 Transfer Actions

```mermaid
flowchart LR
erc_transfers[(ERC20 Transfer Actions)]:::red
dep([Deposit - add]):::red
ref([Refund - extract]):::red
wtd([Withdraw - extract]):::red
ref([Refund - remove]):::red
wtd([Withdraw - remove]):::red
erc_transfers --> dep
erc_transfers --> ref
Expand All @@ -160,37 +175,54 @@ flowchart LR
classDef red fill:#ff4e4e,stroke:#333,stroke-width:2px;
```

$~$

## Amount Calculations

### Ongoing Debt

**Notes:** `now` refers to `block.timestamp`.

```mermaid
flowchart TD
rca([Ongoing Debt - od]):::green1
di0{ }:::green0
di1{ }:::green0
res_00([0 ]):::green1
res_01([0 ]):::green1
res_rca(["rps*(now - st)"]):::green1
res_rca(["rps * elt"]):::green1
rca --> di0
di0 -- "streaming" --> di1
di0 -- "paused" --> res_00
di1 -- "now < st" --> res_01
di1 -- "now >= st" --> res_rca
di0 -- "rps > 0" --> di1
di0 -- "rps == 0" --> res_00
di1 -- "now <= st" --> res_01
di1 -- "now > st" --> res_rca
classDef green0 fill:#98FB98,stroke:#333,stroke-width:2px;
classDef green1 fill:#32cd32,stroke:#333,stroke-width:2px;
```

### Covered debt
### Uncovered Debt

**Notes:** Uncovered debt greater than zero means:
**Notes:** A non-zero uncovered debt implies:

1. `sd > bal` when the status is `PAUSED`
2. `sd + od > bal` when the status is `STREAMING`
1. `bal < sd` when the status is `PAUSED`
2. `bal < sd + od` when the status is `STREAMING`

```mermaid
flowchart TD
di0{ }:::red1
sd([Uncovered Debt - ud]):::red0
res_sd(["td- bal"]):::red1
res_zero([0]):::red1
sd --> di0
di0 -- "bal < td" --> res_sd
di0 -- "bal >= td" --> res_zero
classDef red0 fill:#EA6B66,stroke:#333,stroke-width:2px;
classDef red1 fill:#FFCCCC,stroke:#333,stroke-width:2px;
```

### Covered debt

```mermaid
flowchart TD
Expand All @@ -201,7 +233,7 @@ flowchart TD
res_0([0 ]):::blue1
res_bal([bal]):::blue1
res_sd([sd]):::blue1
res_sum([od + sd]):::blue1
res_sum([td]):::blue1
cd --> di0
Expand Down Expand Up @@ -229,21 +261,3 @@ flowchart TD
classDef orange1 fill:#FFCD28,stroke:#333,stroke-width:2px;
```

### Uncovered Debt

```mermaid
flowchart TD
di0{ }:::red1
sd([Uncovered Debt - ud]):::red0
res_sd(["od + sd - bal"]):::red1
res_zero([0]):::red1
sd --> di0
di0 -- "bal < od + sd" --> res_sd
di0 -- "bal >= od + sd" --> res_zero
classDef red0 fill:#EA6B66,stroke:#333,stroke-width:2px;
classDef red1 fill:#FFCCCC,stroke:#333,stroke-width:2px;
```
Loading

0 comments on commit d7b4d17

Please sign in to comment.