Should Tokenized Credit Pay Interest by Merkle Claim?
A Merkle distributor interest payment is a pull-based payout: the servicer computes each holder's interest off-chain at a record date, publishes one Merkle root on-chain, and each holder claims its line with a proof. In the Uniswap reference contract the root cannot change after deployment, any caller can trigger a claim for any listed account, and the deadline version lets the owner sweep every unclaimed token.
TL;DR — Key Takeaways
- ✓The pattern: One root per payment date. Each leaf is keccak256 of (index, account, amount); a holder proves its leaf and the contract pays that exact amount once.
- ✓No correction: In the Uniswap reference contract the root is immutable. A wrong line means a new contract, new funding and a reconciliation of what the old root already paid.
- ✓No checks: claim() does not look at msg.sender, an identity registry or a freeze list. Anyone can trigger a claim; the money always goes to the listed account.
- ✓The sweep: After endTime, the deadline version lets the owner withdraw the whole remaining balance. That is where unpaid interest to lost or blocked holders ends up.
- ✓Our view: The contract is the easy part. The amount file, the record date and the post-deadline policy carry the compliance risk, and the servicer owns all three.

How does a Merkle distributor pay one interest period?
It turns the payment into a snapshot plus a claim. The servicer fixes every holder's amount off-chain, deploys a contract holding one 32-byte root, and pays each line only when someone submits that line with a valid proof.
The reference design is the Uniswap merkle-distributor, a 56-line contract whose master branch has not changed since 21 November 2022. It is a widely copied pattern, not an RWA product, and we do not know of any tokenized credit fund that uses it unchanged. Its claim(index, account, amount, merkleProof) function runs four steps:
- Already paid? It reads one bit for the index from a bitmap that packs 256 indices into each storage word, and reverts with
AlreadyClaimedif the bit is set. - Valid line? It hashes
abi.encodePacked(index, account, amount)with keccak256 and checks the proof against the root with OpenZeppelin'sMerkleProof.verify. A mismatch reverts withInvalidProof. - Pay. It sets the bit, then calls
safeTransfer(account, amount)on the payment token. - Log. It emits
Claimed(index, account, amount).
The index is not a wallet or a holder ID. It is a position in the servicer's file. The repository's own root-building script sorts addresses, numbers them from 0, rejects duplicate addresses and zero amounts, and outputs the root, a tokenTotal and a proof per account. That output file, not the contract, is the record of which index belongs to which holder.
“Allows anyone to claim a token if they exist in a merkle root.”
Uniswap merkle-distributor, IMerkleDistributor.sol, interface comment
Push or pull: which suits a tokenized credit coupon?
Push pays every holder in the servicer's own transactions, so cost and failure risk grow with the holder count. A Merkle pull costs the servicer one deployment and one funding transfer, and leaves each unpaid line open until claimed or swept.
The proof a claimant submits grows with the base-2 logarithm of the number of lines: 10 sibling hashes for 1,000 holders, 14 for 10,000. The table below is our comparison of the two designs for a periodic interest payment.
| Question | Push (loop or batch transfers) | Merkle pull (reference contract) |
|---|---|---|
| Who pays gas | The servicer, once per holder | The claimant, or a relayer the servicer funds |
| When the payee list is fixed | When each batch is sent, unless built from a snapshot | When the root is built; later transfers do not change it |
| One blocked recipient | Can revert the whole batch unless each transfer is isolated | Only that claim reverts; other lines are unaffected |
| Unpaid amounts | Stay with the servicer; never leave the paying wallet | Sit in the contract until claimed or swept |
| Correcting a line | Send a top-up or claw back by agreement | Not possible on the same contract |
| Evidence of payment | One transfer per holder | Root, funding transfer, Claimed events, sweep |
Fixing the payee list at a record date is the same problem a fund faces for votes. The checkpoint approach is covered in the guide to preserving a voting record date with ERC-5805 checkpoints; a distributor root is the payments version of that snapshot.
What happens when one line in the amount file is wrong?
In the reference contract, nothing on-chain can fix it. Both merkleRoot and token are declared immutable and set once in the constructor, so a correction needs a second contract, a second funding transfer and a reconciliation against the first.
Take an overpaid line. If the holder has claimed, the excess has left the contract and must be recovered off-chain under the note terms. If the holder has not claimed, the servicer cannot cancel the line; it can only wait for the deadline and sweep. An underpaid line is easier: a top-up distribution with its own root covers the difference. In both cases the servicer must keep a mapping of which lines of which root were paid, because the bitmap of the old contract knows nothing about the new one.
A cumulative design avoids the redeploy. In Pendle's PendleMultiTokenMerkleDistributor, the owner replaces the root each cycle with each user's cumulative accrued total, and a claim pays the total minus what that user has already received. An underpayment is fixed in the next root. An overpayment already claimed still cannot be clawed back by the contract. The trade is control: an updatable root means an owner key that can change every holder's entitlement, which needs the same governance as any other privileged key.
“The contract verifies the proof, then transfers totalAccrued - claimed[token][user] to the receiver and records the new claimed amount. Because accruals are cumulative, claiming multiple times is safe — each call only pays out the delta.”
Pendle V2 developer docs, MerkleDistributor
What does the claim function not check?
It never reads msg.sender, an identity registry or a freeze list. Any address can submit any valid line, and the tokens always go to the account in the leaf. Eligibility is decided once, when the servicer builds the file.
The open caller has a use: the servicer or a relayer can submit claims and pay the gas for holders. The cost is in the evidence. The Claimed event records the index, account and amount, but not who triggered it; the transaction sender is the only trace. A reconciliation that needs to show the holder took action must read transaction senders, not events.
The bigger gap is time. A holder can be eligible at the record date and frozen, sanctioned or off-boarded by claim day. The distributor will still try to pay. Whether the payment lands then depends on the payment token. Circle's FiatToken contract checks both the sender and the recipient against its blacklist on every transfer. If the recipient is listed, the transfer reverts, safeTransfer passes the revert up, the claim reverts, and the bit is never set. The line stays open until the deadline. This is our reading of the two contracts together, not a tested result. The same check runs on the distributor's own address: if the contract itself were blacklisted, no line could be paid. How false returns and silent failures from other tokens behave is covered in the analysis of ERC-20 payment failures that hide behind a successful transaction.
“function transfer(address to, uint256 value) [...] notBlacklisted(msg.sender) notBlacklisted(to)”
circlefin/stablecoin-evm, FiatTokenV1.sol, transfer modifiers
Where does unclaimed interest go after the deadline?
To the owner. In MerkleDistributorWithDeadline, claims revert with ClaimWindowFinished once the block time passes endTime, and withdraw() then sends the contract's entire token balance to the owner in one transfer.
Three details in the deadline contract matter for a servicer. First, endTime is immutable and must be in the future at deployment, so the claim window cannot be extended. Second, claim reverts only when the block time is greater than endTime, while withdraw reverts only when it is less, so at exactly endTime both calls succeed. Third, withdraw sweeps balanceOf(address(this)), not the sum of unclaimed lines. Any excess funding or tokens sent by mistake leave in the same transfer, and the sweep carries no per-holder breakdown.
For a credit note, that sweep is interest the issuer still owes. Who received it, how it is booked as a payable to each holder, and when it is offered again all need a written policy before the first payment date. The unclaimed lines also feed into lost-holder duties: a wallet that never claims may belong to a holder nobody can reach, which is the case set out in the guide to who must find a lost holder of a tokenized security. Escheat treatment of unclaimed interest varies by state and instrument, and we do not state a rule here.
| Block time | claim() | withdraw() by owner |
|---|---|---|
| Before endTime | Allowed | Reverts NoWithdrawDuringClaim |
| Equal to endTime | Allowed | Allowed |
| After endTime | Reverts ClaimWindowFinished | Allowed; sends full balance to owner |
What must the amount file handle that the contract cannot?
Everything credit-specific. The contract pays a fixed number to a fixed address once; accrual for mid-period transfers, withholding, defaulted or payment-in-kind (PIK) periods and frozen holders must all be resolved before the root is built.
The list below is our analysis of what a private credit servicer has to settle in the file. None of it is in the reference code.
- Partial-period accrual. If notes trade between payment dates, the file must apply the note terms: pay the record-date holder in full, or split by days held. The contract cannot tell the difference.
- Withholding. The amount in each leaf is what the wallet receives. Tax withheld per holder must be computed first, and the withheld total must be paid elsewhere.
- Default and PIK periods. When interest is capitalised or paid in new notes, the “amount” is not cash and a cash distributor is the wrong tool for that period. Stress cases are covered in the analysis of what happens when tokenized private credit defaults.
- Frozen and blocked holders. Decide at build time whether a frozen holder gets a line, gets a line paid to a controlled account, or gets none with the amount held off-chain. Leaving it to claim time means the token's blocklist decides.
- Leaf layout. The reference leaf packs 32 + 20 + 32 = 84 bytes before hashing. A custom leaf that packs to exactly 64 bytes can be confused with an internal node, which OpenZeppelin warns against.
“You should avoid using leaf values that are 64 bytes long prior to hashing, or use a hash function other than keccak256 for hashing leaves. This is because the concatenation of a sorted pair of internal nodes in the Merkle tree could be reinterpreted as a leaf value.”
OpenZeppelin Contracts v5.7.0, MerkleProof.sol, NatSpec warning
The reference repository pins OpenZeppelin Contracts 4.7.0, whose MerkleProof library carries the same warning.
What belongs in the audit pack for each distribution?
Six items: the record-date snapshot, the amount file, the root, the funding transfer, every Claimed event with its transaction sender, and the post-deadline sweep with its destination. Together they tie each holder's entitlement to cash out.
- Snapshot. The block number or timestamp of the record date and the eligible-holder register at that point, including frozen addresses and withholding status.
- Amount file. Index, account and amount per line, plus the holder ID each account maps to, and the script version that built the root.
- Root and contract. The deployed address, root, token and
endTime, and a check that the published root matches the file. - Funding. The transfer into the contract, equal to the file's
tokenTotal. - Claims. Each
Claimedevent matched to its file line, with the transaction sender recorded. - Sweep. The
withdrawtransaction, the amount, the receiving account, and the list of unpaid lines it represents.
The amount file is a compliance artefact, not an engineering by-product. It has to reflect the identity-bound register of eligible holders on the record date, and claim events have to reconcile back to it. That is the same register discipline described in the guide to institutional RWA custody and lifecycle compliance. Blockmaze focuses on producing that register; it does not ship a distributor contract.
When is a Merkle claim the wrong design?
When the holder count is small, when amounts often need correcting, or when the issuer cannot accept interest sitting unclaimed. For a note with 20 holders, a direct transfer per holder is simpler and leaves no open lines.
The pattern fits a widely held note or fund share with stable terms, a fixed record date and holders able to submit transactions or rely on a relayer. It fits poorly where interest can be capitalised, where withholding changes often, or where an investor agreement promises payment to a registered account by a set date. In those cases the servicer still needs a push path for exceptions. Facts above are taken from the Uniswap merkle-distributor at commit 25a79e8e, OpenZeppelin MerkleProof at v5.7.0, Circle's FiatTokenV1 and Pendle's developer documentation. This is technical analysis, not legal or tax advice.
Frequently Asked Questions
How does a Merkle distributor pay interest to token holders?
The servicer builds a file of index, wallet and amount for every holder at the record date, hashes each line into a leaf, and publishes the Merkle root in a funded contract. A holder, or anyone acting for it, calls claim with its line and a proof. The contract checks the proof, marks the index as paid in a bitmap, transfers the amount and emits a Claimed event.
Can a wrong amount be fixed after the Merkle root is published?
Not in the Uniswap reference contract. The root is declared immutable and set once in the constructor, so a correction means a new contract, a new funding transfer and a record of which lines of the old root were already paid. Cumulative designs, such as Pendle's distributor, let an owner replace the root each cycle and pay only the difference since the last claim.
Does the Merkle distributor check KYC or sanctions at claim time?
No. The reference claim function checks only that the index is unclaimed and that the proof matches the root. It does not read msg.sender or any identity registry. If the payment token itself refuses the recipient, as Circle's FiatToken does for blacklisted addresses, the transfer reverts, the whole claim reverts and the line stays unpaid.
What happens to interest that holders never claim?
In MerkleDistributorWithDeadline, claims revert after endTime and the owner can call withdraw, which sends the contract's entire remaining balance to the owner. The contract keeps no record of whose interest that was. The servicer needs a written policy for those funds, including how they are booked as owed to holders and how lost-holder and unclaimed property rules apply.
Is a Merkle claim cheaper than pushing interest to every wallet?
On-chain work moves from the servicer to the claimants. A push payment makes one transfer per holder, so the servicer's cost grows with the holder count. A Merkle payout costs the servicer one deployment and one funding transfer, and each claim verifies a proof whose length grows with the base-2 logarithm of the holder count: 10 hashes for 1,000 lines.
Related Articles
What Must an Issuer Report After Freezing Sanctioned Tokens?
OFAC blocked property reports, annual filings and record retention after a tokenized security is frozen on-chain.
REITs and Compliant On-Chain Dividends
How a REIT can pay distributions on-chain while keeping holder eligibility and records in line.