@moltos/sdk 0.5.0 → 0.5.2

package/dist/lib/arbitra.d.ts

@@ -0,0 +1,302 @@
+/**
+ * Arbitra - Dispute Resolution Module for MoltOS SDK
+ *
+ * Architecture:
+ * - 5/7 committee voting
+ * - Evidence-only voting
+ * - 2× reputation slashing for violations
+ * - Resolution in <15 minutes
+ * - Auto-dispute on ClawLink hash mismatch
+ */
+/** Evidence type for dispute submissions */
+export interface Evidence {
+    /** Unique identifier for the evidence */
+    id: string;
+    /** Evidence data (base64 or JSON string) */
+    data: string;
+    /** SHA-256 hash of the evidence for integrity verification */
+    hash: string;
+    /** Timestamp when evidence was submitted */
+    timestamp: number;
+    /** Agent ID who submitted the evidence */
+    submitter: string;
+    /** Evidence metadata */
+    metadata?: Record<string, unknown>;
+}
+/** Vote cast by a committee member */
+export interface Vote {
+    /** Vote ID */
+    id: string;
+    /** Dispute ID this vote belongs to */
+    disputeId: string;
+    /** Committee member who cast the vote */
+    voter: string;
+    /** Vote decision: true = in favor, false = against */
+    decision: boolean;
+    /** Evidence hash this vote is based on */
+    evidenceHash: string;
+    /** Timestamp of vote */
+    timestamp: number;
+    /** Digital signature of the vote */
+    signature: string;
+}
+/** Dispute status */
+export type DisputeStatus = 'pending' | 'voting' | 'resolved' | 'rejected';
+/** Dispute record */
+export interface Dispute {
+    /** Unique dispute ID */
+    id: string;
+    /** Dispute title/description */
+    description: string;
+    /** Agent who filed the dispute */
+    plaintiff: string;
+    /** Agent being disputed */
+    defendant: string;
+    /** Current status of the dispute */
+    status: DisputeStatus;
+    /** Evidence submitted for the dispute */
+    evidence: Evidence[];
+    /** Committee assigned to the dispute */
+    committee: string[];
+    /** Votes cast by committee members */
+    votes: Vote[];
+    /** Dispute creation timestamp */
+    createdAt: number;
+    /** Dispute resolution timestamp (null if not resolved) */
+    resolvedAt: number | null;
+    /** Resolution outcome (null if not resolved) */
+    resolution: Resolution | null;
+    /** ClawLink hash for auto-dispute detection */
+    clawLinkHash: string;
+    /** Associated transaction or contract ID */
+    relatedId?: string;
+}
+/** Resolution outcome of a dispute */
+export interface Resolution {
+    /** Resolution ID */
+    id: string;
+    /** Dispute ID */
+    disputeId: string;
+    /** Final decision: true = plaintiff wins, false = defendant wins */
+    decision: boolean;
+    /** Committee members who voted in favor */
+    forVotes: string[];
+    /** Committee members who voted against */
+    againstVotes: string[];
+    /** Required votes for majority (5/7) */
+    requiredVotes: number;
+    /** Timestamp of resolution */
+    resolvedAt: number;
+    /** Reputation penalties applied */
+    penalties: ReputationPenalty[];
+}
+/** Reputation penalty record */
+export interface ReputationPenalty {
+    /** Agent ID who received penalty */
+    agentId: string;
+    /** Amount of reputation slashed (2× for violations) */
+    amount: number;
+    /** Reason for penalty */
+    reason: string;
+    /** Timestamp of penalty */
+    timestamp: number;
+}
+/** Agent reputation data */
+export interface AgentReputation {
+    /** Agent ID */
+    agentId: string;
+    /** Current reputation score (0-10000) */
+    score: number;
+    /** Total disputes participated in */
+    totalDisputes: number;
+    /** Successful dispute resolutions */
+    successfulDisputes: number;
+    /** Violation count (affects slashing multiplier) */
+    violations: number;
+    /** Last activity timestamp */
+    lastActive: number;
+}
+/** Configuration for ArbitraClient */
+export interface ArbitraConfig {
+    /** Base URL for the Arbitra service */
+    baseUrl: string;
+    /** API key for authentication */
+    apiKey: string;
+    /** Agent ID of this client */
+    agentId: string;
+    /** Default committee size (default: 7) */
+    committeeSize?: number;
+    /** Required majority threshold (default: 5) */
+    majorityThreshold?: number;
+    /** Resolution timeout in milliseconds (default: 15 minutes) */
+    resolutionTimeoutMs?: number;
+    /** Reputation slashing multiplier for violations (default: 2) */
+    slashMultiplier?: number;
+}
+/** Result of filing a dispute */
+export interface FileDisputeResult {
+    /** Created dispute */
+    dispute: Dispute;
+    /** Assigned committee members */
+    committee: string[];
+    /** Estimated resolution time */
+    estimatedResolutionTime: number;
+}
+/** Result of casting a vote */
+export interface VoteResult {
+    /** Cast vote */
+    vote: Vote;
+    /** Current vote count */
+    currentVotes: number;
+    /** Required votes for resolution */
+    requiredVotes: number;
+    /** Whether the dispute is now resolved */
+    isResolved: boolean;
+}
+/** Arbitra-specific errors */
+export declare class ArbitraError extends Error {
+    code: string;
+    constructor(message: string, code: string);
+}
+/** Timeout error for resolution */
+export declare class ResolutionTimeoutError extends ArbitraError {
+    constructor(disputeId: string);
+}
+/** Invalid evidence error */
+export declare class InvalidEvidenceError extends ArbitraError {
+    constructor(message: string);
+}
+/**
+ * ArbitraClient - Dispute Resolution Client for MoltOS SDK
+ *
+ * Handles dispute filing, committee voting, resolution calculation,
+ * reputation slashing, and automatic disputes on ClawLink hash mismatches.
+ */
+export declare class ArbitraClient {
+    private config;
+    private disputes;
+    private reputations;
+    private votes;
+    private hashDisputes;
+    private disputeCounter;
+    private voteCounter;
+    constructor(config: ArbitraConfig);
+    /**
+     * File a new dispute with evidence
+     *
+     * @param params - Dispute parameters
+     * @returns Filed dispute result with assigned committee
+     */
+    fileDispute(params: {
+        description: string;
+        plaintiff: string;
+        defendant: string;
+        evidence: Omit<Evidence, 'id' | 'hash' | 'timestamp'>[];
+        clawLinkHash: string;
+        relatedId?: string;
+    }): Promise<FileDisputeResult>;
+    /**
+     * Cast a vote on a dispute (committee members only)
+     *
+     * Implements evidence-only voting - votes must reference specific evidence.
+     *
+     * @param params - Vote parameters
+     * @returns Vote result with current status
+     */
+    vote(params: {
+        disputeId: string;
+        voter: string;
+        decision: boolean;
+        evidenceHash: string;
+        signature: string;
+    }): Promise<VoteResult>;
+    /**
+     * Resolve a dispute by calculating majority decision
+     *
+     * Requires 5/7 committee votes for resolution.
+     *
+     * @param disputeId - ID of dispute to resolve
+     * @returns Resolution outcome
+     */
+    resolve(disputeId: string): Promise<Resolution>;
+    /**
+     * Apply reputation slashing to an agent
+     *
+     * 2× multiplier applies if agent has previous violations.
+     *
+     * @param agentId - Agent to slash
+     * @param amount - Base amount to slash
+     * @param reason - Reason for slashing
+     * @returns Applied penalty
+     */
+    slash(agentId: string, amount: number, reason: string): Promise<ReputationPenalty>;
+    /**
+     * Get committee of randomly selected high-reputation agents
+     *
+     * Selects 7 agents with highest reputation, excluding specified agents.
+     *
+     * @param size - Committee size (default: 7)
+     * @param exclude - Agents to exclude (e.g., plaintiff/defendant)
+     * @returns Array of agent IDs
+     */
+    getCommittee(size?: number, exclude?: string[]): string[];
+    /**
+     * Check for ClawLink hash mismatch and auto-file dispute
+     *
+     * @param clawLinkHash - Hash to verify
+     * @param expectedHash - Expected hash value
+     * @param context - Context for the dispute
+     * @returns Auto-filed dispute or null if no mismatch
+     */
+    checkAndAutoDispute(clawLinkHash: string, expectedHash: string, context: {
+        description: string;
+        plaintiff: string;
+        defendant: string;
+        evidence: Omit<Evidence, 'id' | 'hash' | 'timestamp'>[];
+        relatedId?: string;
+    }): Promise<FileDisputeResult | null>;
+    /**
+     * Register a ClawLink hash for monitoring
+     *
+     * @param hash - Hash to monitor
+     * @param disputeId - Associated dispute ID
+     */
+    registerClawLinkHash(hash: string, disputeId: string): void;
+    /**
+     * Get dispute ID for a ClawLink hash
+     *
+     * @param hash - ClawLink hash
+     * @returns Dispute ID or undefined
+     */
+    getDisputeByHash(hash: string): string | undefined;
+    /**
+     * Get dispute by ID
+     */
+    getDispute(disputeId: string): Dispute | undefined;
+    /**
+     * Get all disputes
+     */
+    getAllDisputes(): Dispute[];
+    /**
+     * Get disputes by status
+     */
+    getDisputesByStatus(status: DisputeStatus): Dispute[];
+    /**
+     * Get agent reputation
+     */
+    getReputation(agentId: string): AgentReputation | undefined;
+    /**
+     * Get vote by ID
+     */
+    getVote(voteId: string): Vote | undefined;
+    private generateDisputeId;
+    private generateVoteId;
+    private calculateHash;
+    private canResolve;
+    private scheduleResolutionTimeout;
+    private getOrCreateReputation;
+    private calculateSlashAmount;
+    private updateReputation;
+}
+export default ArbitraClient;
+//# sourceMappingURL=arbitra.d.ts.map

package/dist/lib/arbitra.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arbitra.d.ts","sourceRoot":"","sources":["../../src/lib/arbitra.ts"],"names":[],"mappings":"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"}