@antseed/node 0.1.0 → 0.1.1

package/src/interfaces/seller-provider.ts

@@ -1,81 +0,0 @@
-import type { SerializedHttpRequest, SerializedHttpResponse } from '../types/http.js';
-import type { ProviderCapability } from '../types/capability.js';
-
-export interface ProviderTokenPricingUsdPerMillion {
-  inputUsdPerMillion: number;
-  outputUsdPerMillion: number;
-}
-
-export interface ProviderPricing {
-  defaults: ProviderTokenPricingUsdPerMillion;
-  models?: Record<string, ProviderTokenPricingUsdPerMillion>;
-}
-
-/**
- * Interface that seller nodes implement to provide inference.
- *
- * Each provider represents one upstream LLM service (e.g., Anthropic, OpenAI, local LLM).
- * The SDK handles P2P connections, discovery, metering, and payments.
- * You just handle the HTTP request → response conversion.
- */
-export interface Provider {
-  /** Unique name for this provider (e.g., 'anthropic', 'openai', 'my-local-llm') */
-  name: string;
-
-  /** Model IDs this provider supports (e.g., ['claude-sonnet-4-5-20250929', 'claude-opus-4-0-20250514']) */
-  models: string[];
-
-  /** Seller pricing in USD per 1M tokens (defaults + optional per-model overrides). */
-  pricing: ProviderPricing;
-
-  /** Maximum concurrent requests this provider can handle */
-  maxConcurrency: number;
-
-  /**
-   * Handle an incoming inference request and return the response.
-   */
-  handleRequest(req: SerializedHttpRequest): Promise<SerializedHttpResponse>;
-
-  /** Optional startup hook — validate credentials, warm caches, etc. */
-  init?(): Promise<void>;
-
-  /** Return current and maximum concurrent request counts */
-  getCapacity(): { current: number; max: number };
-
-  /** Capabilities beyond inference (optional — defaults to ['inference']) */
-  capabilities?: ProviderCapability[];
-
-  /** Handle a long-running agent task. Returns an async iterable of events. */
-  handleTask?(task: TaskRequest): AsyncIterable<TaskEvent>;
-
-  /** Handle a one-shot skill request. */
-  handleSkill?(skill: SkillRequest): Promise<SkillResponse>;
-}
-
-export interface TaskRequest {
-  taskId: string;
-  capability: ProviderCapability;
-  input: unknown;
-  metadata?: Record<string, unknown>;
-}
-
-export interface TaskEvent {
-  taskId: string;
-  type: 'status' | 'progress' | 'intermediate' | 'final';
-  data: unknown;
-  timestamp: number;
-}
-
-export interface SkillRequest {
-  skillId: string;
-  capability: ProviderCapability;
-  input: unknown;
-  inputSchema?: Record<string, unknown>;
-}
-
-export interface SkillResponse {
-  skillId: string;
-  output: unknown;
-  outputSchema?: Record<string, unknown>;
-  durationMs: number;
-}

package/src/metering/index.ts

@@ -1,6 +0,0 @@
-export { estimateTokens, estimateTokensFromContentLength, estimateTokensFromStreamBytes, BYTES_PER_TOKEN, MIN_REQUEST_TOKENS, MIN_RESPONSE_TOKENS } from './token-counter.js';
-export { MeteringStorage } from './storage.js';
-export { ReceiptGenerator, buildSignaturePayload, calculateCost, type Signer } from './receipt-generator.js';
-export { ReceiptVerifier, type SignatureVerifier, type VerifierOptions } from './receipt-verifier.js';
-export { SessionTracker } from './session-tracker.js';
-export { UsageAggregator, type AggregationGranularity, type TimePeriod } from './usage-aggregator.js';

package/src/metering/receipt-generator.ts

@@ -1,105 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import type { ProviderType, TokenCount, UsageReceipt } from '../types/metering.js';
-
-/**
- * Interface for signing data with the seller's Ed25519 private key.
- * The actual implementation lives in the identity module (PRD-01).
- */
-export interface Signer {
-  /**
-   * Sign a message with the seller's Ed25519 private key.
-   * @param message - UTF-8 string to sign
-   * @returns Hex-encoded signature
-   */
-  sign(message: string): string;
-
-  /** The seller's peer ID (Ed25519 public key hex) */
-  peerId: string;
-}
-
-/**
- * Build the canonical string representation of receipt data for signing.
- * The order and format must be deterministic so both sides produce the
- * same string from the same receipt data.
- */
-export function buildSignaturePayload(receipt: Omit<UsageReceipt, 'signature'>): string {
-  return [
-    receipt.receiptId,
-    receipt.sessionId,
-    receipt.eventId,
-    receipt.timestamp.toString(),
-    receipt.provider,
-    receipt.sellerPeerId,
-    receipt.buyerPeerId,
-    receipt.tokens.totalTokens.toString(),
-    receipt.costCents.toString(),
-  ].join('|');
-}
-
-/**
- * Calculate the cost in USD cents from token count and price.
- *
- * @param totalTokens - Total estimated tokens
- * @param unitPriceCentsPerThousandTokens - Unit price in USD cents per 1,000 tokens
- * @returns Cost in USD cents (rounded to nearest cent)
- */
-export function calculateCost(totalTokens: number, unitPriceCentsPerThousandTokens: number): number {
-  const raw = (totalTokens / 1000) * unitPriceCentsPerThousandTokens;
-  return raw > 0 ? Math.max(1, Math.round(raw)) : 0;
-}
-
-/**
- * Generates signed usage receipts for the seller side.
- */
-export class ReceiptGenerator {
-  private readonly signer: Signer;
-
-  constructor(signer: Signer) {
-    this.signer = signer;
-  }
-
-  /**
-   * Generate a signed receipt for a completed request.
-   *
-   * @param sessionId - The buyer session ID
-   * @param eventId - The metering event ID
-   * @param provider - Provider used
-   * @param buyerPeerId - Buyer's peer ID
-   * @param tokens - Token estimate
-   * @param unitPriceCentsPerThousandTokens - Effective unit price in USD cents per 1,000 tokens
-   * @returns Signed UsageReceipt
-   */
-  generate(
-    sessionId: string,
-    eventId: string,
-    provider: ProviderType,
-    buyerPeerId: string,
-    tokens: TokenCount,
-    unitPriceCentsPerThousandTokens: number
-  ): UsageReceipt {
-    const receiptId = randomUUID();
-    const timestamp = Date.now();
-    const costCents = calculateCost(tokens.totalTokens, unitPriceCentsPerThousandTokens);
-
-    const receiptData: Omit<UsageReceipt, 'signature'> = {
-      receiptId,
-      sessionId,
-      eventId,
-      timestamp,
-      provider,
-      sellerPeerId: this.signer.peerId,
-      buyerPeerId,
-      tokens,
-      unitPriceCentsPerThousandTokens,
-      costCents,
-    };
-
-    const payload = buildSignaturePayload(receiptData);
-    const signature = this.signer.sign(payload);
-
-    return {
-      ...receiptData,
-      signature,
-    };
-  }
-}

package/src/metering/receipt-verifier.ts

@@ -1,102 +0,0 @@
-import type { UsageReceipt, TokenCount, ReceiptVerification } from '../types/metering.js';
-import { buildSignaturePayload } from './receipt-generator.js';
-
-/**
- * Interface for verifying Ed25519 signatures.
- * The actual implementation lives in the identity module (PRD-01).
- */
-export interface SignatureVerifier {
-  /**
-   * Verify an Ed25519 signature.
-   * @param message - The original signed message (UTF-8 string)
-   * @param signature - Hex-encoded signature
-   * @param publicKeyHex - Signer's Ed25519 public key (hex)
-   * @returns true if signature is valid
-   */
-  verify(message: string, signature: string, publicKeyHex: string): boolean;
-}
-
-export interface VerifierOptions {
-  /**
-   * Maximum acceptable percentage difference between buyer and seller
-   * token estimates before flagging as disputed.
-   * Default: 15 (percent)
-   */
-  disputeThresholdPercent: number;
-}
-
-const DEFAULT_OPTIONS: VerifierOptions = {
-  disputeThresholdPercent: 15,
-};
-
-/**
- * Verifies seller-issued usage receipts on the buyer side.
- */
-export class ReceiptVerifier {
-  private readonly signatureVerifier: SignatureVerifier;
-  private readonly options: VerifierOptions;
-
-  constructor(signatureVerifier: SignatureVerifier, options?: Partial<VerifierOptions>) {
-    this.signatureVerifier = signatureVerifier;
-    this.options = { ...DEFAULT_OPTIONS, ...options };
-  }
-
-  /**
-   * Verify a receipt against the buyer's independent token estimate.
-   *
-   * Verification steps:
-   * 1. Verify the Ed25519 signature using the seller's public key
-   * 2. Compare seller's token estimate with buyer's estimate
-   * 3. Calculate percentage difference
-   * 4. Flag as disputed if difference exceeds threshold
-   *
-   * @param receipt - The seller's signed receipt
-   * @param buyerEstimate - The buyer's independent token estimate
-   * @returns ReceiptVerification result
-   */
-  verify(receipt: UsageReceipt, buyerEstimate: TokenCount): ReceiptVerification {
-    // Step 1: Verify signature
-    const payload = buildSignaturePayload(receipt);
-    const signatureValid = this.signatureVerifier.verify(
-      payload,
-      receipt.signature,
-      receipt.sellerPeerId
-    );
-
-    // Step 2: Compare token estimates
-    const sellerTotal = receipt.tokens.totalTokens;
-    const buyerTotal = buyerEstimate.totalTokens;
-    const tokenDifference = Math.abs(sellerTotal - buyerTotal);
-
-    // Step 3: Calculate percentage difference
-    const percentageDifference = ReceiptVerifier.calculatePercentageDifference(
-      sellerTotal,
-      buyerTotal
-    );
-
-    // Step 4: Flag as disputed if signature invalid or difference exceeds threshold
-    const disputed = !signatureValid || percentageDifference > this.options.disputeThresholdPercent;
-
-    return {
-      receiptId: receipt.receiptId,
-      signatureValid,
-      buyerTokenEstimate: buyerEstimate,
-      sellerTokenEstimate: receipt.tokens,
-      tokenDifference,
-      percentageDifference,
-      disputed,
-      verifiedAt: Date.now(),
-    };
-  }
-
-  /**
-   * Calculate the percentage difference between two token counts.
-   * Formula: abs(a - b) / max(a, b) * 100
-   * Returns 0 if both are 0.
-   */
-  static calculatePercentageDifference(a: number, b: number): number {
-    const max = Math.max(a, b);
-    if (max === 0) return 0;
-    return (Math.abs(a - b) / max) * 100;
-  }
-}

package/src/metering/session-tracker.ts

@@ -1,145 +0,0 @@
-import { EventEmitter } from 'node:events';
-import type {
-  ProviderType,
-  MeteringEvent,
-  UsageReceipt,
-  ReceiptVerification,
-  SessionMetrics,
-} from '../types/metering.js';
-
-/**
- * Tracks metering events and receipts for a session,
- * computing running aggregates.
- *
- * Emits:
- * - 'event-recorded' (event: MeteringEvent)
- * - 'receipt-recorded' (receipt: UsageReceipt, verification: ReceiptVerification)
- * - 'dispute-detected' (receiptId: string, percentageDifference: number)
- * - 'session-ended' (metrics: SessionMetrics)
- */
-export class SessionTracker extends EventEmitter {
-  private readonly sessionId: string;
-  private readonly sellerPeerId: string;
-  private readonly buyerPeerId: string;
-  private readonly provider: ProviderType;
-  private readonly startedAt: number;
-  private endedAt: number | null;
-
-  private events: MeteringEvent[];
-  private receipts: UsageReceipt[];
-  private verifications: ReceiptVerification[];
-
-  private totalTokens: number;
-  private totalCostCents: number;
-  private totalLatencyMs: number;
-  private peerSwitches: number;
-  private disputedCount: number;
-  private lastPeerId: string;
-
-  constructor(
-    sessionId: string,
-    sellerPeerId: string,
-    buyerPeerId: string,
-    provider: ProviderType
-  ) {
-    super();
-    this.sessionId = sessionId;
-    this.sellerPeerId = sellerPeerId;
-    this.buyerPeerId = buyerPeerId;
-    this.provider = provider;
-    this.startedAt = Date.now();
-    this.endedAt = null;
-
-    this.events = [];
-    this.receipts = [];
-    this.verifications = [];
-
-    this.totalTokens = 0;
-    this.totalCostCents = 0;
-    this.totalLatencyMs = 0;
-    this.peerSwitches = 0;
-    this.disputedCount = 0;
-    this.lastPeerId = sellerPeerId;
-  }
-
-  /**
-   * Record a metering event (one request/response cycle).
-   */
-  recordEvent(event: MeteringEvent): void {
-    this.events.push(event);
-    this.totalTokens += event.tokens.totalTokens;
-    this.totalLatencyMs += event.latencyMs;
-    this.emit('event-recorded', event);
-  }
-
-  /**
-   * Record a receipt and its verification result.
-   */
-  recordReceipt(receipt: UsageReceipt, verification: ReceiptVerification): void {
-    this.receipts.push(receipt);
-    this.verifications.push(verification);
-    this.totalCostCents += receipt.costCents;
-
-    if (verification.disputed) {
-      this.disputedCount++;
-      this.emit('dispute-detected', receipt.receiptId, verification.percentageDifference);
-    }
-
-    this.emit('receipt-recorded', receipt, verification);
-  }
-
-  /**
-   * Record a peer switch (failover to a different seller).
-   */
-  recordPeerSwitch(newPeerId: string): void {
-    if (newPeerId !== this.lastPeerId) {
-      this.peerSwitches++;
-      this.lastPeerId = newPeerId;
-    }
-  }
-
-  /**
-   * End the session and return final metrics.
-   */
-  endSession(): SessionMetrics {
-    this.endedAt = Date.now();
-    const metrics = this.getMetrics();
-    this.emit('session-ended', metrics);
-    return metrics;
-  }
-
-  /**
-   * Get current running metrics (session may still be active).
-   */
-  getMetrics(): SessionMetrics {
-    const totalRequests = this.events.length;
-    return {
-      sessionId: this.sessionId,
-      sellerPeerId: this.sellerPeerId,
-      buyerPeerId: this.buyerPeerId,
-      provider: this.provider,
-      startedAt: this.startedAt,
-      endedAt: this.endedAt,
-      totalRequests,
-      totalTokens: this.totalTokens,
-      totalCostCents: this.totalCostCents,
-      avgLatencyMs: totalRequests > 0 ? this.totalLatencyMs / totalRequests : 0,
-      peerSwitches: this.peerSwitches,
-      disputedReceipts: this.disputedCount,
-    };
-  }
-
-  /**
-   * Get all events in this session.
-   */
-  getEvents(): MeteringEvent[] {
-    return [...this.events];
-  }
-
-  /**
-   * Get all receipts in this session.
-   */
-  getReceipts(): UsageReceipt[] {
-    return [...this.receipts];
-  }
-}