> 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" ``` --- # 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/technical-documentation/architecture.md?ask=&goal= ``` `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.