Waterfall

Begin by importing WaterfallClient into your app. If you are using the SplitsClient, you can access the waterfall client as well.

import { WaterfallClient } from '@0xsplits/splits-sdk'
 
const waterfallClient = new WaterfallClient({
  chainId,
  publicClient, // viem public client (optional, required if using any of the contract functions)
  walletClient, // viem wallet client (optional, required if using any contract write functions. must have an account already attached)
  includeEnsNames, // boolean, defaults to false. If true, will return ens names for any waterfall recipient (only for mainnet)
  // If you want to return ens names on chains other than mainnet, you can pass in a mainnet public client
  // here. Be aware though that the ens name may not necessarily resolve to the proper address on the
  // other chain for non EOAs (e.g. Gnosis Safe's)
  ensPublicClient, // viem public client (optional)
})

import { SplitsClient } from '@0xsplits/splits-sdk'
 
const splitsClient = new SplitsClient({
  chainId,
  publicClient,
  walletClient,
  includeEnsNames,
  ensPublicClient,
})
 
const waterfallClient = splitsClient.waterfall

Now you're ready to use any of the functions. All Arguments and Responses for these functions are objects. This will make it easier for us to release updates to the SDK without breaking existing implementations.

The SDK comprises 3 different types of functions: Subgraph Reads, Waterfall Writes, and Waterfall Reads.

Subgraph Reads

These functions make it easier to query the subgraph.

getWaterfallMetadata

Returns all metadata for a given waterfallModuleAddress.

Usage

const args = {
  waterfallModuleAddress: '0x8904D1fBfc9c88792aaaE8f452ac57E1Ba2130fC',
}
 
const response = await waterfallClient.getWaterfallMetadata(args)

Arguments

{
  waterfallModuleAddress: string
}

Response

{
  type: 'WaterfallModule'
  address: string
  token: {
    address: string
    symbol?: string
    decimals?: number
  }
  nonWaterfallRecipient: {
    address: string
    ensName?: string
  } | null
  tranches: {
    recipient: {
      address: string
      ensName?: string
    }
    startAmount: number
    size?: number
  }[]
}

Waterfall Writes

These functions make it easier to call Waterfall functions.

createWaterfallModule

Creates a new Waterfall contract.

Usage

const args = {
  token: "0x0000000000000000000000000000000000000000"
  tranches: [
    {
      recipient: "0x442C01498ED8205bFD9aaB6B8cc5C810Ed070C8f",
      size: 5.2 # Receives the first 5.2 eth
    },
    {
      recipient: "0xc3313847E2c4A506893999f9d53d07cDa961a675",
      size: 3 # Receives the next 3 eth
    },
    {
      recipient: "0xEc8Bfc8637247cEe680444BA1E25fA5e151Ba342",
    }
  ]
}
 
const response = await waterfallClient.createWaterfallModule(args)

Arguments

{
  token: string
  tranches: {
    recipient: string
    size?: number # the last tranche should have no size set, as it will receive all residual funds
  }[]
  nonWaterfallRecipient?: string # defaults to AddressZero, meaning any tranche recipient can recover non-waterfall tokens
}

Response

{
  waterfallModuleAddress: string
  event: Log # CreateWaterfallModule emitted on WaterfallModuleFactory
}

waterfallFunds

Distributes the current balance for the given waterfall through it's tranches

Usage

const args = {
  waterfallModuleAddress: '0x8904D1fBfc9c88792aaaE8f452ac57E1Ba2130fC',
}
 
const response = await waterfallClient.waterfallFunds(args)

Arguments

{
  waterfallModuleAddress: string
  # If you have attempted to distribute the funds through the tranches, but are
  # hitting an error due to one of the tranche recipients being unable to receive
  # funds, you can call waterfallFunds with usePull set to true. This will set aside
  # the appropriate balance for each tranche recipient within the waterfall module
  # contract. Each recipient can then withdraw their funds using the withdrawPullFunds
  # function below.
  usePull?: boolean # defaults to false
}

Response

{
  event: Log # WaterfallFunds emitted on the Waterfall contract
}

recoverNonWaterfallFunds

Recovers the balance of token for waterfallModuleAddress to the passed in recipient.

Usage

const args = {
  waterfallModuleAddress: "0x8904D1fBfc9c88792aaaE8f452ac57E1Ba2130fC"
  token: "0x64d91f12ece7362f91a6f8e7940cd55f05060b92"
  recipient: "0x2fa128274cfcf47afd4dc03cd3f2a59af09b6a72"
}
 
const response = await waterfallClient.recoverNonWaterfallFunds(args)

Arguments

{
  waterfallModuleAddress: string
  token: string
  # The recipient can be any of the tranche recipients on the waterfall. If a `nonWaterfallRecipient`
  # was set when the waterfall was created, then recipient must be that address
  recipient: string
}

Response

{
  event: Log # RecoverNonWaterfallFunds on the Waterfall contract
}

withdrawPullFunds

Withdraws the funds for the passed in recipient that were set aside after a waterfallFunds call with usePull set to true.

Usage

const args = {
  waterfallModuleAddress: "0x8904D1fBfc9c88792aaaE8f452ac57E1Ba2130fC"
  address: "0x2fa128274cfcf47afd4dc03cd3f2a59af09b6a72"
}
 
const response = await waterfallClient.withdrawPullFunds(args)

Arguments

{
  waterfallModuleAddress: string
  address: string
}

Response

{
  event: Log # Withdrawal emitted on the Waterfall contract
}

Gas Estimation

The client has a gas estimation feature that can be used with any of the above write functions. Just call the function off of the estimateGas property. Estimating the gas for the create waterfall module function would look like:

const args = {
  token: "0x0000000000000000000000000000000000000000"
  tranches: [
    {
      recipient: "0x442C01498ED8205bFD9aaB6B8cc5C810Ed070C8f",
      size: 5.2 # Receives the first 5.2 eth
    },
    {
      recipient: "0xc3313847E2c4A506893999f9d53d07cDa961a675",
      size: 3 # Receives the next 3 eth
    },
    {
      recipient: "0xEc8Bfc8637247cEe680444BA1E25fA5e151Ba342",
    }
  ]
}
 
const gasEstimate = await waterfallClient.estimateGas.createWaterfallModule(args)

CallData

The client has a call data feature that can be used with any of the above write functions. Just call the function off of the callData property. Generating call data for the create waterfall module function would look like:

const args = {
  token: "0x0000000000000000000000000000000000000000"
  tranches: [
    {
      recipient: "0x442C01498ED8205bFD9aaB6B8cc5C810Ed070C8f",
      size: 5.2 # Receives the first 5.2 eth
    },
    {
      recipient: "0xc3313847E2c4A506893999f9d53d07cDa961a675",
      size: 3 # Receives the next 3 eth
    },
    {
      recipient: "0xEc8Bfc8637247cEe680444BA1E25fA5e151Ba342",
    }
  ]
}
 
const callData = await waterfallClient.callData.createWaterfallModule(args)

Waterfall Reads

These functions make it easier to query the Waterfall contracts.

getDistributedFunds

Returns the distributed balance for a given waterfallModuleAddress.

Usage

const args = {
  waterfallModuleAddress: '0x8904D1fBfc9c88792aaaE8f452ac57E1Ba2130fC',
}
 
const response = await waterfallClient.getDistributedFunds(args)

Arguments

{
  waterfallModuleAddress: string
}

Response

{
  distributedFunds: bigint
}

getFundsPendingWithdrawal

Returns the pending balance for pull withdrawal for a given waterfallModuleAddress.

Usage

const args = {
  waterfallModuleAddress: '0x8904D1fBfc9c88792aaaE8f452ac57E1Ba2130fC',
}
 
const response = await waterfallClient.getFundsPendingWithdrawal(args)

Arguments

{
  waterfallModuleAddress: string
}

Response

{
  fundsPendingWithdrawal: bigint
}

getTranches

Returns the recipient list and threshold list for the tranches of a given waterfallModuleAddress.

Usage

const args = {
  waterfallModuleAddress: '0x8904D1fBfc9c88792aaaE8f452ac57E1Ba2130fC',
}
 
const response = await waterfallClient.getTranches(args)

Arguments

{
  waterfallModuleAddress: string
}

Response

{
  recipients: string[]
  thresholds: bigint[]
}

getNonWaterfallRecipient

Returns the non-waterfall recipient for a given waterfallModuleAddress. If none was set, returns the zero address.

Usage

const args = {
  waterfallModuleAddress: '0x8904D1fBfc9c88792aaaE8f452ac57E1Ba2130fC',
}
 
const response = await waterfallClient.getNonWaterfallRecipient(args)

Arguments

{
  waterfallModuleAddress: string
}

Response

{
  nonWaterfallRecipient: string
}

getToken

Returns the token for a given waterfallModuleAddress.

Usage

const args = {
  waterfallModuleAddress: '0x8904D1fBfc9c88792aaaE8f452ac57E1Ba2130fC',
}
 
const response = await waterfallClient.getToken(args)

Arguments

{
  waterfallModuleAddress: string
}

Response

{
  token: string
}

getPullBalance

Returns the balance set aside for withdrawal for a given waterfallModuleAddress and recipient address.

Usage

const args = {
  waterfallModuleAddress: '0x8904D1fBfc9c88792aaaE8f452ac57E1Ba2130fC',
  address: '0x2fa128274cfcf47afd4dc03cd3f2a59af09b6a72',
}
 
const response = await waterfallClient.getPullBalance(args)

Arguments

{
  waterfallModuleAddress: string
  address: string
}

Response

{
  pullBalance: bigint
}

Splits Swapper