@5ive-tech/sdk 1.1.2

package/dist/modules/state-diff.js

@@ -0,0 +1,342 @@
+import { executeOnSolana } from "./execute.js";
+import { fetchMultipleAccountsAndDeserialize } from "./accounts.js";
+import { PDAUtils } from "../crypto/index.js";
+import { ProgramIdResolver } from "../config/ProgramIdResolver.js";
+export async function executeWithStateDiff(scriptAccount, connection, signerKeypair, functionName, parameters = [], options = {}) {
+    const logs = [];
+    try {
+        if (options.debug) {
+            console.log(`[FiveSDK] Starting execution with state diff tracking`);
+            console.log(`  Script Account: ${scriptAccount}`);
+            console.log(`  Function: ${functionName}`);
+            console.log(`  Parameters: ${JSON.stringify(parameters)}`);
+            console.log(`  Track Global Fields: ${options.trackGlobalFields}`);
+        }
+        const accountsToTrack = [scriptAccount];
+        if (options.includeVMState) {
+            const programId = ProgramIdResolver.resolve(options.fiveVMProgramId);
+            const vmStatePDAResult = await PDAUtils.deriveVMStatePDA(programId);
+            const vmStatePDA = vmStatePDAResult.address;
+            accountsToTrack.push(vmStatePDA);
+            if (options.debug) {
+                console.log(`  Added VM State PDA to tracking: ${vmStatePDA}`);
+            }
+        }
+        if (options.additionalAccounts) {
+            accountsToTrack.push(...options.additionalAccounts);
+            if (options.debug) {
+                console.log(`  Added ${options.additionalAccounts.length} additional accounts to tracking`);
+            }
+        }
+        logs.push(`Tracking ${accountsToTrack.length} accounts for state changes`);
+        if (options.debug) {
+            console.log(`[FiveSDK] Fetching BEFORE state for ${accountsToTrack.length} accounts...`);
+        }
+        const beforeState = await fetchMultipleAccountsAndDeserialize(accountsToTrack, connection, {
+            debug: false,
+            parseMetadata: true,
+            validateEncoding: false,
+        });
+        let successfulBeforeFetches = 0;
+        for (const [address, result] of beforeState.entries()) {
+            if (result.success) {
+                successfulBeforeFetches++;
+            }
+            else if (options.debug) {
+                console.warn(`[FiveSDK] Warning: Failed to fetch BEFORE state for ${address}: ${result.error}`);
+            }
+        }
+        logs.push(`BEFORE state: ${successfulBeforeFetches}/${accountsToTrack.length} accounts fetched`);
+        let beforeGlobalFields = {};
+        if (options.trackGlobalFields) {
+            const scriptBefore = beforeState.get(scriptAccount);
+            if (scriptBefore?.success && scriptBefore.scriptMetadata) {
+                beforeGlobalFields = extractGlobalFields(scriptBefore.scriptMetadata, "before");
+                if (options.debug) {
+                    console.log(`[FiveSDK] Extracted ${Object.keys(beforeGlobalFields).length} global fields from BEFORE state`);
+                }
+            }
+        }
+        if (options.debug) {
+            console.log(`[FiveSDK] Executing script...`);
+        }
+        const executionResult = await executeOnSolana(scriptAccount, connection, signerKeypair, functionName, parameters, options.additionalAccounts || [], {
+            debug: options.debug,
+            network: options.network,
+            computeUnitLimit: options.computeUnitLimit,
+        });
+        if (!executionResult.success) {
+            logs.push(`Execution failed: ${executionResult.error}`);
+            return {
+                success: false,
+                error: `Script execution failed: ${executionResult.error}`,
+                logs,
+            };
+        }
+        logs.push(`Execution successful: ${executionResult.transactionId}`);
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+        if (options.debug) {
+            console.log(`[FiveSDK] Fetching AFTER state...`);
+        }
+        const afterState = await fetchMultipleAccountsAndDeserialize(accountsToTrack, connection, {
+            debug: false,
+            parseMetadata: true,
+            validateEncoding: false,
+        });
+        let successfulAfterFetches = 0;
+        for (const [address, result] of afterState.entries()) {
+            if (result.success) {
+                successfulAfterFetches++;
+            }
+            else if (options.debug) {
+                console.warn(`[FiveSDK] Warning: Failed to fetch AFTER state for ${address}: ${result.error}`);
+            }
+        }
+        logs.push(`AFTER state: ${successfulAfterFetches}/${accountsToTrack.length} accounts fetched`);
+        let afterGlobalFields = {};
+        if (options.trackGlobalFields) {
+            const scriptAfter = afterState.get(scriptAccount);
+            if (scriptAfter?.success && scriptAfter.scriptMetadata) {
+                afterGlobalFields = extractGlobalFields(scriptAfter.scriptMetadata, "after");
+                if (options.debug) {
+                    console.log(`[FiveSDK] Extracted ${Object.keys(afterGlobalFields).length} global fields from AFTER state`);
+                }
+            }
+        }
+        if (options.debug) {
+            console.log(`[FiveSDK] Computing state differences...`);
+        }
+        const changes = computeStateDifferences(beforeState, afterState, options.debug);
+        let globalFieldChanges = [];
+        if (options.trackGlobalFields) {
+            globalFieldChanges = computeGlobalFieldChanges(beforeGlobalFields, afterGlobalFields);
+            if (options.debug) {
+                console.log(`[FiveSDK] Found ${globalFieldChanges.length} global field changes`);
+            }
+        }
+        logs.push(`State analysis: ${changes.length} account changes, ${globalFieldChanges.length} global field changes`);
+        return {
+            success: true,
+            execution: {
+                transactionId: executionResult.transactionId,
+                result: executionResult.result,
+                computeUnitsUsed: executionResult.computeUnitsUsed,
+                logs: executionResult.logs,
+            },
+            stateDiff: {
+                beforeState,
+                afterState,
+                changes,
+                globalFieldChanges,
+            },
+            logs,
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : "Unknown state tracking error";
+        if (options.debug) {
+            console.error(`[FiveSDK] State diff execution failed: ${errorMessage}`);
+        }
+        return {
+            success: false,
+            error: errorMessage,
+            logs,
+        };
+    }
+}
+function computeStateDifferences(beforeState, afterState, debug = false) {
+    const changes = [];
+    const allAccounts = new Set([...beforeState.keys(), ...afterState.keys()]);
+    for (const account of allAccounts) {
+        const before = beforeState.get(account);
+        const after = afterState.get(account);
+        if (debug) {
+            console.log(`[FiveSDK] Analyzing account ${account.substring(0, 8)}...`);
+        }
+        if (!before?.success && after?.success) {
+            changes.push({
+                account,
+                oldValue: null,
+                newValue: {
+                    lamports: after.accountInfo?.lamports,
+                    dataLength: after.accountInfo?.dataLength,
+                    owner: after.accountInfo?.owner,
+                },
+                changeType: "created",
+            });
+            continue;
+        }
+        if (before?.success && !after?.success) {
+            changes.push({
+                account,
+                oldValue: {
+                    lamports: before.accountInfo?.lamports,
+                    dataLength: before.accountInfo?.dataLength,
+                    owner: before.accountInfo?.owner,
+                },
+                newValue: null,
+                changeType: "deleted",
+            });
+            continue;
+        }
+        if (before?.success && after?.success) {
+            if (before.accountInfo?.lamports !== after.accountInfo?.lamports) {
+                changes.push({
+                    account,
+                    fieldName: "lamports",
+                    oldValue: before.accountInfo?.lamports,
+                    newValue: after.accountInfo?.lamports,
+                    changeType: "modified",
+                });
+            }
+            if (before.accountInfo?.dataLength !== after.accountInfo?.dataLength) {
+                changes.push({
+                    account,
+                    fieldName: "dataLength",
+                    oldValue: before.accountInfo?.dataLength,
+                    newValue: after.accountInfo?.dataLength,
+                    changeType: "modified",
+                });
+            }
+            if (before.rawBytecode && after.rawBytecode) {
+                if (!bytecodeEqual(before.rawBytecode, after.rawBytecode)) {
+                    changes.push({
+                        account,
+                        fieldName: "bytecode",
+                        oldValue: `${before.rawBytecode.length} bytes (hash: ${hashBytecode(before.rawBytecode)})`,
+                        newValue: `${after.rawBytecode.length} bytes (hash: ${hashBytecode(after.rawBytecode)})`,
+                        changeType: "modified",
+                    });
+                }
+            }
+            if (before.scriptMetadata && after.scriptMetadata) {
+                compareScriptMetadata(before.scriptMetadata, after.scriptMetadata, account, changes);
+            }
+        }
+    }
+    if (debug) {
+        console.log(`[FiveSDK] Found ${changes.length} total state changes`);
+    }
+    return changes;
+}
+function extractGlobalFields(scriptMetadata, phase) {
+    const globalFields = {};
+    try {
+        if (scriptMetadata.bytecode && scriptMetadata.bytecode.length > 6) {
+            const stateSection = extractStateSection(scriptMetadata.bytecode);
+            if (stateSection) {
+                Object.assign(globalFields, stateSection);
+            }
+        }
+    }
+    catch (error) {
+        console.warn(`[FiveSDK] Failed to extract global fields (${phase}):`, error);
+    }
+    return globalFields;
+}
+function computeGlobalFieldChanges(beforeFields, afterFields) {
+    const changes = [];
+    const allFields = new Set([
+        ...Object.keys(beforeFields),
+        ...Object.keys(afterFields),
+    ]);
+    for (const fieldName of allFields) {
+        const oldValue = beforeFields[fieldName];
+        const newValue = afterFields[fieldName];
+        if (!deepEqual(oldValue, newValue)) {
+            changes.push({
+                fieldName,
+                oldValue,
+                newValue,
+            });
+        }
+    }
+    return changes;
+}
+function compareScriptMetadata(beforeMetadata, afterMetadata, account, changes) {
+    if (beforeMetadata.abi.functions.length !== afterMetadata.abi.functions.length) {
+        changes.push({
+            account,
+            fieldName: "function_count",
+            oldValue: beforeMetadata.abi.functions.length,
+            newValue: afterMetadata.abi.functions.length,
+            changeType: "modified",
+        });
+    }
+    if (beforeMetadata.abi.name !== afterMetadata.abi.name) {
+        changes.push({
+            account,
+            fieldName: "script_name",
+            oldValue: beforeMetadata.abi.name,
+            newValue: afterMetadata.abi.name,
+            changeType: "modified",
+        });
+    }
+    if (beforeMetadata.authority !== afterMetadata.authority) {
+        changes.push({
+            account,
+            fieldName: "authority",
+            oldValue: beforeMetadata.authority,
+            newValue: afterMetadata.authority,
+            changeType: "modified",
+        });
+    }
+}
+function extractStateSection(bytecode) {
+    try {
+        if (bytecode.length < 6)
+            return null;
+        const stateMarker = new Uint8Array([0xff, 0xfe]);
+        for (let i = 6; i < bytecode.length - 1; i++) {
+            if (bytecode[i] === stateMarker[0] &&
+                bytecode[i + 1] === stateMarker[1]) {
+                const stateData = {};
+                return stateData;
+            }
+        }
+    }
+    catch (error) {
+        console.warn("[FiveSDK] State section extraction failed:", error);
+    }
+    return null;
+}
+function bytecodeEqual(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;
+}
+function hashBytecode(bytecode) {
+    let hash = 0;
+    for (let i = 0; i < bytecode.length; i++) {
+        hash = ((hash << 5) - hash + bytecode[i]) & 0xffffffff;
+    }
+    return hash.toString(16);
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a == null || b == null)
+        return false;
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a === "object") {
+        if (Array.isArray(a) !== Array.isArray(b))
+            return false;
+        const keysA = Object.keys(a);
+        const keysB = Object.keys(b);
+        if (keysA.length !== keysB.length)
+            return false;
+        for (const key of keysA) {
+            if (!keysB.includes(key))
+                return false;
+            if (!deepEqual(a[key], b[key]))
+                return false;
+        }
+        return true;
+    }
+    return false;
+}

package/dist/modules/vm-state.d.ts

@@ -0,0 +1,7 @@
+export declare function getVMState(connection: any, fiveVMProgramId?: string): Promise<{
+    authority: string;
+    scriptCount: number;
+    deployFeeBps: number;
+    executeFeeBps: number;
+    isInitialized: boolean;
+}>;

package/dist/modules/vm-state.js

@@ -0,0 +1,44 @@
+import { PDAUtils, Base58Utils } from "../crypto/index.js";
+import { ProgramIdResolver } from "../config/ProgramIdResolver.js";
+export async function getVMState(connection, fiveVMProgramId) {
+    const programId = ProgramIdResolver.resolve(fiveVMProgramId);
+    const vmStatePDA = await PDAUtils.deriveVMStatePDA(programId);
+    let accountData;
+    try {
+        if (typeof connection.getAccountInfo === 'function') {
+            let pubkey = vmStatePDA.address;
+            try {
+                const { PublicKey } = await import("@solana/web3.js");
+                pubkey = new PublicKey(vmStatePDA.address);
+            }
+            catch { }
+            const info = await connection.getAccountInfo(pubkey);
+            if (!info)
+                throw new Error("VM State account not found");
+            accountData = new Uint8Array(info.data);
+        }
+        else if (typeof connection.getAccountData === 'function') {
+            const info = await connection.getAccountData(vmStatePDA.address);
+            if (!info)
+                throw new Error("VM State account not found");
+            accountData = new Uint8Array(info.data);
+        }
+        else {
+            throw new Error("Invalid connection object: must support getAccountInfo or getAccountData");
+        }
+        if (accountData.length < 56)
+            throw new Error(`VM State account data too small: expected 56, got ${accountData.length}`);
+        const authority = Base58Utils.encode(accountData.slice(0, 32));
+        const view = new DataView(accountData.buffer, accountData.byteOffset, accountData.byteLength);
+        return {
+            authority,
+            scriptCount: Number(view.getBigUint64(32, true)),
+            deployFeeBps: view.getUint32(40, true),
+            executeFeeBps: view.getUint32(44, true),
+            isInitialized: accountData[48] === 1
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to fetch VM state: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+}

package/dist/program/AccountResolver.d.ts

@@ -0,0 +1,67 @@
+/**
+ * AccountResolver - Automatic system account injection
+ *
+ * Intelligently adds system accounts based on function constraints:
+ * - @init constraint → adds SystemProgram
+ * - Other constraints may add Rent, Clock, etc. (future)
+ *
+ * This reduces boilerplate by eliminating the need for developers to
+ * manually pass system accounts for every function call.
+ */
+import type { FunctionDefinition, ParameterDefinition, ScriptABI } from '../metadata/index.js';
+import type { FiveProgramOptions } from './FiveProgram.js';
+import type { FiveProgram } from './FiveProgram.js';
+export interface ResolvedSystemAccounts {
+    [accountName: string]: string;
+}
+/**
+ * AccountResolver handles automatic injection of system accounts
+ */
+export declare class AccountResolver {
+    private options;
+    constructor(options: FiveProgramOptions);
+    /**
+     * Resolve system accounts that should be auto-injected
+     * Detects @init constraints and adds SystemProgram if needed
+     *
+     * @param funcDef - Function definition from ABI
+     * @param providedAccounts - Accounts already provided by user
+     * @returns Map of system account names to their addresses
+     */
+    resolveSystemAccounts(funcDef: FunctionDefinition, providedAccounts: Map<string, string>): ResolvedSystemAccounts;
+    /**
+     * Resolve PDA accounts based on ABI constraints
+     *
+     * @param abi - Script ABI containing account constraints
+     * @param providedAccounts - Currently known accounts (user provided + system)
+     * @param program - FiveProgram instance for derivation util
+     */
+    resolvePdaAccounts(abi: ScriptABI, providedAccounts: Map<string, string>, program: FiveProgram): Promise<ResolvedSystemAccounts>;
+    /**
+     * Check if function has @init constraint on any parameter
+     * @init means account creation via CPI
+     *
+     * @param funcDef - Function definition
+     * @returns true if any parameter has @init attribute
+     */
+    private hasInitConstraint;
+    /**
+     * Get account metadata from parameter attributes
+     * Maps Five DSL attributes to Solana account properties
+     *
+     * @param param - Parameter definition
+     * @returns Object with isSigner and isWritable flags
+     */
+    getAccountMetadata(param: ParameterDefinition): {
+        isSigner: boolean;
+        isWritable: boolean;
+    };
+    /**
+     * Validate that all required accounts are provided after resolution
+     *
+     * @param funcDef - Function definition
+     * @param allAccounts - All accounts (user-provided + system-injected)
+     * @throws Error if required account is missing
+     */
+    validateResolvedAccounts(funcDef: FunctionDefinition, allAccounts: Map<string, string>): void;
+}

package/dist/program/AccountResolver.js

@@ -0,0 +1,134 @@
+/**
+ * AccountResolver - Automatic system account injection
+ *
+ * Intelligently adds system accounts based on function constraints:
+ * - @init constraint → adds SystemProgram
+ * - Other constraints may add Rent, Clock, etc. (future)
+ *
+ * This reduces boilerplate by eliminating the need for developers to
+ * manually pass system accounts for every function call.
+ */
+// Known system program IDs (Solana standard)
+const SYSTEM_PROGRAM_ID = '11111111111111111111111111111111';
+/**
+ * AccountResolver handles automatic injection of system accounts
+ */
+export class AccountResolver {
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * Resolve system accounts that should be auto-injected
+     * Detects @init constraints and adds SystemProgram if needed
+     *
+     * @param funcDef - Function definition from ABI
+     * @param providedAccounts - Accounts already provided by user
+     * @returns Map of system account names to their addresses
+     */
+    resolveSystemAccounts(funcDef, providedAccounts) {
+        const systemAccounts = {};
+        // Check if function has @init constraint
+        const hasInit = this.hasInitConstraint(funcDef);
+        if (hasInit && !providedAccounts.has('systemProgram')) {
+            systemAccounts['systemProgram'] = SYSTEM_PROGRAM_ID;
+            if (this.options.debug) {
+                console.log(`[AccountResolver] Auto-injecting SystemProgram for @init constraint`);
+            }
+        }
+        return systemAccounts;
+    }
+    /**
+     * Resolve PDA accounts based on ABI constraints
+     *
+     * @param abi - Script ABI containing account constraints
+     * @param providedAccounts - Currently known accounts (user provided + system)
+     * @param program - FiveProgram instance for derivation util
+     */
+    async resolvePdaAccounts(abi, providedAccounts, program) {
+        const pdaAccounts = {};
+        if (!abi.accounts)
+            return pdaAccounts;
+        // Filter for PDA constraints
+        const pdaConstraints = abi.accounts.filter(acc => acc.type === 'pda');
+        for (const constraint of pdaConstraints) {
+            if (providedAccounts.has(constraint.name)) {
+                continue; // User already provided it
+            }
+            // Resolve seeds
+            const seeds = [];
+            let canResolve = true;
+            for (const seed of (constraint.seeds || [])) {
+                if (seed.startsWith('"') && seed.endsWith('"')) {
+                    // Static string seed: "my_seed"
+                    seeds.push(seed.slice(1, -1));
+                }
+                else {
+                    // Dynamic seed: account reference
+                    const refAddr = providedAccounts.get(seed);
+                    if (refAddr) {
+                        seeds.push(refAddr);
+                    }
+                    else {
+                        // Dependency missing; single-pass resolution only.
+                        canResolve = false;
+                        break;
+                    }
+                }
+            }
+            if (canResolve && seeds.length > 0) {
+                try {
+                    const [pda] = await program.findAddress(seeds);
+                    pdaAccounts[constraint.name] = pda;
+                    if (this.options.debug) {
+                        console.log(`[AccountResolver] Auto-derived PDA '${constraint.name}': ${pda}`);
+                    }
+                }
+                catch (e) {
+                    console.warn(`[AccountResolver] Failed to derive PDA '${constraint.name}':`, e);
+                }
+            }
+        }
+        return pdaAccounts;
+    }
+    /**
+     * Check if function has @init constraint on any parameter
+     * @init means account creation via CPI
+     *
+     * @param funcDef - Function definition
+     * @returns true if any parameter has @init attribute
+     */
+    hasInitConstraint(funcDef) {
+        return funcDef.parameters.some((param) => {
+            const attributes = param.attributes || [];
+            return attributes.includes('init');
+        });
+    }
+    /**
+     * Get account metadata from parameter attributes
+     * Maps Five DSL attributes to Solana account properties
+     *
+     * @param param - Parameter definition
+     * @returns Object with isSigner and isWritable flags
+     */
+    getAccountMetadata(param) {
+        const attributes = param.attributes || [];
+        return {
+            isSigner: attributes.includes('signer'),
+            isWritable: attributes.includes('mut') || attributes.includes('init'),
+        };
+    }
+    /**
+     * Validate that all required accounts are provided after resolution
+     *
+     * @param funcDef - Function definition
+     * @param allAccounts - All accounts (user-provided + system-injected)
+     * @throws Error if required account is missing
+     */
+    validateResolvedAccounts(funcDef, allAccounts) {
+        for (const param of funcDef.parameters) {
+            if (param.is_account && !allAccounts.has(param.name)) {
+                throw new Error(`Required account '${param.name}' not provided and not auto-injected`);
+            }
+        }
+    }
+}

package/dist/program/BorshSchemaGenerator.d.ts

@@ -0,0 +1,8 @@
+import { ScriptABI, TypeDefinition } from '../metadata/index.js';
+export declare class BorshSchemaGenerator {
+    private abi;
+    constructor(abi: ScriptABI);
+    generate(typeDef: TypeDefinition): Map<Function, any>;
+    private processType;
+    private mapType;
+}

package/dist/program/BorshSchemaGenerator.js

@@ -0,0 +1,57 @@
+export class BorshSchemaGenerator {
+    constructor(abi) {
+        this.abi = abi;
+    }
+    generate(typeDef) {
+        const map = new Map();
+        this.processType(typeDef, map);
+        return map;
+    }
+    processType(typeDef, map) {
+        // Dynamic class creation for the schema
+        const StructClass = function () { };
+        Object.defineProperty(StructClass, 'name', { value: typeDef.name });
+        if (typeDef.structure === 'struct') {
+            const fields = typeDef.fields?.map(field => {
+                return [field.name, this.mapType(field.type)];
+            });
+            map.set(StructClass, { kind: 'struct', fields });
+        }
+        else if (typeDef.structure === 'enum') {
+            // Enum handling
+            const values = typeDef.variants?.map(v => {
+                // Safe cast or optional access as v matches structure
+                // Based on metadata definition, variants have { name, value? } but not explicit 'fields' in interface?
+                // We will map simple scalar enums
+                return [v.name, undefined];
+            });
+            map.set(StructClass, { kind: 'enum', values });
+        }
+    }
+    mapType(type) {
+        switch (type) {
+            case 'u8': return 'u8';
+            case 'u16': return 'u16';
+            case 'u32': return 'u32';
+            case 'u64': return 'u64';
+            case 'u128': return 'u128';
+            case 'i8': return 'i8';
+            case 'i16': return 'i16';
+            case 'i32': return 'i32';
+            case 'i64': return 'i64';
+            case 'i128': return 'i128';
+            case 'bool': return 'u8'; // Borsh standard for bool
+            case 'string': return 'string';
+            case 'pubkey': return [32]; // Fixed array of 32 bytes
+            default:
+                // Handle vectors: Vec<T>
+                if (type.startsWith('Vec<')) {
+                    const inner = type.slice(4, -1);
+                    return [this.mapType(inner)];
+                }
+                // Handle arrays: [T; N]
+                // Handle option: Option<T>
+                return type; // Assume it's a known struct name
+        }
+    }
+}