From a29b7a863a0c9cb8b4615315dd7c5b134aec796f Mon Sep 17 00:00:00 2001 From: smol-ninja Date: Mon, 20 Oct 2025 15:31:12 +0200 Subject: [PATCH] refactor: flow status page --- docs/concepts/flow/01-overview.md | 49 +++++-------------------------- docs/concepts/flow/02-statuses.md | 42 +++++++++++++++++--------- 2 files changed, 35 insertions(+), 56 deletions(-) diff --git a/docs/concepts/flow/01-overview.md b/docs/concepts/flow/01-overview.md index f61102fa..e18b41c1 100644 --- a/docs/concepts/flow/01-overview.md +++ b/docs/concepts/flow/01-overview.md @@ -19,13 +19,14 @@ premiums, loans interest, token ESOPs etc. If you are looking for vesting and ai ## Features 1. **Flexible deposit:** A stream can be funded with any amount, at any time, by anyone, in full or in parts. -2. **Flexible duration:** A stream can be created with no specific start or end time. It can run indefinitely. -3. **Pause:** A stream can be paused by the sender and can later be restarted without losing track of previously accrued +2. **Flexible start time:** A stream can be created with a start time in past, present or in future. +3. **Flexible end time:** A stream can be created without specifying any end time so that it can run indefinitely. +4. **Pause:** A stream can be paused by the sender and can later be restarted without losing track of previously accrued debt. -4. **Refund:** Unstreamed amount can be refunded back to the sender at any time. -5. **Void:** Voiding a stream implies it cannot be restarted anymore. Voiding an insolvent stream forfeits the uncovered +5. **Refund:** Unstreamed amount can be refunded back to the sender at any time. +6. **Void:** Voiding a stream implies it cannot be restarted anymore. Voiding an insolvent stream forfeits the uncovered debt. Either party can void a stream at any time. -6. **Withdraw:** it is publicly callable as long as `to` is set to the recipient. However, a stream’s recipient is +7. **Withdraw:** it is publicly callable as long as `to` is set to the recipient. However, a stream’s recipient is allowed to withdraw funds to any address. ## Key Definitions @@ -39,7 +40,7 @@ by the sender. Key traits: -- No end time: the stream has a start date but no fixed stop. +- No end time: the stream has a start time but no fixed end time. - Funds are streamed continuously at a fixed rate per second. - Stream must be topped up periodically to maintain solvency, [debt is otherwise accumulated](/concepts/flow/overview#total-debt). @@ -93,39 +94,3 @@ Therefore, at any point in time, total debt can also be defined as: ```math \text{total debt} = \text{snapshot debt} + \text{ongoing debt} ``` - -## Lifecycle - -1. A Flow stream is created with an `rps`, a `sender` and a `recipient` address. -2. During the lifecycle of the stream, all the functions enclosed inside the rectangle (diagram below) can be called any - number of times. There are some limitations though, such as `restart` can only be called if the stream is `paused`. -3. Any party can call `void` to terminate it. Only withdraw and refund are allowed on a voided stream. - -```mermaid -flowchart TD - subgraph "Stream Lifecycle" - direction TB - NULL - - subgraph ACTIVE - direction TB - adjustRatePerSecond - deposit - pause - refund - restart - void - withdraw - - restart --> pause - pause --> restart - end - - subgraph VOID - withdraw2(withdraw) - refund2(refund) - end - end - - NULL -- create() --> ACTIVE -``` diff --git a/docs/concepts/flow/02-statuses.md b/docs/concepts/flow/02-statuses.md index fd45c744..f40b3f78 100644 --- a/docs/concepts/flow/02-statuses.md +++ b/docs/concepts/flow/02-statuses.md @@ -10,6 +10,7 @@ A Flow stream can have one of five distinct statuses: | Status | Description | | --------------------- | ----------------------------------------------------------------------------------- | +| `PENDING` | Stream created but not started. | | `STREAMING_SOLVENT` | Active stream with total debt not exceeding stream balance. | | `STREAMING_INSOLVENT` | Active stream with total debt exceeding stream balance. | | `PAUSED_SOLVENT` | Paused stream with total debt not exceeding stream balance. | @@ -22,6 +23,7 @@ A stream can have the following characteristics: | Characteristic | Statuses | Description | | :------------- | :---------------------------------------------- | :------------------------------------------------------ | +| Pending | `PENDING` | Start time in future, and non-zero rps. | | Streaming | `STREAMING_SOLVENT`, `STREAMING_INSOLVENT` | Non-zero rps. | | Paused | `PAUSED_SOLVENT`, `PAUSED_INSOLVENT`, `VOIDED` | Zero rps. | | Solvent | `STREAMING_SOLVENT`, `PAUSED_SOLVENT`, `VOIDED` | Total debt not exceeding the stream balance. | @@ -33,9 +35,6 @@ The following diagram illustrates the statuses and the allowed transitions betwe ```mermaid flowchart LR - N(NULL) - V(VOIDED) - subgraph PAUSED direction RL PS(SOLVENT) @@ -51,13 +50,16 @@ flowchart LR SS -- "time" --> SI end + PENDING -- "time" --> STREAMING STREAMING -- pause --> PAUSED - STREAMING -- void --> V + STREAMING -- void --> VOIDED PAUSED -- restart --> STREAMING - PAUSED -- void --> V + PAUSED -- void --> VOIDED + PENDING -- void --> VOIDED - N -- create (rps > 0) --> STREAMING - N -- create (rps = 0) --> PAUSED + NULL -- create (rps > 0, startTime > blockTime) --> PENDING + NULL -- create (rps > 0, startTime <= blockTime) --> STREAMING + NULL -- create (rps = 0, startTime <= blockTime) --> PAUSED ``` ## Functions Statuses Interaction @@ -66,7 +68,19 @@ flowchart LR ```mermaid flowchart LR - CR[CREATE] --> NULL((NULL)) + CR([CREATE]) --> NULL((NULL)) +``` + +### PENDING stream + +```mermaid +flowchart TD + P((PENDING)) + + ADJRPS([ADJUST_RPS]) --> P + DP([DEPOSIT]) --> P + RFD([REFUND]) --> P + VD([VOID]) --> P ``` ### STREAMING stream @@ -75,12 +89,12 @@ flowchart LR flowchart TD STR((STREAMING)) - ADJRPS[ADJUST_RPS] --> STR - DP[DEPOSIT] --> STR - RFD[REFUND] --> STR - PS[PAUSE] --> STR - VD[VOID] --> STR - WTD[WITHDRAW] --> STR + ADJRPS([ADJUST_RPS]) --> STR + DP([DEPOSIT]) --> STR + RFD([REFUND]) --> STR + PS([PAUSE]) --> STR + VD([VOID]) --> STR + WTD([WITHDRAW]) --> STR ``` ### PAUSED stream