@oobe-protocol-labs/sap-mcp-server 0.3.0 → 0.7.1

package/dist/tools/magicblock-tools.js

@@ -0,0 +1,578 @@
+/**
+ * MagicBlock MCP Tools
+ *
+ * Registers 20 MagicBlock tools across 3 protocol domains:
+ *   - mb-router   (6 read-only ER Router JSON-RPC tools)
+ *   - mb-payments (12 Private Payment API REST tools)
+ *   - mb-vrf      (2 Solana VRF tools — on-chain via @solana/web3.js)
+ *
+ * Pricing:
+ *   READ  = $0.01/call (10_000 USDC base units) — 14 read-only tools
+ *   WRITE = $0.05/call (50_000 USDC base units) — 6 transaction-building tools
+ *
+ * Write tools (deposit, transfer, withdraw, swap, initializeMint) return
+ * unsigned transactions. The caller must sign with sap_sign_transaction
+ * and submit with sap_submit_signed_transaction to the RPC indicated by
+ * the `sendTo` field ("base" or "ephemeral").
+ */
+import { PublicKey, TransactionInstruction, Transaction, SystemProgram } 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';
+// ═══════════════════════════════════════════════════════════════════
+//  Constants
+// ═══════════════════════════════════════════════════════════════════
+const ROUTER_ENDPOINTS = {
+    mainnet: 'https://router.magicblock.app',
+    devnet: 'https://devnet-router.magicblock.app',
+};
+const PAYMENTS_ENDPOINT = 'https://payments.magicblock.app';
+const JSONRPC_VERSION = '2.0';
+// ─── VRF Program Constants (from ephemeral_vrf_sdk::consts) ───────
+const VRF_PROGRAM_ID = new PublicKey('Vrf1RNUjXmQGjmQrQLvJHs9SNkvDJEsRVFPkfSQUwGz');
+const VRF_PROGRAM_IDENTITY = new PublicKey('9irBy75QS2BN81FUgXuHcjqceJJRuc9oDkAe8TKVvvAw');
+const DEFAULT_QUEUE = new PublicKey('Cuj97ggrhhidhbu39TijNVqE74xvKJ69gDervRUXAxGh');
+const DEFAULT_EPHEMERAL_QUEUE = new PublicKey('5hBR571xnXppuCPveTrctfTU7tJLSN94nq7kv7FRK5Tc');
+// ─── Pricing Constants ────────────────────────────────────────────
+const READ_PRICE_USDC = 10000n;
+const WRITE_PRICE_USDC = 50000n;
+const READ_TOOLS = new Set([
+    'magicblock_getRoutes', 'magicblock_getIdentity', 'magicblock_getDelegationStatus',
+    'magicblock_getAccountInfo', 'magicblock_getBlockhashForAccounts', 'magicblock_getSignatureStatuses',
+    'magicblock_health', 'magicblock_challenge', 'magicblock_login',
+    'magicblock_balance', 'magicblock_privateBalance', 'magicblock_swapQuote',
+    'magicblock_isMintInitialized', 'magicblock_getRandomnessResult',
+]);
+const WRITE_TOOLS = new Set([
+    'magicblock_deposit', 'magicblock_transfer', 'magicblock_withdraw',
+    'magicblock_swap', 'magicblock_initializeMint', 'magicblock_requestRandomness',
+]);
+function getPriceForTool(toolName) {
+    if (READ_TOOLS.has(toolName))
+        return READ_PRICE_USDC;
+    if (WRITE_TOOLS.has(toolName))
+        return WRITE_PRICE_USDC;
+    throw new Error(`No pricing defined for tool: ${toolName}`);
+}
+async function rpcCall(endpoint, method, params) {
+    const url = ROUTER_ENDPOINTS[endpoint];
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ jsonrpc: JSONRPC_VERSION, id: 1, method, params }),
+    });
+    const text = await res.text();
+    if (!res.ok)
+        throw new Error(`MagicBlock Router ${res.status}: ${text.slice(0, 200)}`);
+    const json = JSON.parse(text);
+    if (json.error)
+        throw new Error(`JSON-RPC error ${json.error.code}: ${json.error.message}`);
+    if (!json.result)
+        throw new Error(`JSON-RPC response missing result for ${method}`);
+    return json.result;
+}
+async function apiGet(path, query, authToken) {
+    const url = new URL(PAYMENTS_ENDPOINT + path);
+    if (query) {
+        for (const [key, value] of Object.entries(query)) {
+            if (value != null)
+                url.searchParams.set(key, value);
+        }
+    }
+    const headers = {};
+    if (authToken)
+        headers['Authorization'] = `Bearer ${authToken}`;
+    const res = await fetch(url.toString(), { method: 'GET', headers });
+    const text = await res.text();
+    if (!res.ok)
+        throw new Error(`MagicBlock API ${res.status}: ${text.slice(0, 200)}`);
+    return JSON.parse(text);
+}
+async function apiPost(path, body, authToken) {
+    const url = PAYMENTS_ENDPOINT + path;
+    const headers = { 'Content-Type': 'application/json' };
+    if (authToken)
+        headers['Authorization'] = `Bearer ${authToken}`;
+    const res = await fetch(url, { method: 'POST', headers, body: JSON.stringify(body) });
+    const text = await res.text();
+    if (!res.ok)
+        throw new Error(`MagicBlock API ${res.status}: ${text.slice(0, 200)}`);
+    return JSON.parse(text);
+}
+/** Strip nullish values from an object. Returns a new object with only non-null values. */
+function stripNullish(obj) {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (value != null)
+            result[key] = value;
+    }
+    return result;
+}
+// ═══════════════════════════════════════════════════════════════════
+//  JSON Schema Helpers
+// ═══════════════════════════════════════════════════════════════════
+function schema(properties, required) {
+    return {
+        type: 'object',
+        properties,
+        ...(required && required.length > 0 ? { required } : {}),
+    };
+}
+const f = {
+    pubkey: (d) => ({ type: 'string', description: d }),
+    string: (d) => ({ type: 'string', description: d }),
+    number: (d) => ({ type: 'number', description: d }),
+    boolean: (d) => ({ type: 'boolean', description: d }),
+    enum: (d, values) => ({ type: 'string', enum: values, description: d }),
+    array: (d, items) => ({ type: 'array', items, description: d }),
+    object: (d, props) => ({ type: 'object', properties: props, description: d }),
+};
+const endpointField = f.enum("MagicBlock Router endpoint: 'mainnet' or 'devnet'", ['mainnet', 'devnet']);
+const clusterField = f.string("Cluster: 'mainnet', 'devnet', or custom RPC URL");
+const validatorField = f.string('Optional ER validator pubkey. Defaults to the selected ephemeral RPC identity.');
+// ═══════════════════════════════════════════════════════════════════
+//  Registration
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name registerMagicBlockTools
+ * @description Registers 20 MagicBlock tools (ER Router, Private Payments, VRF)
+ *   with the MCP server. Each tool is priced at $0.01 (read) or $0.05 (write).
+ * @param server - MCP server receiving tool definitions and handlers.
+ * @param context - Shared runtime context (VRF getRandomnessResult uses the Solana connection).
+ */
+export function registerMagicBlockTools(server, context) {
+    logger.debug('Registering MagicBlock tools');
+    let registered = 0;
+    function register(name, description, inputSchema, handler) {
+        registerTool(server, name, { title: name.replace(/_/g, ' '), description, inputSchema }, handler);
+        registered++;
+    }
+    function handleError(toolName, error) {
+        logger.error(`MagicBlock tool failed: ${toolName}`, { error });
+        const errorResponse = {
+            error: `MagicBlock tool ${toolName} failed`,
+            message: error instanceof Error ? error.message : 'Unknown error',
+        };
+        return createTextResponse(JSON.stringify(errorResponse, null, 2), { isError: true });
+    }
+    function success(data, toolName) {
+        const price = getPriceForTool(toolName);
+        const priceUsd = Number(price) / 1e6;
+        const response = {
+            success: true,
+            tool: toolName,
+            priceUsd: `$${priceUsd.toFixed(2)}`,
+            priceBaseUnits: price.toString(),
+            data,
+        };
+        return createTextResponse(JSON.stringify(response, null, 2));
+    }
+    function parseInput(raw) {
+        return raw;
+    }
+    // ═══════════════════════════════════════════════════════════════
+    //  ER Router (6 read-only tools)
+    // ═══════════════════════════════════════════════════════════════
+    register('magicblock_getRoutes', 'List available Ephemeral Rollup nodes from the Magic Router (identity, FQDN, fee, block time, country). Price: $0.01.', schema({ endpoint: endpointField }), async (raw) => {
+        try {
+            const { endpoint = 'devnet' } = parseInput(raw);
+            const routes = await rpcCall(endpoint, 'getRoutes', []);
+            return success({ routes }, 'magicblock_getRoutes');
+        }
+        catch (e) {
+            return handleError('magicblock_getRoutes', e);
+        }
+    });
+    register('magicblock_getIdentity', 'Get the identity and FQDN of the current ER Validator node. Price: $0.01.', schema({ endpoint: endpointField }), async (raw) => {
+        try {
+            const { endpoint = 'devnet' } = parseInput(raw);
+            const identity = await rpcCall(endpoint, 'getIdentity', []);
+            return success(identity, 'magicblock_getIdentity');
+        }
+        catch (e) {
+            return handleError('magicblock_getIdentity', e);
+        }
+    });
+    register('magicblock_getDelegationStatus', 'Check whether a Solana account is delegated to an Ephemeral Rollup. Returns authority, owner, delegation slot, and lamports. Price: $0.01.', schema({ account: f.pubkey('Account pubkey to check delegation status for'), endpoint: endpointField }, ['account']), async (raw) => {
+        try {
+            const { account, endpoint = 'devnet' } = parseInput(raw);
+            const status = await rpcCall(endpoint, 'getDelegationStatus', [account]);
+            return success(status, 'magicblock_getDelegationStatus');
+        }
+        catch (e) {
+            return handleError('magicblock_getDelegationStatus', e);
+        }
+    });
+    register('magicblock_getAccountInfo', 'Fetch account information (data, lamports, owner, executable, space) via the Magic Router. Price: $0.01.', schema({ account: f.pubkey('Account pubkey to fetch info for'), encoding: f.enum('Encoding for account data', ['base64', 'base64+zstd']), endpoint: endpointField }, ['account']), async (raw) => {
+        try {
+            const { account, encoding = 'base64', endpoint = 'devnet' } = parseInput(raw);
+            const info = await rpcCall(endpoint, 'getAccountInfo', [account, { encoding }]);
+            return success(info, 'magicblock_getAccountInfo');
+        }
+        catch (e) {
+            return handleError('magicblock_getAccountInfo', e);
+        }
+    });
+    register('magicblock_getBlockhashForAccounts', 'Get a blockhash and last valid block height for a batch of account addresses (max 100). Price: $0.01.', schema({ accounts: f.array('Array of account addresses (max 100)', f.pubkey('Account pubkey')), endpoint: endpointField }, ['accounts']), async (raw) => {
+        try {
+            const { accounts, endpoint = 'devnet' } = parseInput(raw);
+            const blockhash = await rpcCall(endpoint, 'getBlockhashForAccounts', [accounts]);
+            return success(blockhash, 'magicblock_getBlockhashForAccounts');
+        }
+        catch (e) {
+            return handleError('magicblock_getBlockhashForAccounts', e);
+        }
+    });
+    register('magicblock_getSignatureStatuses', 'Check the confirmation status (processed/confirmed/finalized) of one or more transaction signatures. Price: $0.01.', schema({ signatures: f.array('Array of transaction signatures', f.string('Transaction signature (base58)')), endpoint: endpointField }, ['signatures']), async (raw) => {
+        try {
+            const { signatures, endpoint = 'devnet' } = parseInput(raw);
+            const statuses = await rpcCall(endpoint, 'getSignatureStatuses', [signatures]);
+            return success(statuses, 'magicblock_getSignatureStatuses');
+        }
+        catch (e) {
+            return handleError('magicblock_getSignatureStatuses', e);
+        }
+    });
+    // ═══════════════════════════════════════════════════════════════
+    //  Private Payment API — Meta & Auth (3 tools)
+    // ═══════════════════════════════════════════════════════════════
+    register('magicblock_health', 'Check the health status of the MagicBlock Private Payments API. Price: $0.01.', schema({}), async () => {
+        try {
+            const health = await apiGet('/health');
+            return success(health, 'magicblock_health');
+        }
+        catch (e) {
+            return handleError('magicblock_health', e);
+        }
+    });
+    register('magicblock_challenge', 'Generate a challenge string for the wallet to sign (step 1 of the PER auth flow). Price: $0.01.', schema({ pubkey: f.pubkey('Wallet pubkey that will sign the challenge'), cluster: clusterField, mock: f.boolean('Use a mock challenge for testing (default false)') }, ['pubkey']), async (raw) => {
+        try {
+            const { pubkey, cluster, mock } = parseInput(raw);
+            const result = await apiGet('/v1/spl/challenge', {
+                pubkey, cluster: cluster ?? undefined, mock: mock ? 'true' : undefined,
+            });
+            return success(result, 'magicblock_challenge');
+        }
+        catch (e) {
+            return handleError('magicblock_challenge', e);
+        }
+    });
+    register('magicblock_login', 'Exchange a signed challenge for a bearer token (step 2 of PER auth flow). The token is used for private-balance and private transfers. Price: $0.01.', schema({ pubkey: f.pubkey('Wallet pubkey that signed the challenge'), challenge: f.string('Challenge string from magicblock_challenge'), signature: f.string('Wallet signature over the challenge string'), cluster: clusterField, mock: f.boolean('Use mock login flow (default false)') }, ['pubkey', 'challenge', 'signature']), async (raw) => {
+        try {
+            const { pubkey, challenge, signature, cluster, mock } = parseInput(raw);
+            const result = await apiPost('/v1/spl/login', {
+                pubkey, challenge, signature, cluster: cluster ?? undefined, mock: mock || undefined,
+            });
+            return success(result, 'magicblock_login');
+        }
+        catch (e) {
+            return handleError('magicblock_login', e);
+        }
+    });
+    // ═══════════════════════════════════════════════════════════════
+    //  Private Payment API — Balance (2 tools)
+    // ═══════════════════════════════════════════════════════════════
+    register('magicblock_balance', 'Read the base-chain SPL token balance for an address (public, no auth required). Price: $0.01.', schema({ address: f.pubkey('Owner wallet pubkey'), mint: f.string('SPL mint pubkey'), cluster: clusterField }, ['address', 'mint']), async (raw) => {
+        try {
+            const { address, mint, cluster } = parseInput(raw);
+            const result = await apiGet('/v1/spl/balance', { address, mint, cluster: cluster ?? undefined });
+            return success(result, 'magicblock_balance');
+        }
+        catch (e) {
+            return handleError('magicblock_balance', e);
+        }
+    });
+    register('magicblock_privateBalance', 'Read the ephemeral-rollup SPL token balance for an address (requires bearer token from login). Price: $0.01.', schema({ address: f.pubkey('Owner wallet pubkey'), mint: f.string('SPL mint pubkey'), cluster: clusterField, authToken: f.string('Bearer token from magicblock_login (required for private reads)') }, ['address', 'mint', 'authToken']), async (raw) => {
+        try {
+            const { address, mint, cluster, authToken } = parseInput(raw);
+            const result = await apiGet('/v1/spl/private-balance', { address, mint, cluster: cluster ?? undefined }, authToken);
+            return success(result, 'magicblock_privateBalance');
+        }
+        catch (e) {
+            return handleError('magicblock_privateBalance', e);
+        }
+    });
+    // ═══════════════════════════════════════════════════════════════
+    //  Private Payment API — SPL Token Flows (3 write tools)
+    // ═══════════════════════════════════════════════════════════════
+    register('magicblock_deposit', 'Build an unsigned transaction to deposit SPL tokens from Solana into an Ephemeral Rollup. Sign with sap_sign_transaction and submit to the RPC indicated by sendTo. Price: $0.05.', schema({ owner: f.pubkey('Wallet pubkey that owns the tokens and will sign'), amount: f.number('Base-unit amount to deposit (integer, minimum 1)'), mint: f.string('SPL mint. Defaults to USDC (mainnet) or devnet USDC'), cluster: clusterField, validator: validatorField, initIfMissing: f.boolean('Initialize the transfer queue if missing (default true)'), initVaultIfMissing: f.boolean('Initialize the vault if missing (default true)'), initAtasIfMissing: f.boolean('Initialize associated token accounts if missing (default true)'), idempotent: f.boolean('Use idempotent variants for preparatory init instructions (default true)') }, ['owner', 'amount']), async (raw) => {
+        try {
+            const input = parseInput(raw);
+            const result = await apiPost('/v1/spl/deposit', {
+                owner: input.owner, amount: input.amount, ...stripNullish({
+                    mint: input.mint, cluster: input.cluster, validator: input.validator,
+                    initIfMissing: input.initIfMissing, initVaultIfMissing: input.initVaultIfMissing,
+                    initAtasIfMissing: input.initAtasIfMissing, idempotent: input.idempotent,
+                }),
+            });
+            return success(result, 'magicblock_deposit');
+        }
+        catch (e) {
+            return handleError('magicblock_deposit', e);
+        }
+    });
+    register('magicblock_transfer', 'Build an unsigned SPL token transfer (public or private) through an Ephemeral Rollup. Supports base/ephemeral source and destination, delayed settlement, split transfers, and gasless mode. Price: $0.05.', schema({
+        from: f.pubkey('Sender wallet pubkey'), to: f.pubkey('Recipient wallet pubkey'), mint: f.string('SPL mint pubkey'),
+        amount: f.number('Base-unit amount to transfer (integer, minimum 1)'),
+        visibility: f.enum("'public' = transparent SPL transfer, 'private' = routed through Private ER with delayed+split settlement", ['public', 'private']),
+        fromBalance: f.enum("Where the sender's balance is held", ['base', 'ephemeral']),
+        toBalance: f.enum('Where the recipient should receive funds', ['base', 'ephemeral']),
+        cluster: clusterField, validator: f.string('Optional ER validator pubkey'),
+        authToken: f.string('Bearer token from login (required for private transfers)'),
+        initIfMissing: f.boolean('Initialize transfer queue if missing (default true)'),
+        initAtasIfMissing: f.boolean('Initialize recipient ATA if missing (default true)'),
+        initVaultIfMissing: f.boolean('Initialize vault if missing (default false)'),
+        memo: f.string('Optional memo appended to the transaction'),
+        minDelayMs: f.string("Private only. Earliest (ms) the queued transfer may settle. Default '0'"),
+        maxDelayMs: f.string('Private only. Latest (ms) the queued transfer may settle (<= 600000)'),
+        clientRefId: f.string('Private only. Encrypted client reference ID for payment confirmation'),
+        split: f.number('Private only. Number of queue entries to split across (1-15, default 1)'),
+        gasless: f.boolean('When true, uses configured sponsor as fee payer (default false)'),
+        legacy: f.boolean('Skip lookup-table compilation, return a legacy transaction (default false)'),
+    }, ['from', 'to', 'mint', 'amount', 'visibility', 'fromBalance', 'toBalance']), async (raw) => {
+        try {
+            const input = parseInput(raw);
+            const result = await apiPost('/v1/spl/transfer', {
+                from: input.from, to: input.to, mint: input.mint, amount: input.amount,
+                visibility: input.visibility, fromBalance: input.fromBalance, toBalance: input.toBalance,
+                ...stripNullish({
+                    cluster: input.cluster, validator: input.validator,
+                    initIfMissing: input.initIfMissing, initAtasIfMissing: input.initAtasIfMissing,
+                    initVaultIfMissing: input.initVaultIfMissing, memo: input.memo,
+                    minDelayMs: input.minDelayMs, maxDelayMs: input.maxDelayMs,
+                    clientRefId: input.clientRefId, split: input.split,
+                    gasless: input.gasless, legacy: input.legacy,
+                }),
+            }, input.authToken);
+            return success(result, 'magicblock_transfer');
+        }
+        catch (e) {
+            return handleError('magicblock_transfer', e);
+        }
+    });
+    register('magicblock_withdraw', 'Build an unsigned transaction to withdraw SPL tokens from an Ephemeral Rollup back to Solana. Price: $0.05.', schema({ owner: f.pubkey('Wallet pubkey that owns the tokens and will sign'), mint: f.string('SPL mint on Solana'), amount: f.number('Base-unit amount to withdraw (integer, minimum 1)'), cluster: clusterField, validator: f.string('Optional ER validator pubkey'), initIfMissing: f.boolean('Initialize transfer queue if missing (default true)'), initAtasIfMissing: f.boolean('Initialize ATAs if missing (default true)'), escrowIndex: f.number('Optional escrow index for the withdrawal'), idempotent: f.boolean('Use idempotent variants for preparatory init instructions (default true)') }, ['owner', 'mint', 'amount']), async (raw) => {
+        try {
+            const input = parseInput(raw);
+            const result = await apiPost('/v1/spl/withdraw', {
+                owner: input.owner, mint: input.mint, amount: input.amount,
+                ...stripNullish({
+                    cluster: input.cluster, validator: input.validator,
+                    initIfMissing: input.initIfMissing, initAtasIfMissing: input.initAtasIfMissing,
+                    escrowIndex: input.escrowIndex, idempotent: input.idempotent,
+                }),
+            });
+            return success(result, 'magicblock_withdraw');
+        }
+        catch (e) {
+            return handleError('magicblock_withdraw', e);
+        }
+    });
+    // ═══════════════════════════════════════════════════════════════
+    //  Private Payment API — Swap (2 tools)
+    // ═══════════════════════════════════════════════════════════════
+    register('magicblock_swapQuote', 'Get a swap quote between two SPL mints (proxies Triton Metis swap API). Pass the result into magicblock_swap. Price: $0.01.', schema({ inputMint: f.string('Input token mint address'), outputMint: f.string('Output token mint address'), amount: f.string("Raw amount to swap (unsigned integer string, e.g. '1000000')"), slippageBps: f.number('Slippage threshold in basis points (e.g. 50 = 0.5%)'), swapMode: f.enum('Swap mode: fixed input or fixed output amount', ['ExactIn', 'ExactOut']), onlyDirectRoutes: f.boolean('Limit routing to a single hop (default false)'), restrictIntermediateTokens: f.boolean('Restrict intermediate tokens to a more stable set (default false)'), platformFeeBps: f.number('Optional platform fee in basis points'), maxAccounts: f.number('Approximate maximum account budget for the route (default 64)') }, ['inputMint', 'outputMint', 'amount']), async (raw) => {
+        try {
+            const input = parseInput(raw);
+            const result = await apiGet('/v1/swap/quote', {
+                inputMint: input.inputMint, outputMint: input.outputMint, amount: input.amount,
+                slippageBps: input.slippageBps != null ? String(input.slippageBps) : undefined,
+                swapMode: input.swapMode,
+                onlyDirectRoutes: input.onlyDirectRoutes ? 'true' : undefined,
+                restrictIntermediateTokens: input.restrictIntermediateTokens ? 'true' : undefined,
+                platformFeeBps: input.platformFeeBps != null ? String(input.platformFeeBps) : undefined,
+                maxAccounts: input.maxAccounts != null ? String(input.maxAccounts) : undefined,
+            });
+            return success(result, 'magicblock_swapQuote');
+        }
+        catch (e) {
+            return handleError('magicblock_swapQuote', e);
+        }
+    });
+    register('magicblock_swap', "Build an unsigned swap transaction from a quote. 'public' mode passes through Jupiter, 'private' mode routes output through a scheduled private transfer with delay and split. Price: $0.05.", schema({ userPublicKey: f.pubkey('Wallet that will sign the swap transaction'), quoteResponse: f.object('Quote response object from magicblock_swapQuote (pass as-is)', {}), visibility: f.enum("'public' = transparent Jupiter pass-through, 'private' = output routed through scheduled private transfer", ['public', 'private']), destination: f.pubkey("Final private-transfer recipient (required when visibility='private')"), minDelayMs: f.string("Private only. Earliest (ms) the queued transfer may settle"), maxDelayMs: f.string("Private only. Latest (ms) the queued transfer may settle (<= 600000)"), split: f.number('Private only. Number of queue entries to split across (1-14)'), clientRefId: f.string('Private only. Optional u64 client correlation ID'), validator: f.string('Optional validator pubkey for the transfer-queue PDA'), wrapAndUnwrapSol: f.boolean('Auto wrap/unwrap native SOL when needed (default true)'), asLegacyTransaction: f.boolean('Build a legacy transaction (not allowed when visibility=private, default false)') }, ['userPublicKey', 'quoteResponse']), async (raw) => {
+        try {
+            const input = parseInput(raw);
+            const result = await apiPost('/v1/swap/swap', {
+                userPublicKey: input.userPublicKey, quoteResponse: input.quoteResponse,
+                ...stripNullish({
+                    visibility: input.visibility, destination: input.destination,
+                    minDelayMs: input.minDelayMs, maxDelayMs: input.maxDelayMs,
+                    split: input.split, clientRefId: input.clientRefId,
+                    validator: input.validator, wrapAndUnwrapSol: input.wrapAndUnwrapSol,
+                    asLegacyTransaction: input.asLegacyTransaction,
+                }),
+            });
+            return success(result, 'magicblock_swap');
+        }
+        catch (e) {
+            return handleError('magicblock_swap', e);
+        }
+    });
+    // ═══════════════════════════════════════════════════════════════
+    //  Private Payment API — Mint Init (2 tools)
+    // ═══════════════════════════════════════════════════════════════
+    register('magicblock_initializeMint', 'Build an unsigned transaction that initializes a validator-scoped transfer queue for a mint. Price: $0.05.', schema({ owner: f.pubkey('Wallet pubkey that will sign the transaction'), mint: f.string('SPL mint to initialize a transfer queue for'), cluster: clusterField, validator: f.string('Optional ER validator pubkey') }, ['owner', 'mint']), async (raw) => {
+        try {
+            const input = parseInput(raw);
+            const result = await apiPost('/v1/spl/initialize-mint', {
+                owner: input.owner, mint: input.mint, ...stripNullish({ cluster: input.cluster, validator: input.validator }),
+            });
+            return success(result, 'magicblock_initializeMint');
+        }
+        catch (e) {
+            return handleError('magicblock_initializeMint', e);
+        }
+    });
+    register('magicblock_isMintInitialized', 'Check whether a mint has a validator-scoped transfer queue on the ephemeral RPC. Price: $0.01.', schema({ mint: f.string('SPL mint to check'), cluster: clusterField, validator: f.string('Optional ER validator pubkey') }, ['mint']), async (raw) => {
+        try {
+            const input = parseInput(raw);
+            const result = await apiGet('/v1/spl/is-mint-initialized', {
+                mint: input.mint, cluster: input.cluster ?? undefined, validator: input.validator ?? undefined,
+            });
+            return success(result, 'magicblock_isMintInitialized');
+        }
+        catch (e) {
+            return handleError('magicblock_isMintInitialized', e);
+        }
+    });
+    // ═══════════════════════════════════════════════════════════════
+    //  VRF (2 tools — on-chain via @solana/web3.js)
+    // ═══════════════════════════════════════════════════════════════
+    register('magicblock_requestRandomness', 'Request provably fair on-chain randomness from the MagicBlock VRF oracle (Vrf1RNUjXmQGjmQrQLvJHs9SNkvDJEsRVFPkfSQUwGz). Builds an unsigned transaction that invokes request_randomness on the VRF program. The caller must sign with sap_sign_transaction and submit to Solana. The oracle queue defaults to the base-layer queue (Cuj97ggrhhidhbu39TijNVqE74xvKJ69gDervRUXAxGh); set ephemeral=true to use the ER queue for delegated programs. Price: $0.05.', schema({
+        payer: f.pubkey('Wallet pubkey that will pay for the request and sign the transaction'),
+        callbackProgramId: f.pubkey('Program ID of the callback program (the program that will consume the randomness)'),
+        callbackDiscriminator: f.string('Base58 or hex discriminator for the callback instruction in your program'),
+        callerSeed: f.string('Seed string for the VRF request — committed before randomness is produced. The seed is hashed to 32 bytes.'),
+        callbackAccounts: f.array('Accounts to pass to the callback instruction', f.object('Callback account metadata', { pubkey: f.pubkey('Account pubkey'), isSigner: f.boolean('Whether the account is a signer'), isWritable: f.boolean('Whether the account is writable') })),
+        ephemeral: f.boolean('Use the Ephemeral Rollup oracle queue instead of the base-layer queue (default false)'),
+        endpoint: endpointField,
+    }, ['payer', 'callbackProgramId', 'callbackDiscriminator', 'callerSeed', 'callbackAccounts']), async (raw) => {
+        try {
+            const input = parseInput(raw);
+            const payer = new PublicKey(input.payer);
+            const callbackProgramId = new PublicKey(input.callbackProgramId);
+            const oracleQueue = input.ephemeral ? DEFAULT_EPHEMERAL_QUEUE : DEFAULT_QUEUE;
+            const callerSeed = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(input.callerSeed)));
+            // Parse callback discriminator: accept hex (0x-prefixed) or base58.
+            let callbackDiscriminator;
+            if (input.callbackDiscriminator.startsWith('0x')) {
+                callbackDiscriminator = Array.from(Buffer.from(input.callbackDiscriminator.slice(2), 'hex'));
+            }
+            else {
+                const bs58 = await import('bs58');
+                callbackDiscriminator = Array.from(bs58.default.decode(input.callbackDiscriminator));
+            }
+            // Build callback account metas
+            const accountMetas = input.callbackAccounts.map((acc) => ({
+                pubkey: new PublicKey(acc.pubkey),
+                isSigner: acc.isSigner ?? false,
+                isWritable: acc.isWritable ?? false,
+            }));
+            // Derive the request PDA
+            const [requestKey] = PublicKey.findProgramAddressSync([Buffer.from('vrf_request'), payer.toBuffer(), oracleQueue.toBuffer(), callerSeed], VRF_PROGRAM_ID);
+            // Build the request_randomness instruction data
+            const data = Buffer.alloc(1024);
+            let offset = 0;
+            // Anchor instruction discriminator (first 8 bytes of sha256("global:request_randomness"))
+            const discHash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode('global:request_randomness'));
+            const discBytes = new Uint8Array(discHash).slice(0, 8);
+            for (let i = 0; i < 8; i++)
+                data.writeUInt8(discBytes[i], offset++);
+            oracleQueue.toBuffer().copy(data, offset);
+            offset += 32;
+            callbackProgramId.toBuffer().copy(data, offset);
+            offset += 32;
+            data.writeUInt32LE(callbackDiscriminator.length, offset);
+            offset += 4;
+            Buffer.from(callbackDiscriminator).copy(data, offset);
+            offset += callbackDiscriminator.length;
+            Buffer.from(callerSeed).copy(data, offset);
+            offset += 32;
+            data.writeUInt32LE(accountMetas.length, offset);
+            offset += 4;
+            for (const meta of accountMetas) {
+                meta.pubkey.toBuffer().copy(data, offset);
+                offset += 32;
+                data.writeUInt8(meta.isSigner ? 1 : 0, offset++);
+                data.writeUInt8(meta.isWritable ? 1 : 0, offset++);
+            }
+            const ix = new TransactionInstruction({
+                programId: VRF_PROGRAM_ID,
+                keys: [
+                    { pubkey: payer, isSigner: true, isWritable: true },
+                    { pubkey: oracleQueue, isSigner: false, isWritable: true },
+                    { pubkey: requestKey, isSigner: false, isWritable: true },
+                    { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+                    { pubkey: VRF_PROGRAM_IDENTITY, isSigner: false, isWritable: false },
+                ],
+                data: data.subarray(0, offset),
+            });
+            const tx = new Transaction();
+            tx.add(ix);
+            const serializedTx = Buffer.from(tx.serialize({ requireAllSignatures: false })).toString('base64');
+            const result = {
+                requestKey: requestKey.toBase58(),
+                vrfProgramId: VRF_PROGRAM_ID.toBase58(),
+                oracleQueue: oracleQueue.toBase58(),
+                transactionBase64: serializedTx,
+                sendTo: 'base',
+                callbackProgramId: callbackProgramId.toBase58(),
+                callerSeedHash: Buffer.from(callerSeed).toString('hex'),
+                note: 'Sign with sap_sign_transaction, then submit with sap_submit_signed_transaction. After submission, poll magicblock_getRandomnessResult with the requestKey until fulfilled=true.',
+            };
+            return success(result, 'magicblock_requestRandomness');
+        }
+        catch (e) {
+            return handleError('magicblock_requestRandomness', e);
+        }
+    });
+    register('magicblock_getRandomnessResult', 'Check whether a VRF request has been fulfilled by reading the RandomnessRequest account on-chain. Returns fulfilled status, random bytes (if available), and the request metadata. Price: $0.01.', schema({ requestKey: f.pubkey('VRF request PDA key from magicblock_requestRandomness'), endpoint: endpointField }, ['requestKey']), async (raw) => {
+        try {
+            const { requestKey: requestKeyStr } = parseInput(raw);
+            const requestKey = new PublicKey(requestKeyStr);
+            const accountInfo = await context.connection.getAccountInfo(requestKey, 'confirmed');
+            if (!accountInfo) {
+                const result = {
+                    fulfilled: false, requestKey: requestKey.toBase58(),
+                    randomness: null, randomnessHex: null, callerSeed: '',
+                    owner: '', lamports: 0, executable: false, rentEpoch: 0, dataLength: 0,
+                    message: 'Request account not found. The request may not have been submitted yet, or the transaction has not been confirmed.',
+                };
+                return success(result, 'magicblock_getRandomnessResult');
+            }
+            const data = accountInfo.data;
+            if (data.length < 73) {
+                const result = {
+                    fulfilled: false, requestKey: requestKey.toBase58(),
+                    randomness: null, randomnessHex: null, callerSeed: '',
+                    owner: accountInfo.owner.toBase58(), lamports: accountInfo.lamports,
+                    executable: accountInfo.executable, rentEpoch: accountInfo.rentEpoch, dataLength: data.length,
+                    message: 'Account data too short — request may be in an unexpected state.',
+                };
+                return success(result, 'magicblock_getRandomnessResult');
+            }
+            // Layout: 8-byte discriminator + 32-byte caller_seed + 32-byte randomness
+            const discriminatorEnd = 8;
+            const callerSeed = data.subarray(discriminatorEnd, discriminatorEnd + 32);
+            const randomness = data.subarray(discriminatorEnd + 32, discriminatorEnd + 64);
+            const isZero = randomness.every((byte) => byte === 0);
+            const fulfilled = !isZero;
+            const result = {
+                fulfilled, requestKey: requestKey.toBase58(),
+                randomness: fulfilled ? Array.from(randomness) : null,
+                randomnessHex: fulfilled ? Buffer.from(randomness).toString('hex') : null,
+                callerSeed: Buffer.from(callerSeed).toString('hex'),
+                owner: accountInfo.owner.toBase58(), lamports: accountInfo.lamports,
+                executable: accountInfo.executable, rentEpoch: accountInfo.rentEpoch, dataLength: data.length,
+                message: fulfilled
+                    ? 'Randomness has been produced and verified. Use the random bytes in your callback logic.'
+                    : 'Request submitted but not yet fulfilled. Poll again in a few seconds.',
+            };
+            return success(result, 'magicblock_getRandomnessResult');
+        }
+        catch (e) {
+            return handleError('magicblock_getRandomnessResult', e);
+        }
+    });
+    logger.debug('MagicBlock tools registered', { count: registered });
+}
+//# sourceMappingURL=magicblock-tools.js.map