@ottochain/sdk 0.2.0

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

@@ -0,0 +1,211 @@
+/**
+ * Oracles Application Types
+ *
+ * Constants, types, and utilities for the Oracle system on OttoChain.
+ * Oracles provide truth resolution for markets and disputes.
+ *
+ * Note: When proto files are generated, enums will move to generated types.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Oracle lifecycle states
+ */
+export declare enum OracleState {
+    UNSPECIFIED = 0,
+    /** Oracle has registered but not yet staked */
+    REGISTERED = 1,
+    /** Oracle is staked and available for assignments */
+    ACTIVE = 2,
+    /** Oracle is currently assigned to resolve a market */
+    ASSIGNED = 3,
+    /** Oracle has submitted a resolution, in challenge period */
+    SUBMITTED = 4,
+    /** Oracle is under review due to dispute */
+    CHALLENGED = 5,
+    /** Oracle is suspended due to slashing */
+    SUSPENDED = 6,
+    /** Oracle has withdrawn stake and exited */
+    WITHDRAWN = 7
+}
+/**
+ * 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
+ */
+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/apps/oracles/types.js

@@ -0,0 +1,306 @@
+"use strict";
+/**
+ * Oracles Application Types
+ *
+ * Constants, types, and utilities for the Oracle system on OttoChain.
+ * Oracles provide truth resolution for markets and disputes.
+ *
+ * Note: When proto files are generated, enums will move to generated types.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isResolutionType = exports.isSlashingReason = exports.isOracleState = exports.calculateOracleReward = exports.calculateSelectionScore = exports.calculateStakeAfterSlash = exports.calculateSlashAmount = exports.SLASHING_CONDITIONS = exports.qualifiesForHighValue = exports.calculateWeightedReputation = exports.calculateReputation = exports.REPUTATION_DELTAS = exports.canAcceptAssignment = exports.isTerminalOracleState = exports.ORACLE_TRANSITIONS = exports.SLASHING_PERCENTAGES = exports.DEFAULT_ORACLE_CONFIG = exports.SlashingReason = exports.ResolutionType = exports.OracleState = void 0;
+// ---------------------------------------------------------------------------
+// Enums (will be replaced by proto-generated versions)
+// ---------------------------------------------------------------------------
+/**
+ * Oracle lifecycle states
+ */
+var OracleState;
+(function (OracleState) {
+    OracleState[OracleState["UNSPECIFIED"] = 0] = "UNSPECIFIED";
+    /** Oracle has registered but not yet staked */
+    OracleState[OracleState["REGISTERED"] = 1] = "REGISTERED";
+    /** Oracle is staked and available for assignments */
+    OracleState[OracleState["ACTIVE"] = 2] = "ACTIVE";
+    /** Oracle is currently assigned to resolve a market */
+    OracleState[OracleState["ASSIGNED"] = 3] = "ASSIGNED";
+    /** Oracle has submitted a resolution, in challenge period */
+    OracleState[OracleState["SUBMITTED"] = 4] = "SUBMITTED";
+    /** Oracle is under review due to dispute */
+    OracleState[OracleState["CHALLENGED"] = 5] = "CHALLENGED";
+    /** Oracle is suspended due to slashing */
+    OracleState[OracleState["SUSPENDED"] = 6] = "SUSPENDED";
+    /** Oracle has withdrawn stake and exited */
+    OracleState[OracleState["WITHDRAWN"] = 7] = "WITHDRAWN";
+})(OracleState || (exports.OracleState = OracleState = {}));
+/**
+ * Types of oracle resolutions
+ */
+var ResolutionType;
+(function (ResolutionType) {
+    ResolutionType[ResolutionType["UNSPECIFIED"] = 0] = "UNSPECIFIED";
+    /** Binary yes/no outcome */
+    ResolutionType[ResolutionType["BINARY"] = 1] = "BINARY";
+    /** One of multiple predefined outcomes */
+    ResolutionType[ResolutionType["MULTI_CHOICE"] = 2] = "MULTI_CHOICE";
+    /** Numeric value (e.g., price) */
+    ResolutionType[ResolutionType["NUMERIC"] = 3] = "NUMERIC";
+    /** Free-form attestation */
+    ResolutionType[ResolutionType["ATTESTATION"] = 4] = "ATTESTATION";
+})(ResolutionType || (exports.ResolutionType = ResolutionType = {}));
+/**
+ * Reasons for slashing oracle stake
+ */
+var SlashingReason;
+(function (SlashingReason) {
+    SlashingReason[SlashingReason["UNSPECIFIED"] = 0] = "UNSPECIFIED";
+    /** Failed to submit resolution in time */
+    SlashingReason[SlashingReason["TIMEOUT"] = 1] = "TIMEOUT";
+    /** Resolution overturned by dispute */
+    SlashingReason[SlashingReason["INCORRECT_RESOLUTION"] = 2] = "INCORRECT_RESOLUTION";
+    /** Evidence of collusion or manipulation */
+    SlashingReason[SlashingReason["COLLUSION"] = 3] = "COLLUSION";
+    /** Violation of oracle protocol */
+    SlashingReason[SlashingReason["PROTOCOL_VIOLATION"] = 4] = "PROTOCOL_VIOLATION";
+})(SlashingReason || (exports.SlashingReason = SlashingReason = {}));
+/**
+ * Default oracle configuration
+ */
+exports.DEFAULT_ORACLE_CONFIG = {
+    minStake: 10000n,
+    timeoutSlashPercent: 0.05,
+    incorrectSlashPercent: 0.25,
+    collusionSlashPercent: 1.0,
+    violationSlashPercent: 0.10,
+    cooldownEpochs: 48,
+    baseReputation: 50,
+    highValueThreshold: 100,
+    resolutionWindowEpochs: 12,
+    challengeWindowEpochs: 6,
+    oracleRewardPercent: 0.01,
+};
+/**
+ * Slashing percentages by reason
+ */
+exports.SLASHING_PERCENTAGES = {
+    [SlashingReason.UNSPECIFIED]: 0,
+    [SlashingReason.TIMEOUT]: exports.DEFAULT_ORACLE_CONFIG.timeoutSlashPercent,
+    [SlashingReason.INCORRECT_RESOLUTION]: exports.DEFAULT_ORACLE_CONFIG.incorrectSlashPercent,
+    [SlashingReason.COLLUSION]: exports.DEFAULT_ORACLE_CONFIG.collusionSlashPercent,
+    [SlashingReason.PROTOCOL_VIOLATION]: exports.DEFAULT_ORACLE_CONFIG.violationSlashPercent,
+};
+// ---------------------------------------------------------------------------
+// State Machine Transitions
+// ---------------------------------------------------------------------------
+/**
+ * Valid transitions for each oracle state
+ */
+exports.ORACLE_TRANSITIONS = {
+    [OracleState.UNSPECIFIED]: [],
+    [OracleState.REGISTERED]: ['stake', 'withdraw'],
+    [OracleState.ACTIVE]: ['assign', 'unstake'],
+    [OracleState.ASSIGNED]: ['submit', 'timeout'],
+    [OracleState.SUBMITTED]: ['finalize', 'challenge'],
+    [OracleState.CHALLENGED]: ['uphold', 'overturn'],
+    [OracleState.SUSPENDED]: ['begin_probation', 'permanent_ban'],
+    [OracleState.WITHDRAWN]: [], // Terminal state
+};
+/**
+ * Check if an oracle state is terminal
+ */
+function isTerminalOracleState(state) {
+    return state === OracleState.WITHDRAWN;
+}
+exports.isTerminalOracleState = isTerminalOracleState;
+/**
+ * Check if an oracle can accept new assignments
+ */
+function canAcceptAssignment(state) {
+    return state === OracleState.ACTIVE;
+}
+exports.canAcceptAssignment = canAcceptAssignment;
+// ---------------------------------------------------------------------------
+// Reputation Calculations
+// ---------------------------------------------------------------------------
+/**
+ * Reputation update factors
+ */
+exports.REPUTATION_DELTAS = {
+    /** Successfully resolved market without challenge */
+    successfulResolution: 5,
+    /** Resolution upheld after challenge */
+    upheldChallenge: 10,
+    /** Resolution overturned (negative) */
+    overturnedResolution: -25,
+    /** Timeout on assigned market (negative) */
+    timeout: -15,
+    /** Collusion detected (negative) */
+    collusion: -100,
+    /** Protocol violation (negative) */
+    violation: -20,
+    /** Bonus for high-value market resolution */
+    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
+ */
+function calculateReputation(currentReputation, delta, minReputation = 0) {
+    return Math.max(minReputation, currentReputation + delta);
+}
+exports.calculateReputation = calculateReputation;
+/**
+ * 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
+ */
+function calculateWeightedReputation(baseReputation, successCount, failureCount) {
+    const totalAttempts = successCount + failureCount;
+    if (totalAttempts === 0)
+        return baseReputation;
+    const successRate = successCount / totalAttempts;
+    const experienceMultiplier = Math.min(1 + Math.log10(totalAttempts + 1) * 0.2, 1.5);
+    return Math.round(baseReputation * successRate * experienceMultiplier);
+}
+exports.calculateWeightedReputation = calculateWeightedReputation;
+/**
+ * Check if oracle qualifies for high-value markets
+ */
+function qualifiesForHighValue(reputation, stake, threshold = exports.DEFAULT_ORACLE_CONFIG.highValueThreshold, minStakeMultiplier = 5) {
+    return (reputation >= threshold &&
+        stake >= exports.DEFAULT_ORACLE_CONFIG.minStake * BigInt(minStakeMultiplier));
+}
+exports.qualifiesForHighValue = qualifiesForHighValue;
+/**
+ * Predefined slashing conditions
+ */
+exports.SLASHING_CONDITIONS = {
+    [SlashingReason.UNSPECIFIED]: {
+        reason: SlashingReason.UNSPECIFIED,
+        slashPercent: 0,
+        description: 'No slashing',
+        appealable: false,
+        suspensionEpochs: 0,
+    },
+    [SlashingReason.TIMEOUT]: {
+        reason: SlashingReason.TIMEOUT,
+        slashPercent: exports.DEFAULT_ORACLE_CONFIG.timeoutSlashPercent,
+        description: 'Failed to submit resolution within deadline',
+        appealable: true,
+        suspensionEpochs: 12,
+    },
+    [SlashingReason.INCORRECT_RESOLUTION]: {
+        reason: SlashingReason.INCORRECT_RESOLUTION,
+        slashPercent: exports.DEFAULT_ORACLE_CONFIG.incorrectSlashPercent,
+        description: 'Resolution overturned by dispute process',
+        appealable: true,
+        suspensionEpochs: 48,
+    },
+    [SlashingReason.COLLUSION]: {
+        reason: SlashingReason.COLLUSION,
+        slashPercent: exports.DEFAULT_ORACLE_CONFIG.collusionSlashPercent,
+        description: 'Evidence of collusion or market manipulation',
+        appealable: false,
+        suspensionEpochs: -1, // Permanent
+    },
+    [SlashingReason.PROTOCOL_VIOLATION]: {
+        reason: SlashingReason.PROTOCOL_VIOLATION,
+        slashPercent: exports.DEFAULT_ORACLE_CONFIG.violationSlashPercent,
+        description: 'Violation of oracle operating protocol',
+        appealable: true,
+        suspensionEpochs: 24,
+    },
+};
+/**
+ * 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
+ */
+function calculateSlashAmount(stake, reason) {
+    const condition = exports.SLASHING_CONDITIONS[reason];
+    return (stake * BigInt(Math.floor(condition.slashPercent * 10000))) / 10000n;
+}
+exports.calculateSlashAmount = calculateSlashAmount;
+/**
+ * Calculate remaining stake after slashing
+ */
+function calculateStakeAfterSlash(stake, reason) {
+    return stake - calculateSlashAmount(stake, reason);
+}
+exports.calculateStakeAfterSlash = calculateStakeAfterSlash;
+/**
+ * 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
+ */
+function calculateSelectionScore(candidate, marketValue = 0n) {
+    const reputationWeight = 0.4;
+    const stakeWeight = 0.3;
+    const successWeight = 0.2;
+    const loadWeight = 0.1;
+    // Normalize stake to 0-100 range (assuming 1M max)
+    const normalizedStake = Math.min(Number(candidate.stake / 10000n), 100);
+    // Load penalty (fewer active = better)
+    const loadScore = Math.max(0, 100 - candidate.activeAssignments * 20);
+    // High-value market bonus for qualified oracles
+    const highValueBonus = marketValue > 100000n &&
+        qualifiesForHighValue(candidate.reputation, candidate.stake) ? 10 : 0;
+    return (candidate.reputation * reputationWeight +
+        normalizedStake * stakeWeight +
+        candidate.successRate * 100 * successWeight +
+        loadScore * loadWeight +
+        highValueBonus);
+}
+exports.calculateSelectionScore = calculateSelectionScore;
+// ---------------------------------------------------------------------------
+// Reward Calculations
+// ---------------------------------------------------------------------------
+/**
+ * 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
+ */
+function calculateOracleReward(marketFees, rewardPercent = exports.DEFAULT_ORACLE_CONFIG.oracleRewardPercent) {
+    return (marketFees * BigInt(Math.floor(rewardPercent * 10000))) / 10000n;
+}
+exports.calculateOracleReward = calculateOracleReward;
+// ---------------------------------------------------------------------------
+// Type Guards
+// ---------------------------------------------------------------------------
+/**
+ * Check if a value is a valid OracleState
+ */
+function isOracleState(value) {
+    return typeof value === 'number' && value in OracleState;
+}
+exports.isOracleState = isOracleState;
+/**
+ * Check if a value is a valid SlashingReason
+ */
+function isSlashingReason(value) {
+    return typeof value === 'number' && value in SlashingReason;
+}
+exports.isSlashingReason = isSlashingReason;
+/**
+ * Check if a value is a valid ResolutionType
+ */
+function isResolutionType(value) {
+    return typeof value === 'number' && value in ResolutionType;
+}
+exports.isResolutionType = isResolutionType;

package/dist/cjs/apps/contracts/index.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Contracts Application
+ *
+ * Types and utilities for smart contracts on OttoChain.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   ContractState,
+ *   Contract,
+ *   getContractDefinition,
+ *   getEscrowDefinition
+ * } from '@ottochain/sdk/apps/contracts';
+ *
+ * const contractDef = getContractDefinition();
+ * ```
+ *
+ * @packageDocumentation
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getEscrowDefinition = exports.getContractDefinition = exports.CONTRACT_DEFINITIONS = exports.contractStateToJSON = exports.contractStateFromJSON = exports.ContractDefinition = exports.DisputeContractRequest = exports.RejectContractRequest = exports.CompleteContractRequest = exports.AcceptContractRequest = exports.ProposeContractRequest = exports.Contract = exports.ContractState = void 0;
+// Re-export generated protobuf types (source of truth)
+var contract_js_1 = require("../../generated/ottochain/apps/contracts/v1/contract.js");
+Object.defineProperty(exports, "ContractState", { enumerable: true, get: function () { return contract_js_1.ContractState; } });
+Object.defineProperty(exports, "Contract", { enumerable: true, get: function () { return contract_js_1.Contract; } });
+Object.defineProperty(exports, "ProposeContractRequest", { enumerable: true, get: function () { return contract_js_1.ProposeContractRequest; } });
+Object.defineProperty(exports, "AcceptContractRequest", { enumerable: true, get: function () { return contract_js_1.AcceptContractRequest; } });
+Object.defineProperty(exports, "CompleteContractRequest", { enumerable: true, get: function () { return contract_js_1.CompleteContractRequest; } });
+Object.defineProperty(exports, "RejectContractRequest", { enumerable: true, get: function () { return contract_js_1.RejectContractRequest; } });
+Object.defineProperty(exports, "DisputeContractRequest", { enumerable: true, get: function () { return contract_js_1.DisputeContractRequest; } });
+Object.defineProperty(exports, "ContractDefinition", { enumerable: true, get: function () { return contract_js_1.ContractDefinition; } });
+Object.defineProperty(exports, "contractStateFromJSON", { enumerable: true, get: function () { return contract_js_1.contractStateFromJSON; } });
+Object.defineProperty(exports, "contractStateToJSON", { enumerable: true, get: function () { return contract_js_1.contractStateToJSON; } });
+// ---------------------------------------------------------------------------
+// State Machine JSON Definitions
+// ---------------------------------------------------------------------------
+const contract_json_1 = __importDefault(require("./state-machines/contract.json"));
+const escrow_json_1 = __importDefault(require("./state-machines/escrow.json"));
+exports.CONTRACT_DEFINITIONS = {
+    Contract: contract_json_1.default,
+    Escrow: escrow_json_1.default,
+};
+/**
+ * Get the contract state machine definition.
+ */
+function getContractDefinition() {
+    return contract_json_1.default;
+}
+exports.getContractDefinition = getContractDefinition;
+/**
+ * Get the escrow state machine definition.
+ */
+function getEscrowDefinition() {
+    return escrow_json_1.default;
+}
+exports.getEscrowDefinition = getEscrowDefinition;