Integration.

Copy .env.example to .env.local. NEXT_PUBLIC_* values are inlined at build time — rebuild after changing them.

One contract carries both surfaces: the registry (claims, references) and settlement (settle / getSettlement). Reserve references are computed live from an ERC-20 balance; external references store a locator that the interface resolves through the adapter for their source.

Events (provenance timeline)

• ClaimCreated(bytes32 claimId, address issuer, address asset, uint256 value, bytes32 referenceId)
• ClaimUpdated(bytes32 claimId, uint256 value, uint256 quantity, uint8 state)
• ReferenceRegistered(bytes32 referenceId, address owner, uint8 source, string locator)
• ReferenceLinked(bytes32 claimId, bytes32 referenceId)
• ReferenceUpdated(bytes32 referenceId, uint256 value, uint64 timestamp)
• SettlementAligned(bytes32 claimId, bytes32 referenceId, uint256 expectedValue, uint256 referenceValue)
• SettlementMismatch(bytes32 claimId, bytes32 referenceId, uint256 expectedValue, uint256 referenceValue)
• SettlementStateChanged(bytes32 claimId, uint8 state)

Enums — assetType 0 cash-equivalent · 1 treasury · 2 equity · 3 commodity · 4 credit · 5 fund. state 0 pending · 1 active · 2 settled · 3 disputed. source 0 onchain · 1 api · 2 oracle · 3 manual. status 0 unknown · 1 available · 2 unavailable. Human ids (qUSD-04291) map to bytes32 as right-padded UTF-8, or keccak256 when longer than 32 bytes.

Writing from the interface

/claims/new registers a claim from the connected wallet: asset metadata and quantity are read live from the ERC-20 (totalSupply), the value from the live reference at issuance. Claim pages expose settle() for reserve-backed claims and issuer-only state changes. Every write is simulated first so reverts surface before the wallet prompt.

• onchainconfigured

  Registry (on-chain)

• apiconfigured

  Reference API (HTTPS)

• oracleconfigured

  Oracle feed (AggregatorV3)

• manualnot configured

  Manual attestation

With a registry configured the registry record is authoritative: reserve references come straight from the chain; external ones are fetched through the adapter named by their source using the stored locator (api → yahoo:SYMBOL via the reference route; oracle → an AggregatorV3 feed address), falling back to the last observation the reference owner posted on-chain. Without a registry the adapters are walked in order onchain → api → manual.

Reference API payload

GET {NEXT_PUBLIC_REFERENCE_API_URL}/references/{id}?locator=yahoo:AAPL
{
  "referenceId": "PX-AAPL",
  "source": "Yahoo Finance",
  "asset": "AAPL",
  "value": "314.5800",          // string | number | null
  "currency": "USD",
  "decimals": 4,
  "timestamp": 1787860801,      // the exchange's regularMarketTime (unix seconds | ISO-8601 | null)
  "blockNumber": null,
  "transactionHash": null,
  "status": "available",        // available | unavailable | unknown
  "basis": "unit",              // unit → multiplied by the claim quantity · total → compared directly
  "metadata": { "exchange": "NasdaqGS", "marketState": "CLOSED", "locator": "yahoo:AAPL" }
}

Validated with zod; anything that does not match is REFERENCE UNAVAILABLE (malformed), never a guessed value.

Formats — human 18s · 02m 41s · 1h 18m · 2d 04h; clock hh:mm:ss. AGE DELTA = |claim age − reference age| with direction (claim older / reference older / in sync). Requires both timestamps.

Money is compared as fixed-point bigint scaled to the larger decimals; no floating point until display.

• · Every demo record carries origin: 'demo' and renders a DEMO badge.
• · Demo block numbers and addresses never link to the explorer.
• · Demo timestamps are offsets from first load, so ages are real elapsed time — the feed does not fabricate new activity.
• · Chain lookups (tx hash, address) and the network indicator always hit the live RPC, even in demo mode.

• Reference cannot be fetched → REFERENCE UNAVAILABLE
• Timestamp cannot be determined → AGE UNKNOWN
• Settlement cannot be verified → UNVERIFIED / UNKNOWN
• Data is not from a real source → DEMO