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
Security	OpenZeppelin Stellar Contracts v0.7.2
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

[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"