@5ive-tech/sdk 1.1.2

package/dist/program/FiveProgram.d.ts

@@ -0,0 +1,144 @@
+/**
+ * FiveProgram - High-level wrapper for Five VM scripts
+ *
+ * Provides Anchor-style ergonomics while maintaining zero-dependency design.
+ * FiveProgram simplifies interaction with Five scripts on-chain by:
+ * - Providing fluent API for function calls
+ * - Auto-injecting system accounts when needed
+ * - Generating TypeScript types from ABI
+ * - Handling parameter encoding internally
+ *
+ * Usage:
+ * ```typescript
+ * const program = FiveProgram.fromABI(scriptAccount, abi);
+ * const ix = await program
+ *   .function('increment')
+ *   .accounts({ counter: counter1, owner: user1.publicKey })
+ *   .instruction();
+ * ```
+ */
+import type { ScriptABI, FunctionDefinition, AccountFetcher } from '../metadata/index.js';
+import type { Provider } from '../types.js';
+import { FunctionBuilder } from './FunctionBuilder.js';
+import { ProgramAccount } from './ProgramAccount.js';
+export interface FiveProgramOptions {
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Optional account fetcher for loading metadata from chain */
+    fetcher?: AccountFetcher;
+    /** Five VM Program ID (defaults to mainnet/devnet) */
+    fiveVMProgramId?: string;
+    /** Five VM State PDA account (if not provided, will be derived) */
+    vmStateAccount?: string;
+    /** Fee receiver account (admin account for transaction fees) */
+    feeReceiverAccount?: string;
+    /** Wallet/Network Provider for RPC calls */
+    provider?: Provider;
+}
+/**
+ * FiveProgram represents a deployed Five script with its ABI
+ * Provides high-level API for building function calls
+ */
+export declare class FiveProgram {
+    private scriptAccount;
+    private abi;
+    private options;
+    private functionBuilderCache;
+    /**
+     * RPC Entry point for calling functions
+     * e.g. program.methods.myFunc(params).rpc()
+     */
+    readonly methods: any;
+    constructor(scriptAccount: string, abi: ScriptABI, options?: FiveProgramOptions);
+    /**
+     * Factory method: Create FiveProgram from ABI
+     * Used when ABI is already available locally or compiled
+     */
+    static fromABI(scriptAccount: string, abi: ScriptABI, options?: FiveProgramOptions): FiveProgram;
+    /**
+     * Factory method: Load FiveProgram from deployed script account
+     * Fetches script metadata from chain and extracts ABI
+     *
+     * @param scriptAddress - Script account address
+     * @param connection - web3.js Connection object or custom fetcher
+     * @param options - SDK options
+     * @returns Initialized FiveProgram instance
+     */
+    static load(scriptAddress: string, connection: any, // Connection or custom fetcher
+    options?: FiveProgramOptions): Promise<FiveProgram>;
+    /**
+     * Get function builder for a specific function
+     * Creates a fluent interface for building function calls
+     *
+     * @param functionName - Name of the function to call
+     * @returns FunctionBuilder for chaining .accounts().args().instruction()
+     * @throws Error if function not found in ABI
+     */
+    function(functionName: string): FunctionBuilder;
+    /**
+     * Get an account handler for fetching and decoding state
+     *
+     * @param structName - Name of the struct definition in ABI (e.g., "Counter")
+     * @returns ProgramAccount instance
+     */
+    account(structName: string): ProgramAccount;
+    /**
+     * Get all available function names from ABI
+     */
+    getFunctions(): string[];
+    /**
+     * Get function definition by name
+     */
+    getFunction(name: string): FunctionDefinition | undefined;
+    /**
+     * Get all function definitions
+     */
+    getAllFunctions(): FunctionDefinition[];
+    /**
+     * Generate TypeScript types from ABI
+     * Creates type-safe interfaces for function parameters
+     *
+     * @returns TypeScript interface as string
+     */
+    generateTypes(): string;
+    /**
+     * Get script account address
+     */
+    getScriptAccount(): string;
+    /**
+     * Get Five VM Program ID with consistent resolver precedence
+     */
+    getFiveVMProgramId(): string;
+    /**
+     * Derive a Program Derived Address (PDA)
+     *
+     * @param seeds - Array of seeds (strings, public keys in base58, or buffers)
+     * @param programId - Optional program ID (defaults to Five VM)
+     * @returns [address, bump]
+     */
+    findAddress(seeds: (string | Uint8Array | Buffer)[], programId?: string): Promise<[string, number]>;
+    /**
+     * Get the ABI
+     */
+    getABI(): ScriptABI;
+    /**
+     * Get options
+     */
+    getOptions(): FiveProgramOptions;
+    /**
+     * Get VM State Account
+     */
+    getVMStateAccount(): string | undefined;
+    /**
+     * Set VM State Account
+     */
+    setVMStateAccount(account: string): this;
+    /**
+     * Get Fee Receiver Account
+     */
+    getFeeReceiverAccount(): string | undefined;
+    /**
+     * Set Fee Receiver Account
+     */
+    setFeeReceiverAccount(account: string): this;
+}

package/dist/program/FiveProgram.js

@@ -0,0 +1,282 @@
+/**
+ * FiveProgram - High-level wrapper for Five VM scripts
+ *
+ * Provides Anchor-style ergonomics while maintaining zero-dependency design.
+ * FiveProgram simplifies interaction with Five scripts on-chain by:
+ * - Providing fluent API for function calls
+ * - Auto-injecting system accounts when needed
+ * - Generating TypeScript types from ABI
+ * - Handling parameter encoding internally
+ *
+ * Usage:
+ * ```typescript
+ * const program = FiveProgram.fromABI(scriptAccount, abi);
+ * const ix = await program
+ *   .function('increment')
+ *   .accounts({ counter: counter1, owner: user1.publicKey })
+ *   .instruction();
+ * ```
+ */
+import { FunctionBuilder } from './FunctionBuilder.js';
+import { TypeGenerator } from './TypeGenerator.js';
+import { ProgramAccount } from './ProgramAccount.js';
+import { ProgramIdResolver } from '../config/ProgramIdResolver.js';
+/**
+ * FiveProgram represents a deployed Five script with its ABI
+ * Provides high-level API for building function calls
+ */
+export class FiveProgram {
+    constructor(scriptAccount, abi, options) {
+        this.functionBuilderCache = new Map();
+        this.scriptAccount = scriptAccount;
+        this.abi = abi;
+        this.options = {
+            debug: false,
+            ...options,
+            // fiveVMProgramId will be resolved at call time via ProgramIdResolver
+        };
+        // Build cache for quick function lookup
+        this.abi.functions.forEach((func) => {
+            this.functionBuilderCache.set(func.name, func);
+        });
+        if (this.options.debug) {
+            console.log(`[FiveProgram] Initialized with ${this.abi.functions.length} functions`);
+        }
+        // Initialize the methods proxy
+        this.methods = new Proxy(this, {
+            get: (target, prop) => {
+                if (typeof prop === 'string') {
+                    return (...args) => {
+                        const builder = target.function(prop);
+                        // TODO: Robust argument mapping based on ABI types
+                        // Simple map: if args[0] is object, assume named params
+                        if (args.length === 1 && typeof args[0] === 'object' && !Array.isArray(args[0])) {
+                            builder.args(args[0]);
+                        }
+                        // Logic for positional args would go here
+                        return builder;
+                    };
+                }
+                return undefined;
+            }
+        });
+    }
+    /**
+     * Factory method: Create FiveProgram from ABI
+     * Used when ABI is already available locally or compiled
+     */
+    static fromABI(scriptAccount, abi, options) {
+        return new FiveProgram(scriptAccount, abi, options);
+    }
+    /**
+     * Factory method: Load FiveProgram from deployed script account
+     * Fetches script metadata from chain and extracts ABI
+     *
+     * @param scriptAddress - Script account address
+     * @param connection - web3.js Connection object or custom fetcher
+     * @param options - SDK options
+     * @returns Initialized FiveProgram instance
+     */
+    static async load(scriptAddress, connection, // Connection or custom fetcher
+    options = {}) {
+        const { ScriptMetadataParser } = await import('../metadata/index.js');
+        const { PublicKey } = await import('@solana/web3.js');
+        let fetcher;
+        // Check if connection is a web3.js Connection (has getAccountInfo)
+        if (connection && typeof connection.getAccountInfo === 'function') {
+            fetcher = {
+                getAccountData: async (address) => {
+                    try {
+                        const pubkey = new PublicKey(address);
+                        const info = await connection.getAccountInfo(pubkey);
+                        if (!info)
+                            return null;
+                        return {
+                            address,
+                            data: info.data,
+                            owner: info.owner.toBase58(),
+                            lamports: info.lamports
+                        };
+                    }
+                    catch (error) {
+                        console.warn(`Error fetching account ${address}:`, error);
+                        return null;
+                    }
+                },
+                getMultipleAccountsData: async (addresses) => {
+                    // Minimal implementation for getScriptMetadata requirements
+                    const results = new Map();
+                    // getScriptMetadata currently uses getAccountData, but if it used batch:
+                    try {
+                        const pubkeys = addresses.map(a => new PublicKey(a));
+                        const infos = await connection.getMultipleAccountsInfo(pubkeys);
+                        infos.forEach((info, i) => {
+                            const address = addresses[i];
+                            if (info) {
+                                results.set(address, {
+                                    address,
+                                    data: info.data,
+                                    owner: info.owner.toBase58(),
+                                    lamports: info.lamports
+                                });
+                            }
+                            else {
+                                results.set(address, null);
+                            }
+                        });
+                    }
+                    catch (e) {
+                        console.warn('Batch fetch failed', e);
+                    }
+                    return results;
+                }
+            };
+        }
+        else {
+            // Assume it matches AccountFetcher interface
+            fetcher = connection;
+        }
+        // Set fetcher in options so ProgramAccount can use it later
+        const newOptions = { ...options, fetcher: options.fetcher || fetcher };
+        const metadata = await ScriptMetadataParser.getScriptMetadata(fetcher, scriptAddress);
+        return new FiveProgram(scriptAddress, metadata.abi, newOptions);
+    }
+    /**
+     * Get function builder for a specific function
+     * Creates a fluent interface for building function calls
+     *
+     * @param functionName - Name of the function to call
+     * @returns FunctionBuilder for chaining .accounts().args().instruction()
+     * @throws Error if function not found in ABI
+     */
+    function(functionName) {
+        const funcDef = this.functionBuilderCache.get(functionName);
+        if (!funcDef) {
+            const available = Array.from(this.functionBuilderCache.keys());
+            throw new Error(`Function '${functionName}' not found in ABI. Available: ${available.join(', ')}`);
+        }
+        return new FunctionBuilder(funcDef, this.scriptAccount, this.abi, this.options);
+    }
+    /**
+     * Get an account handler for fetching and decoding state
+     *
+     * @param structName - Name of the struct definition in ABI (e.g., "Counter")
+     * @returns ProgramAccount instance
+     */
+    account(structName) {
+        return new ProgramAccount(structName, this.abi, this.options.fetcher);
+    }
+    /**
+     * Get all available function names from ABI
+     */
+    getFunctions() {
+        return this.abi.functions.map((func) => func.name);
+    }
+    /**
+     * Get function definition by name
+     */
+    getFunction(name) {
+        return this.functionBuilderCache.get(name);
+    }
+    /**
+     * Get all function definitions
+     */
+    getAllFunctions() {
+        return this.abi.functions;
+    }
+    /**
+     * Generate TypeScript types from ABI
+     * Creates type-safe interfaces for function parameters
+     *
+     * @returns TypeScript interface as string
+     */
+    generateTypes() {
+        const typeGenerator = new TypeGenerator(this.abi, {
+            scriptName: this.abi.name || 'Script',
+            debug: this.options.debug,
+        });
+        return typeGenerator.generate();
+    }
+    /**
+     * Get script account address
+     */
+    getScriptAccount() {
+        return this.scriptAccount;
+    }
+    /**
+     * Get Five VM Program ID with consistent resolver precedence
+     */
+    getFiveVMProgramId() {
+        return ProgramIdResolver.resolve(this.options.fiveVMProgramId);
+    }
+    /**
+     * Derive a Program Derived Address (PDA)
+     *
+     * @param seeds - Array of seeds (strings, public keys in base58, or buffers)
+     * @param programId - Optional program ID (defaults to Five VM)
+     * @returns [address, bump]
+     */
+    async findAddress(seeds, programId) {
+        const { PublicKey } = await import('@solana/web3.js');
+        // Convert seeds to Buffers
+        const bufferSeeds = seeds.map(seed => {
+            if (seed instanceof Uint8Array || (typeof Buffer !== 'undefined' && Buffer.isBuffer(seed))) {
+                return seed;
+            }
+            if (typeof seed === 'string') {
+                // Check if it looks like a Pubkey (Base58, 32 bytes approx)
+                // Heuristic: if it decodes to 32 bytes, treat as pubkey, else string literal
+                try {
+                    const pk = new PublicKey(seed);
+                    return pk.toBuffer();
+                }
+                catch {
+                    return Buffer.from(seed);
+                }
+            }
+            throw new Error(`Unsupported seed type: ${typeof seed}`);
+        });
+        const pid = new PublicKey(programId || this.getFiveVMProgramId());
+        // @ts-ignore - PublicKey.findProgramAddress return type mismatch in some versions
+        const [addr, bump] = PublicKey.findProgramAddressSync(bufferSeeds, pid);
+        return [addr.toBase58(), bump];
+    }
+    /**
+     * Get the ABI
+     */
+    getABI() {
+        return this.abi;
+    }
+    /**
+     * Get options
+     */
+    getOptions() {
+        return this.options;
+    }
+    /**
+     * Get VM State Account
+     */
+    getVMStateAccount() {
+        return this.options.vmStateAccount;
+    }
+    /**
+     * Set VM State Account
+     */
+    setVMStateAccount(account) {
+        this.options.vmStateAccount = account;
+        return this;
+    }
+    /**
+     * Get Fee Receiver Account
+     */
+    getFeeReceiverAccount() {
+        return this.options.feeReceiverAccount;
+    }
+    /**
+     * Set Fee Receiver Account
+     */
+    setFeeReceiverAccount(account) {
+        this.options.feeReceiverAccount = account;
+        return this;
+    }
+}

package/dist/program/FunctionBuilder.d.ts

@@ -0,0 +1,114 @@
+/**
+ * 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 type { FunctionDefinition, ScriptABI } from '../metadata/index.js';
+import type { SerializedInstruction } from '../types.js';
+import type { FiveProgramOptions } from './FiveProgram.js';
+/**
+ * FunctionBuilder implements fluent API for function calls
+ */
+export declare class FunctionBuilder {
+    private functionDef;
+    private scriptAccount;
+    private abi;
+    private options;
+    private accountsMap;
+    private argsMap;
+    private resolvedAccounts;
+    constructor(functionDef: FunctionDefinition, scriptAccount: string, abi: ScriptABI, options: FiveProgramOptions);
+    /**
+     * 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: Record<string, string | {
+        toBase58(): string;
+    }>): this;
+    /**
+     * Specify data parameters for this function call
+     *
+     * @param args - Map of parameter names to values
+     * @returns this for method chaining
+     */
+    args(args: Record<string, any>): 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
+     */
+    instruction(): Promise<SerializedInstruction>;
+    /**
+     * Build a Solana Transaction containing this instruction
+     */
+    transaction(options?: {
+        computeUnits?: number;
+    }): Promise<any>;
+    /**
+     * Send transaction with this instruction (RPC)
+     * requires a provider to be set in options
+     */
+    rpc(options?: {
+        signers?: any[];
+        skipPreflight?: boolean;
+        computeUnits?: number;
+    }): Promise<string>;
+    /**
+     * Validate that all required parameters are provided
+     * @throws Error if any required parameter is missing
+     */
+    private validateParameters;
+    /**
+     * 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
+     */
+    private mergeParameters;
+    /**
+     * 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
+     */
+    private buildAccountMetadata;
+    /**
+     * 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
+     */
+    private generateInstructionData;
+    /**
+     * Get the function definition
+     */
+    getFunctionDef(): FunctionDefinition;
+    /**
+     * Get accounts that have been set
+     */
+    getAccounts(): Record<string, string>;
+    /**
+     * Get arguments that have been set
+     */
+    getArgs(): Record<string, any>;
+}