Alethea Oracle SDK

TypeScript SDK for integrating with Alethea Oracle Network - a decentralized oracle service for prediction markets and external dApps.

Installation

npm install @alethea/oracle-sdk@beta

Quick Start

import { AletheaOracleClient } from '@alethea/oracle-sdk';

// Initialize the client
const client = new AletheaOracleClient({
  registryId: 'your-registry-application-id',
  chainId: 'your-chain-id',
  endpoint: 'https://your-linera-node.com/graphql', // optional
});

// Register a market
const registration = await client.registerMarket({
  question: 'Will it rain tomorrow?',
  outcomes: ['Yes', 'No'],
  deadline: String(Date.now() * 1000 + 86400000000), // 24 hours from now in microseconds
  callbackChainId: 'your-callback-chain-id',
  callbackApplicationId: 'your-callback-app-id',
  callbackMethod: 'handleResolution',
  fee: '100', // Registration fee in tokens
});

console.log('Market registered with ID:', registration.marketId);

// Subscribe to resolution updates
const unsubscribe = await client.subscribeToResolution(
  registration.marketId,
  (resolution, error) => {
    if (error) {
      console.error('Subscription error:', error);
      return;
    }
    
    console.log('Market resolved!');
    console.log('Winning outcome:', resolution.outcome);
    console.log('Confidence:', resolution.confidence);
  },
  {
    pollInterval: 5000, // Poll every 5 seconds
    timeout: 86400000, // Timeout after 24 hours
  }
);

// Later, to stop polling
unsubscribe();

Configuration

OracleConfig

interface OracleConfig {
  registryId: string;        // Registry application ID
  chainId: string;           // Your chain ID
  endpoint?: string;         // GraphQL endpoint (optional, auto-generated if not provided)
  retryAttempts?: number;    // Number of retry attempts (default: 3)
  retryDelay?: number;       // Delay between retries in ms (default: 1000)
}

API Reference

registerMarket(params: RegisterMarketParams): Promise

Register a new market with the oracle.

Parameters:

• question: The market question (required)
• outcomes: Array of possible outcomes (2-10 items)
• deadline: Resolution deadline in microseconds
• callbackChainId: Chain ID for callback
• callbackApplicationId: Application ID for callback
• callbackMethod: Method name to call on resolution
• fee: Registration fee as string

Returns: Promise resolving to MarketRegistration with marketId

getMarketStatus(marketId: number): Promise

Get the current status of a market.

Parameters:

• marketId: The market ID

Returns: Promise resolving to MarketStatus

subscribeToResolution(marketId, callback, options?): Promise

Subscribe to market resolution updates.

Parameters:

• marketId: The market ID to monitor
• callback: Function called when market is resolved or on error
• options: Optional subscription configuration

Returns: Promise resolving to unsubscribe function

Error Handling

The SDK provides typed errors for different failure scenarios:

import { 
  ValidationError, 
  NetworkError, 
  MarketNotFoundError,
  InsufficientFeeError 
} from '@alethea/oracle-sdk';

try {
  await client.registerMarket(params);
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Invalid parameters:', error.message);
  } else if (error instanceof NetworkError) {
    console.error('Network issue:', error.message);
  } else if (error instanceof InsufficientFeeError) {
    console.error('Fee too low:', error.required, 'required');
  }
}

Examples

See the examples directory for complete integration examples.

License

MIT