Supply & Investor Limits

TokenSupplyLimit checks minting against configured supply caps. InvestorCount checks whether adding a recipient would exceed configured holder-count limits.

Where these modules apply

TokenSupplyLimit

Enforces maximum token supply limits, with optional base-price conversion for EUR/USD-denominated caps.

Interface (capabilities)

Supply limit types

Base currency conversion

When an admin enables useBasePrice, the module converts token amounts using on-chain price claims before checking the supply limit. The conversion supports EUR- or USD-denominated caps on tokens priced in native units.

Key invariants

• Supply limit applies to minting operations only; transfers and burns are not checked.
• ROLLING_PERIOD uses a sliding window; older mints fall off as time passes.
• FIXED_PERIOD resets at the start of each new period, regardless of previous minting.
• Calling setModuleParameters with maxSupply = 0 reverts; the cap must be a positive value.

Operational signals

No events emitted by this module. Monitor for ComplianceCheckFailed revert errors in failed transactions when minting exceeds the configured limit.

Failure modes & edge cases

• Missing or stale price feed when useBasePrice is active: minting reverts until a valid price claim exists.
• ROLLING_PERIOD window boundary: mints near the window edge may succeed or fail depending on when older mints age out.

---

InvestorCount

Restricts the number of unique token holders. The topicFilter determines which investors count toward the limit, not which investors identity verification blocks.

Interface (capabilities)

How it works

topicFilter and limits

The topicFilter is a claim expression (same RPN system as SMARTIdentityVerification) that determines which investors count toward the limit. InvestorCount can enforce a global limit across all investors and per-country limits for jurisdiction-specific restrictions (e.g., max 50 Singapore residents).

Key invariants

• canTransfer skips burns (to == address(0)) but applies to both mints and transfers.
• The active tracker depends on the global flag. With global enabled, tokens using the same InvestorCount module instance share one investor tracker. Use separate module instances when policies need isolated counts. Otherwise, counts are token-specific.
• InvestorCount checks per-country limits independently of the global limit; both must pass when configured.
• topicFilter determines who counts toward InvestorCount. Identity verification handles blocking.
• InvestorCount does not count addresses without a registered identity; use identity verification when the policy must block unverified recipients.

Operational signals

No events emitted by this module. Monitor for ComplianceCheckFailed revert errors in failed transactions when investor count exceeds limits.

Failure modes & edge cases

• Forced transfers bypass the pre-transfer investor-limit check but still update holder tracking after the transfer. A forced transfer to a new holder can leave the current investor count above the configured limit. Later movements can bring the count back within policy.
• Missing country code in the identity registry: InvestorCount counts the investor globally when a global limit is configured, but not toward a per-country limit.

See also

• Compliance Overview - module architecture and regulatory templates
• Identity Verification - topicFilter uses the same RPN expression system
• Transfer Approval - pre-approval controls complement investor count limits
• Supply Cap & Collateral - CappedComplianceModule for hard circulating supply caps