SDK

Splits Development Kit

This page explains how to use the Splits Development Kit (SDK). The SDK makes it easier to query the subgraph or call contract functions. You can find the SDK source code on Github.

To get started, install the package using yarn or npm.

yarn add @0xsplits/splits-sdk
npm install @0xsplits/splits-sdk

Then, import SplitsClient into your app.

import { SplitsClient } from '@0xsplits/splits-sdk'

const splitsClient = new SplitsClient({
  chainId,
  provider, // ethers provider (optional, required if using any of the SplitMain functions)
  signer, // ethers signer (optional, required if using the SplitMain write functions)
  includeEnsNames, // boolean, defaults to false. If true, will return ens names for split recipients
})

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, SplitMain Writes, and SplitMain Reads.

Subgraph Reads

These functions make it easier to query the subgraph.

getSplitMetadata

Returns all metadata for a given splitId.

Usage

const args = {
  splitId: '0xF8843981e7846945960f53243cA2Fd42a579f719',
}

const response = await splitsClient.getSplitMetadata(args)

Arguments

{
  splitId: string
}

Response

{
  id: string
  controller: string | null
  newPotentialController: string | null
  distributorFeePercent: number
  recipients: {
    address: string
    percentAllocation: number
    ensName?: string
  }[]
  createdBlock: number
}

getRelatedSplits

Returns all Splits related to a given address.

Usage

const args = {
  address: '0xEc8Bfc8637247cEe680444BA1E25fA5e151Ba342',
}

const response = await splitsClient.getRelatedSplits(args)

Arguments

{
  address: string
}

Response

{
  receivingFrom: { # Splits in which the address is a Recipient
    id: string
    controller: string | null
    newPotentialController: string | null
    distributorFeePercent: number
    recipients: {
      address: string;
      percentAllocation: number
      ensName?: string
    }[]
    createdBlock: number
  }[]
  controlling: { # Splits of which the address is the Controller
    id: string
    controller: string | null
    newPotentialController: string | null
    distributorFeePercent: number
    recipients: {
      address: string;
      percentAllocation: number
      ensName?: string
    }[]
    createdBlock: number
  }[]
  pendingControl: { # Splits of which the address has been given but not yet accepted Control
    id: string
    controller: string | null
    newPotentialController: string | null
    distributorFeePercent: number
    recipients: {
      address: string;
      percentAllocation: number
      ensName?: string
    }[]
    createdBlock: number
  }[]
}

getSplitEarnings

Returns token balances for a given splitId.

NOTE: Fetching active balances requires a getLogs request across many blocks. Not all providers may handle it properly. Alchemy and Infura should work just fine. You can disable fetching active balances by passing in includeActiveBalances: false.

Usage

const args = {
  splitId: '0xF8843981e7846945960f53243cA2Fd42a579f719',
}

const response = await splitsClient.getSplitEarnings(args)

Arguments

{
  splitId: string
  includeActiveBalances?: boolean # defaults to true
}

Response

{
  activeBalances?: { # tokens that are waiting to be distributed
    [token: string]: BigNumber
  }
  distributed: { # tokens that have already been distributed
    [token: string]: BigNumber
  }
}

getUserEarnings

Returns token balances for a given userId.

Usage

const args = {
  userId: '0xEc8Bfc8637247cEe680444BA1E25fA5e151Ba342',
}

const response = await splitsClient.getUserEarnings(args)

Arguments

{
  userId: string
}

Response

{
  withdrawn: { # tokens the user has already withdrawn from the protocol
    [token: string]: BigNumber
  }
  activeBalances: { # tokens that have been distributed but not yet withdrawn
    [token: string]: BigNumber
  }
}

SplitMain Writes

These functions make it easier to call SplitMain functions.

createSplit

Creates a new Split contract.

Usage

const args = {
  recipients: [
    {
      address: "0x442C01498ED8205bFD9aaB6B8cc5C810Ed070C8f";
      percentAllocation: 50.0000
    },
    {
      address: "0xc3313847E2c4A506893999f9d53d07cDa961a675";
      percentAllocation: 50.0000
    }
  ]
  distributorFeePercent: 1.0000
  controller: "0xEc8Bfc8637247cEe680444BA1E25fA5e151Ba342"
}

const response = await splitsClient.createSplit(args)

Arguments

{
  recipients: {
      address: string;
      percentAllocation: number # >0 and <100 and up to 4 decimals
    }[]
  distributorFeePercent: number # <10 and up to 4 decimals
  controller?: string # defaults to AddressZero for an immutable split
}

Response

{
  splitId: string
  event: Event # CreateSplit emitted on SplitMain
}

updateSplit

Updates an existing mutable Split contract. Only callable by the controller of splitId.

Usage

const args = {
  splitId: "0x047ED5b8E8a7eDBd92FAF61f3117cAFE8c529ABb"
  recipients: {
    {
      address: "0x442C01498ED8205bFD9aaB6B8cc5C810Ed070C8f";
      percentAllocation: 50.0000
    },
    {
      address: "0xc3313847E2c4A506893999f9d53d07cDa961a675";
      percentAllocation: 50.0000
    },
  }
  distributorFeePercent: 1.0000
}

const response = await splitsClient.updateSplit(args)

Arguments

{
  splitId: string
  recipients: {
    address: string;
    percentAllocation: number
  }[]
  distributorFeePercent: number
}

Response

{
  event: Event # UpdateSplit emitted on SplitMain
}

distributeToken

Distributes the balance of token for splitId, and sends the distributor fee to distributorAddress.

Usage

const args = {
  splitId: "0xd9137B84f56D61Bb961082DD9Eb21bE3D7B14cB9"
  token: "0x64d91f12ece7362f91a6f8e7940cd55f05060b92"
  distributorAddress: "0x2fa128274cfcf47afd4dc03cd3f2a59af09b6a72"
}

const response = await splitsClient.distributeToken(args)

Arguments

{
  splitId: string
  token: string
  distributorAddress?: string # defaults to signer
}

Response

{
  event: Event # DistributeETH or DistributeERC20 emitted on SplitMain
}

updateSplitAndDistributeToken

This combines updateSplit and distributeToken into one transaction. Only callable by the controller of splitId.

Usage

const args = {
  splitId: "0xd9137B84f56D61Bb961082DD9Eb21bE3D7B14cB9"
  token: "0x64d91f12ece7362f91a6f8e7940cd55f05060b92"
  recipients: {
    {
      address: "0x442C01498ED8205bFD9aaB6B8cc5C810Ed070C8f";
      percentAllocation: 50.0000
    },
    {
      address: "0xc3313847E2c4A506893999f9d53d07cDa961a675";
      percentAllocation: 50.0000
    },
  }
  distributorFeePercent: 1.0000
  distributorAddress: "0x2fa128274cfcf47afd4dc03cd3f2a59af09b6a72"
}

const response = await splitsClient.updateSplitAndDistributeToken(args)

Arguments

{
  splitId: string
  token: string
  recipients: {
    address: string;
    percentAllocation: number
  }[]
  distributorFeePercent: number
  distributorAddress?: string # defaults to signer
}

Response

{
  event: Event # UpdateSplit and DistributeETH or DistributeERC20 emitted on SplitMain
}

withdrawFunds

Withdraws tokens for a given address.

Usage

const args = {
  address: "0x357138F2690B82f29dF32bf2a3d0e6d4CC4D63C1"
  tokens: [
    "0x64d91f12ece7362f91a6f8e7940cd55f05060b92",
    "0x0000000000000000000000000000000000000000"
  ]
}

const response = await splitsClient.withdrawFunds(args)

Arguments

{
  address: string
  tokens: string[]
}

Response

{
  event: Event # Withdrawal emitted on SplitMain
}

initiateControlTransfer

Transfers control of splitId to newController. Only callable by the controller of splitId.

Usage

const args = {
  splitId: "0xd9137B84f56D61Bb961082DD9Eb21bE3D7B14cB9"
  newController: "0x2fa128274cfcf47afd4dc03cd3f2a59af09b6a72"
}

const response = await splitsClient.initiateControlTransfer(args)

Arguments

{
  splitId: string
  newController: string
}

Response

{
  event: Event # InitiateControlTransfer emitted on SplitMain
}

acceptControlTransfer

Accepts control of splitId. Only callable by the new controller of splitId.

Usage

const args = {
  splitId: '0xd9137B84f56D61Bb961082DD9Eb21bE3D7B14cB9',
}

const response = await splitsClient.acceptControlTransfer(args)

Arguments

{
  splitId: string
}

Response

{
  event: Event # ControlTransfer emitted on SplitMain
}

cancelControlTransfer

Cancels the transfer of splitId. Only callable by the controller of splitId.

Usage

const args = {
  splitId: '0xd9137B84f56D61Bb961082DD9Eb21bE3D7B14cB9',
}

const response = await splitsClient.cancelControlTransfer(args)

Arguments

{
  splitId: string
}

Response

{
  event: Event # CancelControlTransfer emitted on SplitMain
}

makeSplitImmutable

Makes splitId immutable. Only callable by the controller of splitId.

Usage

const args = {
  splitId: '0xd9137B84f56D61Bb961082DD9Eb21bE3D7B14cB9',
}

const response = await splitsClient.makeSplitImmutable(args)

Arguments

{
  splitId: string
}

Response

{
  event: Event # ControlTransfer emitted on SplitMain
}

SplitMain Reads

These functions make it easier to query SplitMain.

getSplitBalance

Returns the balance for a given splitId and token. If no token is provided, returns the ETH balance.

Usage

const args = {
  splitId: '0x2ed6c4B5dA6378c7897AC67Ba9e43102Feb694EE',
  token: '0x64d91f12ece7362f91a6f8e7940cd55f05060b92',
}

const response = await splitsClient.getSplitBalance(args)

Arguments

{
  splitId: string
  token?: string # defaults to AddressZero
}

Response

{
  balance: BigNumber
}

predictImmutableSplitAddress

Returns the determinisic address (using CREATE2) at which an immutable Split will be deployed for given recipients and distributorFeePercent.

Usage

const args = {
  recipients: {
    {
      address: "0x442C01498ED8205bFD9aaB6B8cc5C810Ed070C8f";
      percentAllocation: 50.0000
    },
    {
      address: "0xc3313847E2c4A506893999f9d53d07cDa961a675";
      percentAllocation: 50.0000
    },
  }
  distributorFeePercent: 1.0000
}

const response = await splitsClient.predictImmutableSplitAddress(args)

Arguments

{
  recipients: {
    address: string;
    percentAllocation: number
  }[]
  distributorFeePercent: number
}

Response

{
  splitId: string
}

getController

Returns the controller for a given splitId.

Usage

const args = {
  splitId: '0xd9137B84f56D61Bb961082DD9Eb21bE3D7B14cB9',
}

const response = await splitsClient.getController(args)

Arguments

{
  splitId: string
}

Response

{
  controller: string
}

getNewPotentialController

Returns the new potential controller (i.e., the account that needs to accept control) for a given splitId.

Usage

const args = {
  splitId: '0xd9137B84f56D61Bb961082DD9Eb21bE3D7B14cB9',
}

const response = await splitsClient.getNewPotentialController(args)

Arguments

{
  splitId: string
}

Response

{
  newPotentialController: string
}

getHash

Returns the current hash for a given splitId.

Usage

const args = {
  splitId: '0xd9137B84f56D61Bb961082DD9Eb21bE3D7B14cB9',
}

const response = await splitsClient.getHash(args)

Arguments

{
  splitId: string
}

Response

{
  hash: string
}