@oobe-protocol-labs/sap-mcp-server 0.9.1 → 0.9.3

package/dist/tools/transaction-tools.js

@@ -2,12 +2,15 @@
  * @module transaction-tools
  * @description MCP tools for decoding, previewing, signing, and submitting Solana transactions.
  */
-import { LAMPORTS_PER_SOL, SystemProgram, Transaction, VersionedTransaction } from '@solana/web3.js';
+import { LAMPORTS_PER_SOL, PublicKey, SystemProgram, Transaction, TransactionInstruction, VersionedTransaction } from '@solana/web3.js';
 import bs58 from 'bs58';
 import { registerTool } from '../adapters/mcp/sdk-compat.js';
 import { createTextResponse } from '../adapters/mcp/tool-response.js';
 const SYSTEM_TRANSFER_INSTRUCTION_INDEX = 2;
 const SYSTEM_TRANSFER_LAYOUT_BYTES = 12;
+const DEFAULT_CONFIRMATION_TIMEOUT_MS = 90_000;
+const MAX_CONFIRMATION_TIMEOUT_MS = 180_000;
+const DEFAULT_TX_SUBMIT_RELAY_URL = 'https://mcp.sap.oobeprotocol.ai/tx/submit';
 /**
  * @name decodeInputBytes
  * @description Decodes base64/base58 transaction text into raw bytes.
@@ -15,7 +18,7 @@ const SYSTEM_TRANSFER_LAYOUT_BYTES = 12;
  * @param encoding - Encoding used by the incoming transaction.
  * @returns Raw serialized transaction bytes.
  */
-function decodeInputBytes(value, encoding = 'base64') {
+export function decodeInputBytes(value, encoding = 'base64') {
     if (encoding === 'base64') {
         return Buffer.from(value, 'base64');
     }
@@ -31,7 +34,7 @@ function decodeInputBytes(value, encoding = 'base64') {
  * @param encoding - Encoding used by the incoming transaction.
  * @returns Deserialized Solana transaction.
  */
-function deserializeTransaction(value, encoding) {
+export function deserializeTransaction(value, encoding) {
     const bytes = decodeInputBytes(value, encoding);
     try {
         return VersionedTransaction.deserialize(bytes);
@@ -105,7 +108,7 @@ function estimateNativeTransfer(transaction, signer) {
  * @param transaction - Deserialized transaction to check.
  * @param signer - Optional signer filter for signing checks.
  */
-async function assertTransactionPolicy(context, transaction, signer) {
+export async function assertTransactionPolicy(context, transaction, signer) {
     const nativeTransfer = estimateNativeTransfer(transaction, signer);
     if (nativeTransfer.sol <= 0) {
         return nativeTransfer;
@@ -125,7 +128,7 @@ async function assertTransactionPolicy(context, transaction, signer) {
  * @param transaction - Transaction to serialize.
  * @returns Base64 encoded transaction bytes.
  */
-function serializeTransaction(transaction) {
+export function serializeTransaction(transaction) {
     if (transaction instanceof VersionedTransaction) {
         return Buffer.from(transaction.serialize()).toString('base64');
     }
@@ -134,13 +137,169 @@ function serializeTransaction(transaction) {
         verifySignatures: false,
     }).toString('base64');
 }
+/**
+ * @name submitSignedTransactionWithLifecycle
+ * @description Submits a signed transaction through the configured local RPC and waits for a bounded confirmation result.
+ * @param context - Shared MCP runtime context.
+ * @param input - Signed transaction plus send/confirmation options.
+ * @returns Submission lifecycle result with retry guidance.
+ */
+export async function submitSignedTransactionWithLifecycle(context, input) {
+    const signedTransaction = input.signedTransaction;
+    const encoding = input.encoding ?? 'base64';
+    const rawTransaction = decodeInputBytes(signedTransaction, encoding);
+    await assertTransactionPolicy(context, deserializeTransaction(signedTransaction, encoding));
+    const signature = await context.connection.sendRawTransaction(rawTransaction, {
+        skipPreflight: input.skipPreflight,
+        maxRetries: input.maxRetries ?? context.config.maxRetries,
+    });
+    const confirmationTimeoutMs = boundConfirmationTimeout(input.confirmationTimeoutMs);
+    const desiredCommitment = input.commitment ?? 'confirmed';
+    const confirmation = await waitForSignatureStatus(context, signature, confirmationTimeoutMs, desiredCommitment);
+    return {
+        success: confirmation.success,
+        submitted: true,
+        signature,
+        confirmationStatus: confirmation.status,
+        retrySafe: confirmation.retrySafe,
+        ...(confirmation.slot === undefined ? {} : { slot: confirmation.slot }),
+        explorerUrl: `https://solscan.io/tx/${signature}`,
+        audit: {
+            intentId: input.intentId ?? `sap-tx-${Date.now()}`,
+            submittedVia: 'local-rpc',
+            confirmationTimeoutMs,
+            desiredCommitment,
+            retrySafe: confirmation.retrySafe,
+            rule: confirmation.success
+                ? 'The signed transaction was submitted and observed on-chain before returning success.'
+                : 'The signed transaction was submitted but did not reach the requested confirmation state before timeout; retry only when retrySafe is true and the user confirms.',
+        },
+    };
+}
+/**
+ * @name submitSignedTransactionViaRelay
+ * @description Submits a signed transaction to the hosted OOBE submit relay. The relay never signs; it only broadcasts and confirms already-signed bytes.
+ * @param input - Signed transaction plus send/confirmation options.
+ * @returns Relay lifecycle result with retry guidance.
+ */
+export async function submitSignedTransactionViaRelay(input) {
+    const relayUrl = input.submitRelayUrl ?? process.env.SAP_MCP_TX_SUBMIT_RELAY_URL ?? DEFAULT_TX_SUBMIT_RELAY_URL;
+    validateRelayUrl(relayUrl);
+    const response = await fetch(relayUrl, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+        },
+        body: JSON.stringify({
+            signedTransaction: input.signedTransaction,
+            encoding: input.encoding ?? 'base64',
+            skipPreflight: input.skipPreflight,
+            maxRetries: input.maxRetries,
+            confirmationTimeoutMs: input.confirmationTimeoutMs,
+            commitment: input.commitment,
+            intentId: input.intentId,
+        }),
+    });
+    const body = await response.json().catch(() => undefined);
+    if (!response.ok) {
+        const message = typeof body === 'object' && body && 'error' in body
+            ? String(body.error)
+            : `submit relay returned HTTP ${response.status}`;
+        throw new Error(message);
+    }
+    if (!isRelaySubmitResult(body)) {
+        throw new Error('submit relay returned an invalid transaction lifecycle response.');
+    }
+    return {
+        ...body,
+        audit: {
+            ...body.audit,
+            submittedVia: 'hosted-submit-relay',
+            relayUrl,
+            signerBoundary: 'local-signer-remote-submit-only',
+        },
+    };
+}
+async function waitForSignatureStatus(context, signature, timeoutMs, desiredCommitment) {
+    const startedAt = Date.now();
+    let lastStatus = 'missing';
+    let lastSlot;
+    while (Date.now() - startedAt < timeoutMs) {
+        const statuses = await context.connection.getSignatureStatuses([signature], { searchTransactionHistory: true });
+        const status = statuses.value[0];
+        if (status?.err) {
+            return {
+                success: false,
+                retrySafe: true,
+                status: 'failed',
+                ...(status.slot === undefined ? {} : { slot: status.slot }),
+            };
+        }
+        if (status) {
+            lastStatus = status.confirmationStatus ?? 'processed';
+            lastSlot = status.slot;
+            if (commitmentReached(lastStatus, desiredCommitment)) {
+                return {
+                    success: true,
+                    retrySafe: false,
+                    status: lastStatus,
+                    ...(lastSlot === undefined ? {} : { slot: lastSlot }),
+                };
+            }
+        }
+        await sleep(2_000);
+    }
+    return {
+        success: false,
+        retrySafe: lastStatus === 'missing',
+        status: lastStatus === 'missing' ? 'expired_or_not_landed' : lastStatus,
+        ...(lastSlot === undefined ? {} : { slot: lastSlot }),
+    };
+}
+function commitmentReached(current, desired) {
+    const rank = {
+        processed: 1,
+        confirmed: 2,
+        finalized: 3,
+    };
+    return (rank[current] ?? 0) >= rank[desired];
+}
+function boundConfirmationTimeout(value) {
+    if (!Number.isFinite(value)) {
+        return DEFAULT_CONFIRMATION_TIMEOUT_MS;
+    }
+    return Math.max(15_000, Math.min(Number(value), MAX_CONFIRMATION_TIMEOUT_MS));
+}
+function validateRelayUrl(value) {
+    const url = new URL(value);
+    if (url.protocol !== 'https:' && url.hostname !== '127.0.0.1' && url.hostname !== 'localhost') {
+        throw new Error('submitRelayUrl must use https, localhost, or 127.0.0.1.');
+    }
+}
+function isRelaySubmitResult(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const record = value;
+    return typeof record.success === 'boolean'
+        && record.submitted === true
+        && typeof record.signature === 'string'
+        && typeof record.confirmationStatus === 'string'
+        && typeof record.retrySafe === 'boolean'
+        && typeof record.explorerUrl === 'string'
+        && typeof record.audit === 'object';
+}
+async function sleep(ms) {
+    await new Promise(resolve => setTimeout(resolve, ms));
+}
 /**
  * @name describeTransaction
  * @description Builds a stable JSON preview from a Solana transaction.
  * @param transaction - Deserialized transaction.
  * @returns Transaction metadata safe to expose to MCP clients.
  */
-function describeTransaction(transaction, context) {
+export function describeTransaction(transaction, context) {
     const nativeTransfer = estimateNativeTransfer(transaction);
     const maxTxValueSol = context?.config.maxTxValueSol;
     const policyAllowed = context
@@ -185,6 +344,120 @@ function describeTransaction(transaction, context) {
         policyReason,
     };
 }
+/**
+ * @name finalizeTransactionWithLocalSigner
+ * @description Preview, sign, and optionally submit a transaction with the local SAP MCP signer.
+ * @param context - Shared MCP runtime context containing signer, policy, and RPC connection.
+ * @param input - Transaction finalization request.
+ * @returns Agent-readable finalization result without secret material.
+ */
+export async function finalizeTransactionWithLocalSigner(context, input) {
+    if (input.confirm !== true) {
+        throw new Error('confirm: true is required before the local SAP MCP signer can finalize a transaction.');
+    }
+    const transactionText = input.transaction ?? input.transactionBase64;
+    if (!transactionText) {
+        throw new Error('transaction or transactionBase64 is required.');
+    }
+    // Resolve signer: use signerProfile if provided, otherwise fall back to the
+    // active context signer. This eliminates the need to switch .active-profile
+    // manually — multiple profiles can coexist in the same session.
+    let signer = context.signer;
+    let signerProfileName;
+    if (input.signerProfile) {
+        const { loadProfileConfig } = await import('../config/profiles.js');
+        const { resolveSigner } = await import('../signer/signer-resolver.js');
+        const profileConfig = loadProfileConfig(input.signerProfile);
+        if (!profileConfig) {
+            throw new Error(`signerProfile "${input.signerProfile}" not found. ` +
+                `Available profiles can be listed with sap_profile_list (local mode) or by checking ~/.config/mcp-sap/config-*.json files. ` +
+                `If the hosted server is accountless, use the local sap_payments bridge to inspect profiles.`);
+        }
+        // FullConfig does not include monetization — merge with the active context
+        // config to provide the required SapMcpConfig shape for resolveSigner.
+        const mergedConfig = { ...context.config, ...profileConfig };
+        const signerResult = await resolveSigner(mergedConfig);
+        if (!signerResult.signer) {
+            throw new Error(`signerProfile "${input.signerProfile}" has no signer configured. ` +
+                `Ensure the profile config has a walletPath or externalSignerUrl set. ` +
+                `Run: sap-mcp-config wizard --profile ${input.signerProfile} to configure.`);
+        }
+        signer = signerResult.signer;
+        signerProfileName = input.signerProfile;
+    }
+    if (!signer) {
+        throw new Error('No local signer configured. Run the SAP MCP wizard full setup or repair the local sap_payments bridge, then restart the agent runtime.');
+    }
+    const encoding = input.encoding ?? 'base64';
+    const transaction = deserializeTransaction(transactionText, encoding);
+    const preview = describeTransaction(transaction, context);
+    const nativeTransfer = await assertTransactionPolicy(context, transaction, signer.publicKey);
+    const signedTransaction = await signer.signTransaction(transaction);
+    const signedTransactionBase64 = serializeTransaction(signedTransaction);
+    const result = {
+        success: true,
+        action: input.submit === true ? 'preview-sign-submit' : 'preview-sign',
+        submitted: false,
+        signerPublicKey: signer.publicKey.toBase58(),
+        signerProfile: signerProfileName ?? null,
+        nativeTransferSol: nativeTransfer.sol,
+        preview: {
+            ...preview,
+            canSign: true,
+            signer: signer.publicKey.toBase58(),
+            signerProfile: signerProfileName ?? null,
+        },
+        signedTransaction: signedTransactionBase64,
+        encoding: 'base64',
+        audit: {
+            intentId: input.intentId ?? `sap-tx-${Date.now()}`,
+            profileMode: context.config.mode,
+            signerProfile: signerProfileName ?? null,
+            signerPublicKey: signer.publicKey.toBase58(),
+            previewed: true,
+            signedLocally: true,
+            submitted: false,
+            secretMaterial: 'keypair-bytes-never-returned',
+            rule: 'Finalized by SAP MCP local signer. No temporary scripts, raw keypair reads, or exported secret bytes were used.',
+        },
+    };
+    if (input.submit === true) {
+        const submitResult = input.submitViaRelay === false
+            ? await submitSignedTransactionWithLifecycle(context, {
+                signedTransaction: signedTransactionBase64,
+                encoding: 'base64',
+                skipPreflight: input.skipPreflight,
+                maxRetries: input.maxRetries,
+                confirmationTimeoutMs: input.confirmationTimeoutMs,
+                commitment: input.commitment,
+                intentId: input.intentId,
+            })
+            : await submitSignedTransactionViaRelay({
+                signedTransaction: signedTransactionBase64,
+                encoding: 'base64',
+                skipPreflight: input.skipPreflight,
+                maxRetries: input.maxRetries,
+                confirmationTimeoutMs: input.confirmationTimeoutMs,
+                commitment: input.commitment,
+                submitRelayUrl: input.submitRelayUrl,
+                intentId: input.intentId,
+            });
+        result.success = submitResult.success;
+        result.submitted = submitResult.submitted;
+        result.signature = submitResult.signature;
+        result.confirmationStatus = submitResult.confirmationStatus;
+        result.retrySafe = submitResult.retrySafe;
+        result.explorerUrl = submitResult.explorerUrl;
+        result.audit = {
+            ...result.audit,
+            ...submitResult.audit,
+            submitted: submitResult.submitted,
+            signature: submitResult.signature,
+            transactionLanded: submitResult.success,
+        };
+    }
+    return result;
+}
 /**
  * @name registerTransactionTools
  * @description Registers real transaction decode, preview, signing, and submission tools.
@@ -194,7 +467,7 @@ function describeTransaction(transaction, context) {
 export function registerTransactionTools(server, context) {
     registerTool(server, 'sap_decode_transaction', {
         title: 'Decode Transaction',
-        description: 'Decode a serialized Solana transaction and return stable transaction metadata.',
+        description: 'Decode a serialized Solana transaction and return stable transaction metadata. Use this before signing when a SAP MCP, Jupiter, MagicBlock, SNS, Metaplex, or DeFi tool returns transactionBase64 or an unsigned transaction.',
         inputSchema: {
             transaction: { type: 'string', description: 'Serialized transaction' },
             encoding: { type: 'string', enum: ['base64', 'base58'], description: 'Input encoding' },
@@ -212,7 +485,7 @@ export function registerTransactionTools(server, context) {
     });
     registerTool(server, 'sap_preview_transaction', {
         title: 'Preview Transaction',
-        description: 'Preview a Solana transaction before signing or submission.',
+        description: 'Preview a Solana transaction before signing or submission. This is the required preflight step for agent workflows; do not create local signing scripts or read keypair files.',
         inputSchema: {
             transaction: { type: 'string', description: 'Serialized transaction' },
             encoding: { type: 'string', enum: ['base64', 'base58'], description: 'Input encoding' },
@@ -236,7 +509,7 @@ export function registerTransactionTools(server, context) {
     });
     registerTool(server, 'sap_sign_transaction', {
         title: 'Sign Transaction',
-        description: 'Sign a serialized Solana transaction with the configured SAP MCP signer.',
+        description: 'Sign a serialized Solana transaction with the configured SAP MCP signer after sap_preview_transaction. This is the supported non-custodial signing path for agents; never read keypair JSON or sign raw message bytes in temporary scripts.',
         inputSchema: {
             transaction: { type: 'string', description: 'Unsigned or partially signed transaction' },
             encoding: { type: 'string', enum: ['base64', 'base58'], description: 'Input encoding' },
@@ -266,27 +539,253 @@ export function registerTransactionTools(server, context) {
     });
     registerTool(server, 'sap_submit_signed_transaction', {
         title: 'Submit Signed Transaction',
-        description: 'Submit a signed Solana transaction through the configured RPC endpoint.',
+        description: 'Submit a signed Solana transaction produced by sap_sign_transaction through the configured RPC endpoint. Use this instead of custom sendRawTransaction scripts so policy, retries, and audit stay inside SAP MCP.',
         inputSchema: {
             signedTransaction: { type: 'string', description: 'Signed serialized transaction' },
             encoding: { type: 'string', enum: ['base64', 'base58'], description: 'Input encoding' },
             skipPreflight: { type: 'boolean', description: 'Skip RPC preflight checks' },
             maxRetries: { type: 'number', description: 'Maximum RPC send retries' },
+            confirmationTimeoutMs: { type: 'number', description: 'Bounded confirmation wait in milliseconds. Defaults to 90000; maximum 180000.' },
+            commitment: { type: 'string', enum: ['processed', 'confirmed', 'finalized'], description: 'Desired confirmation status before returning success. Defaults to confirmed.' },
+            submitViaRelay: { type: 'boolean', description: 'When true, submit through the hosted OOBE relay. The relay only broadcasts already-signed bytes and never signs. Defaults to false for this local tool.' },
+            submitRelayUrl: { type: 'string', description: 'Optional submit relay URL. Must be HTTPS, localhost, or 127.0.0.1.' },
+            intentId: { type: 'string', description: 'Optional caller-provided id binding submission, confirmation, and audit output.' },
         },
     }, async (input) => {
         try {
             if (!input.signedTransaction) {
                 throw new Error('signedTransaction is required');
             }
-            const rawTransaction = decodeInputBytes(input.signedTransaction, input.encoding);
-            await assertTransactionPolicy(context, deserializeTransaction(input.signedTransaction, input.encoding));
-            const signature = await context.connection.sendRawTransaction(rawTransaction, {
-                skipPreflight: input.skipPreflight,
-                maxRetries: input.maxRetries,
+            const result = input.submitViaRelay === true
+                ? await submitSignedTransactionViaRelay({
+                    signedTransaction: input.signedTransaction,
+                    encoding: input.encoding,
+                    skipPreflight: input.skipPreflight,
+                    maxRetries: input.maxRetries,
+                    confirmationTimeoutMs: input.confirmationTimeoutMs,
+                    commitment: input.commitment,
+                    submitRelayUrl: input.submitRelayUrl,
+                    intentId: input.intentId,
+                })
+                : await submitSignedTransactionWithLifecycle(context, {
+                    signedTransaction: input.signedTransaction,
+                    encoding: input.encoding,
+                    skipPreflight: input.skipPreflight,
+                    maxRetries: input.maxRetries,
+                    confirmationTimeoutMs: input.confirmationTimeoutMs,
+                    commitment: input.commitment,
+                    intentId: input.intentId,
+                });
+            return createTextResponse(JSON.stringify(result, null, 2), { isError: !result.success });
+        }
+        catch (error) {
+            return createTextResponse(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`, { isError: true });
+        }
+    });
+    // ── Native SOL Transfer Builder ───────────────────────────────────────────
+    //
+    // There is no hosted builder for native SOL transfers — `spl-token_transferSol`
+    // is local-signer-only and cannot run on the hosted accountless server. This
+    // builder creates an unsigned SystemProgram.transfer transaction that the
+    // agent signs locally via sap_payments_finalize_transaction or
+    // sap_sign_transaction → sap_submit_signed_transaction.
+    //
+    registerTool(server, 'sap_build_sol_transfer', {
+        title: 'Build Native SOL Transfer Transaction',
+        description: 'Build an unsigned native SOL transfer transaction using SystemProgram.transfer. Returns serialized base64 transaction for the agent to sign locally with sap_payments_finalize_transaction or sap_sign_transaction → sap_submit_signed_transaction. This is the hosted-safe equivalent of spl-token_transferSol (which is local-signer-only and cannot run on the hosted accountless server). Builder fee applies.',
+        inputSchema: {
+            fromPubkey: {
+                type: 'string',
+                description: 'Sender public key in base58. This is the fee payer and must sign the transaction locally.',
+            },
+            toPubkey: {
+                type: 'string',
+                description: 'Recipient public key in base58.',
+            },
+            lamports: {
+                type: 'number',
+                description: 'Amount in lamports (1 SOL = 1,000,000,000 lamports). Use sap_estimate_tool_cost to check the builder fee before calling.',
+            },
+        },
+    }, async (input) => {
+        try {
+            const raw = input;
+            const fromPubkey = typeof raw['fromPubkey'] === 'string' ? raw['fromPubkey'] : undefined;
+            const toPubkey = typeof raw['toPubkey'] === 'string' ? raw['toPubkey'] : undefined;
+            const lamports = typeof raw['lamports'] === 'number' ? raw['lamports'] : undefined;
+            if (!fromPubkey || !toPubkey || lamports === undefined) {
+                throw new Error('fromPubkey, toPubkey, and lamports are required.');
+            }
+            // Validate public keys.
+            const fromKey = new PublicKey(fromPubkey);
+            const toKey = new PublicKey(toPubkey);
+            if (lamports <= 0) {
+                throw new Error('lamports must be a positive number.');
+            }
+            // Build the SystemProgram.transfer instruction.
+            const instruction = SystemProgram.transfer({
+                fromPubkey: fromKey,
+                toPubkey: toKey,
+                lamports,
             });
+            // Create a legacy transaction with the transfer instruction.
+            // The latest blockhash is fetched from the configured RPC.
+            const connection = context.connection;
+            const blockhash = await connection.getLatestBlockhash();
+            const transaction = new Transaction({
+                recentBlockhash: blockhash.blockhash,
+                feePayer: fromKey,
+            });
+            transaction.add(instruction);
+            // Serialize as base64 for the agent to sign locally.
+            const serialized = transaction.serialize({
+                requireAllSignatures: false,
+                verifySignatures: false,
+            });
+            const transactionBase64 = serialized.toString('base64');
+            return createTextResponse(JSON.stringify({
+                success: true,
+                transactionBase64,
+                encoding: 'base64',
+                instructions: [
+                    {
+                        program: 'SystemProgram',
+                        type: 'Transfer',
+                        from: fromPubkey,
+                        to: toPubkey,
+                        lamports,
+                        solAmount: (lamports / LAMPORTS_PER_SOL).toFixed(9),
+                    },
+                ],
+                feePayer: fromPubkey,
+                unsigned: true,
+                nextSteps: 'Sign locally with sap_payments_finalize_transaction (hosted mode) or sap_sign_transaction → sap_submit_signed_transaction (local mode). Do not create temporary signing scripts or read keypair JSON.',
+            }, null, 2));
+        }
+        catch (error) {
+            return createTextResponse(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`, { isError: true });
+        }
+    });
+    // ── SPL Token Transfer Builder ─────────────────────────────────────────────
+    //
+    // `spl-token_transfer` is local-signer-only and cannot run on the hosted
+    // accountless server. This builder creates an unsigned SPL token transfer
+    // transaction that the agent signs locally via sap_payments_finalize_transaction.
+    //
+    registerTool(server, 'sap_build_spl_transfer', {
+        title: 'Build SPL Token Transfer Transaction',
+        description: 'Build an unsigned SPL token transfer transaction. Returns serialized base64 transaction for the agent to sign locally with sap_payments_finalize_transaction or sap_sign_transaction → sap_submit_signed_transaction. This is the hosted-safe equivalent of spl-token_transfer (which is local-signer-only and cannot run on the hosted accountless server). Builder fee applies.',
+        inputSchema: {
+            sourceOwner: {
+                type: 'string',
+                description: 'Source token account owner public key in base58. This is the fee payer and must sign the transaction locally.',
+            },
+            destinationOwner: {
+                type: 'string',
+                description: 'Destination wallet public key in base58. The destination ATA will be created if it does not exist.',
+            },
+            mint: {
+                type: 'string',
+                description: 'SPL token mint address in base58.',
+            },
+            amount: {
+                type: 'number',
+                description: 'Amount of tokens to transfer in base units (respect the mint decimals).',
+            },
+            decimals: {
+                type: 'number',
+                description: 'Token decimals for the mint. Used for display purposes only — the on-chain amount is in base units.',
+            },
+        },
+    }, async (input) => {
+        try {
+            const raw = input;
+            const sourceOwner = typeof raw['sourceOwner'] === 'string' ? raw['sourceOwner'] : undefined;
+            const destinationOwner = typeof raw['destinationOwner'] === 'string' ? raw['destinationOwner'] : undefined;
+            const mint = typeof raw['mint'] === 'string' ? raw['mint'] : undefined;
+            const amount = typeof raw['amount'] === 'number' ? raw['amount'] : undefined;
+            const decimals = typeof raw['decimals'] === 'number' ? raw['decimals'] : undefined;
+            if (!sourceOwner || !destinationOwner || !mint || amount === undefined) {
+                throw new Error('sourceOwner, destinationOwner, mint, and amount are required.');
+            }
+            if (amount <= 0) {
+                throw new Error('amount must be a positive number.');
+            }
+            // Build SPL token transfer instructions using @solana/web3.js only.
+            // We construct the raw instruction data manually to avoid depending on
+            // @solana/spl-token (not in package.json).
+            const sourceOwnerKey = new PublicKey(sourceOwner);
+            const destOwnerKey = new PublicKey(destinationOwner);
+            const mintKey = new PublicKey(mint);
+            // Derive Associated Token Account addresses using findProgramAddress.
+            const ASSOCIATED_TOKEN_PROGRAM_ID = new PublicKey('ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL');
+            const TOKEN_PROGRAM_ID = new PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA');
+            // ATA = PDA(['AssociatedTokenAddress', owner, tokenProgram, mint])
+            const [sourceAta] = PublicKey.findProgramAddressSync([Buffer.from('AssociatedTokenAddress'), sourceOwnerKey.toBuffer(), TOKEN_PROGRAM_ID.toBuffer(), mintKey.toBuffer()], ASSOCIATED_TOKEN_PROGRAM_ID);
+            const [destAta] = PublicKey.findProgramAddressSync([Buffer.from('AssociatedTokenAddress'), destOwnerKey.toBuffer(), TOKEN_PROGRAM_ID.toBuffer(), mintKey.toBuffer()], ASSOCIATED_TOKEN_PROGRAM_ID);
+            // CreateAssociatedTokenAccountIdempotent instruction (0x1e data).
+            const createAtaInstruction = new TransactionInstruction({
+                programId: ASSOCIATED_TOKEN_PROGRAM_ID,
+                keys: [
+                    { pubkey: sourceOwnerKey, isSigner: true, isWritable: true },
+                    { pubkey: destAta, isSigner: false, isWritable: true },
+                    { pubkey: destOwnerKey, isSigner: false, isWritable: false },
+                    { pubkey: mintKey, isSigner: false, isWritable: false },
+                    { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+                    { pubkey: TOKEN_PROGRAM_ID, isSigner: false, isWritable: false },
+                ],
+                data: Buffer.from([0x1e]),
+            });
+            // Token Transfer instruction (0x03 + 64-bit amount in little-endian).
+            const transferData = Buffer.alloc(9);
+            transferData.writeUInt8(3, 0); // Transfer instruction discriminator
+            transferData.writeBigUInt64LE(BigInt(amount), 1);
+            const transferInstruction = new TransactionInstruction({
+                programId: TOKEN_PROGRAM_ID,
+                keys: [
+                    { pubkey: sourceAta, isSigner: false, isWritable: true },
+                    { pubkey: destAta, isSigner: false, isWritable: true },
+                    { pubkey: sourceOwnerKey, isSigner: true, isWritable: false },
+                ],
+                data: transferData,
+            });
+            // Fetch latest blockhash and build transaction.
+            const connection = context.connection;
+            const blockhash = await connection.getLatestBlockhash();
+            const transaction = new Transaction({
+                recentBlockhash: blockhash.blockhash,
+                feePayer: sourceOwnerKey,
+            });
+            transaction.add(createAtaInstruction);
+            transaction.add(transferInstruction);
+            const serialized = transaction.serialize({
+                requireAllSignatures: false,
+                verifySignatures: false,
+            });
+            const transactionBase64 = serialized.toString('base64');
             return createTextResponse(JSON.stringify({
                 success: true,
-                signature,
+                transactionBase64,
+                encoding: 'base64',
+                instructions: [
+                    {
+                        program: 'SPL Token',
+                        type: 'CreateAssociatedTokenAccountIdempotent',
+                        destinationAta: destAta.toBase58(),
+                    },
+                    {
+                        program: 'SPL Token',
+                        type: 'Transfer',
+                        sourceAta: sourceAta.toBase58(),
+                        destinationAta: destAta.toBase58(),
+                        mint,
+                        amount,
+                        decimals: decimals ?? undefined,
+                    },
+                ],
+                feePayer: sourceOwner,
+                unsigned: true,
+                nextSteps: 'Sign locally with sap_payments_finalize_transaction (hosted mode) or sap_sign_transaction → sap_submit_signed_transaction (local mode). Do not create temporary signing scripts or read keypair JSON.',
             }, null, 2));
         }
         catch (error) {