> 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 five 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 + Vault registry │ └─────────┬─────────────────────────┬───────────┘ │ │ ┌─────▼─────┐ ┌───────▼──────┐ │ Factory │──creates──► Vault(s) │ │ │ │ (per-loan) │ │ Validates │ │ SEP-41 Token │ │ via Globals│ │ OZ Fungible │ └───────────┘ └──────┬───────┘ │ lock / release / seize │ borrower-posted collateral ┌──────▼─────────┐ │ CollateralEscrow│ │ (RWA pledges) │ └─────────────────┘ ``` ## Contracts Overview | Contract | Purpose | Key OZ Modules | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | **Globals** | Protocol settings, roles, fees, asset whitelist, manager collateral, manager credit/delinquency tracking, Factory & vault registry | Access Control, Pausable, Upgradeable | | **Factory** | Deploys and registers vaults, validates parameters against Globals | Access Control, Upgradeable | | **Vault** | Per-loan contract — lifecycle, payments, yield, debt tokens, collateral release/slash/seize | FungibleToken, FungibleBurnable, Capped, Upgradeable | | **Timelock** | Governance delay on critical actions | TimelockController | | **CollateralEscrow** | Custodies borrower-posted collateral (RWA certificates, fungible tokens) per loan; `lock` / `release` / `seize` driven by the controlling vault | — | ## 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 `principal × collateral_ratio / 100` on vault creation, the Vault releases it on full repayment and slashes it to investors on default. 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. ## OpenZeppelin Stellar Contracts (v0.7.2) | OZ Module | Crate | Used In | Purpose | | --------------------- | ------------------------ | ----------------------- | --------------------------------------------------------------------------------------------------------------------- | | Access Control (RBAC) | `stellar-access` | Globals, Factory, Vault | `#[only_admin]`, `#[only_role(caller, "sec_adm")]`, `#[only_role(caller, "ops_adm")]` macros; two-step admin transfer | | Pausable | `stellar-contract-utils` | Globals | `#[when_not_paused]` macro | | Upgradeable | `stellar-contract-utils` | Globals, Factory, Vault | `#[derive(Upgradeable)]` with admin-authorised upgrades | | FungibleToken | `stellar-tokens` | Vault | SEP-41 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 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) | | EMI Math | Fixed-point integer arithmetic (10¹² internal precision, no floats) | ## Test Suite 140 tests across 5 packages: | Package | Tests | Coverage | | ----------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Globals | 29 | Core settings, roles, collateral, delinquency tracking, credit limits | | Vault | 83 | 64 contract + 19 math tests — lifecycle, deposits, withdrawals, payments, yield, debt tokens, risk/default, renegotiation, manager + borrower collateral, protocol fees, allowlist, upgrade | | Timelock | 14 | Lifecycle, scheduling, execution, cancellation, Globals integration | | Collateral Escrow | 11 | Lock / release / seize, clawback handling, controller auth | | Factory | 3 | Vault deployment, validation, registry | ## 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" ```