OPNVault

What we built

OPNVault is a unified EVM-compatible Collateralized Debt Position (CDP) smart contract (OPNVault.sol) that inherits the ERC20 standard, functioning as both the vault engine and the stablecoin itself (oUSD).

The implementation enforces the following custom state controls and integrations:

• Unified CDP Ledger: Consolidates debt and collateral accounting into a single address space, bypassing standard approve / transferFrom overhead by executing direct internal burns (_burn) during settlements.
• NeoID State Fallback: Interfaces with INeoIDRegistry via try/catch, falling back to a local verification registry (hasVerifiedIdentity) in case of external registry failure or uninitialized state.
• Non-Recursive TBA Resolution: Implements resolveIdentityHolder with a strict 30,000 gas limit on external calls. It halts evaluation if a nested contract owner is detected (tbaOwner.code.length > 0) to prevent stack-exhaustion and reentrancy loops.
• Asymmetric Price Sanity Guard: Bounds manual admin overrides (setEmergencyManualPrice) to a maximum increase of +20% and a minimum of -90% relative to the last cached oracle price (lastValidPrice).

Why

We engineered this unified CDP architecture to align with the core primitives and economic design of OPN Chain:

1. Gas Minimization on L1: Traditional multi-contract CDP designs require separate transactions for vault deposits, credit approvals, and token transfers. By consolidating the vault ledger and minting logic into OPNVault is ERC20, we eliminate state-sync overhead and reduce the transaction footprint during debt settlement.
2. Identity-Tiered Leverage (NeoID): Rather than enforcing a static, conservative Loan-to-Value (LTV) limit across all users, the contract optimizes capital parameters based on sovereign credentials: verified NeoID accounts operate on a 70% baseline LTV, while unverified addresses are limited to 45% LTV.
3. Smart-Wallet Portability for RWAs: Since tokenized RWA portfolios on OPN Chain utilize nested ERC-6551 accounts, checking credentials solely on msg.sender would penalize smart contract wallets. Tracing ownership to the root EOA ensures nested portfolios safely inherit the primary controller's NeoID status without exposing the contract to gas-griefing.

How it works

1. Collateral Sourcing: Users lock native OPN via addCollateral(), updating user balances and system-wide TVL variables.
2. Adaptive Credit Throttling: During mintStablecoin(), the contract checks the user's root NeoID status. It evaluates getDynamicLTVFactor(), scaling down maximum credit capacities linearly if the Global Backing Ratio (GBR) drops below 120% (1.2 ether) to a floor of 30% of the baseline limit at 105% GBR.
3. Game-Theoretic Liquidation Constraints: If a position's health factor falls below 1.0 ether, it is marked for liquidation.
   • Anti-Gaming Limit: To prevent liquidators from performing micro-liquidations solely to harvest bonuses, the contract enforces resultingHF >= 1.05 on partial liquidations.
   • Dust Cleanup: If remaining collateral falls below 0.001 OPN, the contract forces a full liquidation to clean up state dust.
   • Insolvency Cap: If a position is fully insolvent, the bonus is capped at 103% to protect backing, and bad debt is logged to the totalBadDebt accumulator.