@opendatalabs/vana-sdk 0.1.0-alpha.7ee7635 → 0.1.0-alpha.80df35f

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/parseTransactionPojo.d.cts

@@ -1,37 +0,0 @@
-import { TransactionReceipt } from 'viem';
-import { TransactionResult } from '../types/operations.cjs';
-import { Contract, Fn, TypedTransactionResult } from '../generated/event-types.cjs';
-import '../generated/server/server-exports.cjs';
-import '../generated/server/server.cjs';
-
-/**
- * Transaction parsing with POJO support and NO heuristics.
- *
- * @remarks
- * This is the new POJO-based parser that works with TransactionResult objects.
- * Principle: Explicit over implicit, guarantees over guesses.
- */
-
-/**
- * Parses a transaction using TransactionResult POJO with ZERO heuristics.
- *
- * @remarks
- * - Uses function-scoped event registry for O(1) lookups
- * - Only expects events explicitly mapped for this contract.function
- * - Returns typed events matching the exact TypedTransactionResult interface
- *
- * @param transactionResult - The TransactionResult POJO with context
- * @param transactionResult.hash - Transaction hash
- * @param transactionResult.from - Transaction sender address
- * @param transactionResult.contract - Contract name
- * @param transactionResult.fn - Function name
- * @param transactionResult.chainId - Optional chain ID
- * @param transactionResult.value - Optional transaction value
- * @param transactionResult.nonce - Optional nonce
- * @param transactionResult.to - Optional recipient address
- * @param receipt - The transaction receipt from the blockchain
- * @returns Typed transaction result with parsed events
- */
-declare function parseTransaction<C extends Contract, F extends Fn<C>>(transactionResult: TransactionResult<C, F>, receipt: TransactionReceipt): TypedTransactionResult<C, F>;
-
-export { parseTransaction };

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 };

package/dist/utils/signatureCache.d.cts

@@ -1,134 +0,0 @@
-import { Hash } from 'viem';
-import { VanaCacheAdapter } from '../platform/interface.cjs';
-
-/**
- * Simple signature cache using platform cache adapter to avoid repeated signing of identical messages.
- *
- * @remarks
- * This cache significantly improves UX by avoiding repeated wallet signature prompts
- * for identical operations. It's particularly useful for operations that may be
- * retried or called multiple times with the same parameters.
- *
- * Features:
- * - Platform-appropriate storage (sessionStorage in browser, memory in Node.js)
- * - Configurable TTL (default 2 hours)
- * - Automatic cleanup of expired entries
- * - Cache keys based on wallet address + message hash
- *
- * @example
- * ```typescript
- * // Check cache before requesting signature
- * const cached = SignatureCache.get(cache, walletAddress, messageHash);
- * if (cached) {
- *   return cached;
- * }
- *
- * // Request signature and cache it
- * const signature = await wallet.signTypedData(typedData);
- * SignatureCache.set(cache, walletAddress, messageHash, signature);
- * ```
- * @category Utilities
- */
-declare class SignatureCache {
-    private static readonly PREFIX;
-    private static readonly DEFAULT_TTL_HOURS;
-    /**
-     * Get a cached signature if it exists and hasn't expired
-     *
-     * @param cache - Platform cache adapter instance
-     * @param walletAddress - Wallet address that created the signature
-     * @param messageHash - Hash of the message that was signed
-     * @returns The cached signature if valid, null if expired or not found
-     * @example
-     * ```typescript
-     * const messageHash = SignatureCache.hashMessage(typedData);
-     * const cached = SignatureCache.get(cache, '0x123...', messageHash);
-     * if (cached) {
-     *   console.log('Using cached signature:', cached);
-     * }
-     * ```
-     */
-    static get(cache: VanaCacheAdapter, walletAddress: string, messageHash: string): Hash | null;
-    /**
-     * Store a signature in the cache with configurable TTL
-     *
-     * @param cache - Platform cache adapter instance
-     * @param walletAddress - Wallet address that created the signature
-     * @param messageHash - Hash of the message that was signed
-     * @param signature - The signature to cache
-     * @param ttlHours - Time to live in hours (default: 2)
-     * @example
-     * ```typescript
-     * const signature = await wallet.signTypedData(typedData);
-     * const messageHash = SignatureCache.hashMessage(typedData);
-     *
-     * // Cache for default 2 hours
-     * SignatureCache.set(cache, walletAddress, messageHash, signature);
-     *
-     * // Cache for 24 hours
-     * SignatureCache.set(cache, walletAddress, messageHash, signature, 24);
-     * ```
-     */
-    static set(cache: VanaCacheAdapter, walletAddress: string, messageHash: string, signature: Hash, ttlHours?: number): void;
-    /**
-     * Clear all cached signatures (useful for testing or explicit cleanup)
-     *
-     * @param cache - Platform cache adapter instance
-     * @example
-     * ```typescript
-     * // Clear all signatures when user logs out
-     * SignatureCache.clear(cache);
-     *
-     * // Clear before running tests
-     * beforeEach(() => {
-     *   SignatureCache.clear(cache);
-     * });
-     * ```
-     */
-    static clear(cache: VanaCacheAdapter): void;
-    private static getCacheKey;
-    /**
-     * Generate a deterministic hash of a message object for cache key generation
-     *
-     * @remarks
-     * Creates a cryptographically secure hash from complex objects including EIP-712 typed data.
-     * Uses SHA-256 for collision resistance and deterministic key generation.
-     * Handles BigInt serialization and sorts object keys for consistency.
-     *
-     * @param message - The message object to hash (typically EIP-712 typed data)
-     * @returns A hex string hash (SHA-256) suitable for cache keys
-     * @example
-     * ```typescript
-     * const typedData = {
-     *   domain: { name: 'Vana', version: '1' },
-     *   message: { nonce: 123n, grant: '...' }
-     * };
-     *
-     * const hash = SignatureCache.hashMessage(typedData);
-     * // Returns SHA-256 hash like: "a1b2c3d4e5f6..."
-     * ```
-     */
-    static hashMessage(message: object): string;
-    /**
-     * Deterministic JSON replacer that handles BigInt values and sorts object keys
-     * This ensures consistent cache key generation for EIP-712 typed data
-     *
-     * @param _key - The object key being serialized (unused)
-     * @param value - The value to serialize
-     * @returns The serialized value with sorted keys for objects
-     */
-    private static deterministicReplacer;
-}
-/**
- * Wrapper function to cache signature operations
- *
- * @param cache - The cache adapter to use for storage
- * @param walletAddress - The wallet address signing the message
- * @param typedData - The EIP-712 typed data being signed
- * @param signFn - Function that performs the actual signing
- * @param ttlHours - Cache TTL in hours (default 2)
- * @returns The signature (cached or newly generated)
- */
-declare function withSignatureCache(cache: VanaCacheAdapter, walletAddress: string, typedData: Record<string, unknown>, signFn: () => Promise<Hash>, ttlHours?: number): Promise<Hash>;
-
-export { SignatureCache, withSignatureCache };

package/dist/utils/signatureFormatter.d.cts

@@ -1,39 +0,0 @@
-import { Hash } from 'viem';
-
-/**
- * Formats a signature for Ethereum smart contract compatibility by adjusting the v-value.
- *
- * @remarks
- * This function ensures signature compatibility with Ethereum smart contracts by adjusting
- * the v-value component of ECDSA signatures. Some wallet implementations and signing methods
- * produce signatures with v-values in the range [0, 1], while Ethereum smart contracts
- * expect v-values in the range [27, 28] for proper signature verification.
- *
- * The function automatically detects signatures with low v-values and applies the standard
- * Ethereum offset (+27) to ensure compatibility. This is particularly important for gasless
- * transactions and EIP-712 signature verification in smart contracts.
- *
- * **Technical Details:**
- * - Ethereum signatures consist of r (32 bytes) + s (32 bytes) + v (1 byte) = 65 bytes total
- * - Valid v-values for Ethereum are 27 or 28 (or 0/1 + chain-specific offset for EIP-155)
- * - This function handles the common case where v ∈ [0, 1] needs adjustment to [27, 28]
- *
- * @param signature - The ECDSA signature hash to format (65 bytes as hex string)
- * @returns The formatted signature with correct v-value for Ethereum contract verification
- * @example
- * ```typescript
- * // Signature with v-value that needs adjustment
- * const rawSignature = "0x1234...5600"; // v = 0 (last byte)
- * const formatted = formatSignatureForContract(rawSignature);
- * // Result: "0x1234...561b" // v = 27 (0x1b)
- *
- * // Already properly formatted signature remains unchanged
- * const goodSignature = "0x1234...561b"; // v = 27
- * const unchanged = formatSignatureForContract(goodSignature);
- * // Result: "0x1234...561b" (no change needed)
- * ```
- * @category Cryptography
- */
-declare function formatSignatureForContract(signature: Hash): Hash;
-
-export { formatSignatureForContract };

package/dist/utils/transactionHelpers.d.cts

@@ -1,86 +0,0 @@
-import { Hash, Address } from 'viem';
-import { TransactionResult } from '../types/operations.cjs';
-import { Contract, Fn } from '../generated/event-types.cjs';
-import '../generated/server/server-exports.cjs';
-import '../generated/server/server.cjs';
-
-/**
- * Helper functions for creating typed transaction POJOs
- */
-
-/**
- * Creates a strongly-typed TransactionResult POJO.
- *
- * @remarks
- * This helper ensures all required fields are present and typed correctly,
- * reducing boilerplate and preventing mistakes.
- *
- * @param input - Transaction details
- * @param input.hash - Transaction hash
- * @param input.from - Transaction sender address
- * @param input.contract - Contract name
- * @param input.fn - Function name
- * @param input.chainId - Optional chain ID
- * @param input.value - Optional transaction value
- * @param input.nonce - Optional nonce
- * @param input.to - Optional recipient address
- * @returns Typed TransactionResult
- *
- * @example
- * ```typescript
- * return tx({
- *   hash,
- *   from: account.address,
- *   contract: "DataPortabilityPermissions",
- *   fn: "revokePermission",
- * });
- * ```
- */
-declare function tx<C extends Contract, F extends Fn<C>>(input: {
-    hash: Hash;
-    from: Address;
-    contract: C;
-    fn: F;
-    chainId?: number;
-    value?: bigint;
-    nonce?: number;
-    to?: Address;
-}): TransactionResult<C, F>;
-/**
- * Creates a transaction result with literal type inference.
- * Use this when you need TypeScript to preserve exact string literals.
- *
- * @param input - Transaction details
- * @param input.hash - Transaction hash
- * @param input.from - Transaction sender address
- * @param input.contract - Contract name
- * @param input.fn - Function name
- * @param input.chainId - Optional chain ID
- * @param input.value - Optional transaction value
- * @param input.nonce - Optional nonce
- * @param input.to - Optional recipient address
- * @returns Typed TransactionResult
- *
- * @example
- * ```typescript
- * const transaction = txLiteral({
- *   hash: '0x...',
- *   from: '0x...',
- *   contract: "DataPortabilityPermissions",
- *   fn: "revokePermission",
- * });
- * // TypeScript knows exactly: DataPortabilityPermissions + revokePermission
- * ```
- */
-declare function txLiteral<const C extends Contract, const F extends Fn<C>>(input: {
-    hash: Hash;
-    from: Address;
-    contract: C;
-    fn: F;
-    chainId?: number;
-    value?: bigint;
-    nonce?: number;
-    to?: Address;
-}): TransactionResult<C, F>;
-
-export { tx, txLiteral };

package/dist/utils/typedDataConverter.d.cts

@@ -1,13 +0,0 @@
-import { TypedDataDefinition } from 'viem';
-import { GenericTypedData } from '../types/permissions.cjs';
-
-/**
- * Converts a GenericTypedData object to a Viem-compatible TypedDataDefinition.
- * This function ensures type safety when passing typed data to viem's signTypedData method.
- *
- * @param typedData - The typed data object to convert
- * @returns A properly typed TypedDataDefinition for use with viem
- */
-declare function toViemTypedDataDefinition(typedData: GenericTypedData): TypedDataDefinition;
-
-export { toViemTypedDataDefinition };

package/dist/utils/urlResolver.d.cts

@@ -1,40 +0,0 @@
-/**
- * Universal URL resolver for the Vana SDK
- *
- * Handles fetching data from various protocols (IPFS, HTTP, Arweave, etc.)
- * in a consistent, reliable way.
- */
-/**
- * Error thrown when URL resolution fails
- */
-declare class UrlResolutionError extends Error {
-    readonly url: string;
-    readonly cause?: Error | undefined;
-    constructor(message: string, url: string, cause?: Error | undefined);
-}
-/**
- * Fetches and parses JSON data from any supported URL protocol
- *
- * @param url - The URL to fetch from (supports ipfs://, https://, http://, ar://)
- * @param downloadRelayer - Optional download relayer for CORS bypass
- * @param downloadRelayer.proxyDownload - Function to proxy downloads through application server
- * @returns Promise resolving to the parsed JSON data
- * @throws {UrlResolutionError} When the URL cannot be resolved or parsed
- *
- * @example
- * ```typescript
- * // Fetch from IPFS
- * const data = await fetchFromUrl("ipfs://QmXxx...");
- *
- * // Fetch from HTTPS
- * const data = await fetchFromUrl("https://example.com/data.json");
- *
- * // Handles protocol conversion internally
- * const schema = await fetchFromUrl(schemaDefinitionUrl);
- * ```
- */
-declare function fetchFromUrl(url: string, downloadRelayer?: {
-    proxyDownload: (url: string) => Promise<Blob>;
-}): Promise<unknown>;
-
-export { UrlResolutionError, fetchFromUrl };