> For the complete documentation index, see [llms.txt](https://docs.ipor.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipor.io/build-on-fusion/atomists/vault-configuration-step-by-step/timelocks-and-execution-delays.md).

# Timelocks and Execution Delays

This guide explains the conceptual model, governance rules, and operational safeguards of **timelocks (execution delays)** in IPOR Fusion.

## 1. Executive Summary: What is a Timelock?

A **timelock** (technically referred to as an **execution delay**) is a mandatory, onchain "cooling-off" period enforced between the time an administrative action is proposed and the time it actually takes effect on the blockchain.

In IPOR Fusion, no single administrative key can immediately alter critical vault parameters (such as changing performance fees, updating assets, or modifying Fuses) if a timelock is active. This design enforces complete transparency and provides a vital window for depositors and Guardians to react before any high-impact change is executed.

## 2. The Core Value Proposition

Timelocks are not meant to slow down routine operations, but rather to establish a robust line of defense for depositors and operators. They solve three primary security problems:

| **Risk Mitigated**       | **How Timelock Solves It**                                                                                                                                                                |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Admin Key Compromise** | If an Atomist or Owner private key is stolen, the attacker cannot drain or hijack the vault instantly. They must schedule their malicious transaction, triggering public alerts.          |
| **Human Error**          | If an operator inputes an incorrect fee percentage (e.g., 50% instead of 5%), the mistake is caught while sitting in the queue and can be cancelled before execution.                     |
| **User Transparency**    | Depositors are never surprised by sudden policy shifts. If a vault owner increases performance fees, depositors have the entire timelock window to withdraw their funds if they disagree. |

## 3. The Three Shields of Vault Security

Timelocks turn governance from something that *can* happen instantly into something that *must* happen slowly and in the open. To achieve this, the system relies on three distinct defensive shields working together.

**Shield 1: The Notice Period (Execution Delay)** A protected role cannot act on the spot. It must publicly announce an operation and may carry it out only after its delay elapses (e.g., 14 days for the Owner, 3 days for the Atomist). The pending operation is visible on-chain throughout this period.

**Shield 2: The Waiting Room (Grant Delay)** When a new account is granted an important role, its membership does not activate immediately — it waits out that role's grant delay first (recommended: 14 days for `OWNER`, 3 days for the configuration tier). This closes the "inject a key into governance" path: even a grant that completes successfully produces an account that cannot act yet.

The rule itself is protected too. Changing a grant delay via `setGrantDelay` arms only after a hardcoded 5-day minimum setback — and reducing one takes the larger of 5 days and the size of the reduction. Nobody, including a legitimate administrator, can shorten the waiting room and walk a new key straight in. Note that grant delays are `ADMIN`-gated: they must be configured before `ADMIN` is renounced, or they become permanently unavailable.

Re-granting an existing member — for example raising their execution delay — is not subject to the grant delay. This is deliberate: it keeps hardening instantaneous.

**Shield 3: The Minimum Threshold (Floors)** Without a minimum threshold, a timelock could theoretically be bypassed in minutes by removing a role and granting it back with a zero-day waiting period. The Access Manager prevents this by enforcing a hard floor (a minimum execution delay) for critical roles. The contract will reject any attempt to grant a role with a delay shorter than its established floor. Crucially, lowering this floor is itself an Owner action, meaning it also requires a 14-day public notice.

*Developer Note:* Setting a floor is **not retroactive**. It constrains future grants only. If an account already holds a role, setting a new floor does not increase their current delay. To apply the new floor to existing accounts, they must be explicitly re-granted their roles.

> **The Golden Rule:** Tightening security is fast; loosening security is slow. Raising any protection (e.g., increasing a delay) takes effect immediately, allowing a vault to be hardened the moment a problem is suspected. Conversely, every weakening of security is visible long before it lands.

## 4. Timelock Levels and Configuration

Timelocks are highly granular and can be configured at two distinct levels to fit your organization's security posture:

### A. Account-Role Level (Individual Delays)

You can apply different timelock durations to different accounts, even if they hold the exact same administrative role.

* **Operational Example**: A vault owner might grant the Atomist role to a **multi-signature cold wallet** with a 0**-second delay** (for rapid emergency adjustments), while granting the same Atomist role to a **single-signature hot wallet** or automated keeper with a 2**-day delay** for routine rebalancing.

### B. Minimal Role Delay (The Safety Floor)

To prevent key administrators from overriding security thresholds, the system supports a "Minimal Role Delay". Once set, no account can be granted that specific role with a delay lower than the established floor.

* **Operational Example**: If the Minimal Role Delay for the Atomist role is set to 1 day, any attempt by a compromised Owner account to grant an instant, 0-day Atomist role will be automatically rejected by the access manager.

## 5. Who Can Set, Edit, and Remove Timelocks?

The editing and removal of timelocks is governed by the **Role Admin Hierarchy**. Under this model, only the designated "Admin" of a specific role has the authority to grant that role or modify its execution delay:

```
                             ┌───────┐
                             │ Admin │
      ┌──────────────────────┐◄──────┘
      │      OWNER ROLE      │
      └──────────┬───────────┘
                 │ Admin of
                 │
                 ├──────────────────────────────────────┐
                 ▼                   ▼                  ▼
┌─────────────────┐ ┌─────────────────┐ ┌──────────────────┐
│  ATOMIST ROLE   │ │  GUARDIAN ROLE  │ │ PRE HOOKS ROLE   │
└────────┬────────┘ └─────────────────┘ └──────────────────┘
         │ Admin of
         ├───────────────────┐
         ▼                   ▼
┌─────────────────┐ ┌─────────────────┐
│   ALPHA ROLE    │ │FUSE MANAGER ROLE│
└─────────────────┘ └─────────────────┘
```

* **Owners Only**: The Owner administers the Atomist and Guardian . Only Owners can set, edit, or remove timelocks on Atomists or Guardians.
* **Atomists Only**: The Atomist administers operational roles like Alpha or Fuse Manager. Only the Atomists can configure timelocks for those roles.
* **Self-Governance**: The Owner role is self-administered. Only existing Owner accounts can modify the delay settings of other Owner accounts.

## 6. The "Admin Timelock" Constraint

A common security vulnerability in DeFi occurs when an administrator with a timelock simply uses their admin power to change their own timelock to 0 seconds, bypassing the safety window.

IPOR Fusion closes this loophole using **Self-Referential Security**:

> **Rule**: Administrators are strictly bound by their own timelocks.

If a vault Owner is subject to a 14-day timelock (which is the strictly recommended default for this role), they cannot instantly change their own timelock or the timelock of any other user. Any attempt to modify a timelock, grant a role, or change minimal role delays must itself be scheduled as a proposed transaction and wait out the 14-day cooling-off period before taking effect.

## 7. The Guardian: The Emergency Brake

While a timelock prevents malicious changes from occurring instantly, it is only effective if there is a mechanism to stop a malicious transaction while it sits in the queue. This is the responsibility of the [**Guardian**](/build-on-fusion/atomists/vault-configuration-step-by-step/access-management.md#guardian-role).

The Guardian acts as the vault’s emergency security sentinel:

* **The Sentinel Power**: Guardians have the unilateral authority to **cancel** any pending scheduled operational and configuration transaction in the access manager's queue.
* **Instant Cancellation**: Guardians are granted roles with a 0**-day delay**, enabling them to intervene instantly.
* **Safety Isolation**: Guardians can *only* cancel pending actions; they cannot schedule new administrative configurations or authorize movements of capital.

If a monitoring bot or offline cold wallet detects an unauthorized transaction in the queue, the Guardian executes a cancellation. The malicious transaction is instantly deleted, and the compromised key is rendered harmless while the operators coordinate a key rotation.

## 8. Enabling Timelocks on an Existing Vault (High-Level)

Activating timelocks is a configuration change, not a redeployment. No funds move, no migration is required, and the vault keeps operating normally throughout the process.

Before enabling timelocks, the Vault Owner must make several key decisions:

* **Owner Notice Period:** Starting at 14 days is the recommended default. Raising a delay is always immediate, so starting lower and tightening later costs nothing, but lowering it takes time.
* **Guardian Line-up:** Guardians may be individual keys held by people who react within hours. They may also be third-party security providers. Providers that monitor the mempool can react within the same block. Guardians should hold no other role, and their keys must be strictly separate from the Owner's keys.
* **Key Separation:** The Owner should operate via a dedicated multisig that is rarely used (effectively a cold wallet). Timelocks protect against rushed malicious actions; they do not protect against a stolen key. Separation limits the damage if a single key is compromised.
* **Monitoring:** Someone must actively watch for on-chain alerts (`RoleGranted`, `OperationScheduled`) and know how to respond. Without active monitoring, the 3-day and 14-day notice windows provide no actual protection.
* **Re-granting is Required:** Remember that simply setting minimum thresholds (floors) does not magically update the delays of accounts that already hold those roles. During setup, every existing account must be explicitly re-granted its role to apply the target execution delay.

## 9. Frequently Asked Questions (FAQ)

**Are everyday user operations delayed by timelocks?** No. Everyday operations such as deposits, withdrawals, and redemptions remain immediate. Timelocks govern rule changes and administrative parameters, not user activity.

**Can a change be announced and then quietly executed much later?** No. An announced operation expires 7 days after its earliest execution date. If it is not carried out within that execution window, it lapses entirely. The whole announcement process must then be restarted from scratch.

**Why does the automated Alpha (Keeper) operator have no timelock?** The Alpha operator is fast *because* it is strictly boxed in by rules that only the slow roles can change. It moves funds only within the limits, substrates, and protocols explicitly pre-approved by the Atomist and Fuse Manager. Delaying the Alpha would break daily rebalancing and yield harvesting without adding protection, as the dangerous power lies in changing the boundaries, not operating within them.

**What happens if Guardians pause a vault?** The emergency pause is a full freeze. It halts all execution actions, including user deposits and withdrawals. It is designed as an emergency brake for genuine incidents, not a convenience switch, and it is lifted once the situation is resolved.

**What stops an attacker from removing a role and re-granting it instantly?** The Minimum Threshold (Shield 3). The contract rejects any grant below the established floor. Lowering that floor first costs the Owner their own 14-day notice period, in plain sight.