> 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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.trilobyte.finance/protocol-mechanics/governance.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.