Skip to content

architecture.md

Latest commit

 

History

History
114 lines (92 loc) · 4.61 KB

architecture.md

File metadata and controls

114 lines (92 loc) · 4.61 KB

Architecture

Data Flow

  Solana Mainnet (RPC)
         |
         | getProgramAccounts, getAccountInfo
         |
  +------v-------+
  |  FlashDecoder |  Account deserialization via Anchor IDL
  |  decoder.ts   |  Rate-limit-aware batched fetching
  +------+-------+
         |
         | Typed account structs:
         | PoolAccount, CustodyAccount, MarketAccount,
         | PositionAccount, CustomOracleAccount
         |
  +------v-------+     +-------------+
  | risk-engine  |<----| oracle.ts   |  Oracle price range, exit pricing,
  | .ts          |     |             |  trade spread, lock fee computation
  |              |     +-------------+
  | Per-position:|
  | - PnL        |     +-------------+
  | - Margin     |<----| guards.ts   |  Runtime invariant assertions
  | - Leverage   |     +-------------+
  | - Liquidation|
  +------+-------+
         |
         | PositionRisk[]
         |
  +------v-------+
  | metrics.ts   |  Aggregation:
  |              |  - Liquidation density map
  |              |  - Leverage distribution histogram
  |              |  - Utilization monitoring
  |              |  - Borrow rate forecasting
  |              |  - Risk summary statistics
  +------+-------+
         |
         | RiskSummary, LiquidationBucket[],
         | LeverageBucket[], UtilizationInfo
         |
  +------v-------+
  | cli.ts       |  Output:
  |              |  - Phased terminal output
  |              |  - Audit verification snapshot
  |              |  - Post-run sanity checks
  |              |  - Live snapshot summary
  +--------------+

Separation of Pure Math from I/O

The engine enforces a strict boundary between I/O and computation:

I/O Layer (side effects)

  • decoder.ts -- RPC calls, Anchor deserialization, rate limiting
  • subscriber.ts -- WebSocket subscriptions, event callbacks
  • cli.ts -- Console output, argument parsing, file system reads (audit mode IDL hash)

Pure Computation Layer (no side effects)

  • risk-engine.ts -- All functions are pure. Given the same inputs, they produce the same outputs. No network calls, no console output, no global state.
  • oracle.ts -- Pure functions for price banding, exit pricing, spread interpolation, lock fee accumulation.
  • metrics.ts -- Pure aggregation over PositionRisk[] arrays.
  • guards.ts -- Pure assertion functions. The only side effect is throwing on violation.

This separation means the computation layer can be tested, audited, and reasoned about independently of the I/O layer.

Guard Layer

Guards are integrated at five critical points:

Guard Location Invariant
assertNonNegativeMargin computeMargin() Margin >= 0 after clamping
assertNonZeroDivisor computeLeverage(), computeExitPrice() No division by zero
assertLeverageInBps computeLeverage() Leverage in sane range (0 to 10,000x)
assertOracleExponentDynamic getOraclePriceRange() Exponent read from oracle, not hardcoded
assertBorrowRateBound computeBorrowRate() Rate <= base + slope1 + slope2

Guards never fire under normal operation. They exist to catch:

  • Corrupted on-chain account data
  • Engine bugs introduced by refactoring
  • Unexpected oracle configurations

assessPositionRisk() wraps the entire computation in a try/catch that re-throws with position context (address, side, size) for fast debugging.

Audit Mode

When invoked with --audit, the engine:

  1. Fetches all on-chain state (same as normal mode)
  2. Computes SHA-256 of the IDL file used for deserialization
  3. Outputs every computed value in three formats: raw | scaled | human
  4. Selects the highest-leverage position and traces every computation step
  5. Lists all values that cannot be verified against production
  6. Exits without running the full engine output

This mode is designed for independent review. Every number can be cross-checked against on-chain data using a block explorer or direct RPC queries.

Execution Phases

Normal mode executes five sequential phases:

  1. Source Verification -- Program ID, IDL version, RPC endpoint
  2. Parameter Extraction -- Fetch pools, custodies, markets, oracles. Display custody parameters.
  3. Risk Engine -- Fetch positions. Assess per-position risk. Compute summary, density map, leverage distribution.
  4. Utilization Metrics -- Per-custody utilization and borrow rate forecasting.
  5. Sanity Checks + Summary -- Automated invariant validation. Final risk snapshot with natural-language summary.

Each phase depends on data from previous phases. WebSocket subscription (optional) runs as a sixth phase that keeps the process alive for real-time monitoring.