@net-protocol/relay 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,458 @@
+import { Address, LocalAccount } from 'viem/accounts';
+import { Address as Address$1, Hash, PublicClient } from 'viem';
+import { WriteTransactionConfig } from '@net-protocol/core';
+
+/**
+ * Create a relay session token
+ *
+ * Signs an EIP-712 message proving ownership of operatorAddress
+ * and receives a sessionToken that can be reused for multiple batch requests.
+ *
+ * @param params - Session creation parameters
+ * @returns Session token and expiration timestamp
+ * @throws Error if session creation fails
+ */
+declare function createRelaySession(params: {
+    apiUrl: string;
+    chainId: number;
+    operatorAddress: Address;
+    secretKey: string;
+    account: LocalAccount;
+    expiresIn?: number;
+}): Promise<{
+    sessionToken: string;
+    expiresAt: number;
+}>;
+
+/**
+ * Error response from API endpoints
+ */
+interface ErrorResponse {
+    success: false;
+    error: string;
+}
+/**
+ * Response from /api/relay/[chainId]/fund endpoint
+ */
+interface FundResponse {
+    success: boolean;
+    message?: string;
+    payer?: Address$1;
+    amount?: string;
+    error?: string;
+}
+/**
+ * Response from /api/relay/fund/verify endpoint
+ */
+interface VerifyFundResponse {
+    success: boolean;
+    paymentTxHash?: Hash;
+    backendWalletAddress?: Address$1;
+    fundedAmountEth?: string;
+    transactionHash?: Hash;
+    alreadyProcessed?: boolean;
+    message?: string;
+    error?: string;
+}
+/**
+ * Response from /api/relay/submit endpoint
+ */
+interface SubmitResponse {
+    success: boolean;
+    transactionHashes: Hash[];
+    successfulIndexes: number[];
+    failedIndexes: number[];
+    errors: {
+        index: number;
+        error: string;
+    }[];
+    backendWalletAddress: Address$1;
+    appFeeTransactionHash: Hash;
+    error?: string;
+}
+/**
+ * Response from /api/relay/session endpoint
+ */
+interface CreateSessionResponse {
+    success: boolean;
+    sessionToken?: string;
+    expiresAt?: number;
+    error?: string;
+}
+/**
+ * Response from /api/relay/balance endpoint
+ */
+interface BalanceResponse {
+    success: boolean;
+    backendWalletAddress: Address$1;
+    balanceWei: string;
+    balanceEth: string;
+    sufficientBalance: boolean;
+    minRequiredWei: string;
+    minRequiredEth: string;
+    error?: string;
+}
+/**
+ * Result of funding backend wallet
+ */
+interface RelayFundResult {
+    paymentTxHash: Hash;
+    backendWalletAddress: Address$1;
+}
+/**
+ * Result of submitting transactions via relay
+ */
+interface RelaySubmitResult {
+    transactionHashes: Hash[];
+    successfulIndexes: number[];
+    failedIndexes: number[];
+    errors: {
+        index: number;
+        error: string;
+    }[];
+    backendWalletAddress: Address$1;
+    appFeeTransactionHash: Hash;
+}
+/**
+ * Configuration for retry logic
+ */
+interface RetryConfig {
+    maxRetries?: number;
+    initialDelay?: number;
+    maxDelay?: number;
+    backoffMultiplier?: number;
+}
+/**
+ * Parameters for funding backend wallet
+ */
+interface FundBackendWalletParams {
+    apiUrl: string;
+    chainId: number;
+    operatorAddress: Address$1;
+    secretKey: string;
+    fetchWithPayment: typeof fetch;
+    httpClient: {
+        getPaymentSettleResponse: (getHeader: (name: string) => string | null) => {
+            transaction?: string;
+            txHash?: string;
+        } | null;
+    };
+}
+/**
+ * Parameters for submitting transactions via relay
+ */
+interface SubmitTransactionsViaRelayParams {
+    apiUrl: string;
+    chainId: number;
+    operatorAddress: Address$1;
+    secretKey: string;
+    transactions: WriteTransactionConfig[];
+    sessionToken: string;
+}
+/**
+ * Parameters for retrying failed transactions
+ */
+interface RetryFailedTransactionsParams {
+    apiUrl: string;
+    chainId: number;
+    operatorAddress: Address$1;
+    secretKey: string;
+    failedIndexes: number[];
+    originalTransactions: WriteTransactionConfig[];
+    backendWalletAddress: Address$1;
+    config?: RetryConfig;
+    sessionToken: string;
+    recheckFunction?: (failedIndexes: number[], transactions: WriteTransactionConfig[], backendWalletAddress: Address$1) => Promise<number[]>;
+}
+/**
+ * Parameters for waiting for transaction confirmations
+ */
+interface WaitForConfirmationsParams {
+    publicClient: PublicClient;
+    transactionHashes: Hash[];
+    confirmations?: number;
+    timeout?: number;
+    onProgress?: (confirmed: number, total: number) => void;
+}
+/**
+ * Result of waiting for transaction confirmations
+ */
+interface ConfirmationResult {
+    hash: Hash;
+    receipt: any;
+}
+/**
+ * Parameters for checking backend wallet balance
+ */
+interface CheckBackendWalletBalanceParams {
+    apiUrl: string;
+    chainId: number;
+    operatorAddress: Address$1;
+    secretKey: string;
+}
+/**
+ * Result of checking backend wallet balance
+ */
+interface CheckBalanceResult {
+    backendWalletAddress: Address$1;
+    balanceWei: string;
+    balanceEth: string;
+    sufficientBalance: boolean;
+    minRequiredWei: string;
+    minRequiredEth: string;
+}
+/**
+ * Result of creating x402 client
+ */
+interface X402ClientResult {
+    fetchWithPayment: typeof fetch;
+    httpClient: {
+        getPaymentSettleResponse: (getHeader: (name: string) => string | null) => {
+            transaction?: string;
+            txHash?: string;
+        } | null;
+    };
+}
+
+/**
+ * Check backend wallet balance via relay service
+ *
+ * This function:
+ * 1. Calls /api/relay/balance with operatorAddress and secretKey
+ * 2. Returns balance information including sufficientBalance flag
+ *
+ * @param params - Balance check parameters
+ * @returns Result with balance information
+ * @throws Error if balance check fails
+ */
+declare function checkBackendWalletBalance(params: CheckBackendWalletBalanceParams): Promise<CheckBalanceResult>;
+
+/**
+ * Fund backend wallet via x402 relay service
+ *
+ * This function:
+ * 1. Calls /api/relay/[chainId]/fund with x402 payment (using fetchWithPayment)
+ * 2. Extracts paymentTxHash from X-PAYMENT-RESPONSE header
+ * 3. Waits for payment confirmation (2 seconds)
+ * 4. Calls /api/relay/fund/verify to get backendWalletAddress
+ * 5. Returns { paymentTxHash, backendWalletAddress }
+ *
+ * @param params - Funding parameters
+ * @returns Result with paymentTxHash and backendWalletAddress
+ * @throws Error if funding fails
+ */
+declare function fundBackendWallet(params: FundBackendWalletParams): Promise<RelayFundResult>;
+
+/**
+ * Submit transactions via relay service
+ *
+ * Calls /api/relay/submit with transactions and returns result
+ * with success/failure tracking by index.
+ *
+ * @param params - Submission parameters
+ * @returns Result with transaction hashes and success/failure tracking
+ * @throws Error if submission fails
+ */
+declare function submitTransactionsViaRelay(params: SubmitTransactionsViaRelayParams): Promise<RelaySubmitResult>;
+
+/**
+ * Retry failed transactions with exponential backoff
+ *
+ * This function:
+ * 1. Extracts failed transactions by index from RelaySubmitResult
+ * 2. Optionally re-checks on-chain before retry (via recheckFunction)
+ * 3. Retries with exponential backoff
+ * 4. Handles nested retries
+ *
+ * @param params - Retry parameters
+ * @returns Final success/failure status after retries
+ */
+declare function retryFailedTransactions(params: RetryFailedTransactionsParams): Promise<RelaySubmitResult>;
+
+/**
+ * Estimate the size of a serialized transaction config in bytes
+ *
+ * Storage transactions can be large due to:
+ * - Large args arrays (chunk data)
+ * - Hex-encoded data in args
+ * - ABI structure overhead
+ *
+ * We use a conservative estimate of 100KB per transaction to ensure we stay under the 1MB limit.
+ * With 100KB per transaction, we can fit ~9 transactions per batch (900KB / 100KB).
+ */
+declare function estimateTransactionSize(tx: WriteTransactionConfig): number;
+/**
+ * Estimate the total request size for a batch of transactions
+ */
+declare function estimateRequestSize(transactions: WriteTransactionConfig[]): number;
+/**
+ * Batch transactions into groups that respect count and size limits
+ *
+ * With 100KB per transaction estimate:
+ * - Size limit: ~9 transactions per batch (900KB / 100KB)
+ * - Count limit: 100 transactions per batch
+ * - Size limit is the constraining factor for large transactions
+ */
+declare function batchTransactions(transactions: WriteTransactionConfig[]): WriteTransactionConfig[][];
+
+/**
+ * Wait for transaction confirmations
+ *
+ * Uses waitForTransactionReceipt() from viem/actions to wait for
+ * multiple transactions in parallel. Handles timeouts and tracks progress.
+ *
+ * @param params - Confirmation parameters
+ * @returns Array of transaction receipts
+ * @throws Error if timeout occurs or transaction fails
+ */
+declare function waitForConfirmations(params: WaitForConfirmationsParams): Promise<ConfirmationResult[]>;
+
+/**
+ * Create x402 client for relay payments
+ *
+ * Sets up x402Client with user's account, registers EVM scheme,
+ * and returns wrapped fetch function and HTTP client for header extraction.
+ *
+ * @param account - User's local account (from privateKeyToAccount)
+ * @param chainId - Chain ID (optional, for logging purposes)
+ * @returns Object with fetchWithPayment and httpClient
+ */
+declare function createRelayX402Client(account: LocalAccount, chainId?: number): X402ClientResult;
+
+/**
+ * High-level client for Net Relay Service
+ *
+ * Provides a convenient class-based API that stores apiUrl and chainId,
+ * reducing boilerplate when making multiple relay calls.
+ */
+declare class RelayClient {
+    private apiUrl;
+    private chainId;
+    constructor(options: {
+        apiUrl: string;
+        chainId: number;
+    });
+    /**
+     * Create a relay session token
+     *
+     * @param params - Session creation parameters (apiUrl and chainId are already set)
+     * @returns Session token and expiration timestamp
+     */
+    createSession(params: {
+        operatorAddress: Address;
+        secretKey: string;
+        account: LocalAccount;
+        expiresIn?: number;
+    }): Promise<{
+        sessionToken: string;
+        expiresAt: number;
+    }>;
+    /**
+     * Check backend wallet balance
+     *
+     * @param params - Balance check parameters (apiUrl and chainId are already set)
+     * @returns Result with balance information
+     */
+    checkBalance(params: {
+        operatorAddress: Address;
+        secretKey: string;
+    }): Promise<CheckBalanceResult>;
+    /**
+     * Fund backend wallet via x402 payment
+     *
+     * @param params - Funding parameters (apiUrl and chainId are already set)
+     * @returns Result with paymentTxHash and backendWalletAddress
+     */
+    fundBackendWallet(params: {
+        operatorAddress: Address;
+        secretKey: string;
+        fetchWithPayment: typeof fetch;
+        httpClient: FundBackendWalletParams["httpClient"];
+    }): Promise<RelayFundResult>;
+    /**
+     * Submit transactions via relay
+     *
+     * @param params - Submission parameters (apiUrl and chainId are already set)
+     * @returns Result with transaction hashes and success/failure tracking
+     */
+    submitTransactions(params: {
+        operatorAddress: Address;
+        secretKey: string;
+        transactions: WriteTransactionConfig[];
+        sessionToken: string;
+    }): Promise<RelaySubmitResult>;
+    /**
+     * Retry failed transactions with exponential backoff
+     *
+     * @param params - Retry parameters (apiUrl and chainId are already set)
+     * @returns Final success/failure status after retries
+     */
+    retryFailedTransactions(params: {
+        operatorAddress: Address;
+        secretKey: string;
+        failedIndexes: number[];
+        originalTransactions: WriteTransactionConfig[];
+        backendWalletAddress: Address;
+        config?: RetryConfig;
+        sessionToken: string;
+        recheckFunction?: RetryFailedTransactionsParams["recheckFunction"];
+    }): Promise<RelaySubmitResult>;
+    /**
+     * Create x402 client for relay payments
+     *
+     * @param account - User's local account
+     * @returns Object with fetchWithPayment and httpClient
+     */
+    createX402Client(account: LocalAccount): X402ClientResult;
+}
+
+/**
+ * EIP-712 domain name for relay session signing
+ */
+declare const RELAY_DOMAIN_NAME = "Net Relay Service";
+/**
+ * EIP-712 domain version for relay session signing
+ */
+declare const RELAY_DOMAIN_VERSION = "1";
+/**
+ * EIP-712 types for relay session signing
+ */
+declare const RELAY_SESSION_TYPES: {
+    readonly RelaySession: readonly [{
+        readonly name: "operatorAddress";
+        readonly type: "address";
+    }, {
+        readonly name: "secretKeyHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "expiresAt";
+        readonly type: "uint256";
+    }];
+};
+/**
+ * Default retry configuration
+ */
+declare const DEFAULT_RETRY_CONFIG: Required<RetryConfig>;
+/**
+ * Default number of confirmations to wait for
+ */
+declare const DEFAULT_CONFIRMATIONS = 1;
+/**
+ * Default timeout for waiting for transaction confirmations (milliseconds)
+ */
+declare const DEFAULT_TIMEOUT = 60000;
+/**
+ * Maximum transactions per batch (matches server limit)
+ */
+declare const MAX_TRANSACTIONS_PER_BATCH = 100;
+/**
+ * Maximum request size in bytes (slightly under 1MB for safety margin)
+ */
+declare const MAX_BATCH_SIZE_BYTES: number;
+/**
+ * Maximum size per transaction in bytes
+ * Storage transactions can include large data chunks, so we assume up to 100KB per transaction
+ */
+declare const MAX_TRANSACTION_SIZE_BYTES: number;
+
+export { type BalanceResponse, type CheckBackendWalletBalanceParams, type CheckBalanceResult, type ConfirmationResult, type CreateSessionResponse, DEFAULT_CONFIRMATIONS, DEFAULT_RETRY_CONFIG, DEFAULT_TIMEOUT, type ErrorResponse, type FundBackendWalletParams, type FundResponse, MAX_BATCH_SIZE_BYTES, MAX_TRANSACTIONS_PER_BATCH, MAX_TRANSACTION_SIZE_BYTES, RELAY_DOMAIN_NAME, RELAY_DOMAIN_VERSION, RELAY_SESSION_TYPES, RelayClient, type RelayFundResult, type RelaySubmitResult, type RetryConfig, type RetryFailedTransactionsParams, type SubmitResponse, type SubmitTransactionsViaRelayParams, type VerifyFundResponse, type WaitForConfirmationsParams, type X402ClientResult, batchTransactions, checkBackendWalletBalance, createRelaySession, createRelayX402Client, estimateRequestSize, estimateTransactionSize, fundBackendWallet, retryFailedTransactions, submitTransactionsViaRelay, waitForConfirmations };