feat: docs for Flow protocol

.gitmodules

@@ -6,3 +6,7 @@
   branch = "release"
   path = "repos/lockup/v2-periphery"
   url = "https://github.com/sablier-labs/v2-periphery"
+[submodule "repos/flow"]
+  branch = "main"
+  path = "repos/flow"
+  url = "https://github.com/sablier-labs/flow"

docs/apps/features/02-vesting.mdx

@@ -6,7 +6,7 @@ title: "Vesting"
 
 # Vesting
 
-import NFTSVG from "@site/static/img/nft.svg";
+import LockupNFTSVG from "@site/static/img/lockup-nft.svg";
 
 The Sablier Interface will showcase [Lockup](/concepts/lockup/overview) streams under the Vesting tab. These are token
 streams with a fixed duration, predefined amount and strict distribution curve.
@@ -66,9 +66,9 @@ Each stream in wrapped in an ERC-721 non-fungible token (NFT), making the stream
 
 Thus streams can be transferred, traded, and used as collateral in NFT lending protocols.
 
-|                                     |
-| ----------------------------------- |
-| <NFTSVG height={500} width={500} /> |
+|                                           |
+| ----------------------------------------- |
+| <LockupNFTSVG height={500} width={500} /> |
 
 ### Multi-chain experience
 

docs/concepts/06-nft.mdx

@@ -6,13 +6,35 @@ title: "NFTs"
 
 import Link from "@docusaurus/Link";
 import { links } from "@site/src/constants";
-import NFTGalleryURL from "@site/static/img/nft-gallery.png";
-import NFTSVG from "@site/static/img/nft.svg";
+import FlowNFTSVG from "@site/static/img/flow-nft.svg";
+import LockupNFTGalleryURL from "@site/static/img/lockup-gallery.png";
+import LockupNFTSVG from "@site/static/img/lockup-nft.svg";
 
 Both Lockup and Flow Protocols wrap every stream in an ERC-721 non-fungible token (NFT), making the stream recipient the
 owner of the NFT. The recipient can transfer the NFT to another address, and this also transfers the right to withdraw
 funds from the stream, including any funds already streamed.
 
+## Lockup NFT
+
+Sablier Lockup streams are represented as unique onchain generated hourglass SVGs, which change their color and content
+based on user data. Here's an example for a stream that is 42.35% way through:
+
+<LockupNFTSVG height={500} width={500} />
+
+### Gallery of Multiple Sablier NFT SVGs
+
+<img src={LockupNFTGalleryURL} height={500} width={500} />
+
+If you prefer the granularity of a blockchain explorer, you can also view the stream NFTs on
+[Etherscan](https://etherscan.io/token/0xB10daee1FCF62243aE27776D7a92D39dC8740f95). See the
+[Deployments](/guides/lockup/deployments) page for the full list of addresses.
+
+## Flow NFT
+
+Unlike Lockup streams, the first release of Flow streams are represented by Sablier Logo.
+
+<FlowNFTSVG height={500} width={500} />
+
 ## Integrations
 
 The transferability of the NFT makes Sablier streams tradable and usable as collateral in DeFi. Imagine an NFT lending
@@ -22,7 +44,7 @@ their future income). Or a decentralized exchange that allows users to trade str
 :::note
 
 Not all Sablier streams are transferable. The stream creator can choose to make the stream non-transferable. You can
-find more details on it in the [Lockup guide](/guides/lockup/guides/stream-management/transfer).
+find more details on it in the [Transferability](/concepts/transferability) section.
 
 :::
 
@@ -35,6 +57,13 @@ will try to respond as soon as possible.
 
 ## Marketplaces
 
+:::caution
+
+Be careful when buying NFTs that represent cancelable stream. When these streams are canceled, the unstreamed amount is
+returned to the sender.
+
+:::
+
 Thanks to adhering to the ERC-721 standard, Sablier streams can be traded and viewed on any NFT marketplace. Here are
 some of the marketplaces that support Sablier streams:
 
@@ -44,42 +73,14 @@ some of the marketplaces that support Sablier streams:
 - [SuperRare](https://superrare.com)
 - [LooksRare](https://looksrare.org)
 
-## Lockup NFT
-
-:::caution
-
-Be careful when buying NFTs that represent cancelable stream. When these streams are canceled, the unstreamed amount is
-returned to the sender.
-
-:::
-
-### Caching
+## Caching
 
 The SVG artwork is generated using certain real-time values, such as the current time on the blockchain. However, NFT
 marketplaces cache the NFT metadata, and this may cause the SVGs might not always be up to date.
 
-The Lockup Protocol triggers [ERC-4906](https://eips.ethereum.org/EIPS/eip-4906) events whenever there's an update in a
+Sablier Protocols trigger [ERC-4906](https://eips.ethereum.org/EIPS/eip-4906) events whenever there's an update in a
 stream (for instance, when a withdrawal is made). However, it's worth noting that some streams might remain unchanged
 for an extended period.
 
 To ensure you're viewing the most recent version of the NFT SVG, it's recommended to check the stream directly via the
 [Sablier Interface](https://app.sablier.com).
-
-## Hourglass SVG
-
-Sablier Lockup streams are represented as unique onchain generated hourglass SVGs, which change their color and content
-based on user data. Here's an example for a stream that is 42.35% way through:
-
-<NFTSVG height={500} width={500} />
-
-### Gallery of Multiple Sablier NFT SVGs
-
-<img src={NFTGalleryURL} height={500} width={500} />
-
-If you prefer the granularity of a blockchain explorer, you can also view the stream NFTs on
-[Etherscan](https://etherscan.io/token/0xB10daee1FCF62243aE27776D7a92D39dC8740f95). See the
-[Deployments](/guides/lockup/deployments) page for the full list of addresses.
-
-## Flow NFT
-
-Coming soon.

docs/concepts/08-governance.md

@@ -31,16 +31,21 @@ wallets.
 
 Admin has the following permissions on each chain where Lockup is deployed:
 
-| Permission         | Function           | Contract(s)                                                                  |
-| ------------------ | ------------------ | ---------------------------------------------------------------------------- |
-| Allow to Hook      | `allowToHook`      | `SablierV2LockupLinear`, `SablierV2LockupDynamic`, `SablierV2LockupTranched` |
-| Set NFT Descriptor | `setNFTDescriptor` | `SablierV2LockupLinear`, `SablierV2LockupDynamic`, `SablierV2LockupTranched` |
+| Permission         | Function                                                                                         |
+| ------------------ | ------------------------------------------------------------------------------------------------ |
+| Allow to Hook      | [allowToHook](../reference/lockup/core/abstracts/abstract.SablierV2Lockup#allowtohook)           |
+| Set NFT Descriptor | [setNFTDescriptor](../reference/lockup/core/abstracts/abstract.SablierV2Lockup#setnftdescriptor) |
 
 ## Flow
 
 Admin has the following permissions on each chain where Flow is deployed:
 
-Coming soon.
+| Permission               | Function                                                                                                        |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| Collect Protocol Revenue | [collectProtocolRevenue](../reference/flow/contracts/abstracts/abstract.SablierFlowBase#collectprotocolrevenue) |
+| Recover ERC20 token      | [recover](../reference/flow/contracts/abstracts/abstract.SablierFlowBase#recover)                               |
+| Set NFT Descriptor       | [setNFTDescriptor](../reference/flow/contracts/abstracts/abstract.SablierFlowBase#setnftdescriptor)             |
+| Set Protocol Fee         | [setProtocolFee](../reference/flow/contracts/abstracts/abstract.SablierFlowBase#setprotocolfee)                 |
 
 ## Trustlessness
 

docs/concepts/09-fees.mdx

@@ -7,24 +7,40 @@ title: "Fees"
 import Link from "@docusaurus/Link";
 import { links } from "@site/src/constants";
 
-## Lockup
+There are two types of fees in the Sablier ecosystem: **Protocol Fee** and **Broker Fee**.
 
-### Protocol fees
+## Protocol fee
 
-Lockup protocol is entirely free to use. There is no protocol fee. However, external integrators who manage their own UI
-may charge broker free in exchange for providing their services. Broker fees can only be charged when a stream is
-created, and is capped at 10%.
+This is a fee that can be charged at the protocol level, capped at 10%. Only the protocol admin has the authority to
+change it.
 
-### Broker fees
+### Lockup
 
-In the Sablier ecosystem, a "broker" is any third-party entity that interacts with the Sablier Protocol on behalf of
-other users. These brokers have the ability to charge service fees for facilitating such interactions.
+Currently, Lockup doesn't implement protocol fee that means it remains entirely free to use.
+
+### Flow
+
+While Flow has the ability to implement a protocol fee, no fee is set at the moment. If a protocol fee is introduced in
+the future, users will be notified in advance. When active, the fee will be deducted as a percentage from the withdrawn
+amount.
+
+## Broker fee
+
+A "broker" is any third-party entity that interacts with the Sablier Protocol on behalf of other users. These brokers
+have the ability to charge service fees for facilitating such interactions.
 
 Broker fees are particularly useful for front-end applications that integrate the Sablier Protocol. They enable
-front-end operators to levy a fee on each Sablier stream created through their platform.
+front-end operators to levy a fee on each interaction facilitated through their platform.
+
+### Lockup
 
-The broker fee is a percentage of the streamed amount, and it cannot be higher than 10%. In the event of cancellation,
-broker fee is non-refundable.
+The broker fee can be charged as a percentage of the streamed amount, and it cannot be higher than 10%. In the event of
+cancellation, broker fee is non-refundable.
+
+### Flow
+
+The broker fee can be charged as a percentage of the deposit amount, and it cannot be higher than 10%. In case of
+refund, broker fee is non-refundable.
 
 :::info
 
@@ -39,10 +55,6 @@ soon as possible.
 
 :::
 
-## Flow
-
-Coming soon.
-
 ## Gas Fees
 
 ### Q: What are gas fees?
@@ -60,6 +72,7 @@ A: No. 100% of the gas fee goes to the blockchain validators, which are not affi
 
 :::tip
 
-To find how much each function costs, check out these [gas benchmark reports](/guides/lockup/gas-benchmarks).
+To find how much gas each function costs, check out these [gas benchmark reports](/guides/lockup/gas-benchmarks) for
+Lockup.
 
 :::

docs/concepts/10-security.md

@@ -7,15 +7,17 @@ title: "Security"
 Ensuring the security of the Sablier Protocols is our utmost priority. We have dedicated significant efforts towards the
 design and testing of the protocol to guarantee its safety and reliability.
 
+The Sablier contracts have undergone rigorous audits by leading security experts from [Cantina](https://cantina.xyz/),
+[CodeHawks](https://codehawks.cyfrin.io/), and many independent auditors. For a comprehensive list of all audits
+conducted, check out [the audit repo](https://github.com/sablier-labs/audits/)
+
 ## Lockup Audits
 
-The codebase has undergone rigorous audits by leading security experts from [Cantina](https://cantina.xyz/),
-[CodeHawks](https://codehawks.cyfrin.io/), and many independent auditors. For a comprehensive list of all audits
-conducted, check out [this link](https://github.com/sablier-labs/audits).
+All the audits of Lockup contracts can be found [here](https://github.com/sablier-labs/audits/tree/main/lockup).
 
 ## Flow Audits
 
-Coming soon.
+All the audits of Lockup contracts can be found [here](https://github.com/sablier-labs/audits/tree/main/flow).
 
 ## Bug Bounty
 

docs/concepts/flow/01-overview.md

@@ -27,3 +27,53 @@ premiums, loans interest, token ESOPs etc. If you are looking for vesting and ai
    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
    allowed to withdraw funds to any address.
+
+## Key Definitions
+
+The definitions below will help you understand some terms used in Sablier Flow:
+
+### Stream balance
+
+Stream balance is the token balance of a stream. It increases when funds are deposited into a stream, and decreases when
+the sender refunds from it or when a withdrawal happens.
+
+### Total debt
+
+Total debt is the amount of tokens owed to the recipient. This value is further divided into two sub-categories:
+
+- **Covered debt:** The part of the total debt that covered by the stream balance. This is the same as the
+  **withdrawable amount**, which is an alias.
+- **Uncovered debt:** The part of the total debt that is not covered by the stream balance. This is what the sender owes
+  to the stream.
+
+```math
+\text{total debt} = \text{covered debt} + \text{uncovered debt}
+```
+
+### Snapshot debt and Snapshot time
+
+A snapshot is an event during which snapshot debt and snapshot time of a Flow stream are updated. **Snapshot debt** is
+the debt accumulated since the previous snapshot. The UNIX timestamp at which snapshot debt is updated is called
+**Snapshot time**.
+
+At snapshot, the following calculations are taking place:
+
+```math
+\text{snapshot debt} = \text{previous snapshot debt} + \underbrace{
+rps \cdot (\text{block.timestamp} - \text{snapshot time})}_\text{ongoing debt}
+\text{snapshot time} = \text{block.timestamp}
+```
+
+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 dotted 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.

docs/concepts/flow/02-statuses.md

@@ -0,0 +1,80 @@
+---
+id: "statuses"
+sidebar_position: 2
+title: "Statuses"
+---
+
+# Stream Statuses
+
+A Flow stream can have one of five distinct statuses:
+
+| Status              | Description                                                                         |
+| ------------------- | ----------------------------------------------------------------------------------- |
+| STREAMING_SOLVENT   | Active stream with total debt <ins>not exceeding</ins> stream balance.              |
+| STREAMING_INSOLVENT | Active stream with total debt <ins>exceeding</ins> stream balance.                  |
+| PAUSED_SOLVENT      | Paused stream with total debt <ins>not exceeding</ins> stream balance.              |
+| PAUSED_INSOLVENT    | Paused stream with total debt <ins>exceeding</ins> stream balance.                  |
+| VOIDED              | Paused stream that can no longer be restarted and has forfeited its uncovered debt. |
+
+## Stream characteristics
+
+A stream can have the following characteristics:
+
+| Characteristic | Statuses                                  | Description                                             |
+| :------------- | :---------------------------------------- | :------------------------------------------------------ |
+| Streaming      | STREAMING_SOLVENT, STREAMING_INSOLVENT    | Non-zero rps.                                           |
+| Paused         | PAUSED_SOLVENT, PAUSED_INSOLVENT, VOIDED  | Zero rps.                                               |
+| Solvent        | STREAMING_SOLVENT, PAUSED_SOLVENT, VOIDED | Total debt <ins>not exceeding</ins> the stream balance. |
+| Insolvent      | STREAMING_INSOLVENT, PAUSED_INSOLVENT     | Total debt <ins>exceeding</ins> the stream balance.     |
+
+## Diagram
+
+The following diagram illustrates the statuses and the allowed transitions between them:
+
+```mermaid
+flowchart LR
+  N[NULL]
+  V[VOIDED]
+
+  subgraph Paused
+    direction RL
+    PS[PAUSED_SOLVENT]
+    PI[PAUSED_INSOLVENT]
+    PI -- "deposit" --> PS
+  end
+
+  subgraph Streaming
+    direction LR
+    SS[STREAMING_SOLVENT]
+    SI[STREAMING_INSOLVENT]
+    SI -- "deposit" --> SS
+    SS -- "time" --> SI
+  end
+
+  Streaming -- pause --> Paused
+  Streaming -- void --> V
+  Paused -- restart --> Streaming
+  Paused -- void --> V
+
+  N -- create (rps > 0) --> Streaming
+  N -- create (rps = 0) --> Paused
+```
+
+## Q&A
+
+### Q: What is a null stream?
+
+A: An id that does not reference a created stream. Trying to interact with a null stream will result in a revert.
+
+### Q: What to do with a stream status?
+
+A: Knowing the status of a stream can inform your decision making. For example, if a stream is `STREAMING_INSOLVENT`,
+that means the stream is active but has insufficient balance. As a sender, you should deposit into the stream so that
+your recipient can withdraw the streamed amount without any hiccups. And if you don't want to continue the stream, you
+can pause it.
+
+### Q: Who can make a stream `VOIDED`?
+
+A: Both sender and recipient can void the stream. This is especially useful when either party wants to stop the stream
+immediately. Once a stream is voided, it cannot be restarted. If there is uncovered debt, it will be reset to 0. So to
+ensure that your recipient does not lose on any streamed amount, you can deposit into the stream before voiding it.