@5ive-tech/sdk 1.1.2

package/dist/program/FunctionBuilder.js

@@ -0,0 +1,347 @@
+/**
+ * FunctionBuilder - Fluent API for building Five VM function calls
+ *
+ * Provides chainable methods for specifying function parameters:
+ * - .accounts() - Map account names to their addresses
+ * - .args() - Map data parameters to their values
+ * - .instruction() - Generate serialized instruction data
+ *
+ * Usage:
+ * ```typescript
+ * const ix = await program
+ *   .function('add_amount')
+ *   .accounts({ counter: counter1, owner: user1.publicKey })
+ *   .args({ amount: 10 })
+ *   .instruction();
+ * ```
+ */
+import { AccountResolver } from './AccountResolver.js';
+/**
+ * FunctionBuilder implements fluent API for function calls
+ */
+export class FunctionBuilder {
+    constructor(functionDef, scriptAccount, abi, options) {
+        this.accountsMap = new Map();
+        this.argsMap = new Map();
+        this.resolvedAccounts = new Set();
+        this.functionDef = functionDef;
+        this.scriptAccount = scriptAccount;
+        this.abi = abi;
+        this.options = options;
+    }
+    /**
+     * Specify accounts for this function call
+     * Accepts either base58 strings or PublicKey objects
+     *
+     * @param accounts - Map of account names to addresses
+     * @returns this for method chaining
+     */
+    accounts(accounts) {
+        for (const [name, address] of Object.entries(accounts)) {
+            const addressStr = typeof address === 'string' ? address : address.toBase58();
+            this.accountsMap.set(name, addressStr);
+            this.resolvedAccounts.add(addressStr);
+        }
+        if (this.options.debug) {
+            console.log(`[FunctionBuilder] Set accounts: ${Array.from(this.accountsMap.keys()).join(', ')}`);
+        }
+        return this;
+    }
+    /**
+     * Specify data parameters for this function call
+     *
+     * @param args - Map of parameter names to values
+     * @returns this for method chaining
+     */
+    args(args) {
+        for (const [name, value] of Object.entries(args)) {
+            this.argsMap.set(name, value);
+        }
+        if (this.options.debug) {
+            console.log(`[FunctionBuilder] Set args: ${Array.from(this.argsMap.keys()).join(', ')}`);
+        }
+        return this;
+    }
+    /**
+     * Build and return serialized instruction data
+     * This is the main method that orchestrates parameter resolution and instruction generation
+     *
+     * @returns SerializedInstruction ready for transaction building
+     */
+    async instruction() {
+        // Validate parameters later, after auto-injection
+        // Resolve system accounts (auto-inject when needed)
+        const resolver = new AccountResolver(this.options);
+        const resolvedSystemAccounts = resolver.resolveSystemAccounts(this.functionDef, this.accountsMap);
+        // Merge system accounts into our map
+        const systemAccountsList = [];
+        for (const [name, address] of Object.entries(resolvedSystemAccounts)) {
+            this.accountsMap.set(name, address);
+            this.resolvedAccounts.add(address);
+            systemAccountsList.push(address); // Track for inclusion in accounts list
+        }
+        // Resolve PDA accounts (auto-derive based on seeds) using a temporary FiveProgram for findAddress.
+        const { FiveProgram } = await import('./FiveProgram.js');
+        const programForUtil = new FiveProgram(this.scriptAccount, this.abi, this.options);
+        const resolvedPdaAccounts = await resolver.resolvePdaAccounts(this.abi, this.accountsMap, programForUtil);
+        // Merge PDA accounts
+        for (const [name, address] of Object.entries(resolvedPdaAccounts)) {
+            this.accountsMap.set(name, address);
+            this.resolvedAccounts.add(address);
+            systemAccountsList.push(address);
+        }
+        // Now validate that all required parameters are provided (including auto-injected ones)
+        this.validateParameters();
+        // Merge parameters in ABI order (accounts first, then data)
+        const { mergedParams, accountPubkeys } = this.mergeParameters();
+        // Append system accounts to the account list (they go at the end)
+        const allAccountPubkeys = [...accountPubkeys, ...systemAccountsList];
+        // Build account metadata from ABI attributes
+        const accountMetadata = this.buildAccountMetadata(allAccountPubkeys, resolvedSystemAccounts);
+        if (this.options.debug) {
+            console.log(`[FunctionBuilder] Building instruction for function '${this.functionDef.name}'`);
+            console.log(`[FunctionBuilder] Merged params:`, mergedParams);
+            console.log(`[FunctionBuilder] Account metadata:`, accountMetadata);
+        }
+        // Call existing SDK method to generate instruction
+        // This reuses the proven parameter encoding logic
+        const instruction = await this.generateInstructionData(mergedParams, allAccountPubkeys, accountMetadata);
+        if (this.options.debug) {
+            console.log(`[FunctionBuilder] Generated instruction:`, instruction);
+        }
+        return instruction;
+    }
+    /**
+     * Build a Solana Transaction containing this instruction
+     */
+    async transaction(options = {}) {
+        const ix = await this.instruction();
+        // Import Solana web3 dynamically
+        const { Transaction, TransactionInstruction, ComputeBudgetProgram, PublicKey } = await import('@solana/web3.js');
+        const tx = new Transaction();
+        // add compute budget if requested
+        if (options.computeUnits) {
+            tx.add(ComputeBudgetProgram.setComputeUnitLimit({ units: options.computeUnits }));
+        }
+        // construct instruction
+        const solanaIx = new TransactionInstruction({
+            programId: new PublicKey(ix.programId),
+            keys: ix.keys.map(key => ({
+                pubkey: new PublicKey(key.pubkey),
+                isSigner: key.isSigner,
+                isWritable: key.isWritable
+            })),
+            data: Buffer.from(ix.data, 'base64')
+        });
+        tx.add(solanaIx);
+        return tx;
+    }
+    /**
+     * Send transaction with this instruction (RPC)
+     * requires a provider to be set in options
+     */
+    async rpc(options = {}) {
+        const provider = this.options.provider;
+        if (!provider || !provider.sendAndConfirm) {
+            throw new Error("RPC method requires a Provider with sendAndConfirm support");
+        }
+        const tx = await this.transaction({ computeUnits: options.computeUnits });
+        // Send
+        const signers = options.signers || [];
+        return await provider.sendAndConfirm(tx, signers, {
+            skipPreflight: options.skipPreflight
+        });
+    }
+    /**
+     * Validate that all required parameters are provided
+     * @throws Error if any required parameter is missing
+     */
+    validateParameters() {
+        for (const param of this.functionDef.parameters) {
+            if (param.is_account) {
+                if (!this.accountsMap.has(param.name)) {
+                    throw new Error(`Missing required account '${param.name}' for function '${this.functionDef.name}'`);
+                }
+            }
+            else {
+                if (this.argsMap.get(param.name) === undefined) {
+                    throw new Error(`Missing required argument '${param.name}' for function '${this.functionDef.name}'`);
+                }
+            }
+        }
+    }
+    /**
+     * Merge account and data parameters in ABI order
+     * Returns both merged array and list of account pubkeys for instruction building
+     *
+     * @returns Object with mergedParams array and accountPubkeys list
+     */
+    mergeParameters() {
+        const mergedParams = [];
+        const accountPubkeys = [];
+        for (const param of this.functionDef.parameters) {
+            if (param.is_account) {
+                // Account parameter - must be in accountsMap
+                const pubkey = this.accountsMap.get(param.name);
+                if (!pubkey) {
+                    throw new Error(`Missing account '${param.name}'`);
+                }
+                mergedParams.push(pubkey);
+                accountPubkeys.push(pubkey);
+            }
+            else {
+                // Data parameter - must be in argsMap
+                const value = this.argsMap.get(param.name);
+                if (value === undefined) {
+                    throw new Error(`Missing argument '${param.name}'`);
+                }
+                mergedParams.push(value);
+            }
+        }
+        return { mergedParams, accountPubkeys };
+    }
+    /**
+     * Build account metadata (isSigner, isWritable) from ABI attributes
+     *
+     * @param accountPubkeys - List of account pubkeys in order
+     * @param systemAccounts - System accounts that were auto-injected
+     * @returns Map of pubkey to metadata
+     */
+    buildAccountMetadata(accountPubkeys, systemAccounts) {
+        const metadata = new Map();
+        // First pass: identify if there's an @init constraint and find the payer
+        let hasInit = false;
+        let payerPubkey;
+        for (const param of this.functionDef.parameters) {
+            if (param.is_account) {
+                const attributes = param.attributes || [];
+                if (attributes.includes('init')) {
+                    hasInit = true;
+                    if (this.options.debug) {
+                        console.log(`[FunctionBuilder] Detected @init constraint on parameter: ${param.name}`);
+                    }
+                    // Find the payer - typically the @signer in an @init context
+                    // Check if there's another account marked @signer for the payer
+                    for (const payerParam of this.functionDef.parameters) {
+                        if (payerParam.is_account &&
+                            payerParam !== param &&
+                            (payerParam.attributes || []).includes('signer')) {
+                            payerPubkey = this.accountsMap.get(payerParam.name);
+                            if (this.options.debug) {
+                                console.log(`[FunctionBuilder] Found payer for @init: ${payerParam.name} = ${payerPubkey}`);
+                            }
+                            break;
+                        }
+                    }
+                    break;
+                }
+            }
+        }
+        // Build metadata for function parameters
+        for (const param of this.functionDef.parameters) {
+            if (param.is_account) {
+                const pubkey = this.accountsMap.get(param.name);
+                if (!pubkey)
+                    continue;
+                const attributes = param.attributes || [];
+                const isWritable = attributes.includes('mut') ||
+                    attributes.includes('init') ||
+                    // If this is the payer for @init, it must be writable
+                    (hasInit && pubkey === payerPubkey);
+                const entry = {
+                    isSigner: attributes.includes('signer'),
+                    isWritable,
+                };
+                if (this.options.debug) {
+                    console.log(`[FunctionBuilder] Account metadata for ${param.name}: pubkey=${pubkey}, isSigner=${entry.isSigner}, isWritable=${entry.isWritable}, isPayer=${hasInit && pubkey === payerPubkey}`);
+                }
+                metadata.set(pubkey, entry);
+            }
+        }
+        // Mark system accounts
+        for (const [name, address] of Object.entries(systemAccounts)) {
+            if (!metadata.has(address)) {
+                metadata.set(address, {
+                    isSigner: false,
+                    isWritable: false,
+                    isSystemAccount: true,
+                });
+            }
+        }
+        return metadata;
+    }
+    /**
+     * Generate instruction data using serialization
+     * Integrates with FiveSDK.generateExecuteInstruction() for parameter encoding
+     *
+     * @param mergedParams - Parameters in ABI order
+     * @param accountList - List of all account pubkeys (function params + system accounts)
+     * @param accountMetadata - Account metadata (isSigner, isWritable)
+     * @returns SerializedInstruction
+     */
+    async generateInstructionData(mergedParams, accountList, accountMetadata) {
+        // Account list is already passed in
+        // Dynamically import FiveSDK to avoid circular dependencies
+        const { FiveSDK } = await import('../FiveSDK.js');
+        // Call the SDK's generateExecuteInstruction method.
+        // This handles fixed-size typed execute encoding and parameter validation.
+        const executionResult = await FiveSDK.generateExecuteInstruction(this.scriptAccount, this.functionDef.index, // Use function index directly
+        mergedParams, // All parameters in merged order
+        accountList, // Account pubkey list
+        undefined, // No connection needed - we have ABI
+        {
+            debug: this.options.debug,
+            abi: this.abi, // Pass ABI for parameter encoding
+            fiveVMProgramId: this.options.fiveVMProgramId,
+            vmStateAccount: this.options.vmStateAccount,
+            adminAccount: this.options.feeReceiverAccount,
+            accountMetadata: accountMetadata, // Pass account metadata for correct isWritable flags
+        });
+        // Map SDK's instruction format (with 'accounts') to SerializedInstruction format (with 'keys')
+        const sdkInstruction = executionResult.instruction;
+        // Convert accounts array to keys array with proper naming
+        const keys = (sdkInstruction.accounts || []).map((acc) => {
+            // Handle both string and PublicKey-like objects
+            let pubkeyStr;
+            if (typeof acc.pubkey === 'string') {
+                pubkeyStr = acc.pubkey;
+            }
+            else if (acc.pubkey && typeof acc.pubkey.toBase58 === 'function') {
+                pubkeyStr = acc.pubkey.toBase58();
+            }
+            else {
+                pubkeyStr = String(acc.pubkey);
+            }
+            return {
+                pubkey: pubkeyStr,
+                isSigner: acc.isSigner,
+                isWritable: acc.isWritable,
+            };
+        });
+        // Return the properly formatted serialized instruction
+        const instruction = {
+            programId: sdkInstruction.programId,
+            keys,
+            data: sdkInstruction.data,
+        };
+        return instruction;
+    }
+    /**
+     * Get the function definition
+     */
+    getFunctionDef() {
+        return this.functionDef;
+    }
+    /**
+     * Get accounts that have been set
+     */
+    getAccounts() {
+        return Object.fromEntries(this.accountsMap);
+    }
+    /**
+     * Get arguments that have been set
+     */
+    getArgs() {
+        return Object.fromEntries(this.argsMap);
+    }
+}

package/dist/program/ProgramAccount.d.ts

@@ -0,0 +1,38 @@
+/**
+ * ProgramAccount - Typed state fetching for Five VM
+ *
+ * Provides typed access to account state based on ABI definitions.
+ *
+ * Usage:
+ * ```typescript
+ * const myAccount = program.account('MyStruct');
+ * const state = await myAccount.fetch(publicKey);
+ * console.log(state.someField);
+ * ```
+ */
+import { AccountFetcher } from '../metadata/index.js';
+import type { ScriptABI } from '../metadata/index.js';
+export declare class ProgramAccount {
+    private structName;
+    private abi;
+    private fetcher?;
+    constructor(structName: string, abi: ScriptABI, fetcher?: AccountFetcher);
+    /**
+     * Fetch and decode account state
+     *
+     * @param address - Account address to fetch
+     * @returns Decoded account state object
+     */
+    fetch(address: string): Promise<any>;
+    /**
+     * Decode raw account data based on ABI
+     *
+     * @param data - Raw byte array
+     * @returns Decoded JavaScript object
+     */
+    decode(data: Uint8Array): any;
+    private readField;
+    private findStructDefinition;
+    private simpleDecode;
+    private readU32;
+}

package/dist/program/ProgramAccount.js

@@ -0,0 +1,170 @@
+/**
+ * ProgramAccount - Typed state fetching for Five VM
+ *
+ * Provides typed access to account state based on ABI definitions.
+ *
+ * Usage:
+ * ```typescript
+ * const myAccount = program.account('MyStruct');
+ * const state = await myAccount.fetch(publicKey);
+ * console.log(state.someField);
+ * ```
+ */
+import { BorshSchemaGenerator } from './BorshSchemaGenerator.js';
+import * as borsh from 'borsh';
+export class ProgramAccount {
+    constructor(structName, abi, fetcher) {
+        this.structName = structName;
+        this.abi = abi;
+        this.fetcher = fetcher;
+    }
+    /**
+     * Fetch and decode account state
+     *
+     * @param address - Account address to fetch
+     * @returns Decoded account state object
+     */
+    async fetch(address) {
+        if (!this.fetcher) {
+            throw new Error('Account fetcher not provided. Cannot fetch account data.');
+        }
+        const accountData = await this.fetcher.getAccountData(address);
+        if (!accountData) {
+            return null;
+        }
+        return this.decode(accountData.data);
+    }
+    /**
+     * Decode raw account data based on ABI
+     *
+     * @param data - Raw byte array
+     * @returns Decoded JavaScript object
+     */
+    decode(data) {
+        // 1. Find struct definition in ABI
+        const structDef = this.findStructDefinition(this.structName);
+        if (!structDef) {
+            // Fallback: if no types defined, return raw data
+            return { data };
+        }
+        // 2. Decode based on fields
+        // NOTE: This uses the robust BorshSchemaGenerator to map ABI types to runtime schema
+        try {
+            const generator = new BorshSchemaGenerator(this.abi);
+            // We need to construct a class that matches the schema for borsh to deserialize into
+            // The generator effectively returns a map where keys are these classes
+            const schema = generator.generate(structDef);
+            // Find the class constructor from the map keys
+            const SchemaClass = Array.from(schema.keys())[0];
+            if (!SchemaClass) {
+                throw new Error(`Failed to generate schema for ${this.structName}`);
+            }
+            // Fallback: Manual deserialization using BinaryReader
+            // This bypasses potential issues with borsh.deserialize returning empty objects for dynamic classes
+            try {
+                const reader = new borsh.BinaryReader(Buffer.from(data));
+                const result = new SchemaClass();
+                const structSchema = schema.get(SchemaClass);
+                if (structSchema && structSchema.kind === 'struct') {
+                    for (const [fieldName, fieldType] of structSchema.fields) {
+                        result[fieldName] = this.readField(reader, fieldType);
+                    }
+                    return result;
+                }
+            }
+            catch (manualErr) {
+            }
+            // Fallback to library if manual failed (though manual is preferred now)
+            return borsh.deserialize(schema, SchemaClass, Buffer.from(data));
+        }
+        catch (e) {
+            console.error(`Borsh decoding failed for ${this.structName}:`, e);
+            // Fallback to simple decode if borsh fails (e.g. mismatch)
+            return this.simpleDecode(data, structDef);
+        }
+    }
+    readField(reader, fieldType) {
+        if (typeof fieldType === 'string') {
+            switch (fieldType) {
+                case 'u8': return reader.readU8();
+                case 'u16': return reader.readU16();
+                case 'u32': return reader.readU32();
+                case 'u64': return reader.readU64();
+                case 'u128': return reader.readU128();
+                case 'i8': return reader.readU8();
+                case 'i16': return reader.readU16();
+                case 'i32': return reader.readU32();
+                case 'i64': return reader.readU64();
+                case 'i128': return reader.readU128();
+                case 'bool': return reader.readU8() !== 0;
+                case 'string': return reader.readString();
+            }
+        }
+        if (Array.isArray(fieldType)) {
+            // Fixed array [length] or [Type] (Vec)
+            if (typeof fieldType[0] === 'number') {
+                return reader.readFixedArray(fieldType[0]);
+            }
+        }
+        return null;
+    }
+    findStructDefinition(name) {
+        if (!this.abi.types)
+            return undefined;
+        return this.abi.types.find(t => t.name === name && t.structure === 'struct');
+    }
+    simpleDecode(data, structDef) {
+        const result = {};
+        let offset = 0;
+        // Basic discriminator check (8 bytes for Five accounts) could go here
+        // offset += 8;
+        if (!structDef.fields)
+            return result;
+        for (const field of structDef.fields) {
+            // Very basic decoding logic for primitive types
+            // A robust implementation would use a proper deserialization library
+            if (offset >= data.length)
+                break;
+            switch (field.type) {
+                case 'u8':
+                case 'bool':
+                    result[field.name] = data[offset];
+                    offset += 1;
+                    break;
+                case 'u32':
+                case 'i32':
+                    result[field.name] = this.readU32(data, offset);
+                    offset += 4;
+                    break;
+                case 'u64':
+                case 'i64':
+                    // Read as Number for simplicity, BigInt for precision
+                    const low = this.readU32(data, offset);
+                    const high = this.readU32(data, offset + 4);
+                    result[field.name] = low + (high * 0x100000000); // Danger: precision loss > 2^53
+                    offset += 8;
+                    break;
+                case 'Pubkey':
+                case 'address':
+                    if (offset + 32 <= data.length) {
+                        // We return base58 string in a real implementation
+                        // Here we just slice because we don't have bs58 dep in this file
+                        result[field.name] = data.slice(offset, offset + 32);
+                        offset += 32;
+                    }
+                    break;
+                default:
+                    // Skip unknown variable-length types to avoid reading garbage
+                    // console.warn(`Skipping decoding of complex type ${field.type}`);
+                    break;
+            }
+        }
+        return result;
+    }
+    readU32(data, offset) {
+        return (data[offset] |
+            (data[offset + 1] << 8) |
+            (data[offset + 2] << 16) |
+            (data[offset + 3] << 24)) >>> 0;
+    }
+}

package/dist/program/TypeGenerator.d.ts

@@ -0,0 +1,90 @@
+/**
+ * TypeGenerator - Generate TypeScript types from Five VM script ABI
+ *
+ * Creates type-safe interfaces for:
+ * - Function parameters (accounts and data)
+ * - Return types
+ * - Type-safe builder methods
+ *
+ * Example generated interface:
+ * ```typescript
+ * export interface CounterProgram {
+ *   initialize(params: {
+ *     accounts: { counter: PublicKey | string; owner: PublicKey | string };
+ *   }): FunctionBuilder;
+ *
+ *   add_amount(params: {
+ *     accounts: { counter: PublicKey | string; owner: PublicKey | string };
+ *     args: { amount: number };
+ *   }): FunctionBuilder;
+ * }
+ * ```
+ */
+import type { ScriptABI } from '../metadata/index.js';
+export interface TypeGeneratorOptions {
+    /** Name of the generated program interface */
+    scriptName?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Custom namespace for generated types */
+    namespace?: string;
+    /** Include JSDoc comments */
+    includeJSDoc?: boolean;
+}
+/**
+ * TypeGenerator creates TypeScript interfaces from ABI
+ */
+export declare class TypeGenerator {
+    private abi;
+    private options;
+    constructor(abi: ScriptABI, options?: TypeGeneratorOptions);
+    /**
+     * Generate TypeScript interface definitions from ABI
+     *
+     * @returns TypeScript code as string
+     */
+    generate(): string;
+    /**
+     * Generate TypeScript function signature
+     *
+     * @param func - Function definition
+     * @param indent - Indentation level (spaces)
+     * @returns Lines of TypeScript code
+     */
+    private generateFunctionSignature;
+    /**
+     * Generate parameter type definitions for a function
+     *
+     * @param func - Function definition
+     * @returns Lines of TypeScript code
+     */
+    private generateFunctionParameterType;
+    /**
+     * Convert Five VM type to TypeScript type
+     *
+     * @param fiveType - Five VM type string (e.g., "u64", "Account")
+     * @returns TypeScript type string
+     */
+    private typeToTypeScript;
+    /**
+     * Generate interface name from script name
+     * E.g., "counter" → "CounterProgram"
+     *
+     * @param scriptName - Name of the script
+     * @returns Interface name
+     */
+    private generateInterfaceName;
+    /**
+     * Capitalize first letter
+     *
+     * @param str - String to capitalize
+     * @returns Capitalized string
+     */
+    private capitalize;
+    /**
+     * Get the generated ABI as TypeScript AST (for advanced use)
+     *
+     * @returns Object representation of types
+     */
+    getABIStructure(): Record<string, any>;
+}