@5ive-tech/sdk 1.1.2

package/dist/types.d.ts

@@ -0,0 +1,356 @@
+/**
+ * Type definitions for Five SDK.
+ */
+export interface ProjectConfig {
+    name: string;
+    version: string;
+    description?: string;
+    sourceDir: string;
+    buildDir: string;
+    target?: CompilationTarget;
+    entryPoint?: string;
+    outputArtifactName?: string;
+    cluster?: string;
+    commitment?: string;
+    rpcUrl?: string;
+    programId?: string;
+    namespaceManager?: string;
+    keypairPath?: string;
+    optimizations?: ProjectOptimizations;
+    dependencies?: ProjectDependency[];
+    multiFileMode?: boolean;
+    wasm?: {
+        loader?: 'auto' | 'node' | 'bundler';
+        modulePaths?: string[];
+    };
+}
+export interface ProjectOptimizations {
+    enableCompression?: boolean;
+    enableConstraintOptimization?: boolean;
+    optimizationLevel?: 'production' | 'development';
+}
+export interface ProjectDependency {
+    name: string;
+    version: string;
+    type: 'five' | 'wasm' | 'solana';
+    path?: string;
+}
+export type CompilationTarget = 'vm' | 'solana' | 'debug' | 'test' | 'deployment';
+export interface CompilationOptions {
+    /** Source file path (if applicable) */
+    sourceFile?: string;
+    /** Output file path (if applicable) */
+    outputFile?: string;
+    /** ABI output file path (if applicable) */
+    abiOutputFile?: string;
+    /** Enable optimizations */
+    optimize?: boolean;
+    /** Optimization level */
+    optimizationLevel?: 'production' | 'development';
+    /** Target environment */
+    target?: CompilationTarget;
+    /** Include debug info in bytecode */
+    includeDebugInfo?: boolean;
+    debug?: boolean;
+    /** Max allowed bytecode size in bytes */
+    maxBytecodeSize?: number;
+    maxSize?: number;
+    /** Enable general compression */
+    enableCompression?: boolean;
+    /** Include compilation metrics */
+    includeMetrics?: boolean;
+    /** Metrics output format */
+    metricsFormat?: "json" | "csv" | "toml";
+    /** Error output format */
+    errorFormat?: "terminal" | "json" | "lsp";
+    /** Include comprehensive metrics */
+    comprehensiveMetrics?: boolean;
+    /** Output file for metrics */
+    metricsOutput?: string;
+    /** Enable constraint cache */
+    enable_constraint_cache?: boolean;
+    /** Flat namespace for modules */
+    flatNamespace?: boolean;
+}
+export type FiveScript = FiveScriptSource | FiveBytecode;
+export interface CompilationResult {
+    success: boolean;
+    bytecode?: Uint8Array;
+    abi?: any;
+    metadata?: CompilationMetadata;
+    errors?: CompilationError[];
+    warnings?: CompilationWarning[];
+    disassembly?: string[];
+    metrics?: CompilationMetrics;
+    metricsReport?: CompilationMetricsReport;
+    fiveFile?: FiveCompiledFile;
+    publicFunctionNames?: string[];
+    functionNames?: string[] | FunctionNameEntry[];
+}
+export interface CompilationMetadata {
+    sourceFile: string;
+    timestamp: string;
+    compilerVersion: string;
+    target: CompilationTarget;
+    optimizations: string[];
+    originalSize: number;
+    compressedSize: number;
+    compressionRatio: number;
+    sourceSize?: number;
+    bytecodeSize?: number;
+    compilationTime?: number;
+    functions?: any[];
+}
+export interface CompilationError {
+    type: string;
+    message: string;
+    line?: number;
+    column?: number;
+    sourceLocation?: string;
+    suggestion?: string;
+    code?: string;
+    severity?: string;
+    category?: string;
+    description?: string;
+    location?: any;
+    suggestions?: string[];
+}
+export interface CompilationWarning {
+    type: string;
+    message: string;
+    line?: number;
+    column?: number;
+    sourceLocation?: string;
+}
+export interface CompilationMetrics {
+    compilationTime: number;
+    memoryUsed: number;
+    optimizationTime: number;
+    bytecodeSize: number;
+    instructionCount: number;
+    functionCount: number;
+}
+export interface CompilationMetricsReport {
+    format: string;
+    exported: string;
+    detailed?: any;
+}
+export interface VMExecutionOptions {
+    bytecode: Uint8Array;
+    inputData?: Uint8Array;
+    accounts?: AccountInfo[];
+    maxComputeUnits?: number;
+    enableLogging?: boolean;
+    enableProfiling?: boolean;
+}
+export interface VMExecutionResult {
+    success: boolean;
+    result?: any;
+    error?: VMError;
+    logs?: string[];
+    computeUnitsUsed?: number;
+    executionTime?: number;
+    memoryUsage?: MemoryUsage;
+    profileData?: ProfileData;
+    status?: string;
+    stoppedAt?: string;
+    errorMessage?: string;
+}
+export interface VMError {
+    type: string;
+    message: string;
+    instructionPointer?: number;
+    stackTrace?: string[];
+    errorCode?: number;
+    details?: any;
+}
+export interface AccountInfo {
+    pubkey?: string;
+    key?: Uint8Array;
+    lamports: number;
+    data: Uint8Array;
+    owner?: Uint8Array | string;
+    executable?: boolean;
+    rentEpoch?: number;
+    isWritable?: boolean;
+    isSigner?: boolean;
+}
+export interface MemoryUsage {
+    heapUsed: number;
+    heapTotal: number;
+    external: number;
+    arrayBuffers: number;
+    rss: number;
+}
+export interface ProfileData {
+    instructionCounts: Map<string, number>;
+    functionCallCounts: Map<string, number>;
+    hotspots: Array<{
+        instruction: string;
+        count: number;
+        percentage: number;
+    }>;
+}
+export interface Logger {
+    debug(message: string, ...args: any[]): void;
+    info(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+    error(message: string, ...args: any[]): void;
+}
+export interface CLIError extends Error {
+    code: string;
+    exitCode?: number;
+    category: string;
+    details?: any;
+}
+export declare const FIVE_VM_PROGRAM_ID = "Five111111111111111111111111111111111111111";
+export interface FiveSDKConfig {
+    network?: string;
+    connection?: any;
+    payer?: any;
+    confirmTransactionInitialTimeout?: number;
+    debug?: boolean;
+    fiveVMProgramId?: string;
+}
+export interface FiveScriptSource {
+    filename: string;
+    content: string;
+}
+export type FiveBytecode = Uint8Array;
+export type ScriptAccount = SerializableAccount;
+export interface SerializableAccount {
+    pubkey: string;
+    data: string;
+    lamports: number;
+    owner: string;
+    executable: boolean;
+    isSigner?: boolean;
+    isWritable?: boolean;
+}
+export interface DeploymentOptions {
+    network?: string;
+    payer?: any;
+    space?: number;
+    programId?: string;
+    scriptAccount?: any;
+    extraLamports?: number;
+    debug?: boolean;
+    permissions?: number;
+    adminAccount?: string;
+    estimateFees?: boolean;
+    fiveVMProgramId?: string;
+    exportMetadata?: {
+        methods?: string[];
+        interfaces?: Array<{
+            name: string;
+            methodMap?: Record<string, string>;
+        }>;
+    };
+    namespace?: string;
+}
+export interface FeeInformation {
+    feeBps: number;
+    basisLamports: number;
+    feeLamports: number;
+    totalEstimatedCost: number;
+    costBreakdown: {
+        basis: string;
+        fee: string;
+        total: string;
+    };
+}
+export interface SerializedDeployment {
+    programId: string;
+    signature?: string;
+    instruction?: any;
+    scriptAccount?: string;
+    requiredSigners?: string[];
+    estimatedCost?: number;
+    bytecodeSize?: number;
+    setupInstructions?: any;
+    adminAccount?: string;
+    feeInformation?: FeeInformation;
+}
+export interface SerializedExecution {
+    transactionId?: string;
+    result?: any;
+    logs?: string[];
+    estimatedComputeUnits?: number;
+    instruction?: any;
+    scriptAccount?: string;
+    parameters?: any;
+    requiredSigners?: string[];
+    adminAccount?: string;
+    feeInformation?: FeeInformation;
+}
+export interface SerializedInstruction {
+    programId: string;
+    keys: Array<{
+        pubkey: string;
+        isSigner: boolean;
+        isWritable: boolean;
+    }>;
+    data: string;
+}
+export interface ExecutionOptions extends VMExecutionOptions {
+}
+export declare class FiveSDKError extends Error {
+    code: string;
+    details?: any;
+    constructor(message: string, code: string, details?: any);
+}
+export declare class ExecutionSDKError extends FiveSDKError {
+    constructor(message: string, details?: any);
+}
+export declare class CompilationSDKError extends FiveSDKError {
+    constructor(message: string, details?: any);
+}
+export interface EncodedParameters {
+    data: Uint8Array;
+}
+export interface EncodedParameter {
+    type: string | number;
+    value: any;
+}
+export interface ParameterEncodingOptions {
+    none?: boolean;
+    strict?: boolean;
+}
+export declare class ParameterEncodingError extends Error {
+    details?: any;
+    constructor(message: string, details?: any);
+}
+export interface FiveCompiledFile {
+    filename: string;
+    bytecode: string;
+    metadata?: CompilationMetadata;
+    abi?: any;
+    debug?: any;
+    metrics?: any;
+    disassembly?: string[];
+    version: string;
+}
+export interface FiveFunction {
+    name: string;
+    parameters: FiveParameter[];
+    returnType?: FiveType;
+}
+export interface FiveParameter {
+    name: string;
+    type: FiveType;
+}
+export type FiveType = string;
+export interface FunctionNameEntry {
+    name: string;
+    index: number;
+    function_index?: number;
+}
+export interface Provider {
+    connection: any;
+    publicKey?: {
+        toBase58(): string;
+    };
+    sendAndConfirm?: (tx: any, // Transaction | VersionedTransaction
+    signers?: any[], options?: any) => Promise<string>;
+    simulate?: (tx: any, signers?: any[], options?: any) => Promise<any>;
+}

package/dist/types.js

@@ -0,0 +1,32 @@
+/**
+ * Type definitions for Five SDK.
+ */
+// ==================== Legacy SDK Types (for compatibility) ====================
+export const FIVE_VM_PROGRAM_ID = "Five111111111111111111111111111111111111111";
+export class FiveSDKError extends Error {
+    constructor(message, code, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'FiveSDKError';
+    }
+}
+export class ExecutionSDKError extends FiveSDKError {
+    constructor(message, details) {
+        super(message, 'EXECUTION_ERROR', details);
+        this.name = 'ExecutionSDKError';
+    }
+}
+export class CompilationSDKError extends FiveSDKError {
+    constructor(message, details) {
+        super(message, 'COMPILATION_ERROR', details);
+        this.name = 'CompilationSDKError';
+    }
+}
+export class ParameterEncodingError extends Error {
+    constructor(message, details) {
+        super(message);
+        this.details = details;
+        this.name = 'ParameterEncodingError';
+    }
+}

package/dist/utils/abi.d.ts

@@ -0,0 +1,31 @@
+export interface NormalizedABIFunction {
+    name: string;
+    index: number;
+    parameters: Array<{
+        name: string;
+        type: string;
+        optional?: boolean;
+    }>;
+    returnType?: string;
+    accounts?: any[];
+    visibility?: 'public' | 'private';
+}
+/**
+ * Normalize ABI function definitions that may be emitted as either arrays (FIVEABI)
+ * or maps (SimpleABI) into a consistent array format.
+ */
+export declare function normalizeAbiFunctions(abiFunctions: unknown): NormalizedABIFunction[];
+/**
+ * Find a function in the ABI by name, supporting both flat and qualified names
+ *
+ * Handles both naming modes:
+ * - Flat namespace: "functionName"
+ * - Qualified namespace: "module::functionName"
+ *
+ * Falls back to partial matching if exact match not found.
+ */
+export declare function findFunctionInABI(abi: any, functionName: string): NormalizedABIFunction | undefined;
+/**
+ * Resolve function name to index using ABI
+ */
+export declare function resolveFunctionIndex(abi: any, functionName: string): number;

package/dist/utils/abi.js

@@ -0,0 +1,92 @@
+/**
+ * Normalize ABI function definitions that may be emitted as either arrays (FIVEABI)
+ * or maps (SimpleABI) into a consistent array format.
+ */
+export function normalizeAbiFunctions(abiFunctions) {
+    if (!abiFunctions)
+        return [];
+    const functionsArray = Array.isArray(abiFunctions)
+        ? abiFunctions
+        : Object.entries(abiFunctions).map(([name, func]) => ({
+            name,
+            ...(func || {}),
+        }));
+    return functionsArray
+        .map((func, idx) => {
+        const parameters = Array.isArray(func.parameters) ? func.parameters : [];
+        return {
+            name: func.name ?? `function_${func.index ?? idx}`,
+            index: typeof func.index === 'number' ? func.index : idx,
+            parameters: parameters.map((param, paramIdx) => ({
+                name: param.name ?? `param${paramIdx}`,
+                type: param.type ?? param.param_type ?? param.paramType ?? '',
+                optional: param.optional ?? false,
+                isAccount: param.isAccount ?? param.is_account ?? false,
+            })),
+            returnType: func.returnType ?? func.return_type,
+            accounts: func.accounts ?? [],
+            visibility: func.visibility ??
+                (func.is_public === false ? 'private' : 'public'),
+        };
+    })
+        .sort((a, b) => a.index - b.index);
+}
+/**
+ * Find a function in the ABI by name, supporting both flat and qualified names
+ *
+ * Handles both naming modes:
+ * - Flat namespace: "functionName"
+ * - Qualified namespace: "module::functionName"
+ *
+ * Falls back to partial matching if exact match not found.
+ */
+export function findFunctionInABI(abi, functionName) {
+    const functions = normalizeAbiFunctions(abi);
+    // Try exact match first
+    let func = functions.find(f => f.name === functionName);
+    if (func)
+        return func;
+    // Try qualified name match (e.g., "module::function" -> "function")
+    if (functionName.includes('::')) {
+        const parts = functionName.split('::');
+        const unqualifiedName = parts[parts.length - 1];
+        func = functions.find(f => f.name === unqualifiedName);
+        if (func)
+            return func;
+    }
+    // Try partial match (e.g., "function" matches "module::function")
+    func = functions.find(f => f.name.endsWith(`::${functionName}`));
+    if (func)
+        return func;
+    // No match found
+    return undefined;
+}
+/**
+ * Resolve function name to index using ABI
+ */
+export function resolveFunctionIndex(abi, functionName) {
+    if (!abi || !abi.functions) {
+        throw new Error("No ABI information available for function name resolution");
+    }
+    // Handle both array format: [{ name: "add", index: 0 }] and object format: { "add": { index: 0 } }
+    if (Array.isArray(abi.functions)) {
+        // Array format (legacy)
+        const func = abi.functions.find((f) => f.name === functionName);
+        if (!func) {
+            const availableFunctions = abi.functions
+                .map((f) => f.name)
+                .join(", ");
+            throw new Error(`Function '${functionName}' not found in ABI. Available functions: ${availableFunctions}`);
+        }
+        return func.index;
+    }
+    else {
+        // Object format (new WASM ABI)
+        const func = abi.functions[functionName];
+        if (!func) {
+            const availableFunctions = Object.keys(abi.functions).join(", ");
+            throw new Error(`Function '${functionName}' not found in ABI. Available functions: ${availableFunctions}`);
+        }
+        return func.index;
+    }
+}

package/dist/utils/transaction.d.ts

@@ -0,0 +1,5 @@
+export declare function pollForConfirmation(connection: any, signature: string, commitment?: string, timeoutMs?: number, debug?: boolean): Promise<{
+    success: boolean;
+    err?: any;
+    error?: string;
+}>;

package/dist/utils/transaction.js

@@ -0,0 +1,48 @@
+export async function pollForConfirmation(connection, signature, commitment = "confirmed", timeoutMs = 120000, debug = false) {
+    const startTime = Date.now();
+    const pollIntervalMs = 1000;
+    if (debug) {
+        console.log(`[FiveSDK] Starting confirmation poll with ${timeoutMs}ms timeout`);
+    }
+    while (Date.now() - startTime < timeoutMs) {
+        try {
+            const confirmationStatus = await connection.getSignatureStatus(signature);
+            if (debug && (Date.now() - startTime) % 10000 < 1000) {
+                console.log(`[FiveSDK] Confirmation status: ${JSON.stringify(confirmationStatus.value)}`);
+            }
+            if (confirmationStatus.value) {
+                if (confirmationStatus.value.confirmationStatus === commitment ||
+                    confirmationStatus.value.confirmations >= 1) {
+                    const transactionError = confirmationStatus.value.err;
+                    const succeeded = !transactionError;
+                    if (debug) {
+                        console.log(`[FiveSDK] Transaction confirmed after ${Date.now() - startTime}ms${succeeded ? '' : ' (with error)'}`);
+                        if (transactionError) {
+                            console.log(`[FiveSDK] Transaction error: ${JSON.stringify(transactionError)}`);
+                        }
+                    }
+                    return {
+                        success: succeeded,
+                        err: transactionError,
+                        error: transactionError ? JSON.stringify(transactionError) : undefined,
+                    };
+                }
+            }
+            await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+        }
+        catch (error) {
+            if (debug) {
+                console.log(`[FiveSDK] Polling error: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+        }
+    }
+    const elapsed = Date.now() - startTime;
+    if (debug) {
+        console.log(`[FiveSDK] Confirmation polling timeout after ${elapsed}ms`);
+    }
+    return {
+        success: false,
+        error: `Transaction confirmation timeout after ${elapsed}ms. Signature: ${signature}`,
+    };
+}

package/dist/validation/InputValidator.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Five SDK input validation.
+ * Protects against common injection and resource abuse cases.
+ */
+import { FiveSDKError } from '../types.js';
+/**
+ * Input validation configuration
+ */
+export interface ValidationConfig {
+    /** Maximum source code size in bytes */
+    maxSourceSize: number;
+    /** Maximum bytecode size in bytes */
+    maxBytecodeSize: number;
+    /** Maximum parameter count */
+    maxParameters: number;
+    /** Maximum parameter value size */
+    maxParameterSize: number;
+    /** Maximum file path length */
+    maxPathLength: number;
+    /** Maximum account count */
+    maxAccounts: number;
+    /** Maximum string length */
+    maxStringLength: number;
+    /** Maximum array length */
+    maxArrayLength: number;
+    /** Allowed file extensions */
+    allowedExtensions: string[];
+    /** Path whitelist patterns */
+    allowedPaths: RegExp[];
+}
+/**
+ * Default validation configuration
+ */
+export declare const DEFAULT_VALIDATION_CONFIG: ValidationConfig;
+/**
+ * Validation error types
+ */
+export declare enum ValidationErrorType {
+    INVALID_INPUT = "INVALID_INPUT",
+    SIZE_EXCEEDED = "SIZE_EXCEEDED",
+    TYPE_MISMATCH = "TYPE_MISMATCH",
+    UNSAFE_PATH = "UNSAFE_PATH",
+    RESOURCE_EXHAUSTION = "RESOURCE_EXHAUSTION",
+    MALICIOUS_CONTENT = "MALICIOUS_CONTENT",
+    ENCODING_ERROR = "ENCODING_ERROR"
+}
+/**
+ * Input validation error
+ */
+export declare class ValidationError extends FiveSDKError {
+    type: ValidationErrorType;
+    field?: string;
+    value?: any;
+    constructor(message: string, type: ValidationErrorType, field?: string, value?: any);
+}
+/**
+ * Input validator for Five SDK
+ */
+export declare class InputValidator {
+    private config;
+    constructor(config?: ValidationConfig);
+    /**
+     * Validate source code input
+     */
+    validateSourceCode(source: string, context?: string): void;
+    /**
+     * Validate bytecode input
+     */
+    validateBytecode(bytecode: Uint8Array, context?: string): void;
+    /**
+     * Validate file path
+     */
+    validateFilePath(path: string, context?: string): void;
+    /**
+     * Validate function parameters
+     */
+    validateParameters(parameters: any[], context?: string): void;
+    /**
+     * Validate individual parameter
+     */
+    validateParameter(parameter: any, context?: string): void;
+    /**
+     * Validate account addresses
+     */
+    validateAccounts(accounts: string[], context?: string): void;
+    /**
+     * Validate Base58 address
+     */
+    validateBase58Address(address: string, context?: string): void;
+    /**
+     * Validate function name or index
+     */
+    validateFunctionReference(functionRef: string | number, context?: string): void;
+    /**
+     * Validate options object
+     */
+    validateOptions(options: any, context?: string): void;
+    /**
+     * Validate string input
+     */
+    private validateString;
+    /**
+     * Validate number input (also exposed as public for external use)
+     */
+    validateNumber(value: number, context?: string): void;
+    /**
+     * Validate number input (private implementation)
+     */
+    private validateNumberPrivate;
+    /**
+     * Validate buffer input
+     */
+    private validateBuffer;
+    /**
+     * Validate array input
+     */
+    private validateArray;
+    /**
+     * Check for malicious patterns in source code
+     */
+    private containsMaliciousPatterns;
+}
+/**
+ * Global validator instance
+ */
+export declare const validator: InputValidator;
+/**
+ * Validation decorators for class methods
+ */
+export declare function validateInput(validationFn: (args: any[]) => void): (target: any, propertyName: string, descriptor: PropertyDescriptor) => void;
+/**
+ * Common validation patterns
+ */
+export declare const Validators: {
+    sourceCode: (source: string) => void;
+    bytecode: (bytecode: Uint8Array) => void;
+    filePath: (path: string) => void;
+    parameters: (params: any[]) => void;
+    accounts: (accounts: string[]) => void;
+    functionRef: (ref: string | number) => void;
+    options: (opts: any) => void;
+};