Globals Contract

Protocol-wide settings, role management, fee configuration, pool-manager collateral, manager credit/delinquency tracking, and the Factory + vault registry.

Source: contracts/globals/

Source Modules

File	Purpose
contract.rs	All public entry points — settings, roles, collateral, delinquency/credit, Factory/vault registration
storage.rs	Data types (GlobalSettings, Manager, ManagerCollateral), storage keys, getters/setters
constants.rs	Default values (PROTOCOL_FEE = 50_000 = 0.5% in 7-decimal)
errors.rs	#[contracterror] enum
events.rs	#[contractevent] structs
test.rs	29 tests (core settings + collateral + delinquency/credit)

Roles & Authorisation

Roles use OpenZeppelin Access Control. The admin is the governor set at construction (later transferred to the Timelock). sec_adm and ops_adm are granted at construction.

Role	Key	Who	Can Do
Admin	(OZ admin)	Governor / Timelock	whitelist_asset, remove_asset, set_treasury_address, set_factory, register_vault*, upgrade, two-step admin transfer
Security Admin	"sec_adm"	Security team	pause / unpause
Ops Admin	"ops_adm"	Operations team	approve_pool_manager, remove_pool_manager, set_protocol_fee, update_settings, set_manager_inactive, set_manager_credit_limit, clear_delinquency

* register_vault is admin-defined but additionally requires the call to come from the registered Factory (it re-checks factory.require_auth()).

whitelist_asset / remove_asset / set_treasury_address / set_factory use the #[only_admin] macro. The pool-manager, fee, settings, and delinquency functions use #[only_role(caller, "ops_adm")]. pause / unpause use #[only_role(caller, "sec_adm")].

GlobalSettings

The settings struct has 21 fields (no addresses or paused state — those live in OZ storage):

GlobalSettings {
    protocol_fee: i128,             // Fee (7-decimal, 50_000 = 0.5%)
    min_interest_rate: u32,         // Min annual rate, basis points
    max_interest_rate: u32,         // Max annual rate, basis points
    min_loan_term: u32,             // Min loan term, months
    max_loan_term: u32,             // Max loan term, months
    default_grace_period: u32,      // Default grace period (days)
    default_risk_tolerance: u32,    // Default-after % missed payments
    default_collateral_ratio: u32,  // Manager collateral as % of principal
    min_collateral_value: i128,     // Min collateral value (7-decimal)
    one_day: u64,                   // Seconds in a day
    one_year: u64,                  // Seconds in a 360-day year
    days_in_year_30_360: u32,       // 360
    days_in_month_30_360: u32,      // 30
    monthly_emi_interval: u64,      // EMI interval (seconds)
    default_penalty_rate_bps: u32,  // Penalty rate (1800 = 18% p.a.)
    min_emi_tolerance: u32,         // Min % of EMI to avoid penalty
    token_decimals: u32,            // 7
    min_loan_amount: i128,          // Minimum loan amount (7-decimal)
    max_loan_amount: i128,          // Maximum loan amount (7-decimal)
    default_timelock_delay: u64,    // Default timelock delay (ledgers)
    default_timelock_duration: u64, // Default timelock duration (ledgers)
}

The min/max loan bounds are named min_loan_amount / max_loan_amount (not min_principal / max_principal). Timelock delay/duration are measured in ledgers (~5 s/ledger), not seconds.

Functions

Admin-only (#[only_admin])

Function	Description
set_treasury_address(new_treasury)	Update the treasury address (the new treasury must also require_auth)
whitelist_asset(asset)	Whitelist a lending/collateral token
remove_asset(asset)	Remove a token from the whitelist
set_factory(factory)	Register the Factory address (required before vault creation works)
register_vault(vault)	Mark a vault as trusted (Factory-gated)
upgrade(new_wasm_hash, operator)	Upgrade the contract (auth via stored admin)

Two-step admin transfer (OZ Access Control)

Function	Description
transfer_admin_role(new_admin, live_until_ledger)	Initiate admin transfer; pending until accepted or live_until_ledger
accept_admin_transfer()	New admin accepts the pending transfer
renounce_admin()	Current admin renounces
Plus OZ role functions: grant_role, revoke_role, renounce_role, has_role, get_role_admin, set_role_admin, get_role_member, get_role_member_count, get_admin, get_existing_roles

Security Admin (#[only_role(caller, "sec_adm")])

Function	Description
pause(caller)	Pause all #[when_not_paused] functions
unpause(caller)	Resume normal operation

Operations Admin (#[only_role(caller, "ops_adm")])

Function	Description
approve_pool_manager(manager, caller, max_credit)	Approve a manager with a credit limit (returns the Manager)
remove_pool_manager(manager_address, caller)	Remove a manager
set_protocol_fee(fee, caller)	Update the protocol fee
update_settings(settings, caller)	Replace the full GlobalSettings struct
set_manager_inactive(manager_address, caller)	Deactivate a manager
set_manager_credit_limit(manager, max_credit, caller)	Update a manager's credit limit
clear_delinquency(manager, caller)	Clear a manager's delinquency record after review

Collateral (manager / cross-contract, #[when_not_paused])

Function	Auth	Description
deposit_collateral(manager, token, amount)	Manager	Stake collateral (manager must be active, token whitelisted, single token per manager)
withdraw_collateral(manager, amount)	Manager	Withdraw unlocked collateral (staked − locked)
lock_collateral(manager, amount)	Factory	Lock collateral on vault creation
release_collateral(caller, manager, amount)	Registered Vault	Release on full repayment / cancellation
slash_collateral(caller, manager, amount, recipient)	Registered Vault	Slash on default, transfer to recipient
get_manager_collateral(manager)	Any	View { token, staked, locked }
get_available_collateral(manager)	Any	View staked − locked

Manager credit & delinquency tracking (cross-contract)

Function	Called By	Description
mark_delinquent(caller, manager)	Vault	Increment delinquency count on default
clear_delinquency(manager, caller)	Ops Admin	Reset delinquency count
increment_outstanding(manager, amount)	Factory	Track new vault principal against credit
decrement_outstanding(caller, manager, amount)	Vault	Release principal on repayment / default / expiry
is_delinquent(manager)	Any	Whether the manager has any uncleared default
get_manager(manager)	Any	Full Manager record (Option)

Public Queries

Function	Returns
get_global_settings()	GlobalSettings
get_treasury_address()	Treasury address
get_supported_assets()	Whitelisted token list
list_pool_managers()	Vec<Manager>
paused()	bool

Events

Event	Key Fields	When
RoleUpdated	role, new_address	Treasury (or other role address) updated
ProtocolPaused	paused	Paused / unpaused
ManagerApproved	manager	Manager approved
ManagerRemoved	manager	Manager removed
AssetWhitelisted	asset	Asset added
AssetRemoved	asset	Asset removed
FeeUpdated	new_fee	Protocol fee updated
CollateralDeposited	manager, token, amount, total_staked	Manager stakes collateral
CollateralWithdrawn	manager, amount, total_staked	Manager withdraws collateral
CollateralLocked	manager, amount, total_locked	Collateral locked for a vault
CollateralReleased	manager, amount, total_locked	Collateral released
CollateralSlashed	manager, amount, remaining_staked	Collateral slashed on default
ManagerMarkedDelinquent	manager, delinquency_count	Vault defaulted
ManagerDelinquencyCleared	manager	Delinquency cleared
ManagerCreditLimitSet	manager, max_credit	Credit limit set/updated
ManagerOutstandingUpdated	manager, outstanding_principal	Outstanding principal changed

Storage Design

GlobalSettings, treasury, the Factory address, supported assets, pool managers, and per-manager collateral are stored in instance storage with TTL extension (~30-day threshold, ~31-day bump). Registered vaults are stored in persistent storage keyed by vault address, with a TTL clamped to the network maximum (max_ttl()).