@5ive-tech/sdk 1.1.2

package/dist/logging/index.js

@@ -0,0 +1,10 @@
+/**
+ * Simple logging that can be silenced in production
+ */
+const isProduction = (typeof process !== 'undefined' && process?.env?.NODE_ENV === 'production');
+export const log = {
+    debug: (message, ...args) => !isProduction && console.debug(`[FiveSDK] ${message}`, ...args),
+    info: (message, ...args) => !isProduction && console.info(`[FiveSDK] ${message}`, ...args),
+    warn: (message, ...args) => console.warn(`[FiveSDK] ${message}`, ...args),
+    error: (message, ...args) => console.error(`[FiveSDK] ${message}`, ...args)
+};

package/dist/metadata/index.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Five SDK Script Metadata System
+ *
+ * Real implementation for parsing script account data and extracting ABI information
+ * from deployed Five scripts. This replaces mock implementations with production-ready
+ * Solana account data parsing.
+ */
+/**
+ * Account data interface for client-agnostic blockchain interactions
+ */
+export interface AccountData {
+    /** Account address as base58 string */
+    address: string;
+    /** Account data as byte array */
+    data: Uint8Array;
+    /** Account owner program ID */
+    owner: string;
+    /** Account balance in lamports */
+    lamports: number;
+}
+/**
+ * Account fetcher interface for retrieving account data
+ */
+export interface AccountFetcher {
+    /** Get single account data */
+    getAccountData(address: string): Promise<AccountData | null>;
+    /** Get multiple account data in batch */
+    getMultipleAccountsData(addresses: string[]): Promise<Map<string, AccountData | null>>;
+}
+/**
+ * Script metadata extracted from deployed script accounts
+ */
+export interface ScriptMetadata {
+    /** Script account address */
+    address: string;
+    /** Script bytecode */
+    bytecode: Uint8Array;
+    /** Script ABI with function definitions */
+    abi: ScriptABI;
+    /** Deploy timestamp */
+    deployedAt: number;
+    /** Script version */
+    version: string;
+    /** Authority that deployed the script */
+    authority: string;
+}
+/**
+ * Script ABI definition
+ */
+export interface ScriptABI {
+    /** Script name */
+    name: string;
+    /** Function definitions */
+    functions: FunctionDefinition[];
+    /** Type definitions */
+    types?: TypeDefinition[];
+    /** Account constraints */
+    accounts?: AccountConstraint[];
+}
+/**
+ * Function definition in script ABI
+ */
+export interface FunctionDefinition {
+    /** Function name */
+    name: string;
+    /** Function index in bytecode */
+    index: number;
+    /** Function parameters */
+    parameters: ParameterDefinition[];
+    /** Return type */
+    returnType?: string;
+    /** Return type (snake_case from compiled ABI) */
+    return_type?: string | null;
+    /** Function visibility */
+    visibility: 'public' | 'private';
+    /** Function visibility (snake_case from compiled ABI) */
+    is_public?: boolean;
+    /** Documentation */
+    docs?: string;
+    /** Bytecode offset (from compiled ABI) */
+    bytecode_offset?: number;
+}
+/**
+ * Parameter definition
+ */
+export interface ParameterDefinition {
+    /** Parameter name */
+    name: string;
+    /** Parameter type */
+    type: string;
+    /** Parameter type (snake_case from compiled ABI) */
+    param_type?: string;
+    /** Whether this is an account parameter */
+    is_account?: boolean;
+    /** Account attributes (e.g., "mut", "signer", "init") */
+    attributes?: string[];
+    /** Whether parameter is optional */
+    optional?: boolean;
+    /** Parameter documentation */
+    docs?: string;
+}
+/**
+ * Type definition
+ */
+export interface TypeDefinition {
+    /** Type name */
+    name: string;
+    /** Type structure */
+    structure: 'struct' | 'enum' | 'alias';
+    /** Type fields (for structs) */
+    fields?: Array<{
+        name: string;
+        type: string;
+    }>;
+    /** Type variants (for enums) */
+    variants?: Array<{
+        name: string;
+        value?: number;
+    }>;
+    /** Alias target (for type aliases) */
+    target?: string;
+}
+/**
+ * Account constraint definition
+ */
+export interface AccountConstraint {
+    /** Account name */
+    name: string;
+    /** Account type */
+    type: 'signer' | 'writable' | 'readonly' | 'pda';
+    /** Seeds for PDA derivation */
+    seeds?: string[];
+    /** Required account properties */
+    properties?: Record<string, any>;
+}
+/**
+ * Script metadata parser and manager
+ */
+export declare class ScriptMetadataParser {
+    private static readonly SCRIPT_MAGIC;
+    private static readonly CURRENT_VERSION;
+    private static readonly HEADER_SIZE;
+    /**
+     * Parse script metadata from account data
+     */
+    static parseMetadata(accountData: Uint8Array, address: string): ScriptMetadata;
+    /**
+     * Get script metadata from blockchain using account fetcher
+     */
+    static getScriptMetadata(accountFetcher: AccountFetcher, scriptAddress: string): Promise<ScriptMetadata>;
+    /**
+     * Get multiple script metadata entries using account fetcher
+     */
+    static getMultipleScriptMetadata(accountFetcher: AccountFetcher, scriptAddresses: string[]): Promise<Map<string, ScriptMetadata | null>>;
+    /**
+     * Extract function signatures from ABI
+     */
+    static extractFunctionSignatures(abi: ScriptABI): Array<{
+        name: string;
+        index: number;
+        parameters: ParameterDefinition[];
+        signature: string;
+    }>;
+    /**
+     * Generate function signature string
+     */
+    static generateFunctionSignature(func: FunctionDefinition): string;
+    /**
+     * Validate script ABI structure
+     */
+    static validateABI(abi: any): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Validate function definition
+     */
+    private static validateFunction;
+    private static readU32;
+    private static readU64;
+    private static arraysEqual;
+}
+/**
+ * Client-agnostic metadata cache
+ */
+export declare class MetadataCache {
+    private cache;
+    private defaultTTL;
+    /**
+     * Get metadata from cache or fetch
+     */
+    getMetadata(scriptAddress: string, fetcher: (address: string) => Promise<ScriptMetadata>, ttl?: number): Promise<ScriptMetadata>;
+    /**
+     * Invalidate cache entry
+     */
+    invalidate(scriptAddress: string): void;
+    /**
+     * Clear expired entries
+     */
+    cleanup(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        size: number;
+        hitRate: number;
+        entries: Array<{
+            address: string;
+            age: number;
+            ttl: number;
+        }>;
+    };
+}

package/dist/metadata/index.js

@@ -0,0 +1,296 @@
+/**
+ * Five SDK Script Metadata System
+ *
+ * Real implementation for parsing script account data and extracting ABI information
+ * from deployed Five scripts. This replaces mock implementations with production-ready
+ * Solana account data parsing.
+ */
+import { Base58Utils } from '../crypto/index.js';
+import { normalizeAbiFunctions } from '../utils/abi.js';
+/**
+ * Script metadata parser and manager
+ */
+export class ScriptMetadataParser {
+    /**
+     * Parse script metadata from account data
+     */
+    static parseMetadata(accountData, address) {
+        if (accountData.length < this.HEADER_SIZE) {
+            throw new Error(`Invalid script account: data too small (${accountData.length} bytes, minimum ${this.HEADER_SIZE})`);
+        }
+        let offset = 0;
+        // Parse header
+        const magic = accountData.slice(offset, offset + 8);
+        offset += 8;
+        if (!this.arraysEqual(magic, this.SCRIPT_MAGIC)) {
+            throw new Error('Invalid script account: magic bytes mismatch');
+        }
+        const version = this.readU32(accountData, offset);
+        offset += 4;
+        if (version > this.CURRENT_VERSION) {
+            throw new Error(`Unsupported script version: ${version} (max supported: ${this.CURRENT_VERSION})`);
+        }
+        const timestamp = this.readU64(accountData, offset);
+        offset += 8;
+        const authority = accountData.slice(offset, offset + 32);
+        offset += 32;
+        const bytecodeLength = this.readU32(accountData, offset);
+        offset += 4;
+        const abiLength = this.readU32(accountData, offset);
+        offset += 4;
+        // Skip reserved space
+        offset += 8;
+        // Validate data lengths
+        const expectedSize = this.HEADER_SIZE + bytecodeLength + abiLength;
+        if (accountData.length < expectedSize) {
+            throw new Error(`Invalid script account: expected ${expectedSize} bytes, got ${accountData.length}`);
+        }
+        // Extract bytecode
+        const bytecode = accountData.slice(offset, offset + bytecodeLength);
+        offset += bytecodeLength;
+        // Extract and parse ABI
+        const abiData = accountData.slice(offset, offset + abiLength);
+        const abiJson = new TextDecoder().decode(abiData);
+        let abi;
+        try {
+            abi = JSON.parse(abiJson);
+        }
+        catch (error) {
+            throw new Error(`Invalid ABI JSON: ${error instanceof Error ? error.message : 'Parse error'}`);
+        }
+        return {
+            address,
+            bytecode,
+            abi,
+            deployedAt: timestamp,
+            version: version.toString(),
+            authority: Base58Utils.encode(authority)
+        };
+    }
+    /**
+     * Get script metadata from blockchain using account fetcher
+     */
+    static async getScriptMetadata(accountFetcher, scriptAddress) {
+        try {
+            // Validate address format (basic base58 check)
+            if (!scriptAddress || scriptAddress.length < 32 || scriptAddress.length > 44) {
+                throw new Error(`Invalid script address format: ${scriptAddress}`);
+            }
+            // Fetch account data
+            const accountData = await accountFetcher.getAccountData(scriptAddress);
+            if (!accountData) {
+                throw new Error(`Script account not found: ${scriptAddress}`);
+            }
+            if (!accountData.data || accountData.data.length === 0) {
+                throw new Error(`Script account has no data: ${scriptAddress}`);
+            }
+            // Parse metadata
+            return this.parseMetadata(accountData.data, scriptAddress);
+        }
+        catch (error) {
+            throw new Error(`Failed to get script metadata for ${scriptAddress}: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Get multiple script metadata entries using account fetcher
+     */
+    static async getMultipleScriptMetadata(accountFetcher, scriptAddresses) {
+        const results = new Map();
+        // Validate addresses (basic format check)
+        const validAddresses = [];
+        for (const address of scriptAddresses) {
+            if (address && address.length >= 32 && address.length <= 44) {
+                validAddresses.push(address);
+            }
+            else {
+                results.set(address, null);
+            }
+        }
+        if (validAddresses.length === 0) {
+            return results;
+        }
+        try {
+            // Batch fetch account data
+            const accountDataMap = await accountFetcher.getMultipleAccountsData(validAddresses);
+            // Parse metadata for each account
+            for (const address of validAddresses) {
+                const accountData = accountDataMap.get(address);
+                if (!accountData || !accountData.data || accountData.data.length === 0) {
+                    results.set(address, null);
+                    continue;
+                }
+                try {
+                    const metadata = this.parseMetadata(accountData.data, address);
+                    results.set(address, metadata);
+                }
+                catch (error) {
+                    console.warn(`Failed to parse metadata for ${address}:`, error);
+                    results.set(address, null);
+                }
+            }
+        }
+        catch (error) {
+            throw new Error(`Batch metadata fetch failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+        return results;
+    }
+    /**
+     * Extract function signatures from ABI
+     */
+    static extractFunctionSignatures(abi) {
+        const functions = normalizeAbiFunctions(abi.functions ?? abi).map((func) => ({
+            name: func.name,
+            index: func.index,
+            parameters: func.parameters,
+            returnType: func.returnType,
+            visibility: func.visibility ?? 'public',
+        }));
+        return functions.map(func => ({
+            name: func.name,
+            index: func.index,
+            parameters: func.parameters,
+            signature: this.generateFunctionSignature(func)
+        }));
+    }
+    /**
+     * Generate function signature string
+     */
+    static generateFunctionSignature(func) {
+        const paramStrings = func.parameters.map(param => `${param.name}: ${param.type}${param.optional ? '?' : ''}`);
+        const returnType = func.returnType ? ` -> ${func.returnType}` : '';
+        return `${func.name}(${paramStrings.join(', ')})${returnType}`;
+    }
+    /**
+     * Validate script ABI structure
+     */
+    static validateABI(abi) {
+        const errors = [];
+        if (!abi || typeof abi !== 'object') {
+            errors.push('ABI must be an object');
+            return { valid: false, errors };
+        }
+        if (typeof abi.name !== 'string' || abi.name.length === 0) {
+            errors.push('ABI must have a non-empty name');
+        }
+        const functions = normalizeAbiFunctions(abi.functions ?? abi);
+        if (functions.length === 0) {
+            errors.push('ABI must have at least one function');
+        }
+        for (let i = 0; i < functions.length; i++) {
+            const func = functions[i];
+            const funcErrors = this.validateFunction(func, i);
+            errors.push(...funcErrors);
+        }
+        return {
+            valid: errors.length === 0,
+            errors
+        };
+    }
+    /**
+     * Validate function definition
+     */
+    static validateFunction(func, index) {
+        const errors = [];
+        const prefix = `Function ${index}`;
+        if (typeof func.name !== 'string' || func.name.length === 0) {
+            errors.push(`${prefix}: must have a non-empty name`);
+        }
+        if (typeof func.index !== 'number' || func.index < 0) {
+            errors.push(`${prefix}: must have a non-negative index`);
+        }
+        if (!Array.isArray(func.parameters)) {
+            errors.push(`${prefix}: must have a parameters array`);
+        }
+        if (func.visibility && !['public', 'private'].includes(func.visibility)) {
+            errors.push(`${prefix}: visibility must be 'public' or 'private'`);
+        }
+        return errors;
+    }
+    // Utility methods for binary data parsing
+    static readU32(data, offset) {
+        return (data[offset] |
+            (data[offset + 1] << 8) |
+            (data[offset + 2] << 16) |
+            (data[offset + 3] << 24)) >>> 0; // Convert to unsigned
+    }
+    static readU64(data, offset) {
+        // Read as two 32-bit values and combine (JavaScript limitation for large numbers)
+        const low = this.readU32(data, offset);
+        const high = this.readU32(data, offset + 4);
+        return low + (high * 0x100000000);
+    }
+    static arraysEqual(a, b) {
+        if (a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i++) {
+            if (a[i] !== b[i])
+                return false;
+        }
+        return true;
+    }
+}
+ScriptMetadataParser.SCRIPT_MAGIC = new Uint8Array([
+    0x46, 0x49, 0x56, 0x45, 0x5F, 0x53, 0x43, 0x52 // "FIVE_SCR"
+]);
+ScriptMetadataParser.CURRENT_VERSION = 1;
+ScriptMetadataParser.HEADER_SIZE = 64; // Fixed header size
+/**
+ * Client-agnostic metadata cache
+ */
+export class MetadataCache {
+    constructor() {
+        this.cache = new Map();
+        this.defaultTTL = 5 * 60 * 1000; // 5 minutes
+    }
+    /**
+     * Get metadata from cache or fetch
+     */
+    async getMetadata(scriptAddress, fetcher, ttl = this.defaultTTL) {
+        const now = Date.now();
+        const cached = this.cache.get(scriptAddress);
+        if (cached && (now - cached.timestamp) < cached.ttl) {
+            return cached.metadata;
+        }
+        // Fetch fresh metadata
+        const metadata = await fetcher(scriptAddress);
+        // Cache the result
+        this.cache.set(scriptAddress, {
+            metadata,
+            timestamp: now,
+            ttl
+        });
+        return metadata;
+    }
+    /**
+     * Invalidate cache entry
+     */
+    invalidate(scriptAddress) {
+        this.cache.delete(scriptAddress);
+    }
+    /**
+     * Clear expired entries
+     */
+    cleanup() {
+        const now = Date.now();
+        for (const [address, entry] of this.cache.entries()) {
+            if ((now - entry.timestamp) >= entry.ttl) {
+                this.cache.delete(address);
+            }
+        }
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        const now = Date.now();
+        return {
+            size: this.cache.size,
+            hitRate: 0, // Would need to track hits/misses
+            entries: Array.from(this.cache.entries()).map(([address, entry]) => ({
+                address,
+                age: now - entry.timestamp,
+                ttl: entry.ttl
+            }))
+        };
+    }
+}

package/dist/modules/accounts.d.ts

@@ -0,0 +1,60 @@
+import { ScriptMetadata } from "../metadata/index.js";
+export declare function fetchAccountAndDeserialize(accountAddress: string, connection: any, // Solana Connection object
+options?: {
+    debug?: boolean;
+    parseMetadata?: boolean;
+    validateEncoding?: boolean;
+}): Promise<{
+    success: boolean;
+    accountInfo?: {
+        address: string;
+        owner: string;
+        lamports: number;
+        dataLength: number;
+    };
+    scriptMetadata?: ScriptMetadata;
+    rawBytecode?: Uint8Array;
+    decodedData?: {
+        header: any;
+        bytecode: Uint8Array;
+        abi?: any;
+        functions?: Array<{
+            name: string;
+            index: number;
+            parameters: any[];
+        }>;
+    };
+    error?: string;
+    logs?: string[];
+}>;
+export declare function fetchMultipleAccountsAndDeserialize(accountAddresses: string[], connection: any, options?: {
+    debug?: boolean;
+    parseMetadata?: boolean;
+    validateEncoding?: boolean;
+    batchSize?: number;
+}): Promise<Map<string, {
+    success: boolean;
+    accountInfo?: any;
+    scriptMetadata?: ScriptMetadata;
+    rawBytecode?: Uint8Array;
+    decodedData?: any;
+    error?: string;
+    logs?: string[];
+}>>;
+export declare function deserializeParameters(instructionData: Uint8Array, expectedTypes?: string[], options?: {
+    debug?: boolean;
+}): Promise<{
+    success: boolean;
+    parameters?: Array<{
+        type: string;
+        value: any;
+    }>;
+    functionIndex?: number;
+    discriminator?: number;
+    error?: string;
+}>;
+export declare function validateBytecodeEncoding(bytecode: Uint8Array, debug?: boolean): Promise<{
+    valid: boolean;
+    error?: string;
+    info?: string;
+}>;