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

package/dist/controllers/server.d.cts

@@ -1,243 +0,0 @@
-import { C as ControllerContext } from '../permissions-DNKPu_G0.cjs';
-import { InitPersonalServerParams, PersonalServerIdentity, CreateOperationParams } from '../types/personal.cjs';
-import { Operation, PollingOptions } from '../types/operations.cjs';
-import 'viem';
-import '../types/config.cjs';
-import '../types/chains.cjs';
-import '../types/storage.cjs';
-import '../types/permissions.cjs';
-import '../config/eventMappings.cjs';
-import '../generated/abi/index.cjs';
-import '../generated/abi/DataPortabilityPermissionsImplementation.cjs';
-import '../generated/abi/DataPortabilityServersImplementation.cjs';
-import '../generated/abi/DataPortabilityGranteesImplementation.cjs';
-import '../generated/abi/VanaEpochImplementation.cjs';
-import '../generated/abi/DLPRegistryImplementation.cjs';
-import '../generated/abi/DLPTreasuryImplementation.cjs';
-import '../generated/abi/DLPRewardDeployerTreasuryImplementation.cjs';
-import '../generated/abi/DLPPerformanceImplementation.cjs';
-import '../generated/abi/DLPRewardDeployerImplementation.cjs';
-import '../generated/abi/DLPRootImplementation.cjs';
-import '../generated/abi/DataLiquidityPoolImplementation.cjs';
-import '../generated/abi/DLPRegistryTreasuryImplementation.cjs';
-import '../storage/manager.cjs';
-import '../platform/interface.cjs';
-import '../generated/server/server-exports.cjs';
-import '../generated/server/server.cjs';
-
-/**
- * Manages interactions with Vana personal servers and identity infrastructure.
- *
- * @remarks
- * This controller handles communication with personal servers for data processing
- * and identity servers for public key derivation. It provides methods for posting
- * computation requests to personal servers, polling for results, and retrieving
- * cryptographic keys for secure data sharing. All server interactions use the
- * Replicate API infrastructure with proper authentication and error handling.
- *
- * **Server Identity System:**
- * Personal servers use deterministic key derivation: each user address maps to a specific server identity.
- * This enables secure communication without requiring servers to be online during key retrieval.
- *
- * **Method Selection:**
- * - `getIdentity()` retrieves server public keys and addresses for encryption setup
- * - `createOperation()` submits computation requests with signed permission verification
- * - `getOperation()` polls operation status and retrieves results when complete
- * - `cancelOperation()` stops running operations when cancellation is supported
- *
- * **Workflow Pattern:**
- * Typical flow: Get identity → Create operation → Poll status → Retrieve results
- *
- * @example
- * ```typescript
- * // Get a server's identity including public key for encryption
- * const identity = await vana.server.getIdentity({
- *   userAddress: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36"
- * });
- *
- * // Create an operation using a granted permission
- * const response = await vana.server.createOperation({
- *   permissionId: 123,
- * });
- *
- * // Poll for computation results
- * const result = await vana.server.getOperation(response.id);
- * ```
- * @category Server Management
- * @see {@link https://docs.vana.com/developer/personal-servers | Vana Personal Servers} for conceptual overview
- */
-declare class ServerController {
-    private readonly context;
-    constructor(context: ControllerContext);
-    private get personalServerBaseUrl();
-    /**
-     * Retrieves the cryptographic identity of a personal server.
-     *
-     * @remarks
-     * This method fetches the public key and metadata for a personal server,
-     * which is required for encrypting data before sharing with the server.
-     * The identity includes the server's public key, address, and operational
-     * details needed for secure communication. This information is cached
-     * by identity servers to enable offline key retrieval.
-     *
-     * @param request - Parameters containing the user address
-     * @param request.userAddress - The wallet address associated with the personal server
-     * @returns Promise resolving to the server's identity information
-     * @throws {NetworkError} When the identity service is unavailable or returns invalid data
-     * @throws {PersonalServerError} When server identity cannot be retrieved
-     * @example
-     * ```typescript
-     * // Get server identity for data encryption
-     * const identity = await vana.server.getIdentity({
-     *   userAddress: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36"
-     * });
-     *
-     * console.log(`Server: ${identity.name}`);
-     * console.log(`Address: ${identity.address}`);
-     * console.log(`Public Key: ${identity.public_key}`);
-     *
-     * // Use the public key for encrypting data to share with this server
-     * const encryptedData = await encryptWithWalletPublicKey(
-     *   userData,
-     *   identity.public_key
-     * );
-     * ```
-     */
-    getIdentity(request: InitPersonalServerParams): Promise<PersonalServerIdentity>;
-    /**
-     * Creates a server operation and returns its details as a plain object.
-     *
-     * @remarks
-     * This method submits a computation request to the personal server and returns
-     * an Operation object that can be serialized and passed across API boundaries.
-     * Use `waitForOperation()` to poll for completion.
-     *
-     * @param params - The operation request parameters
-     * @param params.permissionId - The permission ID authorizing this operation.
-     *   Obtain via `vana.permissions.getUserPermissionGrantsOnChain()`.
-     * @returns An Operation object containing the operation ID and status
-     * @throws {PersonalServerError} When the server request fails or parameters are invalid
-     * @throws {NetworkError} When personal server API communication fails
-     * @example
-     * ```typescript
-     * const operation = await vana.server.createOperation({
-     *   permissionId: 123
-     * });
-     * console.log(`Operation ID: ${operation.id}`);
-     *
-     * // Wait for completion
-     * const result = await vana.server.waitForOperation(operation.id);
-     * console.log("Result:", result.result);
-     * ```
-     */
-    createOperation<T = unknown>(params: CreateOperationParams): Promise<Operation<T>>;
-    /**
-     * Retrieves the current status and result of a server operation.
-     *
-     * @remarks
-     * Common status values: `starting`, `running`, `succeeded`, `failed`, `canceled`.
-     * When status is `succeeded`, the result field contains the operation output.
-     *
-     * @param operationId - The ID of the operation to query
-     * @returns The operation as a plain object containing status, result, and metadata
-     * @throws {NetworkError} When the API request fails or returns invalid data
-     * @example
-     * ```typescript
-     * const operation = await vana.server.getOperation(operationId);
-     * if (operation.status === 'succeeded') {
-     *   console.log('Result:', operation.result);
-     * }
-     * ```
-     */
-    getOperation<T = unknown>(operationId: string): Promise<Operation<T>>;
-    /**
-     * Waits for an operation to complete and returns the final result.
-     *
-     * @remarks
-     * This method polls the operation status at regular intervals until it
-     * reaches a terminal state (succeeded, failed, or canceled). Supports
-     * ergonomic overloads to accept either an Operation object or just the ID.
-     *
-     * @param opOrId - Either an Operation object or operation ID string
-     * @param options - Optional polling configuration
-     * @returns The completed operation with result or error
-     * @throws {PersonalServerError} When the operation fails or times out
-     * @example
-     * ```typescript
-     * // Using operation object
-     * const operation = await vana.server.createOperation({ permissionId: 123 });
-     * const completed = await vana.server.waitForOperation(operation);
-     *
-     * // Using just the ID
-     * const completed = await vana.server.waitForOperation("op_abc123");
-     *
-     * // With custom timeout
-     * const completed = await vana.server.waitForOperation(operation, {
-     *   timeout: 60000,
-     *   pollingInterval: 1000
-     * });
-     * ```
-     */
-    waitForOperation<T = unknown>(opOrId: Operation<T> | string, options?: PollingOptions): Promise<Operation<T>>;
-    /**
-     * Cancels a running operation on the personal server.
-     *
-     * @remarks
-     * This method attempts to cancel an operation that is currently processing
-     * on the personal server. The operation must be in a cancellable state
-     * (typically `starting` or `processing`). Not all operations support
-     * cancellation, and cancellation may not be immediate. The server will
-     * attempt to stop the operation and update its status to `canceled`.
-     *
-     * **Cancellation Behavior:**
-     * - Operations in `succeeded` or `failed` states cannot be canceled
-     * - Some long-running operations may take time to respond to cancellation
-     * - Always verify cancellation by polling the operation status afterward
-     *
-     * @param operationId - The unique identifier of the operation to cancel,
-     *   obtained from `createOperation()` response
-     * @returns Promise that resolves when the cancellation request is accepted
-     * @throws {PersonalServerError} When the operation cannot be canceled or doesn't exist.
-     *   Check operation status - it may already be completed or failed.
-     * @throws {NetworkError} When unable to reach the personal server API.
-     *   Verify server URL and network connectivity.
-     * @example
-     * ```typescript
-     * // Start a long-running operation
-     * const operation = await vana.server.createOperation({
-     *   permissionId: 123
-     * });
-     *
-     * // Cancel if needed
-     * try {
-     *   await vana.server.cancelOperation(operation.id);
-     *   console.log("Cancellation requested");
-     *
-     *   // Verify cancellation
-     *   const status = await vana.server.getOperation(operation.id);
-     *   if (status.status === "canceled") {
-     *     console.log("Operation successfully canceled");
-     *   }
-     * } catch (error) {
-     *   console.error("Failed to cancel:", error);
-     * }
-     * ```
-     */
-    cancelOperation(operationId: string): Promise<void>;
-    /**
-     * Makes the request to the personal server API.
-     *
-     * @param requestBody - The post request parameters to serialize
-     * @returns JSON string representation of the request data
-     */
-    private makeRequest;
-    /**
-     * Creates a signature for the request JSON.
-     *
-     * @param requestJson - The JSON string to sign
-     * @returns Promise resolving to the cryptographic signature
-     */
-    private createSignature;
-}
-
-export { ServerController };

package/dist/core/apiClient.d.cts

@@ -1,165 +0,0 @@
-import { RetryConfig, RateLimiterConfig, Middleware, GenericResponse } from '../types/generics.cjs';
-import 'viem';
-
-/**
- * Configuration for the generic API client
- */
-interface ApiClientConfig {
-    /** Base URL for all requests */
-    baseUrl?: string;
-    /** Default headers */
-    headers?: Record<string, string>;
-    /** Request timeout in milliseconds */
-    timeout?: number;
-    /** Retry configuration */
-    retry?: RetryConfig;
-    /** Rate limiting configuration */
-    rateLimit?: RateLimiterConfig;
-    /** Circuit breaker configuration */
-    circuitBreaker?: {
-        failureThreshold: number;
-        recoveryTimeout: number;
-        halfOpenMaxAttempts?: number;
-    };
-}
-/**
- * HTTP method types
- */
-type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
-/**
- * Request options for API calls
- */
-interface RequestOptions {
-    /** HTTP method */
-    method?: HttpMethod;
-    /** Request headers */
-    headers?: Record<string, string>;
-    /** Query parameters */
-    params?: Record<string, unknown>;
-    /** Request timeout */
-    timeout?: number;
-    /** Skip retry for this request */
-    skipRetry?: boolean;
-    /** Skip rate limiting for this request */
-    skipRateLimit?: boolean;
-}
-/**
- * Generic API client with middleware, retry, rate limiting, and circuit breaker support
- */
-declare class ApiClient {
-    private readonly config;
-    private readonly middleware;
-    private readonly rateLimiter?;
-    private readonly circuitBreaker?;
-    constructor(config?: ApiClientConfig);
-    /**
-     * Add middleware to the request pipeline
-     *
-     * @param middleware - The middleware function to add to the pipeline
-     */
-    use(middleware: Middleware): void;
-    /**
-     * Make a generic HTTP request
-     *
-     * @param url - The URL to make the request to
-     * @param options - Request options including method, headers, body, etc.
-     * @returns Promise resolving to the response data
-     */
-    request<TData = unknown>(url: string, options?: RequestOptions): Promise<GenericResponse<TData>>;
-    /**
-     * Make a GET request
-     *
-     * @param url - The URL to make the GET request to
-     * @param options - Request options (excluding method)
-     * @returns Promise resolving to the response data
-     */
-    get<TData = unknown>(url: string, options?: Omit<RequestOptions, "method">): Promise<GenericResponse<TData>>;
-    /**
-     * Make a POST request
-     *
-     * @param url - The URL to make the POST request to
-     * @param data - The data to send in the request body
-     * @param options - Request options (excluding method)
-     * @returns Promise resolving to the response data
-     */
-    post<TData = unknown>(url: string, data?: unknown, options?: Omit<RequestOptions, "method">): Promise<GenericResponse<TData>>;
-    /**
-     * Make a PUT request
-     *
-     * @param url - The URL to make the PUT request to
-     * @param data - The data to send in the request body
-     * @param options - Request options (excluding method)
-     * @returns Promise resolving to the response data
-     */
-    put<TData = unknown>(url: string, data?: unknown, options?: Omit<RequestOptions, "method">): Promise<GenericResponse<TData>>;
-    /**
-     * Make a DELETE request
-     *
-     * @param url - The URL to make the DELETE request to
-     * @param options - Request options (excluding method)
-     * @returns Promise resolving to the response data
-     */
-    delete<TData = unknown>(url: string, options?: Omit<RequestOptions, "method">): Promise<GenericResponse<TData>>;
-    /**
-     * Make a PATCH request
-     *
-     * @param url - The URL to make the PATCH request to
-     * @param data - The data to send in the request body
-     * @param options - Request options (excluding method)
-     * @returns Promise resolving to the response data
-     */
-    patch<TData = unknown>(url: string, data?: unknown, options?: Omit<RequestOptions, "method">): Promise<GenericResponse<TData>>;
-    /**
-     * Execute the actual HTTP request with middleware and retry
-     *
-     * @param request - The generic request object containing URL and options
-     * @returns Promise resolving to the generic response with data
-     */
-    private executeRequest;
-    /**
-     * Make the actual HTTP request using fetch API
-     *
-     * @param url - The URL to make the request to
-     * @param options - The request options including method, headers, body, etc.
-     * @returns Promise resolving to the generic response with data
-     */
-    private makeHttpRequest;
-    /**
-     * Build the full URL
-     *
-     * @param url - The URL or path to build the full URL from
-     * @returns The complete URL string
-     */
-    private buildUrl;
-    /**
-     * Build request options with defaults
-     *
-     * @param options - The request options to merge with defaults
-     * @returns The merged request options with defaults applied
-     */
-    private buildRequestOptions;
-    /**
-     * Get client statistics
-     *
-     * @returns Object containing client statistics and performance metrics
-     */
-    getStats(): {
-        rateLimiter: {
-            remaining: number;
-            resetTime: number;
-        } | null;
-        circuitBreaker: {
-            state: string;
-            failures: number;
-        } | null;
-        middleware: {
-            count: number;
-        };
-    };
-    /**
-     * Reset client state
-     */
-    reset(): void;
-}
-
-export { ApiClient, type ApiClientConfig, type HttpMethod, type RequestOptions };

package/dist/core/client.d.cts

@@ -1,92 +0,0 @@
-import { PublicClient, Chain, Account, WalletClient } from 'viem';
-import { chains } from '../config/chains.cjs';
-
-/**
- * Default starting block numbers for querying blockchain events and data per chain.
- *
- * @remarks
- * These block numbers represent the earliest deployment of Vana protocol contracts
- * on each network. Using these as starting points for event queries significantly
- * improves performance by avoiding unnecessary queries of blocks before the
- * protocol existed.
- *
- * - Moksha Testnet (14800): Block 732312 - DataRegistry deployment
- * - Vana Mainnet (1480): Block 758584 - DataRegistry deployment
- *
- * @category Blockchain
- */
-declare const defaultFromBlocks: Record<number, bigint>;
-/**
- * Gets the default starting block for a specific chain.
- *
- * @param chainId - The chain ID to get the default from block for
- * @returns The default starting block for the chain, or 0n if not configured
- * @category Blockchain
- */
-declare function getDefaultFromBlock(chainId: number): bigint;
-/**
- * Creates or retrieves a cached public client for blockchain read operations.
- *
- * @remarks
- * This function provides an optimized way to access blockchain data by maintaining
- * a cached client instance per chain. The client is used for reading contract state,
- * querying events, and other read-only blockchain operations. It automatically
- * handles HTTP transport configuration and chain switching.
- *
- * @param chainId - The chain ID to connect to (defaults to Moksha testnet)
- * @returns A public client configured for the specified chain with caching optimization
- * @throws {Error} When the specified chain ID is not supported by the SDK
- * @example
- * ```typescript
- * // Get client for default chain (Moksha testnet)
- * const client = createClient();
- *
- * // Get client for specific chain
- * const mainnetClient = createClient(14800);
- *
- * // Use client for blockchain reads
- * const blockNumber = await client.getBlockNumber();
- * ```
- * @category Blockchain
- */
-declare const createClient: (chainId?: keyof typeof chains) => PublicClient & {
-    chain: Chain;
-};
-/**
- * Creates a wallet client for blockchain transaction signing and submission.
- *
- * @remarks
- * This function creates a wallet client configured for transaction signing and
- * submission on the specified chain. Unlike the public client, wallet clients
- * are not cached and require an account for transaction signing. The client
- * handles HTTP transport configuration and provides access to wallet-specific
- * operations like signing transactions and messages.
- *
- * @param chainId - The chain ID to connect to (defaults to Moksha testnet)
- * @param account - Optional account for transaction signing (can be set later)
- * @returns A wallet client configured for the specified chain
- * @throws {Error} When the specified chain ID is not supported by the SDK
- * @example
- * ```typescript
- * import { privateKeyToAccount } from 'viem/accounts';
- *
- * // Create wallet client for default chain
- * const account = privateKeyToAccount('0x...');
- * const walletClient = createWalletClient(mokshaTestnet.id, account);
- *
- * // Use for transaction signing
- * const txHash = await walletClient.writeContract({
- *   address: contractAddress,
- *   abi: contractAbi,
- *   functionName: 'someFunction',
- *   args: []
- * });
- *
- * // Create without account (account can be set later)
- * const client = createWalletClient();
- * ```
- * @category Blockchain
- */
-declare const createWalletClient: (chainId?: keyof typeof chains, account?: Account) => WalletClient;
-
-export { createClient, createWalletClient, defaultFromBlocks, getDefaultFromBlock };

package/dist/core/generics.d.cts

@@ -1,120 +0,0 @@
-import { ControllerContext, Controller, GenericRequest, Middleware, GenericResponse, RetryConfig, RateLimiterConfig, Cache, Observable, Observer } from '../types/generics.cjs';
-import 'viem';
-
-/**
- * Base controller class with common functionality
- */
-declare abstract class BaseController<TContext extends ControllerContext = ControllerContext> implements Controller<TContext> {
-    readonly context: TContext;
-    constructor(context: TContext);
-    /**
-     * Execute a request with optional middleware pipeline
-     *
-     * @param request - The generic request object containing parameters and metadata
-     * @param handler - The function that processes the request parameters
-     * @param middleware - Optional array of middleware functions to apply
-     * @returns Promise resolving to a generic response object
-     */
-    protected executeRequest<TParams, TResponse>(request: GenericRequest<TParams>, handler: (params: TParams) => Promise<TResponse>, middleware?: Middleware[]): Promise<GenericResponse<TResponse>>;
-    /**
-     * Validate parameters with optional custom validator
-     *
-     * @param params - The parameters to validate
-     * @param validator - Optional function to validate parameter types
-     * @throws Error if validation fails, asserts type if successful
-     */
-    protected validateParams<T>(params: unknown, validator?: (params: unknown) => params is T): asserts params is T;
-}
-/**
- * Generic retry utility with exponential backoff
- */
-declare class RetryUtility {
-    private static delay;
-    static withRetry<T>(operation: () => Promise<T>, config: RetryConfig): Promise<T>;
-}
-/**
- * Generic rate limiter
- */
-declare class RateLimiter {
-    private config;
-    private requests;
-    constructor(config: RateLimiterConfig);
-    checkLimit(): Promise<boolean>;
-    waitForSlot(): Promise<void>;
-    getRemainingRequests(): number;
-    getResetTime(): number;
-}
-/**
- * Generic in-memory cache implementation
- */
-declare class MemoryCache<TKey = string, TValue = unknown> implements Cache<TKey, TValue> {
-    private cache;
-    get(key: TKey): Promise<TValue | undefined>;
-    set(key: TKey, value: TValue, ttl?: number): Promise<void>;
-    delete(key: TKey): Promise<boolean>;
-    clear(): Promise<void>;
-    has(key: TKey): Promise<boolean>;
-    size(): number;
-    keys(): TKey[];
-}
-/**
- * Generic event emitter implementation
- */
-declare class EventEmitter<TEvent = unknown> implements Observable<TEvent> {
-    private observers;
-    subscribe(observer: Observer<TEvent>): () => void;
-    unsubscribe(observer: Observer<TEvent>): void;
-    emit(event: TEvent): void;
-    getObserverCount(): number;
-    removeAllObservers(): void;
-}
-/**
- * Generic middleware pipeline
- */
-declare class MiddlewarePipeline {
-    private middleware;
-    use(middleware: Middleware<any, any>): void;
-    processRequest<TRequest>(request: TRequest): Promise<TRequest>;
-    processResponse<TResponse>(response: TResponse): Promise<TResponse>;
-    handleError<TRequest, TResponse>(error: Error, request: TRequest): Promise<TResponse | void>;
-    getMiddleware(): Middleware<any, any>[];
-    clear(): void;
-}
-/**
- * Generic async queue for managing concurrent operations
- */
-declare class AsyncQueue<T = unknown> {
-    private concurrency;
-    private queue;
-    private running;
-    constructor(concurrency?: number);
-    add<R>(operation: () => Promise<R>): Promise<R>;
-    private processQueue;
-    get pending(): number;
-    get active(): number;
-    get size(): number;
-    clear(): void;
-}
-/**
- * Generic circuit breaker pattern
- */
-declare class CircuitBreaker {
-    private config;
-    private state;
-    private failures;
-    private lastFailureTime;
-    private successes;
-    constructor(config: {
-        failureThreshold: number;
-        recoveryTimeout: number;
-        halfOpenMaxAttempts?: number;
-    });
-    execute<TResult>(operation: () => Promise<TResult>): Promise<TResult>;
-    private onSuccess;
-    private onFailure;
-    getState(): string;
-    getFailures(): number;
-    reset(): void;
-}
-
-export { AsyncQueue, BaseController, CircuitBreaker, EventEmitter, MemoryCache, MiddlewarePipeline, RateLimiter, RetryUtility };