# TimeLock

Source: https://docs.settlemint.com/docs/architecture/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 with a minimum holding period. DALP records acquisition batches per receiving address, checks transfers against the unlocked balance, and supports both fixed-period configurations and existing expression-based configurations.

## 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 first 100 tokens can be transferred after 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 changing the hold period requires a new module instance rather than an in-place update. Existing expression-based configurations can also include exemption settings in their module parameters. For configurations that do not include exemption expressions, model eligibility exemptions with the compliance engine scope and the surrounding policy modules.

## 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 the requested amount is covered by unlocked batches, even if newer batches remain locked. |
| Exact expiry           | The batch must be past the expiry moment before it is treated as unlocked.                                            |
| Burn lifecycle         | Burn hooks can reduce tracked batches without using the normal transfer lock check.                                   |

The FIFO queue is maintained for the receiving address. If the same investor uses more than one wallet, each address has its own acquisition batches and unlocked balance.

## Operational notes [#operational-notes]

* TimeLock blocks transfers before enough balance is unlocked and returns an insufficient-unlocked compliance failure.
* Mint checks are allowed because they 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 operators should consider batch count when designing high-volume workflows.
* Current configurations that do not include exemption expressions rely on the compliance engine scope and surrounding policy modules for eligibility exemptions.

## See also [#see-also]

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