hyperstack-typescript 0.3.13 → 0.3.15

package/dist/index.d.ts

@@ -1,3 +1,363 @@
+/**
+ * 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 */
+    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;
+}
+/**
+ * Resolves instruction accounts by categorizing and deriving addresses.
+ *
+ * @param accountMetas - Account metadata from the instruction definition
+ * @param args - Instruction arguments (used for PDA derivation)
+ * @param options - Resolution options including wallet and user-provided accounts
+ * @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;
+
+/**
+ * Derives a Program-Derived Address (PDA) from seeds and program ID.
+ *
+ * This function implements PDA derivation using the Solana algorithm:
+ * 1. Concatenate all seeds
+ * 2. Hash with SHA-256
+ * 3. Check if result is off-curve (valid PDA)
+ *
+ * Note: This is a placeholder implementation. In production, you would use
+ * the actual Solana web3.js library's PDA derivation.
+ *
+ * @param seeds - Array of seed buffers
+ * @param programId - The program ID (as base58 string)
+ * @returns The derived PDA address (base58 string)
+ */
+declare function derivePda(seeds: Buffer[], programId: string): Promise<string>;
+/**
+ * Creates a seed buffer from various input types.
+ *
+ * @param value - The value to convert to a seed
+ * @returns Buffer suitable for PDA derivation
+ */
+declare function createSeed(value: string | Buffer | Uint8Array | bigint): Buffer;
+/**
+ * Creates a public key seed from a base58-encoded address.
+ *
+ * @param address - Base58-encoded public key
+ * @returns 32-byte buffer
+ */
+declare function createPublicKeySeed(address: string): Buffer;
+
+/**
+ * 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[];
+}
+/**
+ * @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 ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error';
 type Update<T> = {
     type: 'upsert';
@@ -33,7 +393,9 @@ interface ViewDef<T, TMode extends 'state' | 'list'> {
 }
 interface StackDefinition {
     readonly name: string;
+    readonly url: string;
     readonly views: Record<string, ViewGroup>;
+    instructions?: Record<string, InstructionHandler>;
 }
 interface ViewGroup {
     state?: ViewDef<unknown, 'state'>;
@@ -47,6 +409,11 @@ interface Subscription {
     take?: number;
     skip?: number;
 }
+interface WatchOptions {
+    take?: number;
+    skip?: number;
+    filters?: Record<string, string>;
+}
 interface HyperStackOptions<TStack extends StackDefinition> {
     stack: TStack;
     autoReconnect?: boolean;
@@ -71,22 +438,19 @@ type TypedViews<TViews extends StackDefinition['views']> = {
     [K in keyof TViews]: TypedViewGroup<TViews[K]>;
 };
 type TypedViewGroup<TGroup> = {
-    state: TGroup extends {
-        state: ViewDef<infer T, 'state'>;
-    } ? TypedStateView<T> : never;
-    list: TGroup extends {
-        list: ViewDef<infer T, 'list'>;
-    } ? TypedListView<T> : never;
+    [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> {
-    watch(key: string): AsyncIterable<Update<T>>;
-    watchRich(key: string): AsyncIterable<RichUpdate<T>>;
+    use(key: string, options?: WatchOptions): AsyncIterable<T>;
+    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> {
-    watch(): AsyncIterable<Update<T>>;
-    watchRich(): AsyncIterable<RichUpdate<T>>;
+    use(options?: WatchOptions): AsyncIterable<T>;
+    watch(options?: WatchOptions): AsyncIterable<Update<T>>;
+    watchRich(options?: WatchOptions): AsyncIterable<RichUpdate<T>>;
     get(): Promise<T[]>;
     getSync(): T[] | undefined;
 }
@@ -213,10 +577,26 @@ declare class SubscriptionRegistry {
     private makeSubKey;
 }
 
+interface ConnectOptions {
+    url?: string;
+    storage?: StorageAdapter;
+    maxEntriesPerView?: number | null;
+    autoReconnect?: boolean;
+    reconnectIntervals?: number[];
+    maxReconnectAttempts?: number;
+}
+/** @deprecated Use ConnectOptions instead */
 interface HyperStackOptionsWithStorage<TStack extends StackDefinition> extends HyperStackOptions<TStack> {
     storage?: StorageAdapter;
     maxEntriesPerView?: number | null;
 }
+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 HyperStack<TStack extends StackDefinition> {
     private readonly connection;
     private readonly storage;
@@ -224,9 +604,12 @@ declare class HyperStack<TStack extends StackDefinition> {
     private readonly subscriptionRegistry;
     private readonly _views;
     private readonly stack;
+    private readonly _instructions;
     private constructor();
-    static connect<T extends StackDefinition>(url: string, options: HyperStackOptionsWithStorage<T>): Promise<HyperStack<T>>;
+    private buildInstructions;
+    static connect<T extends StackDefinition>(stack: T, options?: ConnectOptions): Promise<HyperStack<T>>;
     get views(): TypedViews<TStack['views']>;
+    get instructions(): InstructionsInterface<TStack['instructions']>;
     get connectionState(): ConnectionState;
     get stackName(): string;
     get store(): StorageAdapter;
@@ -346,11 +729,12 @@ declare class MemoryAdapter implements StorageAdapter {
 }
 
 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, 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 { ConnectionManager, DEFAULT_CONFIG, DEFAULT_MAX_ENTRIES_PER_VIEW, EntityStore, FrameProcessor, HyperStack, HyperStackError, MemoryAdapter, SubscriptionRegistry, createRichUpdateStream, createTypedListView, createTypedStateView, createTypedViews, createUpdateStream, isEntityFrame, isSnapshotFrame, isSubscribedFrame, isValidFrame, parseFrame, parseFrameFromBlob };
-export type { ConnectionState, ConnectionStateCallback, EntityFrame, EntityStoreConfig, Frame, FrameMode, FrameOp, FrameProcessorConfig, HyperStackConfig, HyperStackOptions, HyperStackOptionsWithStorage, RichUpdate, RichUpdateCallback$1 as RichUpdateCallback, SnapshotEntity, SnapshotFrame, SortConfig, SortOrder, StackDefinition, StorageAdapter, StorageAdapterConfig, SubscribeCallback, SubscribedFrame, Subscription, TypedListView, TypedStateView, TypedViewGroup, TypedViews, UnsubscribeFn, Update, UpdateCallback, ViewConfig, ViewDef, ViewGroup, ViewSortConfig };
+export { ConnectionManager, DEFAULT_CONFIG, DEFAULT_MAX_ENTRIES_PER_VIEW, EntityStore, FrameProcessor, HyperStack, HyperStackError, MemoryAdapter, SubscriptionRegistry, createEntityStream, createInstructionExecutor, createPublicKeySeed, createRichUpdateStream, createSeed, createTypedListView, createTypedStateView, createTypedViews, createUpdateStream, derivePda, executeInstruction, formatProgramError, isEntityFrame, isSnapshotFrame, isSubscribedFrame, isValidFrame, parseFrame, parseFrameFromBlob, parseInstructionError, resolveAccounts, serializeInstructionData, validateAccountResolution, waitForConfirmation };
+export type { AccountCategory, AccountMeta, AccountResolutionOptions, AccountResolutionResult, ArgSchema, ArgType, BuiltInstruction, ConfirmationLevel, ConnectionState, ConnectionStateCallback, EntityFrame, EntityStoreConfig, ErrorMetadata, ExecuteOptions, ExecutionResult, Frame, FrameMode, FrameOp, FrameProcessorConfig, HyperStackConfig, HyperStackOptions, HyperStackOptionsWithStorage, InstructionDefinition, InstructionExecutor, InstructionExecutorOptions, InstructionHandler, PdaConfig, PdaSeed, ProgramError, ResolvedAccount, ResolvedAccounts, RichUpdate, RichUpdateCallback$1 as RichUpdateCallback, SnapshotEntity, SnapshotFrame, SortConfig, SortOrder, StackDefinition, StorageAdapter, StorageAdapterConfig, SubscribeCallback, SubscribedFrame, Subscription, TypedListView, TypedStateView, TypedViewGroup, TypedViews, UnsubscribeFn, Update, UpdateCallback, ViewConfig, ViewDef, ViewGroup, ViewSortConfig, WalletAdapter, WalletConnectOptions, WalletState, WatchOptions };