# Globals Contract

Protocol-wide settings, role management, fee configuration, and pool manager collateral.

**Source:** `contracts/globals/`

## Source Modules

| File           | Purpose                                                         |
| -------------- | --------------------------------------------------------------- |
| `contract.rs`  | All public entry points — settings, role management, collateral |
| `storage.rs`   | Data types, storage keys, getters/setters                       |
| `constants.rs` | Default values (`PROTOCOL_FEE = 50_000` = 0.5% in 7-decimal)    |
| `errors.rs`    | `#[contracterror]` enum                                         |
| `events.rs`    | `#[contractevent]` structs                                      |
| `test.rs`      | 29 tests (11 core + 11 collateral + 7 delinquency/credit)       |

## Roles & Authorisation

| Role           | Key         | Who                 | Can Do                                           |
| -------------- | ----------- | ------------------- | ------------------------------------------------ |
| Admin          | `"admin"`   | Governor / Timelock | Set settings, whitelist assets, upgrade contract |
| Security Admin | `"sec_adm"` | Security team       | Pause/unpause protocol                           |
| Ops Admin      | `"ops_adm"` | Operations team     | Approve/remove pool managers                     |

## GlobalSettings

```rust
GlobalSettings {
    min_interest_rate: u32,        // Minimum annual rate in basis points
    max_loan_term: u32,            // Maximum loan term in months
    min_loan_term: u32,            // Minimum loan term in months
    min_principal: i128,           // Minimum loan amount (7-decimal)
    max_principal: i128,           // Maximum loan amount (7-decimal)
    protocol_fee: i128,            // Fee percentage (7-decimal, 50_000 = 0.5%)
    default_grace_period: u64,     // Grace period in seconds (default 2592000 = 30 days)
    default_collateral_ratio: u32, // Required collateral as % of principal
}
```

## Functions

### Admin-only (`#[only_admin]`)

| Function                                | Description             |
| --------------------------------------- | ----------------------- |
| `set_settings(caller, settings)`        | Update global settings  |
| `add_supported_asset(caller, asset)`    | Whitelist a token       |
| `remove_supported_asset(caller, asset)` | Remove a token          |
| `set_fee(caller, fee)`                  | Update protocol fee     |
| `set_treasury(caller, treasury)`        | Update treasury address |

### Security Admin (`#[only_role(caller, "sec_adm")]`)

| Function          | Description                        |
| ----------------- | ---------------------------------- |
| `pause(caller)`   | Pause all state-changing functions |
| `unpause(caller)` | Resume normal operation            |

### Operations Admin (`#[only_role(caller, "ops_adm")]`)

| Function                                                | Description                          |
| ------------------------------------------------------- | ------------------------------------ |
| `add_pool_manager(caller, manager)`                     | Register a pool manager              |
| `remove_pool_manager(caller, manager)`                  | Remove a pool manager                |
| `approve_pool_manager(manager, caller, max_credit)`     | Activate a manager with credit limit |
| `set_manager_credit_limit(caller, manager, max_credit)` | Update a manager's credit limit      |
| `clear_delinquency(caller, manager)`                    | Clear delinquency flag after review  |

### Collateral (manager-only, `#[when_not_paused]`)

| Function                                       | Description                              |
| ---------------------------------------------- | ---------------------------------------- |
| `deposit_collateral(manager, token, amount)`   | Deposit collateral tokens                |
| `withdraw_collateral(manager, amount)`         | Withdraw unlocked collateral             |
| `lock_collateral(manager, amount)`             | Lock for a new vault (called by Factory) |
| `release_collateral(manager, amount)`          | Release on FullyRepaid (called by Vault) |
| `slash_collateral(manager, amount, recipient)` | Slash on Defaulted (called by Vault)     |
| `get_manager_collateral(manager)`              | View `{ token, staked, locked }`         |
| `get_available_collateral(manager)`            | View `staked − locked`                   |

### Manager Tracking (cross-contract)

| Function                                 | Called By | Description                 |
| ---------------------------------------- | --------- | --------------------------- |
| `mark_delinquent(manager)`               | Vault     | Flag manager on default     |
| `increment_outstanding(manager, amount)` | Factory   | Track new vault principal   |
| `decrement_outstanding(manager, amount)` | Vault     | Release on repayment/expiry |
| `is_delinquent(manager)`                 | Factory   | Check delinquency status    |
| `get_manager(manager)`                   | Any       | View full manager data      |

### Public Queries

| Function                   | Returns                |
| -------------------------- | ---------------------- |
| `get_settings()`           | `GlobalSettings`       |
| `get_fee()`                | Protocol fee           |
| `get_treasury()`           | Treasury address       |
| `get_supported_assets()`   | Whitelisted token list |
| `get_pool_managers()`      | Pool manager list      |
| `is_pool_manager(addr)`    | `bool`                 |
| `is_supported_asset(addr)` | `bool`                 |

## Events

| Event                       | Key Fields                         | When                 |
| --------------------------- | ---------------------------------- | -------------------- |
| `SettingsUpdated`           | `settings`                         | Settings changed     |
| `TreasuryUpdated`           | `treasury`                         | Treasury changed     |
| `PoolManagerAdded`          | `manager`                          | Manager approved     |
| `PoolManagerRemoved`        | `manager`                          | Manager removed      |
| `AssetWhitelisted`          | `asset`                            | Asset added          |
| `AssetRemoved`              | `asset`                            | Asset removed        |
| `ProtocolFeeChanged`        | `new_fee`                          | Fee updated          |
| `ProtocolPaused`            | —                                  | Protocol paused      |
| `ManagerMarkedDelinquent`   | `manager`, `delinquency_count`     | Vault defaulted      |
| `ManagerDelinquencyCleared` | `manager`                          | Delinquency cleared  |
| `ManagerCreditLimitSet`     | `manager`, `max_credit`            | Credit limit updated |
| `ManagerOutstandingUpdated` | `manager`, `outstanding_principal` | Outstanding changed  |

## Storage Design

All global settings are stored in **instance storage** with TTL extension (\~30 day threshold, \~31 day bump). Pool managers stored as `Vec<Address>` under `DataKey::PoolManagers`. Supported assets as `Vec<Address>` under `DataKey::SupportedAssets`. Treasury stored under `DataKey::Treasury`.


---

# Agent Instructions: 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:

```
GET https://docs.trilobyte.finance/technical-documentation/globals-contract.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.