@5ive-tech/sdk 1.1.16 → 1.1.18

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Five VM Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/config/VmClusterConfigResolver.d.ts

@@ -3,6 +3,12 @@ export interface VmClusterProfile {
     configPath: string;
     programId: string;
     feeVaultShardCount: number;
+    sessionService?: {
+        scriptAccount?: string;
+        codeHash?: string;
+        status?: 'active' | 'disabled';
+        version?: number;
+    };
 }
 export interface VmClusterAddresses {
     cluster: VmClusterProfile['cluster'];

package/dist/config/VmClusterConfigResolver.js

@@ -84,11 +84,27 @@ export class VmClusterConfigResolver {
             throw new Error(`Invalid fee_vault_shard_count for cluster ${cluster}`);
         }
         const programId = new PublicKey(entry.program_id).toBase58();
+        const sessionScript = entry.session_v1_script_account
+            ? new PublicKey(entry.session_v1_script_account).toBase58()
+            : undefined;
+        const sessionHash = entry.session_v1_code_hash
+            ? new PublicKey(entry.session_v1_code_hash).toBase58()
+            : undefined;
+        const sessionStatus = entry.session_v1_status === 0 ? 'disabled' : 'active';
+        const sessionVersion = Number.isInteger(entry.session_v1_version)
+            ? entry.session_v1_version
+            : 1;
         return {
             cluster: cluster,
             configPath,
             programId,
             feeVaultShardCount: entry.fee_vault_shard_count,
+            sessionService: {
+                scriptAccount: sessionScript,
+                codeHash: sessionHash,
+                status: sessionStatus,
+                version: sessionVersion,
+            },
         };
     }
     static deriveVmAddresses(profile) {

package/dist/lib/bytecode-encoder.js

@@ -68,6 +68,7 @@ export class BytecodeEncoder {
                 maxLen: typeSpec.maxLen,
             };
         });
+        let wasmLoadError = null;
         // Load WASM module using shared loader
         if (!wasmModule) {
             try {
@@ -88,11 +89,12 @@ export class BytecodeEncoder {
                 }
             }
             catch (e) {
-                // Silently ignore loader errors and try fallback
                 wasmModule = null;
+                wasmLoadError = e;
             }
             // Fallback: import the wasm-pack generated module for Node.js.
-            if (!wasmModule && typeof process !== 'undefined') {
+            const hasWindow = typeof globalThis.window !== 'undefined';
+            if (!wasmModule && !hasWindow && typeof process !== 'undefined') {
                 console.log("[DEBUG] (SRC) Attempting wasm-pack module import...");
                 try {
                     const fs = await import('fs');
@@ -123,6 +125,14 @@ export class BytecodeEncoder {
                     // Don't throw - let it fall through to error handling below.
                 }
             }
+            if (!wasmModule || !wasmModule.ParameterEncoder) {
+                const detail = wasmLoadError instanceof Error
+                    ? wasmLoadError.message
+                    : wasmLoadError
+                        ? String(wasmLoadError)
+                        : "WASM module loaded without ParameterEncoder";
+                throw new Error(`[BytecodeEncoder] WASM ParameterEncoder unavailable: ${detail}`);
+            }
         }
         const filteredParams = normalizedParameters;
         const paramValues = filteredParams.map(param => {

package/dist/metadata/index.d.ts

@@ -92,6 +92,10 @@ export interface ParameterDefinition {
     param_type?: string;
     /** Whether this is an account parameter */
     is_account?: boolean;
+    /** Compiler-injected parameter not authored in source */
+    implicit?: boolean;
+    /** Parameter origin */
+    source?: 'authored' | 'compiler';
     /** Account attributes (e.g., "mut", "signer", "init") */
     attributes?: string[];
     /** Whether parameter is optional */

package/dist/modules/deploy.d.ts

@@ -16,6 +16,7 @@ options?: {
     fiveVMProgramId?: string;
     computeBudget?: number;
     exportMetadata?: ExportMetadataInput;
+    service?: "session_v1";
 }): Promise<{
     transaction: any;
     scriptKeypair: any;
@@ -34,6 +35,7 @@ options?: {
     vmStateAccount?: string;
     adminAccount?: string;
     exportMetadata?: ExportMetadataInput;
+    service?: "session_v1";
 }): Promise<{
     success: boolean;
     programId?: string;

package/dist/modules/deploy.js

@@ -18,10 +18,20 @@ const FEE_VAULT_NAMESPACE_SEED = Buffer.from([
     0xff, 0x66, 0x69, 0x76, 0x65, 0x5f, 0x76, 0x6d, 0x5f, 0x66, 0x65, 0x65,
     0x5f, 0x76, 0x61, 0x75, 0x6c, 0x74, 0x5f, 0x76, 0x31,
 ]);
+const SESSION_V1_SERVICE_SEED = Buffer.from("session_v1", "utf-8");
+const SERVICE_KIND_NONE = 0;
+const SERVICE_KIND_SESSION_V1 = 1;
 function clampShardCount(rawCount) {
     const normalized = rawCount > 0 ? rawCount : DEFAULT_FEE_VAULT_SHARD_COUNT;
     return Math.max(1, Math.min(MAX_FEE_VAULT_SHARD_COUNT, normalized));
 }
+function resolveServiceKind(service) {
+    if (!service)
+        return SERVICE_KIND_NONE;
+    if (service === "session_v1")
+        return SERVICE_KIND_SESSION_V1;
+    throw new Error(`Unsupported deploy service: ${service}`);
+}
 function normalizeRpcEndpoint(connection) {
     return String(connection?.rpcEndpoint || connection?._rpcEndpoint || "").toLowerCase();
 }
@@ -71,6 +81,14 @@ async function deriveProgramFeeVault(programId, shardIndex) {
 }
 async function resolveScriptAccountDerivation(bytecode, deployer, programId, options) {
     const { PublicKey } = await import("@solana/web3.js");
+    if (options.service === "session_v1") {
+        const [servicePda, serviceBump] = PublicKey.findProgramAddressSync([SESSION_V1_SERVICE_SEED], new PublicKey(programId));
+        return {
+            address: servicePda.toBase58(),
+            bump: serviceBump,
+            seed: "session_v1",
+        };
+    }
     if (options.scriptAccount) {
         validator.validateBase58Address(options.scriptAccount, "options.scriptAccount");
         if (!options.scriptSeed) {
@@ -181,7 +199,7 @@ export async function generateDeployInstruction(bytecode, deployer, options = {}
         isSigner: false,
         isWritable: false,
     });
-    const instructionData = encodeDeployInstruction(bytecode, options.permissions || 0, exportMetadata, deployShardIndex, deployVault.bump);
+    const instructionData = encodeDeployInstruction(bytecode, options.permissions || 0, exportMetadata, deployShardIndex, deployVault.bump, resolveServiceKind(options.service));
     const result = {
         programId: programId,
         instruction: {
@@ -193,15 +211,23 @@ export async function generateDeployInstruction(bytecode, deployer, options = {}
         requiredSigners: [deployer],
         estimatedCost: rentLamports + (options.extraLamports || 0),
         bytecodeSize: bytecode.length,
-        setupInstructions: {
-            createScriptAccount: {
-                pda: scriptAccount,
-                seed: scriptSeed,
-                space: totalAccountSize,
-                rent: rentLamports,
-                owner: programId,
+        setupInstructions: options.service === "session_v1"
+            ? {
+                serviceDeployment: {
+                    service: "session_v1",
+                    pda: scriptAccount,
+                    seed: scriptSeed,
+                },
+            }
+            : {
+                createScriptAccount: {
+                    pda: scriptAccount,
+                    seed: scriptSeed,
+                    space: totalAccountSize,
+                    rent: rentLamports,
+                    owner: programId,
+                },
             },
-        },
         adminAccount: options.adminAccount,
     };
     if (options.debug) {
@@ -237,9 +263,18 @@ options = {}) {
     const { Keypair, PublicKey, Transaction, TransactionInstruction, SystemProgram, ComputeBudgetProgram, } = await import("@solana/web3.js");
     const programIdStr = ProgramIdResolver.resolve(options.fiveVMProgramId);
     const programId = new PublicKey(programIdStr);
-    // Generate script keypair
-    const scriptKeypair = Keypair.generate();
-    const scriptAccount = scriptKeypair.publicKey.toString();
+    const serviceKind = resolveServiceKind(options.service);
+    let scriptKeypair = null;
+    let scriptPubkey;
+    if (serviceKind === SERVICE_KIND_SESSION_V1) {
+        const derived = PublicKey.findProgramAddressSync([SESSION_V1_SERVICE_SEED], new PublicKey(programIdStr));
+        scriptPubkey = derived[0];
+    }
+    else {
+        scriptKeypair = Keypair.generate();
+        scriptPubkey = scriptKeypair.publicKey;
+    }
+    const scriptAccount = scriptPubkey.toString();
     // Calculate account size and rent
     const exportMetadata = encodeExportMetadata(options.exportMetadata);
     const totalAccountSize = SCRIPT_ACCOUNT_HEADER_LEN + exportMetadata.length + bytecode.length;
@@ -275,18 +310,22 @@ options = {}) {
         }));
     }
     // 2. Create Script Account
-    tx.add(SystemProgram.createAccount({
-        fromPubkey: deployerPublicKey,
-        newAccountPubkey: scriptKeypair.publicKey,
-        lamports: rentLamports,
-        space: totalAccountSize,
-        programId: programId,
-    }));
+    tx.add(...(scriptKeypair
+        ? [
+            SystemProgram.createAccount({
+                fromPubkey: deployerPublicKey,
+                newAccountPubkey: scriptKeypair.publicKey,
+                lamports: rentLamports,
+                space: totalAccountSize,
+                programId: programId,
+            }),
+        ]
+        : []));
     // 3. Deploy Instruction
-    const deployData = encodeDeployInstruction(bytecode, 0, exportMetadata);
+    const deployData = encodeDeployInstruction(bytecode, 0, exportMetadata, 0, undefined, serviceKind);
     tx.add(new TransactionInstruction({
         keys: [
-            { pubkey: scriptKeypair.publicKey, isSigner: false, isWritable: true },
+            { pubkey: scriptPubkey, isSigner: false, isWritable: true },
             { pubkey: vmStatePubkey, isSigner: false, isWritable: true },
             { pubkey: deployerPublicKey, isSigner: true, isWritable: true },
         ],
@@ -297,7 +336,9 @@ options = {}) {
     tx.recentBlockhash = blockhash;
     tx.feePayer = deployerPublicKey;
     // Partial sign with generated keys
-    tx.partialSign(scriptKeypair);
+    if (scriptKeypair) {
+        tx.partialSign(scriptKeypair);
+    }
     return {
         transaction: tx,
         scriptKeypair,
@@ -319,10 +360,25 @@ options = {}) {
         }
         // Generate script keypair like frontend-five
         const { Keypair, PublicKey, Transaction, TransactionInstruction, SystemProgram, } = await import("@solana/web3.js");
-        const scriptKeypair = Keypair.generate();
-        const scriptAccount = scriptKeypair.publicKey.toString();
+        const serviceKind = resolveServiceKind(options.service);
+        let scriptKeypair = null;
+        let scriptPubkey;
+        if (serviceKind === SERVICE_KIND_SESSION_V1) {
+            const derived = PublicKey.findProgramAddressSync([SESSION_V1_SERVICE_SEED], new PublicKey(programId));
+            scriptPubkey = derived[0];
+        }
+        else {
+            scriptKeypair = Keypair.generate();
+            scriptPubkey = scriptKeypair.publicKey;
+        }
+        const scriptAccount = scriptPubkey.toString();
         if (options.debug) {
-            console.log(`[FiveSDK] Generated script keypair: ${scriptAccount}`);
+            if (scriptKeypair) {
+                console.log(`[FiveSDK] Generated script keypair: ${scriptAccount}`);
+            }
+            else {
+                console.log(`[FiveSDK] Using canonical service PDA script account: ${scriptAccount}`);
+            }
         }
         // Calculate account size and rent
         const exportMetadata = encodeExportMetadata(options.exportMetadata);
@@ -372,21 +428,23 @@ options = {}) {
             }
             catch { }
         }
-        // 1) Create script account
-        const createAccountIx = SystemProgram.createAccount({
-            fromPubkey: deployerKeypair.publicKey,
-            newAccountPubkey: scriptKeypair.publicKey,
-            lamports: rentLamports,
-            space: totalAccountSize,
-            programId: new PublicKey(programId),
-        });
-        tx.add(createAccountIx);
-        const deployData = encodeDeployInstruction(bytecode, 0, exportMetadata, deployShardIndex, deployVault.bump);
+        // 1) Create script account for non-service deployments.
+        if (scriptKeypair) {
+            const createAccountIx = SystemProgram.createAccount({
+                fromPubkey: deployerKeypair.publicKey,
+                newAccountPubkey: scriptKeypair.publicKey,
+                lamports: rentLamports,
+                space: totalAccountSize,
+                programId: new PublicKey(programId),
+            });
+            tx.add(createAccountIx);
+        }
+        const deployData = encodeDeployInstruction(bytecode, 0, exportMetadata, deployShardIndex, deployVault.bump, serviceKind);
         const instructionDataBuffer = Buffer.from(deployData);
         const deployIx = new TransactionInstruction({
             keys: [
                 {
-                    pubkey: scriptKeypair.publicKey,
+                    pubkey: scriptPubkey,
                     isSigner: false,
                     isWritable: true,
                 },
@@ -419,7 +477,9 @@ options = {}) {
         tx.recentBlockhash = blockhash;
         tx.feePayer = deployerKeypair.publicKey;
         tx.partialSign(deployerKeypair);
-        tx.partialSign(scriptKeypair);
+        if (scriptKeypair) {
+            tx.partialSign(scriptKeypair);
+        }
         const txSerialized = tx.serialize();
         if (options.debug) {
             console.log(`[FiveSDK] Transaction serialized: ${txSerialized.length} bytes`);
@@ -1085,13 +1145,14 @@ options = {}) {
         };
     }
 }
-function encodeDeployInstruction(bytecode, permissions = 0, metadata = new Uint8Array(), feeShardIndex = 0, feeVaultBump) {
+function encodeDeployInstruction(bytecode, permissions = 0, metadata = new Uint8Array(), feeShardIndex = 0, feeVaultBump, serviceKind = SERVICE_KIND_NONE) {
     const lengthBuffer = Buffer.allocUnsafe(4);
     lengthBuffer.writeUInt32LE(bytecode.length, 0);
     const metadataLenBuffer = Buffer.allocUnsafe(4);
     metadataLenBuffer.writeUInt32LE(metadata.length, 0);
     const hasFeeTrailer = typeof feeVaultBump === "number";
-    const result = new Uint8Array(1 + 4 + 1 + 4 + metadata.length + bytecode.length + (hasFeeTrailer ? 2 : 0));
+    const hasServiceTrailer = serviceKind !== SERVICE_KIND_NONE;
+    const result = new Uint8Array(1 + 4 + 1 + 4 + metadata.length + bytecode.length + (hasFeeTrailer ? 2 : 0) + (hasServiceTrailer ? 1 : 0));
     result[0] = 8; // Deploy discriminator (matches on-chain FIVE program)
     result.set(new Uint8Array(lengthBuffer), 1); // u32 LE length at bytes 1-4
     result[5] = permissions; // permissions byte at byte 5
@@ -1103,6 +1164,10 @@ function encodeDeployInstruction(bytecode, permissions = 0, metadata = new Uint8
         result[trailerOffset] = feeShardIndex & 0xff;
         result[trailerOffset + 1] = feeVaultBump & 0xff;
     }
+    if (hasServiceTrailer) {
+        const trailerOffset = 10 + metadata.length + bytecode.length + (hasFeeTrailer ? 2 : 0);
+        result[trailerOffset] = serviceKind & 0xff;
+    }
     console.log(`[FiveSDK] Deploy instruction encoded:`, {
         discriminator: result[0],
         lengthBytes: Array.from(new Uint8Array(lengthBuffer)),
@@ -1110,7 +1175,8 @@ function encodeDeployInstruction(bytecode, permissions = 0, metadata = new Uint8
         metadataLength: metadata.length,
         bytecodeLength: bytecode.length,
         totalInstructionLength: result.length,
-        expectedFormat: `[8, ${bytecode.length}_as_u32le, 0x${permissions.toString(16).padStart(2, '0')}, ${metadata.length}_as_u32le, metadata_bytes, bytecode_bytes, optional(shard,bump)]`,
+        serviceKind,
+        expectedFormat: `[8, ${bytecode.length}_as_u32le, 0x${permissions.toString(16).padStart(2, '0')}, ${metadata.length}_as_u32le, metadata_bytes, bytecode_bytes, optional(shard,bump), optional(service_kind)]`,
         instructionHex: Buffer.from(result).toString("hex").substring(0, 20) + "...",
     });
     return result;

package/dist/program/FiveProgram.d.ts

@@ -21,6 +21,7 @@ import type { ScriptABI, FunctionDefinition, AccountFetcher } from '../metadata/
 import type { Provider } from '../types.js';
 import { FunctionBuilder } from './FunctionBuilder.js';
 import { ProgramAccount } from './ProgramAccount.js';
+import type { SessionManager } from './SessionManager.js';
 export interface FiveProgramOptions {
     /** Enable debug logging */
     debug?: boolean;
@@ -34,6 +35,13 @@ export interface FiveProgramOptions {
     feeReceiverAccount?: string;
     /** Wallet/Network Provider for RPC calls */
     provider?: Provider;
+    /** Optional session helper for delegated signer flows */
+    session?: {
+        manager: SessionManager;
+        mode?: 'auto' | 'force-direct' | 'force-session';
+        sessionAccountByFunction?: Record<string, string>;
+        delegateAccountByFunction?: Record<string, string>;
+    };
 }
 /**
  * FiveProgram represents a deployed Five script with its ABI
@@ -109,6 +117,10 @@ export declare class FiveProgram {
      * Get Five VM Program ID with consistent resolver precedence
      */
     getFiveVMProgramId(): string;
+    /**
+     * Return a program instance that auto-applies session account/delegate mapping.
+     */
+    withSession(config: NonNullable<FiveProgramOptions['session']>): FiveProgram;
     /**
      * Derive a Program Derived Address (PDA)
      *

package/dist/program/FiveProgram.js

@@ -210,6 +210,18 @@ export class FiveProgram {
     getFiveVMProgramId() {
         return ProgramIdResolver.resolve(this.options.fiveVMProgramId);
     }
+    /**
+     * Return a program instance that auto-applies session account/delegate mapping.
+     */
+    withSession(config) {
+        return new FiveProgram(this.scriptAccount, this.abi, {
+            ...this.options,
+            session: {
+                mode: 'auto',
+                ...config,
+            },
+        });
+    }
     /**
      * Derive a Program Derived Address (PDA)
      *

package/dist/program/FunctionBuilder.d.ts

@@ -77,6 +77,8 @@ export declare class FunctionBuilder {
         skipPreflight?: boolean;
         computeUnits?: number;
     }): Promise<string>;
+    private applySessionDefaults;
+    private resolveSessionSigner;
     /**
      * Validate that all required parameters are provided
      * @throws Error if any required parameter is missing

package/dist/program/FunctionBuilder.js

@@ -79,6 +79,8 @@ export class FunctionBuilder {
      */
     async instruction() {
         // Validate parameters later, after auto-injection
+        // Optional session auto-wiring.
+        this.applySessionDefaults();
         // Resolve system accounts (auto-inject when needed)
         const resolver = new AccountResolver(this.options);
         const resolvedSystemAccounts = resolver.resolveSystemAccounts(this.functionDef, this.accountsMap);
@@ -156,11 +158,52 @@ export class FunctionBuilder {
         }
         const tx = await this.transaction({ computeUnits: options.computeUnits });
         // Send
-        const signers = options.signers || [];
+        const signers = [...(options.signers || [])];
+        const sessionSigner = this.resolveSessionSigner();
+        if (sessionSigner) {
+            signers.push(sessionSigner);
+        }
         return await provider.sendAndConfirm(tx, signers, {
             skipPreflight: options.skipPreflight
         });
     }
+    applySessionDefaults() {
+        const session = this.options.session;
+        if (session?.mode === 'force-direct') {
+            return;
+        }
+        const functionName = this.functionDef.name;
+        const sessionAddress = session?.sessionAccountByFunction?.[functionName];
+        const authorityAddress = this.accountsMap.get('owner') || this.accountsMap.get('authority');
+        for (const param of this.functionDef.parameters) {
+            if (!param.is_account)
+                continue;
+            const attrs = param.attributes || [];
+            const isImplicit = param.implicit === true || param.source === 'compiler';
+            const isLegacyInjectedSessionParam = param.name === '__session';
+            if ((attrs.includes('session') || isImplicit || param.name === '__session') &&
+                sessionAddress &&
+                !this.accountsMap.has(param.name)) {
+                this.accountsMap.set(param.name, sessionAddress);
+            }
+            // Direct-owner fallback for compiler-injected implicit session wiring:
+            // if no session manager config is present, alias hidden session/delegate
+            // accounts to owner/authority so @session can take the direct-owner path.
+            if ((isImplicit || isLegacyInjectedSessionParam) && !this.accountsMap.has(param.name) && authorityAddress) {
+                if (isLegacyInjectedSessionParam) {
+                    this.accountsMap.set(param.name, authorityAddress);
+                }
+            }
+        }
+    }
+    resolveSessionSigner() {
+        const session = this.options.session;
+        if (!session || session.mode === 'force-direct') {
+            return undefined;
+        }
+        const maybeSigner = session.manager?.delegateSigner;
+        return maybeSigner;
+    }
     /**
      * Validate that all required parameters are provided
      * @throws Error if any required parameter is missing
@@ -169,6 +212,13 @@ export class FunctionBuilder {
         for (const param of this.functionDef.parameters) {
             if (param.is_account) {
                 if (!this.accountsMap.has(param.name)) {
+                    const isImplicit = param.implicit === true ||
+                        param.source === 'compiler' ||
+                        param.name === '__session';
+                    if (isImplicit) {
+                        throw new Error(`Missing implicit account '${param.name}' for function '${this.functionDef.name}'. ` +
+                            `Provide it via .accounts({ ${param.name}: ... }) or configure program.withSession(...) for auto-wiring.`);
+                    }
                     throw new Error(`Missing required account '${param.name}' for function '${this.functionDef.name}'`);
                 }
             }

package/dist/program/SessionManager.d.ts

@@ -0,0 +1,61 @@
+import { FiveProgram } from './FiveProgram.js';
+export interface SessionScope {
+    functions: string[];
+    ttlSlots?: number;
+    bindAccount?: string;
+    nonce?: string;
+}
+export interface SessionCreateParams {
+    authority: string;
+    delegate: string;
+    targetProgram: string;
+    expiresAtSlot: number;
+    scopeHash: string;
+    bindAccount?: string;
+    nonce?: string;
+    payer?: string;
+}
+export interface SessionRecord {
+    sessionAddress: string;
+    authority: string;
+    delegate: string;
+    targetProgram: string;
+    expiresAtSlot: number;
+}
+export interface CanonicalSessionService {
+    cluster: 'localnet' | 'devnet' | 'mainnet';
+    scriptAccount: string;
+    codeHash: string;
+    version: number;
+    status: 'active' | 'disabled';
+}
+export interface SessionManagerOptions {
+    identity?: CanonicalSessionService;
+    enforceCanonical?: boolean;
+    allowUnsafeOverride?: boolean;
+}
+/**
+ * Lightweight helper around a deployed session-manager script.
+ * Uses normal Five execute flow; no VM opcode/runtime changes required.
+ */
+export declare class SessionManager {
+    readonly managerProgram: FiveProgram;
+    readonly defaultTtlSlots: number;
+    readonly identity: CanonicalSessionService;
+    private readonly enforceCanonical;
+    private readonly allowUnsafeOverride;
+    constructor(managerProgram: FiveProgram, defaultTtlSlots?: number, // ~20m on Solana-like slot timings
+    options?: SessionManagerOptions);
+    static resolveCanonicalIdentity(input?: {
+        cluster?: 'localnet' | 'devnet' | 'mainnet';
+        vmProgramId?: string;
+        scriptAccount?: string;
+        codeHash?: string;
+        status?: 'active' | 'disabled';
+        version?: number;
+    }): CanonicalSessionService;
+    static scopeHashForFunctions(functions: string[]): string;
+    deriveSessionAddress(authority: string, delegate: string, targetProgram: string): Promise<string>;
+    buildCreateSessionInstruction(params: SessionCreateParams): Promise<import("../types.js").SerializedInstruction>;
+    buildRevokeSessionInstruction(authority: string, delegate: string, targetProgram: string, payer?: string): Promise<import("../types.js").SerializedInstruction>;
+}

package/dist/program/SessionManager.js

@@ -0,0 +1,97 @@
+import { PublicKey } from '@solana/web3.js';
+/**
+ * Lightweight helper around a deployed session-manager script.
+ * Uses normal Five execute flow; no VM opcode/runtime changes required.
+ */
+export class SessionManager {
+    constructor(managerProgram, defaultTtlSlots = 3000, // ~20m on Solana-like slot timings
+    options = {}) {
+        this.managerProgram = managerProgram;
+        this.defaultTtlSlots = defaultTtlSlots;
+        this.identity =
+            options.identity ||
+                SessionManager.resolveCanonicalIdentity({
+                    vmProgramId: this.managerProgram.getFiveVMProgramId(),
+                });
+        this.allowUnsafeOverride = options.allowUnsafeOverride ?? false;
+        const strictByDefault = this.identity.cluster === 'mainnet';
+        this.enforceCanonical = options.enforceCanonical ?? strictByDefault;
+        if (this.identity.cluster === 'mainnet' &&
+            options.enforceCanonical === false &&
+            !this.allowUnsafeOverride) {
+            throw new Error('Disabling canonical session manager on mainnet requires allowUnsafeOverride');
+        }
+        if (this.enforceCanonical && this.identity.status !== 'active') {
+            throw new Error('Canonical session service is disabled for current cluster');
+        }
+        const hasPinnedScript = this.identity.scriptAccount !== '11111111111111111111111111111111';
+        if (this.enforceCanonical &&
+            hasPinnedScript &&
+            this.managerProgram.getScriptAccount() !== this.identity.scriptAccount) {
+            throw new Error('SessionManager program does not match canonical session_v1 service');
+        }
+    }
+    static resolveCanonicalIdentity(input = {}) {
+        const vmProgramId = input.vmProgramId || process.env.FIVE_PROGRAM_ID;
+        if (!vmProgramId) {
+            throw new Error('SessionManager canonical identity requires vmProgramId or FIVE_PROGRAM_ID');
+        }
+        const vmProgram = new PublicKey(vmProgramId);
+        const [scriptPda] = PublicKey.findProgramAddressSync([Buffer.from('session_v1', 'utf-8')], vmProgram);
+        const cluster = input.cluster || (process.env.FIVE_VM_CLUSTER || 'localnet');
+        return {
+            cluster,
+            scriptAccount: input.scriptAccount || scriptPda.toBase58(),
+            codeHash: input.codeHash || '11111111111111111111111111111111',
+            version: input.version ?? 1,
+            status: input.status || 'active',
+        };
+    }
+    static scopeHashForFunctions(functions) {
+        const sorted = [...functions].sort();
+        // Stable v1 hash seed; caller may replace with stronger domain-specific hashing if desired.
+        let acc = 0n;
+        for (const ch of sorted.join('|')) {
+            acc = (acc * 131n + BigInt(ch.charCodeAt(0))) & ((1n << 256n) - 1n);
+        }
+        return '0x' + acc.toString(16).padStart(64, '0');
+    }
+    async deriveSessionAddress(authority, delegate, targetProgram) {
+        const [pda] = await this.managerProgram.findAddress(['session', authority, delegate, targetProgram], this.managerProgram.getFiveVMProgramId());
+        return pda;
+    }
+    async buildCreateSessionInstruction(params) {
+        const sessionAddress = await this.deriveSessionAddress(params.authority, params.delegate, params.targetProgram);
+        const builder = this.managerProgram
+            .function('create_session')
+            .accounts({
+            session: sessionAddress,
+            authority: params.authority,
+            delegate: params.delegate,
+        })
+            .args({
+            target_program: params.targetProgram,
+            expires_at_slot: params.expiresAtSlot,
+            scope_hash: params.scopeHash,
+            bind_account: params.bindAccount || '11111111111111111111111111111111',
+            nonce: params.nonce || '0x00',
+        });
+        if (params.payer) {
+            builder.payer(params.payer);
+        }
+        return builder.instruction();
+    }
+    async buildRevokeSessionInstruction(authority, delegate, targetProgram, payer) {
+        const sessionAddress = await this.deriveSessionAddress(authority, delegate, targetProgram);
+        const builder = this.managerProgram
+            .function('revoke_session')
+            .accounts({
+            session: sessionAddress,
+            authority,
+        });
+        if (payer) {
+            builder.payer(payer);
+        }
+        return builder.instruction();
+    }
+}

package/dist/program/index.d.ts

@@ -22,3 +22,9 @@ export { AccountResolver } from './AccountResolver.js';
 export type { ResolvedSystemAccounts } from './AccountResolver.js';
 export { TypeGenerator } from './TypeGenerator.js';
 export type { TypeGeneratorOptions } from './TypeGenerator.js';
+export * from './FiveProgram.js';
+export * from './FunctionBuilder.js';
+export * from './ProgramAccount.js';
+export * from './TypeGenerator.js';
+export * from './AccountResolver.js';
+export * from './SessionManager.js';

package/dist/program/index.js

@@ -19,3 +19,9 @@ export { FiveProgram } from './FiveProgram.js';
 export { FunctionBuilder } from './FunctionBuilder.js';
 export { AccountResolver } from './AccountResolver.js';
 export { TypeGenerator } from './TypeGenerator.js';
+export * from './FiveProgram.js';
+export * from './FunctionBuilder.js';
+export * from './ProgramAccount.js';
+export * from './TypeGenerator.js';
+export * from './AccountResolver.js';
+export * from './SessionManager.js';

package/dist/testing/TestDiscovery.js

@@ -18,7 +18,10 @@ export class TestDiscovery {
             return testCases;
         }
         if (testCases && typeof testCases === 'object') {
-            return null;
+            return Object.entries(testCases).map(([name, value]) => ({
+                name,
+                ...(typeof value === 'object' && value !== null ? value : {}),
+            }));
         }
         return [];
     }
@@ -82,7 +85,7 @@ export class TestDiscovery {
                     }
                     for (const testCase of testCases) {
                         tests.push({
-                            name: testCase.name,
+                            name: testCase.name || testCase.function || testCase.id || 'unnamed_test',
                             path: file,
                             type: 'json-suite',
                             description: testCase.description,
@@ -116,7 +119,7 @@ export class TestDiscovery {
                     return [];
                 }
                 return testCases.map((testCase) => ({
-                    name: testCase.name,
+                    name: testCase.name || testCase.function || testCase.id || 'unnamed_test',
                     path: file,
                     type: 'json-suite',
                     description: testCase.description,

package/dist/testing/TestRunner.js

@@ -5,7 +5,7 @@
  * Five SDK usage. Provides comprehensive testing capabilities for Five VM scripts.
  */
 import { readFile } from 'fs/promises';
-import { basename } from 'path';
+import { basename, dirname, join } from 'path';
 import { FiveSDK } from '../FiveSDK.js';
 import { TestDiscovery } from './TestDiscovery.js';
 /**
@@ -203,6 +203,9 @@ export class FiveTestRunner {
         const suites = [];
         const byFile = new Map();
         const loadedJsonSuites = new Set();
+        const jsonSuitePaths = new Set(discovered
+            .filter((test) => test.type === 'json-suite')
+            .map((test) => test.path));
         for (const test of discovered) {
             if (test.type === 'json-suite') {
                 if (loadedJsonSuites.has(test.path)) {
@@ -211,13 +214,30 @@ export class FiveTestRunner {
                 try {
                     const content = await readFile(test.path, 'utf8');
                     const data = JSON.parse(content);
-                    const testCases = Array.isArray(data.tests || data.testCases)
-                        ? (data.tests || data.testCases)
-                        : [];
+                    const rawCases = data.tests || data.testCases || [];
+                    const testCases = Array.isArray(rawCases)
+                        ? rawCases
+                        : Object.entries(rawCases).map(([name, value]) => ({
+                            name,
+                            ...(typeof value === 'object' && value !== null ? value : {}),
+                        }));
+                    const inferredSource = data.source
+                        ? join(dirname(test.path), data.source)
+                        : test.path.replace(/\.test\.json$/i, '.test.v');
+                    const defaultSource = inferredSource;
+                    const normalizedCases = testCases.map((testCase, idx) => {
+                        const name = testCase.name || testCase.function || testCase.id || `test_${idx}`;
+                        return {
+                            ...testCase,
+                            name,
+                            source: testCase.source || defaultSource,
+                            function: testCase.function || name,
+                        };
+                    });
                     suites.push({
                         name: data.name || basename(test.path, '.test.json'),
                         description: data.description,
-                        testCases
+                        testCases: normalizedCases
                     });
                     loadedJsonSuites.add(test.path);
                 }
@@ -227,6 +247,12 @@ export class FiveTestRunner {
                 continue;
             }
             if (test.type === 'v-source' && test.source) {
+                const jsonPath = test.path.endsWith('.test.v')
+                    ? test.path.replace(/\.test\.v$/i, '.test.json')
+                    : test.path.replace(/\.v$/i, '.test.json');
+                if (jsonSuitePaths.has(jsonPath)) {
+                    continue;
+                }
                 const cases = byFile.get(test.path) || [];
                 cases.push({
                     name: test.name,

package/dist/types.d.ts

@@ -269,6 +269,7 @@ export interface DeploymentOptions {
         }>;
     };
     namespace?: string;
+    service?: 'session_v1';
 }
 export interface FeeInformation {
     feeBps: number;

package/dist/utils/abi.d.ts

@@ -8,6 +8,8 @@ export interface NormalizedABIFunction {
         optional?: boolean;
         is_account?: boolean;
         isAccount?: boolean;
+        implicit?: boolean;
+        source?: 'authored' | 'compiler';
         attributes?: string[];
     }>;
     returnType?: string;

package/dist/utils/abi.js

@@ -21,6 +21,8 @@ export function normalizeAbiFunctions(abiFunctions) {
             optional: param.optional ?? false,
             is_account: param.is_account ?? param.isAccount ?? false,
             isAccount: param.isAccount ?? param.is_account ?? false,
+            implicit: param.implicit ?? false,
+            source: param.source ?? 'authored',
             attributes: Array.isArray(param.attributes) ? [...param.attributes] : [],
         }));
         const existingParameterNames = new Set(normalizedParameters.map((param) => param.name));
@@ -39,6 +41,8 @@ export function normalizeAbiFunctions(abiFunctions) {
                     optional: false,
                     is_account: true,
                     isAccount: true,
+                    implicit: false,
+                    source: 'authored',
                     attributes,
                 };
             })

package/dist/wasm/loader.js

@@ -89,17 +89,23 @@ export async function getWasmModule() {
             // Universal initialization (Browser/Node) if default export is init function
             if (mod && typeof mod.default === 'function') {
                 try {
-                    await mod.default();
+                    const initialized = await mod.default();
+                    const normalizedInit = resolveEncoderModule(initialized);
+                    if (normalizedInit) {
+                        wasmModule = normalizedInit;
+                        return wasmModule;
+                    }
                 }
                 catch (initErr) {
                     tried.push({ path: candidate, error: initErr });
                 }
             }
-            if (mod) {
-                wasmModule = mod;
+            const normalized = resolveEncoderModule(mod);
+            if (normalized) {
+                wasmModule = normalized;
                 return wasmModule;
             }
-            tried.push({ path: candidate, error: 'Module import returned null/undefined' });
+            tried.push({ path: candidate, error: 'Module missing ParameterEncoder export' });
         }
         catch (e) {
             tried.push({ path: candidate, error: e });
@@ -110,3 +116,12 @@ export async function getWasmModule() {
         .join('\n');
     throw new Error(`Five VM WASM module not found or failed to load. Please ensure five-wasm is built.\nAttempts:\n${attempted}`);
 }
+const resolveEncoderModule = (mod) => {
+    if (!mod)
+        return null;
+    if (mod.ParameterEncoder)
+        return mod;
+    if (mod.default && mod.default.ParameterEncoder)
+        return mod.default;
+    return null;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@5ive-tech/sdk",
-  "version": "1.1.16",
+  "version": "1.1.18",
   "description": "Client-agnostic TypeScript SDK for Five VM scripts on Solana",
   "type": "module",
   "main": "dist/index.js",