Can You Add a Holding Cap to a Live ERC-3643 Token?
An ERC-3643 MaxBalanceModule is the T-REX compliance module that caps how many tokens one investor ONCHAINID can hold. It keeps its own per-identity balance ledger instead of reading token balances, so in the reference code it refuses to bind to a token with holders until the compliance owner hand-writes every identity's balance and marks the preset complete. Adding a cap to a live token is a migration, not a setting.
TL;DR — Key Takeaways
- ✓The gate: MaxBalanceModule is not plug-and-play. addModule binds it only if totalSupply is 0 or the compliance owner has marked a balance preset complete.
- ✓The ledger: The module counts balances per ONCHAINID in its own mapping and never reads token balances. The preset is a hand-written snapshot the chain then trusts.
- ✓The failure modes: An overstated identity is blocked from receiving; an understated one can exceed the cap, and in code reading its outgoing transfers and burns revert on checked-math underflow.
- ✓The gap: The cap is 0 between addModule and setMaxBalance, so every transfer and mint fails until both calls land. Pause does not stop agent mints, burns or forced transfers.
- ✓The source: All behaviour here is read from the archived TokenySolutions/T-REX main branch at commit f1390127. The successor ERC-3643/ERC-3643 repository ships no MaxBalanceModule.

Why won't MaxBalanceModule bind to a token that already has holders?
In the T-REX reference code, MaxBalanceModule binds only when the token's totalSupply is 0 or the compliance owner has marked a balance preset complete. On a live token with no preset, addModule reverts.
An ERC-3643 token routes every transfer through a ModularCompliance contract, which holds a list of compliance modules. ModularCompliance.addModule is onlyOwner, caps the list at 25 modules, and asks each new module whether it is plug-and-play. If the module says no, the compliance contract calls canComplianceBind and refuses to bind on a false answer. MaxBalanceModule hard-codes isPlugAndPlay() to return false. Its canComplianceBind returns true in two cases only: the preset status for that compliance is true, or the bound token has zero supply.
The reason is structural. The module does not ask the token how many tokens an investor holds. It keeps a private mapping, _IDBalance[compliance][identity], and updates it on every mint, transfer and burn it is told about. A module bound at launch sees every movement from zero. A module bound later starts blind, and the preset is how you tell it what it missed. This is a property of one module in the reference implementation, not of the standard; the token standards themselves are compared in the RWA token standards guide.
“require(module.canComplianceBind(address(this)), "compliance is not suitable for binding to the module");”
ModularCompliance.sol, addModule, TokenySolutions/T-REX main @ f1390127
What does the module count: wallets or investors?
It counts investors. Every wallet is resolved to its ONCHAINID through the token's Identity Registry, and one balance is kept per ONCHAINID per compliance contract, so all wallets of one investor share one cap.
The lookup happens in _getIdentity, which reads identityRegistry().identity(wallet) from the bound token and reverts with “identity not found” if the result is the zero address. Three consequences follow from the code. First, the preset has to aggregate holdings across all wallets of an identity; a per-wallet snapshot from a block explorer is the wrong unit. Second, a wallet that holds tokens but has been removed from the registry cannot send, because the module cannot find its identity. Third, moduleCheck ignores the sender and tests only whether the receiver identity's tracked balance plus the amount exceeds the cap. An investor close to the cap who moves tokens between two of their own wallets is checked as if the full amount were new, so the move can be rejected even though their total does not change.
One module deployment can serve many compliance contracts: both the cap (_maxBalance) and the ledger are keyed by compliance address. The module itself is a UUPS proxy whose _authorizeUpgrade is onlyOwner, and that owner is the module's deployer, not your compliance owner. The upgrade question for the token suite itself is covered in who can upgrade an ERC-3643 token's code; a shared module adds one more key to that list.
How do the preset functions work?
Three owner-only functions write the preset: preSetModuleState sets one identity, batchPreSetModuleState sets many and marks the preset complete, and presetCompleted marks it complete without writing any balance.
| Function | Who can call | What it does | After binding |
|---|---|---|---|
preSetModuleState(compliance, id, balance) | Owner of the compliance contract | Overwrites one identity's tracked balance; emits IDBalancePreSet | Reverts TokenAlreadyBound |
batchPreSetModuleState(compliance, ids, balances) | Owner of the compliance contract | Overwrites many; reverts on empty or mismatched arrays; sets preset status to true | Reverts TokenAlreadyBound |
presetCompleted(compliance) | Owner of the compliance contract | Sets preset status to true; writes no balances; emits PresetCompleted | Still callable |
setMaxBalance(max) | Only a bound compliance contract, so in practice the owner via callModuleFunction | Stores the cap for the calling compliance; emits MaxBalanceSet | Only works after binding |
What the code does not check matters as much. No function compares the sum of preset balances with totalSupply. No function compares a preset balance with the identity's real holdings or with the cap. presetCompleted lets an owner open the binding gate with an empty ledger, and batchPreSetModuleState sets the status without emitting PresetCompleted, so an indexer that watches only that event will miss batch presets. The preset is a statement by one key that the chain accepts as written.
“function presetCompleted(address _compliance) external … _compliancePresetStatus[_compliance] = true;”
MaxBalanceModule.sol, TokenySolutions/T-REX main @ f1390127
What breaks when the preset is wrong?
An overstated identity is blocked from receiving tokens it should be allowed to buy. An understated identity can go over the cap, and in code reading its outgoing transfers and burns revert once they exceed its tracked balance.
Overstatement is the visible error: the investor's next purchase fails moduleCheck, the transfer returns “Transfer not possible”, and someone files a ticket. Understatement is quieter. If a holder's identity is preset lower than its true holdings, the module allows it to receive up to the cap on top of what it already has, so the cap is not enforced for that investor. An identity left out of the batch entirely is tracked at 0.
The outgoing side follows from the arithmetic. The path for a holder transfer in the reference code is: Token.transfer checks the ERC-20 balance and calls canTransfer, which runs moduleCheck on the receiver only; _transfer moves the ERC-20 balances; then ModularCompliance.transferred calls moduleTransferAction on every module, with no try/catch. Inside MaxBalanceModule that function runs _IDBalance[msg.sender][_idTo] += _value and then _IDBalance[msg.sender][_idFrom] -= _value. The contract is compiled with pragma solidity 0.8.17 and contains no unchecked block, so Solidity's default checked arithmetic applies: if the sender identity's tracked balance is lower than _value, the subtraction panics with error code 0x11 and the whole transaction reverts, including the ERC-20 balance change. moduleBurnAction performs the same unguarded subtraction for burns. forcedTransfer skips canTransfer but still calls transferred, so the same subtraction runs. This is our reading of the source; we have not executed it, and the T-REX test file for this module contains no case for it.
“_IDBalance[msg.sender][_idTo] += _value; _IDBalance[msg.sender][_idFrom] -= _value; if (_IDBalance[msg.sender][_idTo] > _maxBalance[msg.sender]) revert MaxBalanceExceeded(msg.sender, _value);”
MaxBalanceModule.sol, moduleTransferAction, TokenySolutions/T-REX main @ f1390127
Illustrative example (invented numbers, not a real issuer). A fund sets a cap of 100,000 units. Investor A holds 60,000 in wallet A1 and 30,000 in wallet A2, both registered to one ONCHAINID, so the true figure is 90,000. The snapshot script reads only A1 and presets 60,000. After binding, A can buy 40,000 more and reach 130,000 against a 100,000 cap. Investor B holds 5,000 and was missed, so B is tracked at 0; when B tries to sell 5,000, the subtraction 0 − 5,000 reverts on the reading above, and B cannot sell until the ledger is fixed or B first receives tokens.
None of this describes an incident. We know of no documented exploit of a permissioned RWA token through this module; the point is an operational failure mode that a snapshot error produces on its own.
Which other operations hit the cap logic?
Mints, burns, forced transfers and wallet recoveries all pass through the module's action hooks. Agents cannot push an identity over the cap with forcedTransfer, and a recovery into an identity already above the cap reverts in code reading.
| Operation | Pre-check (moduleCheck) | Post-action in the module | Stopped by pause()? |
|---|---|---|---|
Holder transfer / transferFrom | Yes, receiver only | Add to receiver, subtract from sender, revert if receiver above cap | Yes |
Agent forcedTransfer | No | Same as transfer; reverts MaxBalanceExceeded if receiver ends above cap | No |
Agent mint | Yes | Add to receiver, revert if above cap | No |
Agent burn | No | Subtract from holder, no floor | No |
Agent recoveryAddress | No (uses forcedTransfer) | Same identity: add then subtract nets to zero, then the receiver check runs | No |
The recovery row needs care. recoveryAddress registers the new wallet to the investor's ONCHAINID and then calls forcedTransfer before deleting the lost wallet from the registry, so both wallets resolve to the same identity. Because the module adds before it subtracts, the tracked balance does not underflow and ends where it started. The module then tests whether that balance is above the cap. If the cap was lowered below the investor's holdings, or the identity was overstated in the preset, the recovery reverts. The register side of a recovery is covered in ERC-3643 lost wallet recovery and register reconciliation; this module adds one more state that has to be correct before recovery works.
Lowering the cap later is a related trap. setMaxBalance stores a number and rebalances nothing. The module's own test sets a cap of 150, credits an identity with 150, lowers the cap to 100, and a 40-unit transfer action out of that identity still succeeds. Over-cap holders can always reduce. They cannot receive, and in code reading they cannot be recovered. Because the mint hook adds each row to the identity total before the next row is checked, two rows for one investor in the same batch can each pass a pre-check and still revert the whole ERC-3643 batch mint. A transfer fee module adds one more identity to this ledger, because its fee leg into the collector wallet runs the same hook, as shown in how an ERC-3643 transfer fee is taken from the receiver.
What is the safe order of operations on a live token?
Halt movements, snapshot per identity, preset in batches, reconcile the preset to totalSupply, then bind and set the cap in one transaction or while still halted. The cap reads 0 until setMaxBalance runs, so every transfer and mint fails in that gap.
The 0 default is easy to miss. setMaxBalance carries the onlyComplianceCall modifier, so it can only be reached through callModuleFunction after the module is bound. Until it runs, _maxBalance for your compliance is 0, moduleCheck returns false for any non-zero amount, and the post-action reverts for any identity with a tracked balance above 0. The ModularCompliance in both the archived T-REX repository and the current ERC-3643/ERC-3643 repository exposes no combined add-and-configure function, so the two calls have to be sequenced deliberately.
- Halt.
pause()stops holdertransferandtransferFromonly.mint,burn,forcedTransferandrecoveryAddresscarry nowhenNotPausedmodifier, so agent operations need a written freeze for the window. - Snapshot. Read ERC-20 balances at a fixed block, map every wallet to its ONCHAINID through the Identity Registry, and sum per identity. Flag any holder wallet with no identity before you go further.
- Preset. Call
batchPreSetModuleStatewith the per-identity totals. Split large holder lists into several calls; the preset can be rewritten freely until binding. - Reconcile. Before binding, read back
getIDBalancefor every identity and confirm the sum equalstotalSupply()at the snapshot block, and that each figure matches the off-chain register. - Bind and set. Call
addModule, thencallModuleFunctionwithsetMaxBalance, from the compliance owner, ideally batched in one multisig transaction. - Resume. Unpause, lift the agent freeze, and test one small transfer before announcing.
The compliance owner signs every step. That key decides what the ledger says, so it belongs in the same governance review as the agent keys described in who controls an ERC-3643 token's agent keys.
How do you fix the ledger after binding?
The preset functions are closed after binding, but the compliance owner can still move an identity's tracked balance by calling moduleMintAction or moduleBurnAction through callModuleFunction. The module's own test suite uses that route to set up balances.
This works because onlyComplianceCall checks only that msg.sender is a bound compliance contract, and callModuleFunction makes the compliance contract the caller. A correction credits or debits a wallet's identity in the module without any token moving. The same caveats apply: the wallet must resolve to an identity, a debit larger than the tracked balance hits the same unguarded subtraction, and a credit that takes the identity above the cap reverts. It also means the ledger is never final. One key can raise or lower any investor's tracked holdings at any time, and holders have no on-chain signal that it happened beyond the ModuleInteraction event the compliance contract emits.
The other route, removing and re-adding the module, is weaker than it looks. removeModule does not reset the preset status or clear _IDBalance. After removal the preset functions open again, but canComplianceBind already returns true, so the module can be re-added at once with a ledger that missed every movement made while it was unbound. Re-adding should be treated as a fresh migration, with a full new preset.
What should the audit trail prove?
That the snapshot block, the per-identity totals, the signer and the reconciliation to totalSupply all agree with the off-chain register. Each IDBalancePreSet event is a claim by one key; the evidence has to show where each number came from.
| Record | Why it matters |
|---|---|
| Snapshot block number and wallet-to-identity mapping | Shows the preset reflects one consistent state, aggregated per ONCHAINID |
| Register extract at the same cut-off | The legal record of ownership; the preset must match it, not only the chain |
| Preset and bind transaction hashes, with signers | Ties every ledger value to the compliance owner key and its approvers |
Read-back of getIDBalance summed against totalSupply() | Detects missed or double-counted identities before the cap goes live |
Log of later callModuleFunction corrections | Explains every change to the ledger made outside a real token movement |
| Cap value and its source document | Links setMaxBalance to the prospectus, investor agreement or regulator's limit |
Who this matters for: issuers adding a concentration limit after launch, transfer agents who must certify the register matches the chain, and auditors reviewing a token that bound the module late. It matters less for tokens that bound MaxBalanceModule before the first mint, where the ledger has seen every movement. Teams on the ERC-3643/ERC-3643 code base should note the module is not shipped there; a copied or rewritten version needs its own review, and the original file header adds a CC-BY-NC-4.0 licence that, in its own words, “prohibits commercial use” and directs commercial inquiries to Tokeny.
Sources: MaxBalanceModule.sol, ModularCompliance.sol, Token.sol, AbstractModuleUpgradeable.sol and module-max-balance.test.ts, all TokenySolutions/T-REX main @ f1390127 (repository archived, read 2026-11-05); ERC-3643/ERC-3643 modular compliance; ERC-3643 specification.
Frequently Asked Questions
Why does MaxBalanceModule refuse to bind to my live ERC-3643 token?
MaxBalanceModule.isPlugAndPlay() returns false, so ModularCompliance.addModule asks canComplianceBind first. That returns true only if the token's totalSupply is 0 or the compliance owner has marked the preset complete. On a token with holders and no preset, addModule reverts with "compliance is not suitable for binding to the module". The fix is to preset every holder identity's balance, then bind.
Does MaxBalanceModule cap each wallet or each investor?
Each investor identity. The module looks up the ONCHAINID behind every wallet in the token's Identity Registry and keeps one balance per ONCHAINID per compliance contract. Three wallets registered to the same ONCHAINID share one cap. A wallet with no identity in the registry makes the module revert with "identity not found", so the preset has to be built per identity, not per wallet.
Can a wrong preset be corrected after the module is bound?
Not with the preset functions: preSetModuleState and batchPreSetModuleState revert with TokenAlreadyBound once the module is bound. The T-REX test suite shows another route: the compliance owner calls moduleMintAction or moduleBurnAction through callModuleFunction, which changes an identity's tracked balance without moving any tokens. That fixes errors, but it also means one key can rewrite the ledger at any time.
What happens to holders already above a new, lower cap?
Nothing is forced. setMaxBalance stores a new number and does not touch existing holdings. A holder above the new cap can still send tokens out, because the checks look only at the receiver. They cannot receive more until their tracked balance drops below the cap. In code reading, a wallet recovery into that same identity also reverts, because the module re-checks the receiver after the move.
Is MaxBalanceModule part of the ERC-3643 standard?
No. The ERC-3643 specification defines a compliance interface, not individual modules. MaxBalanceModule lives in the TokenySolutions/T-REX repository, which is archived and marked deprecated in favour of ERC-3643/ERC-3643. As of November 2026 the successor repository's modules folder holds only AbstractModule, AbstractModuleUpgradeable, IModule, ModuleProxy and TestModule. The file header also adds a CC-BY-NC-4.0 licence that prohibits commercial use.
Related Articles
Who Is the Transfer Agent for a Tokenized Security?
Legal ownership of a security lives in the master securityholder file, not in a wallet balance, even when a registered transfer agent keeps that file on a blockchain.
Can Expired KYC Make an ERC-3643 Position Unsellable?
ERC-3643 transfer checks can turn expired or revoked identity claims into a liveness dependency for tokenized securities.
Is the Tokenized RWA Market Too Concentrated?
Five issuers or platforms control roughly 75-80% of on-chain RWA value, and tokenized products routinely hold each other as underlyings.
Smart Contract Compliance vs Layer-0 Governance for RWA: A Practical Guide
When smart contract compliance is sufficient for an RWA program and when Layer-0 governance is required.