@opendatalabs/vana-sdk 2.3.0 → 3.0.0

package/dist/types/relayer.d.ts

@@ -1,552 +0,0 @@
-/**
- * Defines types for gasless transaction relayers and server operations.
- *
- * @remarks
- * This module provides comprehensive type definitions for interacting with
- * relayer services that enable gasless transactions and auxiliary operations.
- * It includes both legacy v1 types and the simplified v2 unified interface.
- *
- * @category Types
- * @module types/relayer
- */
-import type { Hash, Address, TransactionReceipt } from "viem";
-import type { GrantFile, PermissionGrantTypedData, GenericTypedData } from "./permissions";
-import type { Contract, Fn } from "../generated/event-types";
-/**
- * Represents the response from storing grant files via relayer.
- *
- * @remarks
- * Contains storage location, metadata, and error information for
- * grant file upload operations.
- *
- * @category Advanced
- */
-export interface RelayerStorageResponse {
-    /** The IPFS URL where the grant file is stored */
-    grantUrl: string;
-    /** Success status */
-    success: boolean;
-    /** Optional error message */
-    error?: string;
-    /** Storage metadata */
-    metadata?: {
-        /** IPFS hash */
-        ipfsHash: string;
-        /** File size in bytes */
-        size: number;
-        /** Upload timestamp */
-        timestamp: number;
-    };
-}
-/**
- * Represents the response from submitting transactions via relayer.
- *
- * @remarks
- * Contains transaction hash, status, and metadata for gasless
- * transaction submissions.
- *
- * @category Advanced
- */
-export interface RelayerTransactionResponse {
-    /** The transaction hash of the submitted transaction */
-    transactionHash: Hash;
-    /** Success status */
-    success: boolean;
-    /** Optional error message */
-    error?: string;
-    /** Transaction metadata */
-    metadata?: {
-        /** Gas used */
-        gasUsed?: bigint;
-        /** Gas price */
-        gasPrice?: bigint;
-        /** Block number */
-        blockNumber?: bigint;
-        /** Transaction status */
-        status?: "pending" | "confirmed" | "failed";
-    };
-}
-/**
- * Specifies parameters for storing grant files via relayer.
- *
- * @remarks
- * Includes the grant file and optional storage configuration
- * such as encryption and pinning duration.
- *
- * @category Advanced
- */
-export interface RelayerStoreParams {
-    /** The grant file to store */
-    grantFile: GrantFile;
-    /** Optional storage options */
-    options?: {
-        /** IPFS pin duration in seconds */
-        pinDuration?: number;
-        /** Whether to use encryption */
-        encrypt?: boolean;
-        /** Custom metadata */
-        metadata?: Record<string, unknown>;
-    };
-}
-/**
- * Specifies parameters for submitting gasless transactions.
- *
- * @remarks
- * Contains signed typed data and transaction configuration options
- * for relayer submission.
- *
- * @category Advanced
- */
-export interface RelayerSubmitParams {
-    /** The signed typed data */
-    typedData: PermissionGrantTypedData;
-    /** The signature */
-    signature: string;
-    /** Optional transaction options */
-    options?: {
-        /** Gas limit */
-        gasLimit?: bigint;
-        /** Priority level */
-        priority?: "low" | "medium" | "high";
-        /** Whether to wait for confirmation */
-        waitForConfirmation?: boolean;
-    };
-}
-/**
- * Represents the current status and capabilities of a relayer service.
- *
- * @remarks
- * Provides information about supported chains, rate limits, and
- * current operational status for monitoring and decision-making.
- *
- * @category Advanced
- */
-export interface RelayerStatus {
-    /** Whether the relayer is online */
-    online: boolean;
-    /** Service version */
-    version: string;
-    /** Supported chains */
-    supportedChains: number[];
-    /** Current chain status */
-    chainStatus: Record<number, {
-        /** Whether the chain is supported */
-        supported: boolean;
-        /** Current block number */
-        currentBlock: bigint;
-        /** Gas price estimation */
-        gasPrice: bigint;
-        /** Queue size */
-        queueSize: number;
-    }>;
-    /** Rate limit information */
-    rateLimits: {
-        /** Requests per minute */
-        requestsPerMinute: number;
-        /** Storage requests per hour */
-        storageRequestsPerHour: number;
-        /** Transaction requests per hour */
-        transactionRequestsPerHour: number;
-    };
-}
-/**
- * Configures behavior for relayer requests.
- *
- * @remarks
- * Controls timeout, retry logic, headers, and priority for
- * relayer operation requests.
- *
- * @category Advanced
- */
-export interface RelayerRequestOptions {
-    /** Request timeout in milliseconds */
-    timeout?: number;
-    /** Whether to retry on failure */
-    retry?: boolean;
-    /** Custom headers */
-    headers?: Record<string, string>;
-    /** Request priority */
-    priority?: "low" | "medium" | "high";
-}
-/**
- * Represents an error response from the relayer service.
- *
- * @remarks
- * Provides structured error information including codes, messages,
- * and debugging details for error handling and recovery.
- *
- * @category Advanced
- */
-export interface RelayerErrorResponse {
-    /** Error code */
-    code: string;
-    /** Error message */
-    message: string;
-    /** Additional error details */
-    details?: Record<string, unknown>;
-    /** Request ID for debugging */
-    requestId?: string;
-    /** Timestamp of error */
-    timestamp: number;
-}
-/**
- * Provides information about the relayer's processing queue.
- *
- * @remarks
- * Includes queue size, position, estimated processing time, and
- * performance statistics for queue monitoring.
- *
- * @category Advanced
- */
-export interface RelayerQueueInfo {
-    /** Current queue size */
-    size: number;
-    /** Estimated processing time in seconds */
-    estimatedProcessingTime: number;
-    /** Queue position for a specific request */
-    position?: number;
-    /** Processing statistics */
-    stats: {
-        /** Average processing time in seconds */
-        averageProcessingTime: number;
-        /** Requests processed in last hour */
-        requestsProcessedHour: number;
-        /** Success rate percentage */
-        successRate: number;
-    };
-}
-/**
- * Tracks the status of a transaction submitted via relayer.
- *
- * @remarks
- * Provides detailed tracking information including confirmation status,
- * gas usage, and historical status checks.
- *
- * @category Advanced
- */
-export interface RelayerTransactionStatus {
-    /** Transaction hash */
-    transactionHash: Hash;
-    /** Current status */
-    status: "pending" | "confirmed" | "failed";
-    /** Block number if confirmed */
-    blockNumber?: bigint;
-    /** Gas used */
-    gasUsed?: bigint;
-    /** Error message if failed */
-    error?: string;
-    /** Status checks performed */
-    checks: Array<{
-        /** Check timestamp */
-        timestamp: number;
-        /** Status at time of check */
-        status: string;
-        /** Block number at time of check */
-        blockNumber: bigint;
-    }>;
-}
-/**
- * Provides performance metrics for the relayer service.
- *
- * @remarks
- * Includes transaction statistics, success rates, processing times,
- * and uptime information for monitoring and optimization.
- *
- * @category Advanced
- */
-export interface RelayerMetrics {
-    /** Total transactions processed */
-    totalTransactions: number;
-    /** Successful transactions */
-    successfulTransactions: number;
-    /** Failed transactions */
-    failedTransactions: number;
-    /** Average processing time in seconds */
-    averageProcessingTime: number;
-    /** Current queue size */
-    queueSize: number;
-    /** Uptime percentage */
-    uptime: number;
-    /** Last 24 hour statistics */
-    last24Hours: {
-        /** Transactions processed */
-        transactions: number;
-        /** Success rate */
-        successRate: number;
-        /** Average response time */
-        averageResponseTime: number;
-    };
-}
-/**
- * Configures webhook notifications for relayer events.
- *
- * @remarks
- * Enables asynchronous notifications for transaction confirmations,
- * failures, and storage completions.
- *
- * @category Advanced
- */
-export interface RelayerWebhookConfig {
-    /** Webhook URL */
-    url: string;
-    /** Events to subscribe to */
-    events: Array<"transaction_confirmed" | "transaction_failed" | "storage_complete">;
-    /** Webhook secret for signature verification */
-    secret?: string;
-    /** Whether webhook is active */
-    active: boolean;
-}
-/**
- * Represents a webhook event payload from the relayer.
- *
- * @remarks
- * Contains event data, timestamp, and signature for verification
- * of webhook authenticity.
- *
- * @category Advanced
- */
-export interface RelayerWebhookPayload {
-    /** Event type */
-    event: string;
-    /** Event data */
-    data: Record<string, unknown>;
-    /** Timestamp */
-    timestamp: number;
-    /** Webhook ID */
-    webhookId: string;
-    /** Signature for verification */
-    signature: string;
-}
-/**
- * Handles both EIP-712 signed operations and direct server operations through a single interface.
- *
- * @remarks
- * This discriminated union provides type safety through TypeScript's narrowing.
- * The `type` field determines which operation variant is being used.
- * Signed operations require blockchain transactions, while direct operations
- * handle auxiliary tasks like file storage.
- *
- * @category Relayer
- * @see {@link https://docs.vana.org/docs/gasless-transactions | Gasless Transactions Guide}
- */
-export type UnifiedRelayerRequest = SignedRelayerRequest | DirectRelayerRequest | {
-    type: "status_check";
-    operationId: string;
-};
-/**
- * Represents an EIP-712 signed operation for gasless transaction submission.
- *
- * @remarks
- * Signed requests contain typed data and signatures that are verified
- * on-chain by smart contracts. The relayer pays gas fees on behalf of users.
- *
- * @category Relayer
- */
-export interface SignedRelayerRequest {
-    /** Discriminator field identifying this as a signed operation */
-    type: "signed";
-    /** Operation identifier for routing (e.g., 'submitAddPermission') */
-    operation: SignedOperationType;
-    /** EIP-712 typed data structure for the operation */
-    typedData: GenericTypedData;
-    /** User's signature of the typed data */
-    signature: Hash;
-    /** Optional address for additional signer verification */
-    expectedUserAddress?: Address;
-}
-/**
- * Enumerates supported EIP-712 signed operation types.
- *
- * @remarks
- * Each operation type corresponds to a specific smart contract
- * function that accepts gasless transactions.
- *
- * @category Relayer
- */
-export type SignedOperationType = "submitAddPermission" | "submitPermissionRevoke" | "submitTrustServer" | "submitAddAndTrustServer" | "submitUntrustServer" | "submitAddServerFilesAndPermissions";
-/**
- * Represents direct server operations that don't require blockchain signatures.
- *
- * @remarks
- * Direct requests handle auxiliary operations like file uploads and grant storage.
- * These operations may still result in blockchain transactions but don't require
- * user signatures for gasless submission.
- *
- * @category Relayer
- */
-export type DirectRelayerRequest = {
-    type: "direct";
-    operation: "submitFileAddition";
-    params: {
-        url: string;
-        userAddress: Address;
-    };
-} | {
-    type: "direct";
-    operation: "submitFileAdditionWithPermissions";
-    params: {
-        url: string;
-        userAddress: Address;
-        permissions: Array<{
-            account: Address;
-            key: string;
-        }>;
-    };
-} | {
-    type: "direct";
-    operation: "submitFileAdditionComplete";
-    params: {
-        url: string;
-        userAddress: Address;
-        permissions: Array<{
-            account: Address;
-            key: string;
-        }>;
-        schemaId: number;
-        ownerAddress?: Address;
-    };
-} | {
-    type: "direct";
-    operation: "storeGrantFile";
-    params: GrantFile;
-} | {
-    type: "direct";
-    operation: "submitRegisterGrantee";
-    params: {
-        owner: Address;
-        granteeAddress: Address;
-        publicKey: string;
-    };
-};
-/**
- * Context for transaction operations to enable proper event parsing.
- *
- * @remarks
- * This context is preserved in relayer responses to enable client-side
- * event parsing without requiring manual reconstruction of transaction details.
- *
- * @category Relayer
- */
-export interface TransactionContext {
-    /** The contract that was called */
-    contract: Contract;
-    /** The function that was called on the contract */
-    fn: Fn<Contract>;
-    /** The address that initiated the transaction */
-    from: Address;
-}
-/**
- * Provides type-safe responses for all relayer operations.
- *
- * @remarks
- * The discriminated union ensures proper error handling and result typing.
- * Check the `type` field to determine success or failure before accessing results.
- * The new async pattern returns pending operations with operationIds for polling.
- *
- * Transaction responses include optional context to enable client-side event parsing
- * through the enhanced response pattern.
- *
- * @category Relayer
- */
-export type UnifiedRelayerResponse = {
-    type: "pending";
-    operationId: string;
-} | {
-    type: "submitted";
-    hash: Hash;
-    /** Optional context for client-side event parsing and enhanced responses */
-    context?: TransactionContext;
-} | {
-    type: "confirmed";
-    hash: Hash;
-    receipt?: TransactionReceipt;
-} | {
-    type: "signed";
-    hash: Hash;
-    /** Optional context for client-side event parsing and enhanced responses */
-    context?: TransactionContext;
-} | {
-    /** Non-transactional operations that complete immediately (e.g., IPFS uploads, file info) */
-    type: "direct";
-    /** The result data from the operation, structure depends on the specific operation */
-    result: unknown;
-} | {
-    type: "error";
-    error: string;
-};
-/**
- * Simplified relayer configuration.
- * Can be a URL string for convenience, or a callback for full control.
- *
- * @category Configuration
- * @example
- * ```typescript
- * // Option 1: Simple URL (SDK handles the transport)
- * const vana = Vana({
- *   walletClient,
- *   relayer: '/api/relay'
- * });
- *
- * // Option 2: Full control with callback
- * const vana = Vana({
- *   walletClient,
- *   relayer: async (request) => {
- *     const response = await fetch('/api/relay', {
- *       method: 'POST',
- *       body: JSON.stringify(request)
- *     });
- *     return response.json();
- *   }
- * });
- * ```
- */
-export type RelayerConfig = string | ((request: UnifiedRelayerRequest) => Promise<UnifiedRelayerResponse>);
-/**
- * Simplified relayer callbacks interface (v2).
- * A single callback handles all relayer operations.
- *
- * @category Configuration
- * @example
- * ```typescript
- * const relayerCallbacks: RelayerCallbacksV2 = {
- *   submit: async (request) => {
- *     // Send to your server endpoint
- *     const response = await fetch('/api/relay', {
- *       method: 'POST',
- *       headers: { 'Content-Type': 'application/json' },
- *       body: JSON.stringify(request)
- *     });
- *     return response.json();
- *   }
- * };
- * ```
- */
-export interface RelayerCallbacksV2 {
-    /**
-     * Submits any relayer operation to the server.
-     *
-     * @remarks
-     * This single callback handles all operations:
-     * - EIP-712 signed operations (permissions, server trust, etc.)
-     * - Direct operations (file additions, grant storage)
-     *
-     * On your server, pass the entire request object to the SDK's
-     * `handleRelayerOperation` helper function.
-     *
-     * @param request - The unified request object.
-     *   Check `type` field to determine operation variant.
-     * @returns Promise resolving to operation-specific response
-     *
-     * @example
-     * ```typescript
-     * async submit(request) {
-     *   const response = await fetch('/api/relay', {
-     *     method: 'POST',
-     *     body: JSON.stringify(request)
-     *   });
-     *   return response.json();
-     * }
-     * ```
-     */
-    submit: (request: UnifiedRelayerRequest) => Promise<UnifiedRelayerResponse>;
-}

package/dist/types/relayer.js

@@ -1 +0,0 @@
-//# sourceMappingURL=relayer.js.map

package/dist/types/relayer.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/types/transactionResults.cjs

@@ -1,17 +0,0 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var transactionResults_exports = {};
-module.exports = __toCommonJS(transactionResults_exports);
-//# sourceMappingURL=transactionResults.cjs.map

package/dist/types/transactionResults.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../src/types/transactionResults.ts"],"sourcesContent":["import type { Address } from \"viem\";\n// BaseTransactionResult will be replaced once migration is complete\ninterface BaseTransactionResult {\n  transactionHash: `0x${string}`;\n  blockNumber: bigint;\n  gasUsed: bigint;\n}\n\n/**\n * Transaction result types for all SDK operations.\n * These interfaces define the structure of data returned by enhanced\n * transaction methods that parse blockchain events automatically.\n */\n\n// =============================================================================\n// PERMISSION OPERATIONS\n// =============================================================================\n\n/**\n * Result of a successful permission grant operation.\n * Contains data from the PermissionAdded blockchain event.\n */\nexport interface PermissionGrantResult extends BaseTransactionResult {\n  /** Unique permission ID for this grant */\n  permissionId: bigint;\n  /** Address of the user who granted the permission */\n  user: Address;\n  /** URL where the grant file is stored (IPFS/CDN) */\n  grant: string;\n  /** Array of file IDs covered by this permission */\n  fileIds: readonly bigint[];\n}\n\n/**\n * Result of a successful permission revocation operation.\n * Contains data from the PermissionRevoked blockchain event.\n */\nexport interface PermissionRevokeResult extends BaseTransactionResult {\n  /** ID of the permission that was revoked */\n  permissionId: bigint;\n}\n\n/**\n * Result of a successful server trust operation.\n * Contains data from the ServerTrusted blockchain event.\n */\nexport interface ServerTrustResult extends BaseTransactionResult {\n  /** Address of the user who trusted the server (from event) */\n  user: Address;\n  /** Numeric ID of the trusted server (from event) */\n  serverId: bigint;\n  /** Address of the trusted server (from params/derived) */\n  serverAddress?: Address;\n  /** URL of the trusted server (from params/provided) */\n  serverUrl?: string;\n}\n\n/**\n * Result of a successful server untrust operation.\n * Contains data from the ServerUntrusted blockchain event.\n */\nexport interface ServerUntrustResult extends BaseTransactionResult {\n  /** Address of the user who untrusted the server */\n  user: Address;\n  /** Address/ID of the untrusted server */\n  serverId: Address;\n}\n\n/**\n * Result of a successful server registration operation.\n * Contains data from the ServerRegistered blockchain event.\n */\nexport interface ServerRegisterResult extends BaseTransactionResult {\n  /** Unique server ID assigned by the registry */\n  serverId: bigint;\n  /** URL of the registered server */\n  url: string;\n  /** Owner address of the server */\n  owner: Address;\n}\n\n/**\n * Result of a successful server update operation.\n * Contains data from the ServerUpdated blockchain event.\n */\nexport interface ServerUpdateResult extends BaseTransactionResult {\n  /** ID of the server that was updated */\n  serverId: bigint;\n  /** New URL of the server */\n  url: string;\n}\n\n/**\n * Result of a successful grantee registration operation.\n * Contains data from the GranteeRegistered blockchain event.\n */\nexport interface GranteeRegisterResult extends BaseTransactionResult {\n  /** Unique grantee ID assigned by the registry */\n  granteeId: bigint;\n  /** Address of the registered grantee */\n  granteeAddress: Address;\n  /** Display name of the grantee */\n  name: string;\n}\n\n// =============================================================================\n// DATA REGISTRY OPERATIONS\n// =============================================================================\n\n/**\n * Result of a successful file addition operation.\n * Contains data from the FileAddedV2 blockchain event.\n */\nexport interface FileAddedResult extends BaseTransactionResult {\n  /** Unique file ID assigned by the registry */\n  fileId: bigint;\n  /** Address of the file owner */\n  ownerAddress: Address;\n  /** URL where the file is stored */\n  url: string;\n  /** Schema ID associated with the file (0 for no schema) */\n  schemaId: bigint;\n}\n\n/**\n * Result of a successful schema addition operation.\n * Contains data from the SchemaAdded blockchain event.\n */\nexport interface SchemaAddedResult extends BaseTransactionResult {\n  /** Unique schema ID assigned by the registry */\n  schemaId: bigint;\n  /** Human-readable name of the schema */\n  name: string;\n  /** Schema dialect (e.g., \"jsonschema\") */\n  dialect: string;\n  /** URL where the schema definition is stored */\n  definitionUrl: string;\n}\n\n/**\n * Result of a successful refiner addition operation.\n * Contains data from the RefinerAdded blockchain event.\n */\nexport interface RefinerAddedResult extends BaseTransactionResult {\n  /** Unique refiner ID assigned by the registry */\n  refinerId: bigint;\n  /** DLP ID this refiner belongs to */\n  dlpId: bigint;\n  /** Human-readable name of the refiner */\n  name: string;\n  /** Schema ID this refiner uses */\n  schemaId: bigint;\n  /** URL where the schema definition is stored */\n  schemaDefinitionUrl: string;\n  /** URL with refiner processing instructions */\n  refinementInstructionUrl: string;\n}\n\n/**\n * Result of a successful schema ID update operation.\n * Contains data from the RefinerSchemaUpdated blockchain event.\n */\nexport interface SchemaUpdateResult extends BaseTransactionResult {\n  /** ID of the refiner that was updated */\n  refinerId: bigint;\n  /** New schema ID */\n  schemaId: bigint;\n  /** URL of the new schema definition */\n  schemaDefinitionUrl: string;\n}\n\n/**\n * Result of a successful file permission addition operation.\n * Contains data from the FilePermissionAdded blockchain event.\n */\nexport interface FilePermissionResult extends BaseTransactionResult {\n  /** File ID the permission was added to */\n  fileId: bigint;\n  /** Account that was granted permission */\n  account: Address;\n  /** Encrypted key for file access */\n  encryptedKey: string;\n}\n\n// =============================================================================\n// UNION TYPES FOR GENERIC OPERATIONS\n// =============================================================================\n\n/**\n * Union type of all possible transaction result types.\n * Useful for generic functions that handle multiple operation types.\n */\nexport type AnyTransactionResult =\n  | PermissionGrantResult\n  | PermissionRevokeResult\n  | ServerTrustResult\n  | ServerUntrustResult\n  | ServerRegisterResult\n  | ServerUpdateResult\n  | GranteeRegisterResult\n  | FileAddedResult\n  | SchemaAddedResult\n  | RefinerAddedResult\n  | SchemaUpdateResult\n  | FilePermissionResult;\n\n// =============================================================================\n// TYPE UTILITIES\n// =============================================================================\n\n/**\n * Maps transaction operation names to their result types.\n * Used for type inference in generic transaction parsing functions.\n */\nexport interface TransactionResultMap {\n  grant: PermissionGrantResult;\n  revoke: PermissionRevokeResult;\n  revokePermission: PermissionRevokeResult;\n  addServerFilesAndPermissions: PermissionGrantResult;\n  trustServer: ServerTrustResult;\n  untrustServer: ServerUntrustResult;\n  registerServer: ServerRegisterResult;\n  updateServer: ServerUpdateResult;\n  addAndTrustServer: ServerTrustResult;\n  registerGrantee: GranteeRegisterResult;\n  addFile: FileAddedResult;\n  addFileWithPermissionsAndSchema: FileAddedResult;\n  addFileWithSchema: FileAddedResult;\n  addFileWithPermissions: FileAddedResult;\n  addRefinement: RefinerAddedResult;\n  addRefiner: RefinerAddedResult;\n  updateSchemaId: SchemaUpdateResult;\n  addSchema: SchemaAddedResult;\n  updateRefinement: SchemaUpdateResult;\n  addFilePermission: FilePermissionResult;\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}