# Smart Contract Architecture

Trilobyte is composed of four smart contracts deployed on Stellar's Soroban platform, built with OpenZeppelin Stellar Contracts for battle-tested security.

## Contract Diagram

```
┌───────────────────────────────────────────────┐
│                  Timelock                      │
│        (OZ TimelockController)                │
│   Proposer / Executor / Canceller roles       │
│   Admin of Globals (governor actions delayed) │
└──────────────────────┬────────────────────────┘
                       │ admin
┌──────────────────────▼────────────────────────┐
│                   Globals                      │
│          (OZ Access + Pausable + Upgradeable)  │
│   Settings · Roles · Fees · Assets · Managers  │
│   Pool Manager Collateral (deposit/lock/slash) │
└─────────┬─────────────────────────┬───────────┘
          │                         │
    ┌─────▼─────┐           ┌──────▼──────┐
    │  Factory   │──creates──►   Vault(s)  │
    │            │           │ (per-loan)  │
    │ Validates  │           │ SEP-41 Token│
    │ via Globals│           │ OZ Fungible │
    └───────────┘           └─────────────┘
```

## Contracts Overview

| Contract     | Purpose                                                             | Key OZ Modules                                       |
| ------------ | ------------------------------------------------------------------- | ---------------------------------------------------- |
| **Globals**  | Protocol settings, roles, fees, asset whitelist, manager collateral | Access Control, Pausable, Upgradeable                |
| **Factory**  | Deploys and registers vaults, validates parameters                  | —                                                    |
| **Vault**    | Per-loan contract — lifecycle, payments, yield, debt tokens         | FungibleToken, FungibleBurnable, Capped, Upgradeable |
| **Timelock** | Governance delay on critical actions                                | TimelockController                                   |

## OpenZeppelin Stellar Contracts (v0.6.0)

| OZ Module             | Crate                    | Used In        | Purpose                                                                                      |
| --------------------- | ------------------------ | -------------- | -------------------------------------------------------------------------------------------- |
| Access Control (RBAC) | `stellar-access`         | Globals        | `#[only_admin]`, `#[only_role(caller, "sec_adm")]`, `#[only_role(caller, "ops_adm")]` macros |
| Pausable              | `stellar-contract-utils` | Globals        | `#[when_not_paused]` / `#[when_paused]` macros                                               |
| Upgradeable           | `stellar-contract-utils` | Globals, Vault | `#[derive(Upgradeable)]` with governor-authorised upgrades                                   |
| FungibleToken         | `stellar-tokens`         | Vault          | SEP-41 compliant debt token with `FungibleBurnable` + `Capped`                               |
| Timelock Controller   | `stellar-governance`     | Timelock       | Operation lifecycle (Unset→Waiting→Ready→Done)                                               |

## Tech Stack

| Component            | Technology                                                                               |
| -------------------- | ---------------------------------------------------------------------------------------- |
| Smart Contracts      | Rust + [Soroban SDK v23.5.2](https://soroban.stellar.org/)                               |
| Security             | [OpenZeppelin Stellar Contracts v0.6.0](https://docs.openzeppelin.com/stellar-contracts) |
| Blockchain           | Stellar (Soroban smart contract platform)                                                |
| Deployment           | TypeScript + `@stellar/stellar-sdk`                                                      |
| Day-Count Convention | 30/360 (standard in traditional finance)                                                 |
| Token Precision      | 7 decimal places (Stellar standard)                                                      |
| EMI Math             | Fixed-point integer arithmetic (10¹² internal precision, no floats)                      |

## Test Suite

115 tests across 4 packages:

| Package  | Tests | Coverage                                                                                                                                               |
| -------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Globals  | 29    | Core settings, roles, collateral, delinquency tracking, credit limits                                                                                  |
| Vault    | 69    | Lifecycle, deposits, withdrawals, payments, yield, debt tokens, risk/default, renegotiation, collateral integration, protocol fees, allowlist, upgrade |
| Timelock | 14    | Lifecycle, scheduling, execution, cancellation, Globals integration                                                                                    |
| Factory  | 3     | Vault deployment, validation, registry                                                                                                                 |

## Cargo Dependencies

```toml
[workspace.dependencies]
soroban-sdk = "23.5.2"
stellar-access = "=0.6.0"
stellar-contract-utils = "=0.6.0"
stellar-macros = "=0.6.0"
stellar-tokens = "=0.6.0"
stellar-governance = "=0.6.0"
```


---

# 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/architecture.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.