@hivemind-os/collective-relay 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,425 @@
+import { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
+import { SimpleKeypair, RelayRegistryClient } from '@hivemind-os/collective-core';
+import { DID, PaymentRail } from '@hivemind-os/collective-types';
+import { EventEmitter } from 'node:events';
+import WebSocket from 'ws';
+
+interface RelayConfig {
+    host: string;
+    port: number;
+    identity: {
+        keyPath: string;
+    };
+    fees: {
+        basePercentage: number;
+        minimumMist: bigint;
+    };
+    limits: {
+        maxConnections: number;
+        maxRequestsPerSecond: number;
+        taskTimeoutMs: number;
+        heartbeatIntervalMs: number;
+        heartbeatTimeoutMs: number;
+        authNonceTtlMs: number;
+    };
+    cors?: {
+        allowedOrigins: string[];
+    };
+    sui?: {
+        rpcUrl: string;
+        packageId: string;
+    };
+    relayRegistry?: {
+        enabled: boolean;
+        relayId?: string;
+        stakePositionId?: string;
+        endpoint?: string;
+        capabilities: string[];
+        region?: string;
+        routingFeeBps?: number;
+        heartbeatIntervalMs: number;
+    };
+}
+declare function getDefaultRelayConfig(baseDir?: string): RelayConfig;
+declare function loadRelayConfig(overrides?: Partial<RelayConfig>): RelayConfig;
+declare function validateRelayConfig(config: RelayConfig): void;
+
+interface HealthMonitorStatus {
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    uptime: number;
+    connectedProviders: number;
+    activeRequests: number;
+    totalRequestsServed: number;
+    averageLatencyMs: number;
+}
+interface HealthMonitorOptions {
+    now?: () => number;
+    getConnectedProviders?: () => number;
+}
+declare class HealthMonitor {
+    private readonly options;
+    private readonly now;
+    private readonly startedAt;
+    private activeRequests;
+    private connectedProviders;
+    private totalRequestsServed;
+    private totalLatencyMs;
+    constructor(options?: HealthMonitorOptions);
+    setConnectedProviders(count: number): void;
+    beginRequest(): {
+        finish: () => void;
+    };
+    recordRequest(latencyMs: number): void;
+    getStatus(): HealthMonitorStatus;
+}
+
+declare class RelayIdentity {
+    readonly keyPath: string;
+    readonly keypair: SimpleKeypair;
+    readonly did: DID;
+    private constructor();
+    static load(keyPath: string): RelayIdentity;
+    signPayload(payload: string): string;
+}
+
+interface AuthMessage {
+    type: 'auth';
+    did: DID;
+    nonce: string;
+    signature: string;
+    capabilities: string[];
+}
+interface HeartbeatMessage {
+    type: 'heartbeat';
+    sessionId: string;
+}
+interface TaskResultMessage {
+    type: 'task_result';
+    sessionId: string;
+    taskId: string;
+    sequence: number;
+    result: unknown;
+}
+interface TaskProgressMessage {
+    type: 'task_progress';
+    sessionId: string;
+    taskId: string;
+    sequence: number;
+    progress: number;
+    message?: string;
+}
+interface TaskChunkMessage {
+    type: 'task_chunk';
+    sessionId: string;
+    taskId: string;
+    sequence: number;
+    data: string;
+}
+interface TaskErrorMessage {
+    type: 'task_error';
+    sessionId: string;
+    taskId: string;
+    sequence: number;
+    error: {
+        code: string;
+        message: string;
+    };
+}
+type ProviderMessage = AuthMessage | HeartbeatMessage | TaskResultMessage | TaskProgressMessage | TaskChunkMessage | TaskErrorMessage;
+interface AuthOkMessage {
+    type: 'auth_ok';
+    sessionId: string;
+    relayDid: string;
+}
+interface AuthFailMessage {
+    type: 'auth_fail';
+    reason: string;
+}
+interface TaskRequestMessage {
+    type: 'task_request';
+    sessionId: string;
+    taskId: string;
+    capability: string;
+    input: unknown;
+    requesterDid: DID;
+    sequence: number;
+}
+interface HeartbeatAckMessage {
+    type: 'heartbeat_ack';
+}
+type RelayMessage = AuthOkMessage | AuthFailMessage | TaskRequestMessage | HeartbeatAckMessage;
+interface TaskRequest {
+    requesterDid: DID;
+    capability: string;
+    input: unknown;
+    providerDid?: DID;
+    taskId?: string;
+    timeoutMs?: number;
+}
+interface TaskResponse {
+    taskId: string;
+    providerDid: DID;
+    sequence: number;
+    result: unknown;
+}
+type TaskStreamEvent = {
+    type: 'progress';
+    taskId: string;
+    sequence: number;
+    progress: number;
+    message?: string;
+} | {
+    type: 'chunk';
+    taskId: string;
+    sequence: number;
+    data: string;
+} | {
+    type: 'result';
+    taskId: string;
+    sequence: number;
+    result: unknown;
+};
+type ProviderTaskMessage = Exclude<ProviderMessage, AuthMessage | HeartbeatMessage>;
+declare function normalizeCapability(capability: string): string;
+declare function createAuthPayload(message: Pick<AuthMessage, 'did' | 'nonce' | 'capabilities'>): string;
+declare function serializeRelayMessage(message: RelayMessage): string;
+declare function parseProviderMessage(payload: string | Buffer | ArrayBuffer | Buffer[]): ProviderMessage | null;
+declare function parseRelayMessage(payload: string | Buffer | ArrayBuffer | Buffer[]): RelayMessage | null;
+
+interface ProviderSession {
+    sessionId: string;
+    providerDid: DID;
+    ws: WebSocket;
+    capabilities: string[];
+    connectedAt: number;
+    lastHeartbeat: number;
+    sequenceCounter: number;
+}
+interface ProviderInfo {
+    sessionId: string;
+    providerDid: DID;
+    capabilities: string[];
+    connectedAt: number;
+    lastHeartbeat: number;
+}
+interface SessionManagerOptions {
+    maxConnections: number;
+    heartbeatTimeoutMs: number;
+    authNonceTtlMs?: number;
+    now?: () => number;
+}
+declare class SessionManager extends EventEmitter {
+    private readonly options;
+    private readonly sessions;
+    private readonly sessionsByDid;
+    private readonly capabilityIndex;
+    private readonly inboundSequences;
+    private readonly capabilityCursor;
+    private readonly recentAuthNonces;
+    private readonly now;
+    constructor(options: SessionManagerOptions);
+    registerSession(ws: WebSocket, authMessage: AuthMessage): ProviderSession;
+    findProvider(capability: string, preferredDid?: DID): ProviderSession | null;
+    removeSession(sessionId: string): void;
+    disconnectSession(sessionId: string, code?: number, reason?: string): void;
+    disconnectAllSessions(code?: number, reason?: string): void;
+    handleHeartbeat(sessionId: string): void;
+    sweepExpiredSessions(): string[];
+    getConnectedProviders(): ProviderInfo[];
+    getSession(sessionId: string): ProviderSession | null;
+    getSessionByDid(did: DID, capability?: string): ProviderSession | null;
+    getSessionCount(): number;
+    nextSequence(sessionId: string): number;
+    validateIncomingSequence(sessionId: string, sequence: number): boolean;
+    private verifyAuthMessage;
+    private markAuthNonceUsed;
+    private pruneRecentAuthNonces;
+    private getAuthNonceKey;
+    private getAuthNonceTtlMs;
+    private addDidIndex;
+    private removeDidIndex;
+    private addCapabilities;
+    private removeCapabilities;
+    private toProviderInfo;
+}
+
+interface RelayFeeSchedule {
+    basePercentage: number;
+    minimumMist: bigint;
+}
+interface RelayFeeBreakdown {
+    relayFee: bigint;
+    totalPrice: bigint;
+}
+declare function calculateRelayFee(basePrice: bigint, feeSchedule: RelayFeeSchedule): RelayFeeBreakdown;
+
+interface PaymentChallenge {
+    rail: PaymentRail;
+    paymentAddress: string;
+    amount: string;
+    currency: string;
+    network: string;
+    relayFee: string;
+    expiresAt: number;
+    nonce: string;
+    asset?: string;
+    extra?: Record<string, string>;
+}
+interface PaymentVerification {
+    accepted: boolean;
+    settlementReference?: string;
+    relayFee?: string;
+    totalPrice?: string;
+    payer?: string;
+    reason?: string;
+}
+interface PaymentGateOptions {
+    relayDid: string;
+    feeSchedule: RelayFeeSchedule;
+    paymentAddress?: string;
+    evmPaymentAddress?: string;
+    defaultRail?: PaymentRail;
+    challengeTtlMs?: number;
+    now?: () => number;
+    nonceFactory?: () => string;
+    basePriceResolver?: (capability: string, provider: ProviderSession) => bigint;
+    verifyPaymentProof?: (paymentHeader: string, challenge: PaymentChallenge) => Promise<PaymentVerification>;
+}
+declare class PaymentGate {
+    private readonly options;
+    private readonly activeChallenges;
+    private readonly consumedProofs;
+    private readonly now;
+    private readonly nonceFactory;
+    private readonly basePriceResolver;
+    readonly defaultRail: PaymentRail;
+    constructor(options: PaymentGateOptions);
+    generate402Challenge(rail: PaymentRail, capability: string, provider: ProviderSession): PaymentChallenge;
+    getChallenge(nonce: string): PaymentChallenge | null;
+    isChallengeExpired(challenge: PaymentChallenge): boolean;
+    verifyPayment(paymentHeader: string, challenge: PaymentChallenge): Promise<PaymentVerification>;
+    calculateFee(basePrice: bigint): RelayFeeBreakdown;
+    pruneExpiredChallenges(): number;
+    private pruneConsumedProofs;
+    private createSuiChallenge;
+    private createX402Challenge;
+    private verifyChallenge;
+}
+
+interface RelayRegistryRuntimeInfo {
+    enabled: boolean;
+    registered: boolean;
+    relayId?: string;
+    operator?: string;
+    endpoint?: string;
+    stakePositionId?: string;
+    capabilities?: string[];
+    region?: string;
+    status?: 'ACTIVE' | 'INACTIVE' | 'SLASHED';
+    routingFeeBps?: number;
+    lastHeartbeat?: number;
+    totalRouted?: number;
+    totalFeesEarnedMist?: string;
+    lastError?: string;
+}
+interface RelayRegistryRuntime {
+    start: (serverAddress: string) => Promise<void>;
+    stop: () => Promise<void>;
+    recordRouting: (feeAmountMist: bigint) => Promise<void>;
+    getInfo: () => RelayRegistryRuntimeInfo;
+}
+declare class RelayRegistryService implements RelayRegistryRuntime {
+    private readonly config;
+    private readonly identity;
+    private readonly enabled;
+    private readonly signer;
+    private readonly client?;
+    private heartbeatTimer?;
+    private state;
+    constructor(config: RelayConfig, identity: RelayIdentity, client?: RelayRegistryClient);
+    start(serverAddress: string): Promise<void>;
+    stop(): Promise<void>;
+    recordRouting(feeAmountMist: bigint): Promise<void>;
+    getInfo(): RelayRegistryRuntimeInfo;
+    private sendHeartbeat;
+    private resolveExistingRelay;
+    private refreshRelay;
+    private applyRelay;
+}
+
+interface RelayRouterOptions {
+    sessionManager: SessionManager;
+    taskTimeoutMs: number;
+}
+declare class RelayRouteError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly retryable: boolean;
+    constructor(code: string, message: string, statusCode: number, retryable?: boolean);
+}
+declare class RelayRouter {
+    private readonly options;
+    private readonly pendingTasks;
+    constructor(options: RelayRouterOptions);
+    routeTask(request: TaskRequest): Promise<TaskResponse>;
+    routeStreamingTask(request: TaskRequest, onChunk: (chunk: TaskStreamEvent) => void): Promise<TaskResponse>;
+    routeMulti(request: TaskRequest, providerDids: DID[]): Promise<TaskResponse[]>;
+    close(): void;
+    handleProviderMessage(sessionId: string, message: ProviderTaskMessage): void;
+    private dispatch;
+    private emitTaskEvent;
+    private completeTask;
+    private rejectSessionTasks;
+    private findSession;
+}
+
+interface RelayServer {
+    app: FastifyInstance;
+    config: RelayConfig;
+    identity: RelayIdentity;
+    sessionManager: SessionManager;
+    router: RelayRouter;
+    paymentGate: PaymentGate;
+    healthMonitor: HealthMonitor;
+    relayRegistry?: RelayRegistryRuntime;
+    start: () => Promise<string>;
+}
+interface RelayServerOptions {
+    relayRegistry?: RelayRegistryRuntime;
+}
+declare function createRelayServer(config: RelayConfig, options?: RelayServerOptions): Promise<RelayServer>;
+
+interface MeshRequestContext {
+    requestId: string;
+    requesterDid?: DID;
+    targetProviderDid?: DID;
+    timestamp?: string;
+    signature?: string;
+    paymentSignature?: string;
+    paymentNonce?: string;
+    paymentRail?: PaymentRail;
+    sessionId?: string;
+    sequence?: number;
+}
+declare function registerMeshMiddleware(app: FastifyInstance, relayDid: string): void;
+declare function getMeshRequestContext(request: FastifyRequest): MeshRequestContext;
+declare function applyMeshResponseHeaders(reply: FastifyReply, relayDid: string, requestId: string): void;
+
+interface RelayRouteDependencies {
+    relayDid: DID;
+    version: string;
+    config: RelayConfig;
+    sessionManager: SessionManager;
+    router: RelayRouter;
+    paymentGate: PaymentGate;
+    healthMonitor: HealthMonitor;
+    relayRegistry?: RelayRegistryRuntime;
+}
+declare function registerRelayRoutes(app: FastifyInstance, deps: RelayRouteDependencies): Promise<void>;
+
+declare function startRelayServer(): Promise<{
+    relay: RelayServer;
+    address: string;
+}>;
+
+export { type AuthFailMessage, type AuthMessage, type AuthOkMessage, HealthMonitor, type HealthMonitorOptions, type HealthMonitorStatus, type HeartbeatAckMessage, type HeartbeatMessage, type MeshRequestContext, type PaymentChallenge, PaymentGate, type PaymentGateOptions, type PaymentVerification, type ProviderInfo, type ProviderMessage, type ProviderSession, type ProviderTaskMessage, type RelayConfig, type RelayFeeBreakdown, type RelayFeeSchedule, RelayIdentity, type RelayMessage, type RelayRegistryRuntime, type RelayRegistryRuntimeInfo, RelayRegistryService, type RelayRouteDependencies, RelayRouteError, RelayRouter, type RelayServer, type RelayServerOptions, SessionManager, type SessionManagerOptions, type TaskChunkMessage, type TaskErrorMessage, type TaskProgressMessage, type TaskRequest, type TaskRequestMessage, type TaskResponse, type TaskResultMessage, type TaskStreamEvent, applyMeshResponseHeaders, calculateRelayFee, createAuthPayload, createRelayServer, getDefaultRelayConfig, getMeshRequestContext, loadRelayConfig, normalizeCapability, parseProviderMessage, parseRelayMessage, registerMeshMiddleware, registerRelayRoutes, serializeRelayMessage, startRelayServer, validateRelayConfig };