@5ive-tech/sdk 1.1.21 → 1.1.22

package/dist/session/index.d.ts

@@ -9,21 +9,56 @@ export interface CreateSessionParams {
     authority: string;
     delegate: string;
     targetProgram: string;
+    sessionAccount?: string;
     expiresAtSlot: number;
     scopeHash: string;
     bindAccount?: string;
     nonce?: number;
     payer?: string;
+    rpcLabel?: string;
+    schemaPreference?: CreateSessionSchema | 'auto';
 }
 export interface RevokeSessionParams {
     authority: string;
     delegate: string;
     targetProgram: string;
     payer?: string;
+    rpcLabel?: string;
 }
 export interface CreateSessionCompatResult {
     signature: string;
-    schema: 'minimal';
+    schema: CreateSessionSchema;
+}
+export type CreateSessionSchema = 'legacy' | 'minimal';
+export interface SessionClientBuildContext {
+    operation: 'derive_session' | 'create_session' | 'revoke_session';
+    schema?: CreateSessionSchema;
+    managerScriptAccount: string;
+    vmProgramId: string;
+    sessionAddress?: string;
+    targetProgram?: string;
+    authority?: string;
+    delegate?: string;
+    rpcLabel?: string;
+}
+export declare class SessionClientBuildError extends Error {
+    readonly context: SessionClientBuildContext;
+    readonly cause?: unknown;
+    constructor(message: string, context: SessionClientBuildContext, cause?: unknown);
+}
+export interface BuildCreateSessionPlanOptions {
+    connection?: Connection;
+    payer?: PublicKey;
+    delegateMinLamports?: number;
+    delegateTopupLamports?: number;
+    rpcLabel?: string;
+}
+export interface CreateSessionPlan {
+    schema: CreateSessionSchema;
+    sessionAddress: string;
+    createSessionIx: TransactionInstruction;
+    createSessionAccountIx: TransactionInstruction | null;
+    topupDelegateIx: TransactionInstruction | null;
 }
 export declare function scopeHashForFunctions(functionNames: string[]): string;
 export declare function canonicalSessionManagerScriptAccount(vmProgramId: string): string;
@@ -36,9 +71,13 @@ export declare class SessionClient {
     });
     static scopeHashForFunctions(functionNames: string[]): string;
     static canonicalManagerScriptAccount(vmProgramId: string): string;
+    private buildError;
+    private createSessionSchemas;
     deriveSessionAddress(authority: string, delegate: string, targetProgram: string): Promise<string>;
+    private buildCreateSessionCore;
     createSessionIx(params: CreateSessionParams): Promise<TransactionInstruction>;
-    createSessionWithCompat(params: CreateSessionParams, send: (ix: TransactionInstruction, schema: 'minimal') => Promise<string>): Promise<CreateSessionCompatResult>;
+    buildCreateSessionPlan(params: CreateSessionParams, options?: BuildCreateSessionPlanOptions): Promise<CreateSessionPlan>;
+    createSessionWithCompat(params: CreateSessionParams, send: (ix: TransactionInstruction, schema: CreateSessionSchema) => Promise<string>): Promise<CreateSessionCompatResult>;
     revokeSessionIx(params: RevokeSessionParams): Promise<TransactionInstruction>;
     prepareSessionAccountTx(input: {
         connection: Connection;

package/dist/session/index.js

@@ -1,5 +1,13 @@
 import { PublicKey, SystemProgram, TransactionInstruction } from '@solana/web3.js';
 import { FiveProgram } from '../program/FiveProgram.js';
+export class SessionClientBuildError extends Error {
+    constructor(message, context, cause) {
+        super(message);
+        this.name = 'SessionClientBuildError';
+        this.context = context;
+        this.cause = cause;
+    }
+}
 const SYSTEM_PROGRAM = '11111111111111111111111111111111';
 const SESSION_MANAGER_ABI_MINIMAL = {
     name: 'SessionManager',
@@ -36,6 +44,45 @@ const SESSION_MANAGER_ABI_MINIMAL = {
         },
     ],
 };
+const SESSION_MANAGER_ABI_LEGACY = {
+    name: 'SessionManager',
+    functions: [
+        {
+            name: 'create_session',
+            index: 0,
+            parameters: [
+                { name: 'session', type: 'Account', is_account: true, attributes: ['mut'] },
+                { name: 'authority', type: 'Account', is_account: true, attributes: ['signer'] },
+                { name: 'delegate', type: 'Account', is_account: true, attributes: [] },
+                { name: 'target_program', type: 'pubkey', is_account: false, attributes: [] },
+                { name: 'expires_at_slot', type: 'u64', is_account: false, attributes: [] },
+                { name: 'scope_hash', type: 'u64', is_account: false, attributes: [] },
+                { name: 'bind_account', type: 'pubkey', is_account: false, attributes: [] },
+                { name: 'nonce', type: 'u64', is_account: false, attributes: [] },
+                { name: 'manager_script_account', type: 'pubkey', is_account: false, attributes: [] },
+                { name: 'manager_code_hash', type: 'pubkey', is_account: false, attributes: [] },
+                { name: 'manager_version', type: 'u8', is_account: false, attributes: [] },
+            ],
+            return_type: null,
+            visibility: 'public',
+            is_public: true,
+            bytecode_offset: 0,
+        },
+        {
+            name: 'revoke_session',
+            index: 1,
+            parameters: [
+                { name: 'session', type: 'Account', is_account: true, attributes: ['mut'] },
+                { name: 'authority', type: 'Account', is_account: true, attributes: ['signer'] },
+            ],
+            return_type: null,
+            visibility: 'public',
+            is_public: true,
+            bytecode_offset: 0,
+        },
+    ],
+};
+const DEFAULT_CREATE_SESSION_SCHEMA = 'legacy';
 export function scopeHashForFunctions(functionNames) {
     const sorted = [...functionNames].sort();
     let acc = 0n;
@@ -61,67 +108,222 @@ export class SessionClient {
     static canonicalManagerScriptAccount(vmProgramId) {
         return canonicalSessionManagerScriptAccount(vmProgramId);
     }
+    buildError(message, context, cause) {
+        return new SessionClientBuildError(message, context, cause);
+    }
+    createSessionSchemas(preference) {
+        if (preference === 'minimal')
+            return ['minimal'];
+        if (preference === 'legacy')
+            return ['legacy'];
+        return [DEFAULT_CREATE_SESSION_SCHEMA, 'minimal'].filter((schema, index, all) => all.indexOf(schema) === index);
+    }
     async deriveSessionAddress(authority, delegate, targetProgram) {
-        const [session] = await FiveProgram.fromABI(this.managerScriptAccount, SESSION_MANAGER_ABI_MINIMAL, {
-            fiveVMProgramId: this.vmProgramId,
-        }).findAddress(['session', authority, delegate, targetProgram], this.vmProgramId);
-        return session;
+        try {
+            const [session] = await FiveProgram.fromABI(this.managerScriptAccount, SESSION_MANAGER_ABI_MINIMAL, {
+                fiveVMProgramId: this.vmProgramId,
+            }).findAddress(['session', authority, delegate, targetProgram], this.vmProgramId);
+            return session;
+        }
+        catch (error) {
+            throw this.buildError('Failed to derive canonical session address', {
+                operation: 'derive_session',
+                managerScriptAccount: this.managerScriptAccount,
+                vmProgramId: this.vmProgramId,
+                authority,
+                delegate,
+                targetProgram,
+            }, error);
+        }
     }
-    async createSessionIx(params) {
-        const session = await this.deriveSessionAddress(params.authority, params.delegate, params.targetProgram);
-        const program = FiveProgram.fromABI(this.managerScriptAccount, SESSION_MANAGER_ABI_MINIMAL, {
-            fiveVMProgramId: this.vmProgramId,
-        });
-        const argMap = {
-            target_program: params.targetProgram,
-            expires_at_slot: params.expiresAtSlot,
-            scope_hash: params.scopeHash,
-            bind_account: params.bindAccount || SYSTEM_PROGRAM,
-            nonce: params.nonce ?? 0,
-        };
-        const builder = program
-            .function('create_session')
-            .accounts({
-            session,
+    async buildCreateSessionCore(params, schema) {
+        const sessionAddress = await this.deriveSessionAddress(params.authority, params.delegate, params.targetProgram);
+        const resolvedSessionAddress = schema === 'legacy' && params.sessionAccount
+            ? params.sessionAccount
+            : sessionAddress;
+        const contextBase = {
+            operation: 'create_session',
+            schema,
+            managerScriptAccount: this.managerScriptAccount,
+            vmProgramId: this.vmProgramId,
+            sessionAddress: resolvedSessionAddress,
             authority: params.authority,
             delegate: params.delegate,
-        })
-            .args(argMap);
-        builder.payer(params.payer || params.authority);
-        const encoded = await builder.instruction();
-        return new TransactionInstruction({
-            programId: new PublicKey(encoded.programId),
-            keys: encoded.keys.map((k) => ({
-                pubkey: new PublicKey(k.pubkey),
-                isSigner: k.isSigner,
-                isWritable: k.isWritable,
-            })),
-            data: Buffer.from(encoded.data, 'base64'),
-        });
+            targetProgram: params.targetProgram,
+            rpcLabel: params.rpcLabel,
+        };
+        try {
+            const program = FiveProgram.fromABI(this.managerScriptAccount, schema === 'legacy' ? SESSION_MANAGER_ABI_LEGACY : SESSION_MANAGER_ABI_MINIMAL, {
+                fiveVMProgramId: this.vmProgramId,
+            });
+            const argMap = {
+                target_program: params.targetProgram,
+                expires_at_slot: params.expiresAtSlot,
+                scope_hash: params.scopeHash,
+                bind_account: params.bindAccount || SYSTEM_PROGRAM,
+                nonce: params.nonce ?? 0,
+            };
+            if (schema === 'legacy') {
+                argMap.manager_script_account = this.managerScriptAccount;
+                argMap.manager_code_hash = SYSTEM_PROGRAM;
+                argMap.manager_version = 1;
+            }
+            const builder = program
+                .function('create_session')
+                .accounts({
+                session: resolvedSessionAddress,
+                authority: params.authority,
+                delegate: params.delegate,
+            })
+                .args(argMap);
+            builder.payer(params.payer || params.authority);
+            const encoded = await builder.instruction();
+            return {
+                schema,
+                sessionAddress: resolvedSessionAddress,
+                instruction: new TransactionInstruction({
+                    programId: new PublicKey(encoded.programId),
+                    keys: encoded.keys.map((k) => ({
+                        pubkey: new PublicKey(k.pubkey),
+                        isSigner: k.isSigner,
+                        isWritable: k.isWritable,
+                    })),
+                    data: Buffer.from(encoded.data, 'base64'),
+                }),
+            };
+        }
+        catch (error) {
+            throw this.buildError('Failed to build create_session instruction', contextBase, error);
+        }
+    }
+    async createSessionIx(params) {
+        const schema = this.createSessionSchemas(params.schemaPreference)[0];
+        const built = await this.buildCreateSessionCore(params, schema);
+        return built.instruction;
+    }
+    async buildCreateSessionPlan(params, options = {}) {
+        const schema = this.createSessionSchemas(params.schemaPreference)[0];
+        const built = await this.buildCreateSessionCore(params, schema);
+        let createSessionAccountIx = null;
+        let topupDelegateIx = null;
+        if (options.connection && options.payer && schema === 'legacy' && params.sessionAccount) {
+            try {
+                const prepared = await this.prepareSessionAccountTx({
+                    connection: options.connection,
+                    payer: options.payer,
+                    sessionAccount: new PublicKey(params.sessionAccount),
+                    delegate: new PublicKey(params.delegate),
+                    delegateMinLamports: options.delegateMinLamports,
+                    delegateTopupLamports: options.delegateTopupLamports,
+                });
+                createSessionAccountIx = prepared.createIx;
+                topupDelegateIx = prepared.topupIx;
+            }
+            catch (error) {
+                throw this.buildError('Failed while building session account setup instructions for create_session', {
+                    operation: 'create_session',
+                    schema,
+                    managerScriptAccount: this.managerScriptAccount,
+                    vmProgramId: this.vmProgramId,
+                    sessionAddress: built.sessionAddress,
+                    authority: params.authority,
+                    delegate: params.delegate,
+                    targetProgram: params.targetProgram,
+                    rpcLabel: options.rpcLabel || params.rpcLabel,
+                }, error);
+            }
+        }
+        else if (options.connection &&
+            options.payer &&
+            options.delegateMinLamports &&
+            options.delegateTopupLamports) {
+            try {
+                const delegateBalance = await options.connection.getBalance(new PublicKey(params.delegate), 'confirmed');
+                if (delegateBalance < options.delegateMinLamports) {
+                    topupDelegateIx = SystemProgram.transfer({
+                        fromPubkey: options.payer,
+                        toPubkey: new PublicKey(params.delegate),
+                        lamports: options.delegateTopupLamports,
+                    });
+                }
+            }
+            catch (error) {
+                throw this.buildError('Failed while building delegate funding instruction for create_session', {
+                    operation: 'create_session',
+                    schema,
+                    managerScriptAccount: this.managerScriptAccount,
+                    vmProgramId: this.vmProgramId,
+                    sessionAddress: built.sessionAddress,
+                    authority: params.authority,
+                    delegate: params.delegate,
+                    targetProgram: params.targetProgram,
+                    rpcLabel: options.rpcLabel || params.rpcLabel,
+                }, error);
+            }
+        }
+        return {
+            schema,
+            sessionAddress: built.sessionAddress,
+            createSessionIx: built.instruction,
+            createSessionAccountIx,
+            topupDelegateIx,
+        };
     }
     async createSessionWithCompat(params, send) {
-        const minimalIx = await this.createSessionIx(params);
-        return { signature: await send(minimalIx, 'minimal'), schema: 'minimal' };
+        const attempts = this.createSessionSchemas(params.schemaPreference);
+        let lastError = null;
+        for (const schema of attempts) {
+            try {
+                const built = await this.buildCreateSessionCore(params, schema);
+                return { signature: await send(built.instruction, schema), schema };
+            }
+            catch (error) {
+                lastError = error;
+            }
+        }
+        throw this.buildError('All create_session schema attempts failed', {
+            operation: 'create_session',
+            managerScriptAccount: this.managerScriptAccount,
+            vmProgramId: this.vmProgramId,
+            authority: params.authority,
+            delegate: params.delegate,
+            targetProgram: params.targetProgram,
+            rpcLabel: params.rpcLabel,
+        }, lastError);
     }
     async revokeSessionIx(params) {
         const session = await this.deriveSessionAddress(params.authority, params.delegate, params.targetProgram);
-        const program = FiveProgram.fromABI(this.managerScriptAccount, SESSION_MANAGER_ABI_MINIMAL, {
-            fiveVMProgramId: this.vmProgramId,
-        });
-        const builder = program
-            .function('revoke_session')
-            .accounts({ session, authority: params.authority });
-        builder.payer(params.payer || params.authority);
-        const encoded = await builder.instruction();
-        return new TransactionInstruction({
-            programId: new PublicKey(encoded.programId),
-            keys: encoded.keys.map((k) => ({
-                pubkey: new PublicKey(k.pubkey),
-                isSigner: k.isSigner,
-                isWritable: k.isWritable,
-            })),
-            data: Buffer.from(encoded.data, 'base64'),
-        });
+        try {
+            const program = FiveProgram.fromABI(this.managerScriptAccount, SESSION_MANAGER_ABI_MINIMAL, {
+                fiveVMProgramId: this.vmProgramId,
+            });
+            const builder = program
+                .function('revoke_session')
+                .accounts({ session, authority: params.authority });
+            builder.payer(params.payer || params.authority);
+            const encoded = await builder.instruction();
+            return new TransactionInstruction({
+                programId: new PublicKey(encoded.programId),
+                keys: encoded.keys.map((k) => ({
+                    pubkey: new PublicKey(k.pubkey),
+                    isSigner: k.isSigner,
+                    isWritable: k.isWritable,
+                })),
+                data: Buffer.from(encoded.data, 'base64'),
+            });
+        }
+        catch (error) {
+            throw this.buildError('Failed to build revoke_session instruction', {
+                operation: 'revoke_session',
+                managerScriptAccount: this.managerScriptAccount,
+                vmProgramId: this.vmProgramId,
+                sessionAddress: session,
+                authority: params.authority,
+                delegate: params.delegate,
+                targetProgram: params.targetProgram,
+                rpcLabel: params.rpcLabel,
+            }, error);
+        }
     }
     async prepareSessionAccountTx(input) {
         const sessionSpace = input.sessionSpace ?? 256;

package/package.json

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