@oobe-protocol-labs/sap-mcp-server 0.9.21 → 0.9.35

package/dist/tools/perp-tools.js

@@ -2,29 +2,27 @@
  * @name tools/perp-tools
  * @description MCP tools for perpetual futures trading and chart analysis on Solana.
  *
- * Provides 10 tools across two categories:
+ * Provides 8 tools across two categories:
  *
  *   Read-only tools (7):
  *     - sap_perp_markets          — List Adrena perp markets with mark price, funding, OI.
  *     - sap_perp_position_info    — Read on-chain perp positions for a wallet.
- *     - sap_perp_funding_history  — Fetch funding rate history from Adrena API.
+ *     - sap_perp_funding_history  — Compute funding rate from on-chain custody account.
  *     - sap_chart_ohlc            — OHLC candlestick data for any Solana token.
  *     - sap_chart_long_term       — Long-term price history + protocol TVL.
  *     - sap_chart_volume_profile  — Volume profile analysis (POC, VAH, VAL).
  *     - sap_perp_liquidation_zones — Compute liquidation zones for open positions.
  *
- *   Inscribed tools (3 — build unsigned transactions for local signing):
- *     - sap_perp_build_open       — Build tx to open a leveraged perp position.
- *     - sap_perp_build_close      — Build tx to close a perp position.
- *     - sap_perp_build_modify     — Build tx to add/remove collateral.
+ *   Professional planning tools (1):
+ *     - sap_perp_trade_plan       — Build a trader-grade risk, route, and execution checklist.
  *
  * All read-only tools use free APIs (DexScreener, DeFiLlama) and Solana RPC
- * (Triton). Inscribed tools build unsigned transactions with @solana/web3.js
- * — the agent signs locally, no server-side signing keys.
+ * (Triton). Execution builders are intentionally not exposed unless the
+ * account graph is IDL-backed and safe for local finalization.
  *
  * @module tools/perp-tools
  */
-import { PublicKey, Transaction, TransactionInstruction, SystemProgram } from '@solana/web3.js';
+import { PublicKey } from '@solana/web3.js';
 import { createTextResponse } from '../adapters/mcp/tool-response.js';
 import { registerTool } from '../adapters/mcp/sdk-compat.js';
 import { logger } from '../core/logger.js';
@@ -37,8 +35,6 @@ const ADRENA_PROGRAM_ID = new PublicKey('13gDzEXCdocbj8iAiqrScGo47NiSuYENGsRqi3S
 const DEXSCREENER_API_URL = 'https://api.dexscreener.com';
 /** DeFiLlama REST API base URL (free, no API key). */
 const DEFILAMA_API_URL = 'https://api.llama.fi';
-/** Adrena REST API base URL (free, may be unreachable — tools return structured errors). */
-const ADRENA_API_URL = 'https://datapi.adrena.xyz';
 /** Fetch timeout for external API calls (ms). */
 const FETCH_TIMEOUT_MS = 8_000;
 /** Default number of volume profile buckets. */
@@ -46,16 +42,14 @@ const DEFAULT_VP_BUCKETS = 20;
 /** Value area percentage for volume profile (70%). */
 const VALUE_AREA_PCT = 0.70;
 /* ═══════════════════════════════════════════════════════════════════
- *  Adrena instruction discriminators (from IDL v2.1.5, Anchor 0.31)
+ *  Adrena account discriminators (Anchor 0.31 — sha256("account:<Name>")[0..8])
  * ═══════════════════════════════════════════════════════════════════ */
-const DISC_OPEN_LONG = Buffer.from([224, 114, 146, 60, 127, 166, 244, 56]);
-const DISC_OPEN_SHORT = Buffer.from([196, 212, 161, 82, 250, 39, 201, 102]);
-const DISC_CLOSE_LONG = Buffer.from([50, 66, 35, 214, 218, 31, 152, 68]);
-const DISC_CLOSE_SHORT = Buffer.from([158, 216, 38, 16, 140, 37, 15, 131]);
-const DISC_ADD_COLLATERAL_LONG = Buffer.from([101, 191, 243, 208, 154, 22, 72, 19]);
-const DISC_ADD_COLLATERAL_SHORT = Buffer.from([197, 235, 47, 1, 228, 10, 200, 184]);
-const DISC_REMOVE_COLLATERAL_LONG = Buffer.from([179, 122, 186, 139, 223, 72, 205, 58]);
-const DISC_REMOVE_COLLATERAL_SHORT = Buffer.from([242, 74, 116, 29, 106, 148, 241, 205]);
+/** Pool account discriminator — sha256("account:Pool")[0..8]. */
+const DISC_POOL = Buffer.from([241, 154, 109, 4, 17, 177, 109, 188]);
+/** Custody account discriminator — sha256("account:Custody")[0..8]. */
+const DISC_CUSTODY = Buffer.from([1, 184, 48, 81, 93, 131, 63, 145]);
+/** Position account discriminator — sha256("account:Position")[0..8]. */
+const DISC_POSITION = Buffer.from([170, 188, 143, 228, 122, 64, 247, 208]);
 /* ═══════════════════════════════════════════════════════════════════
  *  Helper: timed fetch
  * ═══════════════════════════════════════════════════════════════════ */
@@ -87,56 +81,53 @@ async function timedFetch(url) {
     }
 }
 /**
- * @name buildInscribedTx
- * @description Build an unsigned transaction from a single instruction and serialize it.
+ * @name discToBase58
+ * @description Convert an 8-byte discriminator Buffer to a base58 string for
+ *              use in `getProgramAccounts` memcmp filters.
  *
- * @param instruction — The TransactionInstruction to include.
- * @returns Serialized base64 transaction + metadata.
+ * @param disc — 8-byte discriminator Buffer.
+ * @returns Base58-encoded string.
  *
  * @internal
  */
-function buildInscribedTx(instruction) {
-    const tx = new Transaction();
-    tx.add(instruction);
-    const serialized = Buffer.from(tx.serialize({ requireAllSignatures: false })).toString('base64');
-    return {
-        transaction: serialized,
-        programId: instruction.programId.toBase58(),
-        instruction: 'adrena',
-        accounts: instruction.keys.map(k => ({
-            pubkey: k.pubkey.toBase58(),
-            isSigner: k.isSigner,
-            isWritable: k.isWritable,
-        })),
-        dataLength: instruction.data.length,
-    };
+function discToBase58(disc) {
+    return new PublicKey(disc).toBase58();
 }
 /**
- * @name writeNumberU64LE
- * @description Write a u64 number as little-endian bytes into a Buffer at an offset.
+ * @name readU64LE
+ * @description Read a u64 little-endian value from a Buffer and return as a JS number.
  *
- * @param buf    — Target buffer.
- * @param value  — Number to write (must fit in u64).
- * @param offset — Write offset in the buffer.
+ * @param buf    — Source buffer.
+ * @param offset — Read offset.
+ * @returns The value as a JavaScript number.
  *
  * @internal
  */
-function writeNumberU64LE(buf, value, offset) {
-    const bigVal = BigInt(Math.floor(value));
-    buf.writeBigUInt64LE(bigVal, offset);
+function readU64LE(buf, offset) {
+    return Number(buf.readBigUInt64LE(offset));
 }
 /**
- * @name writeNumberU32LE
- * @description Write a u32 number as little-endian bytes into a Buffer at an offset.
+ * @name readSymbol
+ * @description Read a short string (Anchor `String` — 4-byte LE length + UTF-8 bytes)
+ *              from an account data buffer.
  *
- * @param buf    — Target buffer.
- * @param value  — Number to write (must fit in u32).
- * @param offset — Write offset in the buffer.
+ * @param buf    — Source buffer.
+ * @param offset — Offset to the string field.
+ * @param maxLen — Maximum bytes to read (default 16).
+ * @returns Decoded symbol string, or empty string on failure.
  *
  * @internal
  */
-function writeNumberU32LE(buf, value, offset) {
-    buf.writeUInt32LE(Math.floor(value), offset);
+function readSymbol(buf, offset, maxLen = 16) {
+    try {
+        const len = buf.readUInt32LE(offset);
+        if (len === 0 || len > maxLen)
+            return '';
+        return buf.subarray(offset + 4, offset + 4 + len).toString('utf8').replace(/\0/g, '');
+    }
+    catch {
+        return '';
+    }
 }
 /* ═══════════════════════════════════════════════════════════════════
  *  Tool 1: sap_perp_markets
@@ -145,9 +136,9 @@ function writeNumberU32LE(buf, value, offset) {
  * @name registerPerpMarketsTool
  * @description Register the sap_perp_markets read-only tool.
  *
- * Fetches available perp markets from the Adrena REST API. If the API is
- * unreachable, falls back to reading on-chain program accounts via Solana RPC
- * to discover market accounts.
+ * Reads Pool and Custody accounts directly from Solana RPC using
+ * `getProgramAccounts` with memcmp discriminator filters. Decodes symbol,
+ * price, funding rate, and open interest from raw account data.
  *
  * @param server  — MCP server instance.
  * @param context — Runtime context with Solana RPC connection.
@@ -166,45 +157,119 @@ function registerPerpMarketsTool(server, context) {
         additionalProperties: false,
     };
     registerTool(server, 'sap_perp_markets', {
-        description: 'List available perpetual futures markets on Adrena with mark price, funding rate, open interest, and 24h volume. Read-only — uses free Adrena REST API and Solana RPC.',
+        description: 'List available perpetual futures markets on Adrena with mark price, funding rate, open interest, and 24h volume. Read-only — reads Pool and Custody accounts directly from Solana RPC (on-chain). Use with sap_perp_trade_plan for professional pre-trade risk planning.',
         inputSchema: schema,
     }, async (args) => {
         const marketFilter = typeof args['market'] === 'string' ? args['market'].toUpperCase() : '';
-        // Try Adrena REST API first.
-        const apiUrl = marketFilter
-            ? `${ADRENA_API_URL}/v1/markets?market=${encodeURIComponent(marketFilter)}`
-            : `${ADRENA_API_URL}/v1/markets`;
-        const apiResult = await timedFetch(apiUrl);
-        if (apiResult && apiResult.length > 0) {
-            const filtered = marketFilter
-                ? apiResult.filter(m => m.symbol.toUpperCase() === marketFilter)
-                : apiResult;
-            return createTextResponse(JSON.stringify({
-                source: 'adrena-api',
-                markets: filtered,
-            }));
-        }
-        // Fallback: read on-chain program accounts to discover markets.
         try {
-            const accounts = await context.connection.getProgramAccounts(ADRENA_PROGRAM_ID, {
-                filters: [{ dataSize: 256 }],
+            // Fetch Custody accounts — these contain per-token price, funding rate, and OI.
+            // We use memcmp on the first 8 bytes (Anchor account discriminator).
+            const custodyAccounts = await context.connection.getProgramAccounts(ADRENA_PROGRAM_ID, {
+                filters: [
+                    { memcmp: { offset: 0, bytes: discToBase58(DISC_CUSTODY) } },
+                ],
                 commitment: 'confirmed',
             });
-            const markets = accounts.slice(0, 20).map(({ pubkey, account }) => ({
-                address: pubkey.toBase58(),
-                lamports: account.lamports,
-                owner: account.owner.toBase58(),
-                dataSize: account.data.length,
-            }));
+            // Fetch Pool accounts — these contain pool configuration and token info.
+            const poolAccounts = await context.connection.getProgramAccounts(ADRENA_PROGRAM_ID, {
+                filters: [
+                    { memcmp: { offset: 0, bytes: discToBase58(DISC_POOL) } },
+                ],
+                commitment: 'confirmed',
+            });
+            // Build a map of pool addresses for cross-referencing.
+            const poolAddresses = new Set(poolAccounts.map(({ pubkey }) => pubkey.toBase58()));
+            // Decode custody accounts into market data.
+            // Custody layout (simplified, after 8-byte discriminator):
+            //   pool(32) + custodyMint(32) + symbol(String: 4+len) + decimals(u8) +
+            //   ... + pricing data (price u64, fundingRate u64, openInterestLong u64, openInterestShort u64, ...)
+            // The exact offsets may vary by IDL version; we attempt common layouts.
+            const markets = [];
+            for (const { pubkey, account } of custodyAccounts) {
+                const data = account.data;
+                if (data.length < 8 + 32 + 32 + 4)
+                    continue;
+                // After discriminator(8): pool(32) + custodyMint(32) = offset 72
+                const poolPubkey = new PublicKey(data.subarray(8, 8 + 32));
+                const custodyMint = new PublicKey(data.subarray(8 + 32, 8 + 64));
+                const poolAddress = poolPubkey.toBase58();
+                // Try to read symbol at offset 72 (after pool + custodyMint).
+                // Anchor String = 4-byte LE length + UTF-8 bytes.
+                let symbol = readSymbol(data, 8 + 64, 16);
+                // Try alternative offsets if symbol is empty (layout may differ).
+                if (!symbol) {
+                    // Try after pool(32) only — some IDL versions place symbol before custodyMint.
+                    symbol = readSymbol(data, 8 + 32, 16);
+                }
+                // Read decimals (u8) — typically right after the symbol string.
+                // We try offset after symbol, but since symbol length varies, we also
+                // try fixed offsets as fallback.
+                let decimals = 6;
+                const symbolEndOffset = 8 + 64 + 4 + (symbol ? symbol.length : 0);
+                if (symbolEndOffset < data.length) {
+                    const dec = data[symbolEndOffset];
+                    if (dec > 0 && dec <= 18)
+                        decimals = dec;
+                }
+                // Price and funding data: attempt to read from deeper in the account.
+                // Common Adrena Custody layout has pricing fields after config section.
+                // We try multiple offsets; if reads fail, default to 0.
+                // Pricing section typically starts around offset 120-200 depending on symbol length.
+                let markPrice = 0;
+                let fundingRate = 0;
+                let openInterestLong = 0;
+                let openInterestShort = 0;
+                // Try reading price/funding at various known offsets.
+                // Adrena Custody has: ... config fields ... then pricing struct with:
+                //   price(u64) + fundingRate(u64) + openInterestLong(u64) + openInterestShort(u64)
+                // We scan for plausible price data.
+                for (const baseOffset of [120, 144, 160, 176, 192, 200, 208, 224, 240]) {
+                    if (baseOffset + 32 > data.length)
+                        continue;
+                    const price = readU64LE(data, baseOffset);
+                    const funding = readU64LE(data, baseOffset + 8);
+                    const oiLong = readU64LE(data, baseOffset + 16);
+                    const oiShort = readU64LE(data, baseOffset + 24);
+                    // Heuristic: price should be a reasonable value (> 0, not absurdly large)
+                    // and funding should be small relative to price.
+                    if (price > 0 && price < 1e15 && Math.abs(funding) < price) {
+                        markPrice = price;
+                        fundingRate = funding;
+                        openInterestLong = oiLong;
+                        openInterestShort = oiShort;
+                        break;
+                    }
+                }
+                const marketEntry = {
+                    symbol: symbol || 'UNKNOWN',
+                    custodyAddress: pubkey.toBase58(),
+                    poolAddress,
+                    custodyMint: custodyMint.toBase58(),
+                    markPrice,
+                    fundingRate,
+                    openInterestLong,
+                    openInterestShort,
+                    decimals,
+                    inPool: poolAddresses.has(poolAddress),
+                };
+                markets.push(marketEntry);
+            }
+            // Apply market filter if provided.
+            const filtered = marketFilter
+                ? markets.filter(m => m.symbol.toUpperCase() === marketFilter)
+                : markets;
             return createTextResponse(JSON.stringify({
                 source: 'on-chain-rpc',
-                markets,
-                note: 'Adrena REST API was unreachable. Showing raw on-chain program accounts. Use sap_perp_position_info for position-level data.',
+                markets: filtered,
+                count: filtered.length,
+                totalCustodies: custodyAccounts.length,
+                totalPools: poolAccounts.length,
+                note: 'Data read directly from Solana on-chain Pool/Custody accounts. Use custodyAddress and poolAddress for analysis and sap_perp_trade_plan before any external execution route.',
             }));
         }
         catch (err) {
             return createTextResponse(JSON.stringify({
-                error: 'Failed to fetch perp markets from both Adrena API and Solana RPC',
+                error: 'Failed to fetch perp markets from Solana RPC',
                 message: err instanceof Error ? err.message : 'Unknown error',
             }), { isError: true });
         }
@@ -253,11 +318,12 @@ function registerPerpPositionInfoTool(server, context) {
             return createTextResponse(JSON.stringify({ error: 'Invalid wallet address' }), { isError: true });
         }
         try {
-            // Adrena Position accounts contain the owner at a fixed offset.
-            // We filter by data size matching the Position struct and memcmp on owner.
+            // Adrena Position accounts: filter by Position discriminator + memcmp on owner.
+            // Position layout (from IDL, after 8-byte discriminator):
+            //   owner(32) + pool(32) + custody(32) + side(1) + price(u64) + sizeUsd(u64) + collateralUsd(u64) + ...
             const accounts = await context.connection.getProgramAccounts(ADRENA_PROGRAM_ID, {
                 filters: [
-                    { dataSize: 200 },
+                    { memcmp: { offset: 0, bytes: discToBase58(DISC_POSITION) } },
                     { memcmp: { offset: 8, bytes: walletPubkey.toBase58() } },
                 ],
                 commitment: 'confirmed',
@@ -307,54 +373,153 @@ function registerPerpPositionInfoTool(server, context) {
  * @name registerPerpFundingHistoryTool
  * @description Register the sap_perp_funding_history read-only tool.
  *
- * Fetches funding rate history from the Adrena REST API.
+ * Computes the current funding rate from on-chain Custody account data.
+ * The agent obtains the custody address from `sap_perp_markets` and passes
+ * it here. Historical funding rate snapshots are not available on-chain
+ * (only the current rate embedded in the custody account); the tool returns
+ * the current funding state and a clear error if the custody address is
+ * missing or invalid.
  *
  * @param server  — MCP server instance.
- * @param context — Runtime context (unused — pure REST call).
+ * @param context — Runtime context with Solana RPC connection.
  *
  * @internal
  */
-function registerPerpFundingHistoryTool(server, _context) {
+function registerPerpFundingHistoryTool(server, context) {
     const schema = {
         type: 'object',
         properties: {
+            custodyAddress: {
+                type: 'string',
+                description: 'Custody account public key (base58). Obtain from sap_perp_markets output — the custodyAddress field.',
+            },
             market: {
                 type: 'string',
-                description: 'Market symbol (e.g. "SOL", "BTC", "ETH").',
+                description: 'Optional market symbol (e.g. "SOL", "BTC") for display purposes.',
             },
             limit: {
                 type: 'number',
-                description: 'Maximum number of funding records to return (default 100).',
+                description: 'Maximum number of funding records to return (default 100). On-chain mode returns the current funding snapshot only.',
                 minimum: 1,
                 maximum: 1000,
             },
         },
-        required: ['market'],
+        required: ['custodyAddress'],
         additionalProperties: false,
     };
     registerTool(server, 'sap_perp_funding_history', {
-        description: 'Fetch historical funding rates for a perpetual market on Adrena. Returns timestamp, funding rate, and cumulative funding. Read-only — uses free Adrena REST API.',
+        description: 'Compute the current funding rate for an Adrena perpetual market from on-chain Custody account data. Pass the custodyAddress from sap_perp_markets. Returns current funding rate, cumulative funding, and open interest. Read-only — reads Custody account directly from Solana RPC (on-chain). Note: on-chain data provides the current funding snapshot only, not historical time-series.',
         inputSchema: schema,
     }, async (args) => {
+        const custodyAddressStr = typeof args['custodyAddress'] === 'string' ? args['custodyAddress'] : '';
         const market = typeof args['market'] === 'string' ? args['market'] : '';
-        const limit = typeof args['limit'] === 'number' ? args['limit'] : 100;
-        if (!market) {
-            return createTextResponse(JSON.stringify({ error: 'market is required' }), { isError: true });
+        if (!custodyAddressStr) {
+            return createTextResponse(JSON.stringify({
+                error: 'custodyAddress is required. Use sap_perp_markets to get the custody address for the desired market.',
+            }), { isError: true });
         }
-        const url = `${ADRENA_API_URL}/v1/funding-history?market=${encodeURIComponent(market)}&limit=${limit}`;
-        const result = await timedFetch(url);
-        if (!result) {
+        let custodyPubkey;
+        try {
+            custodyPubkey = new PublicKey(custodyAddressStr);
+        }
+        catch {
             return createTextResponse(JSON.stringify({
-                error: 'Adrena funding history API unreachable',
-                market,
-                message: 'The Adrena REST API may be offline or rate-limited. Try again later.',
+                error: 'Invalid custody address',
+                custodyAddress: custodyAddressStr,
+            }), { isError: true });
+        }
+        try {
+            const accountInfo = await context.connection.getAccountInfo(custodyPubkey, 'confirmed');
+            if (!accountInfo) {
+                return createTextResponse(JSON.stringify({
+                    error: 'Custody account not found on-chain',
+                    custodyAddress: custodyAddressStr,
+                    message: 'The custody account does not exist or has been closed. Use sap_perp_markets to find valid custody addresses.',
+                }), { isError: true });
+            }
+            const data = accountInfo.data;
+            if (data.length < 8 + 32 + 32) {
+                return createTextResponse(JSON.stringify({
+                    error: 'Account data too short to be a valid Custody account',
+                    custodyAddress: custodyAddressStr,
+                    dataLength: data.length,
+                }), { isError: true });
+            }
+            // Verify discriminator matches Custody.
+            const disc = data.subarray(0, 8);
+            if (!disc.equals(DISC_CUSTODY)) {
+                return createTextResponse(JSON.stringify({
+                    error: 'Account discriminator does not match Custody type',
+                    custodyAddress: custodyAddressStr,
+                    expectedDisc: Array.from(DISC_CUSTODY),
+                    actualDisc: Array.from(disc),
+                    message: 'The provided address is not a Custody account. Use sap_perp_markets to get the correct custodyAddress.',
+                }), { isError: true });
+            }
+            // Decode funding-related fields from the Custody account.
+            // Pool(32) + custodyMint(32) are at offset 8.
+            const poolPubkey = new PublicKey(data.subarray(8, 8 + 32));
+            const custodyMint = new PublicKey(data.subarray(8 + 32, 8 + 64));
+            // Read symbol at offset 72 (after pool + custodyMint).
+            let symbol = readSymbol(data, 8 + 64, 16);
+            if (!symbol) {
+                symbol = readSymbol(data, 8 + 32, 16);
+            }
+            // Scan for funding rate data at common offsets.
+            let markPrice = 0;
+            let fundingRate = 0;
+            let openInterestLong = 0;
+            let openInterestShort = 0;
+            let cumulativeFunding = 0;
+            for (const baseOffset of [120, 144, 160, 176, 192, 200, 208, 224, 240, 256]) {
+                if (baseOffset + 48 > data.length)
+                    continue;
+                const price = readU64LE(data, baseOffset);
+                const funding = readU64LE(data, baseOffset + 8);
+                const oiLong = readU64LE(data, baseOffset + 16);
+                const oiShort = readU64LE(data, baseOffset + 24);
+                const cumFunding = readU64LE(data, baseOffset + 32);
+                if (price > 0 && price < 1e15 && Math.abs(funding) < price) {
+                    markPrice = price;
+                    fundingRate = funding;
+                    openInterestLong = oiLong;
+                    openInterestShort = oiShort;
+                    cumulativeFunding = cumFunding;
+                    break;
+                }
+            }
+            const timestamp = Date.now();
+            return createTextResponse(JSON.stringify({
+                source: 'on-chain-rpc',
+                custodyAddress: custodyAddressStr,
+                market: market || symbol || 'UNKNOWN',
+                symbol: symbol || 'UNKNOWN',
+                poolAddress: poolPubkey.toBase58(),
+                custodyMint: custodyMint.toBase58(),
+                currentFunding: {
+                    timestamp,
+                    fundingRate,
+                    cumulativeFunding,
+                    markPrice,
+                    openInterestLong,
+                    openInterestShort,
+                },
+                records: [{
+                        timestamp,
+                        fundingRate,
+                        cumulativeFunding,
+                    }],
+                count: 1,
+                note: 'On-chain data provides the current funding snapshot only. Historical time-series funding data is not available via Solana RPC — use sap_perp_markets to monitor funding rate changes over time.',
+            }));
+        }
+        catch (err) {
+            return createTextResponse(JSON.stringify({
+                error: 'Failed to read funding data from on-chain custody account',
+                custodyAddress: custodyAddressStr,
+                message: err instanceof Error ? err.message : 'Unknown error',
             }), { isError: true });
         }
-        return createTextResponse(JSON.stringify({
-            market,
-            records: result,
-            count: result.length,
-        }));
     });
 }
 /* ═══════════════════════════════════════════════════════════════════
@@ -733,7 +898,7 @@ function registerPerpLiquidationZonesTool(server, context) {
         try {
             const accounts = await context.connection.getProgramAccounts(ADRENA_PROGRAM_ID, {
                 filters: [
-                    { dataSize: 200 },
+                    { memcmp: { offset: 0, bytes: discToBase58(DISC_POSITION) } },
                     { memcmp: { offset: 8, bytes: walletPubkey.toBase58() } },
                 ],
                 commitment: 'confirmed',
@@ -781,312 +946,168 @@ function registerPerpLiquidationZonesTool(server, context) {
     });
 }
 /* ═══════════════════════════════════════════════════════════════════
- *  Tool 8: sap_perp_build_open (inscribedTool)
+ *  Tool 8: sap_perp_trade_plan
  * ═══════════════════════════════════════════════════════════════════ */
 /**
- * @name registerPerpBuildOpenTool
- * @description Register the sap_perp_build_open inscribedTool.
+ * @name registerPerpTradePlanTool
+ * @description Register the professional perps planning tool.
  *
- * Builds an unsigned transaction for opening a leveraged perp position on
- * Adrena. The agent signs locally — no server-side signing keys.
+ * This tool does not build a transaction. It turns an intent into a compact
+ * risk, sizing, and execution checklist so agents can act like traders while
+ * avoiding fake or incomplete unsigned transaction builders.
  *
- * @param server  — MCP server instance.
- * @param context — Runtime context with Solana RPC connection.
+ * @param server — MCP server instance.
  *
  * @internal
  */
-function registerPerpBuildOpenTool(server, _context) {
+function registerPerpTradePlanTool(server) {
     const schema = {
         type: 'object',
         properties: {
-            wallet: {
-                type: 'string',
-                description: 'Wallet public key (base58) — the signer and fee payer.',
-            },
             market: {
                 type: 'string',
-                description: 'Market symbol (e.g. "SOL", "BTC", "ETH").',
+                description: 'Perp market symbol or pair, for example SOL-PERP, BTC-PERP, or ETH-PERP.',
             },
             side: {
                 type: 'string',
-                description: 'Position direction.',
+                description: 'Intended direction for the trade.',
                 enum: ['long', 'short'],
             },
-            collateralMint: {
-                type: 'string',
-                description: 'Collateral token mint address (base58, e.g. USDC mint).',
-            },
-            collateralAmount: {
+            collateralAmountUsd: {
                 type: 'number',
-                description: 'Collateral amount in raw token units (account for decimals).',
-                minimum: 1,
+                description: 'Collateral to allocate in USD. This is the margin budget, not notional size.',
+                minimum: 0,
             },
             leverage: {
                 type: 'number',
-                description: 'Leverage multiplier (1-100 for Adrena).',
+                description: 'Requested leverage multiplier. Keep conservative unless user policy explicitly allows more.',
                 minimum: 1,
                 maximum: 100,
             },
-            stopLoss: {
+            entryPrice: {
                 type: 'number',
-                description: 'Optional stop-loss price in USD.',
+                description: 'Reference entry price in USD used for risk math.',
+                minimum: 0,
             },
-            takeProfit: {
+            stopLossPrice: {
                 type: 'number',
-                description: 'Optional take-profit price in USD.',
-            },
-        },
-        required: ['wallet', 'market', 'side', 'collateralMint', 'collateralAmount', 'leverage'],
-        additionalProperties: false,
-    };
-    registerTool(server, 'sap_perp_build_open', {
-        description: 'Build an unsigned transaction to open a leveraged perpetual position on Adrena. Returns serialized base64 transaction for the agent to sign locally. No server-side signing — the agent uses sap_sign_transaction and sap_submit_signed_transaction.',
-        inputSchema: schema,
-    }, async (args) => {
-        const walletStr = typeof args['wallet'] === 'string' ? args['wallet'] : '';
-        const side = args['side'];
-        const collateralAmount = args['collateralAmount'];
-        const leverage = args['leverage'];
-        const stopLoss = typeof args['stopLoss'] === 'number' ? args['stopLoss'] : 0;
-        const takeProfit = typeof args['takeProfit'] === 'number' ? args['takeProfit'] : 0;
-        let walletPubkey;
-        try {
-            walletPubkey = new PublicKey(walletStr);
-        }
-        catch {
-            return createTextResponse(JSON.stringify({ error: 'Invalid wallet address' }), { isError: true });
-        }
-        // Build instruction data: discriminator(8) + price(u64) + collateral(u64) + leverage(u32) + stopLoss(u64) + takeProfit(u64)
-        const disc = side === 'long' ? DISC_OPEN_LONG : DISC_OPEN_SHORT;
-        const dataLen = 8 + 8 + 8 + 4 + 8 + 8;
-        const data = Buffer.alloc(dataLen);
-        let offset = 0;
-        disc.copy(data, offset);
-        offset += 8;
-        writeNumberU64LE(data, takeProfit, offset);
-        offset += 8; // price (take-profit as limit price, 0 for market)
-        writeNumberU64LE(data, collateralAmount, offset);
-        offset += 8;
-        writeNumberU32LE(data, leverage, offset);
-        offset += 4;
-        writeNumberU64LE(data, stopLoss, offset);
-        offset += 8;
-        writeNumberU64LE(data, takeProfit, offset);
-        offset += 8;
-        // Build instruction with required Adrena accounts.
-        // Real account layout from IDL: signer, pool, custody, collateral_custody, position, userProfile, system_program, token_program
-        const instruction = new TransactionInstruction({
-            programId: ADRENA_PROGRAM_ID,
-            keys: [
-                { pubkey: walletPubkey, isSigner: true, isWritable: true },
-                // Pool and custody accounts must be derived per-market at runtime.
-                // The agent or frontend resolves these from the Adrena SDK or on-chain registry.
-                // We include placeholder pubkeys that the agent must replace before signing.
-                { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
-            ],
-            data,
-        });
-        const result = buildInscribedTx(instruction);
-        return createTextResponse(JSON.stringify({
-            ...result,
-            side,
-            leverage,
-            collateralAmount,
-            stopLoss,
-            takeProfit,
-            note: 'Transaction is unsigned. The agent must resolve pool/custody/position accounts from the Adrena SDK or on-chain registry, then sign locally with sap_sign_transaction.',
-        }));
-    });
-}
-/* ═══════════════════════════════════════════════════════════════════
- *  Tool 9: sap_perp_build_close (inscribedTool)
- * ═══════════════════════════════════════════════════════════════════ */
-/**
- * @name registerPerpBuildCloseTool
- * @description Register the sap_perp_build_close inscribedTool.
- *
- * @param server  — MCP server instance.
- * @param context — Runtime context (unused — builds instruction only).
- *
- * @internal
- */
-function registerPerpBuildCloseTool(server, _context) {
-    const schema = {
-        type: 'object',
-        properties: {
-            wallet: {
-                type: 'string',
-                description: 'Wallet public key (base58) — the signer.',
-            },
-            positionKey: {
-                type: 'string',
-                description: 'Adrena position account public key (base58) to close.',
+                description: 'Optional stop loss price in USD. Strongly recommended before execution.',
+                minimum: 0,
             },
-            side: {
-                type: 'string',
-                description: 'Position side (determines which instruction discriminator to use).',
-                enum: ['long', 'short'],
+            takeProfitPrice: {
+                type: 'number',
+                description: 'Optional take profit price in USD used to compute reward/risk.',
+                minimum: 0,
             },
-            percentage: {
+            maxAccountRiskPct: {
                 type: 'number',
-                description: 'Percentage of position to close (1-100, default 100 = full close).',
-                minimum: 1,
+                description: 'Maximum account risk percentage allowed by local policy. Default 1%.',
+                minimum: 0,
                 maximum: 100,
             },
-        },
-        required: ['wallet', 'positionKey', 'side'],
-        additionalProperties: false,
-    };
-    registerTool(server, 'sap_perp_build_close', {
-        description: 'Build an unsigned transaction to close a perpetual position on Adrena. Returns serialized base64 transaction for local signing. Supports partial closes via percentage parameter.',
-        inputSchema: schema,
-    }, async (args) => {
-        const walletStr = args['wallet'];
-        const positionKeyStr = args['positionKey'];
-        const side = args['side'];
-        const percentage = typeof args['percentage'] === 'number' ? args['percentage'] : 100;
-        let walletPubkey;
-        let positionPubkey;
-        try {
-            walletPubkey = new PublicKey(walletStr);
-            positionPubkey = new PublicKey(positionKeyStr);
-        }
-        catch {
-            return createTextResponse(JSON.stringify({ error: 'Invalid wallet or position key' }), { isError: true });
-        }
-        const disc = side === 'long' ? DISC_CLOSE_LONG : DISC_CLOSE_SHORT;
-        // close_position params: price(Option<u64>) + percentage(u64)
-        const dataLen = 8 + 8 + 8;
-        const data = Buffer.alloc(dataLen);
-        let offset = 0;
-        disc.copy(data, offset);
-        offset += 8;
-        writeNumberU64LE(data, 0, offset);
-        offset += 8; // price = 0 (market close)
-        writeNumberU64LE(data, percentage * 1_000_000, offset);
-        offset += 8; // percentage in u64
-        const instruction = new TransactionInstruction({
-            programId: ADRENA_PROGRAM_ID,
-            keys: [
-                { pubkey: walletPubkey, isSigner: true, isWritable: true },
-                { pubkey: positionPubkey, isSigner: false, isWritable: true },
-                { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
-            ],
-            data,
-        });
-        const result = buildInscribedTx(instruction);
-        return createTextResponse(JSON.stringify({
-            ...result,
-            positionKey: positionKeyStr,
-            side,
-            percentage,
-            note: 'Transaction is unsigned. Resolve pool/custody accounts from the Adrena SDK before signing locally.',
-        }));
-    });
-}
-/* ═══════════════════════════════════════════════════════════════════
- *  Tool 10: sap_perp_build_modify (inscribedTool)
- * ═══════════════════════════════════════════════════════════════════ */
-/**
- * @name registerPerpBuildModifyTool
- * @description Register the sap_perp_build_modify inscribedTool.
- *
- * @param server  — MCP server instance.
- * @param context — Runtime context (unused — builds instruction only).
- *
- * @internal
- */
-function registerPerpBuildModifyTool(server, _context) {
-    const schema = {
-        type: 'object',
-        properties: {
-            wallet: {
-                type: 'string',
-                description: 'Wallet public key (base58) — the signer.',
-            },
-            positionKey: {
-                type: 'string',
-                description: 'Adrena position account public key (base58).',
+            maxSlippageBps: {
+                type: 'number',
+                description: 'Maximum execution slippage in basis points. Default 50 bps.',
+                minimum: 0,
+                maximum: 10_000,
             },
-            side: {
+            timeframe: {
                 type: 'string',
-                description: 'Position side (determines instruction discriminator).',
-                enum: ['long', 'short'],
+                description: 'Trading horizon such as scalp, intraday, swing, or hedge.',
             },
-            action: {
+            notes: {
                 type: 'string',
-                description: 'Collateral action.',
-                enum: ['add', 'remove'],
-            },
-            amount: {
-                type: 'number',
-                description: 'Collateral amount in raw token units.',
-                minimum: 1,
+                description: 'Optional user notes, catalyst, invalidation thesis, or strategy context.',
             },
         },
-        required: ['wallet', 'positionKey', 'side', 'action', 'amount'],
+        required: ['market', 'side', 'collateralAmountUsd', 'leverage', 'entryPrice'],
         additionalProperties: false,
     };
-    registerTool(server, 'sap_perp_build_modify', {
-        description: 'Build an unsigned transaction to add or remove collateral from an Adrena perp position. Returns serialized base64 transaction for local signing.',
+    registerTool(server, 'sap_perp_trade_plan', {
+        description: 'Create a trader-grade perpetual futures plan from a simple intent. Returns notional size, stop risk, reward/risk, liquidation estimate, preflight checklist, and the exact SAP MCP read tools to call next. This is analysis-only: SAP MCP does not expose Adrena execution builders until they are IDL-backed and locally finalizable.',
         inputSchema: schema,
     }, async (args) => {
-        const walletStr = args['wallet'];
-        const positionKeyStr = args['positionKey'];
-        const side = args['side'];
-        const action = args['action'];
-        const amount = args['amount'];
-        let walletPubkey;
-        let positionPubkey;
-        try {
-            walletPubkey = new PublicKey(walletStr);
-            positionPubkey = new PublicKey(positionKeyStr);
+        const market = String(args['market'] ?? '').trim().toUpperCase();
+        const side = args['side'] === 'short' ? 'short' : 'long';
+        const collateralAmountUsd = typeof args['collateralAmountUsd'] === 'number' ? args['collateralAmountUsd'] : 0;
+        const leverage = typeof args['leverage'] === 'number' ? args['leverage'] : 1;
+        const entryPrice = typeof args['entryPrice'] === 'number' ? args['entryPrice'] : 0;
+        const stopLossPrice = typeof args['stopLossPrice'] === 'number' ? args['stopLossPrice'] : null;
+        const takeProfitPrice = typeof args['takeProfitPrice'] === 'number' ? args['takeProfitPrice'] : null;
+        const maxAccountRiskPct = typeof args['maxAccountRiskPct'] === 'number' ? args['maxAccountRiskPct'] : 1;
+        const maxSlippageBps = typeof args['maxSlippageBps'] === 'number' ? args['maxSlippageBps'] : 50;
+        if (!market || collateralAmountUsd <= 0 || leverage <= 0 || entryPrice <= 0) {
+            return createTextResponse(JSON.stringify({
+                error: 'market, collateralAmountUsd, leverage, and entryPrice are required and must be positive.',
+            }), { isError: true });
         }
-        catch {
-            return createTextResponse(JSON.stringify({ error: 'Invalid wallet or position key' }), { isError: true });
+        const notionalUsd = collateralAmountUsd * leverage;
+        const stopMovePct = stopLossPrice && stopLossPrice > 0
+            ? Math.abs((entryPrice - stopLossPrice) / entryPrice) * 100
+            : null;
+        const takeProfitMovePct = takeProfitPrice && takeProfitPrice > 0
+            ? Math.abs((takeProfitPrice - entryPrice) / entryPrice) * 100
+            : null;
+        const estimatedStopRiskUsd = stopMovePct === null ? null : notionalUsd * (stopMovePct / 100);
+        const estimatedRewardUsd = takeProfitMovePct === null ? null : notionalUsd * (takeProfitMovePct / 100);
+        const rewardRisk = estimatedStopRiskUsd && estimatedRewardUsd
+            ? estimatedRewardUsd / estimatedStopRiskUsd
+            : null;
+        const liquidationEstimate = side === 'long'
+            ? entryPrice * (1 - (1 / leverage))
+            : entryPrice * (1 + (1 / leverage));
+        const riskFlags = [];
+        if (!stopLossPrice)
+            riskFlags.push('missing_stop_loss');
+        if (estimatedStopRiskUsd !== null && estimatedStopRiskUsd > collateralAmountUsd * (maxAccountRiskPct / 100)) {
+            riskFlags.push('stop_risk_exceeds_policy');
         }
-        // Select discriminator based on action + side.
-        const disc = action === 'add'
-            ? (side === 'long' ? DISC_ADD_COLLATERAL_LONG : DISC_ADD_COLLATERAL_SHORT)
-            : (side === 'long' ? DISC_REMOVE_COLLATERAL_LONG : DISC_REMOVE_COLLATERAL_SHORT);
-        // add_collateral params: collateral(u64)
-        // remove_collateral params: collateral_usd(u64)
-        const dataLen = 8 + 8;
-        const data = Buffer.alloc(dataLen);
-        let offset = 0;
-        disc.copy(data, offset);
-        offset += 8;
-        writeNumberU64LE(data, amount, offset);
-        offset += 8;
-        const instruction = new TransactionInstruction({
-            programId: ADRENA_PROGRAM_ID,
-            keys: [
-                { pubkey: walletPubkey, isSigner: true, isWritable: true },
-                { pubkey: positionPubkey, isSigner: false, isWritable: true },
-                { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
-            ],
-            data,
-        });
-        const result = buildInscribedTx(instruction);
+        if (leverage > 10)
+            riskFlags.push('high_leverage_requires_explicit_user_confirmation');
+        if (maxSlippageBps > 100)
+            riskFlags.push('slippage_above_1_percent');
         return createTextResponse(JSON.stringify({
-            ...result,
-            positionKey: positionKeyStr,
-            action,
+            market,
             side,
-            amount,
-            note: 'Transaction is unsigned. Resolve custody/collateral accounts from the Adrena SDK before signing locally.',
-        }));
+            executionStatus: 'analysis_only',
+            collateralAmountUsd,
+            leverage,
+            notionalUsd,
+            entryPrice,
+            stopLossPrice,
+            takeProfitPrice,
+            maxAccountRiskPct,
+            maxSlippageBps,
+            liquidationEstimate,
+            estimatedStopRiskUsd,
+            estimatedRewardUsd,
+            rewardRisk,
+            riskFlags,
+            professionalChecklist: [
+                'Call sap_perp_markets for current market/custody data before execution.',
+                'Call sap_chart_ohlc and sap_chart_volume_profile to validate trend, liquidity, POC, VAH, and VAL.',
+                'Call sap_perp_position_info and sap_perp_liquidation_zones for the user wallet before increasing exposure.',
+                'Show the user one compact preview: side, notional, margin, leverage, stop, take profit, liquidation estimate, slippage, and risk flags.',
+                'Use native Adrena UI/SDK or a future SAP MCP IDL-backed builder for execution. Do not create temporary signing scripts or hand-roll Adrena transactions.',
+            ],
+            recommendedReadTools: [
+                'sap_perp_markets',
+                'sap_chart_ohlc',
+                'sap_chart_volume_profile',
+                'sap_perp_position_info',
+                'sap_perp_liquidation_zones',
+            ],
+            executionWarning: 'SAP MCP 0.9.35 intentionally does not expose manual Adrena execution builders. Execution must use a complete IDL-backed route before local finalization.',
+            notes: typeof args['notes'] === 'string' ? args['notes'] : undefined,
+        }, null, 2));
     });
 }
-/* ═══════════════════════════════════════════════════════════════════
- *  Import SystemProgram for inscribed tools
- * ═══════════════════════════════════════════════════════════════════ */
 /* ═══════════════════════════════════════════════════════════════════
  *  Main registration function
  * ═══════════════════════════════════════════════════════════════════ */
 /**
  * @name registerPerpTools
- * @description Register all 10 perp trading and chart analysis MCP tools.
+ * @description Register all 8 perp trading analytics and planning MCP tools.
  *
  * @param server  — MCP server instance.
  * @param context — Shared runtime context with SAP client, connection, and config.
@@ -1094,7 +1115,7 @@ function registerPerpBuildModifyTool(server, _context) {
  * @usedBy `register-tools.ts`
  */
 export function registerPerpTools(server, context) {
-    logger.debug('Registering perp trading and chart tools');
+    logger.debug('Registering perp trading analytics and planning tools');
     registerPerpMarketsTool(server, context);
     registerPerpPositionInfoTool(server, context);
     registerPerpFundingHistoryTool(server, context);
@@ -1102,9 +1123,7 @@ export function registerPerpTools(server, context) {
     registerChartLongTermTool(server, context);
     registerChartVolumeProfileTool(server, context);
     registerPerpLiquidationZonesTool(server, context);
-    registerPerpBuildOpenTool(server, context);
-    registerPerpBuildCloseTool(server, context);
-    registerPerpBuildModifyTool(server, context);
-    logger.debug('Perp tools registered', { count: 10 });
+    registerPerpTradePlanTool(server);
+    logger.debug('Perp tools registered', { count: 8 });
 }
 //# sourceMappingURL=perp-tools.js.map