> For the complete documentation index, see [llms.txt](https://docs.trilobyte.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.trilobyte.finance/protocol-mechanics/governance.md).

# Governance

Trilobyte uses a **role-based access control** system combined with a **Timelock** for governance delay on critical actions.

## Governance Architecture

```
┌───────────────────────────────────────────────┐
│                  Timelock                      │
│        (OZ TimelockController)                │
│   Proposer / Executor / Canceller roles       │
│   Admin of Globals (governor actions delayed) │
└──────────────────────┬────────────────────────┘
                       │ admin
┌──────────────────────▼────────────────────────┐
│                   Globals                      │
│          (OZ Access + Pausable + Upgradeable)  │
│   Settings · Roles · Fees · Assets · Managers  │
└───────────────────────────────────────────────┘
```

The **Timelock** is set as the admin of the **Globals** contract. This means all admin-level actions must go through a time-delayed governance process.

## Roles

| Role                 | Key         | Assigned To         | Responsibilities                                                           |
| -------------------- | ----------- | ------------------- | -------------------------------------------------------------------------- |
| **Admin**            | `"admin"`   | Governor / Timelock | Global settings, asset whitelist, contract upgrades, treasury, fee updates |
| **Security Admin**   | `"sec_adm"` | Security team       | Emergency pause/unpause of the protocol                                    |
| **Operations Admin** | `"ops_adm"` | Operations team     | Approve/remove pool managers, set credit limits, clear delinquency         |

## Timelock Controller

The Timelock enforces a **minimum delay** on governance operations. This gives protocol participants time to review and react to proposed changes before they take effect.

### Operation Lifecycle

```
Unset → Waiting → Ready → Done
```

1. **Proposer** schedules an operation with a delay
2. The operation enters **Waiting** state
3. After the delay passes, the operation becomes **Ready**
4. **Executor** executes the operation → **Done**

A **Canceller** can cancel any pending operation before execution.

### Admin (Timelock-controlled) actions

The Globals **admin role** is held by the Timelock, so these admin-only actions carry the governance delay:

| Action            | Function               | Impact                                    |
| ----------------- | ---------------------- | ----------------------------------------- |
| Whitelist assets  | `whitelist_asset`      | Enables a token for lending/collateral    |
| Remove assets     | `remove_asset`         | Disables a token                          |
| Update treasury   | `set_treasury_address` | Changes the fee recipient                 |
| Register factory  | `set_factory`          | Authorises the factory to register vaults |
| Upgrade contracts | `upgrade`              | Deploys new contract code                 |

### Non-Timelocked (instant) actions

These are Operations- or Security-Admin actions, executed instantly:

| Action                     | Role           | Function                                       |
| -------------------------- | -------------- | ---------------------------------------------- |
| Pause / unpause            | Security Admin | `pause` / `unpause`                            |
| Approve / remove managers  | Ops Admin      | `approve_pool_manager` / `remove_pool_manager` |
| Set credit limits          | Ops Admin      | `set_manager_credit_limit`                     |
| Clear delinquency          | Ops Admin      | `clear_delinquency`                            |
| **Update global settings** | Ops Admin      | `update_settings`                              |
| **Update protocol fee**    | Ops Admin      | `set_protocol_fee`                             |

{% hint style="warning" %}
**Updating global settings and the protocol fee is an Operations-Admin action and is NOT timelocked** — the Ops Admin can change loan-parameter bounds and the fee instantly. Only the admin-role actions above carry the Timelock delay.
{% endhint %}

## Emergency Powers

The **Security Admin** can pause the entire protocol instantly:

* `pause(caller)` — Halts all state-changing functions protected by `#[when_not_paused]`
* `unpause(caller)` — Resumes normal operation

This is a circuit breaker for emergencies — exploits, critical bugs, or market events that require immediate protocol freeze.

{% hint style="warning" %}
Pausing the protocol prevents new deposits, vault creation, and collateral operations. Existing vaults that are already Active continue to accept payments (the pause is on Globals-level operations).
{% endhint %}

## Self-Administered Timelock

The Timelock is deployed as **self-administered** — it is its own admin. This means:

* No single address can bypass the time delay
* The Timelock's own settings (delay, roles) can only be changed through the Timelock itself
* This creates a fully decentralised governance loop