@sablier/flow/README.md

EVM smart contracts of the Sablier Flow token distribution protocol

# Sablier Flow [![GitHub Actions][gha-badge]][gha] [![Coverage][codecov-badge]][codecov] [![Foundry][foundry-badge]][foundry] [![Discord][discord-badge]][discord] [![Twitter][twitter-badge]][twitter]

In-depth documentation is available at [docs.sablier.com](https://docs.sablier.com).

## Background

Sablier Flow is a debt tracking protocol that tracks tokens owed between two parties, enabling open-ended token
streaming. A Flow stream is characterized by its rate per second (rps). The relationship between the amount owed and
time elapsed is linear and defined as:

```math
\text{amount owed} = rps \cdot \text{elapsed time}
```

Sablier Flow can be used in several areas of everyday finance, such as payroll, subscriptions, grant distributions,
insurance premiums, loans interest, token ESOPs etc. If you are looking for vesting and airdrops, please refer to our
[Lockup](../lockup/) protocol.

## Features

1. **Open-ended:** A stream can be created with no specific end time. It runs indefinitely until it is paused or voided.
2. **Top-ups:** No upfront deposit requirements. A stream can be funded with any amount, at any time, by anyone, in full
   or partially.
3. **Pause:** A stream can be paused by the sender and can later be restarted without losing track of previously accrued
   debt.
4. **Void:** A voided stream cannot be restarted anymore. Voiding an insolvent stream forfeits the uncovered debt.
   Either the sender or the recipient can void a stream at any time.
5. **Refund:** Unstreamed amount can be refunded back to the sender at any time.
6. **Withdraw:** A publicly callable function as long as `to` is set to the recipient. A stream's recipient is allowed
   to withdraw funds to any address.

## Install

### Node.js

This is the recommended approach.

Install Flow using your favorite package manager, e.g. with Bun:

```shell
bun add @sablier/flow
```

### Git Submodules

This installation method is not recommended, but it is available for those who prefer it.

Install the monorepo and its dependencies using Forge:

```shell
forge install sablier-labs/evm-monorepo@flow@v3.0.1 OpenZeppelin/openzeppelin-contracts@v5.3.0 PaulRBerg/prb-math@v4.1.0
```

Then, add the following remappings in `remappings.txt`:

```text
@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/
@prb/math/=lib/prb-math/
@sablier/evm-utils/=lib/evm-monorepo/utils/
@sablier/flow/=lib/evm-monorepo/flow/
```

### Branching Tree Technique

You may notice that some test files are accompanied by `.tree` files. This is because we are using Branching Tree
Technique and [Bulloak](https://bulloak.dev/).

## Usage

This is just a glimpse of Sablier Flow. For more guides and examples, see the [documentation](https://docs.sablier.com).

```solidity
import { ISablierFlow } from "@sablier/flow/src/interfaces/ISablierFlow.sol";

contract MyContract {
  ISablierFlow immutable flow;

  function doSomethingWithFlow(uint256 streamId) external {
    uint128 totalDebt = flow.totalDebtOf(streamId);
    // ...
  }
}
```

## Deployments

The list of all deployment addresses can be found [here](https://docs.sablier.com/guides/flow/deployments).

## Security

The codebase has undergone rigorous audits by leading security experts from Cantina, as well as independent auditors.
For a comprehensive list of all audits conducted, please click [here](https://github.com/sablier-labs/audits).

For any security-related concerns, please refer to the [SECURITY](../SECURITY.md) policy. This repository is subject to a
bug bounty program per the terms outlined in the aforementioned policy.

## Contributing

Feel free to dive in! [Open](https://github.com/sablier-labs/evm-monorepo/issues/new) an issue,
[start](https://github.com/sablier-labs/evm-monorepo/discussions/new/choose) a discussion or submit
[a PR](https://github.com/sablier-labs/evm-monorepo/compare). For any concerns or feedback, please join our
[Discord server](https://discord.gg/bSwRCwWRsT).

Refer to [CONTRIBUTING](../CONTRIBUTING.md) guidelines if you wish to create a PR.

## License

See [LICENSE.md](../LICENSE.md).

[codecov]: https://codecov.io/gh/sablier-labs/evm-monorepo
[codecov-badge]: https://codecov.io/gh/sablier-labs/evm-monorepo/branch/main/graph/badge.svg
[discord]: https://discord.gg/bSwRCwWRsT
[discord-badge]: https://img.shields.io/discord/659709894315868191
[foundry]: https://getfoundry.sh
[foundry-badge]: https://img.shields.io/badge/Built%20with-Foundry-FFDB1C.svg
[gha]: https://github.com/sablier-labs/evm-monorepo/actions
[gha-badge]: https://github.com/sablier-labs/evm-monorepo/actions/workflows/ci-flow.yml/badge.svg
[twitter]: https://x.com/Sablier
[twitter-badge]: https://img.shields.io/twitter/follow/Sablier