@hivemind-os/collective-core 0.2.0

package/src/dispute/client.ts

@@ -0,0 +1,191 @@
+import type { Dispute, NetworkConfig } from '@hivemind-os/collective-types';
+import type { SuiEvent, SuiTransactionBlockResponse } from '@mysten/sui/client';
+import type { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';
+
+import { isRecord, normalizeMoveValue, parseDisputeFields } from '../internal/parsing.js';
+import { MeshSuiClient } from '../sui/client.js';
+import {
+  buildAcceptResolutionTx,
+  buildArbitrateDisputeTx,
+  buildOpenDisputeTx,
+  buildRespondToDisputeTx,
+} from '../sui/tx-helpers.js';
+
+export class DisputeClient {
+  constructor(
+    private readonly suiClient: MeshSuiClient,
+    private readonly config: Pick<NetworkConfig, 'packageId'>,
+  ) {}
+
+  async openDispute(params: {
+    taskId: string;
+    evidenceBlobId: string;
+    proposedSplitMist: bigint;
+    arbitratorAddress?: string;
+    signer: Ed25519Keypair;
+  }): Promise<{ disputeId: string; txDigest: string }> {
+    const tx = buildOpenDisputeTx({
+      packageId: this.config.packageId,
+      taskId: params.taskId,
+      evidenceBlobId: params.evidenceBlobId,
+      proposedSplitMist: params.proposedSplitMist,
+      arbitratorAddress: params.arbitratorAddress,
+    });
+    const response = await this.suiClient.executeTransaction(tx, params.signer);
+    const disputeId =
+      extractObjectId(response, /::dispute::Dispute$/)
+      ?? asString(readEventField(findEvent(response.events, `${this.config.packageId}::dispute::DisputeOpened`), 'dispute_id', 'disputeId'));
+    if (!disputeId) {
+      throw new Error('Unable to determine dispute id from transaction response.');
+    }
+    return { disputeId, txDigest: response.digest };
+  }
+
+  async respondToDispute(params: {
+    disputeId: string;
+    evidenceBlobId: string;
+    proposedSplitMist: bigint;
+    signer: Ed25519Keypair;
+  }): Promise<{ txDigest: string }> {
+    const tx = buildRespondToDisputeTx({
+      packageId: this.config.packageId,
+      disputeId: params.disputeId,
+      evidenceBlobId: params.evidenceBlobId,
+      proposedSplitMist: params.proposedSplitMist,
+    });
+    const response = await this.suiClient.executeTransaction(tx, params.signer);
+    return { txDigest: response.digest };
+  }
+
+  async acceptResolution(params: {
+    disputeId: string;
+    taskId: string;
+    signer: Ed25519Keypair;
+  }): Promise<{ requesterAmount: bigint; providerAmount: bigint; txDigest: string }> {
+    const tx = buildAcceptResolutionTx({
+      packageId: this.config.packageId,
+      disputeId: params.disputeId,
+      taskId: params.taskId,
+    });
+    const response = await this.suiClient.executeTransaction(tx, params.signer);
+    const event = findEvent(response.events, `${this.config.packageId}::dispute::DisputeMutuallyResolved`);
+    return {
+      requesterAmount: requireEventBigInt(event, 'DisputeMutuallyResolved', 'requester_amount', 'requesterAmount'),
+      providerAmount: requireEventBigInt(event, 'DisputeMutuallyResolved', 'provider_amount', 'providerAmount'),
+      txDigest: response.digest,
+    };
+  }
+
+  async arbitrate(params: {
+    disputeId: string;
+    taskId: string;
+    rulingSplitMist: bigint;
+    signer: Ed25519Keypair;
+  }): Promise<{ txDigest: string }> {
+    const tx = buildArbitrateDisputeTx({
+      packageId: this.config.packageId,
+      disputeId: params.disputeId,
+      taskId: params.taskId,
+      rulingSplitMist: params.rulingSplitMist,
+    });
+    const response = await this.suiClient.executeTransaction(tx, params.signer);
+    return { txDigest: response.digest };
+  }
+
+  async getDispute(disputeId: string): Promise<Dispute | null> {
+    try {
+      const object = await this.suiClient.getObject<Record<string, unknown>>(disputeId);
+      return parseDisputeFields(object, disputeId);
+    } catch (error) {
+      if (isObjectMissingError(error)) {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  async getDisputeByTask(taskId: string): Promise<Dispute | null> {
+    const eventType = `${this.config.packageId}::dispute::DisputeOpened`;
+    let cursor = null;
+
+    do {
+      const page = await this.suiClient.queryEvents(eventType, cursor, 100);
+      const matchedEvent = page.events.find((event) => asString(readEventField(normalizeEvent(event), 'task_id', 'taskId')) === taskId);
+      if (matchedEvent) {
+        const disputeId = asString(readEventField(normalizeEvent(matchedEvent), 'dispute_id', 'disputeId'));
+        return disputeId ? await this.getDispute(disputeId) : null;
+      }
+      cursor = page.nextCursor;
+      if (!page.hasMore) {
+        break;
+      }
+    } while (cursor);
+
+    return null;
+  }
+}
+
+function extractObjectId(response: SuiTransactionBlockResponse, objectTypePattern: RegExp): string | undefined {
+  const change = (response.objectChanges as Array<Record<string, unknown>> | null | undefined)?.find(
+    (entry) =>
+      (entry.type === 'created' || entry.type === 'transferred' || entry.type === 'mutated')
+      && typeof entry.objectType === 'string'
+      && objectTypePattern.test(entry.objectType)
+      && typeof entry.objectId === 'string',
+  );
+  return change?.objectId as string | undefined;
+}
+
+function findEvent(events: SuiTransactionBlockResponse['events'], eventType: string): Record<string, unknown> {
+  const payload = events
+    ?.map((event) => ({ type: event.type, payload: normalizeEvent(event) }))
+    .find((event) => event.type === eventType)?.payload;
+  return payload ?? {};
+}
+
+function normalizeEvent(event: SuiEvent): Record<string, unknown> {
+  const normalized = normalizeMoveValue(event.parsedJson);
+  return isRecord(normalized) ? normalized : {};
+}
+
+function readEventField(record: Record<string, unknown>, ...keys: string[]): unknown {
+  for (const key of keys) {
+    if (key in record) {
+      return record[key];
+    }
+  }
+  return undefined;
+}
+
+function asString(value: unknown): string {
+  return typeof value === 'string' ? value : '';
+}
+
+function asBigInt(value: unknown): bigint {
+  if (typeof value === 'bigint') {
+    return value;
+  }
+  if (typeof value === 'number') {
+    return BigInt(value);
+  }
+  if (typeof value === 'string' && value.length > 0) {
+    return BigInt(value);
+  }
+  return 0n;
+}
+
+function requireEventBigInt(record: Record<string, unknown>, eventName: string, ...keys: string[]): bigint {
+  const raw = readEventField(record, ...keys);
+  if (raw == null || raw === '') {
+    throw new Error(`${eventName} event did not include ${keys[0]}.`);
+  }
+  try {
+    return asBigInt(raw);
+  } catch {
+    throw new Error(`${eventName} event did not include a valid ${keys[0]}.`);
+  }
+}
+
+function isObjectMissingError(error: unknown): boolean {
+  return error instanceof Error && /not found|does not contain move object data/i.test(error.message);
+}

package/src/dispute/index.ts

@@ -0,0 +1 @@
+export * from './client.js';

package/src/events/index.ts

@@ -0,0 +1,2 @@
+export * from './subscription.js';
+export * from './parser.js';

package/src/events/parser.ts

@@ -0,0 +1,291 @@
+import { BidStatus, PaymentScheme, RelayNodeStatus, TaskStatus, type MeshEvent } from '@hivemind-os/collective-types';
+import type { SuiEvent } from '@mysten/sui/client';
+
+import { isRecord, parseAgentCardFields, parseBidFields, parseRelayNodeFields, parseTaskFields } from '../internal/parsing.js';
+
+export function parseRawEvent(rawEvent: SuiEvent, packageId: string): MeshEvent | null {
+  if (!rawEvent.type.startsWith(`${packageId}::`)) {
+    return null;
+  }
+
+  if (!isRecord(rawEvent.parsedJson)) {
+    return null;
+  }
+
+  const payload = rawEvent.parsedJson;
+  const timestampMs = Number(rawEvent.timestampMs ?? 0);
+  const base = {
+    packageId,
+    txDigest: rawEvent.id.txDigest,
+    timestampMs,
+  };
+
+  switch (rawEvent.type) {
+    case `${packageId}::registry::AgentRegistered`: {
+      const agent = parseAgentCardFields(payload);
+      return {
+        ...base,
+        type: 'agent.registered',
+        registryId: '',
+        agent,
+      };
+    }
+    case `${packageId}::registry::AgentUpdated`: {
+      const agent = parseAgentCardFields(payload);
+      return {
+        ...base,
+        type: 'agent.updated',
+        agent,
+        previousVersion: Math.max(agent.version - 1, 0),
+      };
+    }
+    case `${packageId}::registry::AgentDeactivated`: {
+      const agent = parseAgentCardFields(payload);
+      return {
+        ...base,
+        type: 'agent.deactivated',
+        agentId: agent.id,
+        owner: agent.owner,
+        deactivatedAt: timestampMs,
+      };
+    }
+    case `${packageId}::task::TaskPosted`: {
+      return {
+        ...base,
+        type: 'task.posted',
+        task: parseTaskFields(payload),
+      };
+    }
+    case `${packageId}::task::TaskAccepted`: {
+      return {
+        ...base,
+        type: 'task.accepted',
+        taskId: asString(payload.task_id, payload.taskId),
+        requester: asString(payload.requester),
+        provider: asString(payload.provider),
+        price: asBigInt(payload.price),
+        acceptedAt: asNumber(payload.accepted_at, timestampMs),
+        status: TaskStatus.ACCEPTED,
+      };
+    }
+    case `${packageId}::task::TaskCompleted`: {
+      return {
+        ...base,
+        type: 'task.completed',
+        taskId: asString(payload.task_id, payload.taskId),
+        provider: asString(payload.provider),
+        resultBlobId: bytesToString(payload.result_blob_id ?? payload.resultBlobId),
+        price: asBigInt(payload.price),
+        paymentScheme: asOptionalPaymentScheme(payload.payment_scheme ?? payload.paymentScheme),
+        meteredUnits: asOptionalNumber(payload.metered_units ?? payload.meteredUnits),
+        verificationHash: bytesToHex(payload.verification_hash ?? payload.verificationHash),
+        completedAt: asNumber(payload.completed_at, timestampMs),
+        status: TaskStatus.COMPLETED,
+      };
+    }
+    case `${packageId}::task::TaskPaymentReleased`: {
+      return {
+        ...base,
+        type: 'task.released',
+        taskId: asString(payload.task_id, payload.taskId),
+        requester: asString(payload.requester),
+        provider: asString(payload.provider),
+        price: asBigInt(payload.price),
+        refundAmount: asOptionalBigInt(payload.refund_amount ?? payload.refundAmount),
+        releasedAt: timestampMs,
+        status: TaskStatus.RELEASED,
+      };
+    }
+    case `${packageId}::task::TaskDisputed`: {
+      return {
+        ...base,
+        type: 'task.disputed',
+        taskId: asString(payload.task_id, payload.taskId),
+        requester: asString(payload.requester),
+        provider: asOptionalString(payload.provider),
+        disputedAt: asNumber(payload.disputed_at, timestampMs),
+        status: TaskStatus.DISPUTED,
+      };
+    }
+    case `${packageId}::task::TaskCancelled`:
+    case `${packageId}::task::TaskExpiredRefunded`: {
+      return {
+        ...base,
+        type: 'task.cancelled',
+        taskId: asString(payload.task_id, payload.taskId),
+        requester: asString(payload.requester),
+        cancelledAt: timestampMs,
+        status: TaskStatus.CANCELLED,
+      };
+    }
+    case `${packageId}::marketplace::BidPlaced`: {
+      return {
+        ...base,
+        type: 'bid.placed',
+        bid: parseBidFields(payload),
+      };
+    }
+    case `${packageId}::marketplace::BidAccepted`: {
+      return {
+        ...base,
+        type: 'bid.accepted',
+        bidId: asString(payload.bid_id, payload.bidId),
+        taskId: asString(payload.task_id, payload.taskId),
+        requester: asString(payload.requester),
+        bidder: asString(payload.bidder),
+        bidPrice: asBigInt(payload.bid_price ?? payload.bidPrice),
+        refundedAmount: asBigInt(payload.refunded_amount ?? payload.refundedAmount),
+        acceptedAt: asNumber(payload.accepted_at, timestampMs),
+        status: BidStatus.ACCEPTED,
+      };
+    }
+    case `${packageId}::marketplace::BidWithdrawn`: {
+      return {
+        ...base,
+        type: 'bid.withdrawn',
+        bidId: asString(payload.bid_id, payload.bidId),
+        taskId: asString(payload.task_id, payload.taskId),
+        bidder: asString(payload.bidder),
+        withdrawnAt: timestampMs,
+        status: BidStatus.WITHDRAWN,
+      };
+    }
+    case `${packageId}::marketplace::BidRejected`: {
+      return {
+        ...base,
+        type: 'bid.rejected',
+        bidId: asString(payload.bid_id, payload.bidId),
+        taskId: asString(payload.task_id, payload.taskId),
+        requester: asString(payload.requester),
+        bidder: asString(payload.bidder),
+        rejectedAt: timestampMs,
+        status: BidStatus.REJECTED,
+      };
+    }
+    case `${packageId}::relay_registry::RelayRegistered`: {
+      return {
+        ...base,
+        type: 'relay.registered',
+        relay: parseRelayNodeFields(payload),
+      };
+    }
+    case `${packageId}::relay_registry::RelayHeartbeat`: {
+      return {
+        ...base,
+        type: 'relay.heartbeat',
+        relayId: asString(payload.relay_id, payload.relayId),
+        operator: asString(payload.operator),
+        lastHeartbeat: asNumber(payload.last_heartbeat ?? payload.lastHeartbeat, timestampMs),
+      };
+    }
+    case `${packageId}::relay_registry::RelayDeactivated`: {
+      return {
+        ...base,
+        type: 'relay.deactivated',
+        relayId: asString(payload.relay_id, payload.relayId),
+        operator: asString(payload.operator),
+        status: RelayNodeStatus.INACTIVE,
+      };
+    }
+    case `${packageId}::relay_registry::RelaySlashed`: {
+      return {
+        ...base,
+        type: 'relay.slashed',
+        relayId: asString(payload.relay_id, payload.relayId),
+        operator: asString(payload.operator),
+        status: RelayNodeStatus.SLASHED,
+      };
+    }
+    default:
+      return null;
+  }
+}
+
+function asString(...values: unknown[]): string {
+  const match = values.find((value) => typeof value === 'string');
+  return typeof match === 'string' ? match : '';
+}
+
+function asOptionalString(value: unknown): string | undefined {
+  const normalized = asString(value);
+  return normalized.length > 0 ? normalized : undefined;
+}
+
+function asNumber(value: unknown, fallback = 0): number {
+  if (typeof value === 'number') {
+    return value;
+  }
+
+  if (typeof value === 'string' && value.length > 0) {
+    return Number(value);
+  }
+
+  if (typeof value === 'bigint') {
+    return Number(value);
+  }
+
+  return fallback;
+}
+
+function asOptionalNumber(value: unknown): number | undefined {
+  if (value === undefined || value === null || value === '') {
+    return undefined;
+  }
+  return asNumber(value);
+}
+
+function asBigInt(value: unknown): bigint {
+  if (typeof value === 'bigint') {
+    return value;
+  }
+  if (typeof value === 'number') {
+    return BigInt(value);
+  }
+  if (typeof value === 'string' && value.length > 0) {
+    return BigInt(value);
+  }
+  return 0n;
+}
+
+function asOptionalBigInt(value: unknown): bigint | undefined {
+  if (value === undefined || value === null || value === '') {
+    return undefined;
+  }
+  return asBigInt(value);
+}
+
+function asOptionalPaymentScheme(value: unknown): PaymentScheme | undefined {
+  if (value === undefined || value === null || value === '') {
+    return undefined;
+  }
+  const parsed = asNumber(value);
+  switch (parsed) {
+    case 0:
+      return PaymentScheme.EXACT;
+    case 1:
+      return PaymentScheme.UPTO;
+    case 2:
+      return PaymentScheme.STREAM;
+    default:
+      return undefined;
+  }
+}
+
+function bytesToString(value: unknown): string {
+  if (typeof value === 'string') {
+    return value;
+  }
+
+  if (Array.isArray(value) && value.every((entry) => typeof entry === 'number')) {
+    return new TextDecoder().decode(new Uint8Array(value));
+  }
+
+  return '';
+}
+
+function bytesToHex(value: unknown): string | undefined {
+  if (!Array.isArray(value) || !value.every((entry) => typeof entry === 'number')) {
+    return undefined;
+  }
+  return Buffer.from(value).toString('hex');
+}

package/src/events/subscription.ts

@@ -0,0 +1,131 @@
+import Database from 'better-sqlite3';
+import pino from 'pino';
+
+import type { EventId as EventID, SuiEvent } from '@mysten/sui/client';
+
+import { MeshSuiClient } from '../sui/client.js';
+
+const logger = pino({ name: '@hivemind-os/collective-core:events' });
+
+export interface CursorStore {
+  getCursor(eventType: string): Promise<EventID | null>;
+  setCursor(eventType: string, cursor: EventID): Promise<void>;
+}
+
+export class EventSubscription {
+  private running = false;
+  private timer?: NodeJS.Timeout;
+  private cursor: EventID | null = null;
+  private polling = false;
+
+  constructor(
+    private readonly params: {
+      suiClient: MeshSuiClient;
+      eventType: string;
+      pollIntervalMs?: number;
+      onEvent: (event: SuiEvent) => Promise<void>;
+      onError?: (error: unknown) => void;
+      cursorStore: CursorStore;
+    },
+  ) {}
+
+  start(): void {
+    if (this.running) {
+      return;
+    }
+
+    this.running = true;
+    void this.poll();
+  }
+
+  stop(): void {
+    this.running = false;
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = undefined;
+    }
+  }
+
+  isRunning(): boolean {
+    return this.running;
+  }
+
+  private async poll(): Promise<void> {
+    if (!this.running || this.polling) {
+      return;
+    }
+
+    this.polling = true;
+    let nextDelay = this.params.pollIntervalMs ?? 5_000;
+
+    try {
+      if (!this.cursor) {
+        this.cursor = await this.params.cursorStore.getCursor(this.params.eventType);
+      }
+
+      const page = await this.params.suiClient.queryEvents(
+        this.params.eventType,
+        this.cursor,
+        100,
+      );
+
+      for (const event of page.events) {
+        await this.params.onEvent(event);
+        this.cursor = event.id;
+        await this.params.cursorStore.setCursor(this.params.eventType, event.id);
+      }
+
+      if (page.hasMore) {
+        nextDelay = 0;
+      }
+    } catch (error) {
+      logger.error({ err: error, eventType: this.params.eventType }, 'Event polling failed.');
+      this.params.onError?.(error);
+    } finally {
+      this.polling = false;
+      if (this.running) {
+        this.timer = setTimeout(() => {
+          void this.poll();
+        }, nextDelay);
+      }
+    }
+  }
+}
+
+export class SqliteCursorStore implements CursorStore {
+  private readonly db: Database.Database;
+
+  constructor(dbPath: string) {
+    this.db = new Database(dbPath);
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS event_cursors (
+        event_type TEXT PRIMARY KEY,
+        cursor_json TEXT NOT NULL,
+        updated_at INTEGER NOT NULL
+      );
+    `);
+  }
+
+  async getCursor(eventType: string): Promise<EventID | null> {
+    const row = this.db
+      .prepare('SELECT cursor_json FROM event_cursors WHERE event_type = ?')
+      .get(eventType) as { cursor_json: string } | undefined;
+
+    return row ? (JSON.parse(row.cursor_json) as EventID) : null;
+  }
+
+  async setCursor(eventType: string, cursor: EventID): Promise<void> {
+    this.db
+      .prepare(
+        `INSERT INTO event_cursors (event_type, cursor_json, updated_at)
+         VALUES (?, ?, ?)
+         ON CONFLICT(event_type)
+         DO UPDATE SET cursor_json = excluded.cursor_json, updated_at = excluded.updated_at`,
+      )
+      .run(eventType, JSON.stringify(cursor), Date.now());
+  }
+
+  close(): void {
+    this.db.close();
+  }
+}

package/src/evm/constants.ts

@@ -0,0 +1,6 @@
+export const USDC_ADDRESS = {
+  base: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+  'base-sepolia': '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+} as const;
+
+export const PERMIT2_ADDRESS = '0x000000000022D473030F116dDEE9F6B43aC78BA3';

package/src/evm/index.ts

@@ -0,0 +1,2 @@
+export * from './constants.js';
+export * from './wallet.js';