@opendatalabs/vana-sdk 0.1.0-alpha.d7fc764 → 0.1.0-alpha.dc68f39

package/dist/utils/grantValidation.d.cts

@@ -1,150 +0,0 @@
-import { Address } from 'viem';
-import { GrantFile } from '../types/permissions.cjs';
-
-/**
- * Base error class for grant validation failures
- *
- * @category Permissions
- */
-declare class GrantValidationError extends Error {
-    details?: Record<string, unknown> | undefined;
-    constructor(message: string, details?: Record<string, unknown> | undefined);
-}
-/**
- * Error thrown when a grant has expired
- *
- * @category Permissions
- */
-declare class GrantExpiredError extends GrantValidationError {
-    expires: number;
-    currentTime: number;
-    constructor(message: string, expires: number, currentTime: number);
-}
-/**
- * Error thrown when grantee doesn't match requesting address
- *
- * @category Permissions
- */
-declare class GranteeMismatchError extends GrantValidationError {
-    grantee: Address;
-    requestingAddress: Address;
-    constructor(message: string, grantee: Address, requestingAddress: Address);
-}
-/**
- * Error thrown when operation is not allowed by grant
- *
- * @category Permissions
- */
-declare class OperationNotAllowedError extends GrantValidationError {
-    grantedOperation: string;
-    requestedOperation: string;
-    constructor(message: string, grantedOperation: string, requestedOperation: string);
-}
-/**
- * Error thrown when grant file structure is invalid
- *
- * @category Permissions
- */
-declare class GrantSchemaError extends GrantValidationError {
-    schemaErrors: unknown[];
-    invalidData: unknown;
-    constructor(message: string, schemaErrors: unknown[], invalidData: unknown);
-}
-/**
- * Options for grant validation
- *
- * @category Permissions
- */
-interface GrantValidationOptions {
-    /** Enable JSON schema validation (default: true) */
-    schema?: boolean;
-    /** Grantee address to validate access for */
-    grantee?: Address;
-    /** Operation to validate permission for */
-    operation?: string;
-    /** Override current time for expiry checking (Unix timestamp) */
-    currentTime?: number;
-    /** Return detailed results instead of throwing (default: false) */
-    throwOnError?: boolean;
-}
-/**
- * Detailed validation result
- *
- * @category Permissions
- */
-interface GrantValidationResult {
-    /** Whether validation passed */
-    valid: boolean;
-    /** Validation errors encountered */
-    errors: Array<{
-        type: "schema" | "business";
-        field?: string;
-        message: string;
-        error?: Error;
-    }>;
-    /** The validated grant file (if validation passed) */
-    grant?: GrantFile;
-}
-/**
- * Validates a grant file with comprehensive schema and business rule checking.
- *
- * This function provides flexible validation with TypeScript overloads:
- * - When `throwOnError` is false (or `{ throwOnError: false }`), returns a detailed validation result
- * - When `throwOnError` is true (default), throws specific errors or returns the validated grant
- *
- * @param data - The grant file data to validate (unknown type for safety)
- * @param options - Validation options including grantee, operation, files, etc.
- * @returns Either a GrantFile (when throwing) or GrantValidationResult (when not throwing)
- * @throws {GrantSchemaError} When the grant file structure is invalid
- * @throws {GrantExpiredError} When the grant has expired
- * @throws {GranteeMismatchError} When the grantee doesn't match the requesting address
- * @throws {OperationNotAllowedError} When the requested operation is not allowed
- * @example
- * ```typescript
- * // Throwing mode (default) - returns GrantFile or throws
- * const grant = validateGrant(data, {
- *   grantee: '0x123...',
- *   operation: 'llm_inference',
- * });
- *
- * // Non-throwing mode - returns validation result
- * const result = validateGrant(data, {
- *   grantee: '0x123...',
- *   throwOnError: false
- * });
- * if (result.valid) {
- *   console.log('Grant is valid:', result.grant);
- * } else {
- *   console.log('Validation errors:', result.errors);
- * }
- * ```
- */
-declare function validateGrant(data: unknown, options: GrantValidationOptions & {
-    throwOnError: false;
-}): GrantValidationResult;
-declare function validateGrant(data: unknown, options?: Omit<GrantValidationOptions, "throwOnError"> | (GrantValidationOptions & {
-    throwOnError?: true;
-})): GrantFile;
-/**
- * Validates that a grant file allows access for a specific grantee
- *
- * @param grantFile - The grant file to validate access for
- * @param requestingAddress - The address requesting access to check against the grantee
- */
-declare function validateGranteeAccess(grantFile: GrantFile, requestingAddress: Address): void;
-/**
- * Validates that a grant has not expired (if expiry is set)
- *
- * @param grantFile - The grant file to check expiration for
- * @param currentTime - Optional override for current time (Unix timestamp)
- */
-declare function validateGrantExpiry(grantFile: GrantFile, currentTime?: number): void;
-/**
- * Validates that a grant allows a specific operation
- *
- * @param grantFile - The grant file to validate operation access for
- * @param requestedOperation - The operation being requested to validate against the grant
- */
-declare function validateOperationAccess(grantFile: GrantFile, requestedOperation: string): void;
-
-export { GrantExpiredError, GrantSchemaError, GrantValidationError, type GrantValidationOptions, type GrantValidationResult, GranteeMismatchError, OperationNotAllowedError, validateGrant, validateGrantExpiry, validateGranteeAccess, validateOperationAccess };

package/dist/utils/grants.d.cts

@@ -1,70 +0,0 @@
-import { Address } from 'viem';
-import { GrantPermissionParams, GrantFile } from '../types/permissions.cjs';
-
-/**
- * High-level utilities for working with grants in the Vana SDK
- */
-/**
- * Creates and validates a grant file from permission parameters
- *
- * @param params - The permission parameters to create and validate the grant from
- * @returns The validated grant file object
- */
-declare function createValidatedGrant(params: GrantPermissionParams): GrantFile;
-/**
- * Creates a grant file and stores it in IPFS
- *
- * @param params - The permission parameters to create the grant from
- * @param relayerUrl - The URL of the relayer service for IPFS storage
- * @returns Promise resolving to an object containing the grant file and its IPFS URL
- */
-declare function createAndStoreGrant(params: GrantPermissionParams, relayerUrl: string): Promise<{
-    grantFile: GrantFile;
-    grantUrl: string;
-}>;
-/**
- * Retrieves and validates a grant file from IPFS
- *
- * @param grantUrl - The IPFS URL of the grant file to retrieve
- * @param relayerUrl - Optional URL of the relayer service
- * @returns Promise resolving to the validated grant file
- */
-declare function retrieveAndValidateGrant(grantUrl: string, relayerUrl?: string): Promise<GrantFile>;
-/**
- * Checks if a grant allows access for a specific request
- *
- * @param grantUrl - The IPFS URL of the grant file to check
- * @param requestingAddress - The address making the access request
- * @param operation - The operation being requested
- * @param fileIds - Array of file IDs being accessed (currently unused but part of interface)
- * @param relayerUrl - Optional URL of the relayer service
- * @returns Promise resolving to access result with allowed status, reason, and grant file
- */
-declare function checkGrantAccess(grantUrl: string, requestingAddress: Address, operation: string, fileIds: number[], relayerUrl?: string): Promise<{
-    allowed: boolean;
-    reason?: string;
-    grantFile?: GrantFile;
-}>;
-/**
- * Utility to check if a grant has expired
- *
- * @param grantFile - The grant file to check for expiration
- * @returns True if the grant has expired, false otherwise
- */
-declare function isGrantExpired(grantFile: GrantFile): boolean;
-/**
- * Utility to get the time remaining before grant expires (in seconds)
- *
- * @param grantFile - The grant file to check time remaining for
- * @returns Number of seconds remaining, or null if no expiration is set
- */
-declare function getGrantTimeRemaining(grantFile: GrantFile): number | null;
-/**
- * Creates a human-readable summary of a grant
- *
- * @param grantFile - The grant file to create a summary for
- * @returns A human-readable string describing the grant
- */
-declare function summarizeGrant(grantFile: GrantFile): string;
-
-export { checkGrantAccess, createAndStoreGrant, createValidatedGrant, getGrantTimeRemaining, isGrantExpired, retrieveAndValidateGrant, summarizeGrant };

package/dist/utils/ipfs.d.cts

@@ -1,90 +0,0 @@
-/**
- * IPFS URL utilities for the Vana SDK
- *
- * Centralized functions for handling IPFS URLs, converting them to gateway URLs,
- * and extracting IPFS hashes from various URL formats.
- */
-/**
- * Default IPFS gateway URL
- */
-declare const DEFAULT_IPFS_GATEWAY = "https://dweb.link/ipfs/";
-/**
- * Alternative IPFS gateways for fallback - ordered by reliability and rate limits
- */
-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/"];
-/**
- * Check if a URL is an IPFS URL (starts with ipfs://)
- *
- * @param url - The URL to check
- * @returns True if the URL is an IPFS URL
- */
-declare function isIpfsUrl(url: string): boolean;
-/**
- * Convert an IPFS URL to an HTTP gateway URL
- *
- * @param url - The IPFS URL to convert (e.g., "ipfs://QmHash...")
- * @param gateway - Optional gateway URL (defaults to DEFAULT_IPFS_GATEWAY)
- * @returns The HTTP gateway URL or original URL if not an IPFS URL
- * @example
- * ```ts
- * convertIpfsUrl("ipfs://QmHash123")
- * // Returns: "https://ipfs.io/ipfs/QmHash123"
- *
- * convertIpfsUrl("ipfs://QmHash123", "https://gateway.pinata.cloud/ipfs/")
- * // Returns: "https://gateway.pinata.cloud/ipfs/QmHash123"
- * ```
- */
-declare function convertIpfsUrl(url: string, gateway?: string): string;
-/**
- * Extract IPFS hash from various URL formats
- *
- * **Edge Cases:**
- * - Returns null for non-IPFS URLs or malformed hashes
- * - Handles both CIDv0 (starts with Qm) and CIDv1 formats
- * - Minimum 46 characters required for standalone hash detection
- * - Gateway paths with subdirectories are not supported
- *
- * @param url - The URL to extract hash from
- * @returns The IPFS hash or null if not found
- * @example
- * ```ts
- * extractIpfsHash("ipfs://QmHash123") // Returns: "QmHash123"
- * extractIpfsHash("https://gateway.pinata.cloud/ipfs/QmHash123") // Returns: "QmHash123"
- * extractIpfsHash("QmHash123456789012345678901234567890123456") // Returns: "QmHash123456789012345678901234567890123456"
- * extractIpfsHash("https://example.com/file.json") // Returns: null (not IPFS)
- * extractIpfsHash("ipfs://QmHash/subdirectory") // Returns: null (subdirectories not supported)
- * ```
- */
-declare function extractIpfsHash(url: string): string | null;
-/**
- * Get multiple gateway URLs for an IPFS hash (useful for fallback)
- *
- * @param hash - The IPFS hash
- * @returns Array of gateway URLs
- */
-declare function getGatewayUrls(hash: string): string[];
-/**
- * Convert an IPFS URL to multiple gateway URLs for fallback
- *
- * @param url - The IPFS URL
- * @returns Array of gateway URLs or original URL if not IPFS
- */
-declare function convertIpfsUrlWithFallbacks(url: string): string[];
-/**
- * Fetch content from IPFS with automatic gateway fallbacks
- *
- * **Edge Cases:**
- * - Non-IPFS URLs are fetched directly without fallback
- * - 10-second timeout per gateway attempt to prevent hanging
- * - Rate-limited gateways (429) are skipped immediately
- * - Exponential backoff between retries (1s, 2s, 3s, etc.)
- * - AbortSignal in options is merged with timeout signal
- *
- * @param url - The IPFS URL to fetch
- * @param options - Optional fetch options
- * @returns Promise resolving to Response object
- * @throws Error if all gateways fail
- */
-declare function fetchWithFallbacks(url: string, options?: RequestInit): Promise<Response>;
-
-export { DEFAULT_IPFS_GATEWAY, IPFS_GATEWAYS, convertIpfsUrl, convertIpfsUrlWithFallbacks, extractIpfsHash, fetchWithFallbacks, getGatewayUrls, isIpfsUrl };

package/dist/utils/lazy-import.d.cts

@@ -1,20 +0,0 @@
-/**
- * Utility for lazy-loading modules to avoid Turbopack TDZ issues
- *
- * WARNING: This is a workaround for Turbopack's strict module initialization.
- * Dependencies that access globals during init must be dynamically imported.
- */
-/**
- * Creates a lazy import function that caches the promise (not the module)
- * to avoid race conditions on concurrent first calls
- *
- * @param importFn - Function that returns a dynamic import promise
- * @returns Function that returns the cached import promise
- *
- * @example
- * const getOpenPGP = lazyImport(() => import('openpgp'));
- * const openpgp = await getOpenPGP();
- */
-declare function lazyImport<T>(importFn: () => Promise<T>): () => Promise<T>;
-
-export { lazyImport };

package/dist/utils/multicall.d.cts

@@ -1,129 +0,0 @@
-import { Address, Abi, PublicClient, MulticallParameters, MulticallReturnType } from 'viem';
-
-/**
- * Type for a contract function configuration used in multicall
- */
-interface ContractFunctionConfig {
-    address: Address;
-    abi: Abi;
-    functionName: string;
-    args?: readonly unknown[];
-}
-/**
- * Configuration options for gas-aware multicall batching.
- *
- * @remarks
- * These options control how the multicall utility splits large batches
- * to stay within gas and calldata limits. The defaults are conservative
- * to ensure compatibility across different chains and RPC providers.
- */
-interface GasAwareMulticallOptions {
-    /**
-     * Maximum gas per batch. Defaults to 10M (conservative for most chains).
-     *
-     * @remarks
-     * This should be set below the block gas limit of your target chain.
-     * Common values:
-     * - Vana mainnet: 30M (use 25M for safety)
-     * - Vana moksha: 30M (use 25M for safety)
-     * - Ethereum mainnet: 30M (use 25M for safety)
-     * - Arbitrum: 32M (use 25M for safety)
-     */
-    maxGasPerBatch?: bigint;
-    /**
-     * Maximum calldata size per batch in bytes. Defaults to 100KB.
-     *
-     * @remarks
-     * This is particularly important for L2 chains where calldata is expensive.
-     * Some RPC providers also have limits on request size.
-     */
-    maxCalldataBytes?: number;
-    /**
-     * How often to checkpoint gas estimates. Defaults to every 32 calls or 8KB.
-     *
-     * @remarks
-     * More frequent checkpoints give more accurate batching but require more
-     * RPC calls for gas estimation. The default balances accuracy vs performance.
-     */
-    checkpointFrequency?: {
-        /** Checkpoint after this many calls */
-        calls: number;
-        /** Checkpoint after this many bytes of calldata */
-        bytes: number;
-    };
-    /**
-     * Whether to allow partial batch failures. Defaults to false.
-     *
-     * @remarks
-     * When true, individual call failures won't fail the entire batch.
-     * This matches viem's multicall behavior with allowFailure option.
-     */
-    allowFailure?: boolean;
-    /**
-     * Optional multicall3 contract address override.
-     *
-     * @remarks
-     * By default, uses the standard multicall3 address deployed on most chains:
-     * 0xcA11bde05977b3631167028862bE2a173976CA11
-     */
-    multicallAddress?: Address;
-    /**
-     * Optional callback for tracking batching progress.
-     *
-     * @remarks
-     * Useful for showing progress in UI or debugging batch performance.
-     */
-    onProgress?: (completed: number, total: number) => void;
-}
-/**
- * A gas-aware multicall function that automatically batches calls to stay within limits.
- *
- * @remarks
- * This function extends viem's multicall with intelligent batching based on:
- * - Actual gas costs (via periodic estimateGas calls)
- * - Calldata size limits
- * - Chain-specific constraints
- *
- * It uses a greedy algorithm with periodic checkpoints to efficiently determine
- * optimal batch sizes without making excessive RPC calls.
- *
- * @param client - The viem public client to use for RPC calls
- * @param parameters - The multicall parameters (same as viem's multicall)
- * @param options - Optional configuration for gas-aware batching
- * @returns The aggregated results from all batches
- *
- * @example
- * ```typescript
- * // Basic usage - drop-in replacement for viem's multicall
- * const results = await gasAwareMulticall(publicClient, {
- *   contracts: [
- *     { address: '0x...', abi: erc20Abi, functionName: 'balanceOf', args: [address1] },
- *     { address: '0x...', abi: erc20Abi, functionName: 'balanceOf', args: [address2] },
- *     // ... hundreds more calls
- *   ]
- * });
- *
- * // With custom limits for a specific chain
- * const results = await gasAwareMulticall(publicClient, {
- *   contracts: calls,
- * }, {
- *   maxGasPerBatch: 25_000_000n, // 25M for mainnet
- *   maxCalldataBytes: 128_000, // 128KB
- *   onProgress: (done, total) => console.log(`Progress: ${done}/${total}`)
- * });
- * ```
- */
-declare function gasAwareMulticall<TContracts extends readonly ContractFunctionConfig[], TAllowFailure extends boolean = false>(client: PublicClient, parameters: MulticallParameters<TContracts, TAllowFailure>, options?: GasAwareMulticallOptions): Promise<MulticallReturnType<TContracts, TAllowFailure>>;
-/**
- * Utility function to analyze calls and predict optimal batch configuration
- *
- * @remarks
- * This function helps determine the best configuration for a specific set of calls
- * by analyzing their characteristics. Useful for optimizing repeated operations.
- *
- * @param contracts - The calls to analyze
- * @returns Suggested configuration based on call analysis
- */
-declare function analyzeCallsForOptimalConfig(contracts: readonly ContractFunctionConfig[]): Pick<GasAwareMulticallOptions, "checkpointFrequency" | "maxCalldataBytes">;
-
-export { type ContractFunctionConfig, type GasAwareMulticallOptions, analyzeCallsForOptimalConfig, gasAwareMulticall };

package/dist/utils/schemaValidation.d.cts

@@ -1,172 +0,0 @@
-import { Schema } from '../types/data.cjs';
-import 'viem';
-
-/**
- * Data schema interface following the Vana schema specification
- *
- * @category Configuration
- */
-interface DataSchema {
-    /** The name of the data schema */
-    name: string;
-    /** The version of the data schema */
-    version: string;
-    /** Optional description of the data schema */
-    description?: string;
-    /** The dialect type - either SQLite or JSON */
-    dialect: "sqlite" | "json";
-    /** Optional version of the dialect */
-    dialectVersion?: string;
-    /** The actual schema definition as string or object */
-    schema: string | object;
-}
-/**
- * Error thrown when schema validation fails
- */
-declare class SchemaValidationError extends Error {
-    errors: Array<{
-        instancePath: string;
-        schemaPath: string;
-        keyword: string;
-        params: Record<string, unknown>;
-        message?: string;
-    }>;
-    constructor(message: string, errors: Array<{
-        instancePath: string;
-        schemaPath: string;
-        keyword: string;
-        params: Record<string, unknown>;
-        message?: string;
-    }>);
-}
-/**
- * Data schema validation utility class
- */
-declare class SchemaValidator {
-    private ajv;
-    private dataSchemaValidator;
-    constructor();
-    /**
-     * Validates a data schema definition against the Vana meta-schema
-     *
-     * @param schema - The data schema definition to validate
-     * @throws SchemaValidationError if invalid
-     * @example
-     * ```typescript
-     * const validator = new SchemaValidator();
-     *
-     * const schema = {
-     *   name: "User Profile",
-     *   version: "1.0.0",
-     *   dialect: "json",
-     *   schema: {
-     *     type: "object",
-     *     properties: {
-     *       name: { type: "string" },
-     *       age: { type: "number" }
-     *     }
-     *   }
-     * };
-     *
-     * validator.validateDataSchemaAgainstMetaSchema(schema); // throws if invalid
-     * ```
-     */
-    validateDataSchemaAgainstMetaSchema(schema: unknown): asserts schema is DataSchema;
-    /**
-     * Validates data against a JSON Schema
-     *
-     * @param data - The data to validate
-     * @param schema - The schema containing the validation rules (must have been validated or fetched from chain)
-     * @throws SchemaValidationError if invalid
-     * @example
-     * ```typescript
-     * const validator = new SchemaValidator();
-     *
-     * // Works with Schema from schemas.get()
-     * const schema = await vana.schemas.get(1);
-     * validator.validateDataAgainstSchema(userData, schema);
-     *
-     * // Also works with pre-validated DataSchema object
-     * const dataSchema = validator.validateDataSchemaAgainstMetaSchema({
-     *   name: "User Profile",
-     *   version: "1.0.0",
-     *   dialect: "json",
-     *   schema: { type: "object", properties: { name: { type: "string" } } }
-     * });
-     * validator.validateDataAgainstSchema(userData, dataSchema);
-     * ```
-     */
-    validateDataAgainstSchema(data: unknown, schema: DataSchema | Schema): void;
-    /**
-     * Validates a SQLite DDL string for basic syntax
-     * Note: This is a basic validation, full SQL parsing would require a proper SQL parser
-     *
-     * @param ddl - The DDL string to validate
-     * @param dialectVersion - Optional SQLite version (e.g., "3" for SQLite v3)
-     * @throws SchemaValidationError if invalid
-     */
-    validateSQLiteDDL(ddl: string, dialectVersion?: string): void;
-    /**
-     * Fetches and validates a data schema from a URL
-     *
-     * @param url - The URL to fetch the data schema from
-     * @param downloadRelayer - Optional download relayer for CORS bypass
-     * @param downloadRelayer.proxyDownload - Function to proxy downloads through application server
-     * @returns The validated data schema
-     * @throws SchemaValidationError if invalid or fetch fails
-     * @example
-     * ```typescript
-     * const validator = new SchemaValidator();
-     * const schema = await validator.fetchAndValidateSchema("https://example.com/schema.json");
-     * ```
-     */
-    fetchAndValidateSchema(url: string, downloadRelayer?: {
-        proxyDownload: (url: string) => Promise<Blob>;
-    }): Promise<DataSchema>;
-}
-/**
- * Global schema validator instance
- */
-declare const schemaValidator: SchemaValidator;
-/**
- * Convenience function to validate a data schema definition against the Vana meta-schema
- *
- * @param schema - The data schema definition to validate
- * @returns The validated DataSchema
- * @throws SchemaValidationError if invalid
- * @example
- * ```typescript
- * const schemaDefinition = {
- *   name: "User Profile",
- *   version: "1.0.0",
- *   dialect: "json",
- *   schema: { type: "object", properties: { name: { type: "string" } } }
- * };
- *
- * const validatedSchema = validateDataSchemaAgainstMetaSchema(schemaDefinition);
- * ```
- */
-declare function validateDataSchemaAgainstMetaSchema(schema: unknown): DataSchema;
-/**
- * Convenience function to validate data against a schema
- *
- * @param data - The data to validate
- * @param schema - The data schema containing the schema
- * @returns void - Function doesn't return a value
- * @throws SchemaValidationError if invalid
- */
-declare function validateDataAgainstSchema(data: unknown, schema: DataSchema | Schema): void;
-/**
- * Convenience function to fetch and validate a data schema from a URL
- *
- * @param url - The URL to fetch the data schema from
- * @param downloadRelayer - Optional download relayer for CORS bypass
- * @param downloadRelayer.proxyDownload - Function to proxy downloads through application server
- * @returns The validated data schema
- * @throws SchemaValidationError if invalid or fetch fails
- */
-declare function fetchAndValidateSchema(url: string, downloadRelayer?: {
-    proxyDownload: (url: string) => Promise<Blob>;
-}): Promise<DataSchema>;
-
-export { type DataSchema, SchemaValidationError, SchemaValidator, fetchAndValidateSchema, schemaValidator, validateDataAgainstSchema, validateDataSchemaAgainstMetaSchema };