@5ive-tech/sdk 1.1.2

package/dist/encoding/ParameterEncoder.js

@@ -0,0 +1,278 @@
+// Parameter encoding for Five VM.
+import { ParameterEncodingError } from '../types.js';
+// Type ID mapping (matches Five VM protocol).
+const TYPE_IDS = {
+    'u8': 1,
+    'u16': 2,
+    'u32': 3,
+    'u64': 4,
+    'i8': 5,
+    'i16': 6,
+    'i32': 7,
+    'i64': 8,
+    'bool': 9,
+    'string': 11,
+    'pubkey': 10,
+    'bytes': 12,
+    'array': 13
+};
+export class ParameterEncoder {
+    constructor(debug = false) {
+        this.debug = debug;
+        if (this.debug) {
+            console.log('[ParameterEncoder] Initialized');
+        }
+    }
+    // ==================== Pure Parameter Encoding ====================
+    async encodeParameterData(parameters = [], functionSignature) {
+        if (this.debug) {
+            console.log(`[ParameterEncoder] Encoding parameter data: params=${parameters.length}`);
+        }
+        const encodedData = await this.encodeParametersInternal(parameters, functionSignature);
+        if (this.debug) {
+            console.log(`[ParameterEncoder] Encoded parameters: ${encodedData.length} bytes, hex: ${encodedData.toString('hex')}`);
+        }
+        return encodedData;
+    }
+    encodeParametersWithABI(parameters, functionSignature, options = {}) {
+        if (this.debug) {
+            console.log(`[ParameterEncoder] Encoding ${parameters.length} parameters with ABI guidance`);
+        }
+        const encoded = [];
+        for (let i = 0; i < parameters.length; i++) {
+            const value = parameters[i];
+            const paramDef = functionSignature.parameters[i];
+            if (!paramDef && options.strict) {
+                throw new ParameterEncodingError(`Parameter ${i} provided but function only expects ${functionSignature.parameters.length} parameters`, { functionName: functionSignature.name, parameterIndex: i });
+            }
+            // Use ABI type if available, otherwise infer
+            const targetType = paramDef?.type || this.inferType(value);
+            const encodedParam = this.encodeParameter(value, targetType, i);
+            encoded.push(encodedParam);
+        }
+        if (this.debug) {
+            console.log(`[ParameterEncoder] Encoded ${encoded.length} parameters successfully`);
+        }
+        return encoded;
+    }
+    // ==================== Type Coercion ====================
+    /// Coerce value to a Five VM type.
+    coerceValue(value, targetType) {
+        if (this.debug) {
+            console.log(`[ParameterEncoder] Coercing value ${JSON.stringify(value)} to ${targetType}`);
+        }
+        try {
+            switch (targetType) {
+                case 'u8':
+                    return this.coerceToU8(value);
+                case 'u16':
+                    return this.coerceToU16(value);
+                case 'u32':
+                    return this.coerceToU32(value);
+                case 'u64':
+                    return this.coerceToU64(value);
+                case 'i8':
+                    return this.coerceToI8(value);
+                case 'i16':
+                    return this.coerceToI16(value);
+                case 'i32':
+                    return this.coerceToI32(value);
+                case 'i64':
+                    return this.coerceToI64(value);
+                case 'bool':
+                    return this.coerceToBool(value);
+                case 'string':
+                    return this.coerceToString(value);
+                case 'pubkey':
+                    return this.coerceToPubkey(value);
+                case 'bytes':
+                    return this.coerceToBytes(value);
+                case 'array':
+                    return this.coerceToArray(value);
+                default:
+                    throw new Error(`Unsupported type: ${targetType}`);
+            }
+        }
+        catch (error) {
+            throw new ParameterEncodingError(`Failed to coerce value ${JSON.stringify(value)} to ${targetType}: ${error instanceof Error ? error.message : 'Unknown error'}`, { value, targetType });
+        }
+    }
+    // ==================== Private Methods ====================
+    /// Use BytecodeEncoder for parameter data only.
+    async encodeParametersInternal(parameters, functionSignature) {
+        try {
+            // Import BytecodeEncoder
+            const { BytecodeEncoder } = await import('../lib/bytecode-encoder.js');
+            // Convert parameters to format expected by encoder
+            const params = parameters.map((value, index) => {
+                const paramDef = functionSignature?.parameters[index];
+                return {
+                    name: paramDef?.name || `param_${index}`,
+                    type: paramDef?.type || this.inferTypeString(value)
+                };
+            });
+            const values = {};
+            params.forEach((param, index) => {
+                values[param.name] = parameters[index];
+            });
+            // Encode parameters only; function index is handled by the SDK when building instruction data
+            const encoded = await BytecodeEncoder.encodeExecute(0, params, values);
+            return Buffer.from(encoded);
+        }
+        catch (error) {
+            throw new Error(`Parameter encoding failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /// Encode individual parameter.
+    encodeParameter(value, type, index) {
+        const coercedValue = this.coerceValue(value, type);
+        const typeId = TYPE_IDS[type];
+        return {
+            type: typeId,
+            value: coercedValue
+        };
+    }
+    /**
+     * Infer Five VM type from JavaScript value
+     */
+    inferType(value) {
+        if (typeof value === 'boolean') {
+            return 'bool';
+        }
+        if (typeof value === 'string') {
+            return 'string';
+        }
+        if (typeof value === 'number') {
+            // Default to u64 for positive integers, i64 for negative
+            return Number.isInteger(value) && value >= 0 ? 'u64' : 'i64';
+        }
+        if (typeof value === 'bigint') {
+            return value >= 0 ? 'u64' : 'i64';
+        }
+        if (Array.isArray(value)) {
+            return 'array';
+        }
+        return 'string'; // Default fallback
+    }
+    /**
+     * Infer type as string
+     */
+    inferTypeString(value) {
+        const type = this.inferType(value);
+        return type;
+    }
+    // ==================== Type Coercion Methods ====================
+    coerceToU8(value) {
+        const num = Number(value);
+        if (!Number.isInteger(num) || num < 0 || num > 255) {
+            throw new Error(`Value ${value} cannot be coerced to u8 (0-255)`);
+        }
+        return num;
+    }
+    coerceToU16(value) {
+        const num = Number(value);
+        if (!Number.isInteger(num) || num < 0 || num > 65535) {
+            throw new Error(`Value ${value} cannot be coerced to u16 (0-65535)`);
+        }
+        return num;
+    }
+    coerceToU32(value) {
+        const num = Number(value);
+        if (!Number.isInteger(num) || num < 0 || num > 4294967295) {
+            throw new Error(`Value ${value} cannot be coerced to u32 (0-4294967295)`);
+        }
+        return num;
+    }
+    coerceToU64(value) {
+        if (typeof value === 'bigint') {
+            if (value < BigInt(0) || value > BigInt('18446744073709551615')) {
+                throw new Error(`Value ${value} cannot be coerced to u64 (0-2^64-1)`);
+            }
+            return value;
+        }
+        const num = Number(value);
+        if (!Number.isInteger(num) || num < 0) {
+            throw new Error(`Value ${value} cannot be coerced to u64`);
+        }
+        return num;
+    }
+    coerceToI8(value) {
+        const num = Number(value);
+        if (!Number.isInteger(num) || num < -128 || num > 127) {
+            throw new Error(`Value ${value} cannot be coerced to i8 (-128 to 127)`);
+        }
+        return num;
+    }
+    coerceToI16(value) {
+        const num = Number(value);
+        if (!Number.isInteger(num) || num < -32768 || num > 32767) {
+            throw new Error(`Value ${value} cannot be coerced to i16 (-32768 to 32767)`);
+        }
+        return num;
+    }
+    coerceToI32(value) {
+        const num = Number(value);
+        if (!Number.isInteger(num) || num < -2147483648 || num > 2147483647) {
+            throw new Error(`Value ${value} cannot be coerced to i32 (-2^31 to 2^31-1)`);
+        }
+        return num;
+    }
+    coerceToI64(value) {
+        if (typeof value === 'bigint') {
+            if (value < BigInt('-9223372036854775808') || value > BigInt('9223372036854775807')) {
+                throw new Error(`Value ${value} cannot be coerced to i64 (-2^63 to 2^63-1)`);
+            }
+            return value;
+        }
+        const num = Number(value);
+        if (!Number.isInteger(num)) {
+            throw new Error(`Value ${value} cannot be coerced to i64`);
+        }
+        return num;
+    }
+    coerceToBool(value) {
+        if (typeof value === 'boolean') {
+            return value;
+        }
+        if (typeof value === 'string') {
+            const lower = value.toLowerCase();
+            if (lower === 'true' || lower === '1')
+                return true;
+            if (lower === 'false' || lower === '0')
+                return false;
+            throw new Error(`String "${value}" cannot be coerced to boolean`);
+        }
+        if (typeof value === 'number') {
+            return value !== 0;
+        }
+        throw new Error(`Value ${value} cannot be coerced to boolean`);
+    }
+    coerceToString(value) {
+        return String(value);
+    }
+    coerceToPubkey(value) {
+        if (typeof value === 'string' && value.length === 44) {
+            return value; // Assume base58 encoded pubkey
+        }
+        throw new Error(`Value ${value} cannot be coerced to pubkey`);
+    }
+    coerceToBytes(value) {
+        if (value instanceof Uint8Array) {
+            return value;
+        }
+        if (Array.isArray(value)) {
+            return new Uint8Array(value);
+        }
+        if (typeof value === 'string') {
+            // Assume hex string
+            return new Uint8Array(Buffer.from(value, 'hex'));
+        }
+        throw new Error(`Value ${value} cannot be coerced to bytes`);
+    }
+    coerceToArray(value) {
+        if (Array.isArray(value)) {
+            return value;
+        }
+        throw new Error(`Value ${value} cannot be coerced to array`);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Five SDK - Client-Agnostic TypeScript/JavaScript library for Five VM
+ *
+ * Minimal build for Frontend integration.
+ */
+export * from './FiveSDK.js';
+export * from './types.js';
+export * from './lib/bytecode-encoder.js';
+export * from './encoding/ParameterEncoder.js';
+export * from './crypto/index.js';
+export * from './project/toml.js';
+export * from './project/config.js';
+export * from './project/workspace.js';
+export * from './wasm/vm.js';
+export * from './wasm/compiler/index.js';
+export * from './wasm/loader.js';
+export * from './testing/index.js';
+export * from './program/index.js';
+export * from './modules/namespaces.js';
+export { ProgramIdResolver, FIVE_BAKED_PROGRAM_ID } from './config/ProgramIdResolver.js';
+export { FIVE_VM_PROGRAM_ID } from './types.js';

package/dist/index.js

@@ -0,0 +1,28 @@
+/**
+ * Five SDK - Client-Agnostic TypeScript/JavaScript library for Five VM
+ *
+ * Minimal build for Frontend integration.
+ */
+// ==================== Core SDK Exports ====================
+export * from './FiveSDK.js';
+export * from './types.js';
+// export * from './validation/index.js'; // Might rely on broken things
+export * from './lib/bytecode-encoder.js';
+export * from './encoding/ParameterEncoder.js'; // Added missing export
+export * from './crypto/index.js'; // Added missing export (for PDAUtils)
+export * from './project/toml.js';
+export * from './project/config.js';
+export * from './project/workspace.js';
+export * from './wasm/vm.js';
+export * from './wasm/compiler/index.js';
+export * from './wasm/loader.js';
+export * from './testing/index.js';
+// ==================== FiveProgram High-Level API ====================
+export * from './program/index.js';
+export * from './modules/namespaces.js';
+// ==================== Program ID Resolution ====================
+export { ProgramIdResolver, FIVE_BAKED_PROGRAM_ID } from './config/ProgramIdResolver.js';
+// ==================== Constants ====================
+export { FIVE_VM_PROGRAM_ID } from './types.js';
+// Default export disabled for minimal build
+// export { FiveSDK as default };

package/dist/lib/bytecode-encoder.d.ts

@@ -0,0 +1,62 @@
+export interface ParameterDefinition {
+    name: string;
+    type: string;
+    isAccount?: boolean;
+    is_account?: boolean;
+    param_type?: string;
+    maxLen?: number;
+}
+export interface ParameterValue {
+    [key: string]: any;
+}
+export declare class BytecodeEncoder {
+    /**
+     * Parse a raw ABI type string into a canonical execute-encoding type.
+     * Supports sized string syntax like string<32>.
+     */
+    static parseTypeSpec(rawType: string): {
+        baseType: string;
+        maxLen?: number;
+    };
+    /**
+     * Get type ID for encoding.
+     */
+    static getTypeId(type: string): number;
+    /**
+     * Encode a 32-bit unsigned integer (Little Endian).
+     */
+    static encodeU32(value: number): Uint8Array;
+    /**
+     * Encode execute instruction data using WASM ParameterEncoder.
+     */
+    static encodeExecute(functionIndex: number, parameters?: ParameterDefinition[], values?: ParameterValue, retry?: boolean, options?: any): Promise<Buffer>;
+    private static isAccountParam;
+    private static getCanonicalTypeSpec;
+    private static normalizeType;
+    /**
+     * Parse parameter definitions from JSON string
+     */
+    static parseParameters(parametersJson: string): {
+        definitions: ParameterDefinition[];
+        values: ParameterValue;
+    };
+    /**
+     * Validate WASM module availability
+     */
+    static validateWasmModule(): Promise<{
+        available: boolean;
+        error?: string;
+    }>;
+    /**
+     * Create typed parameter definitions with validation
+     */
+    static createTypedParameters(params: Array<{
+        name: string;
+        type: string;
+        value: any;
+        optional?: boolean;
+    }>): {
+        definitions: ParameterDefinition[];
+        values: ParameterValue;
+    };
+}

package/dist/lib/bytecode-encoder.js

@@ -0,0 +1,281 @@
+// Bytecode encoder for the Five VM protocol.
+import { getWasmModule } from '../wasm/loader.js';
+let wasmModule = null;
+// Type mapping for encoding - matches Five protocol types.
+const TYPE_IDS = {
+    'u8': 1,
+    'u16': 2,
+    'u32': 3,
+    'u64': 4,
+    'i8': 5,
+    'i16': 6,
+    'i32': 7,
+    'i64': 8,
+    'bool': 9,
+    'pubkey': 10,
+    'string': 11,
+    'account': 12,
+    'bytes': 11,
+    'array': 13
+};
+export class BytecodeEncoder {
+    /**
+     * Parse a raw ABI type string into a canonical execute-encoding type.
+     * Supports sized string syntax like string<32>.
+     */
+    static parseTypeSpec(rawType) {
+        const normalized = (rawType || '').toString().trim().toLowerCase();
+        const sizedStringMatch = normalized.match(/^string\s*<\s*(\d+)\s*>$/);
+        if (sizedStringMatch) {
+            return {
+                baseType: 'string',
+                maxLen: Number.parseInt(sizedStringMatch[1], 10),
+            };
+        }
+        return { baseType: normalized };
+    }
+    /**
+     * Get type ID for encoding.
+     */
+    static getTypeId(type) {
+        const typeId = TYPE_IDS[type.toLowerCase()];
+        if (typeId === undefined) {
+            throw new Error(`Unknown type for encoding: ${type}`);
+        }
+        return typeId;
+    }
+    /**
+     * Encode a 32-bit unsigned integer (Little Endian).
+     */
+    static encodeU32(value) {
+        const buffer = new Uint8Array(4);
+        buffer[0] = value & 0xff;
+        buffer[1] = (value >> 8) & 0xff;
+        buffer[2] = (value >> 16) & 0xff;
+        buffer[3] = (value >>> 24) & 0xff;
+        return buffer;
+    }
+    /**
+     * Encode execute instruction data using WASM ParameterEncoder.
+     */
+    static async encodeExecute(functionIndex, parameters = [], values = {}, retry = true, options = {}) {
+        // Normalize parameter types before encoding to handle custom types (Mint, TokenAccount, etc.).
+        const normalizedParameters = parameters.map(p => {
+            const typeSpec = this.getCanonicalTypeSpec(p);
+            return {
+                ...p,
+                type: typeSpec.baseType,
+                maxLen: typeSpec.maxLen,
+            };
+        });
+        // Load WASM module using shared loader
+        if (!wasmModule) {
+            try {
+                wasmModule = await getWasmModule();
+                // Check if loaded module is valid.
+                if (wasmModule && wasmModule.ParameterEncoder) {
+                    try {
+                        // Health check: try to encode empty params.
+                        wasmModule.ParameterEncoder.encode_execute(0, []);
+                    }
+                    catch (e) {
+                        console.warn("[BytecodeEncoder] Module validation failed, falling back:", e.message);
+                        wasmModule = null; // Force retry with inline loader
+                    }
+                }
+                else {
+                    wasmModule = null;
+                }
+            }
+            catch (e) {
+                // Silently ignore loader errors and try fallback
+                wasmModule = null;
+            }
+            // Fallback: import the wasm-pack generated module for Node.js.
+            if (!wasmModule && typeof process !== 'undefined') {
+                console.log("[DEBUG] (SRC) Attempting wasm-pack module import...");
+                try {
+                    const fs = await import('fs');
+                    const path = await import('path');
+                    const url = await import('url');
+                    const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+                    // Import the wasm-pack generated entry point (five_vm_wasm.js)
+                    // which already handles all the WASM initialization.
+                    const moduleEntryPath = path.resolve(__dirname, '../assets/vm/five_vm_wasm.js');
+                    if (fs.existsSync(moduleEntryPath)) {
+                        console.log("[DEBUG] Found WASM module at:", moduleEntryPath);
+                        const wasmMod = await import(moduleEntryPath);
+                        // The wasm-pack module exports the initialized module directly.
+                        if (wasmMod && wasmMod.ParameterEncoder) {
+                            wasmModule = wasmMod;
+                            console.log("[DEBUG] WASM module imported and initialized successfully!");
+                        }
+                        else {
+                            console.error("[DEBUG] WASM module missing expected exports");
+                        }
+                    }
+                    else {
+                        console.error("[DEBUG] WASM module not found at:", moduleEntryPath);
+                    }
+                }
+                catch (err) {
+                    console.error("[DEBUG] Module import FAILED:", err);
+                    // Don't throw - let it fall through to error handling below.
+                }
+            }
+        }
+        const filteredParams = normalizedParameters;
+        const paramValues = filteredParams.map(param => {
+            const value = values[param.name];
+            if (value === undefined || value === null) {
+                throw new Error(`Missing value for parameter: ${param.name}`);
+            }
+            return { param, value };
+        });
+        if (options && options.debug) {
+            console.log(`[BytecodeEncoder] Parameters:`, paramValues.map(p => ({
+                name: p.param.name,
+                type: p.param.type || p.param.param_type,
+                normalized: this.getCanonicalTypeSpec(p.param).baseType,
+                maxLen: this.getCanonicalTypeSpec(p.param).maxLen,
+                isAccount: this.isAccountParam(p.param)
+            })));
+        }
+        // Build parameter array with full metadata for fixed-size WASM encoder
+        const paramArray = paramValues.map(({ param, value }) => {
+            const canonicalType = this.getCanonicalTypeSpec(param);
+            // Pass full parameter definition for type-aware encoding
+            return {
+                name: param.name,
+                type: canonicalType.baseType,
+                param_type: canonicalType.baseType,
+                maxLen: canonicalType.maxLen,
+                isAccount: canonicalType.baseType === 'account',
+                is_account: canonicalType.baseType === 'account',
+                value: value
+            };
+        });
+        try {
+            // Debug logging to understand parameter encoding
+            console.log(`[BytecodeEncoder] About to encode with paramArray:`, JSON.stringify(paramArray.map(p => ({
+                name: p.name || 'unknown',
+                type: p.type || 'unknown',
+                hasValue: p.value !== undefined
+            }))));
+            const encoded = wasmModule.ParameterEncoder.encode_execute(functionIndex, paramArray);
+            if (options && options.debug) {
+                const buf = Buffer.from(encoded);
+                console.log(`[BytecodeEncoder] WASM encoded ${paramArray.length} parameters: ${buf.length} bytes`);
+            }
+            console.log(`[BytecodeEncoder] Encoded result: ${Buffer.from(encoded).toString('hex')}`);
+            return Buffer.from(encoded);
+        }
+        catch (e) {
+            console.warn("[BytecodeEncoder] Encode failed via WASM:", e);
+            if (retry) {
+                console.warn("[BytecodeEncoder] Reloading WASM module and retrying...");
+                wasmModule = null; // Force reload.
+                return this.encodeExecute(functionIndex, parameters, values, false, options);
+            }
+            throw e;
+        }
+    }
+    static isAccountParam(param) {
+        if (param.isAccount || param.is_account) {
+            return true;
+        }
+        const type = this.getCanonicalTypeSpec(param).baseType;
+        return type === 'account';
+    }
+    static getCanonicalTypeSpec(param) {
+        if (param.isAccount || param.is_account) {
+            return { baseType: 'account' };
+        }
+        const rawType = (param.type || param.param_type || '').toString().trim();
+        const parsed = this.parseTypeSpec(rawType);
+        const explicitMaxLen = param.maxLen;
+        if (parsed.baseType === 'string' &&
+            explicitMaxLen !== undefined &&
+            explicitMaxLen !== null) {
+            const maxLen = Number.parseInt(String(explicitMaxLen), 10);
+            if (!Number.isNaN(maxLen)) {
+                return { baseType: 'string', maxLen };
+            }
+        }
+        // Special handling for common account-backed types in the DSL
+        if (['mint', 'tokenaccount'].includes(parsed.baseType)) {
+            return { baseType: 'account' };
+        }
+        return parsed;
+    }
+    static normalizeType(param) {
+        return this.getCanonicalTypeSpec(param).baseType;
+    }
+    /**
+     * Parse parameter definitions from JSON string
+     */
+    static parseParameters(parametersJson) {
+        try {
+            const parsed = JSON.parse(parametersJson);
+            if (Array.isArray(parsed)) {
+                // Array format: [{ name: "a", type: "u64", value: 123 }, ...]
+                const definitions = [];
+                const values = {};
+                for (const param of parsed) {
+                    if (!param.name || !param.type || param.value === undefined) {
+                        throw new Error('Parameter must have name, type, and value fields');
+                    }
+                    definitions.push({ name: param.name, type: param.type });
+                    values[param.name] = param.value;
+                }
+                return { definitions, values };
+            }
+            else {
+                throw new Error('Object format parameters require type definitions. Use array format: [{ name: "a", type: "u64", value: 123 }]');
+            }
+        }
+        catch (error) {
+            throw new Error(`Invalid parameters JSON: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Validate WASM module availability
+     */
+    static async validateWasmModule() {
+        try {
+            if (!wasmModule) {
+                wasmModule = await getWasmModule();
+            }
+            if (!wasmModule.ParameterEncoder) {
+                return { available: false, error: 'ParameterEncoder not found in WASM module' };
+            }
+            return { available: true };
+        }
+        catch (error) {
+            return {
+                available: false,
+                error: `WASM module not available: ${error instanceof Error ? error.message : 'Unknown error'}`
+            };
+        }
+    }
+    /**
+     * Create typed parameter definitions with validation
+     */
+    static createTypedParameters(params) {
+        const definitions = [];
+        const values = {};
+        for (const param of params) {
+            if (!TYPE_IDS[param.type.toLowerCase()]) {
+                throw new Error(`Unknown parameter type: ${param.type}`);
+            }
+            if (!param.optional && (param.value === undefined || param.value === null)) {
+                throw new Error(`Missing value for required parameter: ${param.name}`);
+            }
+            definitions.push({ name: param.name, type: param.type });
+            if (param.value !== undefined) {
+                values[param.name] = param.value;
+            }
+        }
+        return { definitions, values };
+    }
+}

package/dist/logging/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Simple logging that can be silenced in production
+ */
+export declare const log: {
+    debug: (message: string, ...args: any[]) => void;
+    info: (message: string, ...args: any[]) => void;
+    warn: (message: string, ...args: any[]) => void;
+    error: (message: string, ...args: any[]) => void;
+};