@5ive-tech/sdk 1.1.2

package/dist/testing/AccountMetaGenerator.js

@@ -0,0 +1,261 @@
+/**
+ * Account Meta Generator for Five VM Testing
+ *
+ * Generates AccountMeta structures for testing account system scripts
+ * based on ABI requirements and constraint types (@signer, @mut, @init)
+ */
+import { SolanaPublicKeyUtils, Base58Utils } from '../crypto/index.js';
+/**
+ * Account Meta Generator for Five VM test scripts
+ */
+export class AccountMetaGenerator {
+    /**
+     * Generate AccountMeta array from ABI function definition
+     */
+    static async generateAccountsForFunction(abi, functionName, options = {}) {
+        const func = abi.functions?.[functionName];
+        if (!func) {
+            throw new Error(`Function '${functionName}' not found in ABI`);
+        }
+        const accountSpecs = func.accounts || [];
+        const accounts = [];
+        const stateData = new Map();
+        if (options.debug) {
+            console.log(`[AccountMetaGenerator] Generating accounts for ${functionName}:`);
+            console.log(`  - Found ${accountSpecs.length} account requirements`);
+        }
+        for (const accountSpec of accountSpecs) {
+            const accountMeta = await this.generateAccountMeta(accountSpec, options);
+            accounts.push(accountMeta);
+            // Generate state data for state accounts
+            if (options.generateStateData && this.isStateAccount(accountSpec)) {
+                const state = this.generateStateData(accountSpec);
+                stateData.set(accountSpec.name, state);
+            }
+            if (options.debug) {
+                console.log(`  - ${accountSpec.name}: ${accountMeta.pubkey} (signer: ${accountMeta.isSigner}, writable: ${accountMeta.isWritable})`);
+            }
+        }
+        return {
+            script: functionName,
+            functionIndex: func.index,
+            accounts,
+            stateData: stateData.size > 0 ? stateData : undefined
+        };
+    }
+    /**
+     * Generate single AccountMeta from account specification
+     */
+    static async generateAccountMeta(accountSpec, options) {
+        // Check cache for reusable accounts
+        const cacheKey = `${accountSpec.name}_${accountSpec.signer}_${accountSpec.writable}`;
+        if (options.reuseAccounts && this.accountCache.has(cacheKey)) {
+            const cached = this.accountCache.get(cacheKey);
+            if (options.debug) {
+                console.log(`    [Cache Hit] Reusing account for ${accountSpec.name}: ${cached.pubkey}`);
+            }
+            return cached;
+        }
+        let accountMeta;
+        if (accountSpec.signer) {
+            // Generate new keypair for signer accounts
+            accountMeta = await this.generateSignerAccount(accountSpec, options);
+        }
+        else {
+            // Generate regular account for non-signer accounts
+            accountMeta = await this.generateRegularAccount(accountSpec, options);
+        }
+        // Cache for reuse
+        if (options.reuseAccounts) {
+            this.accountCache.set(cacheKey, accountMeta);
+        }
+        return accountMeta;
+    }
+    /**
+     * Generate signer account with keypair
+     */
+    static async generateSignerAccount(accountSpec, options) {
+        // Generate new keypair for signer
+        const crypto = await import('crypto');
+        const keypair = crypto.generateKeyPairSync('ed25519', {
+            publicKeyEncoding: { type: 'spki', format: 'der' },
+            privateKeyEncoding: { type: 'pkcs8', format: 'der' }
+        });
+        // Extract raw public key (32 bytes) from SPKI DER encoding
+        // SPKI format for ed25519: 12-byte header + 32-byte key
+        const publicKeyDer = keypair.publicKey;
+        const publicKeyRaw = publicKeyDer.slice(-32); // Last 32 bytes are the raw key
+        const publicKey = Base58Utils.encode(new Uint8Array(publicKeyRaw));
+        // Extract private key (64 bytes from PKCS8: 32-byte seed + 32-byte public key)
+        const privateKeyDer = keypair.privateKey;
+        const secretKey = new Uint8Array(privateKeyDer.slice(-64, -32)); // Extract the seed
+        if (options.debug) {
+            console.log(`    [Signer] Generated keypair for ${accountSpec.name}: ${publicKey}`);
+        }
+        return {
+            pubkey: publicKey,
+            isSigner: true,
+            isWritable: accountSpec.writable,
+            keypair: {
+                publicKey,
+                secretKey
+            }
+        };
+    }
+    /**
+     * Generate regular (non-signer) account
+     */
+    static async generateRegularAccount(accountSpec, options) {
+        // Generate random address for non-signer accounts
+        const randomAddress = SolanaPublicKeyUtils.random();
+        if (options.debug) {
+            console.log(`    [Regular] Generated address for ${accountSpec.name}: ${randomAddress}`);
+        }
+        return {
+            pubkey: randomAddress,
+            isSigner: false,
+            isWritable: accountSpec.writable
+        };
+    }
+    /**
+     * Check if account is a state account that needs data
+     */
+    static isStateAccount(accountSpec) {
+        // Common patterns for state accounts
+        const statePatterns = [
+            'state',
+            'account',
+            'data',
+            'storage'
+        ];
+        const name = accountSpec.name.toLowerCase();
+        return statePatterns.some(pattern => name.includes(pattern));
+    }
+    /**
+     * Generate mock state data for state accounts
+     */
+    static generateStateData(accountSpec) {
+        // Generate appropriate state data based on account name
+        const name = accountSpec.name.toLowerCase();
+        if (name.includes('state')) {
+            return {
+                count: 42,
+                total_operations: 0,
+                admin: SolanaPublicKeyUtils.random(),
+                created_accounts: 0,
+                modification_count: 0
+            };
+        }
+        if (name.includes('init')) {
+            return {
+                created_accounts: 0,
+                admin: SolanaPublicKeyUtils.random()
+            };
+        }
+        if (name.includes('mut')) {
+            return {
+                modification_count: 0
+            };
+        }
+        // Default state data
+        return {
+            value: 42,
+            owner: SolanaPublicKeyUtils.random()
+        };
+    }
+    /**
+     * Format accounts for Five CLI execution
+     */
+    static formatAccountsForCLI(context) {
+        const accounts = context.accounts.map(acc => acc.pubkey).join(',');
+        const keypairs = context.accounts
+            .filter(acc => acc.keypair)
+            .map(acc => ({
+            name: acc.pubkey,
+            keypair: acc.keypair
+        }));
+        return {
+            accountsParam: accounts,
+            keypairsNeeded: keypairs
+        };
+    }
+    /**
+     * Generate accounts from .five file
+     */
+    static async generateFromFiveFile(fiveFilePath, functionName = 'test', options = {}) {
+        const fs = await import('fs');
+        const path = await import('path');
+        if (!fs.existsSync(fiveFilePath)) {
+            throw new Error(`Five file not found: ${fiveFilePath}`);
+        }
+        const fiveData = JSON.parse(fs.readFileSync(fiveFilePath, 'utf8'));
+        const abi = fiveData.abi;
+        if (!abi || !abi.functions) {
+            throw new Error(`Invalid Five file: missing ABI or functions in ${fiveFilePath}`);
+        }
+        return this.generateAccountsForFunction(abi, functionName, options);
+    }
+    /**
+     * Clear account cache (useful for testing)
+     */
+    static clearCache() {
+        this.accountCache.clear();
+        this.stateDataCache.clear();
+    }
+    /**
+     * Get account cache statistics
+     */
+    static getCacheStats() {
+        return {
+            accountsCached: this.accountCache.size,
+            stateDataCached: this.stateDataCache.size
+        };
+    }
+}
+AccountMetaGenerator.accountCache = new Map();
+AccountMetaGenerator.stateDataCache = new Map();
+/**
+ * Utility functions for account management
+ */
+export class AccountTestUtils {
+    /**
+     * Create test accounts for common constraint patterns
+     */
+    static async createStandardTestAccounts() {
+        const generator = AccountMetaGenerator;
+        const [payer, authority, state, readonly] = await Promise.all([
+            generator['generateSignerAccount']({ name: 'payer', signer: true, writable: true }, {}),
+            generator['generateSignerAccount']({ name: 'authority', signer: true, writable: false }, {}),
+            generator['generateRegularAccount']({ name: 'state', signer: false, writable: true }, {}),
+            generator['generateRegularAccount']({ name: 'readonly', signer: false, writable: false }, {})
+        ]);
+        return { payer, authority, state, readonly };
+    }
+    /**
+     * Validate account constraints match requirements
+     */
+    static validateAccountConstraints(accounts, requirements) {
+        const errors = [];
+        if (accounts.length !== requirements.length) {
+            errors.push(`Account count mismatch: expected ${requirements.length}, got ${accounts.length}`);
+            return { valid: false, errors };
+        }
+        for (let i = 0; i < requirements.length; i++) {
+            const account = accounts[i];
+            const requirement = requirements[i];
+            if (account.isSigner !== requirement.signer) {
+                errors.push(`Account ${i} (${requirement.name}): signer mismatch - expected ${requirement.signer}, got ${account.isSigner}`);
+            }
+            if (account.isWritable !== requirement.writable) {
+                errors.push(`Account ${i} (${requirement.name}): writable mismatch - expected ${requirement.writable}, got ${account.isWritable}`);
+            }
+            if (requirement.signer && !account.keypair) {
+                errors.push(`Account ${i} (${requirement.name}): signer account missing keypair`);
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            errors
+        };
+    }
+}

package/dist/testing/AccountTestFixture.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Account Test Fixture Framework for Five VM
+ *
+ * Provides a reusable, composable pattern for testing Five account-system scripts.
+ * Builders use this to:
+ * 1. Define test accounts with specific constraints
+ * 2. Initialize account state before test execution
+ * 3. Validate constraints locally before on-chain testing
+ * 4. Reuse common account setups across multiple tests
+ *
+ * Example:
+ * ```
+ * const fixture = new AccountTestFixture()
+ *   .addSignerAccount('payer')
+ *   .addStateAccount('counter', { value: 0 })
+ *   .addMutableAccount('target')
+ *   .build();
+ * ```
+ */
+import { GeneratedAccountMeta } from './AccountMetaGenerator.js';
+import { Connection, Keypair, PublicKey } from '@solana/web3.js';
+/**
+ * Account state initialization template
+ * Builders provide this to set initial account data
+ */
+export interface AccountStateTemplate {
+    [fieldName: string]: any;
+}
+/**
+ * Account specification for fixture building
+ * Describes what kind of account is needed
+ */
+export interface FixtureAccountSpec {
+    name: string;
+    type: 'signer' | 'mutable' | 'readonly' | 'state' | 'init';
+    state?: AccountStateTemplate;
+    description?: string;
+}
+/**
+ * Build options for fixture compilation
+ */
+export interface BuildOptions {
+    debug?: boolean;
+    mode?: 'local' | 'onchain';
+    connection?: Connection;
+    payer?: Keypair;
+    cleanup?: boolean;
+    fiveVMProgramId?: PublicKey;
+}
+/**
+ * Compiled fixture ready for test execution
+ * Contains all accounts and their metadata
+ */
+export interface CompiledFixture {
+    accounts: GeneratedAccountMeta[];
+    accountsByName: Map<string, GeneratedAccountMeta>;
+    stateData: Map<string, AccountStateTemplate>;
+    specs: FixtureAccountSpec[];
+    metadata: {
+        signerCount: number;
+        mutableCount: number;
+        readonlyCount: number;
+        stateCount: number;
+    };
+    cleanup?: () => Promise<void>;
+}
+/**
+ * Validation result from constraint checking
+ */
+export interface ConstraintValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Test execution context with bound accounts
+ */
+export interface AccountExecutionContext {
+    fixture: CompiledFixture;
+    functionName: string;
+    parameters: any[];
+    accountAddresses: string[];
+    keypairs: Map<string, Uint8Array>;
+}
+/**
+ * Account Test Fixture Builder
+ * Fluent API for constructing test account setups
+ */
+export declare class AccountTestFixture {
+    private specs;
+    private stateTemplates;
+    /**
+     * Add a signer account (@signer constraint)
+     * Used for transaction signers, authority checks
+     */
+    addSignerAccount(name: string, options?: {
+        description?: string;
+    }): this;
+    /**
+     * Add a mutable account (@mut constraint)
+     * Can be modified by the script
+     */
+    addMutableAccount(name: string, state?: AccountStateTemplate, options?: {
+        description?: string;
+    }): this;
+    /**
+     * Add a read-only account
+     * Cannot be modified by the script
+     */
+    addReadOnlyAccount(name: string, state?: AccountStateTemplate, options?: {
+        description?: string;
+    }): this;
+    /**
+     * Add a state account (@mut state: StateType)
+     * Typically for program state storage
+     */
+    addStateAccount(name: string, state?: AccountStateTemplate, options?: {
+        description?: string;
+    }): this;
+    /**
+     * Add an initialization account (@init constraint)
+     * For account creation patterns
+     */
+    addInitAccount(name: string, options?: {
+        description?: string;
+    }): this;
+    /**
+     * Add multiple accounts in one call
+     * Useful for standard patterns
+     */
+    addPattern(pattern: 'authorization' | 'state-mutation' | 'batch-operation'): this;
+    /**
+     * Compile fixture into accounts ready for execution
+     * Supports both local (synthetic) and on-chain (real) account modes
+     */
+    build(options?: BuildOptions): Promise<CompiledFixture>;
+    /**
+     * Build fixture with local synthetic accounts (existing behavior)
+     */
+    private buildLocal;
+    /**
+     * Build fixture with real on-chain accounts
+     */
+    private buildOnChain;
+    /**
+     * Create individual account based on spec
+     */
+    private createAccount;
+    /**
+     * Validate fixture against ABI constraints
+     */
+    validateAgainstABI(abiFunction: any): ConstraintValidationResult;
+    /**
+     * Get summary of fixture specs for debugging
+     */
+    getSummary(): string;
+}
+/**
+ * Predefined fixture templates for common patterns
+ * Builders can extend these for their specific needs
+ */
+export declare class FixtureTemplates {
+    /**
+     * Simple state mutation pattern
+     * For scripts that increment counters, track modifications, etc.
+     */
+    static stateCounter(): AccountTestFixture;
+    /**
+     * Authorization pattern
+     * For scripts that check permissions via @signer
+     */
+    static authorization(): AccountTestFixture;
+    /**
+     * Account creation pattern
+     * For scripts using @init constraint
+     */
+    static accountCreation(): AccountTestFixture;
+    /**
+     * Multi-account transaction pattern
+     * For scripts that operate on multiple mutable accounts
+     */
+    static batchOperation(): AccountTestFixture;
+    /**
+     * Complex authorization pattern
+     * For multi-signature or advanced permission schemes
+     */
+    static multiSigPattern(): AccountTestFixture;
+    /**
+     * PDA pattern
+     * For scripts that use Program Derived Addresses
+     */
+    static pdaPattern(): AccountTestFixture;
+}
+/**
+ * Test execution builder
+ * Combines fixture with test parameters for execution
+ */
+export declare class AccountTestExecutor {
+    /**
+     * Bind fixture accounts to a test execution
+     */
+    static bindFixture(fixture: CompiledFixture, functionName: string, parameters?: any[]): AccountExecutionContext;
+    /**
+     * Validate execution context before running
+     */
+    static validateContext(context: AccountExecutionContext): ConstraintValidationResult;
+    /**
+     * Get human-readable execution summary
+     */
+    static getSummary(context: AccountExecutionContext): string;
+}