hyperstack-typescript 0.4.3 → 0.5.1

package/dist/index.d.ts

@@ -92,7 +92,7 @@ interface ResolvedAccount {
  * Result of account resolution.
  */
 interface AccountResolutionResult {
-    /** All resolved accounts */
+    /** All resolved accounts in order */
     accounts: ResolvedAccount[];
     /** Accounts that need to be provided by the user */
     missingUserAccounts: string[];
@@ -105,13 +105,19 @@ interface AccountResolutionOptions {
     accounts?: Record<string, string>;
     /** Wallet adapter for signer accounts */
     wallet?: WalletAdapter;
+    /** Program ID for PDA derivation (required if any PDAs exist) */
+    programId?: string;
 }
 /**
  * Resolves instruction accounts by categorizing and deriving addresses.
  *
+ * Resolution order:
+ * 1. Non-PDA accounts (signer, known, userProvided) are resolved first
+ * 2. PDA accounts are resolved in dependency order (accounts they reference come first)
+ *
  * @param accountMetas - Account metadata from the instruction definition
- * @param args - Instruction arguments (used for PDA derivation)
- * @param options - Resolution options including wallet and user-provided accounts
+ * @param args - Instruction arguments (used for PDA derivation with argRef seeds)
+ * @param options - Resolution options including wallet, user-provided accounts, and programId
  * @returns Resolved accounts and any missing required accounts
  */
 declare function resolveAccounts(accountMetas: AccountMeta[], args: Record<string, unknown>, options: AccountResolutionOptions): AccountResolutionResult;
@@ -124,35 +130,52 @@ declare function resolveAccounts(accountMetas: AccountMeta[], args: Record<strin
 declare function validateAccountResolution(result: AccountResolutionResult): void;
 
 /**
- * Derives a Program-Derived Address (PDA) from seeds and program ID.
+ * PDA (Program Derived Address) derivation utilities.
  *
- * 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)
+ * Implements Solana's PDA derivation algorithm without depending on @solana/web3.js.
+ */
+/**
+ * Decode base58 string to Uint8Array.
+ */
+declare function decodeBase58(str: string): Uint8Array;
+/**
+ * Encode Uint8Array to base58 string.
+ */
+declare function encodeBase58(bytes: Uint8Array): string;
+/**
+ * Derives a Program-Derived Address (PDA) from seeds and program ID.
  *
- * Note: This is a placeholder implementation. In production, you would use
- * the actual Solana web3.js library's PDA derivation.
+ * Algorithm:
+ * 1. For bump = 255 down to 0:
+ *    a. Concatenate: seeds + [bump] + programId + "ProgramDerivedAddress"
+ *    b. SHA-256 hash the concatenation
+ *    c. If result is off the ed25519 curve, return it
+ * 2. If no valid PDA found after 256 attempts, throw error
  *
- * @param seeds - Array of seed buffers
- * @param programId - The program ID (as base58 string)
- * @returns The derived PDA address (base58 string)
+ * @param seeds - Array of seed buffers (max 32 bytes each, max 16 seeds)
+ * @param programId - The program ID (base58 string)
+ * @returns Tuple of [derivedAddress (base58), bumpSeed]
+ */
+declare function findProgramAddress(seeds: Uint8Array[], programId: string): Promise<[string, number]>;
+/**
+ * Synchronous version of findProgramAddress.
+ * Uses synchronous SHA-256 (Node.js crypto module).
  */
-declare function derivePda(seeds: Buffer[], programId: string): Promise<string>;
+declare function findProgramAddressSync(seeds: Uint8Array[], programId: string): [string, number];
 /**
  * Creates a seed buffer from various input types.
  *
  * @param value - The value to convert to a seed
- * @returns Buffer suitable for PDA derivation
+ * @returns Uint8Array suitable for PDA derivation
  */
-declare function createSeed(value: string | Buffer | Uint8Array | bigint): Buffer;
+declare function createSeed(value: string | Uint8Array | bigint | number): Uint8Array;
 /**
  * Creates a public key seed from a base58-encoded address.
  *
  * @param address - Base58-encoded public key
- * @returns 32-byte buffer
+ * @returns 32-byte Uint8Array
  */
-declare function createPublicKeySeed(address: string): Buffer;
+declare function createPublicKeySeed(address: string): Uint8Array;
 
 /**
  * Borsh-compatible instruction data serializer.
@@ -314,6 +337,8 @@ interface InstructionHandler {
     accounts: AccountMeta[];
     /** Error definitions - used by core SDK for error parsing */
     errors: ErrorMetadata[];
+    /** Program ID for this instruction (used for PDA derivation) */
+    programId?: string;
 }
 /**
  * @deprecated Use InstructionHandler instead. Will be removed in next major version.
@@ -358,6 +383,40 @@ declare function createInstructionExecutor(wallet: WalletAdapter): {
     execute: (handler: InstructionHandler, args: Record<string, unknown>, options?: Omit<ExecuteOptions, "wallet">) => Promise<ExecutionResult>;
 };
 
+type SeedDef = {
+    type: 'literal';
+    value: string;
+} | {
+    type: 'bytes';
+    value: Uint8Array;
+} | {
+    type: 'argRef';
+    argName: string;
+    argType?: string;
+} | {
+    type: 'accountRef';
+    accountName: string;
+};
+interface PdaDeriveContext {
+    accounts?: Record<string, string>;
+    args?: Record<string, unknown>;
+    programId?: string;
+}
+interface PdaFactory {
+    readonly seeds: readonly SeedDef[];
+    readonly programId: string;
+    program(programId: string): PdaFactory;
+    derive(context: PdaDeriveContext): Promise<string>;
+    deriveSync(context: PdaDeriveContext): string;
+}
+declare function literal(value: string): SeedDef;
+declare function account(name: string): SeedDef;
+declare function arg(name: string, type?: string): SeedDef;
+declare function bytes(value: Uint8Array): SeedDef;
+declare function pda(programId: string, ...seeds: SeedDef[]): PdaFactory;
+type ProgramPdas<T extends Record<string, PdaFactory>> = T;
+declare function createProgramPdas<T extends Record<string, PdaFactory>>(pdas: T): ProgramPdas<T>;
+
 type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error';
 type Update<T> = {
     type: 'upsert';
@@ -395,6 +454,7 @@ interface StackDefinition {
     readonly name: string;
     readonly url: string;
     readonly views: Record<string, ViewGroup>;
+    readonly schemas?: Record<string, Schema<unknown>>;
     instructions?: Record<string, InstructionHandler>;
 }
 interface ViewGroup {
@@ -409,16 +469,28 @@ interface Subscription {
     take?: number;
     skip?: number;
 }
-interface WatchOptions {
+type SchemaResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: unknown;
+};
+interface Schema<T> {
+    safeParse: (input: unknown) => SchemaResult<T>;
+}
+interface WatchOptions<TSchema = unknown> {
     take?: number;
     skip?: number;
     filters?: Record<string, string>;
+    schema?: Schema<TSchema>;
 }
 interface HyperStackOptions<TStack extends StackDefinition> {
     stack: TStack;
     autoReconnect?: boolean;
     reconnectIntervals?: number[];
     maxReconnectAttempts?: number;
+    validateFrames?: boolean;
 }
 declare const DEFAULT_MAX_ENTRIES_PER_VIEW = 10000;
 interface HyperStackConfig {
@@ -441,14 +513,14 @@ type TypedViewGroup<TGroup> = {
     [K in keyof TGroup]: TGroup[K] extends ViewDef<infer T, 'state'> ? TypedStateView<T> : TGroup[K] extends ViewDef<infer T, 'list'> ? TypedListView<T> : never;
 };
 interface TypedStateView<T> {
-    use(key: string, options?: WatchOptions): AsyncIterable<T>;
+    use<TSchema = T>(key: string, options?: WatchOptions<TSchema>): AsyncIterable<TSchema>;
     watch(key: string, options?: WatchOptions): AsyncIterable<Update<T>>;
     watchRich(key: string, options?: WatchOptions): AsyncIterable<RichUpdate<T>>;
     get(key: string): Promise<T | null>;
     getSync(key: string): T | null | undefined;
 }
 interface TypedListView<T> {
-    use(options?: WatchOptions): AsyncIterable<T>;
+    use<TSchema = T>(options?: WatchOptions<TSchema>): AsyncIterable<TSchema>;
     watch(options?: WatchOptions): AsyncIterable<Update<T>>;
     watchRich(options?: WatchOptions): AsyncIterable<RichUpdate<T>>;
     get(): Promise<T[]>;
@@ -585,6 +657,7 @@ interface ConnectOptions {
     reconnectIntervals?: number[];
     maxReconnectAttempts?: number;
     flushIntervalMs?: number;
+    validateFrames?: boolean;
 }
 /** @deprecated Use ConnectOptions instead */
 interface HyperStackOptionsWithStorage<TStack extends StackDefinition> extends HyperStackOptions<TStack> {
@@ -637,15 +710,19 @@ interface FrameProcessorConfig {
      * reduce unnecessary re-renders during high-frequency updates.
      */
     flushIntervalMs?: number;
+    schemas?: Record<string, Schema<unknown>>;
 }
 declare class FrameProcessor {
     private storage;
     private maxEntriesPerView;
     private flushIntervalMs;
+    private schemas?;
     private pendingUpdates;
     private flushTimer;
     private isProcessing;
     constructor(storage: StorageAdapter, config?: FrameProcessorConfig);
+    private getSchema;
+    private validateEntity;
     handleFrame<T>(frame: Frame<T>): void;
     /**
      * Immediately flush all pending updates.
@@ -731,12 +808,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 createEntityStream<T>(storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry, subscription: Subscription, options?: WatchOptions<any>, keyFilter?: string): AsyncIterable<T>;
 declare function createRichUpdateStream<T>(storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry, subscription: Subscription, keyFilter?: string): AsyncIterable<RichUpdate<T>>;
 
 declare function createTypedStateView<T>(viewDef: ViewDef<T, 'state'>, storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry): TypedStateView<T>;
 declare function createTypedListView<T>(viewDef: ViewDef<T, 'list'>, storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry): TypedListView<T>;
 declare function createTypedViews<TStack extends StackDefinition>(stack: TStack, storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry): TypedViews<TStack['views']>;
 
-export { 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, ConnectOptions, 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 };
+export { ConnectionManager, DEFAULT_CONFIG, DEFAULT_MAX_ENTRIES_PER_VIEW, EntityStore, FrameProcessor, HyperStack, HyperStackError, MemoryAdapter, SubscriptionRegistry, account, arg, bytes, createEntityStream, createInstructionExecutor, createProgramPdas, createPublicKeySeed, createRichUpdateStream, createSeed, createTypedListView, createTypedStateView, createTypedViews, createUpdateStream, decodeBase58, findProgramAddress as derivePda, encodeBase58, executeInstruction, findProgramAddress, findProgramAddressSync, formatProgramError, isEntityFrame, isSnapshotFrame, isSubscribedFrame, isValidFrame, literal, parseFrame, parseFrameFromBlob, parseInstructionError, pda, resolveAccounts, serializeInstructionData, validateAccountResolution, waitForConfirmation };
+export type { AccountCategory, AccountMeta, AccountResolutionOptions, AccountResolutionResult, ArgSchema, ArgType, BuiltInstruction, ConfirmationLevel, ConnectionState, ConnectionStateCallback, EntityFrame, EntityStoreConfig, ErrorMetadata, ExecuteOptions, ExecutionResult, Frame, FrameMode, FrameOp, FrameProcessorConfig, HyperStackConfig, HyperStackOptions, HyperStackOptionsWithStorage, InstructionDefinition, InstructionExecutor, InstructionExecutorOptions, InstructionHandler, PdaConfig, PdaDeriveContext, PdaFactory, PdaSeed, ProgramError, ProgramPdas, ResolvedAccount, ResolvedAccounts, RichUpdate, RichUpdateCallback$1 as RichUpdateCallback, Schema, SchemaResult, SeedDef, 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 };