Oracle infrastructure for collateral, margin and settlement

Define what the price is allowed to mean

A spot index, a fund's net asset value, a wrapper conversion rate and a firm executable quote answer different questions. An index can support a market valuation without proving that a large sale can clear at that price. A conversion rate can describe a claim on an underlying asset without proving that redemption is available now.

Start each integration with a data contract: exact asset and chain, quote currency, measurement method, observation time, expected update behavior and permitted uses. Distinguish valuation, trade execution, liquidation and settlement. Reusing one number across all four is a product decision that requires evidence.

Chainlink's feed-selection guidance distinguishes feed types and source risks, including exchange-rate feeds and single-source data. The relevant engineering task is to establish that the selected feed measures the economic object the application actually needs. FT Inc's role is software and integration engineering; the examples here do not claim that FT publishes or guarantees a market-data service.

Use an adapter with explicit validity information

An adapter can normalize a provider's response into a small, typed record: asset identifier, quote identifier, value, scale, observation timestamp, uncertainty measure where available and a status code. Keep provider-specific verification at that boundary, while allowing each consuming product to impose tighter requirements.

A contract should not interpret a missing answer as zero or carry forward an old answer without preserving its original timestamp. Distinguish unavailable, stale, outside policy bounds and valid. This lets a debt-repayment path remain usable while a withdrawal path correctly rejects a valuation it cannot trust.

Composite prices need traceable inputs. If an asset is valued through an asset-to-ETH rate and ETH-to-USD feed, both timestamps matter. A current dollar feed cannot make an obsolete conversion rate current. Record the oldest component observation and test whether mismatched observation times create unacceptable basis risk.

Normalize units before granting credit

For an illustrative token with 18 decimals, a balance of 2 × 10¹⁸ represents two tokens. A dollar feed with eight decimals reporting 200,000,000,000 represents $2,000 per token. Their value is $4,000, or 4,000 × 10⁶ in a ledger using six decimal dollar units. The arithmetic should encode those units, not infer them from a familiar token symbol.

Validate signed answers before converting to unsigned integers. Define valid ranges for prices and exponents, handle unsupported scales explicitly and use checked full-precision arithmetic where intermediate products can exceed the output range. Collateral and debt may need different conservative rounding directions.

Test all supported token and feed decimal combinations against an independent calculator. Include minimum nonzero balances, large balances, extreme prices and a feed migration with different decimals. A scale error can produce a valid-looking number with orders of magnitude too much borrowing power.

Tie freshness to the action being authorized

Chainlink's timestamp guidance explains that feed updates can follow deviation thresholds and heartbeats rather than a continuous stream. Applications need their own acceptable-age checks. Heartbeats and update behavior can differ by asset and chain, so a universal timeout copied across integrations can be inappropriate.

Track observation time separately from the time a message reached your service. Reject malformed timestamps, unsupported future times and replayed observations where the integration requires monotonic progress. A recently delivered message is not necessarily a recently observed price.

For an executable trade, a trader's ability to select a favorable observation is part of the threat model. Specify which time window is eligible and whether execution uses the order time, fill time or another defined boundary. A loose freshness check alone does not establish a fair execution price when external markets move faster than onchain updates.

Preserve uncertainty instead of discarding it

Pyth's integration guidance describes prices with confidence information and conservative treatment of collateral and debt. An illustrative policy could value collateral at the lower side of an accepted range and liabilities at the upper side. For a price of $100 with a $4 confidence amount, that would mean $96 for collateral and $104 for debt before separate asset-specific rules.

This is a policy choice, not a guaranteed loss bound. Confidence information does not prove that the entire position can be sold inside that range. Executable depth, trade size, transfer permissions and settlement timing remain separate inputs. Wider uncertainty can instead trigger smaller limits or a restricted operating state, depending on the product.

Document how uncertainty combines with haircuts and stress scenarios so the same risk is neither omitted nor charged repeatedly. A model review should be able to explain which adjustment covers measurement uncertainty and which covers the economics of closeout.

Evaluate TWAPs and fallback independence

A time-weighted average price reduces the influence of a momentary spot move, while introducing delay relative to the current market. Uniswap's v2 oracle documentation explains cumulative-price observations and the influence of liquidity and observation length on manipulation cost. A TWAP is not intrinsically safe for every amount of value secured by it.

Compare the value that could be extracted from a manipulated price with the cost of sustaining that manipulation under the actual pool and chain conditions. A thin pool should not gain unlimited lending authority simply because its price has been averaged.

Two providers are not independent if they inherit the same underlying venue or issuer observation. Map common dependencies before treating a second feed as a fallback. A disagreement detector identifies a problem; it does not determine which source is correct. Define the response without automatically choosing whichever number permits the transaction.

Define degraded behavior and recovery

Specify allowed actions for normal, stale, divergent and unavailable states. New debt and risk-increasing withdrawals may stop while fixed-amount repayment remains available. A deposit can be recorded without immediately granting collateral credit. Liquidation requires its own rule because freezing and continuing on unreliable prices create different risks.

For supported rollups, sequencer-uptime checks can detect an additional availability condition and support a recovery grace period. A sequencer returning online does not by itself establish that the market data is fresh or that every participant can respond immediately.

Use explicit recovery criteria: required observations, permitted divergence, elapsed recovery time and approval scope where human intervention is part of the design. Invalidate obsolete quotes and risk authorizations before resuming normal execution. Record each state transition so an operator can distinguish a market event from a broken adapter.

Test failures and retain the evidence

Integration tests should inject zero and negative answers, stale and future timestamps, missing observations, unexpected exponents, provider reverts and conflicting feeds. Exercise parameter changes and feed replacements while quotes or withdrawals are pending. Verify the exact behavior of every consumer, not only the adapter's returned value.

Monitor observation age, update gaps, divergence, uncertainty, rejected actions and time spent in degraded states. Tie alerts to owners and documented responses. A chart showing a fresh price is insufficient if the contract consumes another feed address or a different quote currency.

Retain feed configuration, model version and observation identifiers alongside material risk decisions. That evidence supports incident reconstruction and calibration review. The deliverable is an operational pricing boundary connecting margin, collateral and liquidation, with defined behavior when its assumptions stop holding.

Common engineering questions