Skip to content

Oracle Architecture

Home · Top · Table of Contents

Table of Contents

Kevin K. Le (LinkedIn) — Founder, Founding Engineer, and Current Lead Engineer; Software Engineer at the Oregon Blockchain Group, University of Oregon.

Kellen Snider — Founding Engineer; Software Engineer at the Oregon Blockchain Group, University of Oregon. His vision, ideas, and dedication during TrustLedger's Ethereum development were invaluable to the codebase we build on today.

See CREDITS.md.

TrustLedger currently uses oracle data for display and workflow support only. No smart contract consumes off-chain price data in production paths.

Endpoints

Home · Top · Table of Contents

Endpoint Purpose
GET /api/oracle/rates?base=eth&quote=usd Fetch a validated display rate.
GET /api/oracle/status Return supported pairs, provider URL, TTL, and cache metadata.

Supported Pairs

Home · Top · Table of Contents

Base Quote Provider ID
eth usd ethereum
usdc usd usd-coin

Data Flow

Home · Top · Table of Contents

flowchart LR
    UI[Frontend payment UI] --> API[/api/oracle/rates]
    API --> Service[src/services/oracle.ts]
    Service --> Provider[Price provider]
    Service --> Cache[In-memory TTL cache]
    API --> UI

Validation

Home · Top · Table of Contents

  • base must be one of the supported assets.
  • quote must be usd.
  • Provider payloads must contain a positive finite number.
  • Cache TTL defaults to 60000 ms and is capped at 3600000 ms.

Error Handling

Home · Top · Table of Contents

If the provider fails after a successful read, the service returns the cached rate with stale: true. If there is no cached rate, the route returns a 502 JSON error.

Monitoring

Home · Top · Table of Contents

GET /api/health checks oracle source URL validity. GET /api/oracle/status reports cache population and supported pairs without performing an external fetch.

Security Notes

Home · Top · Table of Contents

Oracle data is informational. Do not use it for custody, payout, or dispute decisions without a separate audited on-chain oracle design and contract tests.

Authors and Contributors

Home · Top · Table of Contents

  • Kevin K. Le — Founder, Founding Engineer, and Current Lead Engineer (LinkedIn)
  • Kellen Snider — Founding Engineer (LinkedIn)

See CREDITS.md for the complete acknowledgement list.

Home · Top · Table of Contents

This document is part of TrustLedger, an open-source decentralized escrow and arbitration protocol. Use of this software and documentation is subject to the Terms and Conditions, Privacy Policy, and Risk Disclosure. See LEGAL.md for the full compliance and licensing overview.