@5ive-tech/sdk 1.1.2

package/dist/program/TypeGenerator.js

@@ -0,0 +1,195 @@
+/**
+ * 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;
+ * }
+ * ```
+ */
+/**
+ * TypeGenerator creates TypeScript interfaces from ABI
+ */
+export class TypeGenerator {
+    constructor(abi, options) {
+        this.abi = abi;
+        this.options = {
+            scriptName: abi.name || 'Program',
+            debug: false,
+            includeJSDoc: true,
+            ...options,
+        };
+    }
+    /**
+     * Generate TypeScript interface definitions from ABI
+     *
+     * @returns TypeScript code as string
+     */
+    generate() {
+        const lines = [];
+        // Header
+        lines.push('/**');
+        lines.push(` * Auto-generated types for ${this.options.scriptName} program`);
+        lines.push(' * Generated from ABI');
+        lines.push(' */');
+        lines.push('');
+        // Generate interface for each function
+        const interfaceName = this.generateInterfaceName(this.options.scriptName || 'Program');
+        lines.push(`export interface ${interfaceName} {`);
+        for (const func of this.abi.functions) {
+            // Check both is_public and visibility properties
+            const isPublic = func.is_public !== false && func.visibility !== 'private';
+            if (isPublic) {
+                lines.push(this.generateFunctionSignature(func, 2));
+            }
+        }
+        lines.push('}');
+        lines.push('');
+        // Generate parameter types for each function
+        for (const func of this.abi.functions) {
+            const isPublic = func.is_public !== false && func.visibility !== 'private';
+            if (isPublic) {
+                lines.push(...this.generateFunctionParameterType(func));
+            }
+        }
+        const result = lines.join('\n');
+        if (this.options.debug) {
+            console.log(`[TypeGenerator] Generated ${this.abi.functions.length} function types`);
+        }
+        return result;
+    }
+    /**
+     * Generate TypeScript function signature
+     *
+     * @param func - Function definition
+     * @param indent - Indentation level (spaces)
+     * @returns Lines of TypeScript code
+     */
+    generateFunctionSignature(func, indent) {
+        const indentStr = ' '.repeat(indent);
+        const paramTypeName = `${this.capitalize(func.name)}Params`;
+        let signature = `${indentStr}${func.name}(params: ${paramTypeName}): FunctionBuilder;`;
+        if (this.options.includeJSDoc) {
+            const lines = [
+                `${indentStr}/**`,
+                `${indentStr} * Call ${func.name}()`,
+                `${indentStr} */`,
+                signature,
+            ];
+            return lines.join('\n');
+        }
+        return signature;
+    }
+    /**
+     * Generate parameter type definitions for a function
+     *
+     * @param func - Function definition
+     * @returns Lines of TypeScript code
+     */
+    generateFunctionParameterType(func) {
+        const lines = [];
+        const paramTypeName = `${this.capitalize(func.name)}Params`;
+        lines.push(`export interface ${paramTypeName} {`);
+        // Extract account and data parameters
+        const accountParams = func.parameters.filter((p) => p.is_account === true);
+        const dataParams = func.parameters.filter((p) => p.is_account !== true);
+        // Generate accounts object if there are account parameters
+        if (accountParams.length > 0) {
+            lines.push('  accounts: {');
+            for (const param of accountParams) {
+                lines.push(`    ${param.name}: string | { toBase58(): string };`);
+            }
+            lines.push('  };');
+        }
+        // Generate args object if there are data parameters
+        if (dataParams.length > 0) {
+            lines.push('  args: {');
+            for (const param of dataParams) {
+                const typeStr = param.type || param.param_type || 'any';
+                const tsType = this.typeToTypeScript(typeStr);
+                lines.push(`    ${param.name}: ${tsType};`);
+            }
+            lines.push('  };');
+        }
+        lines.push('}');
+        lines.push('');
+        return lines;
+    }
+    /**
+     * Convert Five VM type to TypeScript type
+     *
+     * @param fiveType - Five VM type string (e.g., "u64", "Account")
+     * @returns TypeScript type string
+     */
+    typeToTypeScript(fiveType) {
+        const typeMap = {
+            u8: 'number',
+            u16: 'number',
+            u32: 'number',
+            u64: 'number | bigint',
+            u128: 'number | bigint',
+            i8: 'number',
+            i16: 'number',
+            i32: 'number',
+            i64: 'number | bigint',
+            i128: 'number | bigint',
+            f32: 'number',
+            f64: 'number',
+            bool: 'boolean',
+            string: 'string',
+            pubkey: 'string | { toBase58(): string }',
+            'pubkey[]': 'Array<string | { toBase58(): string }>',
+            'u8[]': 'Uint8Array | number[]',
+            'u64[]': 'Array<number | bigint>',
+        };
+        return typeMap[fiveType] || 'any';
+    }
+    /**
+     * Generate interface name from script name
+     * E.g., "counter" → "CounterProgram"
+     *
+     * @param scriptName - Name of the script
+     * @returns Interface name
+     */
+    generateInterfaceName(scriptName) {
+        const base = this.capitalize(scriptName);
+        return `${base}Program`;
+    }
+    /**
+     * Capitalize first letter
+     *
+     * @param str - String to capitalize
+     * @returns Capitalized string
+     */
+    capitalize(str) {
+        return str.charAt(0).toUpperCase() + str.slice(1);
+    }
+    /**
+     * Get the generated ABI as TypeScript AST (for advanced use)
+     *
+     * @returns Object representation of types
+     */
+    getABIStructure() {
+        return {
+            programName: this.generateInterfaceName(this.options.scriptName || 'Program'),
+            functions: this.abi.functions.map((func) => ({
+                name: func.name,
+                parameters: func.parameters,
+                returnType: func.return_type,
+            })),
+        };
+    }
+}

package/dist/program/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Five SDK Program Module
+ *
+ * High-level wrapper for Five VM scripts with Anchor-style ergonomics.
+ * Provides simple, type-safe API for building function calls.
+ *
+ * Usage:
+ * ```typescript
+ * import { FiveProgram } from '@five-vm/sdk';
+ *
+ * const program = FiveProgram.fromABI(scriptAccount, abi);
+ * const ix = await program
+ *   .function('increment')
+ *   .accounts({ counter: counter1, owner: user1 })
+ *   .instruction();
+ * ```
+ */
+export { FiveProgram } from './FiveProgram.js';
+export type { FiveProgramOptions } from './FiveProgram.js';
+export { FunctionBuilder } from './FunctionBuilder.js';
+export { AccountResolver } from './AccountResolver.js';
+export type { ResolvedSystemAccounts } from './AccountResolver.js';
+export { TypeGenerator } from './TypeGenerator.js';
+export type { TypeGeneratorOptions } from './TypeGenerator.js';

package/dist/program/index.js

@@ -0,0 +1,21 @@
+/**
+ * Five SDK Program Module
+ *
+ * High-level wrapper for Five VM scripts with Anchor-style ergonomics.
+ * Provides simple, type-safe API for building function calls.
+ *
+ * Usage:
+ * ```typescript
+ * import { FiveProgram } from '@five-vm/sdk';
+ *
+ * const program = FiveProgram.fromABI(scriptAccount, abi);
+ * const ix = await program
+ *   .function('increment')
+ *   .accounts({ counter: counter1, owner: user1 })
+ *   .instruction();
+ * ```
+ */
+export { FiveProgram } from './FiveProgram.js';
+export { FunctionBuilder } from './FunctionBuilder.js';
+export { AccountResolver } from './AccountResolver.js';
+export { TypeGenerator } from './TypeGenerator.js';

package/dist/project/config.d.ts

@@ -0,0 +1,5 @@
+import type { ProjectConfig } from '../types.js';
+/**
+ * Parses a raw TOML object into a strict ProjectConfig.
+ */
+export declare function parseProjectConfig(parsedToml: Record<string, any>): ProjectConfig;

package/dist/project/config.js

@@ -0,0 +1,33 @@
+/**
+ * Parses a raw TOML object into a strict ProjectConfig.
+ */
+export function parseProjectConfig(parsedToml) {
+    const project = parsedToml.project ?? {};
+    const build = parsedToml.build ?? {};
+    const optimizations = parsedToml.optimizations ?? {};
+    const deploy = parsedToml.deploy ?? {};
+    const name = project.name ?? 'five-project';
+    const target = (project.target ?? 'vm');
+    return {
+        name,
+        version: project.version ?? '0.1.0',
+        description: project.description,
+        sourceDir: project.source_dir ?? 'src',
+        buildDir: project.build_dir ?? 'build',
+        target,
+        entryPoint: project.entry_point,
+        outputArtifactName: build.output_artifact_name ?? name,
+        cluster: deploy.cluster ?? deploy.network,
+        commitment: deploy.commitment,
+        rpcUrl: deploy.rpc_url,
+        programId: deploy.program_id,
+        keypairPath: deploy.keypair_path,
+        multiFileMode: build.multi_file_mode ?? false,
+        optimizations: {
+            enableCompression: optimizations.enable_compression ?? true,
+            enableConstraintOptimization: optimizations.enable_constraint_optimization ?? true,
+            optimizationLevel: 'production'
+        },
+        dependencies: []
+    };
+}

package/dist/project/toml.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Minimal TOML parser supporting the fields used in five.toml.
+ * Handles sections, strings, booleans, and numbers.
+ * Platform-agnostic: Does not rely on Node.js 'fs'.
+ */
+export declare function parseToml(content: string): Record<string, any>;

package/dist/project/toml.js

@@ -0,0 +1,43 @@
+// @ts-nocheck
+/**
+ * Minimal TOML parser supporting the fields used in five.toml.
+ * Handles sections, strings, booleans, and numbers.
+ * Platform-agnostic: Does not rely on Node.js 'fs'.
+ */
+export function parseToml(content) {
+    const result = {};
+    let current = result;
+    const lines = content.split(/\r?\n/);
+    for (const rawLine of lines) {
+        const line = rawLine.split('#')[0].trim();
+        if (!line)
+            continue;
+        const sectionMatch = line.match(/^\[(.+)\]$/);
+        if (sectionMatch) {
+            const sectionName = sectionMatch[1].trim();
+            result[sectionName] = result[sectionName] || {};
+            current = result[sectionName];
+            continue;
+        }
+        const eq = line.indexOf('=');
+        if (eq === -1)
+            continue;
+        const key = line.slice(0, eq).trim();
+        const rawValue = line.slice(eq + 1).trim();
+        current[key] = parseTomlValue(rawValue);
+    }
+    return result;
+}
+function parseTomlValue(raw) {
+    if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) {
+        return raw.slice(1, -1);
+    }
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    const num = Number(raw);
+    if (!Number.isNaN(num))
+        return num;
+    return raw;
+}

package/dist/project/workspace.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Workspace Configuration and Types
+ *
+ * Provides types and utilities for Five workspace support,
+ * enabling multi-package projects with cross-bytecode imports.
+ */
+/**
+ * Dependency link type
+ * - inline: Merge into single bytecode (default)
+ * - external: Use CALL_EXTERNAL at runtime
+ */
+export type LinkType = 'inline' | 'external';
+/**
+ * Root workspace configuration from five.toml [workspace] section
+ */
+export interface WorkspaceConfig {
+    /** Member package paths (supports globs like "packages/*") */
+    members: string[];
+    /** Paths to exclude from workspace */
+    exclude?: string[];
+    /** Default package settings inherited by members */
+    package?: WorkspacePackageDefaults;
+    /** Shared workspace dependencies */
+    dependencies?: Record<string, WorkspaceDependency>;
+}
+/**
+ * Default settings that can be inherited by workspace members
+ */
+export interface WorkspacePackageDefaults {
+    version?: string;
+    authors?: string[];
+    edition?: string;
+}
+/**
+ * Workspace-level dependency definition
+ */
+export interface WorkspaceDependency {
+    version?: string;
+    path?: string;
+    link?: LinkType;
+}
+/**
+ * Package manifest from member five.toml
+ */
+export interface PackageManifest {
+    package: PackageInfo;
+    build?: PackageBuildConfig;
+    dependencies?: Record<string, PackageDependency>;
+    deploy?: PackageDeployConfig;
+}
+/**
+ * Package metadata from [package] section
+ */
+export interface PackageInfo {
+    name: string;
+    version: string | {
+        workspace: boolean;
+    };
+    description?: string;
+    authors?: string[];
+}
+/**
+ * Package build configuration from [build] section
+ */
+export interface PackageBuildConfig {
+    source_dir?: string;
+    entry_point?: string;
+    output?: string;
+    output_type?: 'bytecode_account' | 'library';
+}
+/**
+ * Package dependency specification
+ */
+export interface PackageDependency {
+    version?: string;
+    path?: string;
+    /** Use workspace = true to inherit from workspace deps */
+    workspace?: boolean;
+    /** Link type: inline (merge) or external (CALL_EXTERNAL) */
+    link?: LinkType;
+    /** Explicit bytecode address (for deployed dependencies) */
+    address?: string;
+}
+/**
+ * Package deployment configuration
+ */
+export interface PackageDeployConfig {
+    /** Deployed bytecode account address */
+    address?: string;
+    /** PDA seeds for deriving address */
+    pda_seeds?: string[];
+}
+/**
+ * Lock file structure (five.lock)
+ */
+export interface LockFile {
+    version: number;
+    packages: LockEntry[];
+}
+/**
+ * Individual package entry in lock file
+ */
+export interface LockEntry {
+    name: string;
+    version: string;
+    address: string;
+    bytecode_hash: string;
+    deployed_at?: string;
+}
+/**
+ * Resolved workspace state for IDE
+ */
+export interface WorkspaceState {
+    /** Root directory path */
+    root: string;
+    /** Member package paths */
+    members: string[];
+    /** Resolved package information */
+    packages: ResolvedPackage[];
+    /** Lock file data */
+    lockFile?: LockFile;
+}
+/**
+ * Resolved package with dependency info
+ */
+export interface ResolvedPackage {
+    name: string;
+    path: string;
+    entryPoint?: string;
+    dependencies: ResolvedDependency[];
+    /** Bytecode if compiled */
+    bytecode?: Uint8Array;
+    /** Deployed address if available */
+    address?: string;
+}
+/**
+ * Resolved dependency with link type
+ */
+export interface ResolvedDependency {
+    name: string;
+    link: LinkType;
+    path?: string;
+    address?: string;
+}
+/**
+ * Parse workspace section from TOML
+ */
+export declare function parseWorkspaceConfig(toml: Record<string, any>): WorkspaceConfig | null;
+/**
+ * Parse package manifest from TOML
+ */
+export declare function parsePackageManifest(toml: Record<string, any>): PackageManifest | null;
+/**
+ * Determine build order from packages (topological sort)
+ */
+export declare function getBuildOrder(packages: ResolvedPackage[]): string[];
+/**
+ * Check if a file map represents a workspace
+ */
+export declare function isWorkspace(files: Record<string, string>): boolean;

package/dist/project/workspace.js

@@ -0,0 +1,73 @@
+/**
+ * Workspace Configuration and Types
+ *
+ * Provides types and utilities for Five workspace support,
+ * enabling multi-package projects with cross-bytecode imports.
+ */
+// ==================== Utilities ====================
+/**
+ * Parse workspace section from TOML
+ */
+export function parseWorkspaceConfig(toml) {
+    const ws = toml.workspace;
+    if (!ws || !ws.members)
+        return null;
+    return {
+        members: ws.members,
+        exclude: ws.exclude,
+        package: ws.package,
+        dependencies: ws.dependencies,
+    };
+}
+/**
+ * Parse package manifest from TOML
+ */
+export function parsePackageManifest(toml) {
+    const pkg = toml.package;
+    if (!pkg || !pkg.name)
+        return null;
+    return {
+        package: {
+            name: pkg.name,
+            version: pkg.version || '0.1.0',
+            description: pkg.description,
+            authors: pkg.authors,
+        },
+        build: toml.build,
+        dependencies: toml.dependencies,
+        deploy: toml.deploy,
+    };
+}
+/**
+ * Determine build order from packages (topological sort)
+ */
+export function getBuildOrder(packages) {
+    const visited = new Set();
+    const order = [];
+    const packageMap = new Map(packages.map(p => [p.name, p]));
+    function visit(name) {
+        if (visited.has(name))
+            return;
+        visited.add(name);
+        const pkg = packageMap.get(name);
+        if (pkg) {
+            for (const dep of pkg.dependencies) {
+                visit(dep.name);
+            }
+        }
+        order.push(name);
+    }
+    for (const pkg of packages) {
+        visit(pkg.name);
+    }
+    return order;
+}
+/**
+ * Check if a file map represents a workspace
+ */
+export function isWorkspace(files) {
+    const rootToml = files['five.toml'];
+    if (!rootToml)
+        return false;
+    return rootToml.includes('[workspace]');
+}

package/dist/testing/AccountMetaGenerator.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Account Meta Generator for Five VM Testing
+ *
+ * Generates AccountMeta structures for testing account system scripts
+ * based on ABI requirements and constraint types (@signer, @mut, @init)
+ */
+/**
+ * Account constraint types from Five VM
+ */
+export interface AccountConstraints {
+    name: string;
+    writable: boolean;
+    signer: boolean;
+    init?: boolean;
+}
+/**
+ * Generated account metadata for testing
+ */
+export interface GeneratedAccountMeta {
+    pubkey: string;
+    isSigner: boolean;
+    isWritable: boolean;
+    keypair?: {
+        publicKey: string;
+        secretKey: Uint8Array;
+    };
+}
+/**
+ * Test account generation context
+ */
+export interface TestAccountContext {
+    script: string;
+    functionIndex: number;
+    accounts: GeneratedAccountMeta[];
+    stateData?: Map<string, any>;
+}
+/**
+ * Account Meta Generator for Five VM test scripts
+ */
+export declare class AccountMetaGenerator {
+    private static accountCache;
+    private static stateDataCache;
+    /**
+     * Generate AccountMeta array from ABI function definition
+     */
+    static generateAccountsForFunction(abi: any, functionName: string, options?: {
+        reuseAccounts?: boolean;
+        generateStateData?: boolean;
+        debug?: boolean;
+    }): Promise<TestAccountContext>;
+    /**
+     * Generate single AccountMeta from account specification
+     */
+    private static generateAccountMeta;
+    /**
+     * Generate signer account with keypair
+     */
+    private static generateSignerAccount;
+    /**
+     * Generate regular (non-signer) account
+     */
+    private static generateRegularAccount;
+    /**
+     * Check if account is a state account that needs data
+     */
+    private static isStateAccount;
+    /**
+     * Generate mock state data for state accounts
+     */
+    private static generateStateData;
+    /**
+     * Format accounts for Five CLI execution
+     */
+    static formatAccountsForCLI(context: TestAccountContext): {
+        accountsParam: string;
+        keypairsNeeded: Array<{
+            name: string;
+            keypair: any;
+        }>;
+    };
+    /**
+     * Generate accounts from .five file
+     */
+    static generateFromFiveFile(fiveFilePath: string, functionName?: string, options?: {
+        reuseAccounts?: boolean;
+        generateStateData?: boolean;
+        debug?: boolean;
+    }): Promise<TestAccountContext>;
+    /**
+     * Clear account cache (useful for testing)
+     */
+    static clearCache(): void;
+    /**
+     * Get account cache statistics
+     */
+    static getCacheStats(): {
+        accountsCached: number;
+        stateDataCached: number;
+    };
+}
+/**
+ * Utility functions for account management
+ */
+export declare class AccountTestUtils {
+    /**
+     * Create test accounts for common constraint patterns
+     */
+    static createStandardTestAccounts(): Promise<{
+        payer: GeneratedAccountMeta;
+        authority: GeneratedAccountMeta;
+        state: GeneratedAccountMeta;
+        readonly: GeneratedAccountMeta;
+    }>;
+    /**
+     * Validate account constraints match requirements
+     */
+    static validateAccountConstraints(accounts: GeneratedAccountMeta[], requirements: AccountConstraints[]): {
+        valid: boolean;
+        errors: string[];
+    };
+}