@5ive-tech/sdk 1.1.2

package/README.md

@@ -0,0 +1,279 @@
+# Five SDK
+
+Client-agnostic TypeScript SDK for interacting with 5ive DSL programs on Solana.
+
+This README is for external developers using:
+- `five-cli`
+- `five-sdk`
+- [5ive.tech](https://5ive.tech)
+
+## Install
+
+```bash
+npm install @5ive-tech/sdk @solana/web3.js
+```
+
+Note: Some older examples may use `@5ive-tech/sdk`. Use the package name your registry currently publishes for your release channel.
+
+## Quick Start
+
+### 1. Compile with `five-cli` to `.five` artifact
+
+```bash
+five compile src/main.v -o build/my-program.five
+```
+
+### 1b. Compile directly with `five-sdk` (optional)
+
+```ts
+import { FiveSDK } from '@5ive-tech/sdk';
+import fs from 'fs';
+
+const source = `
+pub add(a: u64, b: u64) -> u64 {
+  return a + b;
+}
+`;
+
+const result = await FiveSDK.compile(source, {
+  optimize: true,
+  debug: false,
+});
+
+if (!result.success || !result.fiveFile) {
+  throw new Error(`Compilation failed: ${JSON.stringify(result.errors ?? [])}`);
+}
+
+fs.writeFileSync('build/my-program.five', JSON.stringify(result.fiveFile, null, 2));
+```
+
+Compile from file path:
+
+```ts
+const fileResult = await FiveSDK.compileFile('src/main.v', { optimize: true });
+```
+
+Compile multi-file/module source:
+
+```ts
+const multi = await FiveSDK.compileModules(
+  { filename: 'main.v', content: mainSource },
+  [{ name: 'math', source: mathModuleSource }],
+  { optimize: true }
+);
+```
+
+### 2. Load ABI from `.five`
+
+```ts
+import fs from 'fs';
+import { FiveSDK } from '@5ive-tech/sdk';
+
+const fiveFileText = fs.readFileSync('build/my-program.five', 'utf-8');
+const { abi } = await FiveSDK.loadFiveFile(fiveFileText);
+```
+
+### 3. Configure program ID resolution
+
+On-chain instruction generation requires a resolvable Five VM program ID.
+Resolution precedence:
+1. Explicit `fiveVMProgramId`
+2. `FiveSDK.setDefaultProgramId(...)`
+3. `FIVE_PROGRAM_ID` environment variable
+4. Release-baked default
+
+```ts
+import { FiveSDK } from '@5ive-tech/sdk';
+
+FiveSDK.setDefaultProgramId('YourFiveVMProgramIdBase58');
+```
+
+### 4. Create `FiveProgram`
+
+```ts
+import { FiveProgram } from '@5ive-tech/sdk';
+
+const program = FiveProgram.fromABI('ScriptAccountBase58', abi, {
+  fiveVMProgramId: 'YourFiveVMProgramIdBase58',
+  vmStateAccount: 'VmStatePdaBase58',
+  feeReceiverAccount: 'FeeReceiverBase58',
+  debug: false,
+});
+```
+
+## Build and Send Instructions
+
+```ts
+import {
+  Connection,
+  PublicKey,
+  Transaction,
+  TransactionInstruction,
+  sendAndConfirmTransaction,
+} from '@solana/web3.js';
+
+const connection = new Connection('http://127.0.0.1:8899', 'confirmed');
+
+const ixData = await program
+  .function('transfer')
+  .accounts({
+    source_account: sourcePubkey,
+    destination_account: destinationPubkey,
+    owner: ownerPubkey,
+  })
+  .args({ amount: 100 })
+  .instruction();
+
+const ix = new TransactionInstruction({
+  programId: new PublicKey(ixData.programId),
+  keys: ixData.keys.map((k) => ({
+    pubkey: new PublicKey(k.pubkey),
+    isSigner: k.isSigner,
+    isWritable: k.isWritable,
+  })),
+  data: Buffer.from(ixData.data, 'base64'),
+});
+
+const tx = new Transaction().add(ix);
+const signature = await sendAndConfirmTransaction(connection, tx, [payer], {
+  skipPreflight: false,
+  commitment: 'confirmed',
+});
+
+const txDetails = await connection.getTransaction(signature, {
+  maxSupportedTransactionVersion: 0,
+  commitment: 'confirmed',
+});
+
+if (txDetails?.meta?.err) {
+  throw new Error(`On-chain error: ${JSON.stringify(txDetails.meta.err)}`);
+}
+
+console.log('signature', signature);
+console.log('computeUnits', txDetails?.meta?.computeUnitsConsumed);
+```
+
+## Operational Patterns
+
+### Function naming in multi-file programs
+
+Function names must match ABI names exactly, including namespaced forms such as `math::add`.
+
+```ts
+console.log(program.getFunctions());
+```
+
+### Account wiring behavior
+
+`FunctionBuilder` automatically handles:
+- system-account injection when ABI constraints require it
+- PDA account resolution from ABI metadata
+- signer/writable metadata derivation from ABI attributes
+
+You still must pass all required business accounts and arguments.
+
+### Deterministic error handling
+
+Recommended send pattern:
+1. send with `skipPreflight: false`
+2. fetch confirmed transaction
+3. assert `meta.err` is null
+4. record CU from `meta.computeUnitsConsumed`
+
+## Advanced SDK APIs (Optional)
+
+Most builders should use `FiveProgram` first. Use these lower-level APIs when you need finer control.
+
+### 1) Local VM testing without RPC
+
+```ts
+const run = await FiveSDK.compileAndExecuteLocally(
+  sourceCode,
+  'transfer',
+  [100],
+  { optimize: true, trace: true, computeUnitLimit: 1_000_000 }
+);
+```
+
+### 2) Instruction-only generation (bring your own sender)
+
+```ts
+const deploy = await FiveSDK.generateDeployInstruction(bytecode, deployerPubkeyBase58, {
+  debug: false,
+});
+
+const exec = await FiveSDK.generateExecuteInstruction(
+  scriptAccountBase58,
+  'transfer',
+  [100],
+  [ownerPubkeyBase58],
+  connection,
+  { computeUnitLimit: 1_000_000 }
+);
+```
+
+### 3) On-chain convenience helpers
+
+```ts
+const deployResult = await FiveSDK.deployToSolana(bytecode, connection, payerKeypair, {
+  fiveVMProgramId: 'YourFiveVMProgramIdBase58',
+});
+
+const execResult = await FiveSDK.executeOnSolana(
+  deployResult.scriptAccount,
+  connection,
+  payerKeypair,
+  'transfer',
+  [100],
+  [ownerPubkeyBase58],
+  { fiveVMProgramId: 'YourFiveVMProgramIdBase58' }
+);
+```
+
+### 4) Metadata, decoding, and diagnostics
+
+```ts
+const meta = await FiveSDK.getScriptMetadataWithConnection(scriptAccountBase58, connection);
+const names = await FiveSDK.getFunctionNamesFromScriptAccount(scriptAccountBase58, connection);
+const account = await FiveSDK.fetchAccountAndDeserialize(scriptAccountBase58, connection, {
+  parseMetadata: true,
+});
+```
+
+### 5) Namespace helpers (5NS)
+
+```ts
+const ns = FiveSDK.canonicalizeNamespace('@acme/payments');
+const derived = await FiveSDK.deriveNamespaceAccounts(ns.canonical, 'YourFiveVMProgramIdBase58');
+```
+
+### 6) Test utilities
+
+```ts
+import { FiveTestRunner } from '@5ive-tech/sdk';
+
+const runner = new FiveTestRunner({ verbose: true, maxComputeUnits: 1_000_000 });
+```
+
+## Frontend Usage (`5ive.tech`)
+
+For frontend integration patterns and UI workflows, use [5ive.tech](https://5ive.tech).
+Typical flow:
+1. compile/deploy with `five-cli`
+2. use `five-sdk` in your app/backend to generate instructions
+3. submit signed transactions from wallet-enabled frontend
+
+## Troubleshooting
+
+### `No program ID resolved for Five VM`
+Set one via explicit `fiveVMProgramId`, `FiveSDK.setDefaultProgramId`, or `FIVE_PROGRAM_ID`.
+
+### `Function '<name>' not found in ABI`
+Use exact ABI function names (including namespace prefixes).
+
+### `Missing required account` / `Missing required argument`
+Provide all required fields in `.accounts(...)` and `.args(...)`.
+
+## Next Doc
+
+For API-level usage details, see `FIVEPROGRAM_USAGE_GUIDE.md`.

package/dist/FiveSDK.d.ts

@@ -0,0 +1,336 @@
+/**
+ * Five SDK client for Five VM scripts.
+ */
+import { FiveSDKConfig, FiveScriptSource, FiveBytecode, CompilationOptions, CompilationResult, DeploymentOptions, SerializedDeployment, SerializedExecution, FiveCompiledFile, FunctionNameEntry, FeeInformation } from "./types.js";
+import { ScriptMetadata } from "./metadata/index.js";
+import * as Namespaces from "./modules/namespaces.js";
+/**
+ * Main Five SDK class - entry point for all Five VM interactions
+ */
+export declare class FiveSDK {
+    private static compiler;
+    private static parameterEncoder;
+    private static metadataCache;
+    private fiveVMProgramId?;
+    private debug;
+    private network?;
+    constructor(config?: FiveSDKConfig);
+    getConfig(): FiveSDKConfig & {
+        network?: string;
+    };
+    private static initializeComponents;
+    static create(options?: {
+        debug?: boolean;
+        fiveVMProgramId?: string;
+    }): FiveSDK;
+    static devnet(options?: {
+        debug?: boolean;
+        fiveVMProgramId?: string;
+    }): FiveSDK;
+    static mainnet(options?: {
+        debug?: boolean;
+        fiveVMProgramId?: string;
+    }): FiveSDK;
+    static localnet(options?: {
+        debug?: boolean;
+        fiveVMProgramId?: string;
+    }): FiveSDK;
+    /**
+     * Set the default program ID for all SDK instances and operations
+     * Useful when deploying to a known program ID across your application
+     * @param programId - Solana public key (base58 encoded)
+     */
+    static setDefaultProgramId(programId: string): void;
+    /**
+     * Get the currently set default program ID
+     * @returns The default program ID, or undefined if not set
+     */
+    static getDefaultProgramId(): string | undefined;
+    static canonicalizeNamespace(value: string): Namespaces.ScopedNamespace;
+    static namespaceSeedBytes(value: string): Uint8Array;
+    static resolveNamespaceFromLockfile(value: string, lockfile: any): string | undefined;
+    static deriveNamespaceAccounts(value: string, fiveVMProgramId: string): Promise<Namespaces.NamespaceDerivedAccounts>;
+    static registerNamespaceTldOnChain(namespaceValue: string, options: {
+        managerScriptAccount: string;
+        connection: any;
+        signerKeypair: any;
+        fiveVMProgramId?: string;
+        debug?: boolean;
+    }): Promise<{
+        transactionId?: string;
+        tldAddress: string;
+        owner: string;
+        treasuryAccount: string;
+    }>;
+    static bindNamespaceOnChain(namespaceValue: string, scriptAccount: string, options: {
+        managerScriptAccount: string;
+        connection: any;
+        signerKeypair: any;
+        fiveVMProgramId?: string;
+        debug?: boolean;
+    }): Promise<{
+        transactionId?: string;
+        bindingAddress: string;
+        owner: string;
+    }>;
+    static resolveNamespaceOnChain(namespaceValue: string, options: {
+        managerScriptAccount: string;
+        connection: any;
+        signerKeypair: any;
+        fiveVMProgramId?: string;
+        debug?: boolean;
+    }): Promise<{
+        transactionId?: string;
+        resolvedScript?: string;
+        bindingAddress: string;
+    }>;
+    static compile(source: FiveScriptSource | string, options?: CompilationOptions & {
+        debug?: boolean;
+    }): Promise<CompilationResult>;
+    static compileModules(mainSource: FiveScriptSource | string, modules: Array<{
+        name: string;
+        source: string;
+    }>, options?: CompilationOptions & {
+        debug?: boolean;
+    }): Promise<CompilationResult>;
+    static compileWithDiscovery(entryPoint: string, options?: CompilationOptions & {
+        debug?: boolean;
+    }): Promise<CompilationResult>;
+    static discoverModules(entryPoint: string, options?: {
+        debug?: boolean;
+    }): Promise<string[]>;
+    static compileFile(filePath: string, options?: CompilationOptions & {
+        debug?: boolean;
+    }): Promise<CompilationResult>;
+    static loadFiveFile(fileContent: string): Promise<{
+        bytecode: FiveBytecode;
+        abi: any;
+        debug?: any;
+    }>;
+    static extractBytecode(fiveFile: FiveCompiledFile): FiveBytecode;
+    static resolveFunctionIndex(abi: any, functionName: string): number;
+    static executeLocally(bytecode: FiveBytecode, functionName: string | number, parameters?: any[], options?: {
+        debug?: boolean;
+        trace?: boolean;
+        computeUnitLimit?: number;
+        abi?: any;
+        accounts?: string[];
+    }): Promise<any>;
+    static execute(source: FiveScriptSource | string, functionName: string | number, parameters?: any[], options?: {
+        debug?: boolean;
+        trace?: boolean;
+        optimize?: boolean;
+        computeUnitLimit?: number;
+        vmStateAccount?: string;
+        accounts?: string[];
+    }): Promise<{
+        success: boolean;
+        compilationErrors: import("./types.js").CompilationError[];
+        error: string;
+    } | {
+        compilation: CompilationResult;
+        bytecodeSize: number;
+        functions: any[];
+        success: boolean;
+        result?: any;
+        logs?: string[];
+        computeUnitsUsed?: number;
+        executionTime?: number;
+        error?: string;
+        trace?: any[];
+        compilationErrors?: undefined;
+    }>;
+    static validateBytecode(bytecode: FiveBytecode, options?: {
+        debug?: boolean;
+    }): Promise<{
+        valid: boolean;
+        errors?: string[];
+        metadata?: any;
+        functions?: any[];
+    }>;
+    static generateDeployInstruction(bytecode: FiveBytecode, deployer: string, options?: DeploymentOptions & {
+        debug?: boolean;
+    }, connection?: any): Promise<SerializedDeployment>;
+    static generateExecuteInstruction(scriptAccount: string, functionName: string | number, parameters?: any[], accounts?: string[], connection?: any, options?: {
+        debug?: boolean;
+        computeUnitLimit?: number;
+        vmStateAccount?: string;
+        fiveVMProgramId?: string;
+        abi?: any;
+        adminAccount?: string;
+        estimateFees?: boolean;
+        accountMetadata?: Map<string, {
+            isSigner: boolean;
+            isWritable: boolean;
+            isSystemAccount?: boolean;
+        }>;
+    }): Promise<SerializedExecution>;
+    static getVMState(connection: any, fiveVMProgramId?: string): Promise<{
+        authority: string;
+        scriptCount: number;
+        deployFeeBps: number;
+        executeFeeBps: number;
+        isInitialized: boolean;
+    }>;
+    static getFees(connection: any, fiveVMProgramId?: string): Promise<{
+        deployFeeBps: number;
+        executeFeeBps: number;
+        adminAccount: string | null;
+    }>;
+    static calculateDeployFee(bytecodeSize: number, connection?: any, fiveVMProgramId?: string): Promise<FeeInformation>;
+    static calculateExecuteFee(connection?: any, fiveVMProgramId?: string): Promise<FeeInformation>;
+    static getFeeInformation(bytecodeSize: number, connection?: any, fiveVMProgramId?: string): Promise<{
+        deploy: FeeInformation;
+        execute: FeeInformation;
+        adminAccount: string | null;
+        feesEnabled: boolean;
+    }>;
+    static getScriptMetadata(scriptAccount: string, connection?: any): Promise<{
+        functions: any[];
+    }>;
+    static getScriptMetadataWithConnection(scriptAccount: string, connection: any): Promise<ScriptMetadata>;
+    static parseScriptMetadata(accountData: Uint8Array, address: string): ScriptMetadata;
+    static getCachedScriptMetadata(scriptAccount: string, connection: any, cacheTTL?: number): Promise<ScriptMetadata>;
+    static invalidateMetadataCache(scriptAccount: string): void;
+    static getMetadataCacheStats(): any;
+    static executeOnSolana(scriptAccount: string, connection: any, signerKeypair: any, functionName: string | number, parameters?: any[], accounts?: string[], options?: any): Promise<{
+        success: boolean;
+        result?: any;
+        transactionId?: string;
+        computeUnitsUsed?: number;
+        cost?: number;
+        error?: string;
+        logs?: string[];
+    }>;
+    static executeScriptAccount(scriptAccount: string, functionIndex: number, parameters: any[], connection: any, signerKeypair: any, options?: any): Promise<{
+        success: boolean;
+        result?: any;
+        transactionId?: string;
+        computeUnitsUsed?: number;
+        cost?: number;
+        error?: string;
+        logs?: string[];
+    }>;
+    static getFunctionNames(bytecode: FiveBytecode): Promise<FunctionNameEntry[]>;
+    static callFunctionByName(scriptAccount: string, functionName: string, parameters?: any[], accounts?: string[], connection?: any, options?: any): Promise<SerializedExecution>;
+    static executeByIndex(scriptAccount: string, functionIndex: number, parameters?: any[], accounts?: string[], connection?: any, options?: any): Promise<SerializedExecution>;
+    static getFunctionNamesFromScriptAccount(scriptAccount: string, connection?: any): Promise<FunctionNameEntry[] | null>;
+    static createDeploymentTransaction(bytecode: FiveBytecode, connection: any, deployerPublicKey: any, options?: any): Promise<{
+        transaction: any;
+        scriptKeypair: any;
+        vmStateKeypair: any;
+        programId: string;
+        rentLamports: number;
+    }>;
+    static deployToSolana(bytecode: FiveBytecode, connection: any, deployerKeypair: any, options?: any): Promise<{
+        success: boolean;
+        programId?: string;
+        transactionId?: string;
+        deploymentCost?: number;
+        error?: string;
+        logs?: string[];
+        vmStateAccount?: string;
+    }>;
+    static deployLargeProgramToSolana(bytecode: FiveBytecode, connection: any, deployerKeypair: any, options?: any): Promise<{
+        success: boolean;
+        scriptAccount?: string;
+        transactionIds?: string[];
+        totalTransactions?: number;
+        deploymentCost?: number;
+        chunksUsed?: number;
+        vmStateAccount?: string;
+        error?: string;
+        logs?: string[];
+    }>;
+    static deployLargeProgramOptimizedToSolana(bytecode: FiveBytecode, connection: any, deployerKeypair: any, options?: any): Promise<{
+        success: boolean;
+        scriptAccount?: string;
+        transactionIds?: string[];
+        totalTransactions?: number;
+        deploymentCost?: number;
+        chunksUsed?: number;
+        vmStateAccount?: string;
+        optimizationSavings?: {
+            transactionsSaved: number;
+            estimatedCostSaved: number;
+        };
+        error?: string;
+        logs?: string[];
+    }>;
+    static fetchAccountAndDeserialize(accountAddress: string, connection: any, options?: any): 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[];
+    }>;
+    static fetchMultipleAccountsAndDeserialize(accountAddresses: string[], connection: any, options?: any): Promise<Map<string, {
+        success: boolean;
+        accountInfo?: any;
+        scriptMetadata?: ScriptMetadata;
+        rawBytecode?: Uint8Array;
+        decodedData?: any;
+        error?: string;
+        logs?: string[];
+    }>>;
+    static deserializeParameters(instructionData: Uint8Array, expectedTypes?: string[], options?: any): Promise<{
+        success: boolean;
+        parameters?: Array<{
+            type: string;
+            value: any;
+        }>;
+        functionIndex?: number;
+        discriminator?: number;
+        error?: string;
+    }>;
+    static validateBytecodeEncoding(bytecode: Uint8Array, debug?: boolean): Promise<{
+        valid: boolean;
+        error?: string;
+        info?: string;
+    }>;
+    static executeWithStateDiff(scriptAccount: string, connection: any, signerKeypair: any, functionName: string | number, parameters?: any[], options?: any): Promise<{
+        success: boolean;
+        execution?: {
+            transactionId?: string;
+            result?: any;
+            computeUnitsUsed?: number;
+            logs?: string[];
+        };
+        stateDiff?: {
+            beforeState: Map<string, any>;
+            afterState: Map<string, any>;
+            changes: Array<{
+                account: string;
+                fieldName?: string;
+                oldValue: any;
+                newValue: any;
+                changeType: "created" | "modified" | "deleted";
+            }>;
+            globalFieldChanges?: Array<{
+                fieldName: string;
+                oldValue: any;
+                newValue: any;
+            }>;
+        };
+        error?: string;
+        logs?: string[];
+    }>;
+}
+export declare const createFiveSDK: (config?: FiveSDKConfig) => FiveSDK;
+export default FiveSDK;