@5ive-tech/sdk 1.1.2

package/dist/testing/OnChainAccountManager.js

@@ -0,0 +1,260 @@
+/**
+ * On-Chain Account Manager for Five VM Account-System Testing
+ *
+ * Creates and manages real Solana accounts on-chain for comprehensive account-system testing.
+ * Handles account creation, funding, initialization, and cleanup.
+ */
+import { Keypair, PublicKey, SystemProgram, Transaction, sendAndConfirmTransaction, LAMPORTS_PER_SOL } from '@solana/web3.js';
+import { RentCalculator } from '../crypto/index.js';
+import { PDAUtils } from '../crypto/index.js';
+/**
+ * Manages creation and lifecycle of real Solana accounts for testing
+ */
+export class OnChainAccountManager {
+    constructor(connection, payer, options = {}) {
+        this.connection = connection;
+        this.payer = payer;
+        this.options = options;
+        this.createdAccounts = [];
+        this.signers = new Map();
+        this.options.maxRetries = this.options.maxRetries || 3;
+        this.options.retryDelay = this.options.retryDelay || 1000;
+    }
+    /**
+     * Create a signer account with generated keypair
+     * Transfers SOL from payer to fund the account
+     */
+    async createSignerAccount(lamports = LAMPORTS_PER_SOL // 1 SOL default
+    ) {
+        const keypair = Keypair.generate();
+        const publicKey = keypair.publicKey;
+        if (this.options.debug) {
+            console.log(`[OnChainAccountManager] Creating signer account: ${publicKey.toString()}`);
+        }
+        // Ensure payer has sufficient balance
+        await this.ensureSufficientBalance(lamports);
+        // Transfer SOL from payer to new account
+        const transaction = new Transaction().add(SystemProgram.transfer({
+            fromPubkey: this.payer.publicKey,
+            toPubkey: publicKey,
+            lamports: lamports,
+        }));
+        try {
+            const signature = await sendAndConfirmTransaction(this.connection, transaction, [this.payer], { commitment: 'confirmed' });
+            if (this.options.debug) {
+                console.log(`[OnChainAccountManager] Signer account funded: ${signature}`);
+            }
+            this.createdAccounts.push(publicKey);
+            this.signers.set(publicKey.toString(), keypair);
+            return { publicKey, keypair };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to create signer account: ${errorMessage}`);
+        }
+    }
+    /**
+     * Create a regular account with specified space and owner
+     * Uses SystemProgram.createAccount for account creation
+     */
+    async createAccount(space, owner, lamports) {
+        const keypair = Keypair.generate();
+        const publicKey = keypair.publicKey;
+        // Calculate rent-exempt lamports if not provided
+        const requiredLamports = lamports || RentCalculator.calculateRentExemption(space);
+        if (this.options.debug) {
+            console.log(`[OnChainAccountManager] Creating account: ${publicKey.toString()} ` +
+                `(space=${space}, lamports=${requiredLamports})`);
+        }
+        // Ensure payer has sufficient balance
+        await this.ensureSufficientBalance(requiredLamports);
+        // Create the account using SystemProgram
+        const transaction = new Transaction().add(SystemProgram.createAccount({
+            fromPubkey: this.payer.publicKey,
+            newAccountPubkey: publicKey,
+            lamports: requiredLamports,
+            space: space,
+            programId: owner,
+        }));
+        try {
+            const signature = await sendAndConfirmTransaction(this.connection, transaction, [this.payer, keypair], { commitment: 'confirmed' });
+            if (this.options.debug) {
+                console.log(`[OnChainAccountManager] Account created: ${signature}`);
+            }
+            this.createdAccounts.push(publicKey);
+            return publicKey;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to create account: ${errorMessage}`);
+        }
+    }
+    /**
+     * Create and initialize a state account with initial data
+     */
+    async createStateAccount(space, owner, initialData, lamports) {
+        const accountAddress = await this.createAccount(space, owner, lamports);
+        // Write initial data if provided
+        if (initialData && initialData.length > 0) {
+            await this.writeAccountData(accountAddress, initialData);
+        }
+        if (this.options.debug) {
+            console.log(`[OnChainAccountManager] State account initialized: ${accountAddress.toString()}`);
+        }
+        return accountAddress;
+    }
+    /**
+     * Create a PDA account at a specific seed path
+     */
+    async createPDAAccount(seeds, programId, space, owner, lamports) {
+        const pda = await PDAUtils.findProgramAddress(seeds, programId.toString());
+        const pdaAddress = new PublicKey(pda.address);
+        if (this.options.debug) {
+            console.log(`[OnChainAccountManager] Creating PDA: ${pdaAddress.toString()} ` +
+                `(bump=${pda.bump})`);
+        }
+        // Check if PDA already exists
+        const exists = await this.checkAccountExists(pdaAddress);
+        if (exists) {
+            if (this.options.debug) {
+                console.log(`[OnChainAccountManager] PDA already exists, skipping creation`);
+            }
+            return { publicKey: pdaAddress, bump: pda.bump };
+        }
+        // Create PDA account
+        const createdAddress = await this.createAccount(space, owner || programId, lamports);
+        return { publicKey: createdAddress, bump: pda.bump };
+    }
+    /**
+     * Write data to an account (requires account to be writable)
+     */
+    async writeAccountData(accountAddress, data) {
+        if (this.options.debug) {
+            console.log(`[OnChainAccountManager] Writing ${data.length} bytes to account: ${accountAddress.toString()}`);
+        }
+        // Note: Writing data directly to an account requires special instructions
+        // This is a simplified implementation. In practice, you would use the Five VM program
+        // or SystemProgram.allocate + loader to write data.
+        // Log that data would be written.
+        if (this.options.debug) {
+            console.log(`[OnChainAccountManager] Data would be written via Five VM program`);
+        }
+    }
+    /**
+     * Check if an account exists
+     */
+    async checkAccountExists(publicKey) {
+        try {
+            const accountInfo = await this.connection.getAccountInfo(publicKey);
+            return accountInfo !== null;
+        }
+        catch (error) {
+            if (this.options.debug) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                console.log(`[OnChainAccountManager] Error checking account: ${errorMessage}`);
+            }
+            return false;
+        }
+    }
+    /**
+     * Ensure payer has sufficient balance
+     */
+    async ensureSufficientBalance(required) {
+        const balance = await this.connection.getBalance(this.payer.publicKey);
+        // Add buffer for transaction fees (0.01 SOL)
+        const feeBuffer = 0.01 * LAMPORTS_PER_SOL;
+        const totalRequired = required + feeBuffer;
+        if (balance < totalRequired) {
+            throw new Error(`Insufficient balance: ${(balance / LAMPORTS_PER_SOL).toFixed(4)} SOL available, ` +
+                `${(totalRequired / LAMPORTS_PER_SOL).toFixed(4)} SOL required. ` +
+                `Please fund the payer account: ${this.payer.publicKey.toString()}`);
+        }
+    }
+    /**
+     * Create account with retry logic
+     */
+    async createAccountWithRetry(createFn, options = {}) {
+        const maxRetries = options.maxRetries || this.options.maxRetries || 3;
+        const retryDelay = options.retryDelay || this.options.retryDelay || 1000;
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            try {
+                return await createFn();
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                if (attempt === maxRetries) {
+                    throw new Error(`Failed to create account after ${maxRetries} attempts: ${errorMessage}`);
+                }
+                if (this.options.debug) {
+                    console.log(`[OnChainAccountManager] Account creation failed (attempt ${attempt}/${maxRetries}), ` +
+                        `retrying in ${retryDelay}ms...`);
+                }
+                await new Promise(resolve => setTimeout(resolve, retryDelay));
+            }
+        }
+        throw new Error('Unreachable');
+    }
+    /**
+     * Get a signer keypair if it was created by this manager
+     */
+    getSignerKeypair(publicKey) {
+        const key = typeof publicKey === 'string' ? publicKey : publicKey.toString();
+        return this.signers.get(key);
+    }
+    /**
+     * Get all created accounts
+     */
+    getCreatedAccounts() {
+        return [...this.createdAccounts];
+    }
+    /**
+     * Cleanup: Close all created accounts and transfer remaining SOL back to payer
+     * This helps with test isolation and prevents account accumulation on testnet
+     */
+    async cleanup() {
+        if (!this.options.cleanup) {
+            if (this.options.debug) {
+                console.log(`[OnChainAccountManager] Cleanup disabled, skipping`);
+            }
+            return;
+        }
+        if (this.options.debug) {
+            console.log(`[OnChainAccountManager] Cleaning up ${this.createdAccounts.length} accounts`);
+        }
+        // Close accounts and transfer lamports back to payer
+        for (const accountAddress of this.createdAccounts) {
+            try {
+                // Get account info to determine if it's an account we can close
+                const accountInfo = await this.connection.getAccountInfo(accountAddress);
+                if (accountInfo) {
+                    // Only try to close accounts owned by SystemProgram (data accounts)
+                    // Don't try to close program accounts or special accounts
+                    if (accountInfo.owner.equals(SystemProgram.programId)) {
+                        const transaction = new Transaction().add(SystemProgram.transfer({
+                            fromPubkey: accountAddress,
+                            toPubkey: this.payer.publicKey,
+                            lamports: accountInfo.lamports,
+                        }));
+                        const signer = this.getSignerKeypair(accountAddress);
+                        if (signer) {
+                            await sendAndConfirmTransaction(this.connection, transaction, [signer], { commitment: 'confirmed' });
+                            if (this.options.debug) {
+                                console.log(`[OnChainAccountManager] Closed account: ${accountAddress.toString()}`);
+                            }
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                if (this.options.debug) {
+                    console.log(`[OnChainAccountManager] Error closing account ${accountAddress.toString()}: ` +
+                        `${errorMessage}`);
+                }
+            }
+        }
+        this.createdAccounts = [];
+        this.signers.clear();
+    }
+}
+export default OnChainAccountManager;

package/dist/testing/StateSerializer.d.ts

@@ -0,0 +1,65 @@
+/**
+ * State Serializer for Five VM Account Data
+ *
+ * Serializes state account data based on Five account field definitions.
+ * Handles conversion of JavaScript types to Five VM bytecode format.
+ */
+export interface StateFieldDefinition {
+    name: string;
+    type: string;
+}
+export interface StateDefinition {
+    name: string;
+    fields: StateFieldDefinition[];
+}
+/**
+ * Serializes state account data to Five VM bytecode format
+ */
+export declare class StateSerializer {
+    /**
+     * Serialize complete state object based on definition
+     */
+    static serialize(stateDefinition: StateDefinition, data: Record<string, any>, options?: {
+        debug?: boolean;
+    }): Uint8Array;
+    /**
+     * Serialize a single field value based on its type
+     */
+    static serializeField(type: string, value: any, options?: {
+        debug?: boolean;
+    }): Uint8Array;
+    /**
+     * Serialize an integer value (u8, u16, u32, u64, i8, i16, i32, i64)
+     */
+    private static serializeInteger;
+    /**
+     * Serialize a public key (base58 to 32-byte array)
+     */
+    private static serializePubkey;
+    /**
+     * Serialize a UTF-8 string with length prefix
+     * Format: u32 length (little-endian) + UTF-8 bytes
+     */
+    private static serializeString;
+    /**
+     * Serialize an array of values
+     */
+    private static serializeArray;
+    /**
+     * Get default value for a type
+     */
+    private static getDefaultValue;
+    /**
+     * Convert byte array to hex string for debugging
+     */
+    private static toHexString;
+    /**
+     * Calculate total size of a state based on definition
+     */
+    static calculateSize(stateDefinition: StateDefinition): number;
+    /**
+     * Get size of a single field type in bytes
+     */
+    private static getFieldSize;
+}
+export default StateSerializer;

package/dist/testing/StateSerializer.js

@@ -0,0 +1,330 @@
+/**
+ * State Serializer for Five VM Account Data
+ *
+ * Serializes state account data based on Five account field definitions.
+ * Handles conversion of JavaScript types to Five VM bytecode format.
+ */
+import { Base58Utils } from '../crypto/index.js';
+/**
+ * Serializes state account data to Five VM bytecode format
+ */
+export class StateSerializer {
+    /**
+     * Serialize complete state object based on definition
+     */
+    static serialize(stateDefinition, data, options = {}) {
+        if (options.debug) {
+            console.log(`[StateSerializer] Serializing ${stateDefinition.name} with ${stateDefinition.fields.length} fields`);
+        }
+        // Collect all field buffers
+        let totalSize = 0;
+        const fieldBuffers = [];
+        for (const field of stateDefinition.fields) {
+            const value = data[field.name];
+            if (value === undefined) {
+                if (options.debug) {
+                    console.warn(`[StateSerializer] Field "${field.name}" not provided, using default value for type ${field.type}`);
+                }
+                // Use default value based on type
+                const defaultValue = this.getDefaultValue(field.type);
+                const buffer = this.serializeField(field.type, defaultValue, options);
+                fieldBuffers.push(buffer);
+                totalSize += buffer.length;
+            }
+            else {
+                const buffer = this.serializeField(field.type, value, options);
+                fieldBuffers.push(buffer);
+                totalSize += buffer.length;
+            }
+        }
+        // Concatenate all field buffers in order
+        const result = new Uint8Array(totalSize);
+        let offset = 0;
+        for (const buffer of fieldBuffers) {
+            result.set(buffer, offset);
+            offset += buffer.length;
+        }
+        if (options.debug) {
+            console.log(`[StateSerializer] Serialized to ${totalSize} bytes, hex: ${this.toHexString(result)}`);
+        }
+        return result;
+    }
+    /**
+     * Serialize a single field value based on its type
+     */
+    static serializeField(type, value, options = {}) {
+        // Normalize type name (remove whitespace, convert to lowercase)
+        const normalizedType = type.toLowerCase().trim();
+        if (options.debug) {
+            console.log(`[StateSerializer] Serializing field type="${normalizedType}" value="${value}"`);
+        }
+        // Handle integer types
+        if (normalizedType === 'u8' || normalizedType === 'u16' ||
+            normalizedType === 'u32' || normalizedType === 'u64' ||
+            normalizedType === 'i8' || normalizedType === 'i16' ||
+            normalizedType === 'i32' || normalizedType === 'i64') {
+            return this.serializeInteger(normalizedType, value);
+        }
+        // Handle boolean type
+        if (normalizedType === 'bool' || normalizedType === 'boolean') {
+            return new Uint8Array([value ? 1 : 0]);
+        }
+        // Handle public key type
+        if (normalizedType === 'pubkey' || normalizedType === 'publickey' ||
+            normalizedType === 'publickey' || normalizedType === 'account') {
+            return this.serializePubkey(value);
+        }
+        // Handle string type (UTF-8 encoded with length prefix)
+        if (normalizedType === 'string') {
+            return this.serializeString(value);
+        }
+        // Handle array types
+        if (normalizedType.endsWith('[]')) {
+            const elementType = normalizedType.slice(0, -2);
+            return this.serializeArray(elementType, value, options);
+        }
+        throw new Error(`Unsupported type: ${type}`);
+    }
+    /**
+     * Serialize an integer value (u8, u16, u32, u64, i8, i16, i32, i64)
+     */
+    static serializeInteger(type, value) {
+        let numValue;
+        if (typeof value === 'string') {
+            // Try parsing as BigInt first for 64-bit values
+            try {
+                numValue = BigInt(value);
+            }
+            catch {
+                numValue = parseInt(value, 10);
+            }
+        }
+        else {
+            numValue = value;
+        }
+        // Determine size based on type
+        let size;
+        let isSigned;
+        switch (type) {
+            case 'u8':
+                size = 1;
+                isSigned = false;
+                break;
+            case 'u16':
+                size = 2;
+                isSigned = false;
+                break;
+            case 'u32':
+                size = 4;
+                isSigned = false;
+                break;
+            case 'u64':
+                size = 8;
+                isSigned = false;
+                break;
+            case 'i8':
+                size = 1;
+                isSigned = true;
+                break;
+            case 'i16':
+                size = 2;
+                isSigned = true;
+                break;
+            case 'i32':
+                size = 4;
+                isSigned = true;
+                break;
+            case 'i64':
+                size = 8;
+                isSigned = true;
+                break;
+            default:
+                throw new Error(`Unsupported integer type: ${type}`);
+        }
+        const buffer = new Uint8Array(size);
+        const view = new DataView(buffer.buffer);
+        // Write value in little-endian format
+        if (size === 8 && typeof numValue === 'bigint') {
+            if (isSigned) {
+                view.setBigInt64(0, numValue, true);
+            }
+            else {
+                view.setBigUint64(0, numValue, true);
+            }
+        }
+        else {
+            const numericValue = typeof numValue === 'bigint' ? Number(numValue) : numValue;
+            switch (type) {
+                case 'u8':
+                    view.setUint8(0, numericValue);
+                    break;
+                case 'u16':
+                    view.setUint16(0, numericValue, true);
+                    break;
+                case 'u32':
+                    view.setUint32(0, numericValue, true);
+                    break;
+                case 'u64':
+                    view.setBigUint64(0, BigInt(numericValue), true);
+                    break;
+                case 'i8':
+                    view.setInt8(0, numericValue);
+                    break;
+                case 'i16':
+                    view.setInt16(0, numericValue, true);
+                    break;
+                case 'i32':
+                    view.setInt32(0, numericValue, true);
+                    break;
+                case 'i64':
+                    view.setBigInt64(0, BigInt(numericValue), true);
+                    break;
+            }
+        }
+        return buffer;
+    }
+    /**
+     * Serialize a public key (base58 to 32-byte array)
+     */
+    static serializePubkey(value) {
+        if (value instanceof Uint8Array) {
+            if (value.length !== 32) {
+                throw new Error(`Invalid pubkey: expected 32 bytes, got ${value.length}`);
+            }
+            return value;
+        }
+        try {
+            // Assume base58-encoded public key string
+            const decoded = Base58Utils.decode(value);
+            if (decoded.length !== 32) {
+                throw new Error(`Invalid pubkey: expected 32 bytes after decoding, got ${decoded.length}`);
+            }
+            return decoded;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to decode pubkey: ${errorMessage}`);
+        }
+    }
+    /**
+     * Serialize a UTF-8 string with length prefix
+     * Format: u32 length (little-endian) + UTF-8 bytes
+     */
+    static serializeString(value) {
+        const encoder = new TextEncoder();
+        const stringBytes = encoder.encode(value);
+        const length = stringBytes.length;
+        // Create buffer: 4 bytes for length + string bytes
+        const buffer = new Uint8Array(4 + length);
+        const view = new DataView(buffer.buffer);
+        // Write length as u32 in little-endian
+        view.setUint32(0, length, true);
+        // Write string bytes
+        buffer.set(stringBytes, 4);
+        return buffer;
+    }
+    /**
+     * Serialize an array of values
+     */
+    static serializeArray(elementType, values, options = {}) {
+        const elementBuffers = [];
+        let totalSize = 4; // 4 bytes for array length
+        // First, serialize all elements
+        for (const value of values) {
+            const buffer = this.serializeField(elementType, value, options);
+            elementBuffers.push(buffer);
+            totalSize += buffer.length;
+        }
+        // Create result buffer with length prefix
+        const result = new Uint8Array(totalSize);
+        const view = new DataView(result.buffer);
+        // Write array length as u32 in little-endian
+        view.setUint32(0, values.length, true);
+        // Write all elements
+        let offset = 4;
+        for (const buffer of elementBuffers) {
+            result.set(buffer, offset);
+            offset += buffer.length;
+        }
+        return result;
+    }
+    /**
+     * Get default value for a type
+     */
+    static getDefaultValue(type) {
+        const normalizedType = type.toLowerCase().trim();
+        if (normalizedType === 'bool' || normalizedType === 'boolean') {
+            return false;
+        }
+        if (normalizedType === 'u8' || normalizedType === 'u16' ||
+            normalizedType === 'u32' || normalizedType === 'u64' ||
+            normalizedType === 'i8' || normalizedType === 'i16' ||
+            normalizedType === 'i32' || normalizedType === 'i64') {
+            return 0;
+        }
+        if (normalizedType === 'pubkey' || normalizedType === 'publickey' ||
+            normalizedType === 'account') {
+            return '11111111111111111111111111111111'; // Default system program
+        }
+        if (normalizedType === 'string') {
+            return '';
+        }
+        if (normalizedType.endsWith('[]')) {
+            return [];
+        }
+        return null;
+    }
+    /**
+     * Convert byte array to hex string for debugging
+     */
+    static toHexString(bytes) {
+        return Array.from(bytes)
+            .map(byte => byte.toString(16).padStart(2, '0'))
+            .join('');
+    }
+    /**
+     * Calculate total size of a state based on definition
+     */
+    static calculateSize(stateDefinition) {
+        let totalSize = 0;
+        for (const field of stateDefinition.fields) {
+            totalSize += this.getFieldSize(field.type);
+        }
+        return totalSize;
+    }
+    /**
+     * Get size of a single field type in bytes
+     */
+    static getFieldSize(type) {
+        const normalizedType = type.toLowerCase().trim();
+        switch (normalizedType) {
+            case 'u8':
+            case 'i8':
+            case 'bool':
+                return 1;
+            case 'u16':
+            case 'i16':
+                return 2;
+            case 'u32':
+            case 'i32':
+                return 4;
+            case 'u64':
+            case 'i64':
+                return 8;
+            case 'pubkey':
+            case 'publickey':
+            case 'account':
+                return 32;
+            case 'string':
+                // Variable-length, return minimum (4 bytes for length)
+                return 4;
+            default:
+                if (normalizedType.endsWith('[]')) {
+                    // Variable-length array
+                    return 4; // Minimum for length prefix
+                }
+                throw new Error(`Unsupported type: ${type}`);
+        }
+    }
+}
+export default StateSerializer;