Goldie City
Protocol

Pricing and Settlement

Pricing integrity is a key institutional requirement. Goldie’s design centers on transparent inputs, explicit governance for parameter updates, and safety handling for oracle failures.

Inputs

Pricing/settlement calculations typically combine:

  • Market inputs from Chainlink price feeds (spot price)
  • Issuer parameters (token-specific configuration locked on-chain)

In the reference implementation, market pricing is provided by PreciousMetalPricingOracle and settlement/quote calculations are performed by PreciousMetalPriceSettlement.

Chainlink price feeds (market data)

badge:chainlink

Goldie uses Chainlink AggregatorV3 feeds for precious metal spot prices (e.g., Gold/USD). Feeds are configured per metal (Gold, Silver, Platinum, Palladium) so deployments can enable only the metals they support.

What is read from Chainlink

On-chain reads use Chainlink’s latestRoundData() and consume:

  • answer: the spot price value
  • updatedAt: the last update timestamp for that answer
  • roundId and answeredInRound: round identifiers used to validate that the returned answer is from a completed round

Validations and safety checks

The oracle applies explicit safety rails before accepting a live Chainlink response:

  • Non-negative, non-zero price: rejects zero/negative answers.
  • Round completion: rejects data with updatedAt == 0.
  • Round consistency: rejects responses where answeredInRound < roundId.
  • Staleness threshold: rejects prices older than priceStalenessThreshold seconds.

These checks are designed to prevent using stale or incomplete data for any price-dependent action.

Caching for gas efficiency (without changing trust assumptions)

For gas optimization, the oracle maintains a per-metal cache:

  • Read methods return the cached price when it is still within cacheValidityDuration.
  • Anyone can call updatePriceCache() / updateAllPriceCaches() to refresh the cache (useful for keepers).
  • Cache updates emit PriceCacheUpdated, which can be indexed off-chain for monitoring and audit trails.

Caching is an optimization only: when the cache is expired, the oracle reads fresh data (subject to the same Chainlink validations above).

Fallback mode (explicitly governed)

The oracle supports a manual fallback price per metal:

  • If fallback mode is explicitly enabled for a metal, the oracle returns fallbackPrice instead of reading Chainlink.
  • If a Chainlink call fails (reverts) and a fallback price is configured, the oracle can return the fallback price.
  • If fallback is not configured, the oracle reverts rather than returning an unsafe value.

Because fallback is a governance-controlled switch, external reviewers can verify whether fallback is in use via on-chain state (isUsingFallback) and governance transactions.

Staleness and safety

Oracles can become delayed or unavailable. The protocol’s design treats stale data as unsafe. A staleness threshold defines when data is no longer acceptable, and the system behavior under stale conditions is governed by explicit policy (e.g., deny operations that depend on price).

In practice, staleness enforcement happens at the oracle read layer (prices older than priceStalenessThreshold are rejected), and settlement functions that execute state changes can be paused via whenNotPaused in PreciousMetalPriceSettlement.

Settlement calculation (issuer parameters + oracle price)

PreciousMetalPriceSettlement calculates a transparent quote using:

  • Oracle price per gram (sourced from Chainlink via PreciousMetalPricingOracle)
  • Token facts (unit weight in milligrams and purity in basis points)
  • Issuer business parameters locked on-chain (storage/insurance/handling/compliance costs, profit margin, and a bounded market adjustment)

The contract also enforces reasonable output bounds (min/max) to avoid executing trades at nonsensical prices.

Decimal conventions (important for integrators)

The reference contracts use consistent decimal conventions:

  • Chainlink prices are treated as 8 decimals.
  • Operational costs are stored as 6 decimals per gram and converted during calculation.
  • Token weight is in milligrams; purity is in basis points.

Governance for pricing parameters

Changing oracle sources, thresholds, or issuer parameters is a privileged action controlled by roles. This keeps pricing integrity anchored in governance rather than in application logic.

At a high level:

  • Platform governance configures oracle feeds, staleness threshold, cache duration, and fallback settings.
  • Token/issuer governance controls business parameters used in settlement (and can update the settlement’s oracle pointer in deployments where that is permitted).

What external parties can verify

  • Which oracle feeds are used (via configuration/state)
  • Whether data is considered stale (via thresholds and timestamps)
  • Who can change parameters (roles)
  • When changes happened (transactions/events)

Diagrams

Pricing pipeline with safety rails

Rendering diagram…