overheat-sdk (JS package)

TypeScript SDK for the Overheat oracle on Solana and EVM. This package exposes a class‑based, network‑aware API with no global state.

Installation

npm install overheat-sdk

Core Exports

From overheat-sdk:

• Class
  • OverheatSDK
• Built‑in network configs
  • SOL_DEVNET_CONFIG
  • SOL_STAGING_CONFIG
  • EVM_BASE_SEPOLIA_CONFIG
• Types
  • ChainSigner
  • QuestionInfo
  • RegisterQuestionParams
  • RegisterQuestionResult
  • UpdateAnswerOptions
  • TimeRangeFilter
  • NetworkConfig
• Low‑level modules
  • sol namespace (from js/lib/sol)
  • evm namespace (from js/lib/evm)
  • Arweave helpers (from js/lib/arweave/arweave)

OverheatSDK Overview

import type {
  ChainSigner,
  QuestionInfo,
  RegisterQuestionParams,
  RegisterQuestionResult,
  TimeRangeFilter,
  UpdateAnswerOptions,
  NetworkConfig,
} from "overheat-sdk";

class OverheatSDK {
  readonly config: NetworkConfig;

  constructor(opts: { config: NetworkConfig });

  getAllQuestions(): Promise<QuestionInfo[]>;
  getQuestionByAddress(address: string): Promise<QuestionInfo | null>;
  getQuestionsByTimeRange(opts?: {
    timeRange?: TimeRangeFilter;
  }): Promise<QuestionInfo[]>;

  registerQuestion(
    signer: ChainSigner,
    params: RegisterQuestionParams,
  ): Promise<RegisterQuestionResult>;

  updateAnswer(
    signer: ChainSigner,
    options: UpdateAnswerOptions,
  ): Promise<string>; // returns tx hash
}

Networks

Use one of the built‑in configs or your own NetworkConfig:

• Solana:
  • SOL_DEVNET_CONFIG
  • SOL_STAGING_CONFIG
• EVM:
  • EVM_BASE_SEPOLIA_CONFIG

You can also construct a custom NetworkConfig:

interface NetworkConfig {
  network: string;
  rpcUrl: string;
  wsUrl: string;
  irysNode: string;
  irysGateway: string;
  idlFileName: string;
  explorerCluster: string;
  explorerUrl: string;
  contractAddress?: string;
}

Signers (ChainSigner)

type ChainSigner =
  | { chain: "solana"; wallet: AnchorWallet }
  | { chain: "evm"; privateKeyHex: string };

• For Solana, pass an Anchor Wallet.
• For EVM, pass a private key (hex); the SDK creates a signer internally.

Quick Start – EVM

import {
  OverheatSDK,
  EVM_BASE_SEPOLIA_CONFIG,
  evm,
  type ChainSigner,
  type RegisterQuestionParams,
} from "overheat-sdk";

async function main() {
  const sdk = new OverheatSDK({ config: EVM_BASE_SEPOLIA_CONFIG });

  // Load private key from file
  const { privateKey } = evm.loadWallet("./example-evm-key.key");
  const signer: ChainSigner = { chain: "evm", privateKeyHex: privateKey };

  const params: RegisterQuestionParams = {
    questionText: "Will BTC trade above $100k by 2030‑01‑01?",
    rules: "Resolution according to CoinGecko BTC/USD daily close.",
    expectedExpirationTime: Math.floor(Date.now() / 1000) + 7 * 24 * 60 * 60,
    latestExpirationTime: Math.floor(Date.now() / 1000) + 8 * 24 * 60 * 60,
    category: "Crypto",
    earlyResolutionThreshold: "0.75",
  };

  const result = await sdk.registerQuestion(signer, params);
  console.log("Question address:", result.questionAddress);
  console.log("Tx hash:", result.txHash);
}

void main();

Quick Start – Solana

import {
  OverheatSDK,
  SOL_DEVNET_CONFIG,
  loadWallet,
  type ChainSigner,
} from "overheat-sdk";

async function main() {
  const sdk = new OverheatSDK({ config: SOL_DEVNET_CONFIG });

  const { solWallet } = loadWallet("./example-sol-key.key");
  const signer: ChainSigner = { chain: "solana", wallet: solWallet };

  const questions = await sdk.getAllQuestions();
  console.log(
    JSON.stringify(
      questions,
      (_, v) => (typeof v === "bigint" ? v.toString() : v),
      2,
    ),
  );
}

void main();

Types (summary)

All core types live in js/lib/types.ts and are re‑exported from overheat-sdk:

• QuestionInfo
• RegisterQuestionParams
• RegisterQuestionResult
• UpdateAnswerOptions
• TimeRangeFilter

They are already used in the method signatures of OverheatSDK.

Low‑level Modules

If you need more control, you can use the low‑level sol/evm modules:

import { sol, evm } from "overheat-sdk"; // via index.ts exports
// or
import * as solMod from "overheat-sdk/lib/sol";
import * as evmMod from "overheat-sdk/lib/evm";

Examples:

• Solana:
  • sol.get_all_questions(config)
  • sol.get_question_by_address(id, config)
  • sol.register_question(params, wallet, arweaveId, config)
  • sol.update_answer(id, answer, explanation, wallet, config)
• EVM:
  • evm.get_all_questions(config)
  • evm.get_question_by_address(id, config)
  • evm.register_question(params, arweaveId, privateKey, config)
  • evm.update_answer(privateKey, id, answer, explanation, config)

Wallet Helpers

Solana (sol/wallet.ts)

• loadWallet(path) → { solWallet, solKeypair }
• generateWallet() → { solWallet, solKeypair }
• saveWallet(wallet, path) → void

EVM (evm/wallet.ts)

• evm.loadWallet(path) → { privateKey }
• evm.generateWallet() → { privateKey }
• evm.saveWallet(privateKey, path) → void
• evm.createSigner(privateKey, config) → Signer

Arweave Helpers

From js/lib/arweave/arweave.ts:

• uploadQuestionToArweaveWithSol(questionData, keypair, config)
• uploadQuestionToArweaveWithEvm(questionData, privateKey, config, network)
• fetchQuestionFromArweave(transactionId)

OverheatSDK.registerQuestion already uses these under the hood; you only need them for advanced use cases.

Examples

See the root examples/ folder:

• examples/basic/ – Small scripts with hard‑coded params.
• examples/cli/ – CLI tools using process.argv.

They are the best reference for real‑world usage patterns of this SDK.