@usearete/sdk 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,3 +1,78 @@
+import { Buffer } from 'buffer';
+
+type TransactionCommitment = 'processed' | 'confirmed' | 'finalized';
+type TransactionAuthScope = 'transaction:inspect' | 'transaction:send';
+interface TransactionRequestContext {
+    commitment?: TransactionCommitment;
+    minContextSlot?: bigint;
+}
+interface LatestBlockhashResult {
+    blockhash: string;
+    contextSlot: bigint;
+    lastValidBlockHeight: bigint;
+}
+interface TransactionFeeResult {
+    feeLamports: bigint | null;
+    contextSlot: bigint;
+}
+interface TransactionSimulationOptions extends TransactionRequestContext {
+    accounts?: readonly string[];
+    innerInstructions?: boolean;
+    replaceRecentBlockhash?: boolean;
+}
+interface TransactionSimulationResult {
+    contextSlot: bigint;
+    err: unknown | null;
+    logs: readonly string[] | null;
+    unitsConsumed?: bigint;
+    accounts?: readonly unknown[] | null;
+}
+interface TransactionSendOptions {
+    skipPreflight?: boolean;
+    preflightCommitment?: TransactionCommitment;
+    minContextSlot?: bigint;
+}
+interface TransactionSendResult {
+    signature: string;
+}
+interface TransactionSignatureStatus {
+    signature: string;
+    slot: bigint | null;
+    confirmationStatus: TransactionCommitment | null;
+    err: unknown | null;
+}
+interface TransactionTransportErrorBody {
+    code: string;
+    message: string;
+    retryable: boolean;
+    request_id?: string;
+    submission_state?: 'not_submitted' | 'unknown';
+    signature?: string;
+    details?: unknown;
+}
+declare class TransactionTransportError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly requestId?: string;
+    readonly submissionState?: 'not_submitted' | 'unknown';
+    readonly signature?: string;
+    readonly details?: unknown;
+    readonly status: number;
+    constructor(status: number, body: TransactionTransportErrorBody);
+}
+interface TransactionTransport {
+    getLatestBlockhash(options?: TransactionRequestContext): Promise<LatestBlockhashResult>;
+    getFeeForMessage(message: string, options?: TransactionRequestContext): Promise<TransactionFeeResult>;
+    simulateTransaction(transaction: string, options?: TransactionSimulationOptions): Promise<TransactionSimulationResult>;
+    sendTransaction(transaction: string, options?: TransactionSendOptions): Promise<TransactionSendResult>;
+    getSignatureStatus(signature: string, options?: TransactionRequestContext & {
+        searchTransactionHistory?: boolean;
+    }): Promise<TransactionSignatureStatus | null>;
+    getBlockHeight(options?: TransactionRequestContext): Promise<bigint>;
+}
+type AuthenticatedTransactionFetch = (input: string, init: RequestInit, scope: TransactionAuthScope, allowAuthReplay: boolean) => Promise<Response>;
+declare function createTransactionTransport(baseUrl: string, authenticatedFetch: AuthenticatedTransactionFetch): TransactionTransport;
+
 /**
  * Wallet adapter boundary for the Arete SDK.
  *
@@ -7,6 +82,7 @@
  * boundary, implemented by adapters that wrap the Solana library of your choice
  * (@solana/web3.js, @solana/kit, a raw Keypair signer for scripts, etc.).
  */
+
 /**
  * A single account reference within a built instruction.
  */
@@ -70,6 +146,35 @@ interface SendResult {
     /** Slot in which the transaction landed, if the adapter reports it */
     slot?: number;
 }
+/**
+ * Adapter-specific options for unsigned transaction inspection.
+ *
+ * Inspection must not sign or submit the transaction. Concrete adapters may
+ * accept additional simulation options through this passthrough object.
+ */
+interface TransactionInspectionOptions {
+    [key: string]: unknown;
+}
+/**
+ * Unsigned transaction inspection returned by a capable wallet adapter.
+ */
+interface TransactionInspectionResult {
+    /** Estimated transaction fee in lamports, when available. */
+    feeLamports?: number;
+    /** Program logs produced by simulation, when available. */
+    logs?: readonly string[];
+    /** Compute units consumed by simulation, when available. */
+    computeUnitsConsumed?: number;
+    /** RPC context slot for the inspection, when available. */
+    contextSlot?: number;
+    /** Raw simulation failure, if the inspected transaction would fail. */
+    error?: unknown;
+    /** Adapter-specific inspection fields. */
+    [key: string]: unknown;
+}
+interface WalletExecutionContext {
+    transactionTransport?: TransactionTransport;
+}
 /**
  * Wallet adapter interface for signing and sending transactions.
  *
@@ -93,7 +198,14 @@ interface WalletAdapter {
      * @param options - Adapter-specific send/confirmation options
      * @returns The transaction signature (and slot, if known)
      */
-    signAndSend(instructions: readonly BuiltInstruction[], options?: SendOptions): Promise<SendResult>;
+    signAndSend(instructions: readonly BuiltInstruction[], options?: SendOptions, context?: WalletExecutionContext): Promise<SendResult>;
+    /**
+     * Inspect a transaction without signing, submitting, or prompting a wallet.
+     *
+     * This capability is optional because not every adapter has an RPC-backed
+     * unsigned simulation implementation.
+     */
+    inspectTransaction?(instructions: readonly BuiltInstruction[], options?: TransactionInspectionOptions, context?: WalletExecutionContext): Promise<TransactionInspectionResult>;
 }
 /**
  * Wallet connection state
@@ -272,6 +384,7 @@ declare function createPublicKeySeed(address: string): Uint8Array;
  * This module handles serializing instruction arguments into the binary format
  * expected by Solana programs using Borsh serialization.
  */
+
 /**
  * Instruction argument schema for serialization.
  */
@@ -352,6 +465,46 @@ interface ErrorMetadata {
     name: string;
     msg: string;
 }
+type TransactionFailureStatus = 'not-submitted' | 'submitted-unknown' | 'chain-failed';
+type TransactionFailurePhase = 'build' | 'wallet' | 'send' | 'confirmation' | 'chain';
+interface ConfirmedTransactionOutcome {
+    readonly status: 'confirmed';
+    readonly phase: 'confirmation';
+    readonly signature: string;
+    readonly slot?: number;
+}
+interface NotSubmittedTransactionOutcome {
+    readonly status: 'not-submitted';
+    readonly phase: 'build' | 'wallet' | 'send';
+    readonly cause: unknown;
+}
+interface SubmittedUnknownTransactionOutcome {
+    readonly status: 'submitted-unknown';
+    readonly phase: 'send' | 'confirmation';
+    readonly signature: string;
+    readonly slot?: number;
+    readonly cause: unknown;
+}
+interface ChainFailedTransactionOutcome {
+    readonly status: 'chain-failed';
+    readonly phase: 'confirmation' | 'chain';
+    readonly signature?: string;
+    readonly slot?: number;
+    readonly programError?: ProgramError;
+    readonly cause: unknown;
+}
+type TransactionFailureOutcome = NotSubmittedTransactionOutcome | SubmittedUnknownTransactionOutcome | ChainFailedTransactionOutcome;
+type TransactionOutcome = ConfirmedTransactionOutcome | TransactionFailureOutcome;
+/**
+ * Structured transaction failure thrown by adapters and the core executor.
+ */
+declare class TransactionExecutionError extends Error {
+    readonly outcome: TransactionFailureOutcome;
+    readonly cause: unknown;
+    readonly signature?: string;
+    readonly slot?: number;
+    constructor(outcome: TransactionFailureOutcome, message?: string);
+}
 /**
  * Parses an error returned from a Solana transaction.
  *
@@ -359,7 +512,7 @@ interface ErrorMetadata {
  * @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;
+declare function parseInstructionError(error: unknown, errorMetadata: readonly ErrorMetadata[]): ProgramError | null;
 /**
  * Formats an error for display.
  *
@@ -376,8 +529,18 @@ declare class InstructionError extends Error {
     readonly programError: ProgramError | null;
     /** The original underlying error from the wallet adapter / RPC. */
     readonly cause: unknown;
-    constructor(message: string, programError: ProgramError | null, cause: unknown);
+    /** Structured chain-failure outcome, including signature and slot when known. */
+    readonly outcome: ChainFailedTransactionOutcome;
+    readonly signature?: string;
+    readonly slot?: number;
+    constructor(message: string, programError: ProgramError | null, cause: unknown, outcome?: ChainFailedTransactionOutcome);
 }
+/** Find a structured transaction failure through nested error causes. */
+declare function getTransactionFailureOutcome(error: unknown): TransactionFailureOutcome | null;
+/**
+ * Normalize an adapter/host exception without retrying or resubmitting.
+ */
+declare function normalizeTransactionError(cause: unknown, errorMetadata?: readonly ErrorMetadata[], fallbackPhase?: 'wallet' | 'send'): InstructionError | TransactionExecutionError;
 
 /**
  * Resolved accounts map passed to a handler's build function.
@@ -546,6 +709,9 @@ type Update<T> = {
     type: 'patch';
     key: string;
     data: Partial<T>;
+} | {
+    type: 'remove';
+    key: string;
 } | {
     type: 'delete';
     key: string;
@@ -560,15 +726,23 @@ type RichUpdate<T> = {
     before: T;
     after: T;
     patch?: unknown;
+} | {
+    type: 'removed';
+    key: string;
+    lastKnown?: T;
 } | {
     type: 'deleted';
     key: string;
     lastKnown?: T;
 };
-interface ViewDef<T, TMode extends 'state' | 'list'> {
+type ViewKeyValue = string | number | bigint;
+type ViewKeyFields<TKey> = unknown extends TKey ? readonly string[] : TKey extends object ? readonly Extract<keyof TKey, string>[] : readonly string[];
+interface ViewDef<T, TMode extends 'state' | 'list', TKey = unknown> {
     readonly mode: TMode;
     readonly view: string;
+    readonly keyFields?: ViewKeyFields<TKey>;
     readonly _entity?: T;
+    readonly _key?: TKey;
 }
 interface StackEndpoints {
     readonly ws: string;
@@ -577,10 +751,26 @@ interface StackEndpoints {
 type ReadTransportMethod = 'GET' | 'POST';
 interface ProgramAccountReadDefinition<T> {
     readonly account: string;
-    readonly path: string;
     readonly schema?: Schema<T>;
     readonly _result?: T;
 }
+type ProgramAccountBatchItem<T> = {
+    readonly address: string;
+    readonly status: 'ok';
+    readonly value: T;
+} | {
+    readonly address: string;
+    readonly status: 'missing';
+} | {
+    readonly address: string;
+    readonly status: 'error';
+    readonly error: {
+        readonly code: string;
+    };
+};
+interface ProgramAccountBatchResult<T> {
+    readonly items: readonly ProgramAccountBatchItem<T>[];
+}
 interface ProgramQueryDefinition<TParams = unknown, TResult = unknown> {
     readonly name: string;
     readonly path: string;
@@ -600,6 +790,11 @@ interface StackQueryDefinition<TParams = unknown, TResult = unknown> {
 interface ProgramSdkDefinition {
     readonly name: string;
     readonly programId?: string;
+    /** Typed identity of the generated program behavior and compiler provenance. */
+    readonly sdkDefinitionHash?: string;
+    readonly programSpecHash?: string;
+    readonly idlContentHash?: string;
+    readonly normalizedIdlHash?: string;
     readonly schemas?: Record<string, Schema<unknown>>;
     readonly pdas?: Record<string, unknown>;
     readonly accounts?: Record<string, ProgramAccountReadDefinition<unknown>>;
@@ -610,33 +805,140 @@ interface ProgramSdkDefinition {
     readonly defaults?: unknown;
     readonly math?: unknown;
 }
-interface StackDefinition {
+interface ProgramReleaseReference {
+    readonly programReleaseHash: string;
+    readonly programSpecHash: string;
+}
+/** Public, non-secret metadata describing how an HTTP bearer token is acquired. */
+interface HttpAuthMetadata {
+    readonly required?: boolean;
+    readonly mode?: string;
+    readonly sessionEndpoint: string;
+    readonly jwksUrl?: string;
+    readonly tokenTransport?: string;
+    readonly audience?: string;
+    readonly targetKind: 'program-read-binding';
+    readonly targetId: string;
+    readonly scopes?: readonly string[];
+    readonly acceptedKeyClasses?: readonly string[];
+}
+interface ProgramReadBinding {
+    readonly endpoint: string;
+    readonly programReadBindingId: string;
+    readonly auth: HttpAuthMetadata;
+}
+type SolanaGatewayAuthScope = 'read' | 'transaction:inspect' | 'transaction:send';
+/** Complete public auth metadata emitted for a hosted Solana gateway binding. */
+interface SolanaGatewayAuthMetadata {
+    readonly required: boolean;
+    readonly mode: string;
+    readonly sessionEndpoint: string;
+    readonly jwksUrl: string;
+    readonly tokenTransport: string;
+    readonly audience: 'arete:solana-gateway';
+    readonly targetKind: 'solana-gateway-binding';
+    readonly targetId: string;
+    readonly scopes: readonly SolanaGatewayAuthScope[];
+    readonly acceptedKeyClasses: readonly string[];
+    readonly transactionEntitlementRequired: boolean;
+}
+/** One generated, non-inheriting hosted Solana gateway capability binding. */
+interface HostedSolanaGatewayCapabilityBinding {
+    readonly endpoint: string;
+    readonly authPolicy: string;
+    readonly solanaGatewayBindingId: string;
+    readonly cluster: string;
+    readonly region: string;
+    readonly auth: SolanaGatewayAuthMetadata;
+}
+interface HostedSolanaGatewayBindings {
+    readonly chain: HostedSolanaGatewayCapabilityBinding;
+    readonly transactions: HostedSolanaGatewayCapabilityBinding;
+}
+/** Generated release identity with one explicit, non-inheriting read transport. */
+type ProgramReadDescriptor = {
+    readonly release: ProgramReleaseReference;
+    readonly transport: {
+        readonly kind: 'local-http';
+        readonly endpointSource: 'connect-http-url';
+    };
+} | {
+    readonly release: ProgramReleaseReference;
+    readonly transport: {
+        readonly kind: 'hosted-binding';
+        readonly binding: ProgramReadBinding;
+    };
+};
+/** Runtime overrides replace the complete generated descriptor. */
+type ProgramReadOverride = ProgramReadDescriptor;
+type ProgramReadDescriptors<TPrograms extends Record<string, ProgramSdkDefinition> | undefined> = TPrograms extends Record<string, ProgramSdkDefinition> ? {
+    readonly [K in keyof TPrograms]: ProgramReadDescriptor;
+} : Record<string, never>;
+type ProgramReadOverrides<TPrograms extends Record<string, ProgramSdkDefinition> | undefined> = TPrograms extends Record<string, ProgramSdkDefinition> ? {
+    readonly [K in keyof TPrograms]?: ProgramReadOverride;
+} : Record<string, never>;
+interface StackDefinition<TPrograms extends Record<string, ProgramSdkDefinition> = Record<string, ProgramSdkDefinition>> {
     readonly name: string;
     readonly endpoints: StackEndpoints;
     readonly views: Record<string, ViewGroup>;
     readonly schemas?: Record<string, Schema<unknown>>;
     readonly patchSchemas?: Record<string, Schema<unknown>>;
     readonly queries?: Record<string, StackQueryDefinition<unknown, unknown>>;
-    readonly programs?: Record<string, ProgramSdkDefinition>;
+    readonly programs?: TPrograms;
+    /** Release and transport metadata keyed in parallel with `programs`. */
+    readonly programReads?: ProgramReadDescriptors<TPrograms>;
 }
 interface ViewGroup {
-    state?: ViewDef<unknown, 'state'>;
-    list?: ViewDef<unknown, 'list'>;
+    state?: ViewDef<any, 'state', any>;
+    list?: ViewDef<any, 'list'>;
 }
-interface Subscription {
+interface SubscriptionQuery {
     view: string;
     key?: string;
     partition?: string;
-    filters?: Record<string, string>;
+    filters?: Record<string, unknown>;
     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;
 }
+interface SubscriptionSnapshotOptions {
+    enabled: boolean;
+}
+/** Protocol v2 wire subscription. The client-selected ID remains stable across reconnects. */
+interface Subscription {
+    type: 'subscribe';
+    protocolVersion: 2;
+    subscriptionId: string;
+    query: SubscriptionQuery;
+    snapshot: SubscriptionSnapshotOptions;
+}
+interface SubscriptionRequest {
+    query: SubscriptionQuery;
+    snapshot?: Partial<SubscriptionSnapshotOptions>;
+}
+/** Canonical query identity includes every server query field and snapshot behavior. */
+type SubscriptionIdentity = SubscriptionRequest;
+type SubscriptionOptions = SubscriptionSnapshotOptions;
+interface QuerySnapshot<T = unknown> {
+    readonly subscriptionId: string;
+    readonly query: SubscriptionQuery;
+    readonly keys: readonly string[];
+    readonly data: readonly T[];
+    readonly isLoading: boolean;
+    readonly isRefreshing: boolean;
+    readonly error?: AreteError;
+}
+interface QueryLease {
+    readonly subscription: Subscription;
+    readonly queryKey: string;
+    getSnapshot<T = unknown>(): QuerySnapshot<T>;
+    onChange(callback: () => void): UnsubscribeFn;
+    onUpdate<T = unknown>(callback: (update: Update<T>) => void): UnsubscribeFn;
+    onRichUpdate<T = unknown>(callback: (update: RichUpdate<T>) => void): UnsubscribeFn;
+    refresh(): Promise<void>;
+    release(): void;
+}
 type SchemaResult<T> = {
     success: true;
     data: T;
@@ -648,9 +950,10 @@ interface Schema<T> {
     safeParse: (input: unknown) => SchemaResult<T>;
 }
 interface WatchOptions<TSchema = unknown> {
+    partition?: string;
     take?: number;
     skip?: number;
-    filters?: Record<string, string>;
+    filters?: Record<string, unknown>;
     schema?: Schema<TSchema>;
     /** Whether to include initial snapshot (defaults to true) */
     withSnapshot?: boolean;
@@ -661,6 +964,9 @@ interface WatchOptions<TSchema = unknown> {
 }
 interface AreteOptions<TStack extends StackDefinition> {
     stack: TStack;
+    /** Connect immediately when the client is created (defaults to true). */
+    autoConnect?: boolean;
+    /** Reconnect automatically after an established connection is lost (defaults to true). */
     autoReconnect?: boolean;
     reconnectIntervals?: number[];
     maxReconnectAttempts?: number;
@@ -671,7 +977,29 @@ interface AuthTokenResult {
     token: string;
     expiresAt?: number;
     expires_at?: number;
-}
+    scopes?: readonly string[];
+}
+interface ProgramReadBindingAuthTarget {
+    readonly targetKind: 'program-read-binding';
+    readonly targetId: string;
+    readonly programReleaseHash: string;
+}
+interface SolanaGatewayBindingAuthTarget {
+    readonly targetKind: 'solana-gateway-binding';
+    readonly targetId: string;
+    readonly programReleaseHash?: never;
+}
+type AuthTokenTarget = ProgramReadBindingAuthTarget | SolanaGatewayBindingAuthTarget;
+type AuthTokenRequest = {
+    readonly scopes: readonly string[];
+    readonly targetKind?: never;
+    readonly targetId?: never;
+    readonly programReleaseHash?: never;
+} | ({
+    readonly scopes: readonly string[];
+} & ProgramReadBindingAuthTarget) | ({
+    readonly scopes: readonly string[];
+} & SolanaGatewayBindingAuthTarget);
 interface WebSocketFactoryInit {
     headers?: Record<string, string>;
 }
@@ -680,7 +1008,7 @@ interface WebSocketFactoryInit {
  */
 interface AuthConfig {
     /** Custom token provider function - called before each connection and during refresh */
-    getToken?: () => Promise<string | AuthTokenResult>;
+    getToken?: (request?: AuthTokenRequest) => Promise<string | AuthTokenResult>;
     /** Arete Cloud token endpoint URL */
     tokenEndpoint?: string;
     /** Publishable key for Arete Cloud */
@@ -699,24 +1027,29 @@ interface AuthConfig {
 interface AreteConfig {
     /** WebSocket endpoint. `null`/omitted disables the WebSocket transport (HTTP-only mode). */
     websocketUrl?: string | null;
+    /** Reconnect automatically after an established connection is lost (defaults to true). */
+    autoReconnect?: boolean;
     reconnectIntervals?: number[];
     maxReconnectAttempts?: number;
     initialSubscriptions?: Subscription[];
     maxEntriesPerView?: number | null;
     /** Authentication configuration */
     auth?: AuthConfig;
+    /** Fetch implementation used for authentication token requests. */
+    fetch?: typeof fetch;
 }
 interface SocketIssue {
     error: string;
     message: string;
-    code: AuthErrorCode;
+    code: string | AuthErrorCode;
     retryable: boolean;
     retryAfter?: number;
     suggestedAction?: string;
     docsUrl?: string;
     fatal: boolean;
+    subscriptionId?: string | null;
 }
-declare const DEFAULT_CONFIG: Required<Pick<AreteConfig, 'reconnectIntervals' | 'maxReconnectAttempts' | 'maxEntriesPerView'>>;
+declare const DEFAULT_CONFIG: Required<Pick<AreteConfig, 'autoReconnect' | 'reconnectIntervals' | 'maxReconnectAttempts' | 'maxEntriesPerView'>>;
 /**
  * Machine-readable error codes for authentication and rate limiting failures
  *
@@ -732,21 +1065,22 @@ 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;
+    [K in keyof TGroup]: TGroup[K] extends ViewDef<infer T, 'state', infer TKey> ? TypedStateView<T, DefaultViewKey<TKey>> : 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;
+type DefaultViewKey<TKey> = unknown extends TKey ? string : TKey;
+interface TypedStateView<T, TKey = string> {
+    use<TSchema = T>(key: TKey, options?: WatchOptions<TSchema>): AsyncIterable<TSchema>;
+    watch(key: TKey, options?: WatchOptions): AsyncIterable<Update<T>>;
+    watchRich(key: TKey, options?: WatchOptions): AsyncIterable<RichUpdate<T>>;
+    get(key: TKey, options?: WatchOptions): Promise<T | null>;
+    getSync(key: TKey, options?: WatchOptions): 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;
+    get(options?: WatchOptions): Promise<T[]>;
+    getSync(options?: WatchOptions): T[] | undefined;
 }
 type SubscribeCallback<T> = (update: Update<T>) => void;
 type UnsubscribeFn = () => void;
@@ -754,52 +1088,77 @@ 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 FrameOp = 'subscribed' | 'unsubscribed' | 'snapshot' | 'upsert' | 'patch' | 'remove' | 'delete';
 type SortOrder = 'asc' | 'desc';
 interface SortConfig {
     field: string[];
     order: SortOrder;
 }
-interface SubscribedFrame {
+interface IdentifiedFrame {
+    protocolVersion: 2;
+    subscriptionId: string;
+}
+interface SubscribedFrame extends IdentifiedFrame {
     op: 'subscribed';
-    view: string;
+    query: SubscriptionQuery;
     mode: FrameMode;
     sort?: SortConfig;
 }
-interface EntityFrame<T = unknown> {
+interface UnsubscribedFrame extends IdentifiedFrame {
+    op: 'unsubscribed';
+}
+interface EntityFrame<T = unknown> extends IdentifiedFrame {
     mode: FrameMode;
     entity: string;
-    op: FrameOp;
+    op: 'upsert' | 'patch' | 'remove' | 'delete';
     key: string;
-    data: T;
+    data: T | null;
     append?: string[];
-    /** Sequence cursor for ordering and resume capability */
     seq?: string;
 }
 interface SnapshotEntity<T = unknown> {
     key: string;
     data: T;
 }
-interface SnapshotFrame<T = unknown> {
+interface SnapshotFrame<T = unknown> extends IdentifiedFrame {
+    snapshotId: string;
+    authoritative: boolean;
     mode: FrameMode;
     entity: string;
     op: 'snapshot';
+    key?: string;
     data: SnapshotEntity<T>[];
-    /** Indicates if this is the final snapshot batch. When false, more batches will follow. */
-    complete?: boolean;
+    complete: boolean;
+}
+interface ErrorFrame {
+    type: 'error';
+    protocolVersion: 2;
+    subscriptionId: string | null;
+    error?: string;
+    message?: string;
+    code: string;
+    retryable?: boolean;
+    fatal: boolean;
+    retry_after?: number;
+    suggested_action?: string;
+    docs_url?: string;
 }
-type Frame<T = unknown> = EntityFrame<T> | SnapshotFrame<T> | SubscribedFrame;
+type Frame<T = unknown> = EntityFrame<T> | SnapshotFrame<T> | SubscribedFrame | UnsubscribedFrame | ErrorFrame;
 declare function isSnapshotFrame<T>(frame: Frame<T>): frame is SnapshotFrame<T>;
 declare function isSubscribedFrame(frame: Frame): frame is SubscribedFrame;
+declare function isUnsubscribedFrame(frame: Frame): frame is UnsubscribedFrame;
+declare function isErrorFrame(frame: Frame): frame is ErrorFrame;
 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 function isHostedAreteEndpoint(url: string): boolean;
 declare class ConnectionManager {
     private ws;
     private websocketUrl;
+    private readonly autoReconnect;
     private reconnectIntervals;
     private maxReconnectAttempts;
     private reconnectAttempts;
@@ -807,15 +1166,22 @@ declare class ConnectionManager {
     private pingInterval;
     private tokenRefreshTimeout;
     private tokenRefreshInFlight;
+    private tokenRequestInFlight;
+    private readonly httpAuthTokenStates;
     private currentState;
     private subscriptionQueue;
     private activeSubscriptions;
+    private socketGeneration;
+    private pendingConnect;
     private frameHandlers;
     private stateHandlers;
     private socketIssueHandlers;
     private authConfig?;
+    private readonly authFetch;
     private currentToken?;
     private tokenExpiry?;
+    private tokenScopes;
+    private requestedScopes;
     private readonly hostedAreteUrl;
     private reconnectForTokenRefresh;
     constructor(config: AreteConfig);
@@ -824,9 +1190,17 @@ declare class ConnectionManager {
     private hasRefreshableAuth;
     private updateTokenState;
     private clearTokenState;
+    private tokenCovers;
     private getOrRefreshToken;
+    private fetchAuthToken;
+    private requestAuthToken;
+    private updateHttpTokenState;
+    private getTargetedHttpAuthToken;
+    private touchHttpAuthTokenState;
+    private trimHttpAuthTokenStates;
     private createTokenEndpointRequestBody;
     private fetchTokenFromEndpoint;
+    private isExpiryExpired;
     private isTokenExpired;
     private scheduleTokenRefresh;
     private clearTokenRefreshTimeout;
@@ -840,19 +1214,28 @@ declare class ConnectionManager {
     private createWebSocket;
     getState(): ConnectionState;
     getHttpAuthToken(forceRefresh?: boolean): Promise<string | undefined>;
+    getHttpAuthToken(requiredScopes?: readonly string[], forceRefresh?: boolean): Promise<string | undefined>;
+    getHttpAuthToken(request: AuthTokenRequest, forceRefresh?: boolean): Promise<string | undefined>;
+    getHttpAuthToken(target: AuthTokenTarget, forceRefresh?: boolean): Promise<string | undefined>;
+    getHttpAuthToken(target: AuthTokenTarget, requiredScopes: readonly string[], forceRefresh?: boolean): Promise<string | undefined>;
+    getHttpAuthToken(requiredScopes: readonly string[], target: AuthTokenTarget, forceRefresh?: boolean): Promise<string | undefined>;
+    getHttpAuthToken(requiredScopes: readonly string[], forceRefresh: boolean, target: AuthTokenTarget): Promise<string | undefined>;
     clearHttpAuthToken(): void;
+    clearHttpAuthToken(request: AuthTokenRequest): void;
+    clearHttpAuthToken(target: AuthTokenTarget, requiredScopes?: readonly string[]): void;
     onFrame(handler: FrameHandler): () => void;
     onStateChange(handler: ConnectionStateCallback): () => void;
     onSocketIssue(handler: SocketIssueCallback): () => void;
     private notifySocketIssue;
-    connect(): Promise<void>;
+    connect(recovering?: boolean): Promise<void>;
     disconnect(): void;
     subscribe(subscription: Subscription): void;
-    unsubscribe(view: string, key?: string): void;
+    unsubscribe(subscriptionId: string): void;
+    refresh(subscription: Subscription): void;
     isConnected(): boolean;
-    private makeSubKey;
     private flushSubscriptionQueue;
     private resubscribeActive;
+    private addQueuedSubscription;
     private updateState;
     private notifyFrameHandlers;
     private handleReconnect;
@@ -893,16 +1276,169 @@ interface StorageAdapter {
     notifyRichUpdate<T>(viewPath: string, key: string, update: RichUpdate<T>): void;
 }
 
+declare class QueryStore {
+    private readonly storage;
+    private readonly records;
+    constructor(storage: StorageAdapter);
+    register(subscription: Subscription, queryKey: string): void;
+    unregister(subscriptionId: string): void;
+    getSubscription(subscriptionId: string): Subscription | undefined;
+    getQueryKey(subscriptionId: string): string | undefined;
+    getSnapshot<T>(subscriptionId: string): QuerySnapshot<T> | undefined;
+    onChange(subscriptionId: string, callback: () => void): UnsubscribeFn;
+    onUpdate<T>(subscriptionId: string, callback: (update: Update<T>) => void): UnsubscribeFn;
+    onRichUpdate<T>(subscriptionId: string, callback: (update: RichUpdate<T>) => void): UnsubscribeFn;
+    acknowledge(subscriptionId: string, effectiveQuery: SubscriptionQuery, mode: FrameMode, sort?: SortConfig): void;
+    stageSnapshot(frame: SnapshotFrame, keys: readonly string[]): void;
+    applyLive(subscriptionId: string, key: string, update: Update<unknown>, richUpdate?: RichUpdate<unknown>, sequence?: string): void;
+    deleteGlobal(view: string, key: string, lastKnown?: unknown): void;
+    evict(view: string, key: string): void;
+    failFrame(frame: ErrorFrame): void;
+    beginRefresh(subscriptionId: string, waitForSnapshot?: boolean): Promise<void>;
+    failRefresh(subscriptionId: string, error: AreteError): void;
+    beginReconnect(): void;
+    failRefreshing(error: AreteError): void;
+    clear(): void;
+    private mergeIncremental;
+    private sortKeys;
+    private entitySequence;
+    private fail;
+    private resolveRefresh;
+    private rejectRefresh;
+    private requireRecord;
+    private touch;
+    private emitUpdate;
+    private emitRichUpdate;
+}
+
+interface WaitForProcessedSlotOptions {
+    /** Reject if the requested slot has not been processed within this duration. */
+    timeoutMs?: number;
+    /** Abort this wait without affecting frame processing or the connection. */
+    signal?: AbortSignal;
+}
+declare class ProcessedSlotTimeoutError extends Error {
+    readonly targetSlot: bigint;
+    readonly processedSlot: bigint | null;
+    constructor(targetSlot: bigint, processedSlot: bigint | null);
+}
+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>>;
+    patchSchemas?: Record<string, Schema<unknown>>;
+    queryStore?: QueryStore;
+    /** Whether rejected frames should also be written to `console.warn`. */
+    warnOnValidationError?: boolean;
+    /** Receives structured details whenever a generated schema rejects a frame. */
+    onValidationError?: (diagnostic: FrameValidationDiagnostic) => void;
+}
+interface FrameValidationDiagnostic {
+    readonly view: string;
+    readonly key?: string;
+    readonly seq?: string;
+    readonly operation: 'snapshot' | 'upsert' | 'patch';
+    readonly error: unknown;
+}
+declare class FrameProcessor {
+    private storage;
+    private maxEntriesPerView;
+    private flushIntervalMs;
+    private schemas?;
+    private patchSchemas?;
+    private queryStore?;
+    private warnOnValidationError;
+    private onValidationError?;
+    private pendingUpdates;
+    private flushTimer;
+    private isProcessing;
+    private latestProcessedSlot;
+    private processedSlotWaiters;
+    constructor(storage: StorageAdapter, config?: FrameProcessorConfig);
+    private getSchema;
+    private normalizeEntity;
+    private hasSchema;
+    private normalizePathSegment;
+    private normalizePath;
+    private normalizeSortConfig;
+    private normalizeAppendPaths;
+    private extractSeq;
+    private getInternalSeq;
+    private compareSeq;
+    private attachInternalSeq;
+    handleFrame<T>(frame: Frame<T>): void;
+    /**
+     * Immediately flush all pending updates.
+     * Useful for ensuring all updates are processed before reading state.
+     */
+    flush(): void;
+    getProcessedSlot(): bigint | null;
+    waitForProcessedSlot(slot: number | bigint, options?: WaitForProcessedSlotOptions): Promise<bigint>;
+    /**
+     * Clean up any pending timers. Call when disposing the processor.
+     */
+    dispose(): void;
+    private scheduleFlush;
+    private flushPendingUpdates;
+    private processFrame;
+    private normalizeSlot;
+    private slotFromSeq;
+    private frameSlot;
+    private markFrameProcessed;
+    private removeProcessedSlotWaiter;
+    private createAbortError;
+    private processFrameWithoutEnforce;
+    private handleSubscribedFrame;
+    private handleSnapshotFrame;
+    private handleSnapshotFrameWithoutEnforce;
+    private handleEntityFrame;
+    private handleEntityFrameWithoutEnforce;
+    private emitRichUpdate;
+    private createRichUpdate;
+    private enforceMaxEntries;
+}
+
+interface NormalizedSubscriptionRequest {
+    query: SubscriptionQuery;
+    snapshot: SubscriptionSnapshotOptions;
+}
+declare function validateSubscriptionId(subscriptionId: string): void;
+declare function createSubscriptionId(): string;
+declare function normalizeSubscriptionQuery(query: SubscriptionQuery): SubscriptionQuery;
+declare function normalizeSubscriptionRequest(request: SubscriptionRequest): NormalizedSubscriptionRequest;
+declare function canonicalQueryKey(request: SubscriptionRequest): string;
+declare function normalizeSubscription(subscription: Subscription): Subscription;
 declare class SubscriptionRegistry {
-    private subscriptions;
-    private connection;
-    constructor(connection: ConnectionManager);
-    subscribe(subscription: Subscription): UnsubscribeFn;
-    unsubscribe(subscription: Subscription): void;
-    getRefCount(subscription: Subscription): number;
+    private readonly connection;
+    private readonly queryStore;
+    private readonly subscriptions;
+    private readonly subscriptionsById;
+    constructor(connection: ConnectionManager, queryStore: QueryStore);
+    subscribe(query: SubscriptionQuery, snapshotEnabled?: boolean): QueryLease;
+    refresh(query: SubscriptionQuery, snapshotEnabled?: boolean): Promise<void>;
+    /**
+     * Refresh every active subscription for a view, optionally narrowed to one
+     * serialized key. Resolves immediately when nothing matches — refreshing a
+     * view with no active subscriptions is a no-op, not an error.
+     */
+    refreshView(view: string, key?: string): Promise<void>;
+    getRefCount(query: SubscriptionQuery, snapshotEnabled?: boolean): number;
     getActiveSubscriptions(): Subscription[];
+    getSnapshot<T>(query: SubscriptionQuery, snapshotEnabled?: boolean): QuerySnapshot<T> | undefined;
+    handleConnectionState(state: ConnectionState): void;
     clear(): void;
-    private makeSubKey;
+    private createLease;
+    private getTracker;
+    private refreshTracker;
+    private releaseTracker;
 }
 
 interface ChainClock {
@@ -936,6 +1472,19 @@ interface TokenBalanceInfo {
     amount: string;
     decimals?: number | null;
     uiAmountString?: string | null;
+    contextSlot: bigint;
+}
+interface NativeBalanceInfo {
+    lamports: bigint;
+    contextSlot: bigint;
+}
+interface ContextSlotOptions {
+    minContextSlot?: number | bigint;
+}
+interface TokenBalanceInput {
+    owner: string;
+    mint: string;
+    tokenProgram?: string;
 }
 interface RawAccountInfo {
     address: string;
@@ -947,16 +1496,13 @@ interface RawAccountInfo {
 interface ChainClient {
     exists(address: string): Promise<boolean>;
     lamports(address: string): Promise<number>;
+    nativeBalance(address: string, options?: ContextSlotOptions): Promise<NativeBalanceInfo>;
     minimumBalanceForRentExemption(space: number): Promise<number>;
     clock(): Promise<ChainClock>;
     account(address: string): Promise<RawAccountInfo | null>;
     mint(address: string): Promise<MintAccountInfo | null>;
     tokenAccount(address: string): Promise<TokenAccountInfo | null>;
-    balance(input: {
-        owner: string;
-        mint: string;
-        tokenProgram?: string;
-    }): Promise<TokenBalanceInfo>;
+    balance(input: TokenBalanceInput, options?: ContextSlotOptions): Promise<TokenBalanceInfo>;
 }
 type FetchLike = typeof fetch;
 declare function deriveHttpEndpoint(wsUrl: string): string;
@@ -1000,6 +1546,19 @@ interface PreparedOperationDescription {
         }[];
     }[];
 }
+interface OperationInspection {
+    /** JSON-safe description produced by {@link describePreparedOperation}. */
+    readonly description: PreparedOperationDescription;
+    /** Raw unsigned inspection returned by the adapter. */
+    readonly transaction: TransactionInspectionResult;
+    /** IDL-aware program error parsed from the inspection failure, if any. */
+    readonly programError: ProgramError | null;
+}
+interface OperationInspectionOptions {
+    wallet?: WalletAdapter;
+    inspect?: TransactionInspectionOptions;
+    transactionTransport?: TransactionTransport;
+}
 interface PreparedTransactionBody {
     readonly name: string;
     readonly instructions: NonEmptyReadonlyArray<BuiltInstruction>;
@@ -1079,6 +1638,7 @@ interface SingleTransactionOperationReceipt<TArtifacts> {
     readonly artifacts: TArtifacts;
     readonly signatures: NonEmptyReadonlyArray<string>;
     readonly transaction: OperationTransactionReceipt;
+    readonly callbackErrors?: readonly OperationCallbackError[];
 }
 interface FlowOperationReceipt<TArtifacts> {
     readonly kind: 'flow';
@@ -1086,6 +1646,7 @@ interface FlowOperationReceipt<TArtifacts> {
     readonly artifacts: TArtifacts;
     readonly signatures: NonEmptyReadonlyArray<string>;
     readonly transactions: NonEmptyReadonlyArray<OperationTransactionReceipt>;
+    readonly callbackErrors?: readonly OperationCallbackError[];
 }
 type OperationReceiptFor<TPrepared extends PreparedOperation> = TPrepared extends PreparedFlow<infer TArtifacts> ? FlowOperationReceipt<TArtifacts> : TPrepared extends PreparedInstruction<infer TArtifacts> ? SingleTransactionOperationReceipt<TArtifacts> : TPrepared extends PreparedTransaction<infer TArtifacts> ? SingleTransactionOperationReceipt<TArtifacts> : never;
 interface OperationExecutionEvent<TPrepared extends PreparedOperation = PreparedOperation> {
@@ -1096,14 +1657,18 @@ interface OperationExecutionEvent<TPrepared extends PreparedOperation = Prepared
 interface OperationExecutionSuccessEvent<TPrepared extends PreparedOperation = PreparedOperation> extends OperationExecutionEvent<TPrepared> {
     readonly receipt: OperationTransactionReceipt;
 }
+type OperationCallbackPhase = 'transaction-start' | 'transaction-success';
 interface OperationExecutionOptions<TSigner = unknown, TPrepared extends PreparedOperation = PreparedOperation> {
     wallet?: WalletAdapter;
+    transactionTransport?: TransactionTransport;
     send?: SendOptions;
     signers?: readonly TSigner[];
     signerRegistry?: SignerRegistry<TSigner>;
     availableSignerAddresses?: readonly string[];
     onTransactionStart?: (event: OperationExecutionEvent<TPrepared>) => void | Promise<void>;
     onTransactionSuccess?: (event: OperationExecutionSuccessEvent<TPrepared>) => void | Promise<void>;
+    /** Receives observer failures without changing the transaction outcome. */
+    onCallbackError?: (error: OperationCallbackError<TPrepared>) => void | Promise<void>;
 }
 interface OperationExecutionHost<TSigner = unknown> {
     readonly wallet?: WalletAdapter;
@@ -1113,28 +1678,60 @@ interface OperationExecutionHost<TSigner = unknown> {
         send?: SendOptions;
         errors?: ErrorMetadata[];
         signers?: readonly TSigner[];
+        transactionTransport?: TransactionTransport;
     }): Promise<{
         signature: string;
         slot?: number;
     }>;
 }
+declare class OperationCallbackError<TPrepared extends PreparedOperation = PreparedOperation> extends Error {
+    readonly phase: OperationCallbackPhase;
+    readonly operation: TPrepared;
+    readonly transaction: PreparedTransactionBody;
+    readonly transactionIndex: number;
+    readonly receipt?: OperationTransactionReceipt;
+    readonly cause: unknown;
+    constructor(input: {
+        phase: OperationCallbackPhase;
+        operation: TPrepared;
+        transaction: PreparedTransactionBody;
+        transactionIndex: number;
+        receipt?: OperationTransactionReceipt;
+        cause: unknown;
+    });
+}
 declare class OperationExecutionError<TPrepared extends PreparedOperation = PreparedOperation> extends Error {
     readonly operation: TPrepared;
     readonly failedTransaction: PreparedTransactionBody;
     readonly failedTransactionIndex: number;
     readonly completedReceipts: readonly OperationTransactionReceipt[];
+    readonly callbackErrors: readonly OperationCallbackError<TPrepared>[];
+    readonly outcome: TransactionFailureOutcome;
+    readonly signature?: string;
+    readonly slot?: number;
     readonly cause: unknown;
     constructor(input: {
         operation: TPrepared;
         failedTransaction: PreparedTransactionBody;
         failedTransactionIndex: number;
         completedReceipts: readonly OperationTransactionReceipt[];
+        callbackErrors?: readonly OperationCallbackError<TPrepared>[];
+        outcome?: TransactionFailureOutcome;
         cause: unknown;
     });
 }
 declare function executePreparedOperation<TPrepared extends PreparedOperation, TSigner = unknown>(host: OperationExecutionHost<TSigner>, operation: TPrepared, options?: OperationExecutionOptions<TSigner, TPrepared>): Promise<OperationReceiptFor<TPrepared>>;
+/**
+ * Recursively unwrap operation context while retaining structured transaction outcomes.
+ */
+declare function unwrapOperationExecutionError(error: unknown): InstructionError | TransactionFailureOutcome | unknown;
 declare function toJsonValue(value: unknown): JsonValue;
 declare function describePreparedOperation(operation: PreparedOperation): PreparedOperationDescription;
+/**
+ * Inspect one prepared instruction/transaction without signing or submission.
+ * Multi-transaction flows are intentionally unsupported.
+ */
+declare function inspectPreparedOperation(wallet: WalletAdapter | undefined, operation: PreparedOperation, options?: TransactionInspectionOptions, context?: WalletExecutionContext): Promise<OperationInspection>;
 declare function formatPreparedOperation(operation: PreparedOperation): string;
 
 interface InstructionOperation<TInput = unknown, TArtifacts = void> {
@@ -1164,6 +1761,16 @@ declare function flowOperation<TInput, TArtifacts>(prepare: (input: TInput) => M
 declare const STACK_RUNTIME_EXTENSIONS: "__areteStackRuntimeExtensions";
 declare const PROGRAM_OPERATION_EXTENSIONS: "__areteProgramOperationExtensions";
 type EmptyRecord = Record<string, never>;
+/** Fixed arity, or `[required, total]` when a read has optional arguments. */
+type ReadArgumentCount = number | readonly [required: number, total: number];
+type RequiredArgumentCount<TArgs extends readonly unknown[], TCount extends readonly unknown[] = []> = TArgs extends readonly [infer THead, ...infer TTail] ? undefined extends THead ? TCount['length'] : RequiredArgumentCount<TTail, readonly [...TCount, unknown]> : TCount['length'];
+type ReadArgumentCountFor<TRead> = TRead extends (...args: infer TArgs) => unknown ? number extends Required<TArgs>['length'] ? ReadArgumentCount : RequiredArgumentCount<TArgs> extends Required<TArgs>['length'] ? Required<TArgs>['length'] : readonly [
+    required: RequiredArgumentCount<TArgs>,
+    total: Required<TArgs>['length']
+] : never;
+type ReadArgumentCounts<TRead = Record<string, unknown>> = {
+    readonly [K in keyof TRead]: ReadArgumentCountFor<TRead[K]>;
+};
 type MaybeField<TKey extends string, TValue> = [TValue] extends [never] ? {} : {
     readonly [K in TKey]: TValue;
 };
@@ -1195,7 +1802,7 @@ interface ProgramRuntimeExtensionCarrier<TOperations extends AnyProgramOperation
 }
 type ProgramOperationsOf<TProgram> = TProgram extends ProgramRuntimeExtensionCarrier<infer TOperations> ? TOperations : ProgramOperations;
 type MergeProgramOperations<TBase extends AnyProgramOperations, TExtension extends AnyProgramOperations> = ProgramOperations<Extract<MergeField<InstructionOperationsOf<TBase>, InstructionOperationsOf<TExtension>>, InstructionOperationNamespace | EmptyRecord>, Extract<MergeField<TransactionOperationsOf<TBase>, TransactionOperationsOf<TExtension>>, TransactionOperationNamespace | EmptyRecord>, Extract<MergeField<FlowOperationsOf<TBase>, FlowOperationsOf<TExtension>>, FlowOperationNamespace | EmptyRecord>>;
-type ExtendedProgramDefinition<TBase extends ProgramSdkDefinition, TAddresses = never, TConstants = never, TDefaults = never, TOperations extends AnyProgramOperations = ProgramOperations, TMath = never> = TBase & MaybeField<'addresses', TAddresses> & MaybeField<'constants', TConstants> & MaybeField<'defaults', TDefaults> & MaybeField<'math', TMath> & ProgramRuntimeExtensionCarrier<MergeProgramOperations<ProgramOperationsOf<TBase>, TOperations>>;
+type ExtendedProgramDefinition<TBase extends ProgramSdkDefinition, TAddresses = never, TConstants = never, TDefaults = never, TOperations extends AnyProgramOperations = ProgramOperations, TMath = never> = Omit<TBase, 'sdkDefinitionHash'> & MaybeField<'addresses', TAddresses> & MaybeField<'constants', TConstants> & MaybeField<'defaults', TDefaults> & MaybeField<'math', TMath> & ProgramRuntimeExtensionCarrier<MergeProgramOperations<ProgramOperationsOf<TBase>, TOperations>>;
 interface ProgramExtensionInput<TAddresses = never, TConstants = never, TDefaults = never, TOperations extends AnyProgramOperations = ProgramOperations, TProgram extends ProgramSdkDefinition = ProgramSdkDefinition, TMath = never> {
     readonly pdas?: Record<string, unknown>;
     readonly accounts?: Record<string, unknown>;
@@ -1222,6 +1829,7 @@ declare function extendPrograms<TPrograms extends Record<string, ProgramSdkDefin
 };
 declare function getProgramRuntimeExtensions<TProgram extends ProgramSdkDefinition>(program: TProgram): ProgramRuntimeExtensions<ProgramOperationsOf<TProgram>, TProgram> | undefined;
 interface StackRuntimeExtensions<TRead = EmptyRecord, TFlows extends FlowOperationNamespace | EmptyRecord = EmptyRecord, TClient = unknown> {
+    readonly readArgCounts?: ReadArgumentCounts<TRead>;
     readonly createRead?: (client: TClient) => TRead;
     readonly createFlows?: (client: TClient) => TFlows;
 }
@@ -1238,16 +1846,22 @@ interface StackExtensionInput<TAddresses = never, TConstants = never, TDefaults
     readonly constants?: TConstants;
     readonly defaults?: TDefaults;
     readonly math?: TMath;
+    readonly readArgCounts?: ReadArgumentCounts<TRead>;
     readonly createRead?: (client: TClient) => TRead;
     readonly createFlows?: (client: TClient) => TFlows;
 }
+type ReadArgumentCountRequirement<TExtension> = TExtension extends {
+    readonly createRead: (...args: any[]) => infer TRead;
+} ? {
+    readonly readArgCounts: ReadArgumentCounts<TRead>;
+} : {};
 type StackExtensionClient<TBase extends StackDefinition, TAddresses = never, TConstants = never, TDefaults = never, TMath = never> = Arete$1<TBase> & MaybeField<'addresses', TAddresses> & MaybeField<'constants', TConstants> & MaybeField<'defaults', TDefaults> & MaybeField<'math', TMath>;
-declare function defineStackExtensions<TBase extends StackDefinition>(): <TExtension extends StackExtensionInput<any, any, any, any, any, FlowOperationNamespace | EmptyRecord, any>>(extensions: TExtension & {
+declare function defineStackExtensions<TBase extends StackDefinition>(): <const TExtension extends StackExtensionInput<any, any, any, any, any, FlowOperationNamespace | EmptyRecord, any>>(extensions: TExtension & ReadArgumentCountRequirement<TExtension> & {
     readonly createRead?: (client: StackExtensionClient<TBase, any, any, any, any>) => unknown;
     readonly createFlows?: (client: StackExtensionClient<TBase, any, any, any, any>) => FlowOperationNamespace | EmptyRecord;
 }) => TExtension;
-declare function extendStack<TBase extends StackDefinition, TExtension extends StackExtensionInput<any, any, any, any, any, any, any>>(stack: TBase, extensions: TExtension): ExtendedStackDefinition<TBase, MergeField<Field<TBase, 'addresses'>, Field<TExtension, 'addresses'>>, MergeField<Field<TBase, 'constants'>, Field<TExtension, 'constants'>>, MergeField<Field<TBase, 'defaults'>, Field<TExtension, 'defaults'>>, MergeField<Field<TBase, 'math'>, Field<TExtension, 'math'>>, MergeField<StackReadOf<TBase>, FactoryReturn<TExtension, 'createRead'>>, Extract<MergeField<StackFlowsOf<TBase>, FactoryReturn<TExtension, 'createFlows'>>, FlowOperationNamespace | EmptyRecord>>;
-declare function getStackRuntimeExtensions<TStack extends StackDefinition>(stack: TStack): StackRuntimeExtensions | undefined;
+declare function extendStack<TBase extends StackDefinition, TExtension extends StackExtensionInput<any, any, any, any, any, any, any>>(stack: TBase, extensions: TExtension & ReadArgumentCountRequirement<TExtension>): ExtendedStackDefinition<TBase, MergeField<Field<TBase, 'addresses'>, Field<TExtension, 'addresses'>>, MergeField<Field<TBase, 'constants'>, Field<TExtension, 'constants'>>, MergeField<Field<TBase, 'defaults'>, Field<TExtension, 'defaults'>>, MergeField<Field<TBase, 'math'>, Field<TExtension, 'math'>>, MergeField<StackReadOf<TBase>, FactoryReturn<TExtension, 'createRead'>>, Extract<MergeField<StackFlowsOf<TBase>, FactoryReturn<TExtension, 'createFlows'>>, FlowOperationNamespace | EmptyRecord>>;
+declare function getStackRuntimeExtensions<TStack extends StackDefinition>(stack: TStack): StackRuntimeExtensions<StackReadOf<TStack>> | undefined;
 declare function applyConnectedStackExtensions<TClient extends object, TStack extends StackDefinition>(client: TClient, stack: TStack): ConnectedStackClient<TClient, TStack>;
 
 type ProgramMap = Record<string, ProgramSdkDefinition>;
@@ -1256,8 +1870,9 @@ type MergeProgramMaps<TStackPrograms, TAttachedPrograms> = Omit<NormalizeProgram
 type StackWithAttachedPrograms<TStack extends StackDefinition, TAttachedPrograms extends ProgramMap | undefined> = Omit<TStack, 'programs'> & {
     programs: MergeProgramMaps<TStack['programs'], TAttachedPrograms>;
 };
+declare function validateProgramReadDescriptor(programName: string, descriptor: ProgramReadDescriptor): void;
 declare function withPrograms<TStack extends StackDefinition, TAttachedPrograms extends ProgramMap | undefined>(stack: TStack, attachedPrograms: TAttachedPrograms): StackWithAttachedPrograms<TStack, TAttachedPrograms>;
-interface ConnectOptions<TPrograms extends ProgramMap | undefined = undefined> {
+interface ConnectOptions<TPrograms extends ProgramMap | undefined = undefined, TStackPrograms extends ProgramMap | undefined = ProgramMap> {
     url?: string;
     httpUrl?: string;
     /**
@@ -1268,11 +1883,21 @@ interface ConnectOptions<TPrograms extends ProgramMap | undefined = undefined> {
     transport?: 'ws' | 'http';
     storage?: StorageAdapter;
     maxEntriesPerView?: number | null;
+    /** Connect immediately when the client is created (defaults to true). */
+    autoConnect?: boolean;
+    /** Reconnect automatically after an established connection is lost (defaults to true). */
     autoReconnect?: boolean;
     reconnectIntervals?: number[];
     maxReconnectAttempts?: number;
     flushIntervalMs?: number;
+    /**
+     * Generated schemas are always applied to normalize typed entities. Set this
+     * to `false` to suppress console warnings for rejected frames while keeping
+     * schema normalization and `onFrameValidationError` active.
+     */
     validateFrames?: boolean;
+    /** Observe generated-schema rejections without scraping console warnings. */
+    onFrameValidationError?: (diagnostic: FrameValidationDiagnostic) => void;
     /** Authentication configuration */
     auth?: AuthConfig;
     /** Default wallet adapter used for instruction execution (overridable per call). */
@@ -1281,6 +1906,12 @@ interface ConnectOptions<TPrograms extends ProgramMap | undefined = undefined> {
     fetch?: typeof fetch;
     /** Additional program SDKs exposed under client.programs.<key>. */
     programs?: TPrograms;
+    /** Per-program complete descriptor replacements. */
+    programReads?: ProgramReadOverrides<MergeProgramMaps<TStackPrograms, TPrograms>>;
+    /** Explicit chain transport, used by composition sessions. */
+    chain?: ChainClient;
+    /** Explicit transaction transport, used by composition sessions. */
+    transactions?: TransactionTransport;
     /** Default semantic-operation execution settings. */
     execution?: OperationExecutionOptions<any>;
 }
@@ -1294,9 +1925,13 @@ interface AreteOptionsWithStorage<TStack extends StackDefinition> extends AreteO
     wallet?: WalletAdapter;
     fetch?: typeof fetch;
     execution?: OperationExecutionOptions<any>;
+    chain?: ChainClient;
+    transactions?: TransactionTransport;
+    onFrameValidationError?: (diagnostic: FrameValidationDiagnostic) => void;
 }
 interface TransactionOptions<TSigner = unknown> {
     wallet?: WalletAdapter;
+    transactionTransport?: TransactionTransport;
     send?: SendOptions;
     errors?: ErrorMetadata[];
     signers?: readonly TSigner[];
@@ -1315,7 +1950,7 @@ interface TypedInstruction<TParams, TError> {
 }
 interface TypedAccountReader<T> {
     fetch(address: string): Promise<T | null>;
-    fetchMany(addresses: readonly string[]): Promise<Array<T | null>>;
+    fetchMany(addresses: readonly string[]): Promise<ProgramAccountBatchResult<T>>;
     exists(address: string): Promise<boolean>;
 }
 type TypedQueryExecutor<TParams, TResult> = (params: TParams) => Promise<TResult>;
@@ -1365,13 +2000,18 @@ declare class Arete$1<TStack extends StackDefinition> {
     private readonly storage;
     private readonly processor;
     private readonly subscriptionRegistry;
+    private readonly queryStore;
     private readonly _views;
     private readonly _queries;
     private readonly _programs;
     private readonly _chain;
+    private readonly _transactions;
     private readonly stack;
     private readonly httpBaseUrl;
+    private readonly connectHttpUrl;
+    private readonly programReadOverrides;
     private readonly fetchImpl;
+    private readonly auth;
     private readonly executionDefaults?;
     private _wallet?;
     private _aggregatedErrors?;
@@ -1380,18 +2020,21 @@ declare class Arete$1<TStack extends StackDefinition> {
     private buildQueries;
     private buildPrograms;
     private createTypedInstruction;
+    private createProgramTransport;
     private createAccountReader;
     private createQueryExecutor;
     private readJson;
     private authenticatedFetch;
+    private authenticatedStackFetch;
     private resolveReadUrl;
     /** Merge the client's default wallet into call options (call options win). */
     private withWallet;
-    static connect<T extends StackDefinition, TPrograms extends ProgramMap | undefined = undefined>(stack: T, options?: ConnectOptions<TPrograms>): Promise<ConnectedArete<StackWithAttachedPrograms<T, TPrograms>, T>>;
+    static connect<T extends StackDefinition, TPrograms extends ProgramMap | undefined = undefined>(stack: T, options?: ConnectOptions<TPrograms, T['programs']>): Promise<ConnectedArete<StackWithAttachedPrograms<T, TPrograms>, T>>;
     get views(): TypedViews<TStack['views']>;
     get queries(): QueriesInterface<TStack['queries']>;
     get programs(): ProgramsInterface<TStack['programs']>;
     get chain(): ChainClient;
+    get transactions(): TransactionTransport;
     /** The default wallet adapter, if one was configured. */
     get wallet(): WalletAdapter | undefined;
     /** The connected wallet address, if a default wallet was configured. */
@@ -1415,11 +2058,20 @@ declare class Arete$1<TStack extends StackDefinition> {
      */
     transaction(instructions: readonly BuiltInstruction[], options?: TransactionOptions): Promise<ExecutionResult>;
     execute<TPrepared extends PreparedOperation, TSigner = unknown>(prepared: TPrepared, options?: OperationExecutionOptions<TSigner, TPrepared>): Promise<OperationReceiptFor<TPrepared>>;
+    /** Inspect one prepared instruction/transaction without signing or submitting it. */
+    inspectOperation(prepared: PreparedOperation, options?: OperationInspectionOptions): Promise<OperationInspection>;
     /** Error metadata from every handler in the stack, deduped by code. */
     private aggregateErrors;
     get connectionState(): ConnectionState;
     get stackName(): string;
     get store(): StorageAdapter;
+    /** Highest Solana slot whose streamed frame has been stored locally. */
+    get processedSlot(): bigint | null;
+    /**
+     * Wait until a frame at or beyond `slot` has been applied to local storage.
+     * Buffered frames satisfy the wait only after their storage batch is flushed.
+     */
+    waitForProcessedSlot(slot: number | bigint, options?: WaitForProcessedSlotOptions): Promise<bigint>;
     onConnectionStateChange(callback: ConnectionStateCallback): UnsubscribeFn;
     onFrame(callback: (frame: Frame) => void): UnsubscribeFn;
     onSocketIssue(callback: SocketIssueCallback): UnsubscribeFn;
@@ -1430,6 +2082,7 @@ declare class Arete$1<TStack extends StackDefinition> {
     getStore(): StorageAdapter;
     getConnection(): ConnectionManager;
     getSubscriptionRegistry(): SubscriptionRegistry;
+    getQueryStore(): QueryStore;
 }
 
 /**
@@ -1440,9 +2093,12 @@ declare class Arete$1<TStack extends StackDefinition> {
  * composition of programs + views, and a standalone program member reuses the
  * exact same machinery as a stack with no views, connected HTTP-only.
  */
-interface SessionDefinition {
+interface SessionDefinition<TPrograms extends Record<string, ProgramSdkDefinition> = Record<string, ProgramSdkDefinition>> {
+    readonly mode?: 'composition';
     readonly stacks?: Record<string, StackDefinition>;
-    readonly programs?: Record<string, ProgramSdkDefinition>;
+    readonly programs?: TPrograms;
+    /** Generated descriptors keyed in parallel with standalone `programs`. */
+    readonly programReads?: ProgramReadDescriptors<TPrograms>;
 }
 type SessionStackPrograms<TDef extends SessionDefinition> = Partial<{
     [K in keyof NonNullable<TDef['stacks']>]: Record<string, ProgramSdkDefinition> | undefined;
@@ -1458,14 +2114,21 @@ interface SessionMemberOptions<TPrograms extends Record<string, ProgramSdkDefini
     transport?: 'ws' | 'http';
     auth?: AuthConfig;
     storage?: StorageAdapter;
+    autoConnect?: boolean;
     autoReconnect?: boolean;
     programs?: TPrograms;
+    /** Override applied to every program owned by this member. */
+    programRead?: ProgramReadOverride;
+    /** Per-program overrides for this member. */
+    programReads?: Readonly<Record<string, ProgramReadOverride>>;
 }
 interface SessionOptions<TDef extends SessionDefinition = SessionDefinition, TStackPrograms extends SessionStackPrograms<TDef> = {}> {
     /** One wallet governs execution across every member. */
     wallet?: WalletAdapter;
     /** Canonical chain reader shared by the session when explicitly provided. */
     chain?: ChainClient;
+    /** Transaction transport override; defaults to the execution host's authenticated client. */
+    transactions?: TransactionTransport;
     auth?: AuthConfig;
     fetch?: typeof fetch;
     /** Default transport for all members ('ws' unless overridden). */
@@ -1484,7 +2147,18 @@ interface SessionOptions<TDef extends SessionDefinition = SessionDefinition, TSt
         [K in keyof NonNullable<TDef['stacks']>]?: SessionMemberOptions<K extends keyof TStackPrograms ? TStackPrograms[K] : undefined>;
     };
     programs?: Record<string, SessionMemberOptions>;
-}
+    /** Override applied to every program in the session. */
+    programRead?: ProgramReadOverride;
+    /** Session-wide per-program overrides, keyed by program key. */
+    programReads?: Readonly<Record<string, ProgramReadOverride>>;
+}
+type CompositionSessionOptions<TDef extends SessionDefinition = SessionDefinition, TStackPrograms extends SessionStackPrograms<TDef> = {}> = Omit<SessionOptions<TDef, TStackPrograms>, 'chain' | 'transactions' | 'endpoints'> & {
+    /** Chain reads never inherit a live member's HTTP endpoint. */
+    chain: ChainClient;
+    /** Transactions never inherit a live member's HTTP endpoint. */
+    transactions: TransactionTransport;
+    endpoints?: never;
+};
 type SessionStacks<TDef extends SessionDefinition, TStackPrograms extends SessionStackPrograms<TDef> = {}> = {
     readonly [K in keyof NonNullable<TDef['stacks']>]: NonNullable<TDef['stacks']>[K] extends StackDefinition ? K extends keyof TStackPrograms ? ConnectedArete<StackWithAttachedPrograms<NonNullable<TDef['stacks']>[K], TStackPrograms[K]>, NonNullable<TDef['stacks']>[K]> : ConnectedArete<NonNullable<TDef['stacks']>[K], NonNullable<TDef['stacks']>[K]> : never;
 };
@@ -1497,19 +2171,38 @@ type PromotedSessionPrograms<TDef extends SessionDefinition, TStackPrograms exte
 type ExplicitSessionPrograms<TDef extends SessionDefinition> = {
     readonly [K in keyof NonNullable<TDef['programs']>]: NonNullable<TDef['programs']>[K] extends ProgramSdkDefinition ? ProgramInterface<NonNullable<TDef['programs']>[K]> : never;
 };
-type SessionPrograms<TDef extends SessionDefinition, TStackPrograms extends SessionStackPrograms<TDef> = {}> = Omit<PromotedSessionPrograms<TDef, TStackPrograms>, keyof NonNullable<TDef['programs']>> & ExplicitSessionPrograms<TDef>;
+type SessionPrograms<TDef extends SessionDefinition, TStackPrograms extends SessionStackPrograms<TDef> = {}> = TDef extends {
+    readonly mode: 'composition';
+} ? ExplicitSessionPrograms<TDef> : Omit<PromotedSessionPrograms<TDef, TStackPrograms>, keyof NonNullable<TDef['programs']>> & ExplicitSessionPrograms<TDef>;
 interface Session<TDef extends SessionDefinition = SessionDefinition, TStackPrograms extends SessionStackPrograms<TDef> = {}> {
     readonly stacks: SessionStacks<TDef, TStackPrograms>;
     readonly programs: SessionPrograms<TDef, TStackPrograms>;
     readonly wallet: WalletAdapter | undefined;
     readonly signerRegistry: SignerRegistry<any>;
     readonly chain: ChainClient;
+    readonly transactions: TransactionTransport;
     transaction(instructions: readonly BuiltInstruction[], options?: TransactionOptions): Promise<ExecutionResult>;
     execute<TPrepared extends PreparedOperation, TSigner = unknown>(prepared: TPrepared, options?: OperationExecutionOptions<TSigner, TPrepared>): Promise<OperationReceiptFor<TPrepared>>;
     setWallet(wallet: WalletAdapter | undefined): void;
     close(): void;
 }
-declare function createSession<TDef extends SessionDefinition, TStackPrograms extends SessionStackPrograms<TDef> = {}>(definition: TDef, options?: SessionOptions<TDef, TStackPrograms>): Promise<Session<TDef, TStackPrograms>>;
+declare function createSession<TDef extends SessionDefinition, TStackPrograms extends SessionStackPrograms<TDef> = {}>(definition: TDef, ...args: TDef extends {
+    readonly mode: 'composition';
+} ? [options: CompositionSessionOptions<TDef, TStackPrograms>] : [options?: SessionOptions<TDef, TStackPrograms>]): Promise<Session<TDef, TStackPrograms>>;
+
+interface HostedSolanaGatewayTransportOptions {
+    readonly auth?: AuthConfig;
+    readonly fetch?: typeof fetch;
+}
+interface HostedSolanaGatewayTransports {
+    readonly chain: ChainClient;
+    readonly transactions: TransactionTransport;
+}
+/**
+ * Construct explicit hosted chain and transaction transports from generated
+ * gateway descriptors. Tokens are isolated by exact binding target and scope.
+ */
+declare function createHostedSolanaGatewayTransports(bindings: HostedSolanaGatewayBindings, options?: HostedSolanaGatewayTransportOptions): HostedSolanaGatewayTransports;
 
 interface AccountLoader {
     getAccount(address: string): Promise<{
@@ -1549,6 +2242,8 @@ declare function parseUiAmountToRaw(value: string | number, decimals: number): b
 declare function formatRawToUi(raw: bigint | string | number, decimals: number): string;
 /** Resolve an {@link AmountInput} to raw base units with known decimals. */
 declare function toRawAmount(amount: AmountInput, decimals: number): bigint;
+/** Convert an amount to raw units without throwing on invalid user input. */
+declare function safeToRawAmount(amount: AmountInput, decimals: number): SchemaResult<bigint>;
 /** Fetch a mint's decimals via the chain read endpoint, throwing when unavailable. */
 declare function getMintDecimals(chain: ChainClient, mint: string): Promise<number>;
 /**
@@ -1570,6 +2265,24 @@ declare function resolveAmountsToRaw<TInputs extends Record<string, AmountResolu
     [K in keyof TInputs]: bigint;
 }>;
 
+/**
+ * Recursively convert bigints to their decimal string form.
+ *
+ * Streamed entities contain bigints, which makes them unsafe to pass through
+ * anything that JSON-stringifies (React's dev-mode performance tooling, log
+ * pipelines, `JSON.stringify` persistence). Prefer stack-provided UI fields
+ * (e.g. `deployedPerSquareUi`) when they exist; use this for the remaining
+ * raw values such as account snapshots.
+ *
+ * Arrays and plain objects are converted structurally and the return type
+ * maps every `bigint` to `string`; class instances (PublicKey, Date, …) are
+ * returned untouched.
+ */
+type StringifiedBigints<T> = T extends bigint ? string : T extends readonly (infer U)[] ? readonly StringifiedBigints<U>[] : T extends object ? {
+    [K in keyof T]: StringifiedBigints<T[K]>;
+} : T;
+declare function stringifyBigints<T>(value: T): StringifiedBigints<T>;
+
 declare class ReadRequestError extends Error {
     readonly status: number;
     readonly path: string;
@@ -1584,7 +2297,6 @@ declare class ReadRequestError extends Error {
 }
 declare function programAccountRead<T>(input: {
     account: string;
-    path: string;
     schema?: Schema<T>;
 }): ProgramAccountReadDefinition<T>;
 declare function programQuery<TParams = unknown, TResult = unknown>(input: {
@@ -1600,61 +2312,21 @@ declare function stackQuery<TParams = unknown, TResult = unknown>(input: {
     schema?: Schema<TResult>;
 }): StackQueryDefinition<TParams, TResult>;
 
-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>>;
-    patchSchemas?: Record<string, Schema<unknown>>;
-}
-declare class FrameProcessor {
-    private storage;
-    private maxEntriesPerView;
-    private flushIntervalMs;
-    private schemas?;
-    private patchSchemas?;
-    private pendingUpdates;
-    private flushTimer;
-    private isProcessing;
-    constructor(storage: StorageAdapter, config?: FrameProcessorConfig);
-    private getSchema;
-    private normalizeEntity;
-    private hasSchema;
-    private normalizePathSegment;
-    private normalizePath;
-    private normalizeSortConfig;
-    private normalizeAppendPaths;
-    private extractSeq;
-    private getInternalSeq;
-    private attachInternalSeq;
-    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;
+type ProgramReadRequest = {
+    readonly operation: 'fetch';
+    readonly account: string;
+    readonly address: string;
+} | {
+    readonly operation: 'fetchMany';
+    readonly account: string;
+    readonly addresses: readonly string[];
+} | {
+    readonly operation: 'exists';
+    readonly account: string;
+    readonly address: string;
+};
+interface ProgramReadTransport {
+    read<T>(request: ProgramReadRequest): Promise<T>;
 }
 
 declare class MemoryAdapter implements StorageAdapter {
@@ -1679,11 +2351,12 @@ declare class MemoryAdapter implements StorageAdapter {
     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 createUpdateStream<T>(_storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry, query: SubscriptionQuery, keyFilter?: string, snapshotEnabled?: boolean): AsyncIterable<Update<T>>;
+declare function createEntityStream<T>(_storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry, query: SubscriptionQuery, options?: WatchOptions<any>, keyFilter?: string): AsyncIterable<T>;
+declare function createRichUpdateStream<T>(_storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry, query: SubscriptionQuery, keyFilter?: string, snapshotEnabled?: boolean): AsyncIterable<RichUpdate<T>>;
 
-declare function createTypedStateView<T>(viewDef: ViewDef<T, 'state'>, storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry): TypedStateView<T>;
+declare function serializeViewKey<TKey>(viewDef: ViewDef<unknown, 'state', TKey>, key: TKey): string;
+declare function createTypedStateView<T, TKey = unknown>(viewDef: ViewDef<T, 'state', TKey>, storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry): TypedStateView<T, DefaultViewKey<TKey>>;
 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']>;
 
@@ -1691,5 +2364,5 @@ declare const Arete: typeof Arete$1 & {
     session: typeof createSession;
 };
 
-export { ASSOCIATED_TOKEN_PROGRAM_ADDRESS, Arete, AreteError, ConnectionManager, DEFAULT_CONFIG, DEFAULT_MAX_ENTRIES_PER_VIEW, FrameProcessor, InstructionError, MemoryAdapter, OperationExecutionError, PROGRAM_OPERATION_EXTENSIONS, ReadRequestError, SPL_TOKEN_PROGRAM_ADDRESS, STACK_RUNTIME_EXTENSIONS, SYSTEM_PROGRAM_ADDRESS, SubscriptionRegistry, TOKEN_2022_PROGRAM_ADDRESS, account, appendFlowTransactions, appendTransactionInstructions, applyConnectedStackExtensions, arg, buildInstruction, bytes, chainAccountLoader, createChainClient, createEntityStream, createInstructionExecutor, createInstructionHandler, createPreparedFlow, createPreparedInstruction, createPreparedTransaction, createPreparedTransactionBody, createProgramPdas, createPublicKeySeed, createRichUpdateStream, createSeed, createSession, createSignerRegistry, createTypedListView, createTypedStateView, createTypedViews, createUpdateStream, decodeBase58, defineProgramExtensions, defineStackExtensions, deriveAssociatedTokenAccount, deriveHttpEndpoint, findProgramAddress as derivePda, describePreparedOperation, encodeBase58, executeInstruction, executePreparedOperation, extendProgram, extendPrograms, extendStack, findProgramAddress, findProgramAddressSync, flowOperation, formatPreparedOperation, formatProgramError, formatRawToUi, getMintDecimals, getProgramRuntimeExtensions, getStackRuntimeExtensions, instructionOperation, isEntityFrame, isSnapshotFrame, isSubscribedFrame, isValidFrame, literal, parseFrame, parseFrameFromBlob, parseInstructionError, parseUiAmountToRaw, pda, prependFlowTransactionInstructions, prependTransactionInstructions, programAccountRead, programQuery, resolveAccounts, resolveAmount, resolveAmountToRaw, resolveAmountsToRaw, resolveTokenProgramAddress, serializeInstructionData, stackQuery, toJsonValue, toRawAmount, transactionOperation, validateAccountResolution, withPrograms };
-export type { AccountCategory, AccountLoader, AccountMeta, AccountResolutionOptions, AccountResolutionResult, AmountInput, AnyOperation, AreteConfig, AreteOptions, AreteOptionsWithStorage, ArgSchema, ArgType, AuthConfig, AuthTokenResult, BuildOptions, BuiltAccountMeta, BuiltInstruction, ChainClient, ChainClock, ConfirmationLevel, ConnectOptions, ConnectedArete, ConnectedStackClient, ConnectionState, ConnectionStateCallback, CreatePreparedFlowInput, CreatePreparedInstructionInput, CreatePreparedTransactionInput, EntityFrame, ErrorMetadata, ExecuteOptions, ExecutionResult, ExtendedProgramDefinition, ExtendedStackDefinition, FlowOperation, FlowOperationNamespace, FlowOperationReceipt, Frame, FrameMode, FrameOp, FrameProcessorConfig, InstructionExecutor, InstructionHandler, InstructionHandlerConfig, InstructionOperation, InstructionOperationNamespace, JsonObject, JsonPrimitive, JsonValue, MergeProgramMaps, MintAccountInfo, NonEmptyReadonlyArray, OperationExecutionEvent, OperationExecutionHost, OperationExecutionOptions, OperationExecutionSuccessEvent, OperationKind, OperationNamespace, OperationPlan, OperationReceiptFor, OperationTransactionReceipt, PdaConfig, PdaDeriveContext, PdaFactory, PdaSeed, PreparedFlow, PreparedInstruction, PreparedOperation, PreparedOperationDescription, PreparedTransaction, PreparedTransactionBody, PreparedTransactionInstruction, PreparedTransactionOperation, ProgramAccountReadDefinition, ProgramError, ProgramExtensionInput, ProgramInterface, ProgramOperationContext, ProgramOperations, ProgramOperationsOf, ProgramPdas, ProgramQueryDefinition, ProgramRuntimeExtensionCarrier, ProgramRuntimeExtensions, ProgramSdkDefinition, ProgramsInterface, QueriesInterface, RawAccountInfo, RawInstructionsInterface, RawProgramsInterface, ReadTransportMethod, ResolvedAccount, ResolvedAccounts, RichUpdate, RichUpdateCallback, Schema, SchemaResult, SeedDef, SendOptions, SendResult, Session, SessionDefinition, SessionMemberOptions, SessionOptions, SignerRegistry, SingleTransactionOperationReceipt, SnapshotEntity, SnapshotFrame, SocketIssue, SocketIssueCallback, SortConfig, SortOrder, StackConnectedExtensions, StackDefinition, StackEndpoints, StackExtensionClient, StackExtensionInput, StackQueryDefinition, StackRuntimeExtensionCarrier, StackRuntimeExtensions, StackWithAttachedPrograms, StorageAdapter, StorageAdapterConfig, SubscribeCallback, SubscribedFrame, Subscription, TokenAccountInfo, TokenBalanceInfo, TransactionOperation, TransactionOperationNamespace, TransactionOptions, TypedAccountReader, TypedInstruction, TypedListView, TypedQueryExecutor, TypedStateView, TypedViewGroup, TypedViews, UnsubscribeFn, Update, UpdateCallback, ViewDef, ViewGroup, ViewSortConfig, WalletAdapter, WalletConnectOptions, WalletState, WatchOptions, WebSocketFactoryInit };
+export { ASSOCIATED_TOKEN_PROGRAM_ADDRESS, Arete, AreteError, ConnectionManager, DEFAULT_CONFIG, DEFAULT_MAX_ENTRIES_PER_VIEW, FrameProcessor, InstructionError, MemoryAdapter, OperationCallbackError, OperationExecutionError, PROGRAM_OPERATION_EXTENSIONS, ProcessedSlotTimeoutError, QueryStore, ReadRequestError, SPL_TOKEN_PROGRAM_ADDRESS, STACK_RUNTIME_EXTENSIONS, SYSTEM_PROGRAM_ADDRESS, SubscriptionRegistry, TOKEN_2022_PROGRAM_ADDRESS, TransactionExecutionError, TransactionTransportError, account, appendFlowTransactions, appendTransactionInstructions, applyConnectedStackExtensions, arg, buildInstruction, bytes, canonicalQueryKey, chainAccountLoader, createChainClient, createEntityStream, createHostedSolanaGatewayTransports, createInstructionExecutor, createInstructionHandler, createPreparedFlow, createPreparedInstruction, createPreparedTransaction, createPreparedTransactionBody, createProgramPdas, createPublicKeySeed, createRichUpdateStream, createSeed, createSession, createSignerRegistry, createSubscriptionId, createTransactionTransport, createTypedListView, createTypedStateView, createTypedViews, createUpdateStream, decodeBase58, defineProgramExtensions, defineStackExtensions, deriveAssociatedTokenAccount, deriveHttpEndpoint, findProgramAddress as derivePda, describePreparedOperation, encodeBase58, executeInstruction, executePreparedOperation, extendProgram, extendPrograms, extendStack, findProgramAddress, findProgramAddressSync, flowOperation, formatPreparedOperation, formatProgramError, formatRawToUi, getMintDecimals, getProgramRuntimeExtensions, getStackRuntimeExtensions, getTransactionFailureOutcome, inspectPreparedOperation, instructionOperation, isEntityFrame, isErrorFrame, isHostedAreteEndpoint, isSnapshotFrame, isSubscribedFrame, isUnsubscribedFrame, isValidFrame, literal, normalizeSubscription, normalizeSubscriptionQuery, normalizeSubscriptionRequest, normalizeTransactionError, parseFrame, parseFrameFromBlob, parseInstructionError, parseUiAmountToRaw, pda, prependFlowTransactionInstructions, prependTransactionInstructions, programAccountRead, programQuery, resolveAccounts, resolveAmount, resolveAmountToRaw, resolveAmountsToRaw, resolveTokenProgramAddress, safeToRawAmount, serializeInstructionData, serializeViewKey, stackQuery, stringifyBigints, toJsonValue, toRawAmount, transactionOperation, unwrapOperationExecutionError, validateAccountResolution, validateProgramReadDescriptor, validateSubscriptionId, withPrograms };
+export type { AccountCategory, AccountLoader, AccountMeta, AccountResolutionOptions, AccountResolutionResult, AmountInput, AnyOperation, AreteConfig, AreteOptions, AreteOptionsWithStorage, ArgSchema, ArgType, AuthConfig, AuthTokenRequest, AuthTokenResult, AuthTokenTarget, BuildOptions, BuiltAccountMeta, BuiltInstruction, ChainClient, ChainClock, ChainFailedTransactionOutcome, CompositionSessionOptions, ConfirmationLevel, ConfirmedTransactionOutcome, ConnectOptions, ConnectedArete, ConnectedStackClient, ConnectionState, ConnectionStateCallback, ContextSlotOptions, CreatePreparedFlowInput, CreatePreparedInstructionInput, CreatePreparedTransactionInput, DefaultViewKey, EntityFrame, ErrorFrame, ErrorMetadata, ExecuteOptions, ExecutionResult, ExtendedProgramDefinition, ExtendedStackDefinition, FlowOperation, FlowOperationNamespace, FlowOperationReceipt, Frame, FrameMode, FrameOp, FrameProcessorConfig, FrameValidationDiagnostic, HostedSolanaGatewayBindings, HostedSolanaGatewayCapabilityBinding, HostedSolanaGatewayTransportOptions, HostedSolanaGatewayTransports, HttpAuthMetadata, InstructionExecutor, InstructionHandler, InstructionHandlerConfig, InstructionOperation, InstructionOperationNamespace, JsonObject, JsonPrimitive, JsonValue, LatestBlockhashResult, MergeProgramMaps, MintAccountInfo, NativeBalanceInfo, NonEmptyReadonlyArray, NotSubmittedTransactionOutcome, OperationCallbackPhase, OperationExecutionEvent, OperationExecutionHost, OperationExecutionOptions, OperationExecutionSuccessEvent, OperationInspection, OperationInspectionOptions, OperationKind, OperationNamespace, OperationPlan, OperationReceiptFor, OperationTransactionReceipt, PdaConfig, PdaDeriveContext, PdaFactory, PdaSeed, PreparedFlow, PreparedInstruction, PreparedOperation, PreparedOperationDescription, PreparedTransaction, PreparedTransactionBody, PreparedTransactionInstruction, PreparedTransactionOperation, ProgramAccountBatchItem, ProgramAccountBatchResult, ProgramAccountReadDefinition, ProgramError, ProgramExtensionInput, ProgramInterface, ProgramOperationContext, ProgramOperations, ProgramOperationsOf, ProgramPdas, ProgramQueryDefinition, ProgramReadBinding, ProgramReadBindingAuthTarget, ProgramReadDescriptor, ProgramReadDescriptors, ProgramReadOverride, ProgramReadOverrides, ProgramReadRequest, ProgramReadTransport, ProgramReleaseReference, ProgramRuntimeExtensionCarrier, ProgramRuntimeExtensions, ProgramSdkDefinition, ProgramsInterface, QueriesInterface, QueryLease, QuerySnapshot, RawAccountInfo, RawInstructionsInterface, RawProgramsInterface, ReadArgumentCount, ReadArgumentCounts, ReadTransportMethod, ResolvedAccount, ResolvedAccounts, RichUpdate, RichUpdateCallback, Schema, SchemaResult, SeedDef, SendOptions, SendResult, Session, SessionDefinition, SessionMemberOptions, SessionOptions, SignerRegistry, SingleTransactionOperationReceipt, SnapshotEntity, SnapshotFrame, SocketIssue, SocketIssueCallback, SolanaGatewayAuthMetadata, SolanaGatewayAuthScope, SolanaGatewayBindingAuthTarget, SortConfig, SortOrder, StackConnectedExtensions, StackDefinition, StackEndpoints, StackExtensionClient, StackExtensionInput, StackQueryDefinition, StackRuntimeExtensionCarrier, StackRuntimeExtensions, StackWithAttachedPrograms, StorageAdapter, StorageAdapterConfig, StringifiedBigints, SubmittedUnknownTransactionOutcome, SubscribeCallback, SubscribedFrame, Subscription, SubscriptionIdentity, SubscriptionOptions, SubscriptionQuery, SubscriptionRequest, SubscriptionSnapshotOptions, TokenAccountInfo, TokenBalanceInfo, TokenBalanceInput, TransactionCommitment, TransactionFailureOutcome, TransactionFailurePhase, TransactionFailureStatus, TransactionFeeResult, TransactionInspectionOptions, TransactionInspectionResult, TransactionOperation, TransactionOperationNamespace, TransactionOptions, TransactionOutcome, TransactionRequestContext, TransactionSendOptions, TransactionSendResult, TransactionSignatureStatus, TransactionSimulationOptions, TransactionSimulationResult, TransactionTransport, TransactionTransportErrorBody, TypedAccountReader, TypedInstruction, TypedListView, TypedQueryExecutor, TypedStateView, TypedViewGroup, TypedViews, UnsubscribeFn, UnsubscribedFrame, Update, UpdateCallback, ViewDef, ViewGroup, ViewKeyFields, ViewKeyValue, ViewSortConfig, WaitForProcessedSlotOptions, WalletAdapter, WalletConnectOptions, WalletExecutionContext, WalletState, WatchOptions, WebSocketFactoryInit };