Waterfall contract

Updated 7 months ago

Waterfall acts as a debt instrument by letting you specify the order in which funds are distributed. It's useful when you want to pay one recipient a specific amount before paying another recipient — for example, to recoup costs incurred by one party before splitting further revenue.

In the example below, alice.eth receives all incoming funds until the sum reaches 1 ETH, then further payments are sent to the other recipient address.

Important: Waterfall is an immutable contract — once it's been created, it cannot be changed. Funds flow unidirectionally and tranches do not reset, meaning the only way to "restart" the sequence is to create a new Waterfall.

Remember

Keep these in mind whenever interacting with any smart contracts:

  1. Interacting with contracts require onchain transactions, and onchain transactions are irreversible.
  2. Contracts are entirely your property; we hold no control or special privileges over them.
  3. Each contract operates exclusively on the network on which it has been deployed — make sure you're on the right network.

Creating a Waterfall

To create a new contract, first click “New contract” from the navigation. Then select the network on which you want to deploy the contract, and choose “Waterfall” from the list of contracts. You will now see that you’re creating a new Waterfall on the network of your choice.

Token to waterfall

Use the dropdown menu to choose the token you want to “flow” through the waterfall. (To use an option that isn't on the list, you'll need to find the token's contract address and paste it in using the "Enter address" option. Make sure the token contract is deployed on same network you’re deploying on.) All other types of tokens will go to the Residual tranche.

Tranches

Tranche 1 will be sent to the specified address(es) before any further funds are distributed. The allotted amount is the total sum of your chosen currency that will be sent to the recipients of this tranche.

Add the addresses of one or more recipients, and determine the percentages that each will receive. (Learn more about valid recipients and Split settings here.)

You can add multiple tranches that will receive funds (in order) before the remainder goes to the Residual tranche. The Residual tranche is distinguished by being the last tranche to receive funds, as well as the tranche that receives any tokens besides the chosen one.

Name

This is the contract name that will be displayed in the Splits app instead of the contract’s hexadecimal address. This gets stored offchain (therefore you must be signed in to add one), and you can choose to make the name public, available to other Splits users, or keep it private for personal use only.

Using Waterfall

Once you’ve created a Waterfall, you’re ready to use it. Using Waterfall means 1) sending ETH or ERC20 tokens to the Waterfall’s address, and 2) distributing funds through the Waterfall to the tranche recipients. Multi-recipient tranches are Splits — find detailed instructions for managing Splits here.

Sending funds

Sending ETH and ERC20 tokens to your Waterfall is as easy as sending funds to any other account. Just copy the address, which can be found at the top of the contract’s detail page, and send tokens to the address. You can send funds via the app, but most people will use the Waterfall address in other platforms and apps (e.g., Zora, Highlight, OpenSea, Manifold, etc).

Distributing balances

Balance distribution is when funds sitting in Waterfall are allocated to tranche recipients, according to the defined order. If tranche 1 has been fully paid, any further funds will be sent to the next tranche’s recipients. This pattern repeats until funds are sent to the Residual tranche, at which point any future distributions will also go to the Residual tranche.

To distribute a balance, navigate to the Waterfall detail page, select the balances, and hit “Distribute”.

Once the balance has been distributed, there is no way to take it back. Distributing a balance is a one-way process. Regardless of whether the tranche Split has a controller or not, once funds have been distributed they are permanently allocated to the recipients. More can be found in the Distributing balances article.

That said, if a tranche Split has a balance and the controller changes the recipients and/or percentages before distribution, the new recipients/percentages will receive the balance.

Still need help? Reach out in /splits, DM us on Twitter, or join our Discord