Add utility to query distributable balance from SplitV2Client

[kckplural]

Referencing the suggestion in #70 (comment)

I attempted to build this function myself, but I am seeing weird behavior where I always get an extra "BigInt(2)" showing up in the rawAmount field. This is on base sepolia fwiw

When I transfer 5000 of an ERC20 to my contract on a testnet, and then query getSplitActiveBalances, it shows me an extra 2n (5002n). I trigger a distribute which distributes 5000 to the two addresses and then another call to getSplitActiveBalances returns no rawAmount

Maybe I am just being stupid? But that dust rounding is causing rippling effects of incorrect math in my accounting

interface DistributableBalanceQuery {
  splitAddress: Address;
  tokenAddresses: Address[];
  chainId: number;
}

async getDistributableBalance({
  splitAddress,
  tokenAddresses,
  chainId,
}: DistributableBalanceQuery) {
  const { split } = await this.splitsClient.getSplitMetadataViaProvider({
    splitAddress,
    chainId,
  });
  const { activeBalances } = await this.splitsClient.getSplitActiveBalances({
    splitAddress,
    chainId,
    erc20TokenList: tokenAddresses,
  });
  console.log("getDistributableBalance", { activeBalances, split });
  const distributable = [];
  for (const [tokenAddress, { rawAmount, decimals }] of Object.entries(
    activeBalances ?? {},
  )) {
    for (const rr of split.recipients) {
      const { recipient, ownership } = rr;
      distributable.push({
        tokenAddress,
        recipient: recipient.address,
        amount: (rawAmount * ownership) / split.totalOwnership,
        decimals,
      });
    }
  }
  return distributable;
}

after transfer of 5000:

plural_local_expressjs     | getDistributableBalance {
plural_local_expressjs     |   activeBalances: {
plural_local_expressjs     |     '0x036CbD53842c5426634e7929541eC2318f3dCF7e': {
plural_local_expressjs     |       rawAmount: 5002n,
plural_local_expressjs     |       formattedAmount: '0.005002',
plural_local_expressjs     |       symbol: 'USDC',
plural_local_expressjs     |       decimals: 6
plural_local_expressjs     |     }
plural_local_expressjs     |   },
plural_local_expressjs     |   split: {
plural_local_expressjs     |     address: '0x26CF1bA659d486d36061281F01a571e12aBE2f51',
plural_local_expressjs     |     totalOwnership: 1000000n,
plural_local_expressjs     |     recipients: [
plural_local_expressjs     |       {
plural_local_expressjs     |         recipient: { address: '0x0A2A01EB8802853cfaA208F8b19F7de55e39b362' },
plural_local_expressjs     |         ownership: 996000n,
plural_local_expressjs     |         percentAllocation: 99.6
plural_local_expressjs     |       },
plural_local_expressjs     |       {
plural_local_expressjs     |         recipient: { address: '0xD3F5d66795A10bFE391C60b7dbcb84d2dDf48c89' },
plural_local_expressjs     |         ownership: 4000n,
plural_local_expressjs     |         percentAllocation: 0.4
plural_local_expressjs     |       }
plural_local_expressjs     |     ],
plural_local_expressjs     |     distributorFeePercent: 0,
plural_local_expressjs     |     distributeDirection: 'push',
plural_local_expressjs     |     type: 'SplitV2',
plural_local_expressjs     |     controller: { address: '0xef22FA887723A493b2A4bCCA1d6e6FB39dD3dCF6' },
plural_local_expressjs     |     distributionsPaused: false,
plural_local_expressjs     |     newPotentialController: { address: '0x0000000000000000000000000000000000000000' },
plural_local_expressjs     |     createdBlock: undefined,
plural_local_expressjs     |     updateBlock: 25399896
plural_local_expressjs     |   }
plural_local_expressjs     | }

After distribute:

plural_local_expressjs     | getDistributableBalance {
plural_local_expressjs     |   activeBalances: {},
plural_local_expressjs     |   split: {
plural_local_expressjs     |     address: '0x26CF1bA659d486d36061281F01a571e12aBE2f51',
plural_local_expressjs     |     totalOwnership: 1000000n,
plural_local_expressjs     |     recipients: [
plural_local_expressjs     |       {
plural_local_expressjs     |         recipient: { address: '0x0A2A01EB8802853cfaA208F8b19F7de55e39b362' },
plural_local_expressjs     |         ownership: 996000n,
plural_local_expressjs     |         percentAllocation: 99.6
plural_local_expressjs     |       },
plural_local_expressjs     |       {
plural_local_expressjs     |         recipient: { address: '0xD3F5d66795A10bFE391C60b7dbcb84d2dDf48c89' },
plural_local_expressjs     |         ownership: 4000n,
plural_local_expressjs     |         percentAllocation: 0.4
plural_local_expressjs     |       }
plural_local_expressjs     |     ],
plural_local_expressjs     |     distributorFeePercent: 0,
plural_local_expressjs     |     distributeDirection: 'push',
plural_local_expressjs     |     type: 'SplitV2',
plural_local_expressjs     |     controller: { address: '0xef22FA887723A493b2A4bCCA1d6e6FB39dD3dCF6' },
plural_local_expressjs     |     distributionsPaused: false,
plural_local_expressjs     |     newPotentialController: { address: '0x0000000000000000000000000000000000000000' },
plural_local_expressjs     |     createdBlock: undefined,
plural_local_expressjs     |     updateBlock: 25399896
plural_local_expressjs     |   }
plural_local_expressjs     | }

[mihoward21]

Yea, I see how this is confusing. There's a few things kind of silently happening that we're not exposing well.

Just to explain what's happening:

• the 5002 coming back initially is correct. That is the full amount of the erc20 in the split.
• when you distribute the split, it is going to leave 1 of the token in the split and not distribute it. That's a gas optimization.
• So it's then attempting to split 5001 among the recipients, and in your case it probably can't do that evenly. It does everything it can do evenly (5000), and leaves the extra 1 in the split.
• At the end of the distribute call, there is 2 of the erc20 left in the split.
• What's definitely confusing here is on future calls to getSplitActiveBalances, we are returning nothing. That is because we're trying to be helpful and not return a balance that can't actually be distributed. But maybe that is just more confusing.

Potential changes:

• My initial thought is to just return any balance in getSplitActiveBalances. That does mean though that you would get back 2 in your next call to it, but you couldn't actually distribute that 2 (because at least 1 has to be left in the Split, and then you can't split the other 1 amongst multiple recipients).
• There is an option in the contract to manually pass in the amount of the token you want to distribute. It will then distribute whatever amount you pass in, and that way you can bypass leaving 1 in the contract if you wish. The downsides there are it becomes less gas efficient for your next distribute call (not a big deal on L2's), and you need to determine that amount yourself. This functionality isn't exposed through the SDK today, but we could add it.

[mihoward21]

The other option to extend the first change there a bit, is to return the distributable balance in getSplitActiveBalances. So instead of it returning 5002, it should just return 5000.

[kckplural]

ahhhh interesting. lmfao...the leaving 1 in the contract as a gas optimization makes sense.

Sounds like the distributable balance from getSplitActiveBalances should just -=1, so 5001 instead of 5002. This will allow the rest of the calculations to work properly. in meantime I will just do the -=1 on my side