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

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