botanary 0.2.2 → 0.4.0

package/dist/src/commands/wallet.js

@@ -1,5 +1,7 @@
 import * as clack from '@clack/prompts';
-import { fetchComposite, walletApiGet, runLogin, openBrowser, portfolioFreshness, walletSend, resolveMandateForSend, signUnderMandateReal, createSignRequestReal, getSignRequestReal, preflightReal, scopedToAccount, GET_ROUTES, } from 'botanary-mcp';
+import { readFile } from 'node:fs/promises';
+import { fetchComposite, walletApiGet, runLogin, openBrowser, portfolioFreshness, resolveMandateForSend, signUnderMandateReal, preflightReal, scopedToAccount, resolveAsset, baseUnits, GET_ROUTES, } from 'botanary-mcp';
+import { submitIntent, describeSignOutcome } from './sign.js';
 import { colors, glyphs } from '../render/colors.js';
 import { renderTable } from '../render/table.js';
 import { redactForDisplay } from '../render/redact.js';
@@ -13,15 +15,20 @@ import { renderChains } from '../render/chains.js';
 import { renderGas } from '../render/gas.js';
 import { renderAccounts } from '../render/accounts.js';
 import { section } from '../render/kv.js';
-import { step, notify } from '../progress.js';
+import { step, notify, cliHitlContext } from '../progress.js';
 import { confirmOrThrow, dryRunPayload, renderReview } from '../review.js';
 import { classifyWalletSend } from '../outcome.js';
-import { assertAddress, assertTierAllows, familyOf, findChain, parseAmount, tokenChoicesFor } from '../validate.js';
+import { assertAddress, assertTierAllows, familyOf, findChain, isTokenRef, parseAmount, symbolRefusalMessage, tokenChoicesFor, } from '../validate.js';
 import { CliError, EXIT, invalidArgs, notLoggedIn } from '../errors.js';
 import { appUrl } from '../app-url.js';
 /** A WalletSession carries `sessionToken` - redact it in any printed output unless --reveal, the same
- *  redact-by-default rule the design spec commits to everywhere. Anything that prints a session (status,
- *  accounts use) must route through this rather than printResult directly. */
+ *  redact-by-default rule the design spec commits to everywhere. Anything that prints a session (login,
+ *  status, whoami, accounts use) must route through this rather than printResult - or a hand-rolled
+ *  `console.log(JSON.stringify(...))` - directly.
+ *
+ *  That is not a style preference. `login --json` hand-rolled its own print and shipped the owner's live
+ *  bearer to stdout in 0.3.0 - and `--json` is the PIPE path, so it landed in CI logs, shell history and
+ *  anything downstream of the pipe. One printer means one place to get this right. */
 function printSessionResult(ctx, data) {
     const session = data?.session ?? data;
     const token = session?.sessionToken;
@@ -34,6 +41,35 @@ async function requireWalletToken(ctx) {
     }
     return session.sessionToken;
 }
+/** Same shape as `account.ts`/`authority.ts`/`services.ts`'s own `reviewAndSubmit` - duplicated per
+ *  `sign.ts`'s own comment on why a shared helper never gets pulled back out of that file. */
+async function reviewAndSubmit(ctx, title, rows, warnings, kind, params) {
+    if (ctx.dryRun) {
+        printResult(ctx, dryRunPayload(title, rows, warnings), () => renderReview('Dry run - nothing will be sent', rows, warnings));
+        return;
+    }
+    await confirmOrThrow(ctx, title, rows, warnings);
+    const outcome = await submitIntent(ctx, kind, params);
+    printResult(ctx, outcome.data, () => describeSignOutcome(outcome));
+}
+/** Read and parse a JSON file for a complex, arbitrarily-sized intent field - the same escape hatch
+ *  `agent request --calls-file` already established, rather than a wall of flags for a deeply nested
+ *  shape (a delegation grant's budgets, a mandate confirm's candidates). */
+async function readJsonFile(path, flag) {
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch (e) {
+        throw invalidArgs(`Could not read ${flag} "${path}": ${e instanceof Error ? e.message : String(e)}`);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        throw invalidArgs(`${flag} "${path}" is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
 export function registerWalletCommands(program) {
     group(program
         .command('login')
@@ -44,6 +80,9 @@ export function registerWalletCommands(program) {
             api: ctx.runtime.api,
             store: ctx.runtime.walletSessionStore,
             openBrowser,
+            // Alongside onPrompt below, never instead of it: onPrompt prints the code and the URL once,
+            // and this reports each status change while the wait runs. Silent under --json.
+            ctx: cliHitlContext(ctx),
             now: () => Date.now(),
             sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
             // The whole point of the 0.6.0 callback: say the code and the URL NOW, not when the flow ends
@@ -58,7 +97,10 @@ export function registerWalletCommands(program) {
         });
         if (result.status === 'authorized') {
             if (ctx.json) {
-                console.log(JSON.stringify({ status: 'authorized', session: result.session ?? null }));
+                // Same payload as 0.3.0, routed through the one redaction path instead of a second
+                // hand-rolled JSON.stringify - see printSessionResult's header. --reveal is still the
+                // deliberate opt-in for an owner who actually wants the token; the default never prints it.
+                printSessionResult(ctx, { status: 'authorized', session: result.session ?? null });
             }
             else {
                 console.log(glyphs.success(`Logged in${result.session ? ` (account ${result.session.accountId ?? 'default'})` : ''}`));
@@ -171,7 +213,7 @@ export function registerWalletCommands(program) {
         .description('Send tokens from an account you own')
         .option('--recipient <address>', 'Destination address (0x... on EVM)')
         .option('--amount <amount>', 'Amount in display units, e.g. 25')
-        .option('--token <symbol>', 'Token symbol, e.g. USDC')
+        .option('--token <addressOrAssetRef>', 'Token contract address (0x...) or CAIP-19 asset ref - see `botanary tokens`')
         .option('--chain-id <chainId>', 'Chain to send on - see `botanary chains`')
         .action(async (opts) => {
         const ctx = program.opts().__ctx;
@@ -179,19 +221,23 @@ export function registerWalletCommands(program) {
         // Validate required inputs before making network calls. If chain-id is not specified and we're
         // not in interactive mode, fail immediately with missing input - do not fetch chains first.
         let amountRaw = opts.amount;
-        let tokenSymbol = opts.token;
+        let tokenRaw = opts.token;
         let recipient = opts.recipient;
         const chainId = opts.chainId ?? ctx.chain;
-        if (!ctx.interactive && (!chainId || !amountRaw || !tokenSymbol || !recipient)) {
+        if (!ctx.interactive && (!chainId || !amountRaw || !tokenRaw || !recipient)) {
             throw invalidArgs('Missing required input', 'Use --amount, --token, --recipient, and --chain-id, or run in an interactive terminal.');
         }
         const chains = await step(ctx, 'Reading chains', () => ctx.runtime.api.get('/v1/chains', walletToken));
         const chain = findChain(chains, chainId);
         assertTierAllows(chain, 'send');
         const family = familyOf(chain.namespace);
-        if (ctx.interactive && (!amountRaw || !tokenSymbol || !recipient)) {
-            const balance = await step(ctx, 'Reading balances', () => ctx.runtime.api.get('/v1/balance', walletToken));
-            const choices = tokenChoicesFor(balance, chain.chainRef);
+        // Hoisted out of the interactive-only branch below: the non-interactive path needs `held` too, to
+        // build a symbol refusal that names real candidates instead of complaining into the void. A
+        // refusal that lists nothing because the CLI declined to look is the papercut this task exists to
+        // remove.
+        const balance = await step(ctx, 'Reading balances', () => ctx.runtime.api.get('/v1/balance', walletToken));
+        const held = tokenChoicesFor(balance, chain.chainId ?? Number.NaN);
+        if (ctx.interactive && (!amountRaw || !tokenRaw || !recipient)) {
             const answers = await clack.group({
                 amount: () => clack.text({
                     message: 'Amount?',
@@ -204,12 +250,18 @@ export function registerWalletCommands(program) {
                         return Number.isFinite(parsed) && parsed > 0 ? undefined : 'A positive number, e.g. 25';
                     },
                 }),
-                token: () => choices.length
+                token: () => held.length
                     ? clack.select({
                         message: `Token? (held on ${chain.name})`,
-                        options: choices.map((choice) => ({ value: choice.symbol, label: `${choice.symbol} (${choice.amount})` })),
+                        // The picker's VALUE is the assetRef, not the symbol - the same identity `resolveAsset`
+                        // takes below, so a picked token never re-enters the ambiguity this task removes.
+                        options: held.map((h) => ({
+                            value: h.assetRef,
+                            label: `${h.symbol} (${h.amount ?? 0})`,
+                            hint: `${h.address}  ${h.decimals}dp  ${h.source ?? ''}`.trim(),
+                        })),
                     })
-                    : clack.text({ message: 'Token?', placeholder: 'USDC', initialValue: tokenSymbol }),
+                    : clack.text({ message: 'Token contract address?', placeholder: '0xAb12...', initialValue: tokenRaw }),
                 recipient: () => clack.text({
                     message: 'To?',
                     placeholder: family === 'evm' ? '0xAb12...9F3' : 'address',
@@ -222,17 +274,28 @@ export function registerWalletCommands(program) {
                 },
             });
             amountRaw = answers.amount;
-            tokenSymbol = answers.token;
+            tokenRaw = answers.token;
             recipient = answers.recipient;
         }
         const amount = parseAmount(amountRaw);
-        if (!tokenSymbol)
-            throw invalidArgs('--token is required.', 'A token symbol, e.g. USDC. See `botanary balance`.');
+        if (!tokenRaw) {
+            throw invalidArgs('--token is required.', 'A contract address or CAIP-19 asset ref - see `botanary tokens`.');
+        }
+        if (!isTokenRef(tokenRaw)) {
+            const matches = held.filter((h) => h.symbol.toUpperCase() === String(tokenRaw).trim().toUpperCase());
+            throw invalidArgs(symbolRefusalMessage(String(tokenRaw).trim(), chain.name, matches), 'Run `botanary tokens` to list every token this account holds.');
+        }
         const to = assertAddress(recipient, family);
+        const asset = await step(ctx, 'Resolving token', () => resolveAsset(ctx.runtime, chain.chainId ?? Number.NaN, tokenRaw, walletToken));
+        // From the ORIGINAL typed string, not the round-tripped `amount` number: a float round-trip
+        // (`String(0.1 + 0.2)`) can lose or invent trailing digits on a token amount, and base units are
+        // exactly the value that must never drift from what the user actually typed.
+        const sendAmountRaw = baseUnits(String(amountRaw), asset.decimals);
         const input = {
             recipient: to,
             amount,
-            tokenSymbol,
+            asset,
+            amountRaw: sendAmountRaw,
             chainId: chain.chainId ?? Number.NaN,
             chainKey: chain.key,
         };
@@ -242,7 +305,9 @@ export function registerWalletCommands(program) {
             ? 'mandate'
             : 'browser';
         const rows = [
-            { label: 'amount', value: `${amount} ${tokenSymbol}` },
+            { label: 'amount', value: `${amount} ${asset.symbol}` },
+            { label: 'token', value: `${asset.symbol}  ${asset.address}  ${asset.decimals}dp` },
+            { label: 'source', value: asset.source },
             { label: 'to', value: to },
             { label: 'chain', value: `${chain.name} (${chain.key}, ${chain.tier})` },
             {
@@ -253,6 +318,12 @@ export function registerWalletCommands(program) {
             },
         ];
         const warnings = [];
+        // `source: 'chain'` means resolution fell all the way through to reading the contract itself -
+        // nothing in Botanary's registry, discovered set or imported list recognises this token, so the
+        // name shown is exactly what the contract claims for itself and nothing more.
+        if (asset.source === 'chain') {
+            warnings.push(`Botanary does not recognise this token - nothing but the contract itself vouches for the name "${asset.symbol}". Check the address.`);
+        }
         // The backend's own reason, not re-authored here: it is the only sentence that can honestly say
         // WHY the mandate lane was not taken.
         if (lane === 'browser' && mandate.accountId !== null && mandate.accountId !== (session?.accountId ?? '')) {
@@ -269,34 +340,116 @@ export function registerWalletCommands(program) {
             return;
         }
         await confirmOrThrow(ctx, 'Review this payment', rows, warnings);
-        const result = await step(ctx, lane === 'mandate' ? 'Signing under your mandate' : 'Waiting for your approval', () => walletSend({
-            mandateAccountId: mandate.accountId,
-            mandateInBounds: mandate.inBounds,
-            mandateBoundsReason: mandate.reason,
-            walletAccountId: session?.accountId ?? '',
-            signUnderMandate: (i) => signUnderMandateReal(ctx.runtime, mandate.grant, i),
-            createSignRequest: createSignRequestReal(ctx.runtime, walletToken),
-            getSignRequest: getSignRequestReal(ctx.runtime, walletToken),
-            openBrowser,
-            now: () => Date.now(),
-            sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
-            preflight: preflightReal(ctx.runtime, walletToken),
-            // Same reason as login's onPrompt: the approval URL is useless once the wait is over.
-            onHandoff: ({ url, browserOpened }) => {
-                notify(ctx, browserOpened
-                    ? glyphs.info(`Opened your browser to approve: ${url}`)
-                    : glyphs.warning(`Could not open a browser - approve here: ${url}`));
-            },
-        }, input));
-        const outcome = classifyWalletSend(result);
-        ctx.outcome.exit = outcome.exit;
-        printResult(ctx, result, () => {
-            const lines = [typeof result.text === 'string' ? result.text : JSON.stringify(result)];
+        // LANE ARBITRATION STAYS HERE - it is the decision `submitIntent` deliberately does not make
+        // (see its own doc comment in sign.ts). Only the browser lane parks a sign request; the mandate
+        // lane signs locally and never reaches submitIntent at all.
+        if (lane === 'mandate') {
+            const relay = await step(ctx, 'Signing under your mandate', () => signUnderMandateReal(ctx.runtime, mandate.grant, input));
+            const result = {
+                lane: 'agent',
+                text: `Signed locally under this machine's own mandate on account ${session?.accountId ?? ''} - no ` +
+                    'browser was opened. The on-chain mandate is what authorized this, not a click.',
+                relay,
+            };
+            const outcome = classifyWalletSend(result);
+            ctx.outcome.exit = outcome.exit;
+            printResult(ctx, result, () => {
+                const lines = [result.text];
+                if (outcome.note)
+                    lines.push(colors.dim(outcome.note));
+                return lines.join('\n');
+            });
+            return;
+        }
+        // Advisory only - never blocks the handoff. Computed before parking so its warning still reads
+        // as "before you approve" rather than a footnote after the fact.
+        const preflightWarning = await preflightReal(ctx.runtime, walletToken)(input);
+        const outcome = await submitIntent(ctx, 'send', {
+            chainKey: input.chainKey,
+            token: input.asset.assetRef,
+            amount: String(input.amount),
+            amountRaw: input.amountRaw,
+            to: input.recipient,
+        });
+        printResult(ctx, outcome.data, () => {
+            const lines = [describeSignOutcome(outcome)];
+            if (preflightWarning)
+                lines.push(colors.dim(`Note: ${preflightWarning}`));
             if (outcome.note)
                 lines.push(colors.dim(outcome.note));
             return lines.join('\n');
         });
     }), 'Wallet');
+    group(program
+        .command('swap')
+        .description('Swap tokens in an account you own')
+        .option('--token-in <addressOrAssetRef>', 'Token to sell - contract address or CAIP-19 asset ref, never a symbol')
+        .option('--token-out <addressOrAssetRef>', 'Token to buy - contract address or CAIP-19 asset ref, never a symbol')
+        .option('--amount-in <amount>', 'Amount of --token-in to sell, in display units, e.g. 25')
+        .option('--chain-id <chainId>', 'Chain to swap on - see `botanary chains`')
+        .option('--max-slippage-bps <bps>', 'Maximum acceptable slippage, in basis points')
+        .action(async (opts) => {
+        const ctx = program.opts().__ctx;
+        const walletToken = await requireWalletToken(ctx);
+        const tokenInRaw = opts.tokenIn;
+        const tokenOutRaw = opts.tokenOut;
+        const amountInRaw = opts.amountIn;
+        const chainId = opts.chainId ?? ctx.chain;
+        if (!chainId || !tokenInRaw || !tokenOutRaw || !amountInRaw) {
+            throw invalidArgs('Missing required input', 'Use --token-in, --token-out, --amount-in, and --chain-id.');
+        }
+        const chains = await step(ctx, 'Reading chains', () => ctx.runtime.api.get('/v1/chains', walletToken));
+        const chain = findChain(chains, chainId);
+        assertTierAllows(chain, 'send');
+        if (chain.chainId === null) {
+            throw invalidArgs(`${chain.name} (${chain.key}) has no EVM chain id - swap is EVM-only today.`, 'Pick an EVM chain - see `botanary chains`.');
+        }
+        const amountIn = parseAmount(amountInRaw, '--amount-in');
+        // Fetched unconditionally, same as `send`: a symbol refusal that names real candidates instead
+        // of complaining into the void needs this even on the success path, because the failure can be
+        // discovered only after trying to validate the flag.
+        const balance = await step(ctx, 'Reading balances', () => ctx.runtime.api.get('/v1/balance', walletToken));
+        const held = tokenChoicesFor(balance, chain.chainId);
+        for (const [raw, flag] of [
+            [tokenInRaw, '--token-in'],
+            [tokenOutRaw, '--token-out'],
+        ]) {
+            if (!isTokenRef(raw)) {
+                const matches = held.filter((h) => h.symbol.toUpperCase() === String(raw).trim().toUpperCase());
+                throw invalidArgs(symbolRefusalMessage(String(raw).trim(), chain.name, matches), `Run \`botanary tokens\` to list every token this account holds, then pass an address to ${flag}.`);
+            }
+        }
+        const [assetIn, assetOut] = await Promise.all([
+            step(ctx, 'Resolving token in', () => resolveAsset(ctx.runtime, chain.chainId, tokenInRaw, walletToken)),
+            step(ctx, 'Resolving token out', () => resolveAsset(ctx.runtime, chain.chainId, tokenOutRaw, walletToken)),
+        ]);
+        const rows = [
+            { label: 'sell', value: `${amountIn} ${assetIn.symbol}` },
+            { label: 'buy', value: assetOut.symbol },
+            { label: 'chain', value: `${chain.name} (${chain.key}, ${chain.tier})` },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        const warnings = [];
+        if (assetIn.source === 'chain' || assetOut.source === 'chain') {
+            warnings.push('At least one token is unrecognised by Botanary - nothing but the contract itself vouches for its name.');
+        }
+        if (chain.testnet)
+            warnings.push('This is a testnet chain.');
+        if (ctx.dryRun) {
+            const payload = dryRunPayload('Review this swap', rows, warnings);
+            printResult(ctx, payload, () => renderReview('Dry run - nothing will be sent', rows, warnings));
+            return;
+        }
+        await confirmOrThrow(ctx, 'Review this swap', rows, warnings);
+        const outcome = await submitIntent(ctx, 'swap', {
+            chainId: chain.chainId,
+            fromToken: { symbol: assetIn.symbol, address: assetIn.address },
+            toToken: { symbol: assetOut.symbol, address: assetOut.address },
+            amountIn: String(amountIn),
+            ...(opts.maxSlippageBps ? { maxSlippageBps: Number(opts.maxSlippageBps) } : {}),
+        });
+        printResult(ctx, outcome.data, () => describeSignOutcome(outcome));
+    }), 'Wallet');
     group(program
         .command('activity')
         .description('Recent sends, swaps and yield transactions')
@@ -318,7 +471,7 @@ export function registerWalletCommands(program) {
         const result = await step(ctx, 'Reading markets', () => fetchComposite(ctx.runtime.api, token, [{ key: 'tokens', path: '/v1/markets/tokens' }]));
         printResult(ctx, result.data);
     }), 'Wallet');
-    group(program
+    const yieldCmd = group(program
         .command('yield')
         .description('Yield pools, a shortlist, and this account\'s positions')
         .action(async () => {
@@ -335,6 +488,259 @@ export function registerWalletCommands(program) {
             scopeCaveats: 'shortlist is ranked off your own holdings server-side and is not scoped by accounts use.',
         });
     }), 'Wallet');
+    /** Shared by `yield deposit` and `yield withdraw` - identical shape (`--pool-id`, `--amount`,
+     *  `--chain-id`), differing only in the sign-request `kind` and the review title. `yield claim` is NOT
+     *  built off this: `CliFarmClaimIntentDto` carries no `amount` field at all - the backend decides what
+     *  is claimable from a live probe of the account's own accrued rewards, so there is nothing for an
+     *  `--amount` flag on claim to mean. */
+    function registerFarmAmountCommand(kind, name, verb) {
+        yieldCmd
+            .command(name)
+            .description(`${verb[0].toUpperCase()}${verb.slice(1)} a yield pool, for an account you own`)
+            .option('--pool-id <poolId>', 'Pool id - see `botanary yield`')
+            .option('--amount <amount>', `Amount of the pool's underlying asset, in display units, e.g. 25`)
+            .option('--chain-id <chainId>', 'Chain the pool is on - see `botanary yield`')
+            .action(async (opts) => {
+            const ctx = program.opts().__ctx;
+            const walletToken = await requireWalletToken(ctx);
+            const poolId = opts.poolId;
+            const amountRaw = opts.amount;
+            const chainId = opts.chainId ?? ctx.chain;
+            if (!poolId || !amountRaw || !chainId) {
+                throw invalidArgs('Missing required input', 'Use --pool-id, --amount, and --chain-id.');
+            }
+            const chains = await step(ctx, 'Reading chains', () => ctx.runtime.api.get('/v1/chains', walletToken));
+            const chain = findChain(chains, chainId);
+            assertTierAllows(chain, 'send');
+            if (chain.chainId === null) {
+                throw invalidArgs(`${chain.name} (${chain.key}) has no EVM chain id - ${verb} is EVM-only today.`, 'Pick an EVM chain - see `botanary chains`.');
+            }
+            const amount = parseAmount(amountRaw);
+            const rows = [
+                { label: 'pool', value: String(poolId) },
+                { label: 'amount', value: String(amount) },
+                { label: 'chain', value: `${chain.name} (${chain.key}, ${chain.tier})` },
+                { label: 'signed by', value: 'you, in your browser' },
+            ];
+            const warnings = [];
+            if (chain.testnet)
+                warnings.push('This is a testnet chain.');
+            if (ctx.dryRun) {
+                const payload = dryRunPayload(`Review this ${verb}`, rows, warnings);
+                printResult(ctx, payload, () => renderReview('Dry run - nothing will be sent', rows, warnings));
+                return;
+            }
+            await confirmOrThrow(ctx, `Review this ${verb}`, rows, warnings);
+            const outcome = await submitIntent(ctx, kind, {
+                poolId: String(poolId),
+                chainId: chain.chainId,
+                amount: String(amount),
+            });
+            printResult(ctx, outcome.data, () => describeSignOutcome(outcome));
+        });
+    }
+    registerFarmAmountCommand('farm.deposit', 'deposit', 'deposit');
+    registerFarmAmountCommand('farm.withdraw', 'withdraw', 'withdraw');
+    yieldCmd
+        .command('claim')
+        .description('Claim accrued rewards from a yield pool, for an account you own')
+        .option('--pool-id <poolId>', 'Pool id - see `botanary yield`')
+        .option('--chain-id <chainId>', 'Chain the pool is on - see `botanary yield`')
+        .action(async (opts) => {
+        const ctx = program.opts().__ctx;
+        const walletToken = await requireWalletToken(ctx);
+        const poolId = opts.poolId;
+        const chainId = opts.chainId ?? ctx.chain;
+        if (!poolId || !chainId) {
+            throw invalidArgs('Missing required input', 'Use --pool-id and --chain-id.');
+        }
+        const chains = await step(ctx, 'Reading chains', () => ctx.runtime.api.get('/v1/chains', walletToken));
+        const chain = findChain(chains, chainId);
+        assertTierAllows(chain, 'send');
+        if (chain.chainId === null) {
+            throw invalidArgs(`${chain.name} (${chain.key}) has no EVM chain id - claim is EVM-only today.`, 'Pick an EVM chain - see `botanary chains`.');
+        }
+        const rows = [
+            { label: 'pool', value: String(poolId) },
+            { label: 'chain', value: `${chain.name} (${chain.key}, ${chain.tier})` },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        const warnings = [];
+        if (chain.testnet)
+            warnings.push('This is a testnet chain.');
+        if (ctx.dryRun) {
+            const payload = dryRunPayload('Review this claim', rows, warnings);
+            printResult(ctx, payload, () => renderReview('Dry run - nothing will be sent', rows, warnings));
+            return;
+        }
+        await confirmOrThrow(ctx, 'Review this claim', rows, warnings);
+        const outcome = await submitIntent(ctx, 'farm.claim', {
+            poolId: String(poolId),
+            chainId: chain.chainId,
+        });
+        printResult(ctx, outcome.data, () => describeSignOutcome(outcome));
+    });
+    // ---- solana: send, swap, and Botanary Mandates Program writes -------------------------------------
+    // Solana is key-keyed, not chainId-keyed (workspace CLAUDE.md, "Chain families and tiers") - every
+    // command below takes --key (see `botanary chains`, e.g. "solana" or "solana-devnet") rather than
+    // --chain-id. Kept as its own group rather than folded into `send`/`swap` above: the DTOs genuinely
+    // differ (raw base-unit amount strings, a `key` selector, no `resolveAsset`/mandate-lane round trip),
+    // so branching one command on chain family would replace one simple code path with two.
+    const solana = group(program.command('solana').description('Send, swap and manage Botanary Mandates on Solana'), 'Wallet');
+    solana
+        .command('send')
+        .description('Send tokens on Solana')
+        .requiredOption('--key <key>', 'Solana chain key - see `botanary chains`, e.g. solana or solana-devnet')
+        .requiredOption('--to <address>', 'Destination Solana address')
+        .option('--mint <address>', 'SPL token mint - omit to send native SOL')
+        .requiredOption('--amount <amount>', 'Raw base-unit amount (lamports for SOL, raw token units for SPL) - not display units')
+        .option('--gas-method <method>', 'native, or usdc routed through Kora, gasless')
+        .option('--account-id <accountId>', 'Specific account of yours - omit for your default')
+        .action(async (opts) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        if (opts.gasMethod !== undefined && opts.gasMethod !== 'native' && opts.gasMethod !== 'usdc') {
+            throw invalidArgs(`--gas-method must be "native" or "usdc", got ${JSON.stringify(opts.gasMethod)}.`);
+        }
+        const to = assertAddress(opts.to, 'solana');
+        const rows = [
+            { label: 'amount', value: `${opts.amount} (raw base units)` },
+            { label: 'to', value: to },
+            { label: 'chain', value: opts.key },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        await reviewAndSubmit(ctx, 'Review this Solana send', rows, [], 'solana.send', {
+            key: opts.key,
+            to,
+            amount: opts.amount,
+            ...(opts.mint ? { mint: opts.mint } : {}),
+            ...(opts.gasMethod ? { gasMethod: opts.gasMethod } : {}),
+            ...(opts.accountId ? { accountId: opts.accountId } : {}),
+        });
+    });
+    solana
+        .command('swap')
+        .description('Swap tokens on Solana')
+        .requiredOption('--key <key>', 'Solana chain key - see `botanary chains`')
+        .option('--from-mint <address>', 'Mint to sell - omit for native SOL')
+        .option('--to-mint <address>', 'Mint to buy - omit for native SOL')
+        .requiredOption('--amount-in <amount>', 'Amount of the sell side, in HUMAN-SCALE units (e.g. 1.5), not raw base units')
+        .requiredOption('--max-slippage-bps <bps>', 'Maximum acceptable slippage, in basis points')
+        .option('--gas-method <method>', 'native, or usdc routed through Kora, gasless')
+        .option('--account-id <accountId>', 'Specific account of yours - omit for your default')
+        .action(async (opts) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        if (opts.gasMethod !== undefined && opts.gasMethod !== 'native' && opts.gasMethod !== 'usdc') {
+            throw invalidArgs(`--gas-method must be "native" or "usdc", got ${JSON.stringify(opts.gasMethod)}.`);
+        }
+        const amountIn = parseAmount(opts.amountIn, '--amount-in');
+        const maxSlippageBps = Number(opts.maxSlippageBps);
+        if (!Number.isInteger(maxSlippageBps) || maxSlippageBps < 0) {
+            throw invalidArgs(`--max-slippage-bps must be a non-negative integer, got ${JSON.stringify(opts.maxSlippageBps)}.`);
+        }
+        const rows = [
+            { label: 'sell', value: `${amountIn}${opts.fromMint ? ` of ${opts.fromMint}` : ' SOL'}` },
+            { label: 'buy', value: opts.toMint ?? 'SOL' },
+            { label: 'chain', value: opts.key },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        await reviewAndSubmit(ctx, 'Review this Solana swap', rows, [], 'solana.swap', {
+            key: opts.key,
+            amountIn,
+            maxSlippageBps,
+            ...(opts.fromMint ? { fromMint: opts.fromMint } : {}),
+            ...(opts.toMint ? { toMint: opts.toMint } : {}),
+            ...(opts.gasMethod ? { gasMethod: opts.gasMethod } : {}),
+            ...(opts.accountId ? { accountId: opts.accountId } : {}),
+        });
+    });
+    const solanaMandate = solana
+        .command('mandate')
+        .description('Grant, freeze/unfreeze and revoke Botanary Mandates Program delegations on Solana');
+    solanaMandate
+        .command('grant')
+        .description('Grant a bounded Solana mandate')
+        .requiredOption('--key <key>', 'Solana chain key - see `botanary chains`')
+        .requiredOption('--mint <address>', 'The SPL token mint this mandate bounds')
+        .requiredOption('--recipient <address...>', 'An allowlisted recipient - repeat for each (at least one, fail-closed)')
+        .option('--venue <address...>', 'An allowlisted venue program id - repeat for each; omit for none')
+        .requiredOption('--per-action-max <amount>', 'Raw base-unit max spend per action')
+        .requiredOption('--cap-limit <amount>', 'Raw base-unit budget per --cap-period-seconds window')
+        .requiredOption('--cap-period-seconds <seconds>', 'The window --cap-limit applies over, at least 3600 (1 hour)')
+        .requiredOption('--expiry <iso>', 'When this mandate expires, ISO 8601 - mandatory, unlike the EVM delegation lane')
+        .option('--account-id <accountId>', 'Specific account of yours - omit for your default')
+        .action(async (opts) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        const capPeriodSeconds = Number(opts.capPeriodSeconds);
+        if (!Number.isInteger(capPeriodSeconds) || capPeriodSeconds < 3600) {
+            throw invalidArgs(`--cap-period-seconds must be an integer of at least 3600, got ${JSON.stringify(opts.capPeriodSeconds)}.`);
+        }
+        const rows = [
+            { label: 'mint', value: opts.mint },
+            { label: 'recipients', value: opts.recipient.join(', ') },
+            { label: 'venues', value: opts.venue?.length ? opts.venue.join(', ') : 'none' },
+            { label: 'per-action max', value: `${opts.perActionMax} (raw base units)` },
+            { label: 'cap', value: `${opts.capLimit} (raw base units) every ${capPeriodSeconds}s` },
+            { label: 'expiry', value: opts.expiry },
+            { label: 'chain', value: opts.key },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        await reviewAndSubmit(ctx, 'Review this Solana mandate grant', rows, [], 'solana.mandate.grant', {
+            key: opts.key,
+            mint: opts.mint,
+            recipientAllowlist: opts.recipient,
+            venueAllowlist: opts.venue ?? [],
+            perActionMax: opts.perActionMax,
+            capLimit: opts.capLimit,
+            capPeriodSeconds,
+            expiry: opts.expiry,
+            ...(opts.accountId ? { accountId: opts.accountId } : {}),
+        });
+    });
+    solanaMandate
+        .command('freeze')
+        .description('Freeze (or unfreeze) every Solana mandate for this owner - one kill switch across every mint')
+        .requiredOption('--key <key>', 'Solana chain key - see `botanary chains`')
+        .option('--unfreeze', 'Unfreeze instead of freeze')
+        .option('--account-id <accountId>', 'Specific account of yours - omit for your default')
+        .action(async (opts) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        const frozen = !opts.unfreeze;
+        const rows = [
+            {
+                label: 'action',
+                value: frozen ? 'freeze every Solana mandate for this owner' : 'unfreeze every Solana mandate for this owner',
+            },
+            { label: 'chain', value: opts.key },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        const warnings = frozen
+            ? ['This stops the copilot acting under ANY Solana mandate for this owner, across every mint, instantly.']
+            : [];
+        await reviewAndSubmit(ctx, `Review this Solana mandate ${frozen ? 'freeze' : 'unfreeze'}`, rows, warnings, 'solana.mandate.freeze', { key: opts.key, frozen, ...(opts.accountId ? { accountId: opts.accountId } : {}) });
+    });
+    solanaMandate
+        .command('revoke <id>')
+        .description('Revoke a Solana mandate')
+        .requiredOption('--key <key>', 'Solana chain key - see `botanary chains`')
+        .option('--account-id <accountId>', 'Specific account of yours - omit for your default')
+        .action(async (id, opts) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        const rows = [
+            { label: 'mandate', value: id },
+            { label: 'chain', value: opts.key },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        await reviewAndSubmit(ctx, 'Review this Solana mandate revoke', rows, [], 'solana.mandate.revoke', {
+            id,
+            key: opts.key,
+            ...(opts.accountId ? { accountId: opts.accountId } : {}),
+        });
+    });
     const mandates = group(program
         .command('mandates')
         .description('What the agent lane may spend unattended (testnet only)')
@@ -387,6 +793,152 @@ export function registerWalletCommands(program) {
             ].join('\n')
             : `${section('Suggested mandates')}\n${colors.muted(`  ${payload.note}`)}`);
     });
+    // ---- mandates writes: two parallel systems, two distinct id spaces --------------------------------
+    // `botanary mandates` above already reads BOTH tables side by side (see `render/mandates.ts`):
+    // "Delegations (Smart Sessions)" - the classic EVM Smart Session grant lane, `delegation.*` kinds,
+    // ids from `POST /delegations` - and "Mandates (on-chain)" - the newer rules/mandates system,
+    // `mandate.*` kinds, ids from `POST /mandates/confirm`. The write verbs below are deliberately named
+    // to keep the two apart: `grant`/`freeze`/`unfreeze`/`revoke` target a DELEGATION id (the first
+    // table); `confirm`/`pause`/`resume`/`cancel` target a MANDATE id (the second table). `cancel`, not
+    // `revoke`, for `mandate.revoke` - `revoke` was already spoken for by `delegation.revoke` above it,
+    // and reusing one verb across two id spaces is exactly the kind of ambiguity a CLI cannot recover
+    // from the way a web form with two separate buttons can.
+    mandates
+        .command('grant')
+        .description('Grant bounded access to a delegatee agent (a Smart Session - the classic delegation lane)')
+        .requiredOption('--grant-file <path>', 'JSON object: { name, delegateeAddress, chainId, budgets: [{ token: { symbol }, amount }], ... } - ' +
+        'see the README for the full shape (perActionMax, recipientAllowlist, allowedContract, deniedContracts, ' +
+        'conditions, maxActions, rate, expiresAt, alsoOnChainIds, agentId, mandateId, mandateVersion)')
+        .option('--name <name>', "Override the file's name field")
+        .option('--delegatee-address <address>', "Override the file's delegateeAddress field")
+        .option('--chain-id <chainId>', "Override the file's chainId field")
+        .action(async (opts) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        const fileParams = await readJsonFile(opts.grantFile, '--grant-file');
+        if (typeof fileParams !== 'object' || fileParams === null || Array.isArray(fileParams)) {
+            throw invalidArgs('--grant-file must contain a single JSON object.');
+        }
+        const params = { ...fileParams };
+        if (opts.name !== undefined)
+            params.name = opts.name;
+        if (opts.delegateeAddress !== undefined)
+            params.delegateeAddress = opts.delegateeAddress;
+        if (opts.chainId !== undefined)
+            params.chainId = Number(opts.chainId);
+        if (typeof params.name !== 'string' || !params.name) {
+            throw invalidArgs('name is required.', 'Set it in --grant-file, or pass --name.');
+        }
+        if (typeof params.delegateeAddress !== 'string' || !params.delegateeAddress) {
+            throw invalidArgs('delegateeAddress is required.', 'Set it in --grant-file, or pass --delegatee-address.');
+        }
+        if (typeof params.chainId !== 'number' || !Number.isFinite(params.chainId)) {
+            throw invalidArgs('chainId is required.', 'Set it in --grant-file, or pass --chain-id.');
+        }
+        if (!Array.isArray(params.budgets) || params.budgets.length === 0) {
+            throw invalidArgs('budgets is required and must be a non-empty array.', 'Set it in --grant-file - see the README for the shape.');
+        }
+        const rows = [
+            { label: 'name', value: String(params.name) },
+            { label: 'delegatee', value: String(params.delegateeAddress) },
+            { label: 'chain id', value: String(params.chainId) },
+            { label: 'budgets', value: String(params.budgets.length) },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        await reviewAndSubmit(ctx, 'Review this mandate grant', rows, [], 'delegation.grant', params);
+    });
+    mandates
+        .command('freeze <delegationId>')
+        .description('Freeze a delegation (reversible) - id from the Delegations table in `botanary mandates`')
+        .action(async (delegationId) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        const rows = [
+            { label: 'delegation', value: delegationId },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        await reviewAndSubmit(ctx, 'Review this delegation freeze', rows, [], 'delegation.freeze', { delegationId });
+    });
+    mandates
+        .command('unfreeze <delegationId>')
+        .description('Unfreeze a delegation - id from the Delegations table in `botanary mandates`')
+        .action(async (delegationId) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        const rows = [
+            { label: 'delegation', value: delegationId },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        await reviewAndSubmit(ctx, 'Review this delegation unfreeze', rows, [], 'delegation.unfreeze', { delegationId });
+    });
+    mandates
+        .command('revoke <delegationId>')
+        .description('Revoke a delegation (permanent) - id from the Delegations table in `botanary mandates`')
+        .action(async (delegationId) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        const rows = [
+            { label: 'delegation', value: delegationId },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        const warnings = ['This is permanent - use `botanary mandates freeze` instead if you may want it back.'];
+        await reviewAndSubmit(ctx, 'Review this delegation revoke', rows, warnings, 'delegation.revoke', { delegationId });
+    });
+    mandates
+        .command('confirm')
+        .description('Confirm and enable proposed mandates or rules - candidates usually come from `botanary mandates propose`')
+        .requiredOption('--candidates-file <path>', 'JSON array of proposed objects, typically saved from `botanary mandates propose --json`')
+        .action(async (opts) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        const candidates = await readJsonFile(opts.candidatesFile, '--candidates-file');
+        if (!Array.isArray(candidates) || candidates.length === 0) {
+            throw invalidArgs('--candidates-file must contain a non-empty JSON array.');
+        }
+        const rows = [
+            { label: 'candidates', value: String(candidates.length) },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        await reviewAndSubmit(ctx, 'Review this mandate confirm', rows, [], 'mandate.confirm', { candidates });
+    });
+    mandates
+        .command('pause <mandateId>')
+        .description('Pause a mandate (reversible) - id from the Mandates (on-chain) table in `botanary mandates`')
+        .action(async (mandateId) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        const rows = [
+            { label: 'mandate', value: mandateId },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        await reviewAndSubmit(ctx, 'Review this mandate pause', rows, [], 'mandate.pause', { mandateId });
+    });
+    mandates
+        .command('resume <mandateId>')
+        .description('Resume a paused mandate - id from the Mandates (on-chain) table in `botanary mandates`')
+        .action(async (mandateId) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        const rows = [
+            { label: 'mandate', value: mandateId },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        await reviewAndSubmit(ctx, 'Review this mandate resume', rows, [], 'mandate.resume', { mandateId });
+    });
+    mandates
+        .command('cancel <mandateId>')
+        .description('Revoke a mandate (permanent) - named cancel, not revoke, to stay distinct from `mandates revoke`, which ' +
+        'targets a delegation, not a mandate. Id from the Mandates (on-chain) table in `botanary mandates`.')
+        .action(async (mandateId) => {
+        const ctx = program.opts().__ctx;
+        await requireWalletToken(ctx);
+        const rows = [
+            { label: 'mandate', value: mandateId },
+            { label: 'signed by', value: 'you, in your browser' },
+        ];
+        const warnings = ['This is permanent - use `botanary mandates pause` instead if you may want it back.'];
+        await reviewAndSubmit(ctx, 'Review this mandate cancel', rows, warnings, 'mandate.revoke', { mandateId });
+    });
     group(program
         .command('agents')
         .description('Connected agents and any pending approval requests')