@ottochain/sdk 0.2.0

package/dist/types/apps/markets/types.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Markets Application Types
+ *
+ * Constants, types, and utilities for the Markets application on OttoChain.
+ *
+ * Core types (MarketType, MarketState, Market, Commitment, Resolution) are
+ * exported from proto-generated types in index.ts.
+ *
+ * @packageDocumentation
+ */
+import { MarketType, MarketState } from '../../generated/ottochain/apps/markets/v1/market_pb.js';
+/**
+ * Commitment direction (for prediction markets)
+ */
+export declare enum CommitmentSide {
+    UNSPECIFIED = 0,
+    YES = 1,
+    NO = 2
+}
+/**
+ * Market configuration type
+ */
+export interface MarketConfig {
+    /** Platform fee as percentage (0.01 = 1%) */
+    platformFeePercent: number;
+    /** Market creator fee as percentage */
+    creatorFeePercent: number;
+    /** Oracle fee as percentage */
+    oracleFeePercent: number;
+    /** Minimum quorum for market validity (in tokens) */
+    minQuorum: bigint;
+    /** Default resolution window in epochs */
+    resolutionWindowEpochs: number;
+    /** Dispute window after resolution in epochs */
+    disputeWindowEpochs: number;
+    /** Minimum commitment amount */
+    minCommitment: bigint;
+    /** Maximum slippage for AMM-style markets */
+    maxSlippagePercent: number;
+}
+/**
+ * Default market configuration
+ */
+export declare const DEFAULT_MARKET_CONFIG: MarketConfig;
+/**
+ * Type-specific market configurations
+ */
+export declare const MARKET_TYPE_CONFIGS: Record<MarketType, Partial<MarketConfig>>;
+/**
+ * Valid transitions for each market state (aligned with proto MarketState enum)
+ */
+export declare const MARKET_TRANSITIONS: Record<MarketState, readonly string[]>;
+/**
+ * Check if a market state is terminal
+ */
+export declare function isTerminalMarketState(state: MarketState): boolean;
+/**
+ * Calculate effective commitment after fees
+ *
+ * @param amount - Raw commitment amount
+ * @param config - Market configuration (uses defaults if not provided)
+ * @returns Net commitment amount after platform fees
+ */
+export declare function calculateNetCommitment(amount: bigint, config?: Partial<MarketConfig>): bigint;
+/**
+ * Calculate total fees for a commitment
+ *
+ * @param amount - Commitment amount
+ * @param marketType - Type of market for type-specific fees
+ * @returns Fee breakdown object
+ */
+export declare function calculateFees(amount: bigint, marketType?: MarketType): {
+    platform: bigint;
+    creator: bigint;
+    oracle: bigint;
+    total: bigint;
+};
+/**
+ * Outcome shares for payout calculation
+ */
+export interface OutcomeShares {
+    /** Total committed to winning outcome */
+    winningPool: bigint;
+    /** Total committed to losing outcome(s) */
+    losingPool: bigint;
+    /** Individual's commitment to winning outcome */
+    userCommitment: bigint;
+}
+/**
+ * Calculate payout for a winning commitment in a prediction market
+ *
+ * Winner receives: their original + proportional share of losing pool (minus fees)
+ *
+ * @param shares - Pool and commitment details
+ * @param marketType - Type of market for fee calculation
+ * @returns Payout amount
+ */
+export declare function calculatePayout(shares: OutcomeShares, marketType?: MarketType): bigint;
+/**
+ * Calculate refund for cancelled market
+ *
+ * @param commitment - Original commitment amount
+ * @param refundFeePercent - Optional fee retained on refund (default 0)
+ * @returns Refund amount
+ */
+export declare function calculateRefund(commitment: bigint, refundFeePercent?: number): bigint;
+/**
+ * Validate a commitment meets market requirements
+ */
+export interface CommitmentValidation {
+    valid: boolean;
+    reason?: string;
+}
+/**
+ * Validate a commitment against market rules
+ */
+export declare function validateCommitment(amount: bigint, marketState: MarketState, config?: Partial<MarketConfig>): CommitmentValidation;
+/**
+ * Calculate crowdfund progress
+ */
+export interface CrowdfundProgress {
+    /** Current total committed */
+    current: bigint;
+    /** Target goal */
+    goal: bigint;
+    /** Percentage complete (0-100) */
+    percentComplete: number;
+    /** Whether goal has been reached */
+    goalReached: boolean;
+}
+/**
+ * Calculate crowdfund campaign progress
+ */
+export declare function calculateCrowdfundProgress(current: bigint, goal: bigint): CrowdfundProgress;
+/**
+ * Tier definition for group buys
+ */
+export interface GroupBuyTier {
+    /** Minimum participants for this tier */
+    minParticipants: number;
+    /** Discount percentage for this tier */
+    discountPercent: number;
+}
+/**
+ * Calculate applicable discount based on participant count
+ */
+export declare function calculateGroupBuyDiscount(participantCount: number, tiers: GroupBuyTier[]): number;
+/**
+ * Check if a value is a valid MarketState
+ */
+export declare function isMarketState(value: unknown): value is MarketState;
+/**
+ * Check if a value is a valid MarketType
+ */
+export declare function isMarketType(value: unknown): value is MarketType;

package/dist/types/apps/oracles/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Oracles Application
+ *
+ * Types and utilities for oracles on OttoChain.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   OracleState,
+ *   Oracle,
+ *   getOracleDefinition,
+ *   DEFAULT_ORACLE_CONFIG
+ * } from '@ottochain/sdk/apps/oracles';
+ *
+ * const oracleDef = getOracleDefinition();
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { OracleState, OracleReputation, SlashingEvent, Oracle, RegisterOracleRequest, ActivateOracleRequest, AddStakeRequest, WithdrawStakeRequest, SlashOracleRequest, WithdrawOracleRequest, OracleDefinition, oracleStateFromJSON, oracleStateToJSON, } from '../../generated/ottochain/apps/oracles/v1/oracle.js';
+export type OracleDefinitionType = 'Oracle';
+export declare const ORACLE_DEFINITIONS: Record<OracleDefinitionType, unknown>;
+/**
+ * Get the oracle state machine definition.
+ */
+export declare function getOracleDefinition(type?: OracleDefinitionType): unknown;
+/**
+ * Default oracle configuration.
+ */
+export declare const DEFAULT_ORACLE_CONFIG: {
+    minStake: number;
+    baseReputation: number;
+    reputationDecay: number;
+};

package/dist/types/apps/oracles/types.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Oracles Application Types
+ *
+ * Constants, types, and utilities for the Oracle system on OttoChain.
+ * Oracles provide truth resolution for markets and disputes.
+ *
+ * Core types (OracleState, Oracle, etc.) are exported from proto-generated
+ * types in index.ts.
+ *
+ * @packageDocumentation
+ */
+import { OracleState } from '../../generated/ottochain/apps/oracles/v1/oracle_pb.js';
+/**
+ * Types of oracle resolutions
+ */
+export declare enum ResolutionType {
+    UNSPECIFIED = 0,
+    /** Binary yes/no outcome */
+    BINARY = 1,
+    /** One of multiple predefined outcomes */
+    MULTI_CHOICE = 2,
+    /** Numeric value (e.g., price) */
+    NUMERIC = 3,
+    /** Free-form attestation */
+    ATTESTATION = 4
+}
+/**
+ * Reasons for slashing oracle stake
+ */
+export declare enum SlashingReason {
+    UNSPECIFIED = 0,
+    /** Failed to submit resolution in time */
+    TIMEOUT = 1,
+    /** Resolution overturned by dispute */
+    INCORRECT_RESOLUTION = 2,
+    /** Evidence of collusion or manipulation */
+    COLLUSION = 3,
+    /** Violation of oracle protocol */
+    PROTOCOL_VIOLATION = 4
+}
+/**
+ * Oracle configuration type
+ */
+export interface OracleConfig {
+    /** Minimum stake required to become an oracle (in base units) */
+    minStake: bigint;
+    /** Stake slashed for timeout (percentage) */
+    timeoutSlashPercent: number;
+    /** Stake slashed for incorrect resolution (percentage) */
+    incorrectSlashPercent: number;
+    /** Stake slashed for collusion (percentage) */
+    collusionSlashPercent: number;
+    /** Stake slashed for protocol violation (percentage) */
+    violationSlashPercent: number;
+    /** Epochs to wait before withdrawal after unstaking */
+    cooldownEpochs: number;
+    /** Base reputation for new oracles */
+    baseReputation: number;
+    /** Minimum reputation to accept high-value markets */
+    highValueThreshold: number;
+    /** Resolution window in epochs */
+    resolutionWindowEpochs: number;
+    /** Challenge window after submission in epochs */
+    challengeWindowEpochs: number;
+    /** Reward percentage from resolved market fees */
+    oracleRewardPercent: number;
+}
+/**
+ * Default oracle configuration
+ */
+export declare const DEFAULT_ORACLE_CONFIG: OracleConfig;
+/**
+ * Slashing percentages by reason
+ */
+export declare const SLASHING_PERCENTAGES: Record<SlashingReason, number>;
+/**
+ * Valid transitions for each oracle state (aligned with proto OracleState enum)
+ */
+export declare const ORACLE_TRANSITIONS: Record<OracleState, readonly string[]>;
+/**
+ * Check if an oracle state is terminal
+ */
+export declare function isTerminalOracleState(state: OracleState): boolean;
+/**
+ * Check if an oracle can accept new assignments
+ */
+export declare function canAcceptAssignment(state: OracleState): boolean;
+/**
+ * Reputation update factors
+ */
+export declare const REPUTATION_DELTAS: {
+    /** Successfully resolved market without challenge */
+    readonly successfulResolution: 5;
+    /** Resolution upheld after challenge */
+    readonly upheldChallenge: 10;
+    /** Resolution overturned (negative) */
+    readonly overturnedResolution: -25;
+    /** Timeout on assigned market (negative) */
+    readonly timeout: -15;
+    /** Collusion detected (negative) */
+    readonly collusion: -100;
+    /** Protocol violation (negative) */
+    readonly violation: -20;
+    /** Bonus for high-value market resolution */
+    readonly highValueBonus: 3;
+};
+/**
+ * Calculate new reputation after an event
+ *
+ * @param currentReputation - Current reputation score
+ * @param delta - Reputation change (positive or negative)
+ * @param minReputation - Minimum reputation floor (default 0)
+ * @returns New reputation score
+ */
+export declare function calculateReputation(currentReputation: number, delta: number, minReputation?: number): number;
+/**
+ * Calculate weighted reputation considering history
+ *
+ * @param baseReputation - Current base reputation
+ * @param successCount - Number of successful resolutions
+ * @param failureCount - Number of failed/overturned resolutions
+ * @returns Weighted reputation score
+ */
+export declare function calculateWeightedReputation(baseReputation: number, successCount: number, failureCount: number): number;
+/**
+ * Check if oracle qualifies for high-value markets
+ */
+export declare function qualifiesForHighValue(reputation: number, stake: bigint, threshold?: number, minStakeMultiplier?: number): boolean;
+/**
+ * Slashing condition definition
+ */
+export interface SlashingCondition {
+    reason: SlashingReason;
+    slashPercent: number;
+    description: string;
+    appealable: boolean;
+    suspensionEpochs: number;
+}
+/**
+ * Predefined slashing conditions
+ */
+export declare const SLASHING_CONDITIONS: Record<SlashingReason, SlashingCondition>;
+/**
+ * Calculate slash amount for a given stake and reason
+ *
+ * @param stake - Oracle's current stake
+ * @param reason - Reason for slashing
+ * @returns Amount to be slashed
+ */
+export declare function calculateSlashAmount(stake: bigint, reason: SlashingReason): bigint;
+/**
+ * Calculate remaining stake after slashing
+ */
+export declare function calculateStakeAfterSlash(stake: bigint, reason: SlashingReason): bigint;
+/**
+ * Oracle candidate for selection
+ */
+export interface OracleCandidate {
+    address: string;
+    reputation: number;
+    stake: bigint;
+    activeAssignments: number;
+    successRate: number;
+}
+/**
+ * Calculate oracle selection score
+ * Higher score = more likely to be selected
+ *
+ * @param candidate - Oracle candidate details
+ * @param marketValue - Value of market to resolve (affects weight for high-value markets)
+ * @returns Selection score
+ */
+export declare function calculateSelectionScore(candidate: OracleCandidate, marketValue?: bigint): number;
+/**
+ * Calculate oracle reward for successful resolution
+ *
+ * @param marketFees - Total fees collected from market
+ * @param rewardPercent - Oracle's reward percentage (default from config)
+ * @returns Oracle reward amount
+ */
+export declare function calculateOracleReward(marketFees: bigint, rewardPercent?: number): bigint;
+/**
+ * Check if a value is a valid OracleState
+ */
+export declare function isOracleState(value: unknown): value is OracleState;
+/**
+ * Check if a value is a valid SlashingReason
+ */
+export declare function isSlashingReason(value: unknown): value is SlashingReason;
+/**
+ * Check if a value is a valid ResolutionType
+ */
+export declare function isResolutionType(value: unknown): value is ResolutionType;

package/dist/types/errors.d.ts

@@ -0,0 +1,221 @@
+/**
+ * Custom Error Classes for OttoChain SDK
+ *
+ * Provides structured error handling with error codes and causes.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Error codes for OttoChain SDK errors
+ */
+export declare enum ErrorCode {
+    /** Unknown or unclassified error */
+    UNKNOWN = "UNKNOWN",
+    /** Network/HTTP connection failure */
+    NETWORK_ERROR = "NETWORK_ERROR",
+    /** Request timeout */
+    NETWORK_TIMEOUT = "NETWORK_TIMEOUT",
+    /** Input validation failed */
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    /** Invalid private key format */
+    INVALID_PRIVATE_KEY = "INVALID_PRIVATE_KEY",
+    /** Invalid public key format */
+    INVALID_PUBLIC_KEY = "INVALID_PUBLIC_KEY",
+    /** Invalid DAG address format */
+    INVALID_ADDRESS = "INVALID_ADDRESS",
+    /** Signature creation failed */
+    SIGNING_ERROR = "SIGNING_ERROR",
+    /** Signature verification failed */
+    VERIFICATION_ERROR = "VERIFICATION_ERROR",
+    /** Transaction rejected by network */
+    TRANSACTION_REJECTED = "TRANSACTION_REJECTED",
+    /** Transaction not found */
+    TRANSACTION_NOT_FOUND = "TRANSACTION_NOT_FOUND",
+    /** Invalid transaction format */
+    INVALID_TRANSACTION = "INVALID_TRANSACTION"
+}
+/**
+ * Base error class for all OttoChain SDK errors
+ *
+ * Provides consistent error structure with:
+ * - Error code for programmatic handling
+ * - Human-readable message
+ * - Optional cause for error chaining
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await signTransaction(data, invalidKey);
+ * } catch (error) {
+ *   if (error instanceof OttoChainError) {
+ *     console.log(error.code);    // 'INVALID_PRIVATE_KEY'
+ *     console.log(error.message); // 'Invalid private key format'
+ *   }
+ * }
+ * ```
+ */
+export declare class OttoChainError extends Error {
+    /** Error code for programmatic handling */
+    readonly code: ErrorCode;
+    /** Original error that caused this error */
+    readonly cause?: Error;
+    constructor(code: ErrorCode, message: string, cause?: Error);
+    /**
+     * Create a string representation of the error
+     */
+    toString(): string;
+    /**
+     * Convert error to a plain object for logging/serialization
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Error thrown when network operations fail
+ *
+ * Covers HTTP failures, connection errors, and timeouts.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.postTransaction(signed);
+ * } catch (error) {
+ *   if (error instanceof NetworkError) {
+ *     console.log(error.statusCode); // 503
+ *     console.log(error.responseBody); // '{"error": "Service unavailable"}'
+ *   }
+ * }
+ * ```
+ */
+export declare class NetworkError extends OttoChainError {
+    /** HTTP status code if applicable */
+    readonly statusCode?: number;
+    /** Response body if available */
+    readonly responseBody?: string;
+    constructor(message: string, statusCode?: number, responseBody?: string, cause?: Error);
+    /**
+     * Create a timeout error
+     */
+    static timeout(timeoutMs: number): NetworkError;
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Error thrown when input validation fails
+ *
+ * Used when function parameters don't meet expected format or constraints.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const keyPair = keyPairFromPrivateKey('invalid');
+ * } catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     console.log(error.field); // 'privateKey'
+ *     console.log(error.value); // 'invalid'
+ *   }
+ * }
+ * ```
+ */
+export declare class ValidationError extends OttoChainError {
+    /** Field that failed validation */
+    readonly field?: string;
+    /** Value that failed validation (sanitized) */
+    readonly value?: unknown;
+    /** Validation details/constraints */
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, options?: {
+        field?: string;
+        value?: unknown;
+        details?: Record<string, unknown>;
+        cause?: Error;
+    });
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Error thrown when cryptographic signing operations fail
+ *
+ * Covers key derivation, signature creation, and related crypto operations.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const signature = await signHash(hash, privateKey);
+ * } catch (error) {
+ *   if (error instanceof SigningError) {
+ *     console.log(error.operation); // 'sign'
+ *   }
+ * }
+ * ```
+ */
+export declare class SigningError extends OttoChainError {
+    /** The operation that failed */
+    readonly operation?: string;
+    constructor(message: string, options?: {
+        operation?: string;
+        cause?: Error;
+    });
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Error thrown when transaction operations fail
+ *
+ * Used when transactions are rejected, not found, or invalid.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.postTransaction(signed);
+ * } catch (error) {
+ *   if (error instanceof TransactionError) {
+ *     console.log(error.transactionHash); // 'abc123...'
+ *     console.log(error.rejectionReason); // 'Insufficient balance'
+ *   }
+ * }
+ * ```
+ */
+export declare class TransactionError extends OttoChainError {
+    /** Transaction hash if available */
+    readonly transactionHash?: string;
+    /** Reason for rejection if available */
+    readonly rejectionReason?: string;
+    constructor(code: ErrorCode, message: string, options?: {
+        transactionHash?: string;
+        rejectionReason?: string;
+        cause?: Error;
+    });
+    /**
+     * Create a transaction rejected error
+     */
+    static rejected(reason: string, transactionHash?: string): TransactionError;
+    /**
+     * Create a transaction not found error
+     */
+    static notFound(transactionHash: string): TransactionError;
+    /**
+     * Create an invalid transaction error
+     */
+    static invalid(message: string, cause?: Error): TransactionError;
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Check if an error is an OttoChain error with a specific code
+ *
+ * @param error - Error to check
+ * @param code - Error code to match
+ * @returns True if error matches the code
+ *
+ * @example
+ * ```typescript
+ * if (isErrorCode(error, ErrorCode.NETWORK_TIMEOUT)) {
+ *   // Retry the request
+ * }
+ * ```
+ */
+export declare function isErrorCode(error: unknown, code: ErrorCode): boolean;
+/**
+ * Wrap an unknown error in an OttoChainError
+ *
+ * @param error - Error to wrap
+ * @param defaultMessage - Default message if error has no message
+ * @returns OttoChainError wrapping the original error
+ */
+export declare function wrapError(error: unknown, defaultMessage?: string): OttoChainError;