@antseed/node 0.1.0

package/src/types/metering.ts

@@ -0,0 +1,175 @@
+/**
+ * Provider type - using string for flexibility with custom providers.
+ */
+export type ProviderType = 'anthropic' | 'openai' | 'google' | 'moonshot' | string;
+
+/**
+ * Token count estimate derived from HTTP content-length.
+ * NOT exact -- this is a heuristic estimate.
+ */
+export interface TokenCount {
+  /** Estimated input tokens (from request content-length) */
+  inputTokens: number;
+  /** Estimated output tokens (from response content-length) */
+  outputTokens: number;
+  /** Total estimated tokens */
+  totalTokens: number;
+  /** The estimation method used */
+  method: 'content-length' | 'chunk-accumulation' | 'fallback';
+  /**
+   * Confidence level of the estimate.
+   * 'high' = Content-Length header was present.
+   * 'medium' = accumulated from stream chunks.
+   * 'low' = fallback estimate based on request path / defaults.
+   */
+  confidence: 'high' | 'medium' | 'low';
+}
+
+/**
+ * A single metering event for one request/response cycle.
+ */
+export interface MeteringEvent {
+  /** Unique event ID (UUIDv4) */
+  eventId: string;
+  /** Session this event belongs to */
+  sessionId: string;
+  /** Timestamp of the request (ms since epoch) */
+  timestamp: number;
+  /** Provider used */
+  provider: ProviderType;
+  /** Seller peer ID */
+  sellerPeerId: string;
+  /** Buyer peer ID */
+  buyerPeerId: string;
+  /** Token estimate */
+  tokens: TokenCount;
+  /** Request latency in ms (from send to first byte) */
+  latencyMs: number;
+  /** HTTP status code of the response */
+  statusCode: number;
+  /** Whether the response was streamed (SSE) */
+  wasStreaming: boolean;
+}
+
+/**
+ * Signed usage receipt produced by the seller after each request.
+ * The receipt is the unit of billing -- payments settle based on receipts.
+ */
+export interface UsageReceipt {
+  /** Unique receipt ID (UUIDv4) */
+  receiptId: string;
+  /** Session ID this receipt belongs to */
+  sessionId: string;
+  /** Corresponding metering event ID */
+  eventId: string;
+  /** Timestamp of receipt creation (ms since epoch) */
+  timestamp: number;
+  /** Provider used */
+  provider: ProviderType;
+  /** Seller's peer ID */
+  sellerPeerId: string;
+  /** Buyer's peer ID */
+  buyerPeerId: string;
+  /** Seller's token estimate */
+  tokens: TokenCount;
+  /** Effective unit price in USD cents per 1,000 tokens (derived from seller offer pricing). */
+  unitPriceCentsPerThousandTokens: number;
+  /** Total cost in USD cents: (totalTokens / 1000) * unitPriceCentsPerThousandTokens */
+  costCents: number;
+  /**
+   * Ed25519 signature over the receipt data (hex string).
+   * Signs: receiptId + sessionId + eventId + timestamp + provider
+   *        + sellerPeerId + buyerPeerId + totalTokens + costCents
+   */
+  signature: string;
+}
+
+/**
+ * Result of buyer verifying a seller's receipt.
+ */
+export interface ReceiptVerification {
+  /** The receipt being verified */
+  receiptId: string;
+  /** Whether the signature is valid */
+  signatureValid: boolean;
+  /** Buyer's independent token estimate */
+  buyerTokenEstimate: TokenCount;
+  /** Seller's token estimate (from receipt) */
+  sellerTokenEstimate: TokenCount;
+  /** Absolute difference in total tokens */
+  tokenDifference: number;
+  /**
+   * Percentage difference: abs(seller - buyer) / max(seller, buyer) * 100
+   */
+  percentageDifference: number;
+  /**
+   * Whether the discrepancy exceeds the acceptable threshold.
+   * Default threshold: 15%
+   */
+  disputed: boolean;
+  /** Verification timestamp */
+  verifiedAt: number;
+}
+
+/**
+ * Aggregated metrics for a single session.
+ */
+export interface SessionMetrics {
+  /** Session ID */
+  sessionId: string;
+  /** Seller's peer ID */
+  sellerPeerId: string;
+  /** Buyer's peer ID */
+  buyerPeerId: string;
+  /** Provider used */
+  provider: ProviderType;
+  /** Session start time */
+  startedAt: number;
+  /** Session end time (null if still active) */
+  endedAt: number | null;
+  /** Total requests in this session */
+  totalRequests: number;
+  /** Total estimated tokens */
+  totalTokens: number;
+  /** Total cost in USD cents (sum of receipt costs) */
+  totalCostCents: number;
+  /** Average latency in ms */
+  avgLatencyMs: number;
+  /** Number of peer switches during this session */
+  peerSwitches: number;
+  /** Number of disputed receipts */
+  disputedReceipts: number;
+}
+
+/**
+ * Aggregated usage over a time period.
+ */
+export interface UsageAggregate {
+  /** Start of aggregation period */
+  periodStart: number;
+  /** End of aggregation period */
+  periodEnd: number;
+  /** Granularity of the period */
+  granularity: 'daily' | 'weekly' | 'monthly';
+  /** Total sessions in this period */
+  totalSessions: number;
+  /** Total requests */
+  totalRequests: number;
+  /** Total estimated tokens */
+  totalTokens: number;
+  /** Total cost/earnings in USD cents */
+  totalCostCents: number;
+  /** Breakdown by provider */
+  byProvider: Record<ProviderType, {
+    requests: number;
+    tokens: number;
+    costCents: number;
+  }>;
+  /** Breakdown by peer (top N) */
+  topPeers: Array<{
+    peerId: string;
+    requests: number;
+    tokens: number;
+    costCents: number;
+  }>;
+}

package/src/types/nat-api.d.ts

@@ -0,0 +1,29 @@
+declare module "@silentbot1/nat-api" {
+  interface NatAPIOptions {
+    ttl?: number;
+    description?: string;
+    gateway?: string;
+    autoUpdate?: boolean;
+    enablePMP?: boolean;
+    enableUPNP?: boolean;
+    upnpPermanentFallback?: boolean;
+  }
+
+  interface MapOptions {
+    publicPort: number;
+    privatePort: number;
+    protocol?: "TCP" | "UDP";
+    ttl?: number;
+    description?: string;
+  }
+
+  class NatAPI {
+    constructor(opts?: NatAPIOptions);
+    map(publicPort: number | MapOptions, privatePort?: number): Promise<boolean>;
+    unmap(publicPort: number | MapOptions, privatePort?: number): Promise<void>;
+    externalIp(): Promise<string>;
+    destroy(): Promise<void>;
+  }
+
+  export default NatAPI;
+}

package/src/types/peer-profile.ts

@@ -0,0 +1,25 @@
+import type { PeerId } from './peer.js';
+import type { ProviderCapability } from './capability.js';
+
+/**
+ * Alias for profile capabilities — uses the canonical ProviderCapability type.
+ */
+export type ProfileCapability = ProviderCapability;
+
+/**
+ * Full peer profile — richer than PeerMetadata (which is DHT wire format).
+ * This is the profile that peers create and publish.
+ */
+export interface PeerProfile {
+  peerId: PeerId;
+  displayName: string;
+  description: string;
+  tags: string[];
+  capabilities: ProfileCapability[];
+  region: string;
+  languages: string[];
+  website?: string;
+  avatar?: string;
+  createdAt: number;
+  updatedAt: number;
+}

package/src/types/peer.ts

@@ -0,0 +1,62 @@
+/**
+ * A PeerId is the hex-encoded Ed25519 public key (64 hex chars = 32 bytes).
+ * This is the canonical identifier for any peer in the network.
+ */
+export type PeerId = string & { readonly __brand: "PeerId" };
+
+/**
+ * Validates and brands a string as a PeerId.
+ * Must be exactly 64 lowercase hex characters.
+ */
+export function toPeerId(hex: string): PeerId {
+  if (!/^[0-9a-f]{64}$/.test(hex)) {
+    throw new Error(`Invalid PeerId: expected 64 hex chars, got "${hex.slice(0, 20)}..."`);
+  }
+  return hex as PeerId;
+}
+
+export interface TokenPricingUsdPerMillion {
+  inputUsdPerMillion: number;
+  outputUsdPerMillion: number;
+}
+
+export interface ProviderPricingMatrixEntry {
+  defaults: TokenPricingUsdPerMillion;
+  models?: Record<string, TokenPricingUsdPerMillion>;
+}
+
+/** Information about a known peer. */
+export interface PeerInfo {
+  /** Unique peer identifier (Ed25519 public key hex). */
+  peerId: PeerId;
+  /** Human-readable label, optional. */
+  displayName?: string;
+  /** Last known STUN-resolved public address. */
+  publicAddress?: string;
+  /** Last seen timestamp (Unix ms). */
+  lastSeen: number;
+  /** LLM providers this peer is offering (empty if buyer-only). */
+  providers: string[];
+  /** Reputation score (0-100). */
+  reputationScore?: number;
+  /** Provider/model-aware pricing map announced by seller. */
+  providerPricing?: Record<string, ProviderPricingMatrixEntry>;
+  /** Deterministic fallback default input price (USD per 1M tokens). */
+  defaultInputUsdPerMillion?: number;
+  /** Deterministic fallback default output price (USD per 1M tokens). */
+  defaultOutputUsdPerMillion?: number;
+  /** Maximum concurrent requests the peer can handle. */
+  maxConcurrency?: number;
+  /** Current number of requests the peer is handling. */
+  currentLoad?: number;
+  /** Computed trust score (0-100) from the trust engine. */
+  trustScore?: number;
+  /** EVM address of the peer (0x-prefixed hex). */
+  evmAddress?: string;
+  /** On-chain reputation score (0-100) from the Base escrow contract. */
+  onChainReputation?: number;
+  /** On-chain session count from the Base escrow contract. */
+  onChainSessionCount?: number;
+  /** On-chain dispute count from the Base escrow contract. */
+  onChainDisputeCount?: number;
+}

package/src/types/plugin-config.ts

@@ -0,0 +1,31 @@
+/**
+ * Plugin instance configuration stored in ~/.antseed/config.json.
+ */
+export interface PluginInstanceConfig {
+  /** Unique instance ID (e.g., "my-anthropic", "cheap-openrouter") */
+  id: string
+  /** npm package name (e.g., "@antseed/provider-anthropic") */
+  package: string
+  /** Plugin type */
+  type: 'provider' | 'router'
+  /** Instance configuration (secrets are encrypted at rest) */
+  config: Record<string, unknown>
+  /** Whether this instance is enabled. Default: true */
+  enabled?: boolean
+  /** ISO timestamp when instance was created */
+  createdAt?: string
+}
+
+/**
+ * Top-level plugin config file structure.
+ */
+export interface PluginConfigFile {
+  /** Plugin instances */
+  instances: PluginInstanceConfig[]
+  /** Encryption metadata */
+  encryption?: {
+    algorithm: string
+    kdf: string
+    salt: string
+  }
+}

package/src/types/protocol.ts

@@ -0,0 +1,162 @@
+export enum MessageType {
+  HandshakeInit = 0x01,
+  HandshakeAck = 0x02,
+  Ping = 0x10,
+  Pong = 0x11,
+  HttpRequest = 0x20,
+  HttpResponse = 0x21,
+  HttpResponseChunk = 0x22,
+  HttpResponseEnd = 0x23,
+  HttpResponseError = 0x24,
+  // Task/Agent message types
+  TaskRequest = 0x30,
+  TaskEvent = 0x31,
+  TaskComplete = 0x32,
+  TaskError = 0x33,
+  // Skill message types
+  SkillRequest = 0x40,
+  SkillResponse = 0x41,
+
+  // --- Bilateral Payment Protocol (0x50-0x5F) ---
+  SessionLockAuth = 0x50,
+  SessionLockConfirm = 0x51,
+  SessionLockReject = 0x52,
+  SellerReceipt = 0x53,
+  BuyerAck = 0x54,
+  SessionEnd = 0x55,
+  TopUpRequest = 0x56,
+  TopUpAuth = 0x57,
+  DisputeNotify = 0x58,
+
+  // Report message types
+  PeerReport = 0x60,
+  ReportAck = 0x61,
+
+  // Rating message types
+  PeerRating = 0x70,
+  RatingQuery = 0x71,
+  RatingResponse = 0x72,
+
+  Disconnect = 0xF0,
+  Error = 0xFF,
+}
+
+export interface FramedMessage {
+  type: MessageType;
+  messageId: number;
+  payload: Uint8Array;
+}
+
+export const FRAME_HEADER_SIZE = 9;
+export const MAX_PAYLOAD_SIZE = 64 * 1024 * 1024;
+
+// ─── Bilateral Payment Messages ─────────────────────────────────
+
+/**
+ * Buyer authorizes locking funds for a session.
+ * Contains the buyer's ECDSA signature over keccak256(sessionId, seller, amount).
+ */
+export interface SessionLockAuthPayload {
+  /** 32-byte session ID as hex string */
+  sessionId: string;
+  /** Amount to lock in USDC base units (6 decimals) */
+  lockedAmount: string;
+  /** Buyer's ECDSA signature over keccak256(sessionId || seller || amount) as hex */
+  buyerSig: string;
+}
+
+/**
+ * Seller confirms the lock was committed on-chain.
+ */
+export interface SessionLockConfirmPayload {
+  sessionId: string;
+  /** Base transaction hash for the commit_lock instruction */
+  txSignature: string;
+}
+
+/**
+ * Seller rejects the lock (insufficient funds, invalid sig, etc).
+ */
+export interface SessionLockRejectPayload {
+  sessionId: string;
+  reason: string;
+}
+
+/**
+ * Running-total receipt signed by seller after processing a request.
+ * Each receipt supersedes the previous one.
+ */
+export interface SellerReceiptPayload {
+  sessionId: string;
+  /** Cumulative cost of all requests in this session (USDC base units) */
+  runningTotal: string;
+  /** Number of requests processed so far */
+  requestCount: number;
+  /** SHA-256 hash of the response body (hex) for proof of work */
+  responseHash: string;
+  /** Seller's Ed25519 signature over (sessionId || runningTotal || requestCount || responseHash) */
+  sellerSig: string;
+}
+
+/**
+ * Buyer acknowledges the seller's receipt by counter-signing.
+ */
+export interface BuyerAckPayload {
+  sessionId: string;
+  /** Must match seller's runningTotal */
+  runningTotal: string;
+  /** Must match seller's requestCount */
+  requestCount: number;
+  /** Buyer's Ed25519 signature over (sessionId || runningTotal || requestCount) */
+  buyerSig: string;
+}
+
+/**
+ * Buyer ends the session with a final score.
+ */
+export interface SessionEndPayload {
+  sessionId: string;
+  /** Final running total (must match last ack'd receipt) */
+  runningTotal: string;
+  /** Final request count */
+  requestCount: number;
+  /** Quality score 0-100 */
+  score: number;
+  /** Buyer's ECDSA signature over keccak256(sessionId || runningTotal || score) as hex */
+  buyerSig: string;
+}
+
+/**
+ * Seller requests additional funds when budget is running low.
+ */
+export interface TopUpRequestPayload {
+  sessionId: string;
+  /** Additional USDC amount requested (base units) */
+  additionalAmount: string;
+  /** Current running total for context */
+  currentRunningTotal: string;
+  /** Current locked amount for context */
+  currentLockedAmount: string;
+}
+
+/**
+ * Buyer authorizes a top-up.
+ */
+export interface TopUpAuthPayload {
+  sessionId: string;
+  /** Additional amount authorized (USDC base units) */
+  additionalAmount: string;
+  /** Buyer's ECDSA signature over keccak256(sessionId || seller || additionalAmount) as hex */
+  buyerSig: string;
+}
+
+/**
+ * Notify counterparty that a dispute has been opened on-chain.
+ */
+export interface DisputeNotifyPayload {
+  sessionId: string;
+  /** Reason for the dispute */
+  reason: string;
+  /** Base tx hash of the open_dispute instruction */
+  txSignature: string;
+}

package/src/types/provider.ts

@@ -0,0 +1,40 @@
+/** @deprecated Each plugin manages its own upstream. Use plugin configSchema instead. */
+export enum KnownProvider {
+  OpenAI = "openai",
+  Anthropic = "anthropic",
+  Google = "google",
+  Mistral = "mistral",
+  Cohere = "cohere",
+  Moonshot = "moonshot",
+}
+
+export interface TokenProviderState {
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt?: number;
+}
+
+/**
+ * Resolves auth tokens dynamically (e.g. OAuth refresh, keychain read).
+ */
+export interface TokenProvider {
+  /** Get a valid access token. May refresh if expired. */
+  getToken(): Promise<string>;
+  /** Clean up resources. */
+  stop(): void;
+  /** Current provider state for persistence (if available). */
+  getState?(): TokenProviderState | null;
+}
+
+export interface ProviderConfig {
+  provider: KnownProvider;
+  baseUrl: string;
+  authHeaderName: string;
+  authHeaderValue: string;
+  allowedModels: string[];
+  maxConcurrency: number;
+  /** Optional dynamic token provider (OAuth, keychain, etc.). */
+  tokenProvider?: TokenProvider;
+  /** Extra headers injected into upstream requests (e.g. OAuth beta flags). */
+  extraHeaders?: Record<string, string>;
+}

package/src/types/rating.ts

@@ -0,0 +1,23 @@
+import type { PeerId } from './peer.js';
+
+export type RatingDimension = 'quality' | 'speed' | 'reliability' | 'value' | 'overall';
+
+export interface PeerRating {
+  ratingId: string;
+  raterPeerId: PeerId;
+  targetPeerId: PeerId;
+  sessionId: string;
+  dimensions: Record<RatingDimension, 1 | 2 | 3 | 4 | 5>;
+  comment?: string;
+  timestamp: number;
+  /** Ed25519 signature (hex) */
+  signature: string;
+}
+
+export interface AggregateRating {
+  peerId: PeerId;
+  averageByDimension: Record<RatingDimension, number>;
+  overallAverage: number;
+  totalRatings: number;
+  lastUpdated: number;
+}

package/src/types/report.ts

@@ -0,0 +1,30 @@
+import type { PeerId } from './peer.js';
+
+export type ReportReason =
+  | 'bad-quality'
+  | 'overcharging'
+  | 'timeout'
+  | 'harmful-content'
+  | 'fraud'
+  | 'impersonation'
+  | 'other';
+
+export type ReportStatus = 'pending' | 'acknowledged' | 'resolved' | 'dismissed';
+
+export interface ReportEvidence {
+  type: 'receipt' | 'log' | 'screenshot' | 'text';
+  data: string;
+}
+
+export interface PeerReport {
+  reportId: string;
+  reporterPeerId: PeerId;
+  targetPeerId: PeerId;
+  reason: ReportReason;
+  evidence: ReportEvidence[];
+  sessionId?: string;
+  timestamp: number;
+  status: ReportStatus;
+  /** Ed25519 signature over report data (hex string) */
+  signature: string;
+}

package/src/types/seller.ts

@@ -0,0 +1,38 @@
+import type { ProviderType } from './metering.js';
+
+export interface SellerProviderPricingConfig {
+  inputUsdPerMillion: number;
+  outputUsdPerMillion: number;
+}
+
+/**
+ * Per-provider capacity and pricing configuration for sellers.
+ */
+export interface SellerProviderConfig {
+  /** Provider identifier (must match a key in AntseedConfig.providers) */
+  type: ProviderType;
+  /** Whether this provider is enabled for selling */
+  enabled: boolean;
+  /** Plan limit in messages per hour. */
+  planLimitMsgPerHour: number;
+  /** Reserve floor in messages per hour. */
+  reserveFloorMsgPerHour: number;
+  /** Default pricing in USD per 1M tokens. */
+  pricing: SellerProviderPricingConfig;
+}
+
+/**
+ * Top-level seller configuration.
+ */
+export interface SellerConfig {
+  /** Whether seller mode is enabled */
+  enabled: boolean;
+  /** Maximum number of concurrent buyer connections */
+  maxConcurrentBuyers: number;
+  /** Per-provider selling configuration */
+  providers: SellerProviderConfig[];
+  /** Session timeout in ms. Default: 300_000 (5 minutes). */
+  sessionTimeoutMs: number;
+  /** DHT re-announce interval in ms. Default: 60_000 (1 minute). */
+  announceIntervalMs: number;
+}

package/src/types/staking.ts

@@ -0,0 +1,23 @@
+import type { PeerId } from './peer.js';
+
+export type StakeStatus = 'active' | 'slashed' | 'withdrawn';
+
+export interface StakeInfo {
+  peerId: PeerId;
+  amountUSDC: number;
+  stakedAt: number;
+  lockPeriodDays: number;
+  status: StakeStatus;
+}
+
+export interface StakeConfig {
+  minStakeUSDC: number;
+  lockPeriodDays: number;
+  slashPercentage: number;
+}
+
+export const DEFAULT_STAKE_CONFIG: StakeConfig = {
+  minStakeUSDC: 100,
+  lockPeriodDays: 30,
+  slashPercentage: 10,
+};

package/src/utils/debug.ts

@@ -0,0 +1,30 @@
+function normalizeDebugValue(value: string | undefined): string {
+  return (value ?? '').trim().toLowerCase();
+}
+
+export function isDebugEnabled(): boolean {
+  const fromAntseed = normalizeDebugValue(process.env['ANTSEED_DEBUG']);
+  if (
+    fromAntseed === '1' ||
+    fromAntseed === 'true' ||
+    fromAntseed === 'yes' ||
+    fromAntseed === 'on'
+  ) {
+    return true;
+  }
+
+  const fromDebug = normalizeDebugValue(process.env['DEBUG']);
+  return fromDebug === '*' || fromDebug.includes('antseed');
+}
+
+export function debugLog(...args: unknown[]): void {
+  if (isDebugEnabled()) {
+    console.log(...args);
+  }
+}
+
+export function debugWarn(...args: unknown[]): void {
+  if (isDebugEnabled()) {
+    console.warn(...args);
+  }
+}

package/src/utils/hex.ts

@@ -0,0 +1,14 @@
+export function hexToBytes(hex: string): Uint8Array {
+  if (hex.length % 2 !== 0) throw new Error("Hex string must have even length");
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = parseInt(hex.slice(i, i + 2), 16);
+  }
+  return bytes;
+}
+
+export function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}