@dfm-fi/agent 0.2.1916 → 0.2.1941

package/dist/mcp-server.js

@@ -70,6 +70,8 @@ import { DEFAULT_OWNER_KEY_PATH, ownerKeyPath, policyUpdateNotice, runCreateAppW
 import { getTestWalletPubkey, signBase64Transaction } from './signing.js';
 import { ONBOARDING_ORDER, avatarPath, ensureIdentityWallet, loadAvatar, mintAndStoreKey, runOnboard } from './onboarding.js';
 import { makeIdentityGuard, makeKeyOwnerLookup, makeSessionFetch, onboardingApi } from './onboarding-api.js';
+import { existingOwnerKey, runOwnerAction } from './owner-actions.js';
+import { Connection } from '@solana/web3.js';
 import { buildWalletIdentity, resolveZapStatusWallet, withActingWalletAlias, withPortfolioWalletAlias, } from './wallet-identity.js';
 const config = loadConfig();
 const session = new SiwsSession(config);
@@ -164,6 +166,30 @@ const errText = (msg) => ({
  * unsigned tx (`ownerSignature`) that only the owner can sign in the app; an
  * MCP client cannot, so say so instead of reporting an empty signature.
  */
+/**
+ * Agent-owned app wallet: when the API answers `ownerSignature` and THIS
+ * machine holds the wallet's P-256 owner key, complete the action here —
+ * the tx is decoded and verified locally before the key signs anything
+ * (owner-actions.ts). Returns null when there is no local owner key (a
+ * Privy-user wallet keeps "approve in the app").
+ */
+async function ownerSignLocally(res, input) {
+    if (!(res && typeof res === 'object' && 'ownerSignature' in res && res.ownerSignature))
+        return null;
+    const key = existingOwnerKey();
+    if (!key)
+        return null;
+    await assertSameIdentity();
+    const conn = new Connection(config.rpcUrl || 'https://api.mainnet-beta.solana.com', 'confirmed');
+    return text(await runOwnerAction({
+        key,
+        signInWallet: session.walletAddress,
+        appWallet: async () => (await api.getOperatingWallet())?.operatingWalletAddress,
+        prepare: (i) => onboardApi.prepareOwnerAction(i),
+        submit: (id, sig) => onboardApi.submitOwnerAction(id, sig),
+        resolveAlt: async (k) => (await conn.getAddressLookupTable(k)).value,
+    }, input));
+}
 function ownerApprovalOr(res, what, where) {
     if (res && typeof res === 'object' && 'ownerSignature' in res && res.ownerSignature) {
         return errText(`not executed: your app wallet is yours (user-owned), so this ${what} needs your one-click approval in the app — open https://app.dfm.finance → ${where}.`);
@@ -638,6 +664,28 @@ server.registerTool('onboard', {
         return errText(`onboard failed: ${e.message}`);
     }
 });
+server.registerTool('close_empty_accounts', {
+    title: 'Close empty token accounts (agent-owned app wallet)',
+    description: 'Close every EMPTY token account of this agent\'s own app wallet (owner = the local P-256 key from ' +
+        'create_app_wallet) and send the rent to the sign-in wallet (default) or back to the app wallet. A ' +
+        'non-empty account is never included. The transaction is decoded and checked locally (only CloseAccount, ' +
+        'authority = the app wallet, rent to the chosen destination) before the owner key signs. Moves only rent.',
+    inputSchema: {
+        destination: z.enum(['sign_in_wallet', 'app_wallet']).optional().describe('where the rent goes; default sign_in_wallet'),
+    },
+    annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: true },
+}, async ({ destination }) => {
+    const write = writeGate();
+    if (!write.ok)
+        return write.result;
+    try {
+        const out = await ownerSignLocally({ ownerSignature: true }, { kind: 'close_empty', ...(destination ? { destination } : {}) });
+        return out ?? errText('close_empty_accounts needs this agent\'s owner key (create_app_wallet); a Privy-user wallet reclaims rent in the app.');
+    }
+    catch (e) {
+        return errText(`close_empty_accounts failed: ${e.message}`);
+    }
+});
 server.registerTool('xp_status', {
     title: 'XP',
     description: "The user's XP (total and by kind: deposit, launch, profile, referral) and the top of the XP leaderboard.",
@@ -993,7 +1041,9 @@ async ({ inputMint, outputMint, amountRaw, slippageBps }) => {
     if (!write.ok)
         return write.result;
     try {
-        return ownerApprovalOr(await api.swap({ inputMint, outputMint, amountRaw, slippageBps }), 'swap', 'the Swap panel');
+        const res = await api.swap({ inputMint, outputMint, amountRaw, slippageBps });
+        return (await ownerSignLocally(res, { kind: 'swap', inputMint, outputMint, amountRaw, ...(slippageBps !== undefined ? { slippageBps } : {}) }))
+            ?? ownerApprovalOr(res, 'swap', 'the Swap panel');
     }
     catch (e) {
         return errText(e.message);
@@ -1345,7 +1395,9 @@ server.registerTool('withdraw_asset', {
     if (!write.ok)
         return write.result;
     try {
-        return ownerApprovalOr(await api.withdrawAppWalletAsset(mint, amount), 'withdrawal', 'Portfolio → App wallet');
+        const res = await api.withdrawAppWalletAsset(mint, amount);
+        return (await ownerSignLocally(res, { kind: 'withdraw_asset', mint, ...(amount !== undefined ? { amount: String(amount) } : {}) }))
+            ?? ownerApprovalOr(res, 'withdrawal', 'Portfolio → App wallet');
     }
     catch (e) {
         return errText(`withdraw_asset failed: ${e.message}`);

package/dist/onboarding-api.d.ts

@@ -37,6 +37,11 @@ export declare function onboardingApi(call: SessionFetch): {
     }) => Promise<Record<string, unknown>>;
     uploadAvatar: (bytes: Buffer, filename: string, mime: string) => Promise<Record<string, unknown>>;
     createApiKey: (body: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    /** Owner-signed actions (agent-owned wallets): build → the MCP decodes + signs → submit. */
+    prepareOwnerAction: (input: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    submitOwnerAction: (requestId: string, signature: string) => Promise<{
+        signature?: string;
+    }>;
     revokeApiKey: (id: string) => Promise<Record<string, unknown>>;
 };
 //# sourceMappingURL=onboarding-api.d.ts.map

package/dist/onboarding-api.js

@@ -96,6 +96,9 @@ export function onboardingApi(call) {
             return call('/profile/avatar', { method: 'POST', body: form });
         },
         createApiKey: (body) => call('/agent/keys', { method: 'POST', json: body }),
+        /** Owner-signed actions (agent-owned wallets): build → the MCP decodes + signs → submit. */
+        prepareOwnerAction: (input) => call('/agent/operating/embedded/agent-wallet/owner-request', { method: 'POST', json: input }),
+        submitOwnerAction: (requestId, signature) => call('/agent/operating/embedded/agent-wallet/owner-request/submit', { method: 'POST', json: { requestId, signature } }),
         revokeApiKey: (id) => call(`/agent/keys/${encodeURIComponent(id)}`, { method: 'DELETE' }),
     };
 }

package/dist/owner-actions.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Owner-signed actions for an AGENT-owned app wallet (the MCP side). When the
+ * API answers a swap / asset withdrawal with `ownerSignature` and this machine
+ * holds the wallet's P-256 owner key, the MCP completes it itself:
+ *   1. `owner-request` → the server builds + asserts the tx and returns the
+ *      exact Privy `signAndSendTransaction` RPC request to sign;
+ *   2. the request envelope is checked against PINNED values (Privy app id,
+ *      RPC url for that wallet, method, caip2, expiry ≤ 10 min) and the
+ *      payload is rebuilt locally;
+ *   3. `body.params.transaction` is decoded HERE and checked against what the
+ *      tool was asked to do (owner-tx-verify.ts) — a payload whose transaction
+ *      was not decoded and approved is never signed;
+ *   4. sign with the owner key, `owner-request/submit`.
+ */
+import { type OwnerKey } from './app-wallet-owner.js';
+import { type AltResolver } from './owner-tx-verify.js';
+export declare const SOLANA_MAINNET_CAIP2 = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+export type OwnerActionInput = {
+    kind: 'swap';
+    inputMint: string;
+    outputMint: string;
+    amountRaw: string;
+    slippageBps?: number;
+} | {
+    kind: 'withdraw_asset';
+    mint: string;
+    amount?: string;
+} | {
+    kind: 'close_empty';
+    destination?: 'sign_in_wallet' | 'app_wallet';
+};
+export interface OwnerRpcRequest {
+    status: 'awaiting_owner_signature';
+    requestId: string;
+    walletId: string;
+    appWallet: string;
+    url: string;
+    body: {
+        method: string;
+        caip2: string;
+        params: {
+            transaction: string;
+            encoding: string;
+        };
+    };
+    headers: Record<string, string>;
+    payload: string;
+    summary?: unknown;
+}
+/** The envelope: pinned app id, this wallet's RPC url, signAndSendTransaction on mainnet, fresh expiry. Returns the rebuilt payload. */
+export declare function checkOwnerRpcRequest(r: OwnerRpcRequest, now?: number): string;
+/** The owner key, ONLY if it already exists on this machine (never created here). */
+export declare function existingOwnerKey(path?: string): OwnerKey | null;
+export declare const DEFAULT_SWAP_SLIPPAGE_BPS = 50;
+/**
+ * The MCP's OWN Jupiter quote (review S20), straight from Jupiter — never via
+ * DFM — so a compromised server cannot make the owner sign a route with a
+ * near-zero minimum output. No key needed; `DFM_JUPITER_QUOTE_URL` overrides.
+ * Any failure throws: no independent quote, no signature.
+ */
+export declare function fetchOwnQuote(q: {
+    inputMint: string;
+    outputMint: string;
+    amountRaw: string;
+    slippageBps: number;
+    platformFeeBps?: number;
+}, doFetch?: typeof fetch): Promise<bigint>;
+export interface OwnerActionDeps {
+    key: OwnerKey;
+    signInWallet: string;
+    /**
+     * The app wallet as GET /agent/operating reports it. NOT a security control
+     * (both values come from DFM's server — review S23): it only catches a
+     * confused request early. What binds the signature is the walletId inside
+     * the signed URL (Privy signs with exactly that wallet) plus the locally
+     * checked destinations (the app wallet's own ATAs, the local sign-in wallet).
+     */
+    appWallet(): Promise<string | undefined>;
+    /** Independent Jupiter quote (swap only). */
+    ownQuote?(q: {
+        inputMint: string;
+        outputMint: string;
+        amountRaw: string;
+        slippageBps: number;
+        platformFeeBps?: number;
+    }): Promise<bigint>;
+    prepare(input: OwnerActionInput): Promise<Record<string, unknown>>;
+    submit(requestId: string, signature: string): Promise<{
+        signature?: string;
+    }>;
+    resolveAlt: AltResolver;
+}
+export declare function runOwnerAction(deps: OwnerActionDeps, input: OwnerActionInput): Promise<Record<string, unknown>>;
+//# sourceMappingURL=owner-actions.d.ts.map

package/dist/owner-actions.js

@@ -0,0 +1,109 @@
+/**
+ * Owner-signed actions for an AGENT-owned app wallet (the MCP side). When the
+ * API answers a swap / asset withdrawal with `ownerSignature` and this machine
+ * holds the wallet's P-256 owner key, the MCP completes it itself:
+ *   1. `owner-request` → the server builds + asserts the tx and returns the
+ *      exact Privy `signAndSendTransaction` RPC request to sign;
+ *   2. the request envelope is checked against PINNED values (Privy app id,
+ *      RPC url for that wallet, method, caip2, expiry ≤ 10 min) and the
+ *      payload is rebuilt locally;
+ *   3. `body.params.transaction` is decoded HERE and checked against what the
+ *      tool was asked to do (owner-tx-verify.ts) — a payload whose transaction
+ *      was not decoded and approved is never signed;
+ *   4. sign with the owner key, `owner-request/submit`.
+ */
+import { MAX_REQUEST_EXPIRY_AHEAD_MS, canonicalJson, lstatOrNull, loadOrCreateOwnerKey, ownerKeyPath, signerPins } from './app-wallet-owner.js';
+import { decodeTx, JUPITER_V6, MAX_PLATFORM_FEE_BPS, verifyCloseIxs, verifySwapIxs, verifyWithdrawIxs } from './owner-tx-verify.js';
+export const SOLANA_MAINNET_CAIP2 = 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp';
+const keysAre = (o, keys) => !!o && typeof o === 'object' && !Array.isArray(o) && Object.keys(o).sort().join() === [...keys].sort().join();
+/** The envelope: pinned app id, this wallet's RPC url, signAndSendTransaction on mainnet, fresh expiry. Returns the rebuilt payload. */
+export function checkOwnerRpcRequest(r, now = Date.now()) {
+    const pins = signerPins();
+    const url = `https://api.privy.io/v1/wallets/${encodeURIComponent(r.walletId)}/rpc`;
+    const exp = r.headers?.['privy-request-expiry'];
+    const ok = typeof r.walletId === 'string' && r.walletId.length > 0 &&
+        r.url === url &&
+        keysAre(r.body, ['method', 'caip2', 'params']) &&
+        r.body.method === 'signAndSendTransaction' &&
+        r.body.caip2 === SOLANA_MAINNET_CAIP2 &&
+        keysAre(r.body.params, ['transaction', 'encoding']) &&
+        r.body.params.encoding === 'base64' &&
+        typeof r.body.params.transaction === 'string' &&
+        keysAre(r.headers, ['privy-app-id', 'privy-request-expiry']) &&
+        r.headers['privy-app-id'] === pins.appId &&
+        typeof exp === 'string' && /^\d{13}$/.test(exp) &&
+        Number(exp) > now && Number(exp) <= now + MAX_REQUEST_EXPIRY_AHEAD_MS;
+    if (!ok)
+        throw new Error('refusing to sign: the owner request is not a signAndSendTransaction for this wallet on DFM’s Privy app, expiring within 10 min');
+    const payload = canonicalJson({ version: 1, method: 'POST', url, body: r.body, headers: r.headers });
+    if (payload !== r.payload)
+        throw new Error('refusing to sign: the server payload differs from the request it describes');
+    return payload;
+}
+/** The owner key, ONLY if it already exists on this machine (never created here). */
+export function existingOwnerKey(path = ownerKeyPath()) {
+    return lstatOrNull(path) ? loadOrCreateOwnerKey(path) : null;
+}
+export const DEFAULT_SWAP_SLIPPAGE_BPS = 50;
+/**
+ * The MCP's OWN Jupiter quote (review S20), straight from Jupiter — never via
+ * DFM — so a compromised server cannot make the owner sign a route with a
+ * near-zero minimum output. No key needed; `DFM_JUPITER_QUOTE_URL` overrides.
+ * Any failure throws: no independent quote, no signature.
+ */
+export async function fetchOwnQuote(q, doFetch = fetch) {
+    const base = process.env.DFM_JUPITER_QUOTE_URL?.trim() || 'https://lite-api.jup.ag/swap/v1/quote';
+    const url = `${base}?inputMint=${encodeURIComponent(q.inputMint)}&outputMint=${encodeURIComponent(q.outputMint)}` +
+        `&amount=${encodeURIComponent(q.amountRaw)}&slippageBps=${q.slippageBps}` +
+        // Same platform fee as the route, so the two outputs are comparable (S24 alignment with the web).
+        (q.platformFeeBps ? `&platformFeeBps=${q.platformFeeBps}` : '');
+    let out;
+    try {
+        const res = await doFetch(url, { signal: AbortSignal.timeout(10_000) });
+        if (!res.ok)
+            throw new Error(`status ${res.status}`);
+        out = (await res.json()).outAmount;
+    }
+    catch (e) {
+        throw new Error(`refusing to sign: no independent Jupiter quote (${e.message})`);
+    }
+    if (typeof out !== 'string' || !/^\d+$/.test(out) || BigInt(out) <= 0n)
+        throw new Error('refusing to sign: the independent Jupiter quote has no outAmount');
+    return BigInt(out);
+}
+export async function runOwnerAction(deps, input) {
+    const prepared = await deps.prepare(input);
+    if (prepared.status !== 'awaiting_owner_signature')
+        return prepared; // executed by DFM's signer / nothing to do
+    const r = prepared;
+    const payload = checkOwnerRpcRequest(r);
+    const app = await deps.appWallet();
+    if (!app || app !== r.appWallet)
+        throw new Error('refusing to sign: the request is for a different app wallet than this owner’s');
+    const { payer, ixs } = await decodeTx(r.body.params.transaction, deps.resolveAlt);
+    if (input.kind === 'swap') {
+        const slippageBps = input.slippageBps ?? DEFAULT_SWAP_SLIPPAGE_BPS;
+        const q = { inputMint: input.inputMint, outputMint: input.outputMint, amountRaw: input.amountRaw, slippageBps };
+        // The route's own platform fee (bounded ≤ 20 bps by the verifier) prices the independent quote.
+        const jup = ixs.find((x) => x.programId.toBase58() === JUPITER_V6);
+        const platformFeeBps = jup && jup.data.length >= 27 ? jup.data[jup.data.length - 1] : 0;
+        if (platformFeeBps > MAX_PLATFORM_FEE_BPS)
+            throw new Error(`refusing to sign: a platform fee of ${platformFeeBps} bps`);
+        const ownOutAmount = await (deps.ownQuote ?? fetchOwnQuote)({ ...q, platformFeeBps });
+        verifySwapIxs(payer, ixs, { appWallet: app, ...q, ownOutAmount });
+    }
+    else if (input.kind === 'withdraw_asset') {
+        verifyWithdrawIxs(payer, ixs, { appWallet: app, signInWallet: deps.signInWallet, mint: input.mint, ...(input.amount ? { amount: input.amount } : {}) });
+    }
+    else {
+        verifyCloseIxs(payer, ixs, { appWallet: app, destination: input.destination === 'app_wallet' ? app : deps.signInWallet });
+    }
+    const res = await deps.submit(r.requestId, deps.key.sign(payload));
+    return {
+        status: 'complete',
+        kind: input.kind,
+        signature: res.signature,
+        signedBy: 'agent owner key (decoded and verified locally before signing)',
+    };
+}
+//# sourceMappingURL=owner-actions.js.map

package/dist/owner-tx-verify.d.ts

@@ -0,0 +1,70 @@
+import { AddressLookupTableAccount, PublicKey, TransactionInstruction } from '@solana/web3.js';
+export declare const PROTOCOL_WALLET = "9GjEBsZ1Cos2J6inmgwhBKv9pXGNtLSJ7xQ9xZb29bET";
+export declare const MAX_SWAP_SOL_FEE_LAMPORTS = 50000000n;
+export declare const MAX_SWAP_SLIPPAGE_BPS = 1000;
+/** DFM's SWAP_PLATFORM_FEE_BPS — the only token platform fee a route may carry. */
+export declare const MAX_PLATFORM_FEE_BPS = 20;
+/** Price drift tolerated between the independent quote and the route's own quote. */
+export declare const QUOTE_DRIFT_BPS = 100n;
+export declare const MAX_COMPUTE_UNITS = 1400000n;
+export declare const MAX_PRIORITY_FEE_LAMPORTS = 1000000n;
+export declare const JUPITER_V6 = "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4";
+export declare const WSOL = "So11111111111111111111111111111111111111112";
+export declare const JUP_ROUTE: string;
+export declare const JUP_SHARED_ROUTE: string;
+/** ATA under either token program (the verifier never trusts a server-claimed program). */
+export declare function ataOf(owner: string, mint: string, program?: string): string;
+export type AltResolver = (key: PublicKey) => Promise<AddressLookupTableAccount | null>;
+/**
+ * Which account positions of each decoded instruction are STATIC keys (review
+ * S24). A lookup table's contents are served by an RPC the agent does not
+ * control, so an account the verifier CHECKS must not come from one — `key()`
+ * refuses a non-static (or unknown) position. Exported so a test that copies
+ * an instruction can carry the mask along.
+ */
+export declare const STATIC_MASK: WeakMap<TransactionInstruction, boolean[]>;
+export declare function decodeTx(txB64: string, resolveAlt: AltResolver): Promise<{
+    payer: string;
+    ixs: TransactionInstruction[];
+}>;
+export interface SwapExpect {
+    appWallet: string;
+    inputMint: string;
+    outputMint: string;
+    amountRaw: string;
+    /** Slippage the TOOL asked for (default 50). The route may not exceed it. */
+    slippageBps: number;
+    /** `outAmount` of the MCP's own Jupiter quote for the same input. */
+    ownOutAmount: bigint;
+}
+/**
+ * ComputeBudget (review S21): at most one SetComputeUnitLimit (≤ 1.4M), at most
+ * one SetComputeUnitPrice, total priority fee ≤ 0.001 SOL, RequestHeapFrame
+ * allowed; any other opcode refused. Without a limit ix the worst case (1.4M)
+ * prices the fee.
+ */
+export declare function checkComputeBudget(ixs: Array<{
+    programId: PublicKey;
+    data: Uint8Array;
+}>): void;
+/**
+ * The route's economics (review S20/S22): amount, slippage ≤ requested,
+ * platform fee ≤ 20 bps, and min-out (quoted × (1 − slippage)) ≥ the
+ * independent quote × (1 − requested slippage) × (1 − 0.5%). Returns the
+ * route's platform fee bps.
+ */
+export declare function checkJupiterEconomics(data: Uint8Array, e: Pick<SwapExpect, 'amountRaw' | 'slippageBps' | 'ownOutAmount'>): number;
+export declare function verifySwapIxs(payer: string, ixs: TransactionInstruction[], e: SwapExpect): void;
+export interface WithdrawExpect {
+    appWallet: string;
+    signInWallet: string;
+    mint: string;
+    amount?: string;
+}
+export declare function verifyWithdrawIxs(payer: string, ixs: TransactionInstruction[], e: WithdrawExpect): void;
+export interface CloseExpect {
+    appWallet: string;
+    destination: string;
+}
+export declare function verifyCloseIxs(payer: string, ixs: TransactionInstruction[], e: CloseExpect): void;
+//# sourceMappingURL=owner-tx-verify.d.ts.map

package/dist/owner-tx-verify.js

@@ -0,0 +1,341 @@
+/**
+ * INDEPENDENT decoding of an owner-signed transaction (agent-owned app
+ * wallets). The DFM server builds the tx and hands the agent a Privy RPC
+ * request to sign with its P-256 owner key; the owner key is ALL the authority
+ * there is (no policy binds the owner), so this file — not the server — decides
+ * whether it is safe to sign. It decodes `body.params.transaction` itself and
+ * accepts ONLY the shapes below; anything else is refused.
+ *
+ *  swap      ComputeBudget · ATA create(-idempotent) owned by the app wallet ·
+ *            wSOL wrap/unwrap on the app wallet's own wSOL ATA · exactly ONE
+ *            Jupiter v6 `route` / `shared_accounts_route` whose authority is
+ *            the app wallet, source = its input-mint ATA, destination = its
+ *            output-mint ATA, input amount = the requested amount, slippage ≤
+ *            the requested slippage, platform fee ≤ 20 bps to none or DFM's
+ *            (9GjE) ATA of either mint, and a quoted output that — after its
+ *            own slippage — is at least what an INDEPENDENT Jupiter quote
+ *            (fetched by the MCP, never via DFM) gives after the requested
+ *            slippage, minus 0.5% drift · at most one SOL transfer to 9GjE ≤
+ *            0.05 SOL, and only when the route carries no token fee ·
+ *            ComputeBudget: ≤ 1 unit limit (≤ 1.4M), ≤ 1 unit price with a
+ *            total priority fee ≤ 0.001 SOL, heap frame; nothing else.
+ *  withdraw  ATA create-idempotent for the SIGN-IN wallet · ONE transferChecked
+ *            of exactly that mint (and amount, when one was asked) from the app
+ *            wallet's ATA to the sign-in wallet's ATA · optional close of the
+ *            drained source ATA back to the app wallet.
+ *  close     only CloseAccount, authority = the app wallet, rent to the chosen
+ *            destination (app wallet or sign-in wallet).
+ *
+ * UNVERIFIED limits (fail closed): Jupiter `route_v2` / token-ledger variants
+ * and exact-out routes are refused, not decoded.
+ */
+import { createHash } from 'node:crypto';
+import { PublicKey, TransactionMessage, VersionedTransaction } from '@solana/web3.js';
+export const PROTOCOL_WALLET = '9GjEBsZ1Cos2J6inmgwhBKv9pXGNtLSJ7xQ9xZb29bET';
+export const MAX_SWAP_SOL_FEE_LAMPORTS = 50000000n;
+export const MAX_SWAP_SLIPPAGE_BPS = 1000;
+/** DFM's SWAP_PLATFORM_FEE_BPS — the only token platform fee a route may carry. */
+export const MAX_PLATFORM_FEE_BPS = 20;
+/** Price drift tolerated between the independent quote and the route's own quote. */
+export const QUOTE_DRIFT_BPS = 100n;
+export const MAX_COMPUTE_UNITS = 1400000n;
+export const MAX_PRIORITY_FEE_LAMPORTS = 1000000n;
+const SYSTEM = '11111111111111111111111111111111';
+const COMPUTE = 'ComputeBudget111111111111111111111111111111';
+const TOKEN = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA';
+const TOKEN22 = 'TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb';
+const ATA_PROGRAM = 'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL';
+export const JUPITER_V6 = 'JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4';
+export const WSOL = 'So11111111111111111111111111111111111111112';
+const disc = (n) => createHash('sha256').update(`global:${n}`).digest().subarray(0, 8).toString('hex');
+export const JUP_ROUTE = disc('route');
+export const JUP_SHARED_ROUTE = disc('shared_accounts_route');
+/** ATA under either token program (the verifier never trusts a server-claimed program). */
+export function ataOf(owner, mint, program = TOKEN) {
+    return PublicKey.findProgramAddressSync([new PublicKey(owner).toBuffer(), new PublicKey(program).toBuffer(), new PublicKey(mint).toBuffer()], new PublicKey(ATA_PROGRAM))[0].toBase58();
+}
+const atasOf = (owner, mint) => [ataOf(owner, mint, TOKEN), ataOf(owner, mint, TOKEN22)];
+/**
+ * Which account positions of each decoded instruction are STATIC keys (review
+ * S24). A lookup table's contents are served by an RPC the agent does not
+ * control, so an account the verifier CHECKS must not come from one — `key()`
+ * refuses a non-static (or unknown) position. Exported so a test that copies
+ * an instruction can carry the mask along.
+ */
+export const STATIC_MASK = new WeakMap();
+export async function decodeTx(txB64, resolveAlt) {
+    const tx = VersionedTransaction.deserialize(Buffer.from(txB64, 'base64'));
+    if (tx.message.header.numRequiredSignatures !== 1) {
+        throw new Error('refusing to sign: the transaction needs a signer other than the app wallet');
+    }
+    const nStatic = tx.message.staticAccountKeys.length;
+    const alts = [];
+    for (const lu of tx.message.addressTableLookups ?? []) {
+        const alt = await resolveAlt(lu.accountKey);
+        if (!alt)
+            throw new Error(`refusing to sign: lookup table ${lu.accountKey.toBase58()} could not be resolved`);
+        alts.push(alt);
+    }
+    const msg = TransactionMessage.decompile(tx.message, { addressLookupTableAccounts: alts });
+    tx.message.compiledInstructions.forEach((c, i) => {
+        if (c.programIdIndex >= nStatic)
+            throw new Error('refusing to sign: a program loaded from a lookup table');
+        STATIC_MASK.set(msg.instructions[i], c.accountKeyIndexes.map((idx) => idx < nStatic));
+    });
+    return { payer: msg.payerKey.toBase58(), ixs: msg.instructions };
+}
+const refuse = (why) => {
+    throw new Error(`refusing to sign: ${why}`);
+};
+/** A CHECKED account: must exist and be a static key of the message (S24). */
+const key = (ix, i) => {
+    const mask = STATIC_MASK.get(ix);
+    if (!mask || mask[i] !== true || !ix.keys[i])
+        refuse(`a checked account (#${i} of ${ix.programId.toBase58()}) is not a static key of the transaction`);
+    return ix.keys[i].pubkey.toBase58();
+};
+/**
+ * A MINT position may come from a lookup table (real Jupiter shared routes put
+ * the source mint there). Safe: every token account it pairs with is a STATIC
+ * key compared to an ATA derived HERE from the requested mint, and the token
+ * programs refuse an account whose mint differs — a lying ALT cannot make the
+ * swap move another mint out of the wallet. The value is still compared.
+ */
+const mintKey = (ix, i) => {
+    if (!STATIC_MASK.get(ix) || !ix.keys[i])
+        refuse(`a mint account (#${i}) of an instruction this decoder did not produce`);
+    return ix.keys[i].pubkey.toBase58();
+};
+const isToken = (p) => p === TOKEN || p === TOKEN22;
+/** ATA program create / create-idempotent, paid by the app wallet, for `owner`. */
+function checkAta(ix, app, owners) {
+    const d = ix.data;
+    if (!(d.length === 0 || (d.length === 1 && (d[0] === 0 || d[0] === 1))))
+        refuse('unexpected associated-token instruction');
+    if (key(ix, 0) !== app)
+        refuse('an account creation not paid by the app wallet');
+    if (!owners.includes(key(ix, 2)))
+        refuse('creates a token account for a foreign owner');
+}
+/**
+ * ComputeBudget (review S21): at most one SetComputeUnitLimit (≤ 1.4M), at most
+ * one SetComputeUnitPrice, total priority fee ≤ 0.001 SOL, RequestHeapFrame
+ * allowed; any other opcode refused. Without a limit ix the worst case (1.4M)
+ * prices the fee.
+ */
+export function checkComputeBudget(ixs) {
+    let limit = null;
+    let price = null;
+    for (const ix of ixs) {
+        if (ix.programId.toBase58() !== COMPUTE)
+            continue;
+        const d = Buffer.from(ix.data);
+        if (d[0] === 1 && d.length === 5)
+            continue; // RequestHeapFrame
+        if (d[0] === 2 && d.length === 5) {
+            if (limit !== null)
+                refuse('two compute unit limits');
+            limit = BigInt(d.readUInt32LE(1));
+            if (limit > MAX_COMPUTE_UNITS)
+                refuse('a compute unit limit above 1.4M');
+            continue;
+        }
+        if (d[0] === 3 && d.length === 9) {
+            if (price !== null)
+                refuse('two compute unit prices');
+            price = d.readBigUInt64LE(1);
+            continue;
+        }
+        refuse(`an unexpected ComputeBudget instruction (${d[0]})`);
+    }
+    const fee = ((limit ?? MAX_COMPUTE_UNITS) * (price ?? 0n)) / 1000000n;
+    if (fee > MAX_PRIORITY_FEE_LAMPORTS)
+        refuse(`a priority fee of ${fee} lamports (max 0.001 SOL)`);
+}
+/**
+ * The route's economics (review S20/S22): amount, slippage ≤ requested,
+ * platform fee ≤ 20 bps, and min-out (quoted × (1 − slippage)) ≥ the
+ * independent quote × (1 − requested slippage) × (1 − 0.5%). Returns the
+ * route's platform fee bps.
+ */
+export function checkJupiterEconomics(data, e) {
+    const d = Buffer.from(data);
+    const tag = d.subarray(0, 8).toString('hex');
+    if ((tag !== JUP_ROUTE && tag !== JUP_SHARED_ROUTE) || d.length < 27)
+        refuse('an unsupported Jupiter instruction');
+    const t = d.length - 19;
+    if (d.readBigUInt64LE(t).toString() !== e.amountRaw)
+        refuse('the swap input amount differs from the request');
+    const quotedOut = d.readBigUInt64LE(t + 8);
+    const slip = d.readUInt16LE(t + 16);
+    const feeBps = d[t + 18];
+    if (slip > Math.min(e.slippageBps, MAX_SWAP_SLIPPAGE_BPS))
+        refuse(`route slippage ${slip} bps above the requested ${e.slippageBps}`);
+    if (feeBps > MAX_PLATFORM_FEE_BPS)
+        refuse(`a platform fee of ${feeBps} bps`);
+    const routeMin = (quotedOut * BigInt(10_000 - slip)) / 10000n;
+    const floor = (e.ownOutAmount * BigInt(10_000 - e.slippageBps) * (10000n - QUOTE_DRIFT_BPS)) / 100000000n;
+    if (e.ownOutAmount <= 0n || routeMin < floor) {
+        refuse(`the route's minimum output ${routeMin} is below the independent quote floor ${floor}`);
+    }
+    return feeBps;
+}
+export function verifySwapIxs(payer, ixs, e) {
+    const app = e.appWallet;
+    if (payer !== app)
+        refuse('fee payer is not the app wallet');
+    const wsolAtas = atasOf(app, WSOL);
+    const feeAtas = [...atasOf(PROTOCOL_WALLET, e.inputMint), ...atasOf(PROTOCOL_WALLET, e.outputMint)];
+    checkComputeBudget(ixs);
+    let routes = 0;
+    let solFees = 0;
+    let tokenFeeBps = 0;
+    for (const ix of ixs) {
+        const p = ix.programId.toBase58();
+        const d = Buffer.from(ix.data);
+        if (p === COMPUTE)
+            continue;
+        if (p === ATA_PROGRAM) {
+            checkAta(ix, app, [app]);
+            continue;
+        }
+        if (p === SYSTEM) {
+            if (d.length !== 12 || d.readUInt32LE(0) !== 2)
+                refuse('a system instruction other than a transfer');
+            if (key(ix, 0) !== app)
+                refuse('a SOL transfer not from the app wallet');
+            const to = key(ix, 1);
+            const lamports = d.readBigUInt64LE(4);
+            if (wsolAtas.includes(to)) {
+                // Wrap into its own wSOL account: only a SOL-input swap, and exactly the swapped amount.
+                if (e.inputMint !== WSOL || lamports.toString() !== e.amountRaw)
+                    refuse('a wSOL wrap that is not exactly the swap input');
+                continue;
+            }
+            if (to === PROTOCOL_WALLET && lamports <= MAX_SWAP_SOL_FEE_LAMPORTS && ++solFees === 1)
+                continue;
+            refuse(`a SOL transfer to ${to}`);
+        }
+        if (isToken(p)) {
+            if (d[0] === 17 && wsolAtas.includes(key(ix, 0)))
+                continue; // syncNative own wSOL
+            if (d[0] === 9 && wsolAtas.includes(key(ix, 0)) && key(ix, 1) === app && key(ix, 2) === app)
+                continue; // unwrap
+            refuse(`a top-level token instruction (${d[0]})`);
+        }
+        if (p === JUPITER_V6) {
+            routes += 1;
+            tokenFeeBps = checkJupiterEconomics(d, e);
+            checkJupiter(ix, d, e, feeAtas);
+            continue;
+        }
+        refuse(`unknown program ${p}`);
+    }
+    if (routes !== 1)
+        refuse(`expected exactly one Jupiter route, found ${routes}`);
+    // The server takes EITHER the token platform fee or the SOL fee, never both (S22).
+    if (solFees > 0 && tokenFeeBps > 0)
+        refuse('a SOL fee on top of a token platform fee');
+}
+function checkJupiter(ix, d, e, feeAtas) {
+    const app = e.appWallet;
+    const tag = d.subarray(0, 8).toString('hex');
+    if ((tag !== JUP_ROUTE && tag !== JUP_SHARED_ROUTE) || d.length < 27)
+        refuse('an unsupported Jupiter instruction');
+    const ins = atasOf(app, e.inputMint);
+    const outs = atasOf(app, e.outputMint);
+    const feeOk = (f) => f === JUPITER_V6 || (f !== undefined && feeAtas.includes(f));
+    if (tag === JUP_ROUTE) {
+        if (key(ix, 1) !== app)
+            refuse('the swap authority is not the app wallet');
+        if (!ins.includes(key(ix, 2)))
+            refuse('the swap source is not the app wallet input account');
+        if (!outs.includes(key(ix, 3)))
+            refuse('the swap output does not land in the app wallet');
+        if (key(ix, 4) !== JUPITER_V6 && key(ix, 4) !== key(ix, 3))
+            refuse('the swap output is redirected');
+        if (mintKey(ix, 5) !== e.outputMint)
+            refuse('the output mint differs from the request');
+        if (!feeOk(key(ix, 6)))
+            refuse('a foreign platform fee account');
+    }
+    else {
+        if (key(ix, 2) !== app)
+            refuse('the swap authority is not the app wallet');
+        if (!ins.includes(key(ix, 3)))
+            refuse('the swap source is not the app wallet input account');
+        if (!outs.includes(key(ix, 6)))
+            refuse('the swap output does not land in the app wallet');
+        if (mintKey(ix, 7) !== e.inputMint)
+            refuse('the input mint differs from the request');
+        if (mintKey(ix, 8) !== e.outputMint)
+            refuse('the output mint differs from the request');
+        if (!feeOk(key(ix, 9)))
+            refuse('a foreign platform fee account');
+    }
+}
+export function verifyWithdrawIxs(payer, ixs, e) {
+    if (payer !== e.appWallet)
+        refuse('fee payer is not the app wallet');
+    const src = atasOf(e.appWallet, e.mint);
+    const dst = atasOf(e.signInWallet, e.mint);
+    let transfers = 0;
+    let closes = 0;
+    for (const ix of ixs) {
+        const p = ix.programId.toBase58();
+        const d = Buffer.from(ix.data);
+        if (p === COMPUTE)
+            continue;
+        if (p === ATA_PROGRAM) {
+            checkAta(ix, e.appWallet, [e.signInWallet]);
+            if (mintKey(ix, 3) !== e.mint)
+                refuse('creates an account for another mint');
+            continue;
+        }
+        if (isToken(p) && d[0] === 12) {
+            transfers += 1;
+            if (!src.includes(key(ix, 0)))
+                refuse('the withdrawal source is not the app wallet');
+            if (mintKey(ix, 1) !== e.mint)
+                refuse('the withdrawal mint differs from the request');
+            if (!dst.includes(key(ix, 2)))
+                refuse('the withdrawal does not go to the sign-in wallet');
+            if (key(ix, 3) !== e.appWallet)
+                refuse('the withdrawal authority is not the app wallet');
+            const amount = d.readBigUInt64LE(1).toString();
+            if (e.amount !== undefined && amount !== e.amount)
+                refuse('the withdrawal amount differs from the request');
+            continue;
+        }
+        if (isToken(p) && d[0] === 9) {
+            closes += 1;
+            if (!src.includes(key(ix, 0)) || key(ix, 1) !== e.appWallet || key(ix, 2) !== e.appWallet)
+                refuse('an unexpected account close');
+            continue;
+        }
+        refuse(`unexpected instruction (${p})`);
+    }
+    if (transfers > 1 || closes > 1 || transfers + closes === 0)
+        refuse('not exactly one withdrawal');
+}
+export function verifyCloseIxs(payer, ixs, e) {
+    if (payer !== e.appWallet)
+        refuse('fee payer is not the app wallet');
+    let closes = 0;
+    for (const ix of ixs) {
+        const p = ix.programId.toBase58();
+        if (p === COMPUTE)
+            continue;
+        const d = Buffer.from(ix.data);
+        if (!isToken(p) || d[0] !== 9 || d.length !== 1)
+            refuse(`not a CloseAccount (${p})`);
+        if (key(ix, 1) !== e.destination)
+            refuse('rent goes to an unexpected destination');
+        if (key(ix, 2) !== e.appWallet)
+            refuse('closes an account the app wallet does not own');
+        closes += 1;
+    }
+    if (closes === 0)
+        refuse('no accounts to close');
+}
+//# sourceMappingURL=owner-tx-verify.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dfm-fi/agent",
-  "version": "0.2.1916",
+  "version": "0.2.1941",
   "description": "DFM v2 MCP server — drive the full fund launch → deposit → redeem (+ manage) lifecycle from an AI agent against the live API.",
   "homepage": "https://app.dfm.finance/docs/agent",
   "mcpName": "io.github.DFM-Finance/dfm-agent",

package/skills.md

@@ -129,15 +129,16 @@ BE PROACTIVE ABOUT THE NEXT STEP, NOT ABOUT NEW SCOPE. Finish the job the person
 
 ## Tools
 
-Kim's in-app registry exposes **44 tools** (24 READ + 20 WRITE). External agents mount the official MCP and MUST treat its runtime `listTools` result as the available subset; the two surfaces intentionally are not assumed to be identical. READ tools are free and touch no funds; WRITE tools move only the caller's own funds or administered vaults.
+Kim's in-app registry exposes **45 tools** (25 READ + 20 WRITE). External agents mount the official MCP and MUST treat its runtime `listTools` result as the available subset; the two surfaces intentionally are not assumed to be identical. READ tools are free and touch no funds; WRITE tools move only the caller's own funds or administered vaults.
 
-**READ (24)** — safe, no funds, no gate:
+**READ (25)** — safe, no funds, no gate:
 - `whoami` — The user's display name, primary DFM app wallet, separate sign-in/funding wallet, cluster, and write status. Call FIRST in a session; when an app wallet exists, do not present the sign-in wallet as their DFM wallet.
 - `app_wallet` — The user's APP WALLET (operating/sub-wallet): whether they have one, its status, its LIVE onchain SOL + USDC, and what they must do next. Call this before telling a user why an autonomous action was refused — the usual reason is no wallet, not activated, or an empty float, and each has a different fix.
 - `create_app_wallet` — Get the user's APP WALLET created. In the app it is created automatically at sign-in and approved in the browser (no key leaves the user); this returns the current app wallet state and, if there is none yet, exactly how to get it. Headless agents use the MCP tool of the same name, which creates a wallet owned by a key generated on their own machine. Moves no funds.
 - `set_profile` — Explain how to set the user's DFM profile (display name, @username, bio, avatar). In the app it is edited on the Profile page; headless agents use the MCP tool of the same name. A chosen name and an avatar are required before an agent can create its own app wallet. Changes nothing.
 - `create_api_key` — Explain how to get a dfm_ API key for an external agent. Keys are minted by the owner (signed-in session) in Settings > API keys or via the MCP tool of the same name; read-only by default, optional caps and expiry, shown once. Kim never mints a key. Changes nothing.
 - `create_identity_wallet` — Explain the agent's IDENTITY wallet: the local Solana keypair a headless agent signs in with (SIWS). The MCP tool of the same name reuses an existing one or creates it once on the agent machine; in the app the user's connected wallet is the identity. Kim never creates keys. Changes nothing.
+- `close_empty_accounts` — Explain how rent locked in the app wallet's EMPTY token accounts comes back. In the app it is reclaimed from the app wallet card; an agent whose app wallet is owned by its own key runs the MCP tool of the same name (decoded and signed locally). Kim never signs it. Changes nothing.
 - `onboard` — Explain the headless-agent onboarding order over MCP: identity wallet, SIWS login, profile (name + avatar), app wallet, API key (optional). The MCP tool of the same name runs the steps and reports the missing one. Changes nothing.
 - `list_app_wallet_assets` — EVERY token the app wallet holds — fund shares included — with amount, decimals, USD value and whether the mint is one of our fund shares. `app_wallet` answers USDC and SOL only (that is what the float is), so it cannot see a single share. Use this when the user asks what they hold, or before proposing a withdrawal.
 - `list_dtfs` — Browse live funds (optional category filter).