Reframing the blockchain oracle problem: not "connecting to an external API," but "designing for trust."

LAB 001 — TRUSTED EXTERNAL DATA. When a smart contract takes in external data, the question is not whether it can connect to an API. It is why that value can be trusted, who confirms it, what evidence is kept, and who can stop things when something looks wrong. Netsujo Lab publishes a reference design for an Oracle Agent that combines multi-source verification, a trust score, human review, and audit hashes.

Status

Reference architecture

Stage

Design / local MVP specification

Production deployment

Not yet

Version

0.1.0

Published

July 5, 2026

Last updated

July 5, 2026

Technical review

Pending

Executive summary

Definition: the oracle problem is the fact that a smart contract cannot itself verify facts from outside the blockchain, and must instead separately design where external data comes from, its accuracy, its freshness, its tamper resistance, and who is accountable for it.

• A smart contract cannot, on its own, confirm facts about the outside world.
• Using multiple data sources does not, by itself, guarantee the truth.
• What is needed is a trust design that combines source multiplicity, freshness, deviation checks, signatures, history, and clear accountability.
• An LLM can help explain an anomaly or assist a human reviewer, but it must never be the final arbiter of truth.
• The chain should not store large amounts of raw data — only a minimal, verifiable trail: the value, the time, the number of sources, the decision, and an audit hash.

What the oracle problem is

A smart contract cannot directly reference an arbitrary web API. A blockchain requires every network participant to be able to reproduce the same result from the same input, but the result of an external API call can vary with the time it was fetched, which endpoint answered, outages, or tampering. An input that not everyone can reproduce identically breaks consensus. This is why a mechanism is needed to fetch, verify, and pass external information on-chain — that mechanism is the oracle.

An oracle is not a device that automatically manufactures truth. It is a boundary layer that is designed to decide under what conditions external information gets adopted.

The central message of this research

The oracle problem is not a matter of picking one correct API. At its core, it is a governance question: with how much evidence, verification, and accountability should uncertain information from the outside world be passed to a smart contract? The design principles below recur throughout the rest of this research: multiplying data sources; recording the verification process; leaving room for human review; accountability through signatures, audit logs, and hashes; never making an LLM the arbiter of truth; and keeping only a minimal trail on-chain.

Threat model

This reference design targets the following eight threats. Threats outside this table — such as economic-incentive design or collusion resistance — are out of scope for this research.

Research hypothesis and design principles

External data should be treated not as something merely "fetched," but as a bundle of evidence: if a single value is not passed on-chain directly, but combined into one evidence package — multiple sources, observation time, deviation, signatures, history, and the reasoning behind the decision — full truth cannot be guaranteed, but transparency and auditability of the adoption decision can be substantially improved.

In scope

price / weather / inventory / event / generic data.

Out of scope

Formal proof of the safety of an entire decentralized oracle network including economic incentives; formal verification of Byzantine fault tolerance; empirical proof of market-manipulation resistance; operating an oracle for production assets; and implementation-level verification of TEE / ZK.

Reference architecture: separating fetch, verification, decision, and audit trail

The Oracle Agent is a pipeline that separates fetching, normalizing, validating, scoring, deciding, and outputting. Each node can be inspected for its input, what it does, its output, its failure conditions, and who is accountable. The design principle at the center is that whichever layer fails, the reason is left in an audit log.

Data model: the five types that make up the evidence package

From a request (OracleRequest) through to a decision (OracleDecision), here is how the evidence is structured, shown by its key fields. The full type definitions are published in the design document (Markdown).

OracleRequest — what to fetch and under what conditions

id (request identifier); oracleType ('price' | 'weather' | 'inventory' | 'event' | 'generic'); target (e.g. ETH/USD, or the inventory of Warehouse A); requiredSources (minimum source count needed for adoption); maxSourceDeviationRate (allowed deviation rate); freshnessThresholdSec (freshness threshold in seconds); humanReviewThreshold (the score below which a case is sent to human review); createdAt (creation time).

SourceResult — each source's fetch result, evidence including the raw data

sourceId / sourceName / sourceType (source identification); value / unit (the observed value and unit — value is kept as a string to preserve precision); observedAt (when the underlying data was observed); fetchedAt (when it was fetched — always kept separate from observedAt); rawData (the raw response, stored off-chain only); success / error (whether the fetch succeeded, and why it failed if not).

ValidationResult — whether verification passed, and why

isValid (overall pass/fail); errors / warnings (distinguishing rejection factors from review factors); sourceAgreementRate (the share of sources that agree within the allowed deviation); deviationRate (deviation from the median); freshnessOk (whether it is within the freshness threshold).

TrustScore — a supporting signal for the adoption decision, not a measure of truth

totalScore (a weighted composite score, 0–100); sourceDiversityScore (source diversity); sourceAgreementScore (agreement across sources); freshnessScore (freshness); historicalReliabilityScore (a source's track record); anomalyPenalty (a deduction for anomalies); requiresHumanReview (whether human review is required).

OracleDecision — the final decision and its audit trail

status ('approved' | 'needs_human_review' | 'rejected'); finalValue (the adopted value, median-based); trustScore / validation (references to the score and validation result); reason (a human-readable explanation of the decision); auditHash (a hash of the audit log); createdAt (decision time).

The validation engine: verifying the conditions under which a value arose, not just the value itself

1. Schema validation

External responses are validated with zod. Data with an invalid type, a missing required field, or a malformed timestamp is excluded from the candidate pool before its content is even examined — this layer is also the first to catch a silent change in an API's specification.

2. Source agreement

For price data: maxDeviationRate = abs(max − min) / median. We use the median as the baseline because it is less affected by outliers than the mean (the denominator is the absolute value of the median; for data that can sit near zero, such as temperature, an absolute-difference threshold is needed instead of a ratio). The median does not guarantee truth either — if a majority of sources return the same wrong value, the median becomes that wrong value.

3. Freshness validation

now − observedAt <= freshnessThresholdSec. We separate fetchedAt (when it was retrieved) from observedAt (when the underlying data was observed), because a recently fetched value can still be built on a stale underlying observation. This separation prevents a cached, outdated value from being mistaken for a fresh fetch.

4. Threshold validation

Thresholds vary by use case; the figures below are design examples, not fixed rules. price: roughly 0.5–2.0% deviation, 60–300 seconds freshness. weather: roughly 5–10% deviation, 1,800–3,600 seconds. inventory: in principle 0% deviation, 300–3,600 seconds. event: roughly 0–5% deviation, 3,600 seconds to one day. These reference values need individual tailoring based on asset scale, update frequency, the impact of a failure, and how the data is fetched.

Trust score: a supporting signal for the adoption decision, not "how true it is"

totalScore = sourceDiversityScore × 0.20 + sourceAgreementScore × 0.30 + freshnessScore × 0.20 + historicalReliabilityScore × 0.20 − anomalyPenalty × 0.10

This weighting and these thresholds are a reference design for research purposes. The score does not guarantee the truth of the outside world. It needs adjustment for each use case's tolerance for loss, data-update frequency, source composition, and legal accountability. That is exactly why we always present the breakdown, the reasoning, and the warnings alongside the score, rather than as a single gauge — the same policy applies to the simulator described below.

Decision flow

A decision always comes back with a reason. Cases that are ambiguous are not auto-approved — they are routed to human review.

Interactive Oracle Decision Simulator

You can change the number of sources, the values, the observation times, and the failure states, and see how validation, the trust score, and the decision change. Everything runs on sample data with local computation only — no input values are sent anywhere externally.

Human review

Cases that fall in the review-threshold band are handled by a Review Agent, which organizes what the problem is, which source is deviating, and why it could not be auto-approved, then presents options — approve, re-fetch, or reject — along with a recommended action. The reviewer, the time of the decision, and the reasoning are kept in the audit log.

Example: STATUS — NEEDS HUMAN REVIEW. Reason: "Source C is 6.8% above the median and exceeds the allowed deviation rate of 2.0%." Recommended actions: (1) re-fetch Source C; (2) add an alternate source; (3) check for a market halt or abnormal pricing; (4) reject the decision. This illustrates a human-review UI: the system auto-generates the material a reviewer needs, but the final call stays with a human.

The LLM boundary: AI can explain, but it is never the arbiter of truth

As a company working in both AI and Web3, Netsujo draws this boundary explicitly. An LLM carries hallucination risk, and the moment it is placed as the generator of verification data or the final decision-maker, auditability collapses.

What can be delegated to an LLM

Explaining differences between sources; summarizing for human review; proposing hypotheses for an anomaly; suggesting candidate data sources; turning an audit log into natural language.

What must never be delegated to an LLM

The final determination of truth; generating price data; substituting for an API response; substituting for signature verification; auto-approving an on-chain post.

What goes on-chain

Given on-chain storage cost, privacy, update frequency, and the fact that on-chain data cannot be deleted, we do not put raw responses or personal information directly on-chain. Only an approved decision can be posted, with a payload of this form:

{ "requestId": "oracle_20260521_001", "oracleType": "price", "target": "ETH/USD", "value": "3760.12", "unit": "USD", "observedAt": "2026-05-21T10:00:00Z", "trustScore": 87, "sourceCount": 3, "auditHash": "0x..." }

• Restrict who can post (an allowlist of addresses)
• Store a hash of the payload
• Never put raw data on-chain
• Record only the hash of the off-chain audit log on-chain
• Require multi-sig approval for important data
• Never post anything other than an approved decision

Failure test matrix

What matters more than "does it work normally" is "does it fail in a way that can be explained." Here are the 10 cases we target for verification in the local MVP.

Applications: not just price oracles, but real-world enterprise data

This reference design mainly targets company-specific data for which no general-purpose feed exists. For each use case, before asking what to put on-chain, we ask six questions first: who observes the fact; whether that observer has an incentive to cheat; how many pieces of evidence are needed; how much freshness is required; what the loss is if a decision is wrong; and who can halt or re-judge it.

RWA / proof of inventory

Real-asset inventory counts, warehouse custody proof, appraisal data, redemption processing, and audit trails.

Tourism / regional revitalization

On-site visit proof, QR scans, GPS check-in, in-store use, and event participation.

Community / SBTs

Event participation, lightning-talk speaking, survey responses, and connpass / Discord / Google Form integration.

Regional currency / stablecoins

Payment records, use at member merchants, point-award conditions, and external price/FX data.

DePIN / YaseiGrid

Sensor observations, detection time, location data, agreement across multiple nodes, false-positive review, and reward conditions.

Relationship to existing oracle networks

This research does not replace existing decentralized oracle networks. For general-purpose price feeds or external computation, using an existing service can be the more rational choice. Netsujo's reference design is instead intended to organize the fetching, verification, accountability, and audit of company-specific external data — inventory, events, visits, and operational data — that general-purpose feeds do not cover well. Please refer to each vendor's primary documentation for the specifics of networks such as Chainlink or Pyth; this page does not rank or declare any network superior.

What this research does not solve

In the interest of being an honest piece of research, here are the limitations this design still carries, unhidden. These can be used as a starting point for risk assessment in an adoption decision.

• Multiple sources may reference the same wrong information
• Sources that look independent may depend on the same primary source
• A signature proves who sent something, but not that its content is true
• A human reviewer may act dishonestly or misjudge
• The weights in the trust score may be wrong
• Distinguishing a sudden market move from an attack
• Delay before a result is reflected on-chain
• Economic incentives and resistance to collusion
• Regulatory and contractual allocation of responsibility

Research artifacts

As open research, the artifact can be read directly with no registration required. The local mock-MVP implementation, test results, and repository will be added to this list once they can be published (we do not list anything that does not yet exist).

• Oracle Agent design document (Markdown, v0.1.0, published July 5, 2026)

Planned: a GitHub repository, test results, and JSON samples — to be published after the local mock MVP is implemented, alongside package version, test results, coverage, commit hash, and license.

Author, review, and changelog

• v0.1.0 (2026-07-05) — Initial reference architecture published

Related articles and services

• Criteria for the Web3 adoption decision — the questions to ask if you are not sure whether to use blockchain
• Web3 PoC design & support — from defining success and ROI through production operation
• Smart contract pre-procurement audit — third-party review of externally contracted code
• RWA (real-world asset tokenization) guide — inventory proof and redemption processing are a primary battleground for external-data design
• Smart contract security — attacks against oracles and how to defend against them
• Web3 hacking case studies — analysis of real incidents, including oracle-driven ones
• YaseiGrid (wildlife-detection DePIN, R&D) — our own R&D project exploring the multiplication of sensor observations
• DID Platform (R&D) — research into signed, verifiable attribute proofs

Frequently asked questions

What is the blockchain oracle problem?

The problem that a smart contract cannot directly confirm facts from outside the blockchain, and must separately design where external data comes from, its accuracy, its freshness, its tamper resistance, and who is accountable for it. This is not a technical defect — it is a design challenge that inevitably arises at the boundary where a deterministic system connects to the outside world.

Why can't a smart contract call an external API directly?

Because every participant on the network needs to be able to reproduce the same result from the same input. The result of an external API call can change with fetch time, endpoint, outages, or tampering, so a structure that directly references an arbitrary web API is incompatible with reaching consensus.

Does using multiple APIs solve the oracle problem?

No. Multiple sources reduce single points of failure, but there remains a risk that all sources depend on the same wrong information or the same primary source. Alongside multiplying sources, you need a trust design that combines freshness, deviation, signatures, history, and clear accountability.

If we use Chainlink, do we not need our own design?

For general-purpose price feeds, it is often more rational to use an existing decentralized oracle. However, company-specific data — inventory, visits, events, operations — usually has no general-purpose feed, so the fetching, verification, and accountability still need to be designed individually.

If the trust score is high, is the data correct?

No. The trust score is a supporting signal for the adoption decision, not "how true it is." It is calculated from source diversity, agreement, freshness, and history, but it does not guarantee the truth of the outside world. That is exactly why we record the breakdown and the reasoning, and route the threshold band to human review.

Can AI or an LLM solve the oracle problem?

No. An LLM is useful for explaining anomalies and assisting reviewers, but because of hallucination risk it must never be the final arbiter of truth or a data source. In this research, an LLM's role is limited to that of an explainer.

What kind of external data does RWA need?

Real-world facts that back a token's value — the count of physical-asset inventory, warehouse custody proof, appraisal data, and completed redemption processing. Because general-purpose price feeds cannot handle these, the observer, the number of pieces of evidence, freshness, and the audit trail all need individual design.

What should an oracle's audit log keep?

Each source's raw response; the observation time and fetch time; whether validation passed and why; the score breakdown; and the final decision and who made it. The goal is for a third party to later trace why a given value was adopted, with a hash of the whole log kept on-chain.

Should raw data be stored on-chain?

In principle, no — because of storage cost, privacy, and the fact that on-chain data cannot be deleted. Only a minimal, verifiable trail should go on-chain — the adopted value, observation time, source count, decision, and audit hash — with the raw data kept off-chain.

How far can Netsujo support this?

We do not sell an oracle network itself. Our support starts from organizing the business requirements — which data, whose responsibility, how far to verify, and what trail to keep on-chain — and turning that into a PoC design and implementation spec. We are happy to talk from the concept stage.

• References: "Oracles" — ethereum.org Developer Documentation (Ethereum Foundation)
• "SoK: Oracles from the Ground Truth to Market Manipulation" — Eskandari, Salehi, Gu, Clark (arXiv:2106.00667)
• Chainlink Whitepapers (Chainlink)
• Pyth Network Documentation (Pyth Network)
• Zod Documentation (Zod) — the TypeScript schema-validation library used for schema validation in this reference design