NEXUS-120Engine
A deterministic evaluation engine that reads live chain state, runs sovereignty pillar logic, and produces cryptographically hashed execution records. Every output is reproducible. Every record is independently verifiable.
The evaluation cycle
Each engine run follows five deterministic steps. The same chain state always produces the same verdict. There is no configurable behavior, no manual override, and no hidden state.
ArbitrumAdapter calls the deployed contracts via Arbitrum Sepolia RPC.OracleModule.getPrice() — returns ETH/USD price. Reverts if the feed is outside the maxDelay freshness window. On revert, the engine falls back to AggregatorV3Interface.latestRoundData() directly on the Chainlink feed and sets oracle_stale: true.VaultManager.collateralOf() and debtOf() are called via multicall for every known vault owner. Vault owner addresses are derived from Deposit event logs. NXUSDToken.totalSupply() returns total outstanding protocol debt. Protocol thresholds (minCollateralRatioBps, liquidationRatioBps) are read from VaultManager. The result is a complete chain state snapshot anchored to a specific block number.
From the raw chain reads, the engine computes protocol-wide and per-vault metrics. Protocol CR: (total_collateral_eth × eth_price_usd) / total_debt_nxusd. Per-vault CR computed identically for each position. Oracle state is set to stale if OracleModule reverted, with price sourced from Chainlink fallback. All derived values are deterministic — no rounding ambiguity, no randomness.
Pillar runners execute sequentially against the computed metrics. SOV_001 checks: CR > 100% AND VaultManager.paused() === false under distress. SOV_003 checks: CR > 130% AND oracle_stale === false. SOV_003 failures are classified into economic, structural, or testnet_env categories. SOV_005 runs a 5-year forward stress lattice across 5,000+ scenarios on five axes. Each pillar runner is stateless — it reads inputs, evaluates conditions, and returns a verdict. No shared state between runners.
The overall verdict is derived deterministically from pillar results. The aggregation logic is non-configurable and has no exceptions: SOV_001 FAIL → overall_verdict: "FAIL" regardless of other pillars. SOV_001 PASS + SOV_003 FAIL → overall_verdict: "WARN". All passing → overall_verdict: "PASS". SOV_005 result is recorded in the AUD_001 package but does not affect overall_verdict. A WARN verdict is degraded, not insolvent — SOV_001 passing means the primary solvency invariant is intact.
The engine assembles the canonical AuditPackage JSON containing all chain state inputs and all pillar outputs. SHA-256 is computed over the complete canonical JSON. Both the package and the hash are committed atomically to NEXUS120-Official/nexus-receipts/packages/ via GitHub Actions. Once committed, the package cannot be modified without producing a detectable hash mismatch. The package is then accessible via /receipts and the /api/receipts endpoint.
Three output surfaces
Engine outputs are exposed through three distinct surfaces. Each has a different source of truth, freshness model, and trust profile. All are independently accessible without authentication.
isLiquidatable() not called — avoids oracle revert. Status derived from CR thresholds only.AUD_001 package pipeline
A receipt is not a log entry. It is a deterministic execution snapshot: inputs the engine received, outputs it produced, and a hash that binds both together. The same inputs always produce the same hash.
The canonical source of truth is the GitHub repository — not this API. Any discrepancy between this interface and the repository is detectable via hash comparison. Audit Evidence Layer →
Five rules. No exceptions.
Each pillar is a stateless runner: it receives chain state, evaluates conditions, and returns a verdict. No runner can modify the chain state it reads. No runner can influence another runner's inputs.
The primary solvency invariant. Evaluates whether the protocol is in a solvent operating state. A SOV_001 failure is a protocol emergency — integrations that depend on protocol solvency must halt immediately.
Six hardened attack scenarios evaluated on a separate cycle. Each scenario produces a signed rejection record if the attack vector is active or unmitigated. Designed to detect governance capture, oracle manipulation, and replay vectors before they reach execution.
Capital buffer enforcement. Requires CR above the liquidation threshold and a live oracle. Failures are classified into three categories so that environmental conditions on testnet do not mask real economic risk. Only economic failures indicate actual protocol stress.
4-tranche waterfall integrity check: OPERATING, LIQUID, CORE, BACKSTOP. Evaluates treasury health and outflow eligibility. An outflow freeze is triggered automatically on treasury failure — no redemption is permitted during an active freeze.
5-year forward stress simulation run against live protocol state on each evaluation cycle. Evaluates protocol survival across 5,000+ scenario combinations on five stress axes simultaneously. A PASS means the protocol survives all simulated scenarios above the defined safety threshold.
Presentation layer above all pillar runners. Reads the latest SOV_001, SOV_003, and SOV_005 outputs, assembles the canonical AuditPackage JSON, computes the SHA-256 hash, and commits to the public repository. AUD_001 never modifies runner output — it assembles and hashes what the runners produced.
Same inputs. Same outputs. Always.
Four contracts. One read surface.
The engine reads these contracts on every evaluation cycle. All are deployed on Arbitrum Sepolia and callable directly via eth_call — no wallet or auth required. Verified source and ABI on Contracts →
Manages vault lifecycle: collateral deposits, NXUSD minting, debt tracking, liquidation execution. Engine reads collateralOf(), debtOf(), minCollateralRatioBps(), liquidationRatioBps(), paused() on each cycle. Min CR: 150%. Liquidation threshold: 130%.
Overcollateralized on-chain credit asset. Mint and burn restricted to VaultManager via MINTER_ROLE and BURNER_ROLE. Engine reads totalSupply() on each cycle to determine total outstanding protocol debt.
Executes liquidations when vault CR falls below 130%. 5% collateral bonus to the keeper. KEEPER_ROLE enforced — unauthorized liquidation calls are rejected. Engine reads paused() and closeFactorBps() to assess engine state.
Protocol-managed Chainlink wrapper with freshness enforcement via maxDelay(). Reverts if the feed is outside the allowed window. On testnet, the Arbitrum Sepolia Chainlink feed does not update at the required frequency — OracleModule consistently reverts, setting oracle_stale: true and activating the Chainlink fallback.
Live chain state visible via Protocol Intelligence Layer. Every evaluation persisted as a verifiable AUD_001 package.