@usearete/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,913 @@
+/**
+ * Wallet adapter interface for signing and sending transactions.
+ * This is framework-agnostic and can be implemented by any wallet provider.
+ */
+interface WalletAdapter {
+    /** The wallet's public key as a base58-encoded string */
+    publicKey: string;
+    /**
+     * Sign and send a transaction.
+     * @param transaction - The transaction to sign and send (can be raw bytes, a Transaction object, or an array of instructions)
+     * @returns The transaction signature
+     */
+    signAndSend: (transaction: unknown) => Promise<string>;
+}
+/**
+ * Wallet connection state
+ */
+type WalletState = 'disconnected' | 'connecting' | 'connected' | 'error';
+/**
+ * Options for wallet connection
+ */
+interface WalletConnectOptions {
+    /** Whether to use the default wallet selection UI if multiple wallets are available */
+    useDefaultSelector?: boolean;
+    /** Specific wallet provider to use */
+    provider?: string;
+}
+
+/**
+ * Categories of accounts in an instruction.
+ * - `signer`: Must sign the transaction (e.g., user wallet)
+ * - `known`: Program-derived addresses with fixed known addresses (e.g., System Program)
+ * - `pda`: Program-derived addresses computed from seeds
+ * - `userProvided`: Must be provided by the caller (e.g., mint, bonding curve)
+ */
+type AccountCategory = 'signer' | 'known' | 'pda' | 'userProvided';
+/**
+ * Metadata for a single account in an instruction.
+ */
+interface AccountMeta {
+    /** Account name (e.g., "user", "mint") */
+    name: string;
+    /** Whether this account must sign the transaction */
+    isSigner: boolean;
+    /** Whether this account is writable */
+    isWritable: boolean;
+    /** Category of this account */
+    category: AccountCategory;
+    /** Fixed address for "known" accounts (e.g., "11111111111111111111111111111111") */
+    knownAddress?: string;
+    /** PDA configuration for "pda" accounts */
+    pdaConfig?: PdaConfig;
+    /** Whether this account is optional */
+    isOptional?: boolean;
+}
+/**
+ * Configuration for PDA (Program-Derived Address) derivation.
+ */
+interface PdaConfig {
+    /** Program ID that owns this PDA (defaults to instruction's programId) */
+    programId?: string;
+    /** Seed definitions for PDA derivation */
+    seeds: PdaSeed[];
+}
+/**
+ * Single seed in a PDA derivation.
+ */
+type PdaSeed = {
+    type: 'literal';
+    value: string;
+} | {
+    type: 'argRef';
+    argName: string;
+} | {
+    type: 'accountRef';
+    accountName: string;
+};
+/**
+ * Resolved account with its final address.
+ */
+interface ResolvedAccount {
+    /** Account name */
+    name: string;
+    /** The resolved public key address */
+    address: string;
+    /** Whether this account must sign */
+    isSigner: boolean;
+    /** Whether this account is writable */
+    isWritable: boolean;
+}
+/**
+ * Result of account resolution.
+ */
+interface AccountResolutionResult {
+    /** All resolved accounts in order */
+    accounts: ResolvedAccount[];
+    /** Accounts that need to be provided by the user */
+    missingUserAccounts: string[];
+}
+/**
+ * Options for account resolution.
+ */
+interface AccountResolutionOptions {
+    /** User-provided account addresses */
+    accounts?: Record<string, string>;
+    /** Wallet adapter for signer accounts */
+    wallet?: WalletAdapter;
+    /** Program ID for PDA derivation (required if any PDAs exist) */
+    programId?: string;
+}
+/**
+ * Resolves instruction accounts by categorizing and deriving addresses.
+ *
+ * Resolution order:
+ * 1. Non-PDA accounts (signer, known, userProvided) are resolved first
+ * 2. PDA accounts are resolved in dependency order (accounts they reference come first)
+ *
+ * @param accountMetas - Account metadata from the instruction definition
+ * @param args - Instruction arguments (used for PDA derivation with argRef seeds)
+ * @param options - Resolution options including wallet, user-provided accounts, and programId
+ * @returns Resolved accounts and any missing required accounts
+ */
+declare function resolveAccounts(accountMetas: AccountMeta[], args: Record<string, unknown>, options: AccountResolutionOptions): AccountResolutionResult;
+/**
+ * Validates that all required accounts are present.
+ *
+ * @param result - Account resolution result
+ * @throws Error if any required accounts are missing
+ */
+declare function validateAccountResolution(result: AccountResolutionResult): void;
+
+/**
+ * PDA (Program Derived Address) derivation utilities.
+ *
+ * Implements Solana's PDA derivation algorithm without depending on @solana/web3.js.
+ */
+/**
+ * Decode base58 string to Uint8Array.
+ */
+declare function decodeBase58(str: string): Uint8Array;
+/**
+ * Encode Uint8Array to base58 string.
+ */
+declare function encodeBase58(bytes: Uint8Array): string;
+/**
+ * Derives a Program-Derived Address (PDA) from seeds and program ID.
+ *
+ * Algorithm:
+ * 1. For bump = 255 down to 0:
+ *    a. Concatenate: seeds + [bump] + programId + "ProgramDerivedAddress"
+ *    b. SHA-256 hash the concatenation
+ *    c. If result is off the ed25519 curve, return it
+ * 2. If no valid PDA found after 256 attempts, throw error
+ *
+ * @param seeds - Array of seed buffers (max 32 bytes each, max 16 seeds)
+ * @param programId - The program ID (base58 string)
+ * @returns Tuple of [derivedAddress (base58), bumpSeed]
+ */
+declare function findProgramAddress(seeds: Uint8Array[], programId: string): Promise<[string, number]>;
+/**
+ * Synchronous version of findProgramAddress.
+ * Uses synchronous SHA-256 (Node.js crypto module).
+ */
+declare function findProgramAddressSync(seeds: Uint8Array[], programId: string): [string, number];
+/**
+ * Creates a seed buffer from various input types.
+ *
+ * @param value - The value to convert to a seed
+ * @returns Uint8Array suitable for PDA derivation
+ */
+declare function createSeed(value: string | Uint8Array | bigint | number): Uint8Array;
+/**
+ * Creates a public key seed from a base58-encoded address.
+ *
+ * @param address - Base58-encoded public key
+ * @returns 32-byte Uint8Array
+ */
+declare function createPublicKeySeed(address: string): Uint8Array;
+
+/**
+ * Borsh-compatible instruction data serializer.
+ *
+ * This module handles serializing instruction arguments into the binary format
+ * expected by Solana programs using Borsh serialization.
+ */
+/**
+ * Instruction argument schema for serialization.
+ */
+interface ArgSchema {
+    /** Argument name */
+    name: string;
+    /** Argument type */
+    type: ArgType;
+}
+/**
+ * Supported argument types for Borsh serialization.
+ */
+type ArgType = 'u8' | 'u16' | 'u32' | 'u64' | 'u128' | 'i8' | 'i16' | 'i32' | 'i64' | 'i128' | 'bool' | 'string' | 'pubkey' | {
+    vec: ArgType;
+} | {
+    option: ArgType;
+} | {
+    array: [ArgType, number];
+};
+/**
+ * Serializes instruction arguments into a Buffer using Borsh encoding.
+ *
+ * @param discriminator - The 8-byte instruction discriminator
+ * @param args - Arguments to serialize
+ * @param schema - Schema defining argument types
+ * @returns Serialized instruction data
+ */
+declare function serializeInstructionData(discriminator: Uint8Array, args: Record<string, unknown>, schema: ArgSchema[]): Buffer;
+
+/**
+ * Confirmation level for transaction processing.
+ * - `processed`: Transaction processed but not confirmed
+ * - `confirmed`: Transaction confirmed by cluster
+ * - `finalized`: Transaction finalized (recommended for production)
+ */
+type ConfirmationLevel = 'processed' | 'confirmed' | 'finalized';
+/**
+ * Options for executing an instruction.
+ */
+interface ExecuteOptions {
+    /** Wallet adapter for signing */
+    wallet?: WalletAdapter;
+    /** User-provided account addresses */
+    accounts?: Record<string, string>;
+    /** Confirmation level to wait for */
+    confirmationLevel?: ConfirmationLevel;
+    /** Maximum time to wait for confirmation (ms) */
+    timeout?: number;
+    /** Refresh view after transaction completes */
+    refresh?: {
+        view: string;
+        key?: string;
+    }[];
+}
+/**
+ * Result of a successful instruction execution.
+ */
+interface ExecutionResult {
+    /** Transaction signature */
+    signature: string;
+    /** Confirmation level achieved */
+    confirmationLevel: ConfirmationLevel;
+    /** Slot when transaction was processed */
+    slot: number;
+    /** Error code if transaction failed */
+    error?: string;
+}
+/**
+ * Waits for transaction confirmation.
+ *
+ * @param signature - Transaction signature
+ * @param level - Desired confirmation level
+ * @param timeout - Maximum wait time in milliseconds
+ * @returns Confirmation result
+ */
+declare function waitForConfirmation(signature: string, level?: ConfirmationLevel, timeout?: number): Promise<{
+    level: ConfirmationLevel;
+    slot: number;
+}>;
+
+/**
+ * Parses and handles instruction errors.
+ */
+/**
+ * Custom error from a Solana program.
+ */
+interface ProgramError {
+    /** Error code */
+    code: number;
+    /** Error name */
+    name: string;
+    /** Error message */
+    message: string;
+}
+/**
+ * Error metadata from IDL.
+ */
+interface ErrorMetadata {
+    code: number;
+    name: string;
+    msg: string;
+}
+/**
+ * Parses an error returned from a Solana transaction.
+ *
+ * @param error - The error from the transaction
+ * @param errorMetadata - Error definitions from the IDL
+ * @returns Parsed program error or null if not a program error
+ */
+declare function parseInstructionError(error: unknown, errorMetadata: ErrorMetadata[]): ProgramError | null;
+/**
+ * Formats an error for display.
+ *
+ * @param error - The program error
+ * @returns Human-readable error message
+ */
+declare function formatProgramError(error: ProgramError): string;
+
+/**
+ * Resolved accounts map passed to the instruction builder.
+ * Keys are account names, values are base58 addresses.
+ */
+type ResolvedAccounts = Record<string, string>;
+/**
+ * The instruction object returned by the handler's build function.
+ * This is a framework-agnostic representation that can be converted
+ * to @solana/web3.js TransactionInstruction.
+ */
+interface BuiltInstruction {
+    /** Program ID (base58) */
+    programId: string;
+    /** Account keys in order */
+    keys: Array<{
+        pubkey: string;
+        isSigner: boolean;
+        isWritable: boolean;
+    }>;
+    /** Serialized instruction data */
+    data: Uint8Array;
+}
+/**
+ * Instruction handler from the generated stack SDK.
+ * The build() function is generated code that handles serialization.
+ */
+interface InstructionHandler {
+    /**
+     * Build the instruction with resolved accounts.
+     * This is generated code - serialization logic lives here.
+     */
+    build(args: Record<string, unknown>, accounts: ResolvedAccounts): BuiltInstruction;
+    /** Account metadata - used by core SDK for resolution */
+    accounts: AccountMeta[];
+    /** Error definitions - used by core SDK for error parsing */
+    errors: ErrorMetadata[];
+    /** Program ID for this instruction (used for PDA derivation) */
+    programId?: string;
+}
+/**
+ * @deprecated Use InstructionHandler instead. Will be removed in next major version.
+ * Legacy instruction definition for backwards compatibility.
+ */
+interface InstructionDefinition {
+    /** Instruction name */
+    name: string;
+    /** Program ID (base58) */
+    programId: string;
+    /** 8-byte discriminator */
+    discriminator: Uint8Array;
+    /** Account metadata */
+    accounts: AccountMeta[];
+    /** Argument schema for serialization */
+    argsSchema: ArgSchema[];
+    /** Error definitions */
+    errors: ErrorMetadata[];
+}
+/**
+ * Executes an instruction handler with the given arguments and options.
+ *
+ * This is the main function for executing Solana instructions. It handles:
+ * 1. Account resolution (signer, PDA, user-provided)
+ * 2. Calling the generated build() function
+ * 3. Transaction signing and sending
+ * 4. Confirmation waiting
+ *
+ * @param handler - Instruction handler from generated SDK
+ * @param args - Instruction arguments
+ * @param options - Execution options
+ * @returns Execution result with signature
+ */
+declare function executeInstruction(handler: InstructionHandler, args: Record<string, unknown>, options?: ExecuteOptions): Promise<ExecutionResult>;
+/**
+ * Creates an instruction executor bound to a specific wallet.
+ *
+ * @param wallet - Wallet adapter
+ * @returns Bound executor function
+ */
+declare function createInstructionExecutor(wallet: WalletAdapter): {
+    execute: (handler: InstructionHandler, args: Record<string, unknown>, options?: Omit<ExecuteOptions, "wallet">) => Promise<ExecutionResult>;
+};
+
+type SeedDef = {
+    type: 'literal';
+    value: string;
+} | {
+    type: 'bytes';
+    value: Uint8Array;
+} | {
+    type: 'argRef';
+    argName: string;
+    argType?: string;
+} | {
+    type: 'accountRef';
+    accountName: string;
+};
+interface PdaDeriveContext {
+    accounts?: Record<string, string>;
+    args?: Record<string, unknown>;
+    programId?: string;
+}
+interface PdaFactory {
+    readonly seeds: readonly SeedDef[];
+    readonly programId: string;
+    program(programId: string): PdaFactory;
+    derive(context: PdaDeriveContext): Promise<string>;
+    deriveSync(context: PdaDeriveContext): string;
+}
+declare function literal(value: string): SeedDef;
+declare function account(name: string): SeedDef;
+declare function arg(name: string, type?: string): SeedDef;
+declare function bytes(value: Uint8Array): SeedDef;
+declare function pda(programId: string, ...seeds: SeedDef[]): PdaFactory;
+type ProgramPdas<T extends Record<string, PdaFactory>> = T;
+declare function createProgramPdas<T extends Record<string, PdaFactory>>(pdas: T): ProgramPdas<T>;
+
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error';
+type Update<T> = {
+    type: 'upsert';
+    key: string;
+    data: T;
+} | {
+    type: 'patch';
+    key: string;
+    data: Partial<T>;
+} | {
+    type: 'delete';
+    key: string;
+};
+type RichUpdate<T> = {
+    type: 'created';
+    key: string;
+    data: T;
+} | {
+    type: 'updated';
+    key: string;
+    before: T;
+    after: T;
+    patch?: unknown;
+} | {
+    type: 'deleted';
+    key: string;
+    lastKnown?: T;
+};
+interface ViewDef<T, TMode extends 'state' | 'list'> {
+    readonly mode: TMode;
+    readonly view: string;
+    readonly _entity?: T;
+}
+interface StackDefinition {
+    readonly name: string;
+    readonly url: string;
+    readonly views: Record<string, ViewGroup>;
+    readonly schemas?: Record<string, Schema<unknown>>;
+    instructions?: Record<string, InstructionHandler>;
+}
+interface ViewGroup {
+    state?: ViewDef<unknown, 'state'>;
+    list?: ViewDef<unknown, 'list'>;
+}
+interface Subscription {
+    view: string;
+    key?: string;
+    partition?: string;
+    filters?: Record<string, string>;
+    take?: number;
+    skip?: number;
+    /** Whether to include initial snapshot (defaults to true for backward compatibility) */
+    withSnapshot?: boolean;
+    /** Cursor for resuming from a specific point (_seq value) */
+    after?: string;
+    /** Maximum number of entities to include in snapshot (pagination hint) */
+    snapshotLimit?: number;
+}
+type SchemaResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: unknown;
+};
+interface Schema<T> {
+    safeParse: (input: unknown) => SchemaResult<T>;
+}
+interface WatchOptions<TSchema = unknown> {
+    take?: number;
+    skip?: number;
+    filters?: Record<string, string>;
+    schema?: Schema<TSchema>;
+    /** Whether to include initial snapshot (defaults to true) */
+    withSnapshot?: boolean;
+    /** Cursor for resuming from a specific point (_seq value) */
+    after?: string;
+    /** Maximum number of entities to include in snapshot */
+    snapshotLimit?: number;
+}
+interface AreteOptions<TStack extends StackDefinition> {
+    stack: TStack;
+    autoReconnect?: boolean;
+    reconnectIntervals?: number[];
+    maxReconnectAttempts?: number;
+    validateFrames?: boolean;
+}
+declare const DEFAULT_MAX_ENTRIES_PER_VIEW = 10000;
+interface AuthTokenResult {
+    token: string;
+    expiresAt?: number;
+    expires_at?: number;
+}
+interface WebSocketFactoryInit {
+    headers?: Record<string, string>;
+}
+/**
+ * Authentication configuration for Arete connections
+ */
+interface AuthConfig {
+    /** Custom token provider function - called before each connection and during refresh */
+    getToken?: () => Promise<string | AuthTokenResult>;
+    /** Arete Cloud token endpoint URL */
+    tokenEndpoint?: string;
+    /** Publishable key for Arete Cloud */
+    publishableKey?: string;
+    /** Pre-minted static token (for server-side use) */
+    token?: string;
+    /** How the websocket token is sent to the server */
+    tokenTransport?: 'query' | 'bearer';
+    /** Custom websocket factory for non-browser environments */
+    websocketFactory?: (url: string, init?: WebSocketFactoryInit) => WebSocket;
+    /** Additional headers sent to the token endpoint */
+    tokenEndpointHeaders?: Record<string, string>;
+    /** Credentials mode for token endpoint fetches */
+    tokenEndpointCredentials?: RequestCredentials;
+}
+interface AreteConfig {
+    websocketUrl?: string;
+    reconnectIntervals?: number[];
+    maxReconnectAttempts?: number;
+    initialSubscriptions?: Subscription[];
+    maxEntriesPerView?: number | null;
+    /** Authentication configuration */
+    auth?: AuthConfig;
+}
+interface SocketIssue {
+    error: string;
+    message: string;
+    code: AuthErrorCode;
+    retryable: boolean;
+    retryAfter?: number;
+    suggestedAction?: string;
+    docsUrl?: string;
+    fatal: boolean;
+}
+declare const DEFAULT_CONFIG: Required<Pick<AreteConfig, 'reconnectIntervals' | 'maxReconnectAttempts' | 'maxEntriesPerView'>>;
+/**
+ * Machine-readable error codes for authentication and rate limiting failures
+ *
+ * These codes match the Rust AuthErrorCode enum for cross-platform consistency.
+ */
+type AuthErrorCode = 'TOKEN_MISSING' | 'TOKEN_EXPIRED' | 'TOKEN_INVALID_SIGNATURE' | 'TOKEN_INVALID_FORMAT' | 'TOKEN_INVALID_ISSUER' | 'TOKEN_INVALID_AUDIENCE' | 'TOKEN_MISSING_CLAIM' | 'TOKEN_KEY_NOT_FOUND' | 'ORIGIN_MISMATCH' | 'ORIGIN_REQUIRED' | 'ORIGIN_NOT_ALLOWED' | 'AUTH_REQUIRED' | 'MISSING_AUTHORIZATION_HEADER' | 'INVALID_AUTHORIZATION_FORMAT' | 'INVALID_API_KEY' | 'EXPIRED_API_KEY' | 'USER_NOT_FOUND' | 'SECRET_KEY_REQUIRED' | 'DEPLOYMENT_ACCESS_DENIED' | 'RATE_LIMIT_EXCEEDED' | 'WEBSOCKET_SESSION_RATE_LIMIT_EXCEEDED' | 'CONNECTION_LIMIT_EXCEEDED' | 'SUBSCRIPTION_LIMIT_EXCEEDED' | 'SNAPSHOT_LIMIT_EXCEEDED' | 'EGRESS_LIMIT_EXCEEDED' | 'QUOTA_EXCEEDED' | 'INVALID_STATIC_TOKEN' | 'INTERNAL_ERROR';
+declare class AreteError extends Error {
+    code: string | AuthErrorCode;
+    details?: unknown | undefined;
+    constructor(message: string, code: string | AuthErrorCode, details?: unknown | undefined);
+}
+type TypedViews<TViews extends StackDefinition['views']> = {
+    [K in keyof TViews]: TypedViewGroup<TViews[K]>;
+};
+type TypedViewGroup<TGroup> = {
+    [K in keyof TGroup]: TGroup[K] extends ViewDef<infer T, 'state'> ? TypedStateView<T> : TGroup[K] extends ViewDef<infer T, 'list'> ? TypedListView<T> : never;
+};
+interface TypedStateView<T> {
+    use<TSchema = T>(key: string, options?: WatchOptions<TSchema>): AsyncIterable<TSchema>;
+    watch(key: string, options?: WatchOptions): AsyncIterable<Update<T>>;
+    watchRich(key: string, options?: WatchOptions): AsyncIterable<RichUpdate<T>>;
+    get(key: string): Promise<T | null>;
+    getSync(key: string): T | null | undefined;
+}
+interface TypedListView<T> {
+    use<TSchema = T>(options?: WatchOptions<TSchema>): AsyncIterable<TSchema>;
+    watch(options?: WatchOptions): AsyncIterable<Update<T>>;
+    watchRich(options?: WatchOptions): AsyncIterable<RichUpdate<T>>;
+    get(): Promise<T[]>;
+    getSync(): T[] | undefined;
+}
+type SubscribeCallback<T> = (update: Update<T>) => void;
+type UnsubscribeFn = () => void;
+type ConnectionStateCallback = (state: ConnectionState, error?: string) => void;
+type SocketIssueCallback = (issue: SocketIssue) => void;
+
+type FrameMode = 'state' | 'append' | 'list';
+type FrameOp = 'create' | 'upsert' | 'patch' | 'delete' | 'snapshot' | 'subscribed';
+type SortOrder = 'asc' | 'desc';
+interface SortConfig {
+    field: string[];
+    order: SortOrder;
+}
+interface SubscribedFrame {
+    op: 'subscribed';
+    view: string;
+    mode: FrameMode;
+    sort?: SortConfig;
+}
+interface EntityFrame<T = unknown> {
+    mode: FrameMode;
+    entity: string;
+    op: FrameOp;
+    key: string;
+    data: T;
+    append?: string[];
+    /** Sequence cursor for ordering and resume capability */
+    seq?: string;
+}
+interface SnapshotEntity<T = unknown> {
+    key: string;
+    data: T;
+}
+interface SnapshotFrame<T = unknown> {
+    mode: FrameMode;
+    entity: string;
+    op: 'snapshot';
+    data: SnapshotEntity<T>[];
+    /** Indicates if this is the final snapshot batch. When false, more batches will follow. */
+    complete?: boolean;
+}
+type Frame<T = unknown> = EntityFrame<T> | SnapshotFrame<T> | SubscribedFrame;
+declare function isSnapshotFrame<T>(frame: Frame<T>): frame is SnapshotFrame<T>;
+declare function isSubscribedFrame(frame: Frame): frame is SubscribedFrame;
+declare function isEntityFrame<T>(frame: Frame<T>): frame is EntityFrame<T>;
+declare function parseFrame(data: ArrayBuffer | string): Frame;
+declare function parseFrameFromBlob(blob: Blob): Promise<Frame>;
+declare function isValidFrame(frame: unknown): frame is Frame;
+
+type FrameHandler = <T>(frame: Frame<T>) => void;
+declare class ConnectionManager {
+    private ws;
+    private websocketUrl;
+    private reconnectIntervals;
+    private maxReconnectAttempts;
+    private reconnectAttempts;
+    private reconnectTimeout;
+    private pingInterval;
+    private tokenRefreshTimeout;
+    private tokenRefreshInFlight;
+    private currentState;
+    private subscriptionQueue;
+    private activeSubscriptions;
+    private frameHandlers;
+    private stateHandlers;
+    private socketIssueHandlers;
+    private authConfig?;
+    private currentToken?;
+    private tokenExpiry?;
+    private readonly hostedAreteUrl;
+    private reconnectForTokenRefresh;
+    constructor(config: AreteConfig);
+    private getTokenEndpoint;
+    private getAuthStrategy;
+    private hasRefreshableAuth;
+    private updateTokenState;
+    private clearTokenState;
+    private getOrRefreshToken;
+    private createTokenEndpointRequestBody;
+    private fetchTokenFromEndpoint;
+    private isTokenExpired;
+    private scheduleTokenRefresh;
+    private clearTokenRefreshTimeout;
+    private refreshTokenInBackground;
+    private sendInBandAuthRefresh;
+    private handleRefreshAuthResponse;
+    private handleSocketIssueMessage;
+    private rotateConnectionForTokenRefresh;
+    private buildAuthUrl;
+    private createWebSocket;
+    getState(): ConnectionState;
+    onFrame(handler: FrameHandler): () => void;
+    onStateChange(handler: ConnectionStateCallback): () => void;
+    onSocketIssue(handler: SocketIssueCallback): () => void;
+    private notifySocketIssue;
+    connect(): Promise<void>;
+    disconnect(): void;
+    subscribe(subscription: Subscription): void;
+    unsubscribe(view: string, key?: string): void;
+    isConnected(): boolean;
+    private makeSubKey;
+    private flushSubscriptionQueue;
+    private resubscribeActive;
+    private updateState;
+    private notifyFrameHandlers;
+    private handleReconnect;
+    private clearReconnectTimeout;
+    private startPingInterval;
+    private stopPingInterval;
+}
+
+type UpdateCallback<T = unknown> = (viewPath: string, key: string, update: Update<T>) => void;
+type RichUpdateCallback$1<T = unknown> = (viewPath: string, key: string, update: RichUpdate<T>) => void;
+interface StorageAdapterConfig {
+    maxEntriesPerView?: number | null;
+}
+interface ViewSortConfig {
+    sort?: SortConfig;
+}
+/**
+ * Storage adapter interface for Arete entity storage.
+ * Implement this to integrate with Zustand, Pinia, Svelte stores, Redux, IndexedDB, etc.
+ */
+interface StorageAdapter {
+    get<T>(viewPath: string, key: string): T | null;
+    getAll<T>(viewPath: string): T[];
+    getAllSync<T>(viewPath: string): T[] | undefined;
+    getSync<T>(viewPath: string, key: string): T | null | undefined;
+    has(viewPath: string, key: string): boolean;
+    keys(viewPath: string): string[];
+    size(viewPath: string): number;
+    set<T>(viewPath: string, key: string, data: T): void;
+    delete(viewPath: string, key: string): void;
+    clear(viewPath?: string): void;
+    evictOldest?(viewPath: string): string | undefined;
+    setViewConfig?(viewPath: string, config: ViewSortConfig): void;
+    getViewConfig?(viewPath: string): ViewSortConfig | undefined;
+    onUpdate(callback: UpdateCallback): () => void;
+    onRichUpdate(callback: RichUpdateCallback$1): () => void;
+    notifyUpdate<T>(viewPath: string, key: string, update: Update<T>): void;
+    notifyRichUpdate<T>(viewPath: string, key: string, update: RichUpdate<T>): void;
+}
+
+declare class SubscriptionRegistry {
+    private subscriptions;
+    private connection;
+    constructor(connection: ConnectionManager);
+    subscribe(subscription: Subscription): UnsubscribeFn;
+    unsubscribe(subscription: Subscription): void;
+    getRefCount(subscription: Subscription): number;
+    getActiveSubscriptions(): Subscription[];
+    clear(): void;
+    private makeSubKey;
+}
+
+interface ConnectOptions {
+    url?: string;
+    storage?: StorageAdapter;
+    maxEntriesPerView?: number | null;
+    autoReconnect?: boolean;
+    reconnectIntervals?: number[];
+    maxReconnectAttempts?: number;
+    flushIntervalMs?: number;
+    validateFrames?: boolean;
+    /** Authentication configuration */
+    auth?: AuthConfig;
+}
+/** @deprecated Use ConnectOptions instead */
+interface AreteOptionsWithStorage<TStack extends StackDefinition> extends AreteOptions<TStack> {
+    storage?: StorageAdapter;
+    maxEntriesPerView?: number | null;
+    flushIntervalMs?: number;
+    auth?: AuthConfig;
+}
+interface InstructionExecutorOptions extends Omit<ExecuteOptions, 'wallet'> {
+    wallet: WalletAdapter;
+}
+type InstructionExecutor = (args: Record<string, unknown>, options: InstructionExecutorOptions) => Promise<ExecutionResult>;
+type InstructionsInterface<TInstructions extends Record<string, InstructionHandler> | undefined> = TInstructions extends Record<string, InstructionHandler> ? {
+    [K in keyof TInstructions]: InstructionExecutor;
+} : {};
+declare class Arete<TStack extends StackDefinition> {
+    private readonly connection;
+    private readonly storage;
+    private readonly processor;
+    private readonly subscriptionRegistry;
+    private readonly _views;
+    private readonly stack;
+    private readonly _instructions;
+    private constructor();
+    private buildInstructions;
+    static connect<T extends StackDefinition>(stack: T, options?: ConnectOptions): Promise<Arete<T>>;
+    get views(): TypedViews<TStack['views']>;
+    get instructions(): InstructionsInterface<TStack['instructions']>;
+    get connectionState(): ConnectionState;
+    get stackName(): string;
+    get store(): StorageAdapter;
+    onConnectionStateChange(callback: ConnectionStateCallback): UnsubscribeFn;
+    onFrame(callback: (frame: Frame) => void): UnsubscribeFn;
+    onSocketIssue(callback: SocketIssueCallback): UnsubscribeFn;
+    connect(): Promise<void>;
+    disconnect(): void;
+    isConnected(): boolean;
+    clearStore(): void;
+    getStore(): StorageAdapter;
+    getConnection(): ConnectionManager;
+    getSubscriptionRegistry(): SubscriptionRegistry;
+}
+
+interface FrameProcessorConfig {
+    maxEntriesPerView?: number | null;
+    /**
+     * Interval in milliseconds to buffer frames before flushing to storage.
+     * Set to 0 for immediate processing (no buffering).
+     * Default: 0 (immediate)
+     *
+     * For React applications, 16ms (one frame at 60fps) is recommended to
+     * reduce unnecessary re-renders during high-frequency updates.
+     */
+    flushIntervalMs?: number;
+    schemas?: Record<string, Schema<unknown>>;
+}
+declare class FrameProcessor {
+    private storage;
+    private maxEntriesPerView;
+    private flushIntervalMs;
+    private schemas?;
+    private pendingUpdates;
+    private flushTimer;
+    private isProcessing;
+    constructor(storage: StorageAdapter, config?: FrameProcessorConfig);
+    private getSchema;
+    private validateEntity;
+    handleFrame<T>(frame: Frame<T>): void;
+    /**
+     * Immediately flush all pending updates.
+     * Useful for ensuring all updates are processed before reading state.
+     */
+    flush(): void;
+    /**
+     * Clean up any pending timers. Call when disposing the processor.
+     */
+    dispose(): void;
+    private scheduleFlush;
+    private flushPendingUpdates;
+    private processFrame;
+    private processFrameWithoutEnforce;
+    private handleSubscribedFrame;
+    private handleSnapshotFrame;
+    private handleSnapshotFrameWithoutEnforce;
+    private handleEntityFrame;
+    private handleEntityFrameWithoutEnforce;
+    private emitRichUpdate;
+    private enforceMaxEntries;
+}
+
+interface EntityStoreConfig {
+    maxEntriesPerView?: number | null;
+}
+interface ViewConfig {
+    sort?: SortConfig;
+}
+type EntityUpdateCallback = (viewPath: string, key: string, update: Update<unknown>) => void;
+type RichUpdateCallback = (viewPath: string, key: string, update: RichUpdate<unknown>) => void;
+declare class EntityStore {
+    private views;
+    private viewConfigs;
+    private updateCallbacks;
+    private richUpdateCallbacks;
+    private maxEntriesPerView;
+    constructor(config?: EntityStoreConfig);
+    private enforceMaxEntries;
+    handleFrame<T>(frame: Frame<T>): void;
+    private handleSubscribedFrame;
+    private handleSnapshotFrame;
+    private handleEntityFrame;
+    getAll<T>(viewPath: string): T[];
+    get<T>(viewPath: string, key: string): T | null;
+    getAllSync<T>(viewPath: string): T[] | undefined;
+    getSync<T>(viewPath: string, key: string): T | null | undefined;
+    keys(viewPath: string): string[];
+    size(viewPath: string): number;
+    clear(): void;
+    clearView(viewPath: string): void;
+    getViewConfig(viewPath: string): ViewConfig | undefined;
+    setViewConfig(viewPath: string, config: ViewConfig): void;
+    onUpdate(callback: EntityUpdateCallback): UnsubscribeFn;
+    onRichUpdate(callback: RichUpdateCallback): UnsubscribeFn;
+    subscribe<T>(viewPath: string, callback: SubscribeCallback<T>): UnsubscribeFn;
+    subscribeToKey<T>(viewPath: string, key: string, callback: SubscribeCallback<T>): UnsubscribeFn;
+    private notifyUpdate;
+    private notifyRichUpdate;
+    private notifyRichDelete;
+}
+
+declare class MemoryAdapter implements StorageAdapter {
+    private views;
+    private updateCallbacks;
+    private richUpdateCallbacks;
+    constructor(_config?: StorageAdapterConfig);
+    get<T>(viewPath: string, key: string): T | null;
+    getAll<T>(viewPath: string): T[];
+    getAllSync<T>(viewPath: string): T[] | undefined;
+    getSync<T>(viewPath: string, key: string): T | null | undefined;
+    has(viewPath: string, key: string): boolean;
+    keys(viewPath: string): string[];
+    size(viewPath: string): number;
+    set<T>(viewPath: string, key: string, data: T): void;
+    delete(viewPath: string, key: string): void;
+    clear(viewPath?: string): void;
+    evictOldest(viewPath: string): string | undefined;
+    onUpdate(callback: UpdateCallback): () => void;
+    onRichUpdate(callback: RichUpdateCallback$1): () => void;
+    notifyUpdate<T>(viewPath: string, key: string, update: Update<T>): void;
+    notifyRichUpdate<T>(viewPath: string, key: string, update: RichUpdate<T>): void;
+}
+
+declare function createUpdateStream<T>(storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry, subscription: Subscription, keyFilter?: string): AsyncIterable<Update<T>>;
+declare function createEntityStream<T>(storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry, subscription: Subscription, options?: WatchOptions<any>, keyFilter?: string): AsyncIterable<T>;
+declare function createRichUpdateStream<T>(storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry, subscription: Subscription, keyFilter?: string): AsyncIterable<RichUpdate<T>>;
+
+declare function createTypedStateView<T>(viewDef: ViewDef<T, 'state'>, storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry): TypedStateView<T>;
+declare function createTypedListView<T>(viewDef: ViewDef<T, 'list'>, storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry): TypedListView<T>;
+declare function createTypedViews<TStack extends StackDefinition>(stack: TStack, storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry): TypedViews<TStack['views']>;
+
+export { Arete, AreteError, ConnectionManager, DEFAULT_CONFIG, DEFAULT_MAX_ENTRIES_PER_VIEW, EntityStore, FrameProcessor, MemoryAdapter, SubscriptionRegistry, account, arg, bytes, createEntityStream, createInstructionExecutor, createProgramPdas, createPublicKeySeed, createRichUpdateStream, createSeed, createTypedListView, createTypedStateView, createTypedViews, createUpdateStream, decodeBase58, findProgramAddress as derivePda, encodeBase58, executeInstruction, findProgramAddress, findProgramAddressSync, formatProgramError, isEntityFrame, isSnapshotFrame, isSubscribedFrame, isValidFrame, literal, parseFrame, parseFrameFromBlob, parseInstructionError, pda, resolveAccounts, serializeInstructionData, validateAccountResolution, waitForConfirmation };
+export type { AccountCategory, AccountMeta, AccountResolutionOptions, AccountResolutionResult, AreteConfig, AreteOptions, AreteOptionsWithStorage, ArgSchema, ArgType, AuthConfig, AuthTokenResult, BuiltInstruction, ConfirmationLevel, ConnectionState, ConnectionStateCallback, EntityFrame, EntityStoreConfig, ErrorMetadata, ExecuteOptions, ExecutionResult, Frame, FrameMode, FrameOp, FrameProcessorConfig, InstructionDefinition, InstructionExecutor, InstructionExecutorOptions, InstructionHandler, PdaConfig, PdaDeriveContext, PdaFactory, PdaSeed, ProgramError, ProgramPdas, ResolvedAccount, ResolvedAccounts, RichUpdate, RichUpdateCallback$1 as RichUpdateCallback, Schema, SchemaResult, SeedDef, SnapshotEntity, SnapshotFrame, SocketIssue, SocketIssueCallback, SortConfig, SortOrder, StackDefinition, StorageAdapter, StorageAdapterConfig, SubscribeCallback, SubscribedFrame, Subscription, TypedListView, TypedStateView, TypedViewGroup, TypedViews, UnsubscribeFn, Update, UpdateCallback, ViewConfig, ViewDef, ViewGroup, ViewSortConfig, WalletAdapter, WalletConnectOptions, WalletState, WatchOptions, WebSocketFactoryInit };