Cross-Marketplace Royalty Escrow Tool

WHAT IT DOES

This tool enables NFT marketplaces, dApp operators, and royalty enforcement services to deposit royalties into escrow from marketplace sales and release them to multiple recipients in batch transactions. It connects to your wallet and reads the royalty registry address, token contract address, token ID, sale price, escrow balance, pending royalties, marketplace fee, recipient list, basis points, escrow history, and timestamps. The tool signs and submits transactions to deposit royalties into escrow, release royalties to recipients in batch, update escrow status, record escrow metadata, and emit escrow events. This ensures that royalties are held securely in escrow before being distributed to creators and rights holders.

HOW TO USE

1. Connect your wallet using the wallet bridge (supports MetaMask, WalletConnect, and other EVM-compatible wallets).

2. Select the target network that matches your escrow contract deployment.

3. Enter the escrow contract address and the royalty registry address, then click "load contracts" to initialize the connection.

4. Click "fetch escrow data" to retrieve the current escrow balance and pending royalties amount.

5. Enter the token contract address, token ID, sale price, and marketplace fee (in basis points).

6. Enter recipients and their royalty basis points in the list, or click "lookup from registry" to automatically populate recipients from the on-chain royalty registry.

7. Click "calculate royalties" to compute the total royalty amount based on the sale price minus marketplace fee.

8. Review the escrow contract details, recipients, and royalty amounts before executing.

9. Click "deposit royalties" to sign and submit the transaction that deposits the royalty funds into escrow.

10. Click "release royalties" to batch-release pending royalties to all recipients in a single transaction using the bulk sender contract.

TECHNICAL MECHANISM

The tool uses ethers.js v5.7.2 to interact with escrow contracts and royalty registries. The escrow contract implements depositRoyalties(uint256, uint256, address[], uint256[]) external payable and releaseRoyalties() external functions, along with balance() and pendingRoyalties() views. The deposit function takes a token ID, sale price, recipient addresses, and basis points, and holds the funds in escrow. The release function calculates each recipient's share based on the basis points and sends funds using the BotGentz bulk sender contract for gas-efficient batch distribution. The tool looks up the bulk sender address from the BULKSEND registry by chain ID and reads the fee live from the sender contract. The fee is shown to the user before any transaction is signed. The tool also supports royalty registry integration via royaltyInfo(uint256, uint256) view to automatically populate recipients.

WHAT IT CANNOT SEE

This tool operates purely on-chain and cannot verify off-chain royalty agreements — it does not check that recipients actually hold rights to the royalties they are claiming. It cannot validate recipient entitlement — the tool cannot confirm that recipients created the works, hold copyrights, or are otherwise entitled to the royalty streams. It cannot detect disputes — if multiple parties claim the same rights or there are unresolved royalty conflicts, the tool cannot identify or resolve them. It cannot ensure fair distribution — the tool does not verify that the basis points are appropriate or that the splits are equitable. The tool also cannot verify that recipients actually hold the rights they claim to have — all registry and recipient data is accepted as configured. Users are responsible for ensuring that the royalty configuration is accurate and legally enforceable.

PLEASE NOTE

This tool works exclusively with EVM-compatible blockchain networks (Ethereum, Polygon, Arbitrum, Optimism, Base, etc.). It requires the escrow contract to implement the interface described above. All transactions incur gas fees plus the bulk sender contract fee, paid by the connected wallet. The tool maintains no persistent storage — all state is refreshed from the blockchain on each session. For production use, ensure your escrow contract and royalty registry have been professionally audited. Always test with small amounts on a testnet first and verify that royalty distributions are correct before processing large sales.