NFT Royalty Waterfall Distributor (Multiple Collaborators)

WHAT IT DOES

NFT Royalty Waterfall Distributor is a bulk distribution tool that splits and sends accumulated NFT royalties to multiple collaborators according to a waterfall (sequential) percentage split. It reads the NFT contract address, royalty payment receiver address (royalty split contract), collaborator addresses and split percentages, current royalty balance, distribution history, distribution status (pending/completed), account nonce, gas estimates for distribution, previous distribution records, and payment token address and balance. The tool then distributes royalties to all collaborators in a single batch transaction using the BotGentz bulk sender contract, respecting the specified split percentages and deducting the sender contract fee.

HOW TO USE

Connect your wallet via the built-in connector. Select the network where your NFT contract and royalty split contract are deployed. Enter the NFT contract address and the royalty split contract address. List each collaborator as a line with their address and split percentage separated by a comma (e.g., "0x...,25"). Specify the payment token address—use address(0) for native token (ETH/BNB/MATIC). The tool will read on-chain data and display a preview including: NFT contract, royalty split contract, payment token, current royalty balance, a collaborator list with their split percentages (with a warning if splits don't sum to 100%), distribution status, the bulk sender contract address (from the registry), its owner, the current fee, and estimated gas. Review all details carefully. Click "distribute royalties" to execute the batch distribution in a single transaction.

TECHNICAL MECHANISM

The tool uses ethers.js v5.7.2 to interact with royalty split contracts and the BotGentz bulk sender contract. It reads the current royalty balance using `getBalance()` or `balanceOf()` on the royalty split contract. Collaborator splits are validated to ensure they sum to 100%. The bulk sender contract is looked up from the BULKSEND registry using the current chain ID and the ERC-20 standard (since royalties are typically fungible tokens). The fee is read live from the sender contract via `fee()`, and the owner is read via `owner()`. The tool calculates the total amount to send as the royalty balance minus the sender fee. It then constructs a batch transfer with the collaborator addresses and their respective amounts (balance * split percentage). The sender contract's `distribute()` method is called with the payment token address, recipients array, and amounts array. The tool checks the user's balance against the total required (total to send + fee) and approves the sender contract for the exact total. All transactions are built with EIP-1559 fee data using `feeData` from the provider, and the tool uses `effectiveGasPrice` from receipts for accurate cost accounting.

WHAT IT CANNOT SEE

This tool cannot verify that royalty payments are accurately reported by NFT marketplaces—it only distributes what is on-chain. It cannot detect if royalties are being paid off-chain or through alternative channels. It cannot guarantee that collaborator addresses are correct—you must verify them. It cannot prevent front-running of distribution transactions. It cannot ensure that split percentages sum to 100%—you must validate this manually. It cannot validate that royalty payments are not being withheld by NFT marketplaces. It cannot detect if the royalty split contract has been modified or upgraded. It cannot ensure that distribution is fair if collaborators have off-chain agreements not reflected on-chain. It cannot verify that the split contract has received all royalties owed.

PLEASE NOTE

This tool is EVM-only and supports Ethereum, Polygon, BNB Chain, Arbitrum, Optimism, and Avalanche. The bulk sender contract address is automatically looked up from the registry—no manual entry required. The fee is set by the contract owner and is deducted from the total distribution amount. Ensure you have sufficient native tokens to cover gas and the sender fee. The tool does not store or transmit any collaborator data. Always verify split percentages before distributing—errors may be irreversible.