@hivemind-os/collective-core 0.2.0

package/src/marketplace/client.ts

@@ -0,0 +1,349 @@
+import pino from 'pino';
+
+import type { Bid, BidRecommendation, NetworkConfig, Task } from '@hivemind-os/collective-types';
+import { BidStatus, TaskStatus } from '@hivemind-os/collective-types';
+import type { SuiEvent, SuiTransactionBlockResponse } from '@mysten/sui/client';
+import type { Signer } from '@mysten/sui/cryptography';
+
+import { isRecord, normalizeMoveValue, parseBidFields, parseTaskFields } from '../internal/parsing.js';
+import { ReputationScoreCalculator } from '../reputation/score-calculator.js';
+import { RegistryClient } from '../registry/client.js';
+import { MeshSuiClient } from '../sui/client.js';
+import { buildAcceptBidTx, buildPlaceBidTx, buildRejectBidTx, buildWithdrawBidTx } from '../sui/tx-helpers.js';
+import { TaskClient } from '../task/client.js';
+
+const logger = pino({ name: '@hivemind-os/collective-core:marketplace' });
+const DEFAULT_REPUTATION_WEIGHT = 1_000_000n;
+const DEFAULT_PRICE_WEIGHT = 1n;
+const DEFAULT_BROWSE_LIMIT = 20;
+const SCORE_SCALE = 1_000_000n;
+
+export interface BrowseOpenTasksFilters {
+  category?: string;
+  minPriceMist?: bigint;
+  maxPriceMist?: bigint;
+  limit?: number;
+}
+
+export class MarketplaceClient {
+  private readonly taskClient: TaskClient;
+  private readonly registryClient: RegistryClient;
+  private readonly scoreCalculator = new ReputationScoreCalculator();
+
+  constructor(
+    private readonly suiClient: MeshSuiClient,
+    private readonly config: NetworkConfig,
+  ) {
+    this.taskClient = new TaskClient(suiClient, config);
+    this.registryClient = new RegistryClient(suiClient, config);
+  }
+
+  async postOpenTask(params: {
+    capability: string;
+    category: string;
+    inputBlobId: string;
+    agreementHash?: string;
+    priceMist: bigint;
+    disputeWindowMs: number;
+    expiryHours: number;
+    signer: Signer;
+  }): Promise<{ txDigest: string; taskId: string }> {
+    return await this.taskClient.postTask({
+      capability: params.capability,
+      category: params.category,
+      inputBlobId: params.inputBlobId,
+      agreementHash: params.agreementHash,
+      priceMist: params.priceMist,
+      disputeWindowMs: params.disputeWindowMs,
+      expiryHours: params.expiryHours,
+      keypair: params.signer,
+    });
+  }
+
+  async placeBid(params: {
+    taskId: string;
+    bidPriceMist: bigint;
+    signer: Signer;
+    reputationScore?: bigint | number;
+    evidenceBlob?: string;
+  }): Promise<{ bidId: string; txDigest: string; reputationScore: bigint }> {
+    const reputationScore = params.reputationScore == null
+      ? await this.deriveReputationScore(params.signer.getPublicKey().toSuiAddress())
+      : toNonNegativeBigInt(params.reputationScore, 'params.reputationScore');
+
+    const tx = buildPlaceBidTx({
+      packageId: this.config.packageId,
+      taskId: params.taskId,
+      bidPriceMist: params.bidPriceMist,
+      reputationScore,
+      evidenceBlob: params.evidenceBlob,
+    });
+    const response = await this.suiClient.executeTransaction(tx, params.signer);
+    const bidId = extractObjectId(response, /::marketplace::Bid$/);
+    if (!bidId) {
+      logger.warn({ response }, 'Bid placement succeeded without a Bid object change.');
+      throw new Error('Unable to determine bid id from transaction response.');
+    }
+
+    return { bidId, txDigest: response.digest, reputationScore };
+  }
+
+  async acceptBid(params: {
+    taskId: string;
+    bidId: string;
+    signer: Signer;
+    rejectCompeting?: boolean;
+  }): Promise<{ txDigest: string; rejectedBidIds: string[] }> {
+    const rejectedBidIds = params.rejectCompeting === false
+      ? []
+      : (await this.getBidsForTask(params.taskId))
+        .filter((bid) => bid.id !== params.bidId && bid.status === BidStatus.ACTIVE)
+        .map((bid) => bid.id);
+
+    const tx = buildAcceptBidTx({
+      packageId: this.config.packageId,
+      taskId: params.taskId,
+      bidId: params.bidId,
+      otherBidIds: rejectedBidIds,
+    });
+    const response = await this.suiClient.executeTransaction(tx, params.signer);
+    return { txDigest: response.digest, rejectedBidIds };
+  }
+
+  async withdrawBid(params: { bidId: string; signer: Signer }): Promise<{ txDigest: string }> {
+    const tx = buildWithdrawBidTx({ packageId: this.config.packageId, bidId: params.bidId });
+    const response = await this.suiClient.executeTransaction(tx, params.signer);
+    return { txDigest: response.digest };
+  }
+
+  async rejectBid(params: { taskId: string; bidId: string; signer: Signer }): Promise<{ txDigest: string }> {
+    const tx = buildRejectBidTx({ packageId: this.config.packageId, taskId: params.taskId, bidId: params.bidId });
+    const response = await this.suiClient.executeTransaction(tx, params.signer);
+    return { txDigest: response.digest };
+  }
+
+  async getBid(bidId: string): Promise<Bid | null> {
+    try {
+      const object = await this.suiClient.getObject<Record<string, unknown>>(bidId);
+      return parseBidFields(object, bidId);
+    } catch (error) {
+      if (isObjectMissingError(error)) {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  async getBidsForTask(taskId: string): Promise<Bid[]> {
+    const eventType = `${this.config.packageId}::marketplace::BidPlaced`;
+    const bidIds = new Set<string>();
+    let cursor = null;
+
+    do {
+      const page = await this.suiClient.queryEvents(eventType, cursor, 100);
+      for (const event of page.events) {
+        const payload = normalizeEvent(event);
+        if (asString(readField(payload, 'task_id', 'taskId')) !== taskId) {
+          continue;
+        }
+        const bidId = asString(readField(payload, 'bid_id', 'bidId'));
+        if (bidId) {
+          bidIds.add(bidId);
+        }
+      }
+
+      cursor = page.nextCursor;
+      if (!page.hasMore) {
+        break;
+      }
+    } while (cursor);
+
+    const bids = await Promise.all([...bidIds].map(async (bidId) => await this.getBid(bidId)));
+    return bids
+      .filter((bid): bid is Bid => Boolean(bid))
+      .sort((left, right) => left.createdAt - right.createdAt || compareBigInt(left.bidPrice, right.bidPrice));
+  }
+
+  async browseOpenTasks(filters: BrowseOpenTasksFilters = {}): Promise<Task[]> {
+    const eventType = `${this.config.packageId}::task::TaskPosted`;
+    const limit = normalizeLimit(filters.limit, DEFAULT_BROWSE_LIMIT, 'filters.limit');
+    const category = normalizeOptionalCategory(filters.category);
+    if (filters.minPriceMist != null && filters.maxPriceMist != null && filters.minPriceMist > filters.maxPriceMist) {
+      throw new Error('filters.minPriceMist must be less than or equal to filters.maxPriceMist.');
+    }
+    const taskIds = new Set<string>();
+    const tasks: Task[] = [];
+    let cursor = null;
+
+    do {
+      const page = await this.suiClient.queryEvents(eventType, cursor, Math.max(limit * 3, 20));
+      for (const event of page.events) {
+        const postedTask = parseTaskFields(normalizeEvent(event));
+        if (!postedTask.id || taskIds.has(postedTask.id)) {
+          continue;
+        }
+        if (category && postedTask.category.toLowerCase() !== category.toLowerCase()) {
+          continue;
+        }
+
+        const current = await this.taskClient.getTask(postedTask.id);
+        if (!current || current.status !== TaskStatus.OPEN || Date.now() >= current.expiresAt) {
+          continue;
+        }
+        if (category && current.category.toLowerCase() !== category.toLowerCase()) {
+          continue;
+        }
+        if (filters.minPriceMist != null && current.price < filters.minPriceMist) {
+          continue;
+        }
+        if (filters.maxPriceMist != null && current.price > filters.maxPriceMist) {
+          continue;
+        }
+
+        taskIds.add(current.id);
+        tasks.push(current);
+        if (tasks.length >= limit) {
+          return tasks.sort((left, right) => right.createdAt - left.createdAt);
+        }
+      }
+
+      cursor = page.nextCursor;
+      if (!page.hasMore) {
+        break;
+      }
+    } while (cursor);
+
+    return tasks.sort((left, right) => right.createdAt - left.createdAt);
+  }
+
+  async getRecommendedBid(
+    taskId: string,
+    options: { reputationWeight?: bigint | number; priceWeight?: bigint | number } = {},
+  ): Promise<BidRecommendation | null> {
+    const bids = (await this.getBidsForTask(taskId)).filter((bid) => bid.status === BidStatus.ACTIVE);
+    if (bids.length === 0) {
+      return null;
+    }
+
+    const reputationWeight = options.reputationWeight == null
+      ? DEFAULT_REPUTATION_WEIGHT
+      : toNonNegativeBigInt(options.reputationWeight, 'options.reputationWeight');
+    const priceWeight = options.priceWeight == null
+      ? DEFAULT_PRICE_WEIGHT
+      : toNonNegativeBigInt(options.priceWeight, 'options.priceWeight');
+    const ranked = bids
+      .map((bid) => ({
+        bid,
+        score: calculateBidSelectionScore(bid.reputationScore, bid.bidPrice, reputationWeight, priceWeight),
+        reputationWeight,
+        priceWeight,
+      }))
+      .sort((left, right) => {
+        if (left.score !== right.score) {
+          return left.score > right.score ? -1 : 1;
+        }
+        return compareBigInt(left.bid.bidPrice, right.bid.bidPrice) || left.bid.createdAt - right.bid.createdAt;
+      });
+
+    return ranked[0] ?? null;
+  }
+
+  private async deriveReputationScore(owner: string): Promise<bigint> {
+    const card = await this.registryClient.getAgentCardByOwner(owner);
+    if (!card) {
+      return 0n;
+    }
+
+    const score = this.scoreCalculator.computeScore(card, []);
+    const stakeBonus = score.stakeAmount / 1_000_000_000n;
+    const boundedStakeBonus = stakeBonus > 10_000n ? 10_000n : stakeBonus;
+    const reputationScore = Math.max(
+      Math.round(score.successRate * 1_000) + (score.totalTasks * 10) - (score.totalDisputes * 25),
+      0,
+    );
+    return BigInt(reputationScore) + boundedStakeBonus;
+  }
+}
+
+function calculateBidSelectionScore(
+  reputationScore: bigint,
+  bidPrice: bigint,
+  reputationWeight: bigint,
+  priceWeight: bigint,
+): bigint {
+  return (reputationScore * reputationWeight * SCORE_SCALE) / ((bidPrice * priceWeight) + 1n);
+}
+
+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 normalizeEvent(event: SuiEvent): Record<string, unknown> {
+  const normalized = normalizeMoveValue(event.parsedJson);
+  return isRecord(normalized) ? normalized : {};
+}
+
+function readField(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 compareBigInt(left: bigint, right: bigint): number {
+  if (left === right) {
+    return 0;
+  }
+  return left < right ? -1 : 1;
+}
+
+function toNonNegativeBigInt(value: bigint | number, field: string): bigint {
+  if (typeof value === 'bigint') {
+    if (value < 0n) {
+      throw new Error(`${field} must be non-negative.`);
+    }
+    return value;
+  }
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new Error(`${field} must be a non-negative safe integer.`);
+  }
+  return BigInt(value);
+}
+
+function normalizeLimit(value: number | undefined, fallback: number, field: string): number {
+  if (value == null) {
+    return fallback;
+  }
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new Error(`${field} must be a positive safe integer.`);
+  }
+  return value;
+}
+
+function normalizeOptionalCategory(value: string | undefined): string | undefined {
+  if (value == null) {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    throw new Error('filters.category must be a non-empty string when provided.');
+  }
+  return trimmed;
+}
+
+function isObjectMissingError(error: unknown): boolean {
+  return error instanceof Error && /not found|does not contain move object data/i.test(error.message);
+}

package/src/marketplace/index.ts

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

package/src/metering/hash-chain.ts

@@ -0,0 +1,94 @@
+import { sha256 } from '@noble/hashes/sha256';
+
+import type { HashChainProof } from '@hivemind-os/collective-types';
+
+const encoder = new TextEncoder();
+const DEFAULT_SEED_PREFIX = 'agentic-mesh:metering:v1';
+const HASH_HEX_PATTERN = /^[a-f0-9]{64}$/i;
+
+export const DEFAULT_METERING_CHUNK_SIZE = 1024;
+
+export class HashChain {
+  private currentHash: Uint8Array;
+  private readonly intermediateHashes: string[] = [];
+
+  constructor(private readonly seed: Uint8Array = encoder.encode(DEFAULT_SEED_PREFIX)) {
+    this.currentHash = hashBytes(this.seed);
+  }
+
+  addUnit(data: Uint8Array): string {
+    this.currentHash = hashBytes(concatBytes(this.currentHash, data));
+    const hash = bytesToHex(this.currentHash);
+    this.intermediateHashes.push(hash);
+    return hash;
+  }
+
+  getRoot(): string {
+    return bytesToHex(this.currentHash);
+  }
+
+  getProof(): HashChainProof {
+    return {
+      root: this.getRoot(),
+      intermediateHashes: [...this.intermediateHashes],
+      unitCount: this.intermediateHashes.length,
+    };
+  }
+
+  static verifyChain(proof: HashChainProof, unitData: Uint8Array[], seed: Uint8Array = encoder.encode(DEFAULT_SEED_PREFIX)): boolean {
+    if (
+      proof.unitCount !== unitData.length
+      || proof.intermediateHashes.length !== unitData.length
+      || !HASH_HEX_PATTERN.test(proof.root)
+      || proof.intermediateHashes.some((entry) => !HASH_HEX_PATTERN.test(entry))
+    ) {
+      return false;
+    }
+
+    let currentHash = hashBytes(seed);
+    for (const [index, unit] of unitData.entries()) {
+      currentHash = hashBytes(concatBytes(currentHash, unit));
+      if (bytesToHex(currentHash) !== proof.intermediateHashes[index]) {
+        return false;
+      }
+    }
+
+    return bytesToHex(currentHash) === proof.root;
+  }
+}
+
+export function createMeteringSeed(taskId: string): Uint8Array {
+  return encoder.encode(`${DEFAULT_SEED_PREFIX}:${taskId}`);
+}
+
+export function splitIntoMeteringUnits(data: Uint8Array, chunkSize = DEFAULT_METERING_CHUNK_SIZE): Uint8Array[] {
+  if (!Number.isSafeInteger(chunkSize) || chunkSize <= 0) {
+    throw new Error('chunkSize must be a positive safe integer.');
+  }
+
+  if (data.length === 0) {
+    return [];
+  }
+
+  const units: Uint8Array[] = [];
+  for (let offset = 0; offset < data.length; offset += chunkSize) {
+    units.push(data.slice(offset, Math.min(offset + chunkSize, data.length)));
+  }
+
+  return units;
+}
+
+function hashBytes(data: Uint8Array): Uint8Array {
+  return sha256(data);
+}
+
+function concatBytes(left: Uint8Array, right: Uint8Array): Uint8Array {
+  const result = new Uint8Array(left.length + right.length);
+  result.set(left, 0);
+  result.set(right, left.length);
+  return result;
+}
+
+function bytesToHex(value: Uint8Array): string {
+  return Buffer.from(value).toString('hex');
+}

package/src/metering/index.ts

@@ -0,0 +1,4 @@
+export * from './hash-chain.js';
+export * from './meter.js';
+export * from './streaming.js';
+export * from './verification.js';

package/src/metering/meter.ts

@@ -0,0 +1,80 @@
+import type { HashChainProof, MeteringReport } from '@hivemind-os/collective-types';
+
+import { HashChain, createMeteringSeed } from './hash-chain.js';
+
+const MAX_U64 = (1n << 64n) - 1n;
+const MAX_RECORDED_UNITS = Number.MAX_SAFE_INTEGER;
+
+export interface UsageMeterOptions {
+  taskId: string;
+  maxPrice: bigint;
+  unitPrice?: bigint;
+  seed?: Uint8Array;
+}
+
+export class UsageMeter {
+  private readonly hashChain: HashChain;
+  private actualUnits = 0;
+  private readonly taskId: string;
+  private readonly maxPrice: bigint;
+  private readonly unitPrice: bigint;
+
+  constructor(options: UsageMeterOptions) {
+    const taskId = options.taskId.trim();
+    const maxPrice = options.maxPrice;
+    const unitPrice = options.unitPrice ?? 0n;
+    if (!taskId) {
+      throw new Error('taskId is required.');
+    }
+    if (maxPrice < 0n || unitPrice < 0n) {
+      throw new Error('maxPrice and unitPrice must be non-negative.');
+    }
+    if (maxPrice > MAX_U64 || unitPrice > MAX_U64) {
+      throw new Error('maxPrice and unitPrice must fit in an unsigned 64-bit integer.');
+    }
+
+    this.taskId = taskId;
+    this.maxPrice = maxPrice;
+    this.unitPrice = unitPrice;
+    this.hashChain = new HashChain(options.seed ?? createMeteringSeed(taskId));
+  }
+
+  recordUnit(data: Uint8Array): number {
+    if (this.actualUnits >= MAX_RECORDED_UNITS) {
+      throw new Error('Too many metering units recorded.');
+    }
+
+    this.hashChain.addUnit(data);
+    this.actualUnits += 1;
+    return this.actualUnits;
+  }
+
+  getActualUnits(): number {
+    return this.actualUnits;
+  }
+
+  getVerificationHash(): string {
+    return this.hashChain.getRoot();
+  }
+
+  getProof(): HashChainProof {
+    return this.hashChain.getProof();
+  }
+
+  getCost(unitPrice = this.unitPrice): bigint {
+    const uncapped = BigInt(this.actualUnits) * unitPrice;
+    return uncapped > this.maxPrice ? this.maxPrice : uncapped;
+  }
+
+  getReport(): MeteringReport {
+    const actualCost = this.getCost();
+    return {
+      taskId: this.taskId,
+      actualUnits: this.actualUnits,
+      actualCost,
+      maxPrice: this.maxPrice,
+      refundAmount: this.maxPrice - actualCost,
+      verificationHash: this.getVerificationHash(),
+    };
+  }
+}