hyperstack-typescript 0.3.13 → 0.3.15

package/dist/index.js

@@ -741,6 +741,69 @@ function createUpdateStream(storage, subscriptionRegistry, subscription, keyFilt
         },
     };
 }
+function createEntityStream(storage, subscriptionRegistry, subscription, keyFilter) {
+    return {
+        [Symbol.asyncIterator]() {
+            const queue = [];
+            let waitingResolve = null;
+            let unsubscribeStorage = null;
+            let unsubscribeRegistry = null;
+            let done = false;
+            const handler = (viewPath, key, update) => {
+                if (viewPath !== subscription.view)
+                    return;
+                if (keyFilter !== undefined && key !== keyFilter)
+                    return;
+                if (update.type === 'deleted')
+                    return;
+                const entity = (update.type === 'created' ? update.data : update.after);
+                if (waitingResolve) {
+                    const resolve = waitingResolve;
+                    waitingResolve = null;
+                    resolve({ value: entity, done: false });
+                }
+                else {
+                    if (queue.length >= MAX_QUEUE_SIZE) {
+                        queue.shift();
+                    }
+                    queue.push(entity);
+                }
+            };
+            const start = () => {
+                unsubscribeStorage = storage.onRichUpdate(handler);
+                unsubscribeRegistry = subscriptionRegistry.subscribe(subscription);
+            };
+            const cleanup = () => {
+                done = true;
+                unsubscribeStorage?.();
+                unsubscribeRegistry?.();
+            };
+            start();
+            return {
+                async next() {
+                    if (done) {
+                        return { value: undefined, done: true };
+                    }
+                    const queued = queue.shift();
+                    if (queued) {
+                        return { value: queued, done: false };
+                    }
+                    return new Promise((resolve) => {
+                        waitingResolve = resolve;
+                    });
+                },
+                async return() {
+                    cleanup();
+                    return { value: undefined, done: true };
+                },
+                async throw(error) {
+                    cleanup();
+                    throw error;
+                },
+            };
+        },
+    };
+}
 function createRichUpdateStream(storage, subscriptionRegistry, subscription, keyFilter) {
     return {
         [Symbol.asyncIterator]() {
@@ -808,11 +871,14 @@ function createRichUpdateStream(storage, subscriptionRegistry, subscription, key
 
 function createTypedStateView(viewDef, storage, subscriptionRegistry) {
     return {
-        watch(key) {
-            return createUpdateStream(storage, subscriptionRegistry, { view: viewDef.view, key }, key);
+        use(key, options) {
+            return createEntityStream(storage, subscriptionRegistry, { view: viewDef.view, key, ...options }, key);
         },
-        watchRich(key) {
-            return createRichUpdateStream(storage, subscriptionRegistry, { view: viewDef.view, key }, key);
+        watch(key, options) {
+            return createUpdateStream(storage, subscriptionRegistry, { view: viewDef.view, key, ...options }, key);
+        },
+        watchRich(key, options) {
+            return createRichUpdateStream(storage, subscriptionRegistry, { view: viewDef.view, key, ...options }, key);
         },
         async get(key) {
             return storage.get(viewDef.view, key);
@@ -824,11 +890,14 @@ function createTypedStateView(viewDef, storage, subscriptionRegistry) {
 }
 function createTypedListView(viewDef, storage, subscriptionRegistry) {
     return {
-        watch() {
-            return createUpdateStream(storage, subscriptionRegistry, { view: viewDef.view });
+        use(options) {
+            return createEntityStream(storage, subscriptionRegistry, { view: viewDef.view, ...options });
+        },
+        watch(options) {
+            return createUpdateStream(storage, subscriptionRegistry, { view: viewDef.view, ...options });
         },
-        watchRich() {
-            return createRichUpdateStream(storage, subscriptionRegistry, { view: viewDef.view });
+        watchRich(options) {
+            return createRichUpdateStream(storage, subscriptionRegistry, { view: viewDef.view, ...options });
         },
         async get() {
             return storage.getAll(viewDef.view);
@@ -840,20 +909,512 @@ function createTypedListView(viewDef, storage, subscriptionRegistry) {
 }
 function createTypedViews(stack, storage, subscriptionRegistry) {
     const views = {};
-    for (const [viewName, viewGroup] of Object.entries(stack.views)) {
+    for (const [entityName, viewGroup] of Object.entries(stack.views)) {
         const group = viewGroup;
         const typedGroup = {};
-        if (group.state) {
-            typedGroup.state = createTypedStateView(group.state, storage, subscriptionRegistry);
-        }
-        if (group.list) {
-            typedGroup.list = createTypedListView(group.list, storage, subscriptionRegistry);
+        for (const [viewName, viewDef] of Object.entries(group)) {
+            if (viewDef.mode === 'state') {
+                typedGroup[viewName] = createTypedStateView(viewDef, storage, subscriptionRegistry);
+            }
+            else if (viewDef.mode === 'list') {
+                typedGroup[viewName] = createTypedListView(viewDef, storage, subscriptionRegistry);
+            }
         }
-        views[viewName] = typedGroup;
+        views[entityName] = typedGroup;
     }
     return views;
 }
 
+/**
+ * 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
+ */
+function resolveAccounts(accountMetas, args, options) {
+    const resolved = [];
+    const missing = [];
+    for (const meta of accountMetas) {
+        const resolvedAccount = resolveSingleAccount(meta, args, options);
+        if (resolvedAccount) {
+            resolved.push(resolvedAccount);
+        }
+        else if (!meta.isOptional) {
+            missing.push(meta.name);
+        }
+    }
+    return {
+        accounts: resolved,
+        missingUserAccounts: missing,
+    };
+}
+function resolveSingleAccount(meta, args, options) {
+    switch (meta.category) {
+        case 'signer':
+            return resolveSignerAccount(meta, options.wallet);
+        case 'known':
+            return resolveKnownAccount(meta);
+        case 'pda':
+            return resolvePdaAccount(meta);
+        case 'userProvided':
+            return resolveUserProvidedAccount(meta, options.accounts);
+        default:
+            return null;
+    }
+}
+function resolveSignerAccount(meta, wallet) {
+    if (!wallet) {
+        return null;
+    }
+    return {
+        name: meta.name,
+        address: wallet.publicKey,
+        isSigner: true,
+        isWritable: meta.isWritable,
+    };
+}
+function resolveKnownAccount(meta) {
+    if (!meta.knownAddress) {
+        return null;
+    }
+    return {
+        name: meta.name,
+        address: meta.knownAddress,
+        isSigner: meta.isSigner,
+        isWritable: meta.isWritable,
+    };
+}
+function resolvePdaAccount(meta, args) {
+    if (!meta.pdaConfig) {
+        return null;
+    }
+    // PDA derivation will be implemented in pda.ts
+    // For now, return a placeholder that will be resolved later
+    return {
+        name: meta.name,
+        address: '', // Will be derived
+        isSigner: meta.isSigner,
+        isWritable: meta.isWritable,
+    };
+}
+function resolveUserProvidedAccount(meta, accounts) {
+    const address = accounts?.[meta.name];
+    if (!address) {
+        return null;
+    }
+    return {
+        name: meta.name,
+        address,
+        isSigner: meta.isSigner,
+        isWritable: meta.isWritable,
+    };
+}
+/**
+ * Validates that all required accounts are present.
+ *
+ * @param result - Account resolution result
+ * @throws Error if any required accounts are missing
+ */
+function validateAccountResolution(result) {
+    if (result.missingUserAccounts.length > 0) {
+        throw new Error(`Missing required accounts: ${result.missingUserAccounts.join(', ')}`);
+    }
+}
+
+/**
+ * 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)
+ */
+async function derivePda(seeds, programId) {
+    // In production, this would use:
+    // PublicKey.findProgramAddressSync(seeds, new PublicKey(programId))
+    // For now, return a placeholder that will be replaced with actual implementation
+    const combined = Buffer.concat(seeds);
+    // Simulate PDA derivation (this is NOT the actual algorithm)
+    const hash = await simulateHash(combined);
+    // Return base58-encoded address
+    return bs58Encode(hash);
+}
+/**
+ * Creates a seed buffer from various input types.
+ *
+ * @param value - The value to convert to a seed
+ * @returns Buffer suitable for PDA derivation
+ */
+function createSeed(value) {
+    if (Buffer.isBuffer(value)) {
+        return value;
+    }
+    if (value instanceof Uint8Array) {
+        return Buffer.from(value);
+    }
+    if (typeof value === 'string') {
+        return Buffer.from(value, 'utf-8');
+    }
+    if (typeof value === 'bigint') {
+        // Convert bigint to 8-byte buffer (u64)
+        const buffer = Buffer.alloc(8);
+        buffer.writeBigUInt64LE(value);
+        return buffer;
+    }
+    throw new Error(`Cannot create seed from type: ${typeof value}`);
+}
+/**
+ * Creates a public key seed from a base58-encoded address.
+ *
+ * @param address - Base58-encoded public key
+ * @returns 32-byte buffer
+ */
+function createPublicKeySeed(address) {
+    // In production, decode base58 to 32-byte buffer
+    // For now, return placeholder
+    return Buffer.alloc(32);
+}
+async function simulateHash(data) {
+    // In production, use actual SHA-256
+    // This is a placeholder
+    if (typeof crypto !== 'undefined' && crypto.subtle) {
+        const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+        return Buffer.from(hashBuffer);
+    }
+    // Fallback for Node.js
+    return Buffer.alloc(32, 0);
+}
+function bs58Encode(buffer) {
+    // In production, use actual base58 encoding
+    // This is a placeholder
+    return 'P' + buffer.toString('hex').slice(0, 31);
+}
+
+/**
+ * Borsh-compatible instruction data serializer.
+ *
+ * This module handles serializing instruction arguments into the binary format
+ * expected by Solana programs using Borsh serialization.
+ */
+/**
+ * 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
+ */
+function serializeInstructionData(discriminator, args, schema) {
+    const buffers = [Buffer.from(discriminator)];
+    for (const field of schema) {
+        const value = args[field.name];
+        const serialized = serializeValue(value, field.type);
+        buffers.push(serialized);
+    }
+    return Buffer.concat(buffers);
+}
+function serializeValue(value, type) {
+    if (typeof type === 'string') {
+        return serializePrimitive(value, type);
+    }
+    if ('vec' in type) {
+        return serializeVec(value, type.vec);
+    }
+    if ('option' in type) {
+        return serializeOption(value, type.option);
+    }
+    if ('array' in type) {
+        return serializeArray(value, type.array[0], type.array[1]);
+    }
+    throw new Error(`Unknown type: ${JSON.stringify(type)}`);
+}
+function serializePrimitive(value, type) {
+    switch (type) {
+        case 'u8':
+            return Buffer.from([value]);
+        case 'u16':
+            const u16 = Buffer.alloc(2);
+            u16.writeUInt16LE(value, 0);
+            return u16;
+        case 'u32':
+            const u32 = Buffer.alloc(4);
+            u32.writeUInt32LE(value, 0);
+            return u32;
+        case 'u64':
+            const u64 = Buffer.alloc(8);
+            u64.writeBigUInt64LE(BigInt(value), 0);
+            return u64;
+        case 'u128':
+            // u128 is 16 bytes, little-endian
+            const u128 = Buffer.alloc(16);
+            const bigU128 = BigInt(value);
+            u128.writeBigUInt64LE(bigU128 & BigInt('0xFFFFFFFFFFFFFFFF'), 0);
+            u128.writeBigUInt64LE(bigU128 >> BigInt(64), 8);
+            return u128;
+        case 'i8':
+            return Buffer.from([value]);
+        case 'i16':
+            const i16 = Buffer.alloc(2);
+            i16.writeInt16LE(value, 0);
+            return i16;
+        case 'i32':
+            const i32 = Buffer.alloc(4);
+            i32.writeInt32LE(value, 0);
+            return i32;
+        case 'i64':
+            const i64 = Buffer.alloc(8);
+            i64.writeBigInt64LE(BigInt(value), 0);
+            return i64;
+        case 'i128':
+            const i128 = Buffer.alloc(16);
+            const bigI128 = BigInt(value);
+            i128.writeBigInt64LE(bigI128 & BigInt('0xFFFFFFFFFFFFFFFF'), 0);
+            i128.writeBigInt64LE(bigI128 >> BigInt(64), 8);
+            return i128;
+        case 'bool':
+            return Buffer.from([value ? 1 : 0]);
+        case 'string':
+            const str = value;
+            const strBytes = Buffer.from(str, 'utf-8');
+            const strLen = Buffer.alloc(4);
+            strLen.writeUInt32LE(strBytes.length, 0);
+            return Buffer.concat([strLen, strBytes]);
+        case 'pubkey':
+            // In production, decode base58 to 32 bytes
+            return Buffer.alloc(32, 0);
+        default:
+            throw new Error(`Unknown primitive type: ${type}`);
+    }
+}
+function serializeVec(values, elementType) {
+    const len = Buffer.alloc(4);
+    len.writeUInt32LE(values.length, 0);
+    const elementBuffers = values.map(v => serializeValue(v, elementType));
+    return Buffer.concat([len, ...elementBuffers]);
+}
+function serializeOption(value, innerType) {
+    if (value === null || value === undefined) {
+        return Buffer.from([0]); // None
+    }
+    const inner = serializeValue(value, innerType);
+    return Buffer.concat([Buffer.from([1]), inner]); // Some
+}
+function serializeArray(values, elementType, length) {
+    if (values.length !== length) {
+        throw new Error(`Array length mismatch: expected ${length}, got ${values.length}`);
+    }
+    const elementBuffers = values.map(v => serializeValue(v, elementType));
+    return Buffer.concat(elementBuffers);
+}
+
+/**
+ * Waits for transaction confirmation.
+ *
+ * @param signature - Transaction signature
+ * @param level - Desired confirmation level
+ * @param timeout - Maximum wait time in milliseconds
+ * @returns Confirmation result
+ */
+async function waitForConfirmation(signature, level = 'confirmed', timeout = 60000) {
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeout) {
+        const status = await checkTransactionStatus();
+        if (status.err) {
+            throw new Error(`Transaction failed: ${JSON.stringify(status.err)}`);
+        }
+        if (isConfirmationLevelSufficient(status.confirmations, level)) {
+            return {
+                level,
+                slot: status.slot,
+            };
+        }
+        await sleep(1000);
+    }
+    throw new Error(`Transaction confirmation timeout after ${timeout}ms`);
+}
+async function checkTransactionStatus(signature) {
+    // In production, query the Solana RPC
+    return {
+        err: null,
+        confirmations: 32,
+        slot: 123456789,
+    };
+}
+function isConfirmationLevelSufficient(confirmations, level) {
+    if (confirmations === null) {
+        return false;
+    }
+    switch (level) {
+        case 'processed':
+            return confirmations >= 0;
+        case 'confirmed':
+            return confirmations >= 1;
+        case 'finalized':
+            return confirmations >= 32;
+        default:
+            return false;
+    }
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Parses and handles instruction errors.
+ */
+/**
+ * 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
+ */
+function parseInstructionError(error, errorMetadata) {
+    if (!error) {
+        return null;
+    }
+    const errorCode = extractErrorCode(error);
+    if (errorCode === null) {
+        return null;
+    }
+    const metadata = errorMetadata.find(e => e.code === errorCode);
+    if (metadata) {
+        return {
+            code: metadata.code,
+            name: metadata.name,
+            message: metadata.msg,
+        };
+    }
+    return {
+        code: errorCode,
+        name: `CustomError${errorCode}`,
+        message: `Unknown error with code ${errorCode}`,
+    };
+}
+function extractErrorCode(error) {
+    if (typeof error !== 'object' || error === null) {
+        return null;
+    }
+    const errorObj = error;
+    // Check for InstructionError format
+    if (errorObj.InstructionError) {
+        const instructionError = errorObj.InstructionError;
+        if (instructionError[1]?.Custom !== undefined) {
+            return instructionError[1].Custom;
+        }
+    }
+    // Check for direct code
+    if (typeof errorObj.code === 'number') {
+        return errorObj.code;
+    }
+    return null;
+}
+/**
+ * Formats an error for display.
+ *
+ * @param error - The program error
+ * @returns Human-readable error message
+ */
+function formatProgramError(error) {
+    return `${error.name} (${error.code}): ${error.message}`;
+}
+
+/**
+ * Converts resolved account array to a map for the builder.
+ */
+function toResolvedAccountsMap(accounts) {
+    const map = {};
+    for (const account of accounts) {
+        map[account.name] = account.address;
+    }
+    return map;
+}
+/**
+ * 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
+ */
+async function executeInstruction(handler, args, options = {}) {
+    // Step 1: Resolve accounts using handler's account metadata
+    const resolutionOptions = {
+        accounts: options.accounts,
+        wallet: options.wallet,
+    };
+    const resolution = resolveAccounts(handler.accounts, args, resolutionOptions);
+    validateAccountResolution(resolution);
+    // Step 2: Call generated build() function
+    const resolvedAccountsMap = toResolvedAccountsMap(resolution.accounts);
+    const instruction = handler.build(args, resolvedAccountsMap);
+    // Step 3: Build transaction from the built instruction
+    const transaction = buildTransaction(instruction);
+    // Step 4: Sign and send
+    if (!options.wallet) {
+        throw new Error('Wallet required to sign transaction');
+    }
+    const signature = await options.wallet.signAndSend(transaction);
+    // Step 5: Wait for confirmation
+    const confirmationLevel = options.confirmationLevel ?? 'confirmed';
+    const timeout = options.timeout ?? 60000;
+    const confirmation = await waitForConfirmation(signature, confirmationLevel, timeout);
+    return {
+        signature,
+        confirmationLevel: confirmation.level,
+        slot: confirmation.slot,
+    };
+}
+/**
+ * Creates a transaction object from a built instruction.
+ *
+ * @param instruction - Built instruction from handler
+ * @returns Transaction object ready for signing
+ */
+function buildTransaction(instruction) {
+    // This returns a framework-agnostic transaction representation.
+    // The wallet adapter is responsible for converting this to the
+    // appropriate format (@solana/web3.js Transaction, etc.)
+    return {
+        instructions: [{
+                programId: instruction.programId,
+                keys: instruction.keys,
+                data: Array.from(instruction.data),
+            }],
+    };
+}
+/**
+ * Creates an instruction executor bound to a specific wallet.
+ *
+ * @param wallet - Wallet adapter
+ * @returns Bound executor function
+ */
+function createInstructionExecutor(wallet) {
+    return {
+        execute: async (handler, args, options) => {
+            return executeInstruction(handler, args, {
+                ...options,
+                wallet,
+            });
+        },
+    };
+}
+
 class HyperStack {
     constructor(url, options) {
         this.stack = options.stack;
@@ -871,16 +1432,34 @@ class HyperStack {
             this.processor.handleFrame(frame);
         });
         this._views = createTypedViews(this.stack, this.storage, this.subscriptionRegistry);
+        this._instructions = this.buildInstructions();
+    }
+    buildInstructions() {
+        const instructions = {};
+        if (this.stack.instructions) {
+            for (const [name, handler] of Object.entries(this.stack.instructions)) {
+                instructions[name] = (args, options) => {
+                    return executeInstruction(handler, args, options);
+                };
+            }
+        }
+        return instructions;
     }
-    static async connect(url, options) {
+    static async connect(stack, options) {
+        const url = options?.url ?? stack.url;
         if (!url) {
-            throw new HyperStackError('URL is required', 'INVALID_CONFIG');
-        }
-        if (!options.stack) {
-            throw new HyperStackError('Stack definition is required', 'INVALID_CONFIG');
-        }
-        const client = new HyperStack(url, options);
-        if (options.autoReconnect !== false) {
+            throw new HyperStackError('URL is required (provide url option or define url in stack)', 'INVALID_CONFIG');
+        }
+        const internalOptions = {
+            stack,
+            storage: options?.storage,
+            maxEntriesPerView: options?.maxEntriesPerView,
+            autoReconnect: options?.autoReconnect,
+            reconnectIntervals: options?.reconnectIntervals,
+            maxReconnectAttempts: options?.maxReconnectAttempts,
+        };
+        const client = new HyperStack(url, internalOptions);
+        if (options?.autoReconnect !== false) {
             await client.connection.connect();
         }
         return client;
@@ -888,6 +1467,9 @@ class HyperStack {
     get views() {
         return this._views;
     }
+    get instructions() {
+        return this._instructions;
+    }
     get connectionState() {
         return this.connection.getState();
     }
@@ -1356,15 +1938,27 @@ exports.HyperStack = HyperStack;
 exports.HyperStackError = HyperStackError;
 exports.MemoryAdapter = MemoryAdapter;
 exports.SubscriptionRegistry = SubscriptionRegistry;
+exports.createEntityStream = createEntityStream;
+exports.createInstructionExecutor = createInstructionExecutor;
+exports.createPublicKeySeed = createPublicKeySeed;
 exports.createRichUpdateStream = createRichUpdateStream;
+exports.createSeed = createSeed;
 exports.createTypedListView = createTypedListView;
 exports.createTypedStateView = createTypedStateView;
 exports.createTypedViews = createTypedViews;
 exports.createUpdateStream = createUpdateStream;
+exports.derivePda = derivePda;
+exports.executeInstruction = executeInstruction;
+exports.formatProgramError = formatProgramError;
 exports.isEntityFrame = isEntityFrame;
 exports.isSnapshotFrame = isSnapshotFrame;
 exports.isSubscribedFrame = isSubscribedFrame;
 exports.isValidFrame = isValidFrame;
 exports.parseFrame = parseFrame;
 exports.parseFrameFromBlob = parseFrameFromBlob;
+exports.parseInstructionError = parseInstructionError;
+exports.resolveAccounts = resolveAccounts;
+exports.serializeInstructionData = serializeInstructionData;
+exports.validateAccountResolution = validateAccountResolution;
+exports.waitForConfirmation = waitForConfirmation;
 //# sourceMappingURL=index.js.map