@opendatalabs/vana-sdk 0.1.0-alpha.f2a82f7 → 0.1.0-alpha.f35bb9c
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/controllers/base.cjs +0 -33
- package/dist/controllers/base.cjs.map +1 -1
- package/dist/controllers/base.d.ts +0 -10
- package/dist/controllers/base.js +0 -33
- package/dist/controllers/base.js.map +1 -1
- package/dist/controllers/data.cjs +19 -26
- package/dist/controllers/data.cjs.map +1 -1
- package/dist/controllers/data.d.ts +9 -9
- package/dist/controllers/data.js +19 -26
- package/dist/controllers/data.js.map +1 -1
- package/dist/controllers/permissions.cjs +65 -124
- package/dist/controllers/permissions.cjs.map +1 -1
- package/dist/controllers/permissions.d.ts +11 -20
- package/dist/controllers/permissions.js +65 -124
- package/dist/controllers/permissions.js.map +1 -1
- package/dist/core.cjs +1 -4
- package/dist/core.cjs.map +1 -1
- package/dist/core.d.ts +1 -2
- package/dist/core.js +1 -4
- package/dist/core.js.map +1 -1
- package/dist/index.node.cjs +0 -2
- package/dist/index.node.cjs.map +1 -1
- package/dist/index.node.d.ts +4 -27
- package/dist/index.node.js +0 -2
- package/dist/index.node.js.map +1 -1
- package/dist/server/relayerHandler.cjs +87 -201
- package/dist/server/relayerHandler.cjs.map +1 -1
- package/dist/server/relayerHandler.d.ts +1 -3
- package/dist/server/relayerHandler.js +87 -201
- package/dist/server/relayerHandler.js.map +1 -1
- package/dist/types/config.cjs.map +1 -1
- package/dist/types/config.d.ts +0 -32
- package/dist/types/config.js.map +1 -1
- package/dist/types/controller-context.cjs.map +1 -1
- package/dist/types/controller-context.d.ts +1 -3
- package/dist/types/generics.cjs.map +1 -1
- package/dist/types/generics.d.ts +1 -1
- package/dist/types/index.cjs.map +1 -1
- package/dist/types/index.d.ts +2 -3
- package/dist/types/index.js.map +1 -1
- package/dist/types/operations.cjs.map +1 -1
- package/dist/types/operations.d.ts +0 -46
- package/dist/types/operations.js.map +1 -1
- package/dist/types/relayer.cjs.map +1 -1
- package/dist/types/relayer.d.ts +8 -19
- package/dist/utils/ipfs.cjs +4 -2
- package/dist/utils/ipfs.cjs.map +1 -1
- package/dist/utils/ipfs.d.ts +1 -1
- package/dist/utils/ipfs.js +4 -2
- package/dist/utils/ipfs.js.map +1 -1
- package/package.json +1 -3
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../../src/types/relayer.ts"],"sourcesContent":["/**\n * Defines types for gasless transaction relayers and server operations.\n *\n * @remarks\n * This module provides comprehensive type definitions for interacting with\n * relayer services that enable gasless transactions and auxiliary operations.\n * It includes both legacy v1 types and the simplified v2 unified interface.\n *\n * @category Types\n * @module types/relayer\n */\n\nimport type { Hash, Address, TransactionReceipt } from \"viem\";\nimport type {\n GrantFile,\n PermissionGrantTypedData,\n GenericTypedData,\n} from \"./permissions\";\n\n/**\n * Represents the response from storing grant files via relayer.\n *\n * @remarks\n * Contains storage location, metadata, and error information for\n * grant file upload operations.\n *\n * @category Advanced\n */\nexport interface RelayerStorageResponse {\n /** The IPFS URL where the grant file is stored */\n grantUrl: string;\n /** Success status */\n success: boolean;\n /** Optional error message */\n error?: string;\n /** Storage metadata */\n metadata?: {\n /** IPFS hash */\n ipfsHash: string;\n /** File size in bytes */\n size: number;\n /** Upload timestamp */\n timestamp: number;\n };\n}\n\n/**\n * Represents the response from submitting transactions via relayer.\n *\n * @remarks\n * Contains transaction hash, status, and metadata for gasless\n * transaction submissions.\n *\n * @category Advanced\n */\nexport interface RelayerTransactionResponse {\n /** The transaction hash of the submitted transaction */\n transactionHash: Hash;\n /** Success status */\n success: boolean;\n /** Optional error message */\n error?: string;\n /** Transaction metadata */\n metadata?: {\n /** Gas used */\n gasUsed?: bigint;\n /** Gas price */\n gasPrice?: bigint;\n /** Block number */\n blockNumber?: bigint;\n /** Transaction status */\n status?: \"pending\" | \"confirmed\" | \"failed\";\n };\n}\n\n/**\n * Specifies parameters for storing grant files via relayer.\n *\n * @remarks\n * Includes the grant file and optional storage configuration\n * such as encryption and pinning duration.\n *\n * @category Advanced\n */\nexport interface RelayerStoreParams {\n /** The grant file to store */\n grantFile: GrantFile;\n /** Optional storage options */\n options?: {\n /** IPFS pin duration in seconds */\n pinDuration?: number;\n /** Whether to use encryption */\n encrypt?: boolean;\n /** Custom metadata */\n metadata?: Record<string, unknown>;\n };\n}\n\n/**\n * Specifies parameters for submitting gasless transactions.\n *\n * @remarks\n * Contains signed typed data and transaction configuration options\n * for relayer submission.\n *\n * @category Advanced\n */\nexport interface RelayerSubmitParams {\n /** The signed typed data */\n typedData: PermissionGrantTypedData;\n /** The signature */\n signature: string;\n /** Optional transaction options */\n options?: {\n /** Gas limit */\n gasLimit?: bigint;\n /** Priority level */\n priority?: \"low\" | \"medium\" | \"high\";\n /** Whether to wait for confirmation */\n waitForConfirmation?: boolean;\n };\n}\n\n/**\n * Represents the current status and capabilities of a relayer service.\n *\n * @remarks\n * Provides information about supported chains, rate limits, and\n * current operational status for monitoring and decision-making.\n *\n * @category Advanced\n */\nexport interface RelayerStatus {\n /** Whether the relayer is online */\n online: boolean;\n /** Service version */\n version: string;\n /** Supported chains */\n supportedChains: number[];\n /** Current chain status */\n chainStatus: Record<\n number,\n {\n /** Whether the chain is supported */\n supported: boolean;\n /** Current block number */\n currentBlock: bigint;\n /** Gas price estimation */\n gasPrice: bigint;\n /** Queue size */\n queueSize: number;\n }\n >;\n /** Rate limit information */\n rateLimits: {\n /** Requests per minute */\n requestsPerMinute: number;\n /** Storage requests per hour */\n storageRequestsPerHour: number;\n /** Transaction requests per hour */\n transactionRequestsPerHour: number;\n };\n}\n\n/**\n * Configures behavior for relayer requests.\n *\n * @remarks\n * Controls timeout, retry logic, headers, and priority for\n * relayer operation requests.\n *\n * @category Advanced\n */\nexport interface RelayerRequestOptions {\n /** Request timeout in milliseconds */\n timeout?: number;\n /** Whether to retry on failure */\n retry?: boolean;\n /** Custom headers */\n headers?: Record<string, string>;\n /** Request priority */\n priority?: \"low\" | \"medium\" | \"high\";\n}\n\n/**\n * Represents an error response from the relayer service.\n *\n * @remarks\n * Provides structured error information including codes, messages,\n * and debugging details for error handling and recovery.\n *\n * @category Advanced\n */\nexport interface RelayerErrorResponse {\n /** Error code */\n code: string;\n /** Error message */\n message: string;\n /** Additional error details */\n details?: Record<string, unknown>;\n /** Request ID for debugging */\n requestId?: string;\n /** Timestamp of error */\n timestamp: number;\n}\n\n/**\n * Provides information about the relayer's processing queue.\n *\n * @remarks\n * Includes queue size, position, estimated processing time, and\n * performance statistics for queue monitoring.\n *\n * @category Advanced\n */\nexport interface RelayerQueueInfo {\n /** Current queue size */\n size: number;\n /** Estimated processing time in seconds */\n estimatedProcessingTime: number;\n /** Queue position for a specific request */\n position?: number;\n /** Processing statistics */\n stats: {\n /** Average processing time in seconds */\n averageProcessingTime: number;\n /** Requests processed in last hour */\n requestsProcessedHour: number;\n /** Success rate percentage */\n successRate: number;\n };\n}\n\n/**\n * Tracks the status of a transaction submitted via relayer.\n *\n * @remarks\n * Provides detailed tracking information including confirmation status,\n * gas usage, and historical status checks.\n *\n * @category Advanced\n */\nexport interface RelayerTransactionStatus {\n /** Transaction hash */\n transactionHash: Hash;\n /** Current status */\n status: \"pending\" | \"confirmed\" | \"failed\";\n /** Block number if confirmed */\n blockNumber?: bigint;\n /** Gas used */\n gasUsed?: bigint;\n /** Error message if failed */\n error?: string;\n /** Status checks performed */\n checks: Array<{\n /** Check timestamp */\n timestamp: number;\n /** Status at time of check */\n status: string;\n /** Block number at time of check */\n blockNumber: bigint;\n }>;\n}\n\n/**\n * Provides performance metrics for the relayer service.\n *\n * @remarks\n * Includes transaction statistics, success rates, processing times,\n * and uptime information for monitoring and optimization.\n *\n * @category Advanced\n */\nexport interface RelayerMetrics {\n /** Total transactions processed */\n totalTransactions: number;\n /** Successful transactions */\n successfulTransactions: number;\n /** Failed transactions */\n failedTransactions: number;\n /** Average processing time in seconds */\n averageProcessingTime: number;\n /** Current queue size */\n queueSize: number;\n /** Uptime percentage */\n uptime: number;\n /** Last 24 hour statistics */\n last24Hours: {\n /** Transactions processed */\n transactions: number;\n /** Success rate */\n successRate: number;\n /** Average response time */\n averageResponseTime: number;\n };\n}\n\n/**\n * Configures webhook notifications for relayer events.\n *\n * @remarks\n * Enables asynchronous notifications for transaction confirmations,\n * failures, and storage completions.\n *\n * @category Advanced\n */\nexport interface RelayerWebhookConfig {\n /** Webhook URL */\n url: string;\n /** Events to subscribe to */\n events: Array<\n \"transaction_confirmed\" | \"transaction_failed\" | \"storage_complete\"\n >;\n /** Webhook secret for signature verification */\n secret?: string;\n /** Whether webhook is active */\n active: boolean;\n}\n\n/**\n * Represents a webhook event payload from the relayer.\n *\n * @remarks\n * Contains event data, timestamp, and signature for verification\n * of webhook authenticity.\n *\n * @category Advanced\n */\nexport interface RelayerWebhookPayload {\n /** Event type */\n event: string;\n /** Event data */\n data: Record<string, unknown>;\n /** Timestamp */\n timestamp: number;\n /** Webhook ID */\n webhookId: string;\n /** Signature for verification */\n signature: string;\n}\n\n// ===== NEW SIMPLIFIED RELAYER TYPES (v2) =====\n\n/**\n * Handles both EIP-712 signed operations and direct server operations through a single interface.\n *\n * @remarks\n * This discriminated union provides type safety through TypeScript's narrowing.\n * The `type` field determines which operation variant is being used.\n * Signed operations require blockchain transactions, while direct operations\n * handle auxiliary tasks like file storage.\n *\n * @category Relayer\n * @see {@link https://docs.vana.org/docs/gasless-transactions | Gasless Transactions Guide}\n */\nexport type UnifiedRelayerRequest =\n | SignedRelayerRequest\n | DirectRelayerRequest\n | {\n type: \"status_check\";\n operationId: string;\n };\n\n/**\n * Represents an EIP-712 signed operation for gasless transaction submission.\n *\n * @remarks\n * Signed requests contain typed data and signatures that are verified\n * on-chain by smart contracts. The relayer pays gas fees on behalf of users.\n *\n * @category Relayer\n */\nexport interface SignedRelayerRequest {\n /** Discriminator field identifying this as a signed operation */\n type: \"signed\";\n /** Operation identifier for routing (e.g., 'submitAddPermission') */\n operation: SignedOperationType;\n /** EIP-712 typed data structure for the operation */\n typedData: GenericTypedData;\n /** User's signature of the typed data */\n signature: Hash;\n /** Optional address for additional signer verification */\n expectedUserAddress?: Address;\n}\n\n/**\n * Enumerates supported EIP-712 signed operation types.\n *\n * @remarks\n * Each operation type corresponds to a specific smart contract\n * function that accepts gasless transactions.\n *\n * @category Relayer\n */\nexport type SignedOperationType =\n | \"submitAddPermission\"\n | \"submitPermissionRevoke\"\n | \"submitTrustServer\"\n | \"submitAddAndTrustServer\"\n | \"submitUntrustServer\"\n | \"submitAddServerFilesAndPermissions\"\n | \"submitRegisterGrantee\";\n\n/**\n * Represents direct server operations that don't require blockchain signatures.\n *\n * @remarks\n * Direct requests handle auxiliary operations like file uploads and grant storage.\n * These operations may still result in blockchain transactions but don't require\n * user signatures for gasless submission.\n *\n * @category Relayer\n */\nexport type DirectRelayerRequest =\n | {\n type: \"direct\";\n operation: \"submitFileAddition\";\n params: {\n url: string;\n userAddress: Address;\n };\n }\n | {\n type: \"direct\";\n operation: \"submitFileAdditionWithPermissions\";\n params: {\n url: string;\n userAddress: Address;\n permissions: Array<{ account: Address; key: string }>;\n };\n }\n | {\n type: \"direct\";\n operation: \"submitFileAdditionComplete\";\n params: {\n url: string;\n userAddress: Address;\n permissions: Array<{ account: Address; key: string }>;\n schemaId: number;\n ownerAddress?: Address;\n };\n }\n | {\n type: \"direct\";\n operation: \"storeGrantFile\";\n params: GrantFile;\n };\n\n/**\n * Provides type-safe responses for all relayer operations.\n *\n * @remarks\n * The discriminated union ensures proper error handling and result typing.\n * Check the `type` field to determine success or failure before accessing results.\n * The new async pattern returns pending operations with operationIds for polling.\n *\n * @category Relayer\n */\nexport type UnifiedRelayerResponse =\n | {\n type: \"pending\";\n operationId: string;\n }\n | {\n type: \"submitted\";\n hash: Hash;\n }\n | {\n type: \"confirmed\";\n hash: Hash;\n // Receipt is optional; a performance hint for the client SDK's polling logic.\n receipt?: TransactionReceipt;\n }\n | {\n type: \"signed\";\n hash: Hash;\n }\n | {\n /** Non-transactional operations that complete immediately (e.g., IPFS uploads, file info) */\n type: \"direct\";\n /** The result data from the operation, structure depends on the specific operation */\n result: unknown;\n }\n | {\n type: \"error\";\n error: string;\n };\n\n/**\n * Simplified relayer configuration.\n * Can be a URL string for convenience, or a callback for full control.\n *\n * @category Configuration\n * @example\n * ```typescript\n * // Option 1: Simple URL (SDK handles the transport)\n * const vana = Vana({\n * walletClient,\n * relayer: '/api/relay'\n * });\n *\n * // Option 2: Full control with callback\n * const vana = Vana({\n * walletClient,\n * relayer: async (request) => {\n * const response = await fetch('/api/relay', {\n * method: 'POST',\n * body: JSON.stringify(request)\n * });\n * return response.json();\n * }\n * });\n * ```\n */\nexport type RelayerConfig =\n | string\n | ((request: UnifiedRelayerRequest) => Promise<UnifiedRelayerResponse>);\n\n/**\n * Simplified relayer callbacks interface (v2).\n * A single callback handles all relayer operations.\n *\n * @category Configuration\n * @example\n * ```typescript\n * const relayerCallbacks: RelayerCallbacksV2 = {\n * submit: async (request) => {\n * // Send to your server endpoint\n * const response = await fetch('/api/relay', {\n * method: 'POST',\n * headers: { 'Content-Type': 'application/json' },\n * body: JSON.stringify(request)\n * });\n * return response.json();\n * }\n * };\n * ```\n */\nexport interface RelayerCallbacksV2 {\n /**\n * Submits any relayer operation to the server.\n *\n * @remarks\n * This single callback handles all operations:\n * - EIP-712 signed operations (permissions, server trust, etc.)\n * - Direct operations (file additions, grant storage)\n *\n * On your server, pass the entire request object to the SDK's\n * `handleRelayerOperation` helper function.\n *\n * @param request - The unified request object.\n * Check `type` field to determine operation variant.\n * @returns Promise resolving to operation-specific response\n *\n * @example\n * ```typescript\n * async submit(request) {\n * const response = await fetch('/api/relay', {\n * method: 'POST',\n * body: JSON.stringify(request)\n * });\n * return response.json();\n * }\n * ```\n */\n submit: (request: UnifiedRelayerRequest) => Promise<UnifiedRelayerResponse>;\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
|
|
1
|
+
{"version":3,"sources":["../../src/types/relayer.ts"],"sourcesContent":["/**\n * Defines types for gasless transaction relayers and server operations.\n *\n * @remarks\n * This module provides comprehensive type definitions for interacting with\n * relayer services that enable gasless transactions and auxiliary operations.\n * It includes both legacy v1 types and the simplified v2 unified interface.\n *\n * @category Types\n * @module types/relayer\n */\n\nimport type { Hash, Address } from \"viem\";\nimport type {\n GrantFile,\n PermissionGrantTypedData,\n GenericTypedData,\n} from \"./permissions\";\n\n/**\n * Represents the response from storing grant files via relayer.\n *\n * @remarks\n * Contains storage location, metadata, and error information for\n * grant file upload operations.\n *\n * @category Advanced\n */\nexport interface RelayerStorageResponse {\n /** The IPFS URL where the grant file is stored */\n grantUrl: string;\n /** Success status */\n success: boolean;\n /** Optional error message */\n error?: string;\n /** Storage metadata */\n metadata?: {\n /** IPFS hash */\n ipfsHash: string;\n /** File size in bytes */\n size: number;\n /** Upload timestamp */\n timestamp: number;\n };\n}\n\n/**\n * Represents the response from submitting transactions via relayer.\n *\n * @remarks\n * Contains transaction hash, status, and metadata for gasless\n * transaction submissions.\n *\n * @category Advanced\n */\nexport interface RelayerTransactionResponse {\n /** The transaction hash of the submitted transaction */\n transactionHash: Hash;\n /** Success status */\n success: boolean;\n /** Optional error message */\n error?: string;\n /** Transaction metadata */\n metadata?: {\n /** Gas used */\n gasUsed?: bigint;\n /** Gas price */\n gasPrice?: bigint;\n /** Block number */\n blockNumber?: bigint;\n /** Transaction status */\n status?: \"pending\" | \"confirmed\" | \"failed\";\n };\n}\n\n/**\n * Specifies parameters for storing grant files via relayer.\n *\n * @remarks\n * Includes the grant file and optional storage configuration\n * such as encryption and pinning duration.\n *\n * @category Advanced\n */\nexport interface RelayerStoreParams {\n /** The grant file to store */\n grantFile: GrantFile;\n /** Optional storage options */\n options?: {\n /** IPFS pin duration in seconds */\n pinDuration?: number;\n /** Whether to use encryption */\n encrypt?: boolean;\n /** Custom metadata */\n metadata?: Record<string, unknown>;\n };\n}\n\n/**\n * Specifies parameters for submitting gasless transactions.\n *\n * @remarks\n * Contains signed typed data and transaction configuration options\n * for relayer submission.\n *\n * @category Advanced\n */\nexport interface RelayerSubmitParams {\n /** The signed typed data */\n typedData: PermissionGrantTypedData;\n /** The signature */\n signature: string;\n /** Optional transaction options */\n options?: {\n /** Gas limit */\n gasLimit?: bigint;\n /** Priority level */\n priority?: \"low\" | \"medium\" | \"high\";\n /** Whether to wait for confirmation */\n waitForConfirmation?: boolean;\n };\n}\n\n/**\n * Represents the current status and capabilities of a relayer service.\n *\n * @remarks\n * Provides information about supported chains, rate limits, and\n * current operational status for monitoring and decision-making.\n *\n * @category Advanced\n */\nexport interface RelayerStatus {\n /** Whether the relayer is online */\n online: boolean;\n /** Service version */\n version: string;\n /** Supported chains */\n supportedChains: number[];\n /** Current chain status */\n chainStatus: Record<\n number,\n {\n /** Whether the chain is supported */\n supported: boolean;\n /** Current block number */\n currentBlock: bigint;\n /** Gas price estimation */\n gasPrice: bigint;\n /** Queue size */\n queueSize: number;\n }\n >;\n /** Rate limit information */\n rateLimits: {\n /** Requests per minute */\n requestsPerMinute: number;\n /** Storage requests per hour */\n storageRequestsPerHour: number;\n /** Transaction requests per hour */\n transactionRequestsPerHour: number;\n };\n}\n\n/**\n * Configures behavior for relayer requests.\n *\n * @remarks\n * Controls timeout, retry logic, headers, and priority for\n * relayer operation requests.\n *\n * @category Advanced\n */\nexport interface RelayerRequestOptions {\n /** Request timeout in milliseconds */\n timeout?: number;\n /** Whether to retry on failure */\n retry?: boolean;\n /** Custom headers */\n headers?: Record<string, string>;\n /** Request priority */\n priority?: \"low\" | \"medium\" | \"high\";\n}\n\n/**\n * Represents an error response from the relayer service.\n *\n * @remarks\n * Provides structured error information including codes, messages,\n * and debugging details for error handling and recovery.\n *\n * @category Advanced\n */\nexport interface RelayerErrorResponse {\n /** Error code */\n code: string;\n /** Error message */\n message: string;\n /** Additional error details */\n details?: Record<string, unknown>;\n /** Request ID for debugging */\n requestId?: string;\n /** Timestamp of error */\n timestamp: number;\n}\n\n/**\n * Provides information about the relayer's processing queue.\n *\n * @remarks\n * Includes queue size, position, estimated processing time, and\n * performance statistics for queue monitoring.\n *\n * @category Advanced\n */\nexport interface RelayerQueueInfo {\n /** Current queue size */\n size: number;\n /** Estimated processing time in seconds */\n estimatedProcessingTime: number;\n /** Queue position for a specific request */\n position?: number;\n /** Processing statistics */\n stats: {\n /** Average processing time in seconds */\n averageProcessingTime: number;\n /** Requests processed in last hour */\n requestsProcessedHour: number;\n /** Success rate percentage */\n successRate: number;\n };\n}\n\n/**\n * Tracks the status of a transaction submitted via relayer.\n *\n * @remarks\n * Provides detailed tracking information including confirmation status,\n * gas usage, and historical status checks.\n *\n * @category Advanced\n */\nexport interface RelayerTransactionStatus {\n /** Transaction hash */\n transactionHash: Hash;\n /** Current status */\n status: \"pending\" | \"confirmed\" | \"failed\";\n /** Block number if confirmed */\n blockNumber?: bigint;\n /** Gas used */\n gasUsed?: bigint;\n /** Error message if failed */\n error?: string;\n /** Status checks performed */\n checks: Array<{\n /** Check timestamp */\n timestamp: number;\n /** Status at time of check */\n status: string;\n /** Block number at time of check */\n blockNumber: bigint;\n }>;\n}\n\n/**\n * Provides performance metrics for the relayer service.\n *\n * @remarks\n * Includes transaction statistics, success rates, processing times,\n * and uptime information for monitoring and optimization.\n *\n * @category Advanced\n */\nexport interface RelayerMetrics {\n /** Total transactions processed */\n totalTransactions: number;\n /** Successful transactions */\n successfulTransactions: number;\n /** Failed transactions */\n failedTransactions: number;\n /** Average processing time in seconds */\n averageProcessingTime: number;\n /** Current queue size */\n queueSize: number;\n /** Uptime percentage */\n uptime: number;\n /** Last 24 hour statistics */\n last24Hours: {\n /** Transactions processed */\n transactions: number;\n /** Success rate */\n successRate: number;\n /** Average response time */\n averageResponseTime: number;\n };\n}\n\n/**\n * Configures webhook notifications for relayer events.\n *\n * @remarks\n * Enables asynchronous notifications for transaction confirmations,\n * failures, and storage completions.\n *\n * @category Advanced\n */\nexport interface RelayerWebhookConfig {\n /** Webhook URL */\n url: string;\n /** Events to subscribe to */\n events: Array<\n \"transaction_confirmed\" | \"transaction_failed\" | \"storage_complete\"\n >;\n /** Webhook secret for signature verification */\n secret?: string;\n /** Whether webhook is active */\n active: boolean;\n}\n\n/**\n * Represents a webhook event payload from the relayer.\n *\n * @remarks\n * Contains event data, timestamp, and signature for verification\n * of webhook authenticity.\n *\n * @category Advanced\n */\nexport interface RelayerWebhookPayload {\n /** Event type */\n event: string;\n /** Event data */\n data: Record<string, unknown>;\n /** Timestamp */\n timestamp: number;\n /** Webhook ID */\n webhookId: string;\n /** Signature for verification */\n signature: string;\n}\n\n// ===== NEW SIMPLIFIED RELAYER TYPES (v2) =====\n\n/**\n * Handles both EIP-712 signed operations and direct server operations through a single interface.\n *\n * @remarks\n * This discriminated union provides type safety through TypeScript's narrowing.\n * The `type` field determines which operation variant is being used.\n * Signed operations require blockchain transactions, while direct operations\n * handle auxiliary tasks like file storage.\n *\n * @category Relayer\n * @see {@link https://docs.vana.org/docs/gasless-transactions | Gasless Transactions Guide}\n */\nexport type UnifiedRelayerRequest = SignedRelayerRequest | DirectRelayerRequest;\n\n/**\n * Represents an EIP-712 signed operation for gasless transaction submission.\n *\n * @remarks\n * Signed requests contain typed data and signatures that are verified\n * on-chain by smart contracts. The relayer pays gas fees on behalf of users.\n *\n * @category Relayer\n */\nexport interface SignedRelayerRequest {\n /** Discriminator field identifying this as a signed operation */\n type: \"signed\";\n /** Operation identifier for routing (e.g., 'submitAddPermission') */\n operation: SignedOperationType;\n /** EIP-712 typed data structure for the operation */\n typedData: GenericTypedData;\n /** User's signature of the typed data */\n signature: Hash;\n /** Optional address for additional signer verification */\n expectedUserAddress?: Address;\n}\n\n/**\n * Enumerates supported EIP-712 signed operation types.\n *\n * @remarks\n * Each operation type corresponds to a specific smart contract\n * function that accepts gasless transactions.\n *\n * @category Relayer\n */\nexport type SignedOperationType =\n | \"submitAddPermission\"\n | \"submitPermissionRevoke\"\n | \"submitTrustServer\"\n | \"submitAddAndTrustServer\"\n | \"submitUntrustServer\"\n | \"submitAddServerFilesAndPermissions\"\n | \"submitRegisterGrantee\";\n\n/**\n * Represents direct server operations that don't require blockchain signatures.\n *\n * @remarks\n * Direct requests handle auxiliary operations like file uploads and grant storage.\n * These operations may still result in blockchain transactions but don't require\n * user signatures for gasless submission.\n *\n * @category Relayer\n */\nexport type DirectRelayerRequest =\n | {\n type: \"direct\";\n operation: \"submitFileAddition\";\n params: {\n url: string;\n userAddress: Address;\n };\n }\n | {\n type: \"direct\";\n operation: \"submitFileAdditionWithPermissions\";\n params: {\n url: string;\n userAddress: Address;\n permissions: Array<{ account: Address; key: string }>;\n };\n }\n | {\n type: \"direct\";\n operation: \"submitFileAdditionComplete\";\n params: {\n url: string;\n userAddress: Address;\n permissions: Array<{ account: Address; key: string }>;\n schemaId: number;\n ownerAddress?: Address;\n };\n }\n | {\n type: \"direct\";\n operation: \"storeGrantFile\";\n params: GrantFile;\n };\n\n/**\n * Provides type-safe responses for all relayer operations.\n *\n * @remarks\n * The discriminated union ensures proper error handling and result typing.\n * Check the `type` field to determine success or failure before accessing results.\n *\n * @category Relayer\n */\nexport type UnifiedRelayerResponse =\n | {\n type: \"signed\";\n hash: Hash;\n }\n | {\n type: \"direct\";\n result: { fileId: number; transactionHash: Hash } | { url: string } | any;\n }\n | {\n type: \"error\";\n error: string;\n };\n\n/**\n * Simplified relayer configuration.\n * Can be a URL string for convenience, or a callback for full control.\n *\n * @category Configuration\n * @example\n * ```typescript\n * // Option 1: Simple URL (SDK handles the transport)\n * const vana = Vana({\n * walletClient,\n * relayer: '/api/relay'\n * });\n *\n * // Option 2: Full control with callback\n * const vana = Vana({\n * walletClient,\n * relayer: async (request) => {\n * const response = await fetch('/api/relay', {\n * method: 'POST',\n * body: JSON.stringify(request)\n * });\n * return response.json();\n * }\n * });\n * ```\n */\nexport type RelayerConfig =\n | string\n | ((request: UnifiedRelayerRequest) => Promise<UnifiedRelayerResponse>);\n\n/**\n * Simplified relayer callbacks interface (v2).\n * A single callback handles all relayer operations.\n *\n * @category Configuration\n * @example\n * ```typescript\n * const relayerCallbacks: RelayerCallbacksV2 = {\n * submit: async (request) => {\n * // Send to your server endpoint\n * const response = await fetch('/api/relay', {\n * method: 'POST',\n * headers: { 'Content-Type': 'application/json' },\n * body: JSON.stringify(request)\n * });\n * return response.json();\n * }\n * };\n * ```\n */\nexport interface RelayerCallbacksV2 {\n /**\n * Submits any relayer operation to the server.\n *\n * @remarks\n * This single callback handles all operations:\n * - EIP-712 signed operations (permissions, server trust, etc.)\n * - Direct operations (file additions, grant storage)\n *\n * On your server, pass the entire request object to the SDK's\n * `handleRelayerOperation` helper function.\n *\n * @param request - The unified request object.\n * Check `type` field to determine operation variant.\n * @returns Promise resolving to operation-specific response\n *\n * @example\n * ```typescript\n * async submit(request) {\n * const response = await fetch('/api/relay', {\n * method: 'POST',\n * body: JSON.stringify(request)\n * });\n * return response.json();\n * }\n * ```\n */\n submit: (request: UnifiedRelayerRequest) => Promise<UnifiedRelayerResponse>;\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
|
package/dist/types/relayer.d.ts
CHANGED
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
* @category Types
|
|
10
10
|
* @module types/relayer
|
|
11
11
|
*/
|
|
12
|
-
import type { Hash, Address
|
|
12
|
+
import type { Hash, Address } from "viem";
|
|
13
13
|
import type { GrantFile, PermissionGrantTypedData, GenericTypedData } from "./permissions";
|
|
14
14
|
/**
|
|
15
15
|
* Represents the response from storing grant files via relayer.
|
|
@@ -328,10 +328,7 @@ export interface RelayerWebhookPayload {
|
|
|
328
328
|
* @category Relayer
|
|
329
329
|
* @see {@link https://docs.vana.org/docs/gasless-transactions | Gasless Transactions Guide}
|
|
330
330
|
*/
|
|
331
|
-
export type UnifiedRelayerRequest = SignedRelayerRequest | DirectRelayerRequest
|
|
332
|
-
type: "status_check";
|
|
333
|
-
operationId: string;
|
|
334
|
-
};
|
|
331
|
+
export type UnifiedRelayerRequest = SignedRelayerRequest | DirectRelayerRequest;
|
|
335
332
|
/**
|
|
336
333
|
* Represents an EIP-712 signed operation for gasless transaction submission.
|
|
337
334
|
*
|
|
@@ -415,28 +412,20 @@ export type DirectRelayerRequest = {
|
|
|
415
412
|
* @remarks
|
|
416
413
|
* The discriminated union ensures proper error handling and result typing.
|
|
417
414
|
* Check the `type` field to determine success or failure before accessing results.
|
|
418
|
-
* The new async pattern returns pending operations with operationIds for polling.
|
|
419
415
|
*
|
|
420
416
|
* @category Relayer
|
|
421
417
|
*/
|
|
422
418
|
export type UnifiedRelayerResponse = {
|
|
423
|
-
type: "pending";
|
|
424
|
-
operationId: string;
|
|
425
|
-
} | {
|
|
426
|
-
type: "submitted";
|
|
427
|
-
hash: Hash;
|
|
428
|
-
} | {
|
|
429
|
-
type: "confirmed";
|
|
430
|
-
hash: Hash;
|
|
431
|
-
receipt?: TransactionReceipt;
|
|
432
|
-
} | {
|
|
433
419
|
type: "signed";
|
|
434
420
|
hash: Hash;
|
|
435
421
|
} | {
|
|
436
|
-
/** Non-transactional operations that complete immediately (e.g., IPFS uploads, file info) */
|
|
437
422
|
type: "direct";
|
|
438
|
-
|
|
439
|
-
|
|
423
|
+
result: {
|
|
424
|
+
fileId: number;
|
|
425
|
+
transactionHash: Hash;
|
|
426
|
+
} | {
|
|
427
|
+
url: string;
|
|
428
|
+
} | any;
|
|
440
429
|
} | {
|
|
441
430
|
type: "error";
|
|
442
431
|
error: string;
|
package/dist/utils/ipfs.cjs
CHANGED
|
@@ -30,10 +30,12 @@ __export(ipfs_exports, {
|
|
|
30
30
|
module.exports = __toCommonJS(ipfs_exports);
|
|
31
31
|
const DEFAULT_IPFS_GATEWAY = "https://dweb.link/ipfs/";
|
|
32
32
|
const IPFS_GATEWAYS = [
|
|
33
|
+
"https://dweb.link/ipfs/",
|
|
34
|
+
// Interplanetary Shipyard - highly reliable
|
|
33
35
|
"https://ipfs.io/ipfs/",
|
|
34
36
|
// IPFS Foundation - reliable
|
|
35
|
-
"https://
|
|
36
|
-
//
|
|
37
|
+
"https://cloudflare-ipfs.com/ipfs/",
|
|
38
|
+
// Cloudflare - good performance
|
|
37
39
|
"https://gateway.pinata.cloud/ipfs/",
|
|
38
40
|
// Pinata - backup option (has rate limits)
|
|
39
41
|
"https://ipfs.filebase.io/ipfs/"
|
package/dist/utils/ipfs.cjs.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../../src/utils/ipfs.ts"],"sourcesContent":["/**\n * IPFS URL utilities for the Vana SDK\n *\n * Centralized functions for handling IPFS URLs, converting them to gateway URLs,\n * and extracting IPFS hashes from various URL formats.\n */\n\n/**\n * Default IPFS gateway URL\n */\nexport const DEFAULT_IPFS_GATEWAY = \"https://dweb.link/ipfs/\";\n\n/**\n * Alternative IPFS gateways for fallback - ordered by reliability and rate limits\n */\nexport const IPFS_GATEWAYS = [\n \"https://ipfs.io/ipfs/\", // IPFS Foundation - reliable\n \"https://
|
|
1
|
+
{"version":3,"sources":["../../src/utils/ipfs.ts"],"sourcesContent":["/**\n * IPFS URL utilities for the Vana SDK\n *\n * Centralized functions for handling IPFS URLs, converting them to gateway URLs,\n * and extracting IPFS hashes from various URL formats.\n */\n\n/**\n * Default IPFS gateway URL\n */\nexport const DEFAULT_IPFS_GATEWAY = \"https://dweb.link/ipfs/\";\n\n/**\n * Alternative IPFS gateways for fallback - ordered by reliability and rate limits\n */\nexport const IPFS_GATEWAYS = [\n \"https://dweb.link/ipfs/\", // Interplanetary Shipyard - highly reliable\n \"https://ipfs.io/ipfs/\", // IPFS Foundation - reliable\n \"https://cloudflare-ipfs.com/ipfs/\", // Cloudflare - good performance\n \"https://gateway.pinata.cloud/ipfs/\", // Pinata - backup option (has rate limits)\n \"https://ipfs.filebase.io/ipfs/\", // Filebase - emerging reliable option\n] as const;\n\n/**\n * Check if a URL is an IPFS URL (starts with ipfs://)\n *\n * @param url - The URL to check\n * @returns True if the URL is an IPFS URL\n */\nexport function isIpfsUrl(url: string): boolean {\n return url.startsWith(\"ipfs://\");\n}\n\n/**\n * Convert an IPFS URL to an HTTP gateway URL\n *\n * @param url - The IPFS URL to convert (e.g., \"ipfs://QmHash...\")\n * @param gateway - Optional gateway URL (defaults to DEFAULT_IPFS_GATEWAY)\n * @returns The HTTP gateway URL or original URL if not an IPFS URL\n * @example\n * ```ts\n * convertIpfsUrl(\"ipfs://QmHash123\")\n * // Returns: \"https://ipfs.io/ipfs/QmHash123\"\n *\n * convertIpfsUrl(\"ipfs://QmHash123\", \"https://gateway.pinata.cloud/ipfs/\")\n * // Returns: \"https://gateway.pinata.cloud/ipfs/QmHash123\"\n * ```\n */\nexport function convertIpfsUrl(\n url: string,\n gateway: string = DEFAULT_IPFS_GATEWAY,\n): string {\n if (isIpfsUrl(url)) {\n const hash = url.replace(\"ipfs://\", \"\");\n return `${gateway}${hash}`;\n }\n return url;\n}\n\n/**\n * Extract IPFS hash from various URL formats\n *\n * **Edge Cases:**\n * - Returns null for non-IPFS URLs or malformed hashes\n * - Handles both CIDv0 (starts with Qm) and CIDv1 formats\n * - Minimum 46 characters required for standalone hash detection\n * - Gateway paths with subdirectories are not supported\n *\n * @param url - The URL to extract hash from\n * @returns The IPFS hash or null if not found\n * @example\n * ```ts\n * extractIpfsHash(\"ipfs://QmHash123\") // Returns: \"QmHash123\"\n * extractIpfsHash(\"https://gateway.pinata.cloud/ipfs/QmHash123\") // Returns: \"QmHash123\"\n * extractIpfsHash(\"QmHash123456789012345678901234567890123456\") // Returns: \"QmHash123456789012345678901234567890123456\"\n * extractIpfsHash(\"https://example.com/file.json\") // Returns: null (not IPFS)\n * extractIpfsHash(\"ipfs://QmHash/subdirectory\") // Returns: null (subdirectories not supported)\n * ```\n */\nexport function extractIpfsHash(url: string): string | null {\n // Handle various IPFS URL formats\n const patterns = [\n /ipfs\\/([a-zA-Z0-9]+)/, // https://gateway.pinata.cloud/ipfs/HASH\n /^ipfs:\\/\\/([a-zA-Z0-9]+)$/, // ipfs://HASH\n /^([a-zA-Z0-9]{46,})$/, // Just the hash (46+ chars for IPFS hashes)\n ];\n\n for (const pattern of patterns) {\n const match = url.match(pattern);\n if (match) {\n return match[1];\n }\n }\n\n return null;\n}\n\n/**\n * Get multiple gateway URLs for an IPFS hash (useful for fallback)\n *\n * @param hash - The IPFS hash\n * @returns Array of gateway URLs\n */\nexport function getGatewayUrls(hash: string): string[] {\n return IPFS_GATEWAYS.map((gateway) => `${gateway}${hash}`);\n}\n\n/**\n * Convert an IPFS URL to multiple gateway URLs for fallback\n *\n * @param url - The IPFS URL\n * @returns Array of gateway URLs or original URL if not IPFS\n */\nexport function convertIpfsUrlWithFallbacks(url: string): string[] {\n const hash = extractIpfsHash(url);\n if (hash) {\n return getGatewayUrls(hash);\n }\n return [url];\n}\n\n/**\n * Fetch content from IPFS with automatic gateway fallbacks\n *\n * **Edge Cases:**\n * - Non-IPFS URLs are fetched directly without fallback\n * - 10-second timeout per gateway attempt to prevent hanging\n * - Rate-limited gateways (429) are skipped immediately\n * - Exponential backoff between retries (1s, 2s, 3s, etc.)\n * - AbortSignal in options is merged with timeout signal\n *\n * @param url - The IPFS URL to fetch\n * @param options - Optional fetch options\n * @returns Promise resolving to Response object\n * @throws Error if all gateways fail\n */\nexport async function fetchWithFallbacks(\n url: string,\n options?: RequestInit,\n): Promise<Response> {\n const hash = extractIpfsHash(url);\n if (!hash) {\n // Not an IPFS URL, fetch directly\n return fetch(url, options);\n }\n\n const gatewayUrls = getGatewayUrls(hash);\n let lastError: Error | null = null;\n\n for (let i = 0; i < gatewayUrls.length; i++) {\n const gatewayUrl = gatewayUrls[i];\n try {\n const response = await fetch(gatewayUrl, {\n ...options,\n // Add timeout to avoid hanging on slow gateways\n signal: AbortSignal.timeout(10000), // 10 second timeout\n });\n\n // If response is ok, return it\n if (response.ok) {\n return response;\n }\n\n // If rate limited (429), try next gateway immediately\n if (response.status === 429) {\n lastError = new Error(`Gateway rate limited: ${gatewayUrl}`);\n continue;\n }\n\n // For other HTTP errors, still try next gateway\n lastError = new Error(`Gateway error ${response.status}: ${gatewayUrl}`);\n } catch (error) {\n lastError = error instanceof Error ? error : new Error(String(error));\n\n // For rate limiting or timeout errors, continue to next gateway\n if (\n lastError.message.includes(\"429\") ||\n lastError.name === \"TimeoutError\"\n ) {\n continue;\n }\n }\n\n // Add delay between retries (except for last attempt)\n if (i < gatewayUrls.length - 1) {\n await new Promise((resolve) => setTimeout(resolve, 1000 * (i + 1))); // Exponential backoff\n }\n }\n\n throw new Error(\n `All IPFS gateways failed for hash ${hash}. Last error: ${lastError?.message}`,\n );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAUO,MAAM,uBAAuB;AAK7B,MAAM,gBAAgB;AAAA,EAC3B;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AACF;AAQO,SAAS,UAAU,KAAsB;AAC9C,SAAO,IAAI,WAAW,SAAS;AACjC;AAiBO,SAAS,eACd,KACA,UAAkB,sBACV;AACR,MAAI,UAAU,GAAG,GAAG;AAClB,UAAM,OAAO,IAAI,QAAQ,WAAW,EAAE;AACtC,WAAO,GAAG,OAAO,GAAG,IAAI;AAAA,EAC1B;AACA,SAAO;AACT;AAsBO,SAAS,gBAAgB,KAA4B;AAE1D,QAAM,WAAW;AAAA,IACf;AAAA;AAAA,IACA;AAAA;AAAA,IACA;AAAA;AAAA,EACF;AAEA,aAAW,WAAW,UAAU;AAC9B,UAAM,QAAQ,IAAI,MAAM,OAAO;AAC/B,QAAI,OAAO;AACT,aAAO,MAAM,CAAC;AAAA,IAChB;AAAA,EACF;AAEA,SAAO;AACT;AAQO,SAAS,eAAe,MAAwB;AACrD,SAAO,cAAc,IAAI,CAAC,YAAY,GAAG,OAAO,GAAG,IAAI,EAAE;AAC3D;AAQO,SAAS,4BAA4B,KAAuB;AACjE,QAAM,OAAO,gBAAgB,GAAG;AAChC,MAAI,MAAM;AACR,WAAO,eAAe,IAAI;AAAA,EAC5B;AACA,SAAO,CAAC,GAAG;AACb;AAiBA,eAAsB,mBACpB,KACA,SACmB;AACnB,QAAM,OAAO,gBAAgB,GAAG;AAChC,MAAI,CAAC,MAAM;AAET,WAAO,MAAM,KAAK,OAAO;AAAA,EAC3B;AAEA,QAAM,cAAc,eAAe,IAAI;AACvC,MAAI,YAA0B;AAE9B,WAAS,IAAI,GAAG,IAAI,YAAY,QAAQ,KAAK;AAC3C,UAAM,aAAa,YAAY,CAAC;AAChC,QAAI;AACF,YAAM,WAAW,MAAM,MAAM,YAAY;AAAA,QACvC,GAAG;AAAA;AAAA,QAEH,QAAQ,YAAY,QAAQ,GAAK;AAAA;AAAA,MACnC,CAAC;AAGD,UAAI,SAAS,IAAI;AACf,eAAO;AAAA,MACT;AAGA,UAAI,SAAS,WAAW,KAAK;AAC3B,oBAAY,IAAI,MAAM,yBAAyB,UAAU,EAAE;AAC3D;AAAA,MACF;AAGA,kBAAY,IAAI,MAAM,iBAAiB,SAAS,MAAM,KAAK,UAAU,EAAE;AAAA,IACzE,SAAS,OAAO;AACd,kBAAY,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC;AAGpE,UACE,UAAU,QAAQ,SAAS,KAAK,KAChC,UAAU,SAAS,gBACnB;AACA;AAAA,MACF;AAAA,IACF;AAGA,QAAI,IAAI,YAAY,SAAS,GAAG;AAC9B,YAAM,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,OAAQ,IAAI,EAAE,CAAC;AAAA,IACpE;AAAA,EACF;AAEA,QAAM,IAAI;AAAA,IACR,qCAAqC,IAAI,iBAAiB,WAAW,OAAO;AAAA,EAC9E;AACF;","names":[]}
|
package/dist/utils/ipfs.d.ts
CHANGED
|
@@ -11,7 +11,7 @@ export declare const DEFAULT_IPFS_GATEWAY = "https://dweb.link/ipfs/";
|
|
|
11
11
|
/**
|
|
12
12
|
* Alternative IPFS gateways for fallback - ordered by reliability and rate limits
|
|
13
13
|
*/
|
|
14
|
-
export declare const IPFS_GATEWAYS: readonly ["https://ipfs.io/ipfs/", "https://
|
|
14
|
+
export declare const IPFS_GATEWAYS: readonly ["https://dweb.link/ipfs/", "https://ipfs.io/ipfs/", "https://cloudflare-ipfs.com/ipfs/", "https://gateway.pinata.cloud/ipfs/", "https://ipfs.filebase.io/ipfs/"];
|
|
15
15
|
/**
|
|
16
16
|
* Check if a URL is an IPFS URL (starts with ipfs://)
|
|
17
17
|
*
|
package/dist/utils/ipfs.js
CHANGED
|
@@ -1,9 +1,11 @@
|
|
|
1
1
|
const DEFAULT_IPFS_GATEWAY = "https://dweb.link/ipfs/";
|
|
2
2
|
const IPFS_GATEWAYS = [
|
|
3
|
+
"https://dweb.link/ipfs/",
|
|
4
|
+
// Interplanetary Shipyard - highly reliable
|
|
3
5
|
"https://ipfs.io/ipfs/",
|
|
4
6
|
// IPFS Foundation - reliable
|
|
5
|
-
"https://
|
|
6
|
-
//
|
|
7
|
+
"https://cloudflare-ipfs.com/ipfs/",
|
|
8
|
+
// Cloudflare - good performance
|
|
7
9
|
"https://gateway.pinata.cloud/ipfs/",
|
|
8
10
|
// Pinata - backup option (has rate limits)
|
|
9
11
|
"https://ipfs.filebase.io/ipfs/"
|
package/dist/utils/ipfs.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../../src/utils/ipfs.ts"],"sourcesContent":["/**\n * IPFS URL utilities for the Vana SDK\n *\n * Centralized functions for handling IPFS URLs, converting them to gateway URLs,\n * and extracting IPFS hashes from various URL formats.\n */\n\n/**\n * Default IPFS gateway URL\n */\nexport const DEFAULT_IPFS_GATEWAY = \"https://dweb.link/ipfs/\";\n\n/**\n * Alternative IPFS gateways for fallback - ordered by reliability and rate limits\n */\nexport const IPFS_GATEWAYS = [\n \"https://ipfs.io/ipfs/\", // IPFS Foundation - reliable\n \"https://
|
|
1
|
+
{"version":3,"sources":["../../src/utils/ipfs.ts"],"sourcesContent":["/**\n * IPFS URL utilities for the Vana SDK\n *\n * Centralized functions for handling IPFS URLs, converting them to gateway URLs,\n * and extracting IPFS hashes from various URL formats.\n */\n\n/**\n * Default IPFS gateway URL\n */\nexport const DEFAULT_IPFS_GATEWAY = \"https://dweb.link/ipfs/\";\n\n/**\n * Alternative IPFS gateways for fallback - ordered by reliability and rate limits\n */\nexport const IPFS_GATEWAYS = [\n \"https://dweb.link/ipfs/\", // Interplanetary Shipyard - highly reliable\n \"https://ipfs.io/ipfs/\", // IPFS Foundation - reliable\n \"https://cloudflare-ipfs.com/ipfs/\", // Cloudflare - good performance\n \"https://gateway.pinata.cloud/ipfs/\", // Pinata - backup option (has rate limits)\n \"https://ipfs.filebase.io/ipfs/\", // Filebase - emerging reliable option\n] as const;\n\n/**\n * Check if a URL is an IPFS URL (starts with ipfs://)\n *\n * @param url - The URL to check\n * @returns True if the URL is an IPFS URL\n */\nexport function isIpfsUrl(url: string): boolean {\n return url.startsWith(\"ipfs://\");\n}\n\n/**\n * Convert an IPFS URL to an HTTP gateway URL\n *\n * @param url - The IPFS URL to convert (e.g., \"ipfs://QmHash...\")\n * @param gateway - Optional gateway URL (defaults to DEFAULT_IPFS_GATEWAY)\n * @returns The HTTP gateway URL or original URL if not an IPFS URL\n * @example\n * ```ts\n * convertIpfsUrl(\"ipfs://QmHash123\")\n * // Returns: \"https://ipfs.io/ipfs/QmHash123\"\n *\n * convertIpfsUrl(\"ipfs://QmHash123\", \"https://gateway.pinata.cloud/ipfs/\")\n * // Returns: \"https://gateway.pinata.cloud/ipfs/QmHash123\"\n * ```\n */\nexport function convertIpfsUrl(\n url: string,\n gateway: string = DEFAULT_IPFS_GATEWAY,\n): string {\n if (isIpfsUrl(url)) {\n const hash = url.replace(\"ipfs://\", \"\");\n return `${gateway}${hash}`;\n }\n return url;\n}\n\n/**\n * Extract IPFS hash from various URL formats\n *\n * **Edge Cases:**\n * - Returns null for non-IPFS URLs or malformed hashes\n * - Handles both CIDv0 (starts with Qm) and CIDv1 formats\n * - Minimum 46 characters required for standalone hash detection\n * - Gateway paths with subdirectories are not supported\n *\n * @param url - The URL to extract hash from\n * @returns The IPFS hash or null if not found\n * @example\n * ```ts\n * extractIpfsHash(\"ipfs://QmHash123\") // Returns: \"QmHash123\"\n * extractIpfsHash(\"https://gateway.pinata.cloud/ipfs/QmHash123\") // Returns: \"QmHash123\"\n * extractIpfsHash(\"QmHash123456789012345678901234567890123456\") // Returns: \"QmHash123456789012345678901234567890123456\"\n * extractIpfsHash(\"https://example.com/file.json\") // Returns: null (not IPFS)\n * extractIpfsHash(\"ipfs://QmHash/subdirectory\") // Returns: null (subdirectories not supported)\n * ```\n */\nexport function extractIpfsHash(url: string): string | null {\n // Handle various IPFS URL formats\n const patterns = [\n /ipfs\\/([a-zA-Z0-9]+)/, // https://gateway.pinata.cloud/ipfs/HASH\n /^ipfs:\\/\\/([a-zA-Z0-9]+)$/, // ipfs://HASH\n /^([a-zA-Z0-9]{46,})$/, // Just the hash (46+ chars for IPFS hashes)\n ];\n\n for (const pattern of patterns) {\n const match = url.match(pattern);\n if (match) {\n return match[1];\n }\n }\n\n return null;\n}\n\n/**\n * Get multiple gateway URLs for an IPFS hash (useful for fallback)\n *\n * @param hash - The IPFS hash\n * @returns Array of gateway URLs\n */\nexport function getGatewayUrls(hash: string): string[] {\n return IPFS_GATEWAYS.map((gateway) => `${gateway}${hash}`);\n}\n\n/**\n * Convert an IPFS URL to multiple gateway URLs for fallback\n *\n * @param url - The IPFS URL\n * @returns Array of gateway URLs or original URL if not IPFS\n */\nexport function convertIpfsUrlWithFallbacks(url: string): string[] {\n const hash = extractIpfsHash(url);\n if (hash) {\n return getGatewayUrls(hash);\n }\n return [url];\n}\n\n/**\n * Fetch content from IPFS with automatic gateway fallbacks\n *\n * **Edge Cases:**\n * - Non-IPFS URLs are fetched directly without fallback\n * - 10-second timeout per gateway attempt to prevent hanging\n * - Rate-limited gateways (429) are skipped immediately\n * - Exponential backoff between retries (1s, 2s, 3s, etc.)\n * - AbortSignal in options is merged with timeout signal\n *\n * @param url - The IPFS URL to fetch\n * @param options - Optional fetch options\n * @returns Promise resolving to Response object\n * @throws Error if all gateways fail\n */\nexport async function fetchWithFallbacks(\n url: string,\n options?: RequestInit,\n): Promise<Response> {\n const hash = extractIpfsHash(url);\n if (!hash) {\n // Not an IPFS URL, fetch directly\n return fetch(url, options);\n }\n\n const gatewayUrls = getGatewayUrls(hash);\n let lastError: Error | null = null;\n\n for (let i = 0; i < gatewayUrls.length; i++) {\n const gatewayUrl = gatewayUrls[i];\n try {\n const response = await fetch(gatewayUrl, {\n ...options,\n // Add timeout to avoid hanging on slow gateways\n signal: AbortSignal.timeout(10000), // 10 second timeout\n });\n\n // If response is ok, return it\n if (response.ok) {\n return response;\n }\n\n // If rate limited (429), try next gateway immediately\n if (response.status === 429) {\n lastError = new Error(`Gateway rate limited: ${gatewayUrl}`);\n continue;\n }\n\n // For other HTTP errors, still try next gateway\n lastError = new Error(`Gateway error ${response.status}: ${gatewayUrl}`);\n } catch (error) {\n lastError = error instanceof Error ? error : new Error(String(error));\n\n // For rate limiting or timeout errors, continue to next gateway\n if (\n lastError.message.includes(\"429\") ||\n lastError.name === \"TimeoutError\"\n ) {\n continue;\n }\n }\n\n // Add delay between retries (except for last attempt)\n if (i < gatewayUrls.length - 1) {\n await new Promise((resolve) => setTimeout(resolve, 1000 * (i + 1))); // Exponential backoff\n }\n }\n\n throw new Error(\n `All IPFS gateways failed for hash ${hash}. Last error: ${lastError?.message}`,\n );\n}\n"],"mappings":"AAUO,MAAM,uBAAuB;AAK7B,MAAM,gBAAgB;AAAA,EAC3B;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AACF;AAQO,SAAS,UAAU,KAAsB;AAC9C,SAAO,IAAI,WAAW,SAAS;AACjC;AAiBO,SAAS,eACd,KACA,UAAkB,sBACV;AACR,MAAI,UAAU,GAAG,GAAG;AAClB,UAAM,OAAO,IAAI,QAAQ,WAAW,EAAE;AACtC,WAAO,GAAG,OAAO,GAAG,IAAI;AAAA,EAC1B;AACA,SAAO;AACT;AAsBO,SAAS,gBAAgB,KAA4B;AAE1D,QAAM,WAAW;AAAA,IACf;AAAA;AAAA,IACA;AAAA;AAAA,IACA;AAAA;AAAA,EACF;AAEA,aAAW,WAAW,UAAU;AAC9B,UAAM,QAAQ,IAAI,MAAM,OAAO;AAC/B,QAAI,OAAO;AACT,aAAO,MAAM,CAAC;AAAA,IAChB;AAAA,EACF;AAEA,SAAO;AACT;AAQO,SAAS,eAAe,MAAwB;AACrD,SAAO,cAAc,IAAI,CAAC,YAAY,GAAG,OAAO,GAAG,IAAI,EAAE;AAC3D;AAQO,SAAS,4BAA4B,KAAuB;AACjE,QAAM,OAAO,gBAAgB,GAAG;AAChC,MAAI,MAAM;AACR,WAAO,eAAe,IAAI;AAAA,EAC5B;AACA,SAAO,CAAC,GAAG;AACb;AAiBA,eAAsB,mBACpB,KACA,SACmB;AACnB,QAAM,OAAO,gBAAgB,GAAG;AAChC,MAAI,CAAC,MAAM;AAET,WAAO,MAAM,KAAK,OAAO;AAAA,EAC3B;AAEA,QAAM,cAAc,eAAe,IAAI;AACvC,MAAI,YAA0B;AAE9B,WAAS,IAAI,GAAG,IAAI,YAAY,QAAQ,KAAK;AAC3C,UAAM,aAAa,YAAY,CAAC;AAChC,QAAI;AACF,YAAM,WAAW,MAAM,MAAM,YAAY;AAAA,QACvC,GAAG;AAAA;AAAA,QAEH,QAAQ,YAAY,QAAQ,GAAK;AAAA;AAAA,MACnC,CAAC;AAGD,UAAI,SAAS,IAAI;AACf,eAAO;AAAA,MACT;AAGA,UAAI,SAAS,WAAW,KAAK;AAC3B,oBAAY,IAAI,MAAM,yBAAyB,UAAU,EAAE;AAC3D;AAAA,MACF;AAGA,kBAAY,IAAI,MAAM,iBAAiB,SAAS,MAAM,KAAK,UAAU,EAAE;AAAA,IACzE,SAAS,OAAO;AACd,kBAAY,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC;AAGpE,UACE,UAAU,QAAQ,SAAS,KAAK,KAChC,UAAU,SAAS,gBACnB;AACA;AAAA,MACF;AAAA,IACF;AAGA,QAAI,IAAI,YAAY,SAAS,GAAG;AAC9B,YAAM,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,OAAQ,IAAI,EAAE,CAAC;AAAA,IACpE;AAAA,EACF;AAEA,QAAM,IAAI;AAAA,IACR,qCAAqC,IAAI,iBAAiB,WAAW,OAAO;AAAA,EAC9E;AACF;","names":[]}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@opendatalabs/vana-sdk",
|
|
3
|
-
"version": "0.1.0-alpha.
|
|
3
|
+
"version": "0.1.0-alpha.f35bb9c",
|
|
4
4
|
"description": "A TypeScript library for interacting with Vana Network smart contracts.",
|
|
5
5
|
"publishConfig": {
|
|
6
6
|
"access": "public"
|
|
@@ -122,7 +122,6 @@
|
|
|
122
122
|
"eccrypto-js": "^5.4.0",
|
|
123
123
|
"graphql": "^16.11.0",
|
|
124
124
|
"openpgp": "^6.1.1",
|
|
125
|
-
"uuid": "^13.0.0",
|
|
126
125
|
"viem": "^2.35.1"
|
|
127
126
|
},
|
|
128
127
|
"devDependencies": {
|
|
@@ -132,7 +131,6 @@
|
|
|
132
131
|
"@graphql-codegen/typescript-operations": "^4.6.1",
|
|
133
132
|
"@types/node": "^24.3.0",
|
|
134
133
|
"@types/secp256k1": "^4.0.6",
|
|
135
|
-
"@types/uuid": "^10.0.0",
|
|
136
134
|
"@typescript-eslint/eslint-plugin": "^8.41.0",
|
|
137
135
|
"@typescript-eslint/parser": "^8.41.0",
|
|
138
136
|
"@vitest/coverage-v8": "^3.2.4",
|