Modules

Architecture

Explains the technical architecture, data flow, and design principles.

Path: architecture

Third-party documentation. This is independently authored analysis of the public Aurum Protocol codebase — not the official docs, and not reviewed or endorsed by the Aurum Protocol team.

System Architecture

Aurum is built on a hub-and-spoke model. The Core module holds shared state; all market modules speak to Core through a standardised interface, never directly to each other.

Design Principles

Single-responsibility modules — each contract owns one concern.
Fail-safe defaults — every state-changing path has a fallback revert.
Event-first telemetry — subgraph indexers receive real-time updates through structured events.
Deterministic state transitions — no block-timestamp dependency for security-critical paths.

Data Flow

User calls a market module (Lending, Vaults, Payments…)
Module reads/writes Core state after validating invariants
Oracle is queried inline for any USD-denominated check
Liquidation can be triggered by any external keeper when health-factor < 1
Events emitted → subgraph updated → frontend reflects new state

System Diagram

User

Frontend

Lending

Vaults

Trading

Liquidation

Core

Oracle

Data / Storage

Examples

Read a vault's current state

typescript

const vault = await core.getVault(userAddress);
console.log("Collateral:", ethers.formatEther(vault.collateral));
console.log("Debt:      ", ethers.formatEther(vault.debt));

STATUSexample

Fetch the on-chain vault struct for any address.

Check health factor before borrowing

typescript

const hf = await core.healthFactor(userAddress);
if (hf < ethers.parseEther("1.2")) {
  throw new Error("Health factor too low — borrow rejected");
}

STATUSexample

Always check health factor before submitting a borrow transaction.

Edge Cases

healthFactor returns type(uint256).max for accounts with zero debt
updateCollateral reverts if the resulting balance would breach minimum collateral ratio
Re-entrant calls to Core are blocked by a ReentrancyGuard modifier

Interface

solidity

interface ICore {
    /// @notice Returns the on-chain vault record for a user
    function getVault(address user) external view returns (Vault memory);
 
    /// @notice Atomically updates a user's collateral balance
    function updateCollateral(address user, int256 delta) external;
 
    /// @notice Returns the current health-factor scaled to 1e18
    function healthFactor(address user) external view returns (uint256);
 
    event CollateralUpdated(address indexed user, int256 delta, uint256 newBalance);
}

STATUSinterface