Deployment

Trilobyte contracts are deployed to Stellar with a TypeScript script that drives the stellar CLI (@stellar/stellar-sdk is used for keypair/address handling).

Full Protocol Deployment

The main deployment script is scripts/deploy-protocol.ts. It deploys the four governance/registry contracts and runs post-deploy initialisation. (The CollateralEscrow is deployed separately, per RWA-collateral lender — it is not part of the core protocol deploy.)

Step 1 — Deploy Globals

Globals(governor, treasury, security_admin, operations_admin)

Globals is deployed first. governor becomes the OZ admin; security_admin and operations_admin are granted their roles in the constructor.

Step 2 — Deploy Timelock

Timelock(min_delay, proposers, executors, admin: None)

Self-administered. min_delay is in ledgers. Proposers are also granted the canceller role; an empty executor list means anyone can execute.

Step 3 — Upload Vault WASM

The compiled vault WASM is uploaded (stellar contract upload), returning a WASM hash used by the Factory to deploy vault instances.

Step 4 — Deploy Factory

Factory(governor, globals_address, vault_wasm_hash)

Step 5 — Register the Factory in Globals (MANDATORY)

globals.set_factory(factory_address)

This step is required. Globals gates lock_collateral, increment_outstanding, and register_vault on the call coming from the registered Factory. Until set_factory has been called, create_vault fails when it tries those cross-contract calls — no vault can be created. set_factory is #[only_admin], so it must run before admin is transferred to the Timelock.

Step 6 — Whitelist Assets

globals.whitelist_asset(asset)

Must be done before transferring Globals admin to the Timelock, since it requires direct admin access.

Step 7 — Approve Initial Managers

globals.approve_pool_manager(manager_address, caller, max_credit)

A single call both registers and approves a manager (there is no separate add_pool_manager). caller must hold the ops_adm role.

Step 8 — Transfer Globals Admin to the Timelock

Globals uses the OZ two-step admin transfer:

globals.transfer_admin_role(timelock_address, live_until_ledger)   // current admin initiates
globals.accept_admin_transfer()                                     // the Timelock accepts

live_until_ledger bounds when the pending transfer expires (0 cancels it). After acceptance, all admin-gated operations on Globals must go through the Timelock's governance process.

This step is effectively irreversible. Once admin is the Timelock, direct admin access is gone. Ensure set_factory, asset whitelisting, and manager approval are all complete first.

Deploy-script discrepancy (verify before running). As of this writing scripts/deploy-protocol.ts calls a single transfer_admin (one-step) for step 8. The deployed Globals contract exposes only the OZ two-step transfer_admin_role / accept_admin_transfer — there is no transfer_admin function. The single call will fail. Use transfer_admin_role(new_admin, live_until_ledger) followed by accept_admin_transfer().

Running the Deployment

# Build all contracts (WASM target wasm32v1-none)
stellar contract build

# Deploy the full protocol
npx ts-node scripts/deploy-protocol.ts

Configuration

All deployment parameters are configured via environment variables. See .env.example:

Variable	Description
SOROBAN_NETWORK	Network to deploy to (testnet / mainnet)
NETWORK_RPC_URL	Soroban RPC endpoint
NETWORK_PASSPHRASE	Network passphrase
NETWORK_HORIZON_URL	Horizon endpoint
WASM_TARGET_DIR	Build output dir (default target/wasm32v1-none/release)
SOURCE_SECRET_KEY	Secret key for the deploying account
GOVERNOR_ADDRESS	Initial governor (root admin of Globals)
TREASURY_ADDRESS	Protocol treasury address
SECURITY_ADMIN_ADDRESS	Security admin address
OPERATIONS_ADMIN_ADDRESS	Operations admin address
TIMELOCK_MIN_DELAY	Minimum delay for timelocked operations (ledgers)
TIMELOCK_PROPOSERS	Comma-separated proposer addresses (≥ 1 required)
TIMELOCK_EXECUTORS	Comma-separated executor addresses (empty ⇒ anyone)
WHITELIST_ASSETS	Comma-separated asset addresses to whitelist
INITIAL_MANAGERS	Comma-separated manager addresses to approve
MANAGER_CREDIT_LIMIT	Credit limit applied to initial managers (7-decimal)
STELLAR_CLI_PATH	(optional) Absolute path override for the stellar CLI

The deployer secret is passed to the CLI via the STELLAR_ACCOUNT / STELLAR_SIGN_WITH_KEY environment variables (never on argv), and the stellar CLI path is resolved on a sanitised PATH to prevent PATH-hijack.

Output

Deployment results are saved to .soroban/contract-ids.json:

{
  "network": "testnet",
  "deployedAt": "2026-02-27T12:00:00Z",
  "contracts": {
    "globals": "CABC...",
    "timelock": "CDEF...",
    "factory": "CGHI..."
  },
  "vaultWasmHash": "abc123..."
}