soren-oracle-sdk/README.md

SDK for interacting with Soren CTF Adapter contracts

# 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](https://github.com/appweb123/gami-ctf-adapter-contarcts) 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](https://book.getfoundry.sh/) (for contract compilation)
- MetaMask or private key
- RPC provider (Infura, Alchemy, etc.)

---

## 🚀 Contract Deployment Steps

### 1. Deploy Conditional Tokens (CTF)

- Open [Remix IDE](https://remix.ethereum.org/)
- Clone: `https://github.com/gnosis/conditional-tokens-contracts.git`
- Compile & deploy `contracts/ConditionalToken.sol`
- Save the deployed contract address

### 2. Deploy `SorenCtfAdapter`

```bash
git clone git@bitbucket.org: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:

```bash
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

```bash
./deploy/scripts/deploy_adapter.sh
```

---

## 📦 SDK Installation

```bash
npm install soren-sdk
```

---

## 🛠️ SDK Usage

### 1. Import SDK

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

### 2. Configuration

```javascript
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

```javascript
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>`

```javascript
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>`

```javascript
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](https://bitbucket.org/appweb123/gami-ctf-adapter-contarcts/issues)
* Contact: `team@sorenoracle.com`

---

## 📄 License

MIT © Soren Oracle Labs