> 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/technical-documentation/architecture.md).

# Smart Contract Architecture

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

## Contract Diagram

```mermaid
flowchart TB
    T["Timelock\n(OZ TimelockController)\nProposer / Executor / Canceller\nAdmin of Globals"] -->|admin| GL
    GL["Globals\n(OZ Access + Pausable + Upgradeable)\nSettings · Roles · Fees · Assets\nManager collateral · Exposure tracking\nCompliance gate pointer"]
    GL -->|validates via| F["Factory\ndeploys vaults"]
    F -->|creates| V["Vault(s)\none per loan, two tranches\nSEP-41 debt token"]
    V -->|lock / release / seize\nborrower pledges| E["CollateralEscrow\n(shared, generic custody)"]
    CA["ComplianceAllowlist\nis_allowed(who, action)"] -.->|optional: Globals.compliance_gate| GL
    W["WebAuth\n(standalone)\nSEP-45 challenge verification"]
```

`WebAuth` is standalone — it is not part of the lending call graph above; it's consumed directly by the auth server for passkey sign-in.

## Contracts Overview

| Contract                | Purpose                                                                                                                                                                                                             | Key OZ Modules                                       |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| **Globals**             | Protocol settings, roles, fees, asset + collateral-asset whitelists, manager collateral, manager credit/delinquency tracking, borrower/manager exposure tracking, compliance-gate pointer, Factory & vault registry | Access Control, Pausable, Upgradeable                |
| **Factory**             | Deploys and registers vaults, validates parameters (including leverage and exposure caps) against Globals                                                                                                           | Access Control, Upgradeable                          |
| **Vault**               | Per-loan contract — two-tranche capital raise, six-bucket payment waterfall, default recovery, NAV write-down, covenants, renegotiation, debt tokens                                                                | FungibleToken, FungibleBurnable, Capped, Upgradeable |
| **CollateralEscrow**    | Shared custody for borrower-posted collateral (RWA certificates, fungible tokens) across all loans; `lock` / `release` / `seize` driven by the controlling vault                                                    | Upgradeable                                          |
| **ComplianceAllowlist** | First implementation of the optional protocol-wide compliance gate (`is_allowed(who, action)`)                                                                                                                      | Access Control, Upgradeable                          |
| **Timelock**            | Governance delay on critical actions; can be the enforced admin for upgrades once `require_timelock_admin` is set                                                                                                   | TimelockController                                   |
| **WebAuth**             | SEP-45 web-authentication challenge verification for passkey sign-in                                                                                                                                                | —                                                    |

## Two Collateral Systems

Trilobyte has **two independent collateral mechanisms**:

1. **Pool-manager (skin-in-the-game) collateral** — lives in **Globals**. The pool manager who underwrites a vault stakes collateral; the Factory locks it on vault creation (crediting it toward the vault's junior tranche target), the Vault releases it on full repayment and slashes it into the recovery pool on default, senior-first.
2. **Borrower-posted collateral** — lives in **CollateralEscrow**. Optional per loan. The borrower pledges an asset (e.g. an RWA certificate) naming the vault as controller; the Vault verifies the pledge at disbursement, releases it to the borrower on full repayment, and seizes it to a recovery party on default — ahead of manager collateral in the recovery order.

Both use assets from Globals' **collateral asset whitelist**, a separate list from the assets that can be lent.

## OpenZeppelin Stellar Contracts (v0.7.2)

| OZ Module             | Crate                    | Used In                                                                  | Purpose                                                                                                                                                                                       |
| --------------------- | ------------------------ | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Access Control (RBAC) | `stellar-access`         | Globals, Vault, Factory, Timelock, CollateralEscrow, ComplianceAllowlist | `#[only_admin]`, `#[only_role(caller, "sec_adm")]`, `#[only_role(caller, "ops_adm")]` macros; two-step admin transfer                                                                         |
| Pausable              | `stellar-contract-utils` | Globals (checked cross-contract by Vault)                                | `#[when_not_paused]` macro. Wind-down paths (`release_collateral`, `slash_collateral`, `mark_delinquent`, `decrement_outstanding`, `check_default`, `claim_recovery`) are deliberately exempt |
| Upgradeable           | `stellar-contract-utils` | Globals, Vault, Factory, CollateralEscrow, ComplianceAllowlist           | `#[derive(Upgradeable)]` with admin-authorised upgrades, hardened to require the timelock once `require_timelock_admin` is set                                                                |
| FungibleToken         | `stellar-tokens`         | Vault                                                                    | SEP-41 debt token with `FungibleBurnable` + `Capped`                                                                                                                                          |
| Timelock Controller   | `stellar-governance`     | Timelock                                                                 | Operation lifecycle (Unset → Waiting → Ready → Done); delays in **ledger sequence numbers**                                                                                                   |

## Tech Stack

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

## Shared Types (`common-types`)

Every contract that calls another contract imports shared `#[contracttype]` definitions (`GlobalSettings`, `Manager`, `ManagerCollateral`, `Pledge`, `VaultParams`) and `#[contractclient]` traits from a single `common-types` crate, rather than hand-mirroring them. See [Common Types and Events](/technical-documentation/common-types-and-events.md) for why this matters and the full event catalogue.

## Test Suite

See `cargo test --workspace` for the exact current count across all 7 packages — the tranched-waterfall change added substantially more coverage than the prior protocol version:

| Package             | Coverage                                                                                                                                                                                                                                                                                                             |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Globals             | Core settings, roles, collateral, delinquency tracking, credit limits, settings/fee validation bounds (incl. tranche settings), borrower/total outstanding tracking, compliance gate, trilo event-topic shape                                                                                                        |
| Vault               | Tranche capital raise, `lock_junior` threshold credit, worked-example waterfall (exact stroop values) and short-payment/arrears carry, default with/without a borrower pledge, distribute/claim recovery, NAV write-down, reporting + cash-pool covenants, renegotiation, allowlist, deadline expiry, pause coverage |
| Timelock            | Lifecycle, scheduling, execution, cancellation, Globals integration                                                                                                                                                                                                                                                  |
| Factory             | Vault deployment, validation, registry, leverage-cap and borrower/manager exposure-cap unit tests                                                                                                                                                                                                                    |
| CollateralEscrow    | Lock/release/seize, per-pledge accounting griefing regression, clawback robustness, controller-auth enforcement                                                                                                                                                                                                      |
| ComplianceAllowlist | Default-deny, grant/revoke, per-action and per-address independence, admin-auth enforcement                                                                                                                                                                                                                          |
| WebAuth             | SEP-45 challenge verification happy path and rejection cases                                                                                                                                                                                                                                                         |

## Cargo Dependencies

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

*As of September 2026.*