Soren SDK - Prediction Market Integration

Overview

The Soren SDK allows seamless integration of the Soren Oracle as a truth source for resolving prediction markets. It enables protocols to assert binary questions (claims) and later resolve them using on-chain economic consensus.

This SDK utilizes the SorenCtfAdapter smart contract, acting as middleware between your protocol and the Optimistic Oracle from UMA, with Conditional Tokens Framework (CTF) for payout resolution.

Example: The open-source Gamimarket prediction market integrates with Soren Oracle using this same flow.

✳️ Architecture Summary

Workflow:
initialize() → Optimistic Oracle Challenge Window → resolve() → getExpectedPayouts()

⚠️ Challenge window may involve proposer bonding and optional disputes before final resolution.

🔧 Prerequisites

• Node.js & npm
• Foundry (for contract compilation)
• MetaMask or private key
• RPC provider (Infura, Alchemy, etc.)

🚀 Contract Deployment Steps

1. Deploy Conditional Tokens (CTF)

• Open Remix IDE
• Clone: https://github.com/gnosis/conditional-tokens-contracts.git
• Compile & deploy contracts/ConditionalToken.sol
• Save the deployed contract address

2. Deploy SorenCtfAdapter

git clone [email protected]:appweb123/gami-ctf-adapter-contarcts.git --recurse-submodules
cd gami-ctf-adapter-contarcts
forge install
forge compile

3. Set Environment Variables

Create a .env file:

PK=<YOUR_PRIVATE_KEY>
CTF=<CTF_CONTRACT_ADDRESS>
FINDER=0x80cD9f4C6EDF50CECa790c028296efFE2B0AB6D9
ETH_RPC_URL=<YOUR_RPC_URL>
ETHERSCAN_API_KEY=<YOUR_ETHERSCAN_API_KEY>

4. Deploy Adapter

./deploy/scripts/deploy_adapter.sh

📦 SDK Installation

npm install soren-sdk

🛠️ SDK Usage

1. Import SDK

const { initialize, getSorenCtfAdapter, resolveMarket } = require("soren-sdk");
const { ethers } = require("ethers");
const Web3 = require("web3");

2. Configuration

const CONFIG = {
  RPC_URL: "https://polygon-amoy.infura.io/v3/YOUR_INFURA_KEY",
  PRIVATE_KEY: "your_private_key_here",
  CTF_ADAPTER_ADDRESS: "<Adapter Address>",
  REWARD_TOKEN_ADDRESS: "<Reward Token>"
};

3. Create Provider & Signer

const provider = new ethers.JsonRpcProvider(CONFIG.RPC_URL);
const signer = new ethers.Wallet(CONFIG.PRIVATE_KEY, provider);

🔍 Initialize a Prediction Market

initialize(params: InitializeParams): Promise<TransactionReceipt>

const initParams = {
  ancillaryData: Web3.utils.utf8ToHex(
    '"q:Will Bitcoin price be above $50,000 on December 31, 2024?, description: Market will resolve YES if Bitcoin closes above $50,000 USD on December 31, 2024, 11:59 PM UTC"'
  ),
  rewardTokenAddress: CONFIG.REWARD_TOKEN_ADDRESS,
  reward: "10000000000000000",        // in wei
  proposalBond: "5000000000000000",   // in wei
  liveness: "7200",                   // in seconds
  signer,
  ctfAdapterAddress: CONFIG.CTF_ADAPTER_ADDRESS
};

await initialize(initParams);

📝 Notes on Ancillary Data

• Must be deterministic and verifiable
• Max length: 8139 bytes
• Include clear conditions for resolution

✅ Resolve a Market

resolveMarket(params: ResolveParams): Promise<TransactionReceipt>

const resolveParams = {
  questionId: "0x123...", // ID from event logs or tracking
  signer,
  ctfAdapterAddress: CONFIG.CTF_ADAPTER_ADDRESS
};

await resolveMarket(resolveParams);

🔎 Event Listeners (for Indexing)

Your frontend or backend can index the following events:

• QuestionInitialized
• QuestionResolved
• QuestionReset
• QuestionFlagged / Unflagged
• QuestionPaused / Unpaused
• QuestionEmergencyResolved

These are useful for building UIs or analytics dashboards.

🔁 Responsibilities of Integrators

This SDK abstracts oracle interaction. As a developer, you only need to:

• Encode ancillary data clearly
• Choose appropriate economic parameters
• Call initialize() to post the question
• Call resolve() to finalize
• Handle your own business logic (market creation, payouts, frontend)

📌 Appendix

Example Ancillary Data

q: Was Ethereum above $3000 on May 1st 2025?
description: Market will resolve YES if the closing price was above $3000 on that day.

Best Practices

• Avoid ambiguous or subjective questions
• Use consistent time zones (preferably UTC)
• Proposal bond and liveness must reflect desired dispute protection

📫 Support & Contributions

• Open Issues
• Contact: [email protected]

📄 License

MIT © Soren Oracle Labs