# TimeLock

Source: https://docs.settlemint.com/docs/compliance-security/compliance/timelock
TimeLock enforces minimum holding periods with FIFO batch tracking, hold-period configuration, and address-level transfer checks.



TimeLock is a compliance module for assets that require a minimum holding period. When an investor receives tokens, the platform records an acquisition batch for that address. A transfer proceeds only when unlocked batches cover the requested amount. Use TimeLock when your token policy requires a lockup period before holders can sell or transfer.

## TimeLock checks [#timelock-checks]

TimeLock applies to received tokens. When an investor receives tokens, DALP records the amount and acquisition time as a batch. A transfer can proceed only when enough of the investor's oldest batches have passed the configured holding period.

For example, if an investor receives 100 tokens on day 1 and 50 tokens on day 90 with a 180-day hold period, the investor can transfer the first 100 tokens once the day-1 batch clears. The second batch remains locked until its own holding period clears.

## Configuration [#configuration]

| Parameter             | Description                                                                                           |
| --------------------- | ----------------------------------------------------------------------------------------------------- |
| `holdPeriod`          | Minimum holding period in seconds. Current deployments can require a value from 1 second to 10 years. |
| `allowExemptions`     | Optional setting on existing module configurations that allows identity-claim exemptions.             |
| `exemptionExpression` | Optional expression used by existing configurations when exemptions are enabled.                      |

The hold period is part of the module configuration. Fixed-period configurations accept the same value again, but if you need to change the hold period you must deploy a new module instance rather than updating in place. Existing expression-based configurations can also include exemption settings in their module parameters. Configurations without exemption expressions rely on the compliance engine scope and surrounding policy modules for eligibility exemptions.

## Transfer lifecycle [#transfer-lifecycle]

<Mermaid
  chart="flowchart TD
  receive[Investor receives tokens] --> batch[DALP records an acquisition batch]
  batch --> wait[Batch remains locked for the configured period]
  wait --> check[Investor submits a transfer]
  check --> enough{Enough unlocked balance?}
  enough -->|Yes| allow[Transfer can continue through the compliance engine]
  enough -->|No| block[Transfer is blocked for insufficient unlocked tokens]"
/>

TimeLock runs during the compliance check. DALP can also report the investor's available balance and remaining lock time, so operators and applications can explain why a transfer is still locked.

## Batch accounting [#batch-accounting]

TimeLock uses FIFO batch accounting:

| Behaviour              | What happens                                                                                                  |
| ---------------------- | ------------------------------------------------------------------------------------------------------------- |
| Incoming token receipt | DALP records a new batch for the recipient address with the received amount and acquisition time.             |
| Transfer check         | DALP walks the oldest batches first and counts only batches whose holding period has cleared.                 |
| Partial availability   | A transfer can proceed when unlocked batches cover the requested amount, even if newer batches remain locked. |
| Exact expiry           | The batch must be past the expiry moment before the compliance engine treats it as unlocked.                  |
| Burn lifecycle         | Burn hooks can reduce tracked batches without using the normal transfer lock check.                           |

The platform maintains the FIFO queue per receiving address. If the same investor uses more than one wallet, each address carries its own acquisition batches and unlocked balance.

## Operational notes [#operational-notes]

* TimeLock blocks transfers when not enough balance has cleared the holding period, and returns an insufficient-unlocked compliance failure.
* The compliance engine allows mint checks because mints do not spend previously received tokens.
* The compliance engine is the caller for lifecycle hooks that record created, transferred, and destroyed token amounts.
* Frequent small receipts create more batches, so consider your expected batch count when designing high-volume workflows.
* Configurations without exemption expressions rely on the compliance engine scope and surrounding policy modules for eligibility exemptions.

## See also [#see-also]

* [Compliance overview](/docs/compliance-security/compliance) for the broader module model.
* [Identity verification](/docs/compliance-security/compliance/identity-verification) for identity-based policy checks.
* [Supply and investor limits](/docs/compliance-security/compliance/supply-investor-limits) for supply and participant controls often used with holding periods.
* [Transfer approval](/docs/compliance-security/compliance/transfer-approval) for approval controls that can sit alongside holding-period enforcement.