Waterfall

Send the first $100 to bob.eth, then the next $50 to mary.eth, and then all residual to yoursplit.eth

The Waterfall module makes it easy to set the order in which funds are distributed to different recipients. It's useful when you want to pay one party a certain amount before paying another party. Waterfalls are payable smart contracts that compose well with Splits and other contracts. This is an old concept that has many different names—preference stack, seniority structure, distribution waterfall, recoupment—and the Waterfall module brings this logic onchain.

How It Works#

• Each Waterfall is a payable smart contract to which a Permitted Token may be sent. This token can be ETH or any ERC20 token. Non-permitted tokens sent to the Waterfall can be recovered to any of the Recipients.
• Each Waterfall has 2 or more Tranches. Each Tranche has a Threshold (a number) and a Recipient (an address). The last Tranche has no Threshold (i.e., upper limit) and will receive all residual funds.
• Tokens sent to the Waterfall are held as a balance until it's distributed. During a distribution, each Tranche sends funds to the Recipient only once the preceding Tranche Threshold has been reached. This repeats until the all Tranches have been filled, at which point all residual funds are sent to the residual Tranche Recipient.

        EXTERNAL ACCOUNT/SMART CONTRACT
                       │
                       │ ETH or ERC20 (permitted token)
                       ▼
Waterfall Contract────────────────────────────┐
│                      │                      │
│       ┌──────────────┘                      │
│       ▼                                     │
│  ┌────────┐                                 │
│  │ 0 to X │───then───┐                      │
│  └────────┘          ▼                      │
│       │         ┌────────┐                  │
│       │         │ X to Y │───then───┐       │
│       │         └────────┘          ▼       │
│       │              │         ┌────────┐   │
│       │              │         │ Y to ∞ │   │
│       │              │         └────────┘   │
│       │              │              │       │
└───────┼──────────────┼──────────────┼───────┘
        │              │              │
        ▼              ▼              ▼
     EOA/SC         EOA/SC         EOA/SC

Addresses#

Mainnet Deployments#

Testnet Deployments#

How To Use#

• Create a new Waterfall by selecting which ERC20 token should be permitted. Then, for each Tranche add a Threshold and Recipient. You may add as many Tranches as you wish. Double check everything is right (these are immutable!) and hit Create Waterfall.
• Once the transaction has been confirmed, you'll be redirected to the Waterfall's account page. If this doesn't happen, you can locate it by searching for one of the Recipients and looking at their "Receiving" section.
• Tokens sent to the Waterfall are held as a balance until they're distributed. You can see the Waterfall's balance and distributions in the Earnings section. Hitting "Distribute Funds" will send each Recipient their funds.
• If the Waterfall has received non-permitted tokens, they will show up below the Address section. You can recover these tokens to any of the Recipients using Etherscan.
• Once all Tranche Thresholds have been filled, all remaining funds will be sent to the Recipient of the last Tranche (i.e., the residual).

Notes#

• Any non-permitted tokens sent to the Waterfall may be recovered to any of the Recipients. If there are any, you'll find all non-permitted token balances below the address section in the top right of the Waterfall page. The account you're recovering funds to must be one of the Tranche Recipients.
• The Waterfall is an immutable contract. Once it's been created, it cannot be changed. However, you can create a Waterfall that distributes to an existing Waterfall.
• Funds flow unidirectionally and Tranches do not reset, meaning the only way to "restart" the sequence is to create a new Waterfall.

Code & Natspec#

Github