Soracles

An on-chain ADA price prediction game on Cardano.

Predict the future price of ADA against the Charli3 oracle. Predictions are scored 24 hours later and points convert to ADA payouts at tier thresholds.

🔮 Live game: https://server-tools.grahamsnumberplus1.com/Oracle_Project/oracle-game.html 🐦 Twitter: @GrahamsNoPlus1 🏊 Stake pool: GNP1

---

Highlights

• ✅ Free to play — no payment required
• ✅ No wallet connection needed — addresses entered as plain text (read-only)
• ✅ Fully on-chain — predictions, scoring, and payouts all live on Cardano mainnet
• ✅ Aiken-compiled Plutus V3 validator (Conway era)
• ✅ Charli3 oracle integration — public on-chain ADA/USD price feed
• ✅ Skill-based — predictions scored against a future oracle price
• ✅ Open source — verify the code yourself

---

How it works

1. A player submits a USD price prediction for ADA
2. The prediction is stored in the smart contract's datum
3. 24 hours later, a scheduled transaction (TX2) reads the latest Charli3 price and awards points based on accuracy (5-tier graded scoring)
4. When a player accumulates enough points (4 payout tiers), a scheduled transaction (TX3) pays them ADA from the admin wallet (5, 10, 20, or 100 ADA)
5. Inactive players are removed (TX4) to free slots — the contract supports 16 concurrent active users

Scoring tiers

Tier	Accuracy (vs oracle)	Points awarded
Exact	0 micro-cents	50,000
Excellent	≤ ±0.0002 USD	10,000
Great	≤ ±0.001 USD	1,000
Good	≤ ±0.01 USD	100
Okay	≤ ±0.1 USD	50
Miss	> ±0.1 USD	0

Payout tiers

Tier	Banked points	ADA paid
Tier 1	50,000+	100 ADA
Tier 2	10,000+	20 ADA
Tier 3	1,000+	10 ADA
Tier 4	200+	5 ADA

---

Live on-chain references

Item	Value
Script address	addr1w9rm69uacrw8rrlkes0rtz7c6wlshh34hpfn2652tqy6gmchp6reu
Script hash	47bd179dc0dc718ff6cc1e358bd8d3bf0bde35b853356a8a5809a46f
Admin wallet	addr1v9l0d2448cq5dmk3qudn35fd9d48dngvrlacs38wsxgqetgzhuxal
Charli3 OracleFeed UTxO	addr1wyvxns52tsgz8ggvrh4np5gjyfk0g5fshqq2ytvu9t7pe8qp3adw6
Charli3 policy ID	08c56c0fa73748a23c3bc1d9e6a60a4187416fc4ff8fe3475506990e
Plutus version	V3

---

Verify the smart contract yourself

The trust-critical part of Soracles is the Aiken validator. You can independently rebuild from source and confirm that the compiled script hash matches the live on-chain contract.

# Install Aiken (one-time)
curl -sSfL https://install.aiken-lang.org | bash

# Clone and build
git clone https://github.com/GNP1-dev/soracles.git
cd soracles/aiken
aiken build

# Inspect the compiled script hash
cat plutus.json | python3 -c "import json,sys; d=json.load(sys.stdin); print('script_hash:', d['validators'][0]['hash'])"

Expected output:

script_hash: 47bd179dc0dc718ff6cc1e358bd8d3bf0bde35b853356a8a5809a46f

If the hash matches, the source you just compiled is byte-identical to the live contract on Cardano mainnet.

---

Repository layout

soracles/
├── aiken/                    # Aiken smart contract source
│   ├── aiken.toml            # Aiken project config
│   ├── plutus.json           # Compiled output (regenerated by `aiken build`)
│   ├── lib/oracle_datum.ak   # Charli3 datum parser (Apache 2.0, see NOTICE)
│   └── validators/oracle_prediction.ak  # Main validator (MIT)
├── frontend/                 # Static HTML/CSS/JS served by Apache
├── backend/                  # PHP API endpoints
├── cron/                     # Wrapper scripts called by cron (tx2/3/4)
├── datums/                   # Datum JSON templates for cardano-cli
├── plutus-binaries/          # Compiled .plutus file (matches aiken/plutus.json output)
└── docs/                     # Architecture notes and handover manual

---

Architecture

┌──────────────┐                  ┌──────────────────┐
│   Player     │  HTTP POST       │  PHP Backend     │
│   browser    ├─────────────────►│  on Apache       │
└──────────────┘  (prediction +   └────────┬─────────┘
                   ADA address)            │
                                           │  cardano-cli
                                           ▼
                                  ┌──────────────────┐
                                  │  Cardano node    │
                                  │  (gnp1 server)   │
                                  └────────┬─────────┘
                                           │  TX submission
                                           ▼
                                  ┌──────────────────┐         ┌──────────────────┐
                                  │ Cardano mainnet  │◄────────│ Charli3 oracle   │
                                  │ Soracles datum   │  reads  │ ADA/USD feed     │
                                  └──────────────────┘         └──────────────────┘

Transaction flow

TX	Triggered by	Schedule	What it does
Register	Player	On demand	Adds player to active list with their ADA address
Submit	Player	On demand	Adds a prediction to the on-chain datum
TX2 (Award)	Cron	00:15 / 06:15 / 12:15 / 18:15 UTC	Scores mature predictions vs Charli3 price, awards points
TX3 (Payout)	Cron	06:25 UTC on days 1, 4, 7, 10, 13, 16, 19, 22, 25, 28	Pays out ADA to players who hit payout tier thresholds
TX4 (Remove)	Cron	06:35 UTC on days 2, 5, 8, 11, 14, 17, 20, 23, 26, 29	Removes inactive players to free slots

All times UTC. System timezone must be UTC (timedatectl set-timezone UTC) — cron evaluates schedules against system TZ.

---

Running your own instance

⚠️ This codebase is published primarily for transparency and audit, not as a turnkey deployment. Setting up your own instance requires:

• A Cardano node with cardano-cli
• An Apache/PHP server
• A dedicated admin wallet funded with ADA for fees + payouts
• Familiarity with Cardano CLI workflows and Plutus contract deployment

Setup outline

1. Compile and deploy your own validator (script hash will differ from ours; that's expected — you should deploy your own contract, not consume our datum)
2. Set up Apache to serve frontend/ and backend/ under a single URL prefix (e.g. /Oracle_Project/)
3. Set up directory layout: by default the PHP files reference /home/russell/Oracle_Project_v86/ for state files, plutus binaries, and wallet keys. You'll either need to:
   • Use the same paths on your server, or
   • Find and replace /home/russell/Oracle_Project_v86 in the PHP files with your own paths
4. Create the admin config file at /home/russell/giveaway-config.json (or your equivalent path), schema:

   {
     "admin_password": "your-chosen-password-here"
   }

   This is read by oracle-admin-auth.php to gate the admin dashboard. Never commit this file.
5. Initialize state JSONs (empty) at the configured paths:

   echo "{}" > codes/oracle_valid_codes.json
   echo "{}" > codes/oracle_registrations.json
   echo "{}" > codes/oracle_leaderboard.json
   echo "{}" > codes/oracle_predictions.json
   echo "{}" > codes/oracle_code_usage.json
   echo "[]" > codes/oracle_leaderboard_history.json
   

6. Submit the initial lock transaction to put the empty datum + 20 ADA into your script address. Use the cardano-cli pattern documented in docs/HANDOVER-MANUAL.md.
7. Install cron entries referencing cron/oracle-cron-tx{2,3,4}.sh on the schedule described above
8. Generate access codes in oracle_valid_codes.json and distribute as you wish

Files NOT included in this repo (and why)

File / dir	Why excluded
*.skey / wallet keys	Operator-specific, NEVER published
giveaway-config.json	Contains the admin password
oracle_*.json state files	Contains live user wallet addresses, predictions, leaderboard history
cache-*.json	Runtime caches, regenerated automatically
logs/	Operator-specific runtime logs
Aiken build/ directory	Build artifacts, regenerated by aiken build

---

Charli3 oracle dependency

Soracles reads ADA/USD price data from Charli3's public on-chain oracle. This is public data on the Cardano blockchain — no agreement with Charli3 is required to consume it. We gratefully acknowledge Charli3 for providing this public infrastructure.

The aiken/lib/oracle_datum.ak module is derived from Charli3's public oracle-datum-lib and used under the Apache License 2.0. See NOTICE for full attribution.

Oracle outage contingency

If Charli3 were to discontinue their public feed, Soracles would migrate to:

1. First fallback: An alternative public Cardano oracle (e.g., Orcfax). This requires a new contract version (V87) with the alternative oracle's script address baked in.
2. Second fallback: Self-sourced price feeder. The admin would fetch ADA/USD from multiple public APIs (CoinGecko / Binance / Kraken), average them, and write to a dedicated oracle datum on a fixed schedule. Cost: ~0.8 ADA/day. The cron code would be open-sourced alongside this change for full audit.

Neither fallback is currently active — Charli3 is the live oracle source.

---

Licence

• Original Soracles code: MIT License (see LICENSE)
• aiken/lib/oracle_datum.ak: Apache License 2.0 (derived from Charli3's reference library — see NOTICE)

You're free to fork, modify, and run your own instance under these terms.

---

Not affiliated with

Soracles is not affiliated with, endorsed by, or sponsored by:

• Charli3 (we are a consumer of their public oracle)
• Input Output Global (IOG)
• The Cardano Foundation
• Emurgo

Soracles is an independent project operated by GNP1 Stake Pool (Russell Wallace) as a free educational demonstration.

---

About GNP1

GNP1 (GrahamsNumberPlus1) is a Cardano stake pool operated since October 2020, based in Harrogate, UK. The pool donates a share of rewards to mental health charities — over £4,100 contributed since 2021.

If Soracles entertains or educates you, consider delegating to GNP1. It's not required to play — but it does help fund the charity contributions.

---

Disclaimer

This is experimental software. The smart contract has been tested but may still contain bugs. By using Soracles or this code, you accept that we cannot be held liable for contract failures or payout issues, to the extent permitted by law. See the in-game disclaimer (frontend/oracle-game.html, accessible via the "⚠️ Disclaimers" button) for the full terms.

Nothing in this game or repository constitutes financial advice. ADA price predictions in Soracles are scored against a stale oracle snapshot and are not market forecasts.