Oracles

AiOracle is a resolution mode where the single admin is an off‑chain service that fetches evidence and resolves automatically. On‑chain the contract treats it identically to SingleAdmin — the difference lives in the operational wiring.

Mechanical contract behavior

resolutionMode === 2 requires:

• one oracle-controlled resolver path onchain
• backend-owned signing authority behind that path
• a normal submitResolution call once the oracle has enough evidence

After closeTime, only that address can call submitResolution. Dispute and finalization behave exactly as in SingleAdmin.

What a typical oracle service does

The oracle polls for markets it admins, acts on those past closeTime, and submits resolution transactions with evidence.

import { MarketsClient, MarketStatus } from "@sdk.markets/sdk";

const client = new MarketsClient({ publicClient, walletClient });

for (const address of await findAdminedMarkets(oracleAddress)) {
  const market = await client.markets.get(address);
  if (market.status !== MarketStatus.Closed) continue;

  const { winningOptionIndex, evidenceUrl } = await resolveOffchain(address);

  await client.markets.submitResolution({
    marketAddress: address,
    option: winningOptionIndex,
    evidenceUrl,  // SDK hashes it for you
  });
}

The resolveOffchain step is where your oracle earns its keep. It typically:

1. Pulls structured sources registered alongside the market off‑chain — a list of URLs, APIs, or data providers the host promised would back this market.
2. Queries those sources and reconciles them.
3. Feeds the evidence into an LLM or rules engine that maps the question to an option index.
4. Produces a canonical evidenceUrl — usually a gist, a blob in your own storage, or an IPFS CID containing the raw sources and the reasoning.

Publishing evidence

The evidenceUrl is the part a disputing participant reads. Treat it as a public artifact, not a private log:

• Include the raw source data the oracle ingested (timestamps, response payloads).
• Include the oracle's reasoning in human‑readable form.
• Host at a stable URL. S3, R2, or IPFS are all reasonable. If the URL dies before the challenge window closes, expect disputes.

The on‑chain evidenceHash is keccak256(evidenceUrl) — it anchors the URL text, not its contents. If the URL stays stable but the document at that URL is edited, disputers can present the edit as grounds for voiding. Most oracle services either publish immutable artifacts (IPFS CIDs, content‑addressed S3) or hash the document contents into a second URL parameter.

Failure modes and how to plan for them

• Evidence source is down or ambiguous. The oracle should abstain rather than guess. No resolution means the market stays in Closed until a human intervenes or a fallback path kicks in.
• Oracle key compromised. The attacker can submit a false resolution. Disputes are the on‑chain defense. Rotate the key and rebuild any affected markets with new admin sets.
• Oracle is a single point of failure. For high‑value markets, prefer MultiAdmin with the oracle as one of several admins. The on‑chain mechanism requires unanimity on the winning option index, which prevents a compromised oracle from single‑handedly resolving.

Agent‑based oracles

In practice "oracle" and "agent" are the same thing here — a key‑holding off‑chain process. The distinction is organizational: an oracle is specialized in resolution, while a general agent may also create markets, finalize, and otherwise operate. See agents for custody and key‑management guidance that applies equally.