@onchaindb/sdk 0.4.0 → 0.4.2

package/src/x402/index.ts

@@ -0,0 +1,12 @@
+/**
+ * x402 Protocol Module
+ *
+ * Exports types and utilities for x402 payment protocol support.
+ *
+ * Two payment flows are supported:
+ * 1. Celestia native: User broadcasts tx, sends txHash to server
+ * 2. Facilitator (EVM/Solana): User signs authorization, server sends to facilitator
+ */
+
+export * from './types';
+export * from './utils';

package/src/x402/types.ts

@@ -0,0 +1,250 @@
+/**
+ * x402 Protocol Types
+ *
+ * Type definitions for the x402 payment protocol specification.
+ * See: https://github.com/coinbase/x402/blob/main/specs/x402-specification.md
+ */
+
+/**
+ * Payment scheme - currently only "exact" is supported per spec
+ */
+export type PaymentScheme = 'exact';
+
+/**
+ * Chain type for payment processing
+ */
+export type ChainType = 'cosmos' | 'evm' | 'solana';
+
+/**
+ * Payment method
+ */
+export type PaymentMethod = 'native' | 'x402-facilitator';
+
+/**
+ * x402 Payment requirement from server
+ */
+export interface X402PaymentRequirement {
+    /** Payment scheme - must be "exact" */
+    scheme: PaymentScheme;
+    /** Network identifier (e.g., "mocha-4", "base", "solana") */
+    network: string;
+    /** Maximum amount required in smallest units as string */
+    maxAmountRequired: string;
+    /** Recipient address */
+    payTo: string;
+    /** Asset identifier (e.g., "utia", USDC address) */
+    asset: string;
+    /** Resource URL being accessed */
+    resource: string;
+    /** Human-readable description */
+    description: string;
+    /** Content type of the resource */
+    mimeType: string;
+    /** Maximum timeout for payment in seconds */
+    maxTimeoutSeconds: number;
+    /** Extra extension data */
+    extra?: X402Extra;
+}
+
+/**
+ * x402 Extra field with OnChainDB extensions
+ */
+export interface X402Extra {
+    /** Extension identifier */
+    x402Extension?: string;
+    /** Quote ID for this payment */
+    quoteId?: string;
+    /** Chain type (cosmos, evm, solana) */
+    chainType?: ChainType;
+    /** Chain ID for EVM chains */
+    chainId?: number;
+    /** Payment method */
+    paymentMethod?: PaymentMethod;
+    /** x402 facilitator URL */
+    facilitator?: string;
+    /** Token symbol */
+    tokenSymbol?: string;
+    /** Token decimals */
+    tokenDecimals?: number;
+    /** Cost breakdown */
+    costBreakdown?: Record<string, number>;
+    /** Pricing information */
+    pricing?: {
+        baseAmount: string;
+        baseAsset: string;
+        premiumPercent?: number;
+        expiresAt?: number;
+    };
+}
+
+/**
+ * x402 Payment Required Response (402 status)
+ */
+export interface X402PaymentRequiredResponse {
+    /** Protocol version - must be 1 */
+    x402Version: 1;
+    /** Error message explaining why payment is required */
+    error: string;
+    /** Array of accepted payment options */
+    accepts: X402PaymentRequirement[];
+}
+
+/**
+ * x402 Payment Payload sent in X-PAYMENT header
+ */
+export interface X402PaymentPayload {
+    /** Protocol version */
+    x402Version: 1;
+    /** Payment scheme */
+    scheme: PaymentScheme;
+    /** Network used for payment */
+    network: string;
+    /** Quote ID from server */
+    quoteId: string;
+    /** Payment-specific payload */
+    payload: X402NativePayload | X402EvmPayload | X402SolanaPayload;
+}
+
+/**
+ * Native Celestia payment payload
+ */
+export interface X402NativePayload {
+    /** Transaction hash */
+    txHash: string;
+    /** Sender address */
+    sender: string;
+    /** Payment timestamp */
+    timestamp: number;
+}
+
+/**
+ * EVM payment payload (for x402 facilitator)
+ */
+export interface X402EvmPayload {
+    /** EIP-712 signature */
+    signature: string;
+    /** ERC-3009 authorization */
+    authorization: {
+        from: string;
+        to: string;
+        value: string;
+        validAfter: number;
+        validBefore: number;
+        nonce: string;
+    };
+}
+
+/**
+ * Solana payment payload (for x402 facilitator)
+ */
+export interface X402SolanaPayload {
+    /** Signed transaction (base64) */
+    transaction: string;
+}
+
+/**
+ * x402 Payment Response header value
+ */
+export interface X402PaymentResponse {
+    /** Transaction hash */
+    txHash: string;
+    /** Network where payment was made */
+    network: string;
+    /** Block height of confirmation */
+    blockHeight: number;
+    /** Amount paid */
+    amount: string;
+    /** Confirmation timestamp */
+    confirmedAt: number;
+}
+
+/**
+ * Quote format for payment callback
+ */
+export interface X402Quote {
+    /** Quote ID */
+    quoteId: string;
+    /** Total cost in TIA */
+    totalCostTia: number;
+    /** Amount in smallest units */
+    amountRaw: string;
+    /** Broker/recipient address */
+    brokerAddress: string;
+    /** Payment description */
+    description: string;
+    /** Quote expiration timestamp */
+    expiresAt: number;
+    /** Chain type */
+    chainType: ChainType;
+    /** Network name */
+    network: string;
+    /** Asset address/identifier */
+    asset: string;
+    /** Token symbol */
+    tokenSymbol: string;
+    /** Token decimals */
+    tokenDecimals: number;
+    /** Payment method */
+    paymentMethod: PaymentMethod;
+    /** Facilitator URL (if applicable) */
+    facilitator?: string;
+    /** All available payment options */
+    allOptions: X402PaymentRequirement[];
+}
+
+/**
+ * Payment result from callback - supports both native and facilitator flows
+ */
+export interface X402PaymentResult {
+    /** Transaction hash (required for Celestia native, optional for facilitator) */
+    txHash: string;
+    /** Network used */
+    network: string;
+    /** Sender address */
+    sender: string;
+    /** Chain type */
+    chainType: ChainType;
+    /** Payment method used */
+    paymentMethod: PaymentMethod;
+}
+
+/**
+ * Facilitator payment result - used for EVM/Solana payments via x402 facilitator
+ * User provides authorization, facilitator executes the payment
+ */
+export interface X402FacilitatorPaymentResult {
+    /** Network used */
+    network: string;
+    /** Chain type */
+    chainType: 'evm' | 'solana';
+    /** Payment method - always x402-facilitator */
+    paymentMethod: 'x402-facilitator';
+    /** EVM authorization (for EVM chains) */
+    evmAuthorization?: {
+        signature: string;
+        authorization: {
+            from: string;
+            to: string;
+            value: string;
+            validAfter: number;
+            validBefore: number;
+            nonce: string;
+        };
+    };
+    /** Solana authorization (for Solana) */
+    solanaAuthorization?: {
+        transaction: string;
+    };
+}
+
+/**
+ * Union type for all payment callback results
+ */
+export type X402PaymentCallbackResult = X402PaymentResult | X402FacilitatorPaymentResult;
+
+/**
+ * Type guard to check if result is a facilitator payment
+ */
+export function isFacilitatorPaymentResult(result: X402PaymentCallbackResult): result is X402FacilitatorPaymentResult {
+    return result.paymentMethod === 'x402-facilitator' && !('txHash' in result && result.txHash);
+}

package/src/x402/utils.ts

@@ -0,0 +1,332 @@
+/**
+ * x402 Protocol Utilities
+ *
+ * Helper functions for parsing and building x402 protocol messages.
+ */
+
+import {
+    X402PaymentRequiredResponse,
+    X402PaymentRequirement,
+    X402Quote,
+    X402PaymentPayload,
+    X402PaymentResult,
+    ChainType,
+    PaymentMethod,
+} from './types';
+
+/**
+ * Parse a 402 response into typed x402 format
+ */
+export function parseX402Response(data: any): X402PaymentRequiredResponse {
+    if (!data || typeof data !== 'object') {
+        throw new Error('Invalid x402 response: not an object');
+    }
+
+    if (data.x402Version !== 1) {
+        throw new Error(`Unsupported x402 version: ${data.x402Version}`);
+    }
+
+    if (!Array.isArray(data.accepts) || data.accepts.length === 0) {
+        throw new Error('Invalid x402 response: no payment options');
+    }
+
+    return {
+        x402Version: 1,
+        error: data.error || 'Payment required',
+        accepts: data.accepts.map(parsePaymentRequirement),
+    };
+}
+
+/**
+ * Parse a single payment requirement
+ */
+function parsePaymentRequirement(req: any): X402PaymentRequirement {
+    if (req.scheme !== 'exact') {
+        console.warn(`Non-standard scheme "${req.scheme}", treating as exact`);
+    }
+
+    return {
+        scheme: 'exact',
+        network: req.network,
+        maxAmountRequired: req.maxAmountRequired,
+        payTo: req.payTo,
+        asset: req.asset,
+        resource: req.resource,
+        description: req.description,
+        mimeType: req.mimeType || 'application/json',
+        maxTimeoutSeconds: req.maxTimeoutSeconds || 300,
+        extra: req.extra,
+    };
+}
+
+/**
+ * Convert x402 payment requirement to quote format for callbacks
+ */
+export function requirementToQuote(
+    requirement: X402PaymentRequirement,
+    allOptions: X402PaymentRequirement[]
+): X402Quote {
+    const extra = requirement.extra || {};
+    const amountRaw = requirement.maxAmountRequired;
+
+    // Determine chain type from extra or network
+    let chainType: ChainType = 'cosmos';
+    if (extra.chainType) {
+        chainType = extra.chainType;
+    } else if (isEvmNetwork(requirement.network)) {
+        chainType = 'evm';
+    } else if (isSolanaNetwork(requirement.network)) {
+        chainType = 'solana';
+    }
+
+    // Calculate TIA amount (for display purposes)
+    const decimals = extra.tokenDecimals || 6;
+    const totalCostTia = parseInt(amountRaw) / Math.pow(10, decimals);
+
+    // Calculate expiration
+    const expiresAt = extra.pricing?.expiresAt ||
+        Math.floor(Date.now() / 1000) + requirement.maxTimeoutSeconds;
+
+    return {
+        quoteId: extra.quoteId || '',
+        totalCostTia,
+        amountRaw,
+        brokerAddress: requirement.payTo,
+        description: requirement.description,
+        expiresAt,
+        chainType,
+        network: requirement.network,
+        asset: requirement.asset,
+        tokenSymbol: extra.tokenSymbol || getTokenSymbol(requirement.asset),
+        tokenDecimals: decimals,
+        paymentMethod: (extra.paymentMethod || 'native') as PaymentMethod,
+        facilitator: extra.facilitator,
+        allOptions,
+    };
+}
+
+/**
+ * Build X-PAYMENT header payload for Celestia native payments
+ * For EVM/Solana facilitator payments, use buildFacilitatorPaymentPayload instead
+ */
+export function buildPaymentPayload(
+    requirement: X402PaymentRequirement,
+    payment: X402PaymentResult
+): X402PaymentPayload {
+    const extra = requirement.extra || {};
+
+    return {
+        x402Version: 1,
+        scheme: 'exact',
+        network: payment.network,
+        quoteId: extra.quoteId || '',
+        payload: {
+            txHash: payment.txHash.toLowerCase(),
+            sender: payment.sender,
+            timestamp: Math.floor(Date.now() / 1000),
+        },
+    };
+}
+
+/**
+ * Build X-PAYMENT header payload for facilitator networks (EVM/Solana)
+ * These payments don't have a txHash upfront - the facilitator executes the payment
+ */
+export function buildFacilitatorPaymentPayload(
+    requirement: X402PaymentRequirement,
+    authorization: FacilitatorAuthorization
+): X402PaymentPayload {
+    const extra = requirement.extra || {};
+
+    if (authorization.type === 'evm') {
+        return {
+            x402Version: 1,
+            scheme: 'exact',
+            network: requirement.network,
+            quoteId: extra.quoteId || '',
+            payload: {
+                signature: authorization.signature,
+                authorization: authorization.authorization,
+            } as any,
+        };
+    } else if (authorization.type === 'solana') {
+        return {
+            x402Version: 1,
+            scheme: 'exact',
+            network: requirement.network,
+            quoteId: extra.quoteId || '',
+            payload: {
+                transaction: authorization.transaction,
+            } as any,
+        };
+    }
+
+    throw new Error(`Unsupported facilitator authorization type: ${(authorization as any).type}`);
+}
+
+/**
+ * EVM authorization for facilitator (ERC-3009 / EIP-712)
+ */
+export interface EvmFacilitatorAuthorization {
+    type: 'evm';
+    /** EIP-712 signature */
+    signature: string;
+    /** ERC-3009 authorization details */
+    authorization: {
+        from: string;
+        to: string;
+        value: string;
+        validAfter: number;
+        validBefore: number;
+        nonce: string;
+    };
+}
+
+/**
+ * Solana authorization for facilitator
+ */
+export interface SolanaFacilitatorAuthorization {
+    type: 'solana';
+    /** Signed transaction (base64) */
+    transaction: string;
+}
+
+export type FacilitatorAuthorization = EvmFacilitatorAuthorization | SolanaFacilitatorAuthorization;
+
+/**
+ * Check if a network requires the x402 facilitator
+ */
+export function isFacilitatorNetwork(network: string): boolean {
+    return isEvmNetwork(network) || isSolanaNetwork(network);
+}
+
+/**
+ * Encode payment payload to base64 for X-PAYMENT header
+ */
+export function encodePaymentHeader(payload: X402PaymentPayload): string {
+    const json = JSON.stringify(payload);
+    if (typeof Buffer !== 'undefined') {
+        return Buffer.from(json).toString('base64');
+    } else {
+        return btoa(json);
+    }
+}
+
+/**
+ * Decode X-PAYMENT-RESPONSE header
+ */
+export function decodePaymentResponse(header: string): any {
+    try {
+        if (typeof Buffer !== 'undefined') {
+            return JSON.parse(Buffer.from(header, 'base64').toString());
+        } else {
+            return JSON.parse(atob(header));
+        }
+    } catch {
+        // Try parsing as direct JSON (some servers don't base64 encode)
+        return JSON.parse(header);
+    }
+}
+
+/**
+ * Check if network is EVM-based
+ */
+function isEvmNetwork(network: string): boolean {
+    const evmNetworks = [
+        'ethereum', 'ethereum-sepolia',
+        'base', 'base-sepolia',
+        'polygon', 'polygon-amoy',
+        'arbitrum', 'arbitrum-sepolia',
+        'avalanche', 'avalanche-fuji',
+    ];
+    return evmNetworks.includes(network.toLowerCase());
+}
+
+/**
+ * Check if network is Solana-based
+ */
+function isSolanaNetwork(network: string): boolean {
+    return network.toLowerCase() === 'solana' || network.toLowerCase() === 'solana-devnet';
+}
+
+/**
+ * Get token symbol from asset address
+ */
+function getTokenSymbol(asset: string): string {
+    // Common asset mappings
+    const assetSymbols: Record<string, string> = {
+        'utia': 'TIA',
+        'native': 'ETH',
+        // USDC addresses on various chains
+        '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913': 'USDC', // Base
+        '0x036cbd53842c5426634e7929541ec2318f3dcf7e': 'USDC', // Base Sepolia
+        '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48': 'USDC', // Ethereum
+        'epjfwdd5aufqssqem2qn1xzybapC8g4weggkzwyTdt1v': 'USDC', // Solana
+    };
+
+    const normalized = asset.toLowerCase();
+    return assetSymbols[normalized] || 'TOKEN';
+}
+
+/**
+ * Select best payment option based on user preference
+ */
+export function selectPaymentOption(
+    options: X402PaymentRequirement[],
+    preferredChainType?: ChainType,
+    preferredNetwork?: string
+): X402PaymentRequirement {
+    // If specific network requested, find it
+    if (preferredNetwork) {
+        const match = options.find(o =>
+            o.network.toLowerCase() === preferredNetwork.toLowerCase()
+        );
+        if (match) return match;
+    }
+
+    // If chain type requested, find first match
+    if (preferredChainType) {
+        const match = options.find(o => {
+            const extra = o.extra || {};
+            if (extra.chainType === preferredChainType) return true;
+            if (preferredChainType === 'evm' && isEvmNetwork(o.network)) return true;
+            if (preferredChainType === 'solana' && isSolanaNetwork(o.network)) return true;
+            if (preferredChainType === 'cosmos' && o.asset === 'utia') return true;
+            return false;
+        });
+        if (match) return match;
+    }
+
+    // Default to first option (typically native TIA)
+    return options[0];
+}
+
+/**
+ * Group payment options by chain type
+ */
+export function groupPaymentOptions(
+    options: X402PaymentRequirement[]
+): Record<ChainType, X402PaymentRequirement[]> {
+    const groups: Record<ChainType, X402PaymentRequirement[]> = {
+        cosmos: [],
+        evm: [],
+        solana: [],
+    };
+
+    for (const option of options) {
+        const extra = option.extra || {};
+        let chainType: ChainType = 'cosmos';
+
+        if (extra.chainType) {
+            chainType = extra.chainType;
+        } else if (isEvmNetwork(option.network)) {
+            chainType = 'evm';
+        } else if (isSolanaNetwork(option.network)) {
+            chainType = 'solana';
+        }
+
+        groups[chainType].push(option);
+    }
+
+    return groups;
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "removeComments": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}