TimeLock
TimeLock module enforces minimum holding periods using FIFO batch tracking. Covers configuration, identity-based exemptions, and integration with regulatory templates like MAS Singapore.
Purpose: Reference for the TimeLock compliance module.
- Doc type: Reference
- What you'll find here:
- TimeLock — minimum holding period enforcement with FIFO batch tracking
- Interface table showing on-chain capabilities
- Identity-based exemptions and regulatory use cases
- Key invariants, operational signals, and failure modes
- Related: Compliance Overview, Identity Verification, Supply & Investor Limits, Transfer Approval
TimeLock
Enforces minimum holding periods — tokens received must be held for at least holdPeriod seconds before they can be transferred.
Interface (capabilities)
| Capability | Who can call | Inputs | On-chain effect | Emits | Notes |
|---|---|---|---|---|---|
setModuleParameters | Token admin (via compliance) | holdPeriod, allowExemptions, exemptionExpression | Stores holding-period config | — | exemptionExpression uses the same RPN system as identity verification |
canTransfer | Compliance engine | Sender, recipient, amount | Walks FIFO queue; checks if enough unlocked balance exists for the transfer amount | — | Exempted investors bypass the check entirely |
recordAcquisition | Compliance engine (post-transfer hook) | Investor identity, amount, timestamp | Creates a new FIFO batch entry with expiry = timestamp + holdPeriod | AcquisitionRecorded | Called after every successful incoming transfer |
unlockTokens | Token holder (or agent) | Investor identity | Releases expired batches from the FIFO queue | TokensUnlocked | Optional — canTransfer also processes expired batches inline |
How it works
TimeLock uses FIFO (First In, First Out) batch tracking. Each incoming transfer creates a batch with:
- Amount received
- Timestamp received
- Expiry (received + holdPeriod)
On transfer, the module walks the FIFO queue and checks whether the oldest batches have cleared their holding period. If the requested transfer amount exceeds the unlocked balance, the transfer is blocked.
Example: An investor receives 100 tokens on day 1 and 50 tokens on day 90, with a 180-day hold. On day 185, they can transfer up to 100 tokens (day 1 batch unlocked). The day 90 batch unlocks on day 270.
Configuration
| Parameter | Description |
|---|---|
holdPeriod | Minimum holding period in seconds (e.g., 15552000 = 180 days) |
allowExemptions | If true, investors matching the exemption expression bypass the lock |
exemptionExpression | RPN expression identifying exempt investors |
Identity-based exemptions
The exemption expression uses the same RPN system as SMARTIdentityVerification. Common exemption patterns:
| Exemption | Expression | Use case |
|---|---|---|
| QII investors exempt | [CONTRACT] | Japan FSA: institutional investors skip lockup |
| Accredited investors exempt | [ACCREDITED] | Reg D: accredited investors can trade freely |
| No exemptions | Empty | MAS Singapore: all investors subject to hold period |
Regulatory use cases
| Regulation | Hold period | Exemption |
|---|---|---|
| MAS Singapore — Capital Markets | 180 days (15,552,000 seconds) | None |
| US Reg D 506(b) — typical | 1 year (31,536,000 seconds) | [ACCREDITED] |
| EU MiCA — some asset types | Varies | Depends on instrument type |
Key invariants
- TimeLock applies to received tokens, not the sender's full balance
- Forced transfers (custodian) bypass the TimeLock check
- Burns are not blocked by TimeLock — the FIFO queue walks batches oldest-first and skips lock checks for burn operations
- The FIFO queue is maintained per investor identity (not per wallet address)
Operational signals
AcquisitionRecorded— emitted after each incoming transfer creates a new FIFO batchTokensUnlocked— emitted when expired batches are released from the FIFO queue- Monitor for
ComplianceCheckFailedrevert errors in failed transactions when transfers exceed unlocked balance
Failure modes & edge cases
- Hold period changed after tokens acquired — existing batches keep their original expiry; only new acquisitions use the updated period
- Exemption expression changed — investors who previously bypassed the lock are now subject to it (and vice versa), but only for future transfers
- Large number of FIFO batches from frequent small transfers —
canTransfergas cost increases linearly with batch count
See also
- Compliance Overview — module architecture and regulatory templates
- Identity Verification — RPN expression system for exemption expressions
- Supply & Investor Limits — InvestorCount often paired with TimeLock
- Transfer Approval — complementary pre-approval controls
Supply Cap & Collateral
CappedComplianceModule and CollateralComplianceModule — simple circulating supply cap enforcement and ERC-735 claim-based collateral requirements for minting.
Wallet Verification
Wallet verification gates blockchain write operations as a second security layer beyond session authentication, supporting PIN, TOTP, backup codes, and passkey-based verification methods.