@relaycore/sdk 1.0.0

package/lib/x402.ts

@@ -0,0 +1,220 @@
+/**
+ * X402 Payment Middleware - Cronos Standard Implementation
+ * 
+ * Based on x402-examples reference from Cronos Labs.
+ * Provides middleware for protecting routes with x402 payment requirements.
+ */
+
+import crypto from 'crypto';
+import type { Request, Response, NextFunction } from 'express';
+import type { Facilitator, VerifyRequest } from '@crypto.com/facilitator-client';
+import type {
+    X402Accepts,
+    X402Response,
+    X402PaidRecord,
+    X402PayResult,
+    X402ProtectionOptions,
+} from '../types/x402.types';
+
+/**
+ * In-memory entitlement store keyed by payment ID.
+ * 
+ * @remarks
+ * For production, replace with persistent storage (Redis, Supabase, etc.)
+ */
+const paidEntitlements = new Map<string, X402PaidRecord>();
+
+/**
+ * Generates a unique payment identifier per Cronos standard.
+ * @returns Payment ID in format `pay_<uuid>`
+ */
+export const generatePaymentId = (): string => `pay_${crypto.randomUUID()}`;
+
+/**
+ * Check if a payment ID has been settled.
+ */
+export function isEntitled(paymentId: string): boolean {
+    return paidEntitlements.get(paymentId)?.settled === true;
+}
+
+/**
+ * Get entitlement record for a payment ID.
+ */
+export function getEntitlement(paymentId: string): X402PaidRecord | undefined {
+    return paidEntitlements.get(paymentId);
+}
+
+/**
+ * Store an entitlement record after successful payment.
+ */
+export function recordEntitlement(paymentId: string, record: X402PaidRecord): void {
+    paidEntitlements.set(paymentId, record);
+}
+
+/**
+ * Creates Express middleware that enforces x402 payment.
+ * 
+ * If the request is already entitled (has valid x-payment-id), calls next().
+ * Otherwise, responds with HTTP 402 and x402 challenge.
+ * 
+ * @example
+ * ```ts
+ * router.get('/protected', requireX402({
+ *   network: 'cronos-testnet',
+ *   payTo: '0x...',
+ *   asset: '0x...',
+ *   maxAmountRequired: '1000000',
+ *   description: 'Access to premium data',
+ *   resource: '/api/protected',
+ * }), handler);
+ * ```
+ */
+export function requireX402(options: X402ProtectionOptions) {
+    const {
+        network,
+        payTo,
+        asset,
+        maxAmountRequired,
+        maxTimeoutSeconds = 300,
+        description,
+        mimeType = 'application/json',
+        resource,
+        outputSchema,
+        getEntitlementKey,
+    } = options;
+
+    return (req: Request, res: Response, next: NextFunction): void => {
+        // Check for existing entitlement
+        const entitlementKey = (
+            getEntitlementKey?.(req) ??
+            req.header('x-payment-id') ??
+            ''
+        ).trim();
+
+        if (entitlementKey && isEntitled(entitlementKey)) {
+            next();
+            return;
+        }
+
+        // Generate new payment ID for challenge
+        const paymentId = generatePaymentId();
+
+        const accepts: X402Accepts = {
+            scheme: 'exact',
+            network,
+            asset,
+            payTo,
+            maxAmountRequired,
+            maxTimeoutSeconds,
+            description,
+            mimeType,
+            resource,
+            outputSchema,
+            extra: { paymentId },
+        };
+
+        const response: X402Response = {
+            x402Version: 1,
+            error: 'payment_required',
+            accepts: [accepts],
+        };
+
+        res.status(402).json(response);
+    };
+}
+
+/**
+ * Verifies and settles an x402 payment using the Facilitator SDK.
+ * Records entitlement on success.
+ * 
+ * @example
+ * ```ts
+ * const result = await handleX402Settlement({
+ *   facilitator,
+ *   paymentId: 'pay_...',
+ *   paymentHeader: '...',
+ *   paymentRequirements: {...},
+ * });
+ * ```
+ */
+export async function handleX402Settlement(params: {
+    facilitator: Facilitator;
+    paymentId: string;
+    paymentHeader: string;
+    paymentRequirements: VerifyRequest['paymentRequirements'];
+}): Promise<X402PayResult> {
+    const { facilitator, paymentId, paymentHeader, paymentRequirements } = params;
+
+    const body: VerifyRequest = {
+        x402Version: 1,
+        paymentHeader,
+        paymentRequirements,
+    };
+
+    // Step 1: Verify
+    const verify = await facilitator.verifyPayment(body);
+    if (!verify.isValid) {
+        return {
+            ok: false,
+            error: 'verify_failed',
+            details: verify,
+        };
+    }
+
+    // Step 2: Settle
+    const settle = await facilitator.settlePayment(body);
+    if (settle.event !== 'payment.settled') {
+        return {
+            ok: false,
+            error: 'settle_failed',
+            details: settle,
+        };
+    }
+
+    // Step 3: Record entitlement
+    recordEntitlement(paymentId, {
+        settled: true,
+        txHash: settle.txHash,
+        at: Date.now(),
+    });
+
+    return {
+        ok: true,
+        txHash: settle.txHash,
+    };
+}
+
+/**
+ * Helper to create payment requirements for a resource.
+ */
+export function createPaymentRequirements(options: {
+    network: string;
+    payTo: string;
+    asset: string;
+    maxAmountRequired: string;
+    resource: string;
+    description: string;
+}): X402Accepts {
+    return {
+        scheme: 'exact',
+        network: options.network as X402Accepts['network'],
+        payTo: options.payTo,
+        asset: options.asset,
+        maxAmountRequired: options.maxAmountRequired,
+        maxTimeoutSeconds: 300,
+        description: options.description,
+        mimeType: 'application/json',
+        resource: options.resource,
+        extra: { paymentId: generatePaymentId() },
+    };
+}
+
+export default {
+    requireX402,
+    handleX402Settlement,
+    generatePaymentId,
+    isEntitled,
+    getEntitlement,
+    recordEntitlement,
+    createPaymentRequirements,
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+    "name": "@relaycore/sdk",
+    "version": "1.0.0",
+    "description": "The official SDK for Relay Core - Build AI Agents and Services on Cronos",
+    "main": "dist/index.js",
+    "module": "dist/index.mjs",
+    "types": "dist/index.d.ts",
+    "scripts": {
+        "build": "tsup",
+        "lint": "eslint .",
+        "test": "vitest"
+    },
+    "keywords": [
+        "relaycore",
+        "cronos",
+        "ai",
+        "agents",
+        "sdk",
+        "x402"
+    ],
+    "author": "Relay Core Team",
+    "license": "MIT",
+    "dependencies": {
+        "@crypto.com/facilitator-client": "^1.0.2",
+        "@reown/appkit": "^1.8.16",
+        "ethers": "^6.13.4",
+        "siwe": "^3.0.0"
+    },
+    "devDependencies": {
+        "@types/express": "^5.0.6",
+        "tsup": "^8.3.5",
+        "typescript": "^5.6.3",
+        "vitest": "^2.1.8"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/provider-sdk.ts

@@ -0,0 +1,311 @@
+
+/**
+ * Service Provider SDK
+ * 
+ * For service providers to register services, handle payments,
+ * and track their reputation on the Relay Core platform.
+ */
+
+// Configuration for the SDK
+export interface ProviderSDKConfig {
+    apiUrl?: string;
+    supabaseUrl?: string;
+    supabaseKey?: string;
+}
+
+// Service registration parameters
+export interface ServiceRegistration {
+    name: string;
+    description: string;
+    category: string;
+    endpointUrl: string;
+    pricePerCall: string;
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    inputType?: string;
+    outputType?: string;
+    tags?: string[];
+    capabilities?: string[];
+}
+
+// Registered service response
+export interface RegisteredService {
+    id: string;
+    name: string;
+    endpointUrl: string;
+    ownerAddress: string;
+    createdAt: string;
+}
+
+// Reputation data
+export interface ProviderReputation {
+    reputationScore: number;
+    successRate: number;
+    totalPayments: number;
+    avgLatencyMs: number;
+    trend: 'improving' | 'stable' | 'declining';
+}
+
+// Payment received event
+export interface PaymentReceived {
+    paymentId: string;
+    txHash: string;
+    amount: string;
+    payerAddress: string;
+    timestamp: string;
+}
+
+// Metrics snapshot
+export interface ServiceMetrics {
+    timestamp: string;
+    successRate: number;
+    avgLatencyMs: number;
+    callVolume: number;
+    reputationScore: number;
+}
+
+const DEFAULT_API_URL = 'https://api.relaycore.xyz';
+
+export class ServiceProviderSDK {
+    private apiUrl: string;
+    private walletAddress: string;
+
+    constructor(walletAddress: string, config: ProviderSDKConfig = {}) {
+        this.walletAddress = walletAddress.toLowerCase();
+        this.apiUrl = config.apiUrl || DEFAULT_API_URL;
+    }
+
+    /**
+     * Register a new service
+     */
+    async registerService(service: ServiceRegistration): Promise<RegisteredService> {
+        const response = await fetch(`${this.apiUrl}/api/services`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                ...service,
+                ownerAddress: this.walletAddress,
+            }),
+        });
+
+        if (!response.ok) {
+            const error = await response.json();
+            throw new Error(`Failed to register service: ${error.error || response.statusText}`);
+        }
+
+        const data = await response.json();
+        return {
+            id: data.id,
+            name: data.name,
+            endpointUrl: data.endpointUrl,
+            ownerAddress: this.walletAddress,
+            createdAt: new Date().toISOString(),
+        };
+    }
+
+    /**
+     * Update an existing service
+     */
+    async updateService(
+        serviceId: string,
+        updates: Partial<ServiceRegistration>
+    ): Promise<void> {
+        const response = await fetch(`${this.apiUrl}/api/services/${serviceId}`, {
+            method: 'PUT',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(updates),
+        });
+
+        if (!response.ok) {
+            const error = await response.json();
+            throw new Error(`Failed to update service: ${error.error || response.statusText}`);
+        }
+    }
+
+    /**
+     * Deactivate a service
+     */
+    async deactivateService(serviceId: string): Promise<void> {
+        await this.updateService(serviceId, { isActive: false } as any);
+    }
+
+    /**
+     * Get current reputation
+     */
+    async getReputation(): Promise<ProviderReputation> {
+        const response = await fetch(
+            `${this.apiUrl}/api/services?ownerAddress=${this.walletAddress}&limit=1`
+        );
+
+        if (!response.ok) {
+            throw new Error('Failed to fetch reputation');
+        }
+
+        const data = await response.json();
+        const service = data.services?.[0];
+
+        if (!service) {
+            return {
+                reputationScore: 0,
+                successRate: 0,
+                totalPayments: 0,
+                avgLatencyMs: 0,
+                trend: 'stable',
+            };
+        }
+
+        return {
+            reputationScore: service.reputationScore || 0,
+            successRate: service.successRate || 0,
+            totalPayments: service.totalPayments || 0,
+            avgLatencyMs: service.avgLatencyMs || 0,
+            trend: service.trend || 'stable',
+        };
+    }
+
+    /**
+     * Get service metrics history
+     */
+    async getMetricsHistory(
+        serviceId: string,
+        options: { from?: Date; to?: Date } = {}
+    ): Promise<ServiceMetrics[]> {
+        const params = new URLSearchParams();
+        if (options.from) params.set('from', options.from.toISOString());
+        if (options.to) params.set('to', options.to.toISOString());
+
+        const response = await fetch(
+            `${this.apiUrl}/api/services/${serviceId}/metrics?${params}`
+        );
+
+        if (!response.ok) {
+            throw new Error('Failed to fetch metrics');
+        }
+
+        const data = await response.json();
+        return data.data || [];
+    }
+
+    /**
+     * Get all registered services for this provider
+     */
+    async getMyServices(): Promise<RegisteredService[]> {
+        const response = await fetch(
+            `${this.apiUrl}/api/services?ownerAddress=${this.walletAddress}`
+        );
+
+        if (!response.ok) {
+            throw new Error('Failed to fetch services');
+        }
+
+        const data = await response.json();
+        return (data.services || []).map((s: Record<string, unknown>) => ({
+            id: s.id,
+            name: s.name,
+            endpointUrl: s.endpointUrl,
+            ownerAddress: s.ownerAddress,
+            createdAt: s.createdAt,
+        }));
+    }
+
+    /**
+     * Generate x402 payment requirements for an endpoint
+     * Use this when building your service's 402 response
+     */
+    generatePaymentRequirements(params: {
+        amount: string;
+        resourceUrl: string;
+        description?: string;
+        timeoutSeconds?: number;
+    }): {
+        x402Version: number;
+        paymentRequirements: {
+            scheme: 'exact';
+            network: string;
+            payTo: string;
+            asset: string;
+            maxAmountRequired: string;
+            maxTimeoutSeconds: number;
+            description?: string;
+        };
+    } {
+        return {
+            x402Version: 1,
+            paymentRequirements: {
+                scheme: 'exact',
+                network: 'cronos-mainnet',
+                payTo: this.walletAddress,
+                asset: '0xf951eC28187D9E5Ca673Da8FE6757E6f0Be5F77C', // USDC.e on Cronos
+                maxAmountRequired: params.amount,
+                maxTimeoutSeconds: params.timeoutSeconds || 60,
+                description: params.description,
+            },
+        };
+    }
+
+    /**
+     * Verify a payment was made (for use in your service)
+     */
+    async verifyPayment(paymentId: string): Promise<{
+        verified: boolean;
+        amount?: string;
+        payerAddress?: string;
+    }> {
+        const response = await fetch(`${this.apiUrl}/api/payments/${paymentId}`);
+
+        if (!response.ok) {
+            return { verified: false };
+        }
+
+        const data = await response.json();
+        return {
+            verified: data.payment?.status === 'settled',
+            amount: data.payment?.amount,
+            payerAddress: data.payment?.payerAddress,
+        };
+    }
+
+    /**
+     * Record a service outcome (success or failure)
+     * Call after each service invocation
+     */
+    async recordOutcome(params: {
+        paymentId: string;
+        outcomeType: 'delivered' | 'failed' | 'partial';
+        latencyMs: number;
+        evidence?: Record<string, unknown>;
+    }): Promise<void> {
+        const response = await fetch(`${this.apiUrl}/api/outcomes`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                paymentId: params.paymentId,
+                outcomeType: params.outcomeType,
+                latencyMs: params.latencyMs,
+                evidence: params.evidence,
+            }),
+        });
+
+        if (!response.ok) {
+            console.error('Failed to record outcome');
+        }
+    }
+}
+
+/**
+ * Create a Service Provider SDK instance
+ */
+export function createProviderSDK(
+    walletAddress: string,
+    config?: ProviderSDKConfig
+): ServiceProviderSDK {
+    return new ServiceProviderSDK(walletAddress, config);
+}
+
+export default ServiceProviderSDK;