klout Oracle v0

The first Social Engagement Oracle powering Social Dynamic Bonding Curves (SDBCs) and tweet‑to‑trade execution on klout.bet - built to make attention verifiable, timestamped, and tradable across platforms.

---

Overview

The Klout Oracle started as a fix for tweet‑to‑trade execution issues - API limits, delayed responses, and inconsistent engagement reads. We needed a way to pull tweet metrics fast, verify them, and make sure every trader saw the same numbers at the same block height.

It quickly became much more: a verifiable attention layer for any app wanting to build on top of real‑time social engagement.

---

Quick Start

What it does

• Pulls engagement metrics from X: likes, reposts, replies, quotes, and views.

• Signs + timestamps each observation off‑chain.

• Publishes a proof on Solana that other contracts can verify.

• Exposes the same data via REST + WebSocket APIs.

Who it’s for

• Bonding curve markets (SDBCs)

• Prediction / attention trading platforms

• Indexers, dashboards, or risk engines

5‑Minute Integration Example (yes example)

import { KloutOracle } from "@klout/oracle-sdk";

const oracle = new KloutOracle({
  endpoint: "https://oracle.klout.bet",
  network: "mainnet-beta",
});

const obs = await oracle.fetchObservation({ tweetId: "1873456789012345678" });

if (await oracle.verifyObservation(obs)) {
  console.log('✅ Valid observation', obs.hash);
  await oracle.submitProof({
    payer, // Solana Keypair
    tweetId: obs.tweetId,
    metrics: obs.metrics,
    proof: obs.proof,
  });
}

Output example:

{
  "tweetId": "1873456789012345678",
  "likes": 125,
  "reposts": 42,
  "replies": 19,
  "hash": "5G6fk3xTz...",
  "verified": true,
  "slot": 265492303
}

---

Why It Exists

We’ve built klout.bet around the idea that attention is an asset. But assets need verifiable data to be priced and traded correctly.

API calls from X aren’t deterministic, you can’t settle a market on something that might change or be rate‑limited. So the Oracle signs every observation, publishes it on‑chain, and gives both traders and developers a common source of truth.

This is what allows tweet‑to‑trade markets to execute fairly and lets other projects use the same engagement proofs without trusting our servers.

---

Architecture

   +-------------+        +----------------+        +-------------------+
   |  Ingestors  |  -->  |  Normalizers   |  -->  |  Signature Engine |
   +-------------+        +----------------+        +-------------------+
          |                         |                          |
          v                         v                          v
   +-------------+        +----------------+        +-------------------+
   |   Relayer   |  -->  | Solana Program |  -->  | REST / WS Clients |
   +-------------+        +----------------+        +-------------------+

• Ingestor: pulls tweet metrics directly from X API shards.

• Normalizer: cleans data, deduplicates, and calculates velocity/decay.

• Signer: hashes and signs observations with Ed25519 keys held in an HSM.

• Relayer: submits Merkle roots to Solana.

• API Layer: streams verified observations over REST + WebSocket.

Program ID: KLOUTORACLE1111111111111111111111111111111 (placeholder)

---

Data Model

interface Observation {
  version: 0;
  tweetId: string;
  capturedAt: string; // ISO timestamp
  metrics: {
    likes: number;
    reposts: number;
    replies: number;
    quotes: number;
    views?: number;
  };
  derived: {
    velocity: number;
    decayFactor: number;
    quality: number;
  };
  nonce: string;
  oraclePubkey: string;
  signature: string;
  hash: string;
}

Example log during signing:

[oracle] collected metrics: likes=102, reposts=36, replies=18, quotes=4
[oracle] derived velocity=0.34, decay=0.87, quality=0.93
[oracle] signing hash=5G6fk3xTz...
[oracle] relayed proof at slot=265492303

---

REST + WS API

REST

GET /v0/observation/:tweetId

Returns latest signed observation.

WebSocket

wss://oracle.klout.bet/v0/stream?tweetId=...

Pushes real‑time engagement updates within ~250ms of change.

Example stream message:

{
  "tweetId": "1873456789012345678",
  "metrics": {"likes": 153, "reposts": 49},
  "velocity": 0.31,
  "hash": "7fGd42...",
  "capturedAt": "2025-11-01T20:11:23Z"
}

---

Verification and Security

• Signatures: Ed25519 over canonical JSON (blake3 hash).

• Freshness: observations expire after 2 minutes unless refreshed.

• Replay Protection: unique (tweetId, nonce) pair.

• Key Rotation: controlled by Klout governance, dual‑sign grace period.

• Hardware Signing: keys inside a dedicated HSM node.

• Merkle Proofs: periodically pinned on-chain for auditability.

---

Deterministic Transforms

We keep transforms public so anyone can recompute the same price:

engagement = 0.3*likes + 0.5*reposts + 0.1*replies + 0.1*quotes
velocity   = d(engagement)/dt
score      = engagement * decay(age_half_life) * quality
price      = base + alpha*score + beta*velocity

All constants (alpha, beta, etc.) are versioned and pinned in the SDK for reproducibility.

---

Tweet‑to‑Trade Execution

This Oracle directly fixes the issues we had with early tweet‑to‑bet orders:

• Before: API delays caused missed fills when a tweet blew up.

• Now: trades settle against the latest verified observation signed and timestamped at block height.

Example:

@tradeklout buy 2 shares
→ Oracle fetches obs_265492303 (valid)
→ Bot executes @ price=0.1234 PTS (hash=5G6fk3xTz...)
→ On-chain verify passes ✅

---

Governance & Roadmap

Governance: parameter updates, key rotations, and curve coefficients are proposed through Klout governance. All SDKs pin to parameter epochs to ensure determinism.

Roadmap:

• v0 — tweet observations → Solana proofs (live)

• v0.1 — creator‑level streams (aggregated per account)

• v0.2 — cross‑chain relay to EVM

• v1 — multi‑platform data (TikTok, YouTube)

---

Contact

• Dev support: @faxonchain on X

---

© Klout.bet — built by humans obsessed with making attention tradable.