@hivemind-os/collective-core 0.2.0

package/src/metering/streaming.ts

@@ -0,0 +1,196 @@
+import Database from 'better-sqlite3';
+
+import type { StreamingPaymentState } from '@hivemind-os/collective-types';
+
+interface StreamRow {
+  task_id: string;
+  total_paid: bigint | number | string;
+  max_budget: bigint | number | string;
+  unit_price: bigint | number | string;
+  current_unit: number | bigint;
+  last_payment_timestamp: number | bigint;
+}
+
+interface PaymentRow {
+  task_id: string;
+  unit_index: number | bigint;
+  amount: bigint | number | string;
+  timestamp: number | bigint;
+}
+
+export interface StreamingPaymentManagerOptions {
+  dbPath: string;
+  now?: () => number;
+  paymentProcessor?: (entry: {
+    taskId: string;
+    amount: bigint;
+    unitIndex: number;
+    totalPaid: bigint;
+    timestamp: number;
+  }) => Promise<void> | void;
+}
+
+export class StreamingPaymentManager {
+  private readonly db: Database.Database;
+  private readonly now: () => number;
+
+  constructor(private readonly options: StreamingPaymentManagerOptions) {
+    this.db = new Database(options.dbPath);
+    this.db.defaultSafeIntegers(true);
+    this.now = options.now ?? (() => Date.now());
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS streaming_payment_state (
+        task_id TEXT PRIMARY KEY,
+        total_paid TEXT NOT NULL,
+        max_budget TEXT NOT NULL,
+        unit_price TEXT NOT NULL,
+        current_unit INTEGER NOT NULL,
+        last_payment_timestamp INTEGER NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS streaming_payment_log (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        task_id TEXT NOT NULL,
+        unit_index INTEGER NOT NULL,
+        amount TEXT NOT NULL,
+        timestamp INTEGER NOT NULL
+      );
+    `);
+  }
+
+  startStream(taskId: string, maxBudget: bigint, unitPrice: bigint): StreamingPaymentState {
+    taskId = normalizeTaskId(taskId);
+    if (maxBudget < 0n) {
+      throw new Error('maxBudget must be non-negative.');
+    }
+    if (unitPrice <= 0n) {
+      throw new Error('unitPrice must be positive.');
+    }
+
+    const timestamp = this.now();
+    this.db
+      .prepare(
+        `INSERT OR REPLACE INTO streaming_payment_state (
+          task_id, total_paid, max_budget, unit_price, current_unit, last_payment_timestamp
+        ) VALUES (?, ?, ?, ?, ?, ?)`,
+      )
+      .run(taskId, '0', maxBudget.toString(), unitPrice.toString(), 0, timestamp);
+
+    return {
+      taskId,
+      totalPaid: 0n,
+      maxBudget,
+      currentUnit: 0,
+      lastPaymentTimestamp: timestamp,
+    };
+  }
+
+  getState(taskId: string): StreamingPaymentState | null {
+    const row = this.db.prepare('SELECT * FROM streaming_payment_state WHERE task_id = ?').get(normalizeTaskId(taskId)) as StreamRow | undefined;
+    return row ? mapStreamRow(row) : null;
+  }
+
+  async payUnit(taskId: string): Promise<StreamingPaymentState> {
+    taskId = normalizeTaskId(taskId);
+    const row = this.requireStreamRow(taskId);
+    const state = mapStreamRow(row);
+    const unitPrice = toBigInt(row.unit_price);
+    const remainingBudget = state.maxBudget - state.totalPaid;
+    const amount = remainingBudget < unitPrice ? remainingBudget : unitPrice;
+    if (amount <= 0n) {
+      return state;
+    }
+
+    const nextState: StreamingPaymentState = {
+      taskId: state.taskId,
+      totalPaid: state.totalPaid + amount,
+      maxBudget: state.maxBudget,
+      currentUnit: state.currentUnit + 1,
+      lastPaymentTimestamp: this.now(),
+    };
+
+    // v1 streaming uses periodic on-chain transfers recorded locally; it is not a payment channel.
+    await this.options.paymentProcessor?.({
+      taskId,
+      amount,
+      unitIndex: nextState.currentUnit,
+      totalPaid: nextState.totalPaid,
+      timestamp: nextState.lastPaymentTimestamp,
+    });
+
+    this.db.transaction(() => {
+      this.db
+        .prepare(
+          `UPDATE streaming_payment_state
+           SET total_paid = ?, current_unit = ?, last_payment_timestamp = ?
+           WHERE task_id = ?`,
+        )
+        .run(nextState.totalPaid.toString(), nextState.currentUnit, nextState.lastPaymentTimestamp, taskId);
+      this.db
+        .prepare(
+          `INSERT INTO streaming_payment_log (task_id, unit_index, amount, timestamp)
+           VALUES (?, ?, ?, ?)`,
+        )
+        .run(taskId, nextState.currentUnit, amount.toString(), nextState.lastPaymentTimestamp);
+    })();
+
+    return nextState;
+  }
+
+  finalizeStream(taskId: string): { state: StreamingPaymentState; refundAmount: bigint } {
+    const state = this.getState(normalizeTaskId(taskId));
+    if (!state) {
+      throw new Error(`Unknown stream for task ${taskId}.`);
+    }
+
+    return {
+      state,
+      refundAmount: state.maxBudget - state.totalPaid,
+    };
+  }
+
+  getAuditTrail(taskId: string): Array<{ taskId: string; unitIndex: number; amount: bigint; timestamp: number }> {
+    const rows = this.db
+      .prepare('SELECT task_id, unit_index, amount, timestamp FROM streaming_payment_log WHERE task_id = ? ORDER BY id ASC')
+      .all(normalizeTaskId(taskId)) as PaymentRow[];
+    return rows.map((row) => ({
+      taskId: row.task_id,
+      unitIndex: Number(row.unit_index),
+      amount: toBigInt(row.amount),
+      timestamp: Number(row.timestamp),
+    }));
+  }
+
+  close(): void {
+    this.db.close();
+  }
+
+  private requireStreamRow(taskId: string): StreamRow {
+    const row = this.db.prepare('SELECT * FROM streaming_payment_state WHERE task_id = ?').get(normalizeTaskId(taskId)) as StreamRow | undefined;
+    if (!row) {
+      throw new Error(`Unknown stream for task ${taskId}.`);
+    }
+    return row;
+  }
+}
+
+function normalizeTaskId(taskId: string): string {
+  const normalized = taskId.trim();
+  if (!normalized) {
+    throw new Error('taskId is required.');
+  }
+  return normalized;
+}
+
+function mapStreamRow(row: StreamRow): StreamingPaymentState {
+  return {
+    taskId: row.task_id,
+    totalPaid: toBigInt(row.total_paid),
+    maxBudget: toBigInt(row.max_budget),
+    currentUnit: Number(row.current_unit),
+    lastPaymentTimestamp: Number(row.last_payment_timestamp),
+  };
+}
+
+function toBigInt(value: bigint | number | string): bigint {
+  return typeof value === 'bigint' ? value : BigInt(value);
+}

package/src/metering/verification.ts

@@ -0,0 +1,104 @@
+import type { HashChainProof, Task } from '@hivemind-os/collective-types';
+
+import { DEFAULT_METERING_CHUNK_SIZE, HashChain, createMeteringSeed, splitIntoMeteringUnits } from './hash-chain.js';
+
+const decoder = new TextDecoder();
+const METERED_RESULT_SCHEMA = 'agentic-mesh-metered-result/v1';
+const BASE64_RESULT_PATTERN = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+
+export interface MeteredResultEnvelope {
+  schema: typeof METERED_RESULT_SCHEMA;
+  resultEncoding: 'base64';
+  result: string;
+  proof: HashChainProof;
+  unitChunkSize: number;
+}
+
+export class ResultVerifier {
+  verify(task: Pick<Task, 'id' | 'verificationHash'>, proof: HashChainProof, expectedData: Uint8Array[]): boolean {
+    if (!task.verificationHash) {
+      return false;
+    }
+
+    return HashChain.verifyChain(proof, expectedData, createMeteringSeed(task.id))
+      && task.verificationHash.toLowerCase() === proof.root.toLowerCase();
+  }
+}
+
+export function createMeteredResultEnvelope(
+  resultData: Uint8Array,
+  proof: HashChainProof,
+  unitChunkSize = DEFAULT_METERING_CHUNK_SIZE,
+): MeteredResultEnvelope {
+  if (!Number.isSafeInteger(unitChunkSize) || unitChunkSize <= 0) {
+    throw new Error('unitChunkSize must be a positive safe integer.');
+  }
+
+  return {
+    schema: METERED_RESULT_SCHEMA,
+    resultEncoding: 'base64',
+    result: Buffer.from(resultData).toString('base64'),
+    proof,
+    unitChunkSize,
+  };
+}
+
+export function serializeMeteredResultEnvelope(envelope: MeteredResultEnvelope): Uint8Array {
+  return new TextEncoder().encode(JSON.stringify(envelope));
+}
+
+export function parseMeteredResultEnvelope(data: Uint8Array): MeteredResultEnvelope | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(decoder.decode(data)) as unknown;
+  } catch {
+    return null;
+  }
+
+  if (!isMeteredResultEnvelope(parsed)) {
+    return null;
+  }
+
+  return parsed;
+}
+
+export function decodeMeteredResult(envelope: MeteredResultEnvelope): Uint8Array {
+  return new Uint8Array(Buffer.from(envelope.result, 'base64'));
+}
+
+export function getMeteredResultUnits(envelope: MeteredResultEnvelope): Uint8Array[] {
+  return splitIntoMeteringUnits(decodeMeteredResult(envelope), envelope.unitChunkSize);
+}
+
+function isMeteredResultEnvelope(value: unknown): value is MeteredResultEnvelope {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+
+  const candidate = value as Record<string, unknown>;
+  const unitChunkSize = candidate.unitChunkSize;
+  return candidate.schema === METERED_RESULT_SCHEMA
+    && candidate.resultEncoding === 'base64'
+    && typeof candidate.result === 'string'
+    && BASE64_RESULT_PATTERN.test(candidate.result)
+    && typeof unitChunkSize === 'number'
+    && Number.isSafeInteger(unitChunkSize)
+    && unitChunkSize > 0
+    && isHashChainProof(candidate.proof);
+}
+
+function isHashChainProof(value: unknown): value is HashChainProof {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+
+  const candidate = value as Record<string, unknown>;
+  const unitCount = candidate.unitCount;
+  return typeof candidate.root === 'string'
+    && /^[a-f0-9]{64}$/i.test(candidate.root)
+    && Array.isArray(candidate.intermediateHashes)
+    && candidate.intermediateHashes.every((entry) => typeof entry === 'string' && /^[a-f0-9]{64}$/i.test(entry))
+    && typeof unitCount === 'number'
+    && Number.isSafeInteger(unitCount)
+    && unitCount >= 0;
+}

package/src/payment/index.ts

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

package/src/payment/rail-selector.ts

@@ -0,0 +1,41 @@
+export type SelectedPaymentRail = 'sui-escrow' | 'sui-transfer' | 'x402-base';
+
+export interface RailSelectionContext {
+  executionMode: 'sync' | 'async';
+  consumerHasSuiWallet: boolean;
+  consumerHasEvmWallet: boolean;
+  providerAcceptsSui: boolean;
+  providerAcceptsX402: boolean;
+  amount: bigint;
+  currency: string;
+}
+
+export class PaymentRailSelector {
+  selectRail(context: RailSelectionContext): SelectedPaymentRail {
+    const available = this.getAvailableRails(context);
+    const selected = available[0];
+    if (!selected) {
+      throw new Error('No compatible payment rail is available for this task.');
+    }
+
+    return selected;
+  }
+
+  getAvailableRails(context: RailSelectionContext): SelectedPaymentRail[] {
+    if (context.executionMode === 'async') {
+      return context.consumerHasSuiWallet && context.providerAcceptsSui ? ['sui-escrow'] : [];
+    }
+
+    const rails: SelectedPaymentRail[] = [];
+
+    if (context.consumerHasSuiWallet && context.providerAcceptsSui) {
+      rails.push('sui-transfer');
+    }
+
+    if (context.consumerHasEvmWallet && context.providerAcceptsX402) {
+      rails.push('x402-base');
+    }
+
+    return rails;
+  }
+}

package/src/registry/client.ts

@@ -0,0 +1,328 @@
+import pino from 'pino';
+
+import type { AgentCard, Capability, NetworkConfig, ReputationScore } from '@hivemind-os/collective-types';
+import type { Signer } from '@mysten/sui/cryptography';
+
+import { parseAgentCardFields } from '../internal/parsing.js';
+import { parseRawEvent } from '../events/parser.js';
+import { ReputationScoreCalculator } from '../reputation/score-calculator.js';
+import { MeshSuiClient } from '../sui/client.js';
+import { StakingClient } from '../staking/client.js';
+import {
+  buildDeactivateAgentTx,
+  buildReactivateAgentTx,
+  buildRegisterAgentTx,
+  buildSetEncryptionKeyTx,
+  buildUpdateAgentTx,
+  buildUpdateCapabilitiesTx,
+} from '../sui/tx-helpers.js';
+
+const logger = pino({ name: '@hivemind-os/collective-core:registry' });
+
+export class RegistryClient {
+  private readonly scoreCalculator = new ReputationScoreCalculator();
+  private readonly stakingClient: StakingClient;
+
+  constructor(
+    private readonly suiClient: MeshSuiClient,
+    private readonly config: NetworkConfig,
+  ) {
+    this.stakingClient = new StakingClient(suiClient, config);
+  }
+
+  async registerAgent(params: {
+    name: string;
+    did: string;
+    description: string;
+    capabilities: Capability[];
+    endpoint: string;
+    encryptionPublicKey?: Uint8Array;
+    keypair: Signer;
+  }): Promise<{ txDigest: string; agentCardId: string }> {
+    const tx = buildRegisterAgentTx({
+      packageId: this.config.packageId,
+      registryId: this.config.registryId,
+      name: params.name,
+      did: params.did,
+      description: params.description,
+      capabilities: params.capabilities,
+      endpoint: params.endpoint,
+    });
+
+    const response = await this.suiClient.executeTransaction(tx, params.keypair);
+    const agentCardId = extractObjectId(response.objectChanges, /::registry::AgentCard$/);
+
+    if (!agentCardId) {
+      logger.warn({ response }, 'Agent registration succeeded without an AgentCard object change.');
+      throw new Error('Unable to determine AgentCard object id from transaction response.');
+    }
+
+    if (params.encryptionPublicKey !== undefined) {
+      await this.setEncryptionKey({
+        cardId: agentCardId,
+        encryptionPublicKey: params.encryptionPublicKey,
+        keypair: params.keypair,
+      });
+    }
+
+    return { txDigest: response.digest, agentCardId };
+  }
+
+  async updateAgent(params: {
+    cardId: string;
+    name: string;
+    description: string;
+    endpoint: string;
+    encryptionPublicKey?: Uint8Array;
+    keypair: Signer;
+  }): Promise<{ txDigest: string }> {
+    const tx = buildUpdateAgentTx({
+      packageId: this.config.packageId,
+      registryId: this.config.registryId,
+      cardId: params.cardId,
+      name: params.name,
+      description: params.description,
+      endpoint: params.endpoint,
+    });
+
+    const response = await this.suiClient.executeTransaction(tx, params.keypair);
+    if (params.encryptionPublicKey !== undefined) {
+      await this.setEncryptionKey({
+        cardId: params.cardId,
+        encryptionPublicKey: params.encryptionPublicKey,
+        keypair: params.keypair,
+      });
+    }
+    return { txDigest: response.digest };
+  }
+
+  async setEncryptionKey(params: {
+    cardId: string;
+    encryptionPublicKey: Uint8Array;
+    keypair: Signer;
+  }): Promise<{ txDigest: string }> {
+    const tx = buildSetEncryptionKeyTx({
+      packageId: this.config.packageId,
+      cardId: params.cardId,
+      encryptionPublicKey: params.encryptionPublicKey,
+    });
+
+    const response = await this.suiClient.executeTransaction(tx, params.keypair);
+    return { txDigest: response.digest };
+  }
+
+  async updateCapabilities(params: {
+    cardId: string;
+    capabilities: Capability[];
+    keypair: Signer;
+  }): Promise<{ txDigest: string }> {
+    const tx = buildUpdateCapabilitiesTx({
+      packageId: this.config.packageId,
+      registryId: this.config.registryId,
+      cardId: params.cardId,
+      capabilities: params.capabilities,
+    });
+
+    const response = await this.suiClient.executeTransaction(tx, params.keypair);
+    return { txDigest: response.digest };
+  }
+
+  async deactivateAgent(params: {
+    cardId: string;
+    keypair: Signer;
+  }): Promise<{ txDigest: string }> {
+    const tx = buildDeactivateAgentTx({
+      packageId: this.config.packageId,
+      registryId: this.config.registryId,
+      cardId: params.cardId,
+    });
+
+    const response = await this.suiClient.executeTransaction(tx, params.keypair);
+    return { txDigest: response.digest };
+  }
+
+  async reactivateAgent(params: {
+    cardId: string;
+    keypair: Signer;
+  }): Promise<{ txDigest: string }> {
+    const tx = buildReactivateAgentTx({
+      packageId: this.config.packageId,
+      registryId: this.config.registryId,
+      cardId: params.cardId,
+    });
+
+    const response = await this.suiClient.executeTransaction(tx, params.keypair);
+    return { txDigest: response.digest };
+  }
+
+  async getAgentCard(cardId: string): Promise<AgentCard | null> {
+    try {
+      const object = await this.suiClient.getObject<Record<string, unknown>>(cardId);
+      return await this.enrichAgentStake(parseAgentCardFields(object, cardId));
+    } catch (error) {
+      if (isObjectMissingError(error)) {
+        return null;
+      }
+
+      throw error;
+    }
+  }
+
+  async getAgentCardByOwner(owner: string): Promise<AgentCard | null> {
+    const page = await this.suiClient.client.getOwnedObjects({
+      owner,
+      filter: { StructType: `${this.config.packageId}::registry::AgentCard` },
+      limit: 20,
+    });
+
+    const cards = await Promise.all(
+      page.data
+        .map((entry) => entry.data?.objectId)
+        .filter((objectId): objectId is string => typeof objectId === 'string')
+        .map(async (objectId) => await this.getAgentCard(objectId)),
+    );
+
+    return cards
+      .filter((card): card is AgentCard => Boolean(card))
+      .sort((left, right) => right.updatedAt - left.updatedAt)
+      .find((card) => card.active) ?? null;
+  }
+
+  async findAgentByDid(did: string): Promise<AgentCard | null> {
+    const eventType = `${this.config.packageId}::registry::AgentRegistered`;
+    let cursor = null;
+
+    do {
+      const page = await this.suiClient.queryEvents(eventType, cursor, 100);
+      for (const event of page.events) {
+        const parsed = parseRawEvent(event, this.config.packageId);
+        if (parsed?.type !== 'agent.registered' || parsed.agent.did !== did) {
+          continue;
+        }
+
+        return await this.getAgentCard(parsed.agent.id);
+      }
+
+      cursor = page.nextCursor;
+      if (!page.hasMore) {
+        break;
+      }
+    } while (cursor);
+
+    return null;
+  }
+
+  async discoverByCapability(
+    capability: string,
+    limit = 20,
+    options: { sortByReputation?: boolean; scores?: Map<string, ReputationScore> } = {},
+  ): Promise<AgentCard[]> {
+    const eventType = `${this.config.packageId}::registry::AgentRegistered`;
+    const matches: AgentCard[] = [];
+    const seen = new Set<string>();
+    let cursor = null;
+
+    do {
+      const page = await this.suiClient.queryEvents(eventType, cursor, Math.max(limit * 2, 20));
+      for (const event of page.events) {
+        const parsed = parseRawEvent(event, this.config.packageId);
+        if (parsed?.type !== 'agent.registered') {
+          continue;
+        }
+
+        const hasMatch = parsed.agent.capabilities.some(
+          (entry) => entry.name.toLowerCase() === capability.toLowerCase(),
+        );
+        if (!hasMatch) {
+          continue;
+        }
+
+        const current = await this.getAgentCard(parsed.agent.id);
+        if (current?.active && !seen.has(current.id)) {
+          matches.push(current);
+          seen.add(current.id);
+        }
+
+        if (!options.sortByReputation && matches.length >= limit) {
+          return matches;
+        }
+      }
+
+      cursor = page.nextCursor;
+      if (!page.hasMore) {
+        break;
+      }
+    } while (cursor);
+
+    if (!options.sortByReputation) {
+      return [...matches].sort(compareStakePreference).slice(0, limit);
+    }
+
+    const scores = options.scores ?? new Map(matches.map((agent) => [agent.did, this.scoreCalculator.computeScore(agent, [])]));
+    return this.scoreCalculator.rankByReputation(matches, scores).slice(0, limit);
+  }
+
+  private async enrichAgentStake(agent: AgentCard): Promise<AgentCard> {
+    try {
+      const stake = await this.stakingClient.getStakeByOwner(agent.owner);
+      if (!stake) {
+        return { ...agent, hasStake: false, stakeMist: undefined, stakeType: undefined };
+      }
+
+      return {
+        ...agent,
+        hasStake: Boolean(stake.isActive && stake.meetsMinium),
+        stakeMist: stake.balanceMist,
+        stakeType: stake.stakeType,
+      };
+    } catch {
+      return { ...agent, hasStake: false, stakeMist: undefined, stakeType: undefined };
+    }
+  }
+}
+
+function extractObjectId(
+  objectChanges: Array<Record<string, unknown>> | null | undefined,
+  objectTypePattern: RegExp,
+): string | undefined {
+  return objectChanges?.find(
+    (change) =>
+      (change.type === 'created' || change.type === 'transferred' || change.type === 'mutated') &&
+      typeof change.objectType === 'string' &&
+      objectTypePattern.test(change.objectType) &&
+      typeof change.objectId === 'string',
+  )?.objectId as string | undefined;
+}
+
+function isObjectMissingError(error: unknown): boolean {
+  return error instanceof Error && /not found|does not contain move object data/i.test(error.message);
+}
+
+function compareStakePreference(left: AgentCard, right: AgentCard): number {
+  return (
+    compareBoolean(left.hasStake ?? false, right.hasStake ?? false) ||
+    compareBigInt(left.stakeMist ?? 0n, right.stakeMist ?? 0n) ||
+    compareNumber(left.updatedAt, right.updatedAt)
+  );
+}
+
+function compareBoolean(left: boolean, right: boolean): number {
+  if (left === right) {
+    return 0;
+  }
+  return left ? -1 : 1;
+}
+
+function compareBigInt(left: bigint, right: bigint): number {
+  if (left === right) {
+    return 0;
+  }
+  return left > right ? -1 : 1;
+}
+
+function compareNumber(left: number, right: number): number {
+  if (left === right) {
+    return 0;
+  }
+  return left > right ? -1 : 1;
+}

package/src/registry/index.ts

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