@hivemind-os/collective-core 0.2.0

package/src/relay-registry/client.ts

@@ -0,0 +1,295 @@
+import pino from 'pino';
+
+import { RelayNodeStatus, type RelayListFilters, type RelayNode } from '@hivemind-os/collective-types';
+import type { SuiEvent, SuiTransactionBlockResponse } from '@mysten/sui/client';
+import type { Signer } from '@mysten/sui/cryptography';
+
+import { isRecord, normalizeMoveValue, parseRelayNodeFields } from '../internal/parsing.js';
+import { MeshSuiClient } from '../sui/client.js';
+import {
+  buildDeactivateRelayTx,
+  buildHeartbeatRelayTx,
+  buildRegisterRelayTx,
+} from '../sui/tx-helpers.js';
+import { StakingClient } from '../staking/client.js';
+
+const logger = pino({ name: '@hivemind-os/collective-core:relay-registry' });
+
+export interface RelayRegistryContractConfig {
+  packageId: string;
+  heartbeatFreshnessMs?: number;
+}
+
+export const DEFAULT_RELAY_HEARTBEAT_FRESHNESS_MS = 5 * 60_000;
+
+export class RelayRegistryClient {
+  private readonly stakingClient: StakingClient;
+  private readonly heartbeatFreshnessMs: number;
+
+  constructor(
+    private readonly suiClient: MeshSuiClient,
+    private readonly config: RelayRegistryContractConfig,
+  ) {
+    this.stakingClient = new StakingClient(suiClient, config);
+    this.heartbeatFreshnessMs = config.heartbeatFreshnessMs ?? DEFAULT_RELAY_HEARTBEAT_FRESHNESS_MS;
+  }
+
+  async registerRelay(params: {
+    endpoint: string;
+    stakeId: string;
+    capabilities: string[];
+    region: string;
+    routingFeeBps: number;
+    signer: Signer;
+  }): Promise<{ relayId: string; txDigest: string }> {
+    const tx = buildRegisterRelayTx({
+      packageId: this.config.packageId,
+      endpoint: params.endpoint,
+      stakeId: params.stakeId,
+      capabilities: params.capabilities,
+      region: params.region,
+      routingFeeBps: params.routingFeeBps,
+    });
+    const response = await this.suiClient.executeTransaction(tx, params.signer);
+    const relayId = readRelayId(response, `${this.config.packageId}::relay_registry::RelayRegistered`);
+    if (!relayId) {
+      logger.warn({ response }, 'Relay registration succeeded without a RelayNode object change.');
+      throw new Error('Unable to determine relay id from transaction response.');
+    }
+    return { relayId, txDigest: response.digest };
+  }
+
+  async heartbeat(params: { relayId: string; signer: Signer }): Promise<{ lastHeartbeat: number; txDigest: string }> {
+    const tx = buildHeartbeatRelayTx({ packageId: this.config.packageId, relayId: params.relayId });
+    const response = await this.suiClient.executeTransaction(tx, params.signer);
+    const event = findEvent(response.events, `${this.config.packageId}::relay_registry::RelayHeartbeat`);
+    return {
+      lastHeartbeat: requireEventNumber(event, 'RelayHeartbeat', 'last_heartbeat', 'lastHeartbeat'),
+      txDigest: response.digest,
+    };
+  }
+
+  async recordRouting(params: { relayId: string; feeAmountMist: bigint; signer: Signer }): Promise<{ txDigest: string }> {
+    void params;
+    throw new Error('Relay routing metrics are package-internal and cannot be reported by external operators.');
+  }
+
+  async deactivateRelay(params: { relayId: string; signer: Signer }): Promise<{ txDigest: string }> {
+    const tx = buildDeactivateRelayTx({ packageId: this.config.packageId, relayId: params.relayId });
+    const response = await this.suiClient.executeTransaction(tx, params.signer);
+    return { txDigest: response.digest };
+  }
+
+  async listRelays(filters: RelayListFilters = {}): Promise<RelayNode[]> {
+    const relayIds = await this.collectRelayIds();
+    const relays = await Promise.all([...relayIds].map(async (relayId) => await this.getRelay(relayId)));
+    return relays
+      .filter((relay): relay is RelayNode => Boolean(relay))
+      .filter((relay) => matchesRelayFilters(relay, filters))
+      .sort(compareRelays);
+  }
+
+  async getRelay(relayId: string): Promise<RelayNode | null> {
+    try {
+      const object = await this.suiClient.getObject<Record<string, unknown>>(relayId);
+      return await this.enrichRelay(parseRelayNodeFields(object, relayId));
+    } catch (error) {
+      if (isObjectMissingError(error)) {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  async getRelaysByRegion(region: string): Promise<RelayNode[]> {
+    return await this.listRelays({ region });
+  }
+
+  private async collectRelayIds(): Promise<Set<string>> {
+    const relayIds = new Set<string>();
+    const eventType = `${this.config.packageId}::relay_registry::RelayRegistered`;
+    let cursor = null;
+
+    do {
+      const page = await this.suiClient.queryEvents(eventType, cursor, 100);
+      for (const event of page.events) {
+        const payload = normalizeEvent(event);
+        const relayId = asString(readEventField(payload, 'relay_id', 'relayId'));
+        if (relayId) {
+          relayIds.add(relayId);
+        }
+      }
+      cursor = page.nextCursor;
+      if (!page.hasMore) {
+        break;
+      }
+    } while (cursor);
+
+    return relayIds;
+  }
+
+  private async enrichRelay(relay: RelayNode): Promise<RelayNode> {
+    const heartbeatAgeMs = Math.max(Date.now() - relay.lastHeartbeat, 0);
+    try {
+      const stake = await this.stakingClient.getStakePosition(relay.stakePositionId);
+      return {
+        ...relay,
+        stakeAmountMist: stake?.balanceMist,
+        heartbeatAgeMs,
+        isHeartbeatFresh: heartbeatAgeMs <= this.heartbeatFreshnessMs,
+      };
+    } catch {
+      return {
+        ...relay,
+        heartbeatAgeMs,
+        isHeartbeatFresh: heartbeatAgeMs <= this.heartbeatFreshnessMs,
+      };
+    }
+  }
+}
+
+function readRelayId(response: SuiTransactionBlockResponse, eventType: string): string | undefined {
+  const event = findEvent(response.events, eventType);
+  return asString(readEventField(event, 'relay_id', 'relayId')) || extractObjectId(response, /::relay_registry::RelayNode$/);
+}
+
+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 asNumber(value: unknown): number {
+  if (typeof value === 'number') {
+    return value;
+  }
+  if (typeof value === 'bigint') {
+    return Number(value);
+  }
+  if (typeof value === 'string' && value.length > 0) {
+    return Number(value);
+  }
+  return 0;
+}
+
+function requireEventNumber(record: Record<string, unknown>, eventName: string, ...keys: string[]): number {
+  const raw = readEventField(record, ...keys);
+  if (raw == null || raw === '') {
+    throw new Error(`${eventName} event did not include a valid ${keys[0]}.`);
+  }
+  const value = asNumber(raw);
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new Error(`${eventName} event did not include a valid ${keys[0]}.`);
+  }
+  return value;
+}
+
+function matchesRelayFilters(relay: RelayNode, filters: RelayListFilters): boolean {
+  const activeOnly = filters.status === undefined && filters.activeOnly === undefined ? true : (filters.activeOnly ?? false);
+  const statuses = normalizeStatuses(filters.status, activeOnly);
+  if (!statuses.includes(relay.status)) {
+    return false;
+  }
+  if (filters.operator && relay.operator.toLowerCase() !== filters.operator.toLowerCase()) {
+    return false;
+  }
+  if (filters.region && relay.region.toLowerCase() !== filters.region.toLowerCase()) {
+    return false;
+  }
+  if (filters.stakePositionId && relay.stakePositionId.toLowerCase() !== filters.stakePositionId.toLowerCase()) {
+    return false;
+  }
+  if (filters.endpoint && relay.endpoint.toLowerCase() !== filters.endpoint.toLowerCase()) {
+    return false;
+  }
+  if (filters.capability) {
+    const capability = filters.capability.toLowerCase();
+    if (!relay.capabilities.some((entry) => entry.toLowerCase() === capability)) {
+      return false;
+    }
+  }
+  if (filters.heartbeatWithinMs !== undefined && (relay.heartbeatAgeMs ?? Number.POSITIVE_INFINITY) > filters.heartbeatWithinMs) {
+    return false;
+  }
+  return true;
+}
+
+function normalizeStatuses(status: RelayListFilters['status'], activeOnly: boolean): RelayNodeStatus[] {
+  if (Array.isArray(status)) {
+    return status;
+  }
+  if (status !== undefined) {
+    return [status];
+  }
+  return activeOnly
+    ? [RelayNodeStatus.ACTIVE]
+    : [RelayNodeStatus.ACTIVE, RelayNodeStatus.INACTIVE, RelayNodeStatus.SLASHED];
+}
+
+function compareRelays(left: RelayNode, right: RelayNode): number {
+  return (
+    compareBoolean(left.status === RelayNodeStatus.ACTIVE, right.status === RelayNodeStatus.ACTIVE) ||
+    compareBoolean(left.isHeartbeatFresh ?? false, right.isHeartbeatFresh ?? false) ||
+    compareNumber(left.routingFeeBps, right.routingFeeBps, true) ||
+    compareBigInt(left.stakeAmountMist ?? 0n, right.stakeAmountMist ?? 0n) ||
+    compareNumber(left.lastHeartbeat, right.lastHeartbeat)
+  );
+}
+
+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, ascending = false): number {
+  if (left === right) {
+    return 0;
+  }
+  if (ascending) {
+    return left < right ? -1 : 1;
+  }
+  return left > right ? -1 : 1;
+}
+
+function isObjectMissingError(error: unknown): boolean {
+  return error instanceof Error && /not found|does not contain move object data/i.test(error.message);
+}

package/src/relay-registry/discovery.ts

@@ -0,0 +1,109 @@
+import { RelayNodeStatus, type RelayNode } from '@hivemind-os/collective-types';
+
+import { DEFAULT_RELAY_HEARTBEAT_FRESHNESS_MS, type RelayRegistryClient } from './client.js';
+
+export interface RelayDiscoveryOptions {
+  cacheTtlMs?: number;
+  heartbeatFreshnessMs?: number;
+  now?: () => number;
+}
+
+interface RelayCacheEntry {
+  relays: RelayNode[];
+  expiresAt: number;
+}
+
+export class RelayDiscovery {
+  private readonly cacheTtlMs: number;
+  private readonly heartbeatFreshnessMs: number;
+  private readonly now: () => number;
+  private cache?: RelayCacheEntry;
+
+  constructor(
+    private readonly registryClient: Pick<RelayRegistryClient, 'listRelays'>,
+    options: RelayDiscoveryOptions = {},
+  ) {
+    this.cacheTtlMs = options.cacheTtlMs ?? 30_000;
+    this.heartbeatFreshnessMs = options.heartbeatFreshnessMs ?? DEFAULT_RELAY_HEARTBEAT_FRESHNESS_MS;
+    this.now = options.now ?? (() => Date.now());
+  }
+
+  async findBestRelay(capability: string, region?: string): Promise<RelayNode | null> {
+    const normalizedCapability = capability.trim().toLowerCase();
+    if (!normalizedCapability) {
+      throw new Error('capability must be a non-empty string.');
+    }
+
+    const normalizedRegion = region?.trim() || undefined;
+    const relays = (await this.getRelayList())
+      .filter((relay) => relay.status === RelayNodeStatus.ACTIVE)
+      .filter((relay) => relay.capabilities.some((entry) => entry.toLowerCase() === normalizedCapability));
+
+    if (relays.length === 0) {
+      return null;
+    }
+
+    return [...relays].sort(
+      (left, right) => scoreRelay(right, normalizedRegion, this.heartbeatFreshnessMs, this.now())
+        - scoreRelay(left, normalizedRegion, this.heartbeatFreshnessMs, this.now()),
+    )[0] ?? null;
+  }
+
+  invalidateCache(): void {
+    this.cache = undefined;
+  }
+
+  private async getRelayList(): Promise<RelayNode[]> {
+    const now = this.now();
+    if (this.cache && this.cache.expiresAt > now) {
+      return this.cache.relays.map((relay) => ({ ...relay }));
+    }
+
+    const relays = (await this.registryClient.listRelays({ activeOnly: true })).map((relay) => ({ ...relay }));
+    this.cache = {
+      relays,
+      expiresAt: now + this.cacheTtlMs,
+    };
+    return relays.map((relay) => ({ ...relay }));
+  }
+}
+
+function scoreRelay(relay: RelayNode, region: string | undefined, heartbeatFreshnessMs: number, now: number): number {
+  const feeScore = Math.max(0, 1 - relay.routingFeeBps / 10_000);
+  const regionScore = scoreRegion(relay.region, region);
+  const stakeScore = scoreStake(relay.stakeAmountMist ?? 0n);
+  const freshnessScore = scoreHeartbeat(relay.heartbeatAgeMs ?? Math.max(now - relay.lastHeartbeat, 0), heartbeatFreshnessMs);
+
+  return feeScore * 0.35 + regionScore * 0.25 + stakeScore * 0.2 + freshnessScore * 0.2;
+}
+
+function scoreRegion(relayRegion: string, desiredRegion: string | undefined): number {
+  if (!desiredRegion) {
+    return 0.5;
+  }
+
+  const normalizedRelayRegion = relayRegion.trim().toLowerCase();
+  const normalizedDesiredRegion = desiredRegion.trim().toLowerCase();
+  if (normalizedRelayRegion === normalizedDesiredRegion) {
+    return 1;
+  }
+
+  const relayPrefix = normalizedRelayRegion.split(/[-_\s]/)[0];
+  const desiredPrefix = normalizedDesiredRegion.split(/[-_\s]/)[0];
+  return relayPrefix && relayPrefix === desiredPrefix ? 0.65 : 0;
+}
+
+function scoreStake(stakeAmountMist: bigint): number {
+  const capped = stakeAmountMist > 1_000_000_000_000n ? 1_000_000_000_000n : stakeAmountMist;
+  return Number(capped) / Number(1_000_000_000_000n);
+}
+
+function scoreHeartbeat(heartbeatAgeMs: number, heartbeatFreshnessMs: number): number {
+  if (heartbeatAgeMs <= heartbeatFreshnessMs) {
+    return 1;
+  }
+  if (heartbeatAgeMs >= heartbeatFreshnessMs * 4) {
+    return 0;
+  }
+  return 1 - (heartbeatAgeMs - heartbeatFreshnessMs) / (heartbeatFreshnessMs * 3);
+}

package/src/relay-registry/index.ts

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

package/src/reputation/anchor-client.ts

@@ -0,0 +1,126 @@
+import type { ReputationAnchor, ReputationEvent } from '@hivemind-os/collective-types';
+import type { Signer } from '@mysten/sui/cryptography';
+
+import type { BlobStore } from '../blobstore/interface.js';
+import { bytesToHex, bytesToString } from '../internal/parsing.js';
+import { MeshSuiClient } from '../sui/client.js';
+import { buildPublishReputationAnchorTx } from '../sui/tx-helpers.js';
+
+import { buildMerkleTree } from './merkle.js';
+
+export interface ContractConfig {
+  packageId: string;
+}
+
+export class ReputationAnchorClient {
+  constructor(
+    private readonly suiClient: MeshSuiClient,
+    private readonly config: ContractConfig,
+  ) {}
+
+  async publishAnchor(
+    events: ReputationEvent[],
+    blobStore: BlobStore,
+    signer: Signer,
+  ): Promise<{ anchorId: string; merkleRoot: string; txDigest: string }> {
+    if (events.length === 0) {
+      throw new Error('At least one reputation event is required to publish an anchor.');
+    }
+
+    const { root } = buildMerkleTree(events);
+    const stored = await blobStore.store(new TextEncoder().encode(JSON.stringify(events)));
+    const timestamps = events.map((event) => Date.parse(event.timestamp)).filter(Number.isFinite);
+    const tx = buildPublishReputationAnchorTx({
+      packageId: this.config.packageId,
+      merkleRoot: [...root],
+      eventCount: events.length,
+      blobId: stored.blobId,
+      fromTimestamp: timestamps.length > 0 ? Math.min(...timestamps) : 0,
+      toTimestamp: timestamps.length > 0 ? Math.max(...timestamps) : 0,
+    });
+    const response = await this.suiClient.executeTransaction(tx, signer);
+    const anchorId = extractObjectId(response.objectChanges, /::reputation::ReputationAnchor$/);
+    if (!anchorId) {
+      throw new Error('Unable to determine reputation anchor id from transaction response.');
+    }
+
+    return {
+      anchorId,
+      merkleRoot: Buffer.from(root).toString('hex'),
+      txDigest: response.digest,
+    };
+  }
+
+  async getAnchors(author?: string, limit = 20): Promise<ReputationAnchor[]> {
+    const eventType = `${this.config.packageId}::reputation::AnchorPublished`;
+    const anchors: ReputationAnchor[] = [];
+    let cursor = null;
+
+    do {
+      const page = await this.suiClient.queryEvents(eventType, cursor, Math.max(limit * 2, 20));
+      const candidates = page.events.filter((event) => {
+        const payload = event.parsedJson as { author?: string } | null | undefined;
+        return !author || payload?.author === author;
+      });
+      const fetched = await Promise.all(candidates.map((event) => this.fetchAnchor(asString((event.parsedJson as { anchor_id?: string })?.anchor_id))));
+      anchors.push(...fetched.filter((anchor): anchor is ReputationAnchor => Boolean(anchor)));
+      if (anchors.length >= limit) {
+        return anchors.slice(0, limit);
+      }
+      cursor = page.nextCursor;
+      if (!page.hasMore) {
+        break;
+      }
+    } while (cursor);
+
+    return anchors.slice(0, limit);
+  }
+
+  private async fetchAnchor(anchorId: string): Promise<ReputationAnchor | null> {
+    if (!anchorId) {
+      return null;
+    }
+
+    try {
+      const object = await this.suiClient.getObject<Record<string, unknown>>(anchorId);
+      return {
+        anchorId,
+        author: asString(object.author),
+        merkleRoot: bytesToHex(asBytes(object.merkle_root)),
+        eventCount: Number(object.event_count ?? 0),
+        blobId: bytesToString(object.blob_id),
+        fromTimestamp: Number(object.from_timestamp ?? 0),
+        toTimestamp: Number(object.to_timestamp ?? 0),
+      };
+    } catch {
+      return null;
+    }
+  }
+}
+
+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 asString(value: unknown): string {
+  return typeof value === 'string' ? value : '';
+}
+
+function asBytes(value: unknown): Uint8Array {
+  if (value instanceof Uint8Array) {
+    return value;
+  }
+  if (Array.isArray(value) && value.every((entry) => typeof entry === 'number')) {
+    return new Uint8Array(value);
+  }
+  return new Uint8Array();
+}

package/src/reputation/event-publisher.ts

@@ -0,0 +1,67 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+
+import type { ReputationEvent, ReputationEventType } from '@hivemind-os/collective-types';
+
+import type { AuthProvider } from '../auth/types.js';
+import type { BlobStore } from '../blobstore/interface.js';
+
+import { serializeReputationEvent, serializeReputationEventPayload } from './serialization.js';
+import { assertValidReputationEvent } from './validation.js';
+
+const decoder = new TextDecoder();
+
+export class ReputationEventPublisher {
+  constructor(
+    private readonly blobStore: BlobStore,
+    private readonly identity: AuthProvider,
+  ) {}
+
+  async createEvent(params: {
+    type: ReputationEventType;
+    subject: string;
+    taskId: string;
+    outcome: string;
+    capability: string;
+    rating?: number;
+    latencyMs?: number;
+    paymentAmount?: { amount: string; currency: string };
+  }): Promise<ReputationEvent> {
+    const unsignedEvent = {
+      eventId: `rep_evt_${randomUUID().replace(/-/g, '')}`,
+      type: params.type,
+      subject: params.subject,
+      author: this.identity.getDID(),
+      taskId: params.taskId,
+      outcome: normalizeOutcome(params.outcome),
+      rating: params.rating,
+      capability: params.capability,
+      paymentAmount: params.paymentAmount,
+      latencyMs: params.latencyMs,
+      timestamp: new Date().toISOString(),
+      nonce: randomBytes(16).toString('hex'),
+    } satisfies Omit<ReputationEvent, 'signature'>;
+
+    const signed = await this.identity.signPersonalMessage(serializeReputationEventPayload(unsignedEvent));
+    return assertValidReputationEvent({
+      ...unsignedEvent,
+      signature: decoder.decode(signed.signature),
+    });
+  }
+
+  async publishEvent(event: ReputationEvent): Promise<void> {
+    await this.blobStore.store(serializeReputationEvent(event));
+  }
+}
+
+function normalizeOutcome(outcome: string): ReputationEvent['outcome'] {
+  switch (outcome) {
+    case 'success':
+    case 'failure':
+    case 'timeout':
+    case 'cancelled':
+    case 'disputed':
+      return outcome;
+    default:
+      throw new Error(`Unsupported reputation outcome: ${outcome}`);
+  }
+}

package/src/reputation/index.ts

@@ -0,0 +1,5 @@
+export * from './anchor-client.js';
+export * from './event-publisher.js';
+export * from './merkle.js';
+export * from './score-calculator.js';
+export * from './store.js';

package/src/reputation/merkle.ts

@@ -0,0 +1,79 @@
+import { createHash } from 'node:crypto';
+
+import type { ReputationEvent } from '@hivemind-os/collective-types';
+
+import { serializeReputationEvent } from './serialization.js';
+
+export function buildMerkleTree(events: ReputationEvent[]): {
+  root: Uint8Array;
+  proof: (index: number) => Uint8Array[];
+} {
+  if (events.length === 0) {
+    throw new Error('Cannot build a Merkle tree from an empty event set.');
+  }
+
+  const leaves = events.map((event) => hash(serializeReputationEvent(event)));
+  const levels: Uint8Array[][] = [leaves];
+
+  while (levels[levels.length - 1]!.length > 1) {
+    const current = levels[levels.length - 1]!;
+    const next: Uint8Array[] = [];
+    for (let index = 0; index < current.length; index += 2) {
+      const left = current[index]!;
+      const right = current[index + 1] ?? left;
+      next.push(hash(concat(left, right)));
+    }
+    levels.push(next);
+  }
+
+  return {
+    root: levels[levels.length - 1]![0]!,
+    proof: (index: number) => createProof(levels, index),
+  };
+}
+
+export function verifyMerkleProof(
+  event: ReputationEvent,
+  proof: Uint8Array[],
+  root: Uint8Array,
+  index: number,
+): boolean {
+  let computed = hash(serializeReputationEvent(event));
+  let offset = index;
+
+  for (const sibling of proof) {
+    computed = offset % 2 === 0 ? hash(concat(computed, sibling)) : hash(concat(sibling, computed));
+    offset = Math.floor(offset / 2);
+  }
+
+  return Buffer.from(computed).equals(Buffer.from(root));
+}
+
+function createProof(levels: Uint8Array[][], index: number): Uint8Array[] {
+  const leaves = levels[0] ?? [];
+  if (!Number.isInteger(index) || index < 0 || index >= leaves.length) {
+    throw new Error(`Merkle proof index ${index} is out of range.`);
+  }
+
+  const proof: Uint8Array[] = [];
+  let offset = index;
+  for (let level = 0; level < levels.length - 1; level += 1) {
+    const nodes = levels[level]!;
+    const siblingIndex = offset % 2 === 0 ? offset + 1 : offset - 1;
+    proof.push(nodes[siblingIndex] ?? nodes[offset]!);
+    offset = Math.floor(offset / 2);
+  }
+
+  return proof;
+}
+
+function hash(data: Uint8Array): Uint8Array {
+  return createHash('sha256').update(data).digest();
+}
+
+function concat(left: Uint8Array, right: Uint8Array): Uint8Array {
+  const combined = new Uint8Array(left.length + right.length);
+  combined.set(left, 0);
+  combined.set(right, left.length);
+  return combined;
+}