On-Chain Verification Layer

CONTRACTSource of Truth

Four contracts define the complete state of the NEXUS protocol on Arbitrum Sepolia. Every value the API returns is derived from these. Every receipt records outcomes computed from them. They are not a reference — they are the ground truth.

ARBITRUM SEPOLIA · VERIFIED · READ WITHOUT WALLET

Data Flow

Contracts define. API reads. Receipts prove.

This page is not a directory. It is the base layer of the verification chain. Understanding what each contract holds — and what the engine reads from it — is prerequisite to verifying any API response or audit receipt independently.

CONTRACTS DEFINE

These four contracts hold the authoritative on-chain state: collateral balances, debt obligations, protocol thresholds, oracle price, and pause status. No off-chain computation can override what these contracts return.

API READS

Every field in /api/status and /api/vaults is derived from a direct eth_call to one of these contracts on each cache miss. The mapping is documented below and in API Docs →

RECEIPTS PROVE

AUD_001 audit packages record the chain state reads alongside pillar verdicts. Any receipt can be verified by re-reading the same contract methods at the same block number and comparing the values. See Audit Evidence Layer →

Read Mapping

From contract call to API field

Every value in the API has a direct on-chain source. The table below maps each API field to the contract call that produces it. You can reproduce any response by calling these methods directly at the relevant block number.

/api/status — contract read sourcesFull schema in /api-docs →

eth_price_usdOracleModule.getPrice() → price field. On revert: Chainlink.latestRoundData() → answer field.

oracle_staletrue when OracleModule.getPrice() reverts for any reason. false when it returns successfully.

price_source"oracle" when OracleModule succeeded. "chainlink_fallback" when it reverted.

total_collateral_ethΣ VaultManager.collateralOf(owner) across all known owners via multicall.

total_debt_nxusdNXUSDToken.totalSupply().

collateral_ratio_pct(total_collateral_eth × eth_price_usd) / total_debt_nxusd × 100. Server-computed.

min_collateral_ratio_bpsVaultManager.minCollateralRatioBps(). Currently 15000 (150%).

liquidation_ratio_bpsVaultManager.liquidationRatioBps(). Currently 13000 (130%).

vault_pausedVaultManager.paused().

liquidation_engine_pausedLiquidationEngine.paused().

block_numberBlock number at time of RPC fetch. Anchors all reads to a specific chain state.

/api/vaults — per-vault reads

vaults[].collateral_ethVaultManager.collateralOf(owner) / 1e18 for each owner discovered in Deposit event logs.

vaults[].debt_nxusdVaultManager.debtOf(owner) / 1e18 for each owner.

vaults[].collateral_ratio(collateral_eth × eth_price_usd) / debt_nxusd. Server-computed. null when debt is zero.

vaults[].statusClassified server-side from CR vs thresholds. isLiquidatable() is NOT called — it reverts when oracle is stale.

NoteYou can verify any vault status by calling VaultManager.collateralOf() and debtOf() at the block_number in the response and computing CR manually. No trust in this API is required.

Deployed Contracts

Four contracts. All state.

PROTOCOL DEBT LEDGER

NXUSDToken

ERC-20 representing total protocol debt. Mint and burn are restricted exclusively to VaultManager via MINTER_ROLE and BURNER_ROLE — no external mint is possible. totalSupply() is the authoritative source of total outstanding NXUSD.

ENGINE READS

totalSupply() → total_debt_nxusd in all API responses

0x515844Dd91956C749e33521B4f171dac4e04FE07

Arbiscan →ABI (JSON) →

READ FUNCTIONS

totalSupply()Total NXUSD in circulation — equals total protocol debt

balanceOf(address)NXUSD balance of any wallet

decimals()Returns 18

allowance(owner, spender)Spending allowance

COLLATERAL STATE & THRESHOLDS

VaultManager

The primary state contract. Tracks every vault's collateral and debt, enforces protocol thresholds, and controls pause state. Every collateral ratio in any API response is derived from this contract's state. Min CR: 150%. Liquidation threshold: 130%.

ENGINE READS

collateralOf() + debtOf() via multicall for all vault owners → vault CR. minCollateralRatioBps() + liquidationRatioBps() → protocol thresholds. paused() → vault_paused.

0xF09AAD220C6c4d805cF6cE5561B546f51ADFBb03

Arbiscan →ABI (JSON) →

READ FUNCTIONS

collateralOf(address)WETH deposited by a vault owner — engine reads this for every known owner

debtOf(address)NXUSD outstanding for a vault owner — engine reads this for every known owner

minCollateralRatioBps()Minimum safe CR in BPS — 15000 = 150%

liquidationRatioBps()Liquidation threshold in BPS — 13000 = 130%

isLiquidatable(address)Returns true if vault is below liquidation threshold — calls OracleModule internally, reverts when oracle is stale

paused()True when vault deposits, withdrawals, and mints are halted

KEEPER EXECUTION MODULE

LiquidationEngine

Executes controlled liquidations when vault CR falls below the 130% threshold. 5% collateral bonus incentivizes keepers. KEEPER_ROLE is enforced — unauthorized calls revert. The API does not call isLiquidatable() on-chain to avoid oracle revert; status is computed server-side from CR thresholds.

ENGINE READS

paused() → liquidation_engine_paused. closeFactorBps() → max debt repayable per liquidation call.

0xF333d9ae2D70305758E714ecBeA938e9377a9f9D

Arbiscan →ABI (JSON) →

READ FUNCTIONS

closeFactorBps()Maximum portion of debt repayable in a single liquidation call

paused()True when liquidation execution is halted

PRICE SOURCE WITH STALENESS GUARD

OracleModule

Chainlink ETH/USD feed wrapper with a freshness window enforced by maxDelay(). Reverts if the feed has not been updated within the allowed window. On revert, the engine falls back directly to the Chainlink aggregator. On Arbitrum Sepolia testnet, the feed does not update at the required frequency — OracleModule consistently reverts and oracle_stale is set to true across all API responses.

ENGINE READS

getPrice() → eth_price_usd (primary). On revert: Chainlink.latestRoundData() → eth_price_usd (fallback). Revert → oracle_stale: true in all API responses.

0xa1BD5AF1174140caB018e46eBCFEf1d005c3df84

Arbiscan →ABI (JSON) →

READ FUNCTIONS

getPrice()Returns (price, updatedAt, decimals) — reverts if feed is outside maxDelay window

feed()Address of the underlying Chainlink aggregator

maxDelay()Maximum allowed data age in seconds — determines staleness threshold

Independent Verification

You don't need this API.

Every read function listed above is callable via eth_call on any Arbitrum Sepolia RPC endpoint. No wallet, no authentication, no dependency on this interface. If the API returns a value you want to verify, call the contract directly at the same block number. The numbers must match.

To verify a status response

1Note the block_number in the API response

2Call OracleModule.getPrice() at that block. On revert, call Chainlink.latestRoundData()

3Call NXUSDToken.totalSupply() at that block for total debt

4Call VaultManager.collateralOf() for any vault owner you want to check

5Compute CR: (collateral × price) / debt × 100

6Compare against collateral_ratio_pct in the API response — they must match

To verify a receipt

1Note the block_number in the AUD_001 package

2Call the same contract methods at that block

3Reproduce the pillar logic: CR > 100%? CR > 130%? oracle live?

4Compute expected overall_verdict from pillar results

5Compare against overall_verdict in the package — must match

6Recompute SHA-256 over the raw field and compare against package_hash

Audit Evidence Layer →

The contracts are the ground truth.

API responses are derived from them. Receipts record what they returned. Verification requires nothing beyond an RPC endpoint and these addresses.

Live Protocol State →API Read Reference →Contract Source →