@5ive-tech/sdk 1.1.2

package/dist/compiler/BytecodeCompiler.js

@@ -0,0 +1,379 @@
+/**
+ * Five Bytecode Compiler
+ *
+ * Handles compilation of Five script source (.v files) to bytecode (.bin files)
+ * using the existing WASM compilation infrastructure.
+ *
+ * This maintains the real compilation capabilities while providing a clean SDK interface.
+ */
+import { readFile } from "fs/promises";
+import { CompilationSDKError, } from "../types.js";
+import { normalizeAbiFunctions } from "../utils/abi.js";
+/**
+ * Bytecode compiler for Five scripts
+ */
+export class BytecodeCompiler {
+    constructor(config = {}) {
+        this.debug = config.debug || false;
+        if (this.debug) {
+            console.log("[BytecodeCompiler] Initialized");
+        }
+    }
+    /**
+     * Compile Five script source to bytecode
+     */
+    async compile(source, options = {}) {
+        const startTime = Date.now();
+        const sourceContent = typeof source === 'string' ? source : source.content;
+        const sourceFilename = typeof source === 'string' ? 'unknown.v' : source.filename || 'unknown.v';
+        // Compile source (debug info available in this.debug mode)
+        try {
+            // Lazy load WASM compiler
+            if (!this.wasmCompiler) {
+                await this.loadWasmCompiler();
+            }
+            // Prepare compilation options - pass through all metrics options
+            const compilerOptions = {
+                optimize: options.optimize || false,
+                target: options.target || "vm",
+                debug: options.debug || false,
+                maxSize: options.maxSize || 1048576, // 1MB default
+                optimizationLevel: options.optimizationLevel || "production", // Default to Production
+                // Pass through metrics options
+                metricsFormat: options.metricsFormat,
+                metricsOutput: options.metricsOutput,
+                errorFormat: options.errorFormat,
+                includeMetrics: options.includeMetrics,
+                comprehensiveMetrics: options.comprehensiveMetrics,
+            };
+            // Perform compilation
+            const result = await this.wasmCompiler.compile(sourceContent, compilerOptions);
+            const compilationTime = Date.now() - startTime;
+            if (result.success && result.bytecode) {
+                let abiData = result.abi;
+                if (!abiData) {
+                    abiData = await this.generateABI(source);
+                }
+                if (this.debug) {
+                    console.log(`[BytecodeCompiler] Compilation successful in ${compilationTime}ms`);
+                    console.log(`[BytecodeCompiler] Bytecode size: ${result.bytecode.length} bytes`);
+                }
+                const normalizedFunctions = normalizeAbiFunctions(abiData?.functions ?? abiData);
+                const normalizedAbi = {
+                    ...abiData,
+                    functions: normalizedFunctions,
+                };
+                const compilerInfo = await this.getCompilerInfo();
+                return {
+                    success: true,
+                    bytecode: result.bytecode,
+                    abi: normalizedAbi,
+                    disassembly: result.disassembly || [],
+                    metadata: {
+                        sourceFile: sourceFilename,
+                        timestamp: new Date().toISOString(),
+                        compilerVersion: compilerInfo.version || '1.0.0',
+                        target: (options.target || 'vm'),
+                        optimizations: [],
+                        originalSize: sourceContent.length,
+                        compressedSize: result.bytecode.length,
+                        compressionRatio: 1.0,
+                        sourceSize: sourceContent.length,
+                        bytecodeSize: result.bytecode.length,
+                        functions: this.extractFunctions(normalizedAbi),
+                        compilationTime,
+                    },
+                    metricsReport: result.metricsReport,
+                };
+            }
+            else {
+                const errors = this.transformErrors(result.errors || []);
+                if (this.debug) {
+                    console.log(`[BytecodeCompiler] Compilation failed with ${errors.length} errors`);
+                    errors.forEach((error) => {
+                        console.log(`  - ${error.severity}: ${error.message} (${error.line}:${error.column})`);
+                    });
+                }
+                return {
+                    success: false,
+                    errors,
+                    metricsReport: result.metricsReport,
+                };
+            }
+        }
+        catch (error) {
+            throw new CompilationSDKError(`Compilation error: ${error instanceof Error ? error.message : "Unknown error"}`, { source: sourceContent.substring(0, 200), options });
+        }
+    }
+    /**
+     * Compile multiple modules (entry + dependencies)
+     */
+    async compileModules(mainSource, modules, options = {}) {
+        const startTime = Date.now();
+        try {
+            if (!this.wasmCompiler) {
+                await this.loadWasmCompiler();
+            }
+            if (!this.wasmCompiler?.compile_multi) {
+                throw new CompilationSDKError("Multi-file compilation is not supported in this build");
+            }
+            const compilerOptions = {
+                optimize: options.optimize || false,
+                target: options.target || "vm",
+                debug: options.debug || false,
+                maxSize: options.maxSize || 1048576,
+                optimizationLevel: options.optimizationLevel || "production",
+                includeMetrics: options.includeMetrics || options.metricsOutput !== undefined,
+                metricsFormat: options.metricsFormat || "json",
+                errorFormat: options.errorFormat || "terminal",
+                comprehensiveMetrics: options.comprehensiveMetrics || false,
+            };
+            const result = await this.wasmCompiler.compile_multi(mainSource.content, modules, compilerOptions);
+            const compilationTime = Date.now() - startTime;
+            if (result.success && result.bytecode) {
+                const compilerInfo = await this.getCompilerInfo();
+                return {
+                    success: true,
+                    bytecode: result.bytecode,
+                    abi: result.abi,
+                    disassembly: result.disassembly || [],
+                    metadata: {
+                        sourceFile: mainSource.filename || 'main.v',
+                        timestamp: new Date().toISOString(),
+                        compilerVersion: compilerInfo.version || '1.0.0',
+                        target: (options.target || 'vm'),
+                        optimizations: [],
+                        originalSize: mainSource.content.length,
+                        compressedSize: result.bytecode.length,
+                        compressionRatio: 1.0,
+                        sourceSize: mainSource.content.length,
+                        bytecodeSize: result.bytecode.length,
+                        functions: [],
+                        compilationTime,
+                    },
+                    metricsReport: result.metricsReport,
+                };
+            }
+            else {
+                const errors = this.transformErrors(result.errors || result.compiler_errors || []);
+                return {
+                    success: false,
+                    errors,
+                    metricsReport: result.metricsReport,
+                };
+            }
+        }
+        catch (error) {
+            throw new CompilationSDKError(`Compilation error: ${error instanceof Error ? error.message : "Unknown error"}`, { options });
+        }
+    }
+    /**
+     * Compile script from file path
+     */
+    async compileFile(filePath, options = {}) {
+        if (this.debug) {
+            console.log(`[BytecodeCompiler] Reading file: ${filePath}`);
+        }
+        try {
+            const source = await readFile(filePath, "utf-8");
+            return this.compile(source, options);
+        }
+        catch (error) {
+            throw new CompilationSDKError(`Failed to read file ${filePath}: ${error instanceof Error ? error.message : "Unknown error"}`, { filePath, options });
+        }
+    }
+    /**
+     * Validate Five script source without compiling
+     */
+    async validateSource(source) {
+        const code = typeof source === 'string' ? source : source.content;
+        if (this.debug) {
+            console.log(`[BytecodeCompiler] Validating source (${code.length} chars)...`);
+        }
+        try {
+            if (!this.wasmCompiler) {
+                await this.loadWasmCompiler();
+            }
+            const result = await this.wasmCompiler.validateSource(code);
+            return {
+                valid: result.valid,
+                errors: result.errors ? this.transformErrors(result.errors) : undefined,
+            };
+        }
+        catch (error) {
+            if (this.debug) {
+                console.log(`[BytecodeCompiler] Validation error: ${error}`);
+            }
+            return {
+                valid: false,
+                errors: [
+                    {
+                        message: error instanceof Error
+                            ? error.message
+                            : "Unknown validation error",
+                        severity: "error",
+                    },
+                ],
+            };
+        }
+    }
+    /**
+     * Get compiler version and information
+     */
+    async getCompilerInfo() {
+        try {
+            if (!this.wasmCompiler) {
+                await this.loadWasmCompiler();
+            }
+            let version = "1.0.0";
+            if (this.wasmCompiler && typeof this.wasmCompiler.getCompilerInfo === 'function') {
+                const info = this.wasmCompiler.getCompilerInfo();
+                version = info.version;
+            }
+            return {
+                version,
+                wasmLoaded: !!this.wasmCompiler,
+                debug: this.debug,
+            };
+        }
+        catch (error) {
+            return {
+                version: "unknown",
+                wasmLoaded: false,
+                debug: this.debug,
+                error: error instanceof Error ? error.message : "Unknown error",
+            };
+        }
+    }
+    // ==================== Private Methods ====================
+    /**
+     * Load WASM compiler (reuse existing infrastructure)
+     */
+    async loadWasmCompiler() {
+        try {
+            // Load WASM compiler silently unless debug
+            // Import existing WASM compiler from the SDK
+            const wasmModule = await import("../wasm/compiler/index.js");
+            const wasmInstance = new wasmModule.FiveCompiler(this.createWasmLogger());
+            // Initialize the compiler
+            await wasmInstance.initialize();
+            this.wasmCompiler = wasmInstance;
+            this.wasmModule = wasmModule;
+            if (this.debug) {
+                console.log("[BytecodeCompiler] WASM compiler loaded and initialized successfully");
+            }
+        }
+        catch (error) {
+            throw new CompilationSDKError(`Failed to load WASM compiler: ${error instanceof Error ? error.message : "Unknown error"}`, { debug: this.debug });
+        }
+    }
+    createWasmLogger() {
+        if (this.debug) {
+            return console;
+        }
+        return {
+            debug: () => { },
+            info: () => { },
+            warn: console.warn.bind(console),
+            error: console.error.bind(console),
+        };
+    }
+    /**
+     * Transform compiler errors to SDK format
+     */
+    transformErrors(errors) {
+        return errors.map((error) => ({
+            type: 'compiler',
+            message: error.message || error.toString(),
+            line: error.line,
+            column: error.column,
+            severity: error.severity || "error",
+        }));
+    }
+    /**
+     * Extract function definitions from ABI
+     */
+    extractFunctions(abi) {
+        const functions = normalizeAbiFunctions(abi?.functions ?? abi);
+        return functions.map((func) => ({
+            name: func.name,
+            index: func.index,
+            parameters: func.parameters?.map((param) => ({
+                name: param.name,
+                type: param.type,
+                optional: param.optional || false,
+            })) || [],
+            returnType: func.returnType,
+        }));
+    }
+    /**
+     * Generate ABI from Five script source code
+     */
+    async generateABI(source) {
+        const code = typeof source === 'string' ? source : source.content;
+        if (this.debug) {
+            console.log(`[BytecodeCompiler] Generating ABI for source (${code.length} chars)...`);
+        }
+        try {
+            if (!this.wasmCompiler) {
+                await this.loadWasmCompiler();
+            }
+            const abi = await this.wasmCompiler.generateABI(code);
+            const normalizedFunctions = normalizeAbiFunctions(abi?.functions ?? abi);
+            return { ...abi, functions: normalizedFunctions };
+        }
+        catch (error) {
+            if (this.debug) {
+                console.log(`[BytecodeCompiler] ABI generation error: ${error}`);
+            }
+            throw new CompilationSDKError(`ABI generation failed: ${error instanceof Error ? error.message : "Unknown error"}`, { source: code.substring(0, 100) });
+        }
+    }
+    /**
+     * Extract function names from compiled bytecode
+     */
+    async getFunctionNames(bytecode) {
+        if (this.debug) {
+            console.log(`[BytecodeCompiler] Extracting function names from bytecode (${bytecode.length} bytes)...`);
+        }
+        try {
+            if (!this.wasmCompiler) {
+                await this.loadWasmCompiler();
+            }
+            let namesJson = null;
+            if (this.wasmCompiler &&
+                typeof this.wasmCompiler.getFunctionNames === "function") {
+                namesJson = await this.wasmCompiler.getFunctionNames(bytecode);
+            }
+            else if (this.wasmModule &&
+                typeof this.wasmModule.get_function_names === "function") {
+                namesJson = await this.wasmModule.get_function_names(bytecode);
+            }
+            // Fallback: direct call if previous attempts yielded no data
+            if (!namesJson && this.wasmModule?.get_function_names) {
+                namesJson = this.wasmModule.get_function_names(bytecode);
+            }
+            let parsedNames = namesJson;
+            if (typeof namesJson === "string") {
+                try {
+                    parsedNames = JSON.parse(namesJson);
+                }
+                catch (e) {
+                    if (this.debug) {
+                        console.log(`[BytecodeCompiler] Failed to parse function names JSON:`, e);
+                    }
+                }
+            }
+            if (this.debug) {
+                console.log(`[BytecodeCompiler] Function names extracted: ${JSON.stringify(parsedNames)}`);
+            }
+            return parsedNames || [];
+        }
+        catch (error) {
+            if (this.debug) {
+                console.log(`[BytecodeCompiler] Function name extraction error: ${error}`);
+            }
+            throw new CompilationSDKError(`Function name extraction failed: ${error instanceof Error ? error.message : "Unknown error"}`, { bytecodeLength: bytecode.length });
+        }
+    }
+}

package/dist/config/ConfigManager.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Five SDK configuration manager.
+ */
+import { FiveSDKConfig } from '../types.js';
+export declare class ConfigManager {
+    private static instance;
+    private config;
+    private constructor();
+    static getInstance(): ConfigManager;
+    get(): Promise<any>;
+    getSync(): any;
+    set(config: Partial<FiveSDKConfig>): Promise<void>;
+}

package/dist/config/ConfigManager.js

@@ -0,0 +1,27 @@
+/**
+ * Five SDK configuration manager.
+ */
+const DEFAULT_CONFIG = {
+    network: 'devnet',
+    debug: false
+};
+export class ConfigManager {
+    constructor() {
+        this.config = { ...DEFAULT_CONFIG };
+    }
+    static getInstance() {
+        if (!ConfigManager.instance) {
+            ConfigManager.instance = new ConfigManager();
+        }
+        return ConfigManager.instance;
+    }
+    async get() {
+        return this.config;
+    }
+    getSync() {
+        return this.config;
+    }
+    async set(config) {
+        this.config = { ...this.config, ...config };
+    }
+}

package/dist/config/ProgramIdResolver.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Centralized program ID resolution for Five SDK.
+ * Implements consistent precedence: explicit → default → env → baked → error
+ */
+/**
+ * Baked program ID injected at release time (set by scripts/set-default-program-id.sh)
+ * Empty string by default; overridden in npm published packages.
+ */
+export declare const FIVE_BAKED_PROGRAM_ID = "";
+/**
+ * Centralized resolver for program IDs across all SDK operations.
+ * Ensures consistent validation and error messaging.
+ */
+export declare class ProgramIdResolver {
+    private static defaultProgramId;
+    /**
+     * Set the default program ID for the entire SDK.
+     * Used when no explicit program ID is provided.
+     * @param programId - Solana public key (base58 encoded)
+     * @throws {ValidationError} - If programId is not a valid Solana address
+     */
+    static setDefault(programId: string): void;
+    /**
+     * Get the currently set default program ID.
+     * @returns The default program ID, or undefined if not set
+     */
+    static getDefault(): string | undefined;
+    /**
+     * Resolve program ID with consistent precedence.
+     * Order: explicit → instance default → env (FIVE_PROGRAM_ID) → baked → error
+     *
+     * @param explicit - Explicit program ID (highest priority)
+     * @param options - Resolution options
+     * @returns Resolved program ID (validated)
+     * @throws {Error} - If no valid program ID resolves and allowUndefined is false
+     *
+     * @example
+     * ```typescript
+     * // Will use explicit if provided, fall back through chain
+     * const programId = ProgramIdResolver.resolve(options.fiveVMProgramId);
+     *
+     * // For local/WASM paths that don't need program ID
+     * const optional = ProgramIdResolver.resolveOptional(options.fiveVMProgramId);
+     * ```
+     */
+    static resolve(explicit?: string, options?: {
+        allowUndefined?: boolean;
+    }): string;
+    /**
+     * Resolve program ID but allow undefined return.
+     * Used for local/WASM execution paths that don't require a program ID.
+     *
+     * @param explicit - Explicit program ID (highest priority)
+     * @returns Resolved program ID (validated) or undefined if no resolution possible
+     */
+    static resolveOptional(explicit?: string): string | undefined;
+    /**
+     * Clear the default program ID.
+     * Useful for testing or resetting to clean state.
+     */
+    static clearDefault(): void;
+}

package/dist/config/ProgramIdResolver.js

@@ -0,0 +1,104 @@
+/**
+ * Centralized program ID resolution for Five SDK.
+ * Implements consistent precedence: explicit → default → env → baked → error
+ */
+import { validator } from '../validation/index.js';
+/**
+ * Baked program ID injected at release time (set by scripts/set-default-program-id.sh)
+ * Empty string by default; overridden in npm published packages.
+ */
+export const FIVE_BAKED_PROGRAM_ID = '';
+/**
+ * Centralized resolver for program IDs across all SDK operations.
+ * Ensures consistent validation and error messaging.
+ */
+export class ProgramIdResolver {
+    /**
+     * Set the default program ID for the entire SDK.
+     * Used when no explicit program ID is provided.
+     * @param programId - Solana public key (base58 encoded)
+     * @throws {ValidationError} - If programId is not a valid Solana address
+     */
+    static setDefault(programId) {
+        validator.validateBase58Address(programId, 'defaultProgramId');
+        this.defaultProgramId = programId;
+    }
+    /**
+     * Get the currently set default program ID.
+     * @returns The default program ID, or undefined if not set
+     */
+    static getDefault() {
+        return this.defaultProgramId;
+    }
+    /**
+     * Resolve program ID with consistent precedence.
+     * Order: explicit → instance default → env (FIVE_PROGRAM_ID) → baked → error
+     *
+     * @param explicit - Explicit program ID (highest priority)
+     * @param options - Resolution options
+     * @returns Resolved program ID (validated)
+     * @throws {Error} - If no valid program ID resolves and allowUndefined is false
+     *
+     * @example
+     * ```typescript
+     * // Will use explicit if provided, fall back through chain
+     * const programId = ProgramIdResolver.resolve(options.fiveVMProgramId);
+     *
+     * // For local/WASM paths that don't need program ID
+     * const optional = ProgramIdResolver.resolveOptional(options.fiveVMProgramId);
+     * ```
+     */
+    static resolve(explicit, options) {
+        // Precedence: explicit → default → env → baked
+        // Note: Must check for explicit empty string differently from undefined
+        let resolved;
+        if (explicit) {
+            resolved = explicit;
+        }
+        else if (this.defaultProgramId) {
+            resolved = this.defaultProgramId;
+        }
+        else if (process.env.FIVE_PROGRAM_ID) {
+            resolved = process.env.FIVE_PROGRAM_ID;
+        }
+        else if (FIVE_BAKED_PROGRAM_ID) {
+            resolved = FIVE_BAKED_PROGRAM_ID;
+        }
+        if (!resolved && !options?.allowUndefined) {
+            throw new Error(`No program ID resolved for Five VM. ` +
+                `Set via one of: ` +
+                `(1) explicit call parameter, ` +
+                `(2) FiveSDK.setDefaultProgramId(), ` +
+                `(3) FIVE_PROGRAM_ID environment variable, ` +
+                `(4) released package default. ` +
+                `For setup guidance, see: https://docs.five.build/cli/program-id-setup`);
+        }
+        if (resolved) {
+            validator.validateBase58Address(resolved, 'programId');
+        }
+        return resolved || '';
+    }
+    /**
+     * Resolve program ID but allow undefined return.
+     * Used for local/WASM execution paths that don't require a program ID.
+     *
+     * @param explicit - Explicit program ID (highest priority)
+     * @returns Resolved program ID (validated) or undefined if no resolution possible
+     */
+    static resolveOptional(explicit) {
+        try {
+            const result = this.resolve(explicit, { allowUndefined: true });
+            return result || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Clear the default program ID.
+     * Useful for testing or resetting to clean state.
+     */
+    static clearDefault() {
+        this.defaultProgramId = undefined;
+    }
+}