Debt Token Metadata

Defines the essential financial state of a debt position. This includes:

• Principal Amount: The original sum borrowed.
• Accrued Interest: Interest accumulated since the last payment.
• Interest Rate: The current annual percentage rate (APR or APY).
• Collateralization Ratio: The value of collateral backing the loan relative to the debt.
• Liquidation Threshold: The ratio at which the position can be liquidated.

Specifies the assets involved in the position using standardized identifiers.

• Collateral Assets: Lists the token addresses (e.g., ERC-20, ERC-721) and amounts locked.
• Debt Asset: Identifies the borrowed token (e.g., USDC, DAI).
• Protocol & Market: References the originating lending protocol (e.g., Aave, Compound) and specific pool or market.

Encodes time-sensitive data and the operational state of the debt.

• Origination & Maturity Dates: Timestamps for loan start and scheduled end.
• Last Update Block: The blockchain block number when parameters were last refreshed.
• Health Status: Boolean or enumerated flags indicating if the position is Active, Underwater, or Liquidated.
• Repayment Schedule: For structured debt, details on payment intervals.

Provides data layers for external risk engines and regulatory compliance.

• Risk Scores: Protocol-assigned or oracle-derived risk ratings for the position.
• Liquidation Penalty: The fee applied upon liquidation.
• Debt Tokenization Standard: The technical standard used (e.g., an extension of ERC-721 or ERC-1155).
• On-Chain Provenance: An immutable audit trail of all transactions affecting the debt.

Standardized metadata unlocks key DeFi primitives:

• Secondary Debt Markets: Enables trading debt positions as NFTs with clear terms.
• Automated Risk Management: Allows vaults and robots to programmatically assess portfolio health.
• Cross-Margin & Aggregation: Lets protocols aggregate debt from multiple sources into a unified position.
• Credit Scoring: Provides the raw data for on-chain credit history and reputation systems.

The foundational metadata for fungible debt tokens, as defined by the ERC-20 standard. This includes:

• name: The human-readable name of the debt token (e.g., "Aave aUSDC").
• symbol: The ticker symbol (e.g., aUSDC).
• decimals: The number of decimal places the token uses, crucial for representing fractional debt positions.
• totalSupply: The total circulating supply of the debt tokens, representing the aggregate debt in the system.

Critical fields that define the financial specifics of the debt position.

• underlyingAsset: The address of the asset that was borrowed (e.g., the USDC token contract).
• debtTokenAddress: The contract address of the debt token itself.
• interestRateModel: A reference to the contract calculating variable or stable interest rates.
• liquidationThreshold: The Loan-to-Value (LTV) ratio at which the position becomes eligible for liquidation.

For non-fungible debt positions (e.g., NFT-backed loans), metadata is extended via ERC-721 or similar standards.

• tokenURI: Points to a JSON file containing detailed metadata for the unique debt position.
• collateralTokenId: The ID of the specific NFT used as collateral.
• debtPrincipal: The original amount borrowed.
• debtAccruedInterest: The interest accrued since the loan's inception.
• maturityDate: The timestamp when the loan must be repaid.

Metadata that identifies the originating lending protocol and the token's version for upgradeability and compatibility.

• protocol: The name of the lending platform (e.g., Aave, Compound).
• version: The implementation version of the debt token contract (e.g., AaveV3).
• poolAddress: The address of the main lending pool contract that manages this debt token. This is essential for integrations and queries.

This standardized metadata enables key DeFi functionalities:

• Price Oracles: Use underlyingAsset to fetch the correct price feed.
• Portfolio Trackers: Parse symbol and protocol to categorize debt.
• Liquidation Bots: Monitor liquidationThreshold and debt balances.
• Aggregators: Use poolAddress and version to route transactions to the correct protocol contract.

Debt token metadata, especially the collateral value and health factor, is derived from external price oracles. This creates a critical dependency.

• Oracle manipulation (e.g., flash loan attacks) can trigger unjust liquidations or allow undercollateralized borrowing.
• Oracle staleness in low-liquidity markets can cause the protocol to operate on outdated, inaccurate prices.
• Mitigations include using time-weighted average prices (TWAPs), multiple oracle sources, and circuit breakers.

The liquidation threshold and liquidation penalty encoded in metadata are fundamental to protocol solvency.

• An overly aggressive liquidation threshold increases capital efficiency but raises the risk of bad debt from rapid price drops.
• A liquidation penalty that is too low may not incentivize liquidators, leading to unprocessed underwater positions.
• These parameters must be stress-tested against historical volatility and maximum drawdown scenarios for each collateral asset.

A core design tension exists between the security of immutable metadata and the need for parameter updates.

• Fully immutable metadata (e.g., in a non-upgradable contract) prevents admin abuse but can render a protocol obsolete or unsafe if market conditions change.
• Upgradable metadata via a multi-signature wallet or DAO governance introduces centralization risk and potential for malicious proposals.
• Common solutions include timelocks on parameter changes and gradual, bounded adjustments to critical values like loan-to-value ratios.

The public nature of blockchain data allows miner-extractable value (MEV) bots to frontrun liquidation transactions.

• Bots monitor for positions falling below the health factor and compete to be the first to submit a liquidation tx, capturing the penalty.
• This can lead to gas price auctions, making liquidations expensive for users and potentially crowding out decentralized liquidators.
• Mitigations include Dutch auctions for liquidation discounts or keeper networks with permissionless but prioritized access.

When debt tokens are integrated into other DeFi protocols (e.g., as collateral in a different lending market), their metadata assumptions can break.

• A secondary protocol may misprice the risk of the underlying debt position, treating it as simple collateral.
• This can create recursive leverage and systemic risk if the primary protocol's liquidation mechanisms are not accounted for.
• Risk oracles and explicit integration whitelists are used to manage these cross-protocol dependencies.

How metadata is displayed to users is a security consideration. Opaque or misleading information can lead to user error.

• A clear display of the health factor, liquidation price, and borrow APR is essential for informed decision-making.
• Frontends must accurately reflect on-chain state; a compromised or malicious frontend could display falsified metadata to trick users.
• Direct contract interaction and blockchain explorers provide a verification layer, but place a high cognitive load on users.

A risk parameter in lending protocols that determines the maximum borrowing power of a deposited asset. It is expressed as a percentage (e.g., 75%).

• Defines the loan-to-value (LTV) ratio for a collateral asset.
• Directly influences the minting and liquidation parameters of associated debt tokens.
• A higher factor allows more debt to be issued against the same collateral, increasing both capital efficiency and risk.

A real-time metric representing the safety of a borrower's position, calculated as the ratio of the collateral value to the borrowed value. It is crucial for debt token systems.

• A health factor below 1.0 makes the position eligible for liquidation.
• Debt token metadata or associated smart contracts continuously monitor this value.
• It is a key off-chain analytic derived from on-chain debt and collateral data.

A source of external price data fed on-chain to determine the value of collateral and debt assets. Accurate oracles are essential for all debt-based systems.

• Provides the market price used to calculate collateral value and health factors.
• Prevents inaccurate liquidations or under-collateralized loans.
• Can be decentralized (e.g., Chainlink) or based on internal AMM pricing.

The smart contract logic that automatically seizes and sells under-collateralized positions to repay bad debt. It is the enforcement mechanism for debt token systems.

• Triggered when a user's health factor falls below a threshold.
• Involves liquidation bonuses for liquidators and penalties for borrowers.
• Ensures the solvency of the lending pool backing the debt tokens.

A protocol-level limit on the total amount of debt that can be minted against a specific type of collateral or for a specific debt token. It is a critical risk management tool.

• Caps systemic risk by limiting exposure to any single asset.
• Can be adjusted via governance based on market conditions.
• Once reached, new debt tokens cannot be minted until existing debt is repaid.