feat: clarify Permit2 approval requirement after bot create

- Add `needsPermit2Approval` flag to create response; always true since on-chain allowances are not verified at creation time
- Update create endpoint messaging to explicitly name Permit2, mention gas costs, and guide users to approve before dry-run or live start
- Add warning banner in OneShotRunner to highlight Permit2 + gas requirement when `highlightPermit2` is set
- Land on Tools tab after successful bot creation to make "Approve allowances" the next obvious step
- Display persistent Permit2 approval warning banner on BotDetail page that dismisses after approval succeeds
- Update confirmation dialogs and help text throughout to reference "Permit2" instead of vague "router allowance" language
- Clarify that approval transactions cost "a little gas" and are one-time operations per input token
- Add callback `onApproved` to OneShotRunner to dismiss Permit2 banner when approve action succeeds

Author: bnolens

.textile-monorepo-source

@@ -1 +1 @@
-d6793d883ce3f83e24a797330e516b57419da1c3
+a953771c46c910ce1507c781200778ef395adb98

.textile-stitch-release-version

@@ -1 +1 @@
-0.1.163
+0.1.164

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "stitch-bot"
-version = "0.1.163"
+version = "0.1.164"
 edition = "2021"
 description = "Stitch — Textile filler-network operator bot; market-makes the filler order book with signed UniswapX limit orders."
 license = "AGPL-3.0-or-later"

Cargo.toml

@@ -253,7 +253,7 @@ pub struct CreateRequest {
     pub corridor_id: String,
     pub signer: SignerRequest,
     /// Start the bot immediately. Off by default: the recommended path is to
-    /// approve the router allowance and dry-run first.
+    /// approve Permit2 (costs a little gas) and dry-run first.
     #[serde(default)]
     pub start: bool,
 }
@@ -411,22 +411,34 @@ pub async fn create(
     // Re-read for the response — the wallet comes from the config just written, and the
     // state changed if the start took.
     let (bot, fleet) = state.bot_and_fleet(&name).await?;
+    // Create never checks on-chain Permit2 allowances. `docker.start` succeeding
+    // only means the container launched — the bot's own preflight can still fail
+    // and restart-loop if approvals are missing. Always tell the UI to surface
+    // the Permit2 handoff; Approve is a no-op when allowances are already set.
+    let needs_permit2_approval = true;
     Ok((
         axum::http::StatusCode::CREATED,
         Json(serde_json::json!({
             "bot": bots::to_body(&bot, &state, &fleet),
+            "needsPermit2Approval": needs_permit2_approval,
             "message": format!(
                 "{name} is set up for {} on {}. {}",
                 corridor.display_name,
                 corridor.network_label,
                 match (&start_error, started) {
                     (Some(reason), _) => format!(
                         "It was created but not started: {reason} Start it from its page once that \
-                         clears."
+                         clears. Approve Permit2 first if that was the blocker (needs a little gas)."
                     ),
-                    (None, true) => "It's running — check its logs.".to_string(),
+                    (None, true) => {
+                        "It's running — check its logs. If it restart-loops, approve Permit2 \
+                         (Tools → Approve allowances — needs a little gas)."
+                            .to_string()
+                    },
                     (None, false) => {
-                        "Approve the router allowance and dry-run it before starting.".to_string()
+                        "Next: approve Permit2 for its input tokens (Tools → Approve \
+                         allowances — needs a little gas), then dry-run before starting."
+                            .to_string()
                     }
                 }
             ),
@@ -630,6 +642,18 @@ mod tests {
         let v = Harness::parse(&body);
         assert_eq!(v["bot"]["running"], false);
         assert!(v["message"].as_str().unwrap().contains("dry-run"), "{body}");
+        assert!(
+            v["message"].as_str().unwrap().contains("Permit2"),
+            "create message should name Permit2: {body}"
+        );
+        assert!(
+            v["message"].as_str().unwrap().contains("gas"),
+            "create message should mention gas: {body}"
+        );
+        assert_eq!(
+            v["needsPermit2Approval"], true,
+            "create must hand off Permit2 regardless of container state: {body}"
+        );
         // The response must not echo the key back.
         assert!(!body.contains(TEST_KEY));
     }

src/panel/http/wizard.rs

@@ -9,6 +9,7 @@ import type {
   ActionResult,
   Bot,
   Corridor,
+  CreateBotResult,
   Fleet,
   MigrationResult,
   SaveResult,
@@ -139,7 +140,7 @@ export const api = {
   corridors: () => request<{ corridors: Corridor[] }>('/api/corridors'),
 
   createBot: (body: unknown) =>
-    request<{ bot: Bot; message: string }>('/api/bots', json(body)),
+    request<CreateBotResult>('/api/bots', json(body)),
 
   /**
    * Mint a fresh hot wallet for the Create wallet step. Returns address + seed

web/src/api.ts

@@ -29,10 +29,16 @@ export default function OneShotRunner({
   bot,
   canApprove,
   approveBlockedReason,
+  highlightPermit2 = false,
+  onApproved,
 }: {
   bot: string
   canApprove: boolean
   approveBlockedReason: string | null
+  /** After create: surface the Permit2 + gas requirement up front. */
+  highlightPermit2?: boolean
+  /** Fired when `stitch approve` exits successfully. */
+  onApproved?: () => void
 }) {
   const [lines, setLines] = useState<LogLine[]>([])
   const [running, setRunning] = useState<string | null>(null)
@@ -50,7 +56,7 @@ export default function OneShotRunner({
     if (
       action === 'approve' &&
       !window.confirm(
-        `Approve the router allowances for ${bot}? This sends transactions from its operator wallet and costs gas.`,
+        `Approve Permit2 for ${bot}'s input tokens?\n\nThis sends transactions from its operator wallet and costs a little gas. Without this approval the bot cannot trade.`,
       )
     ) {
       return
@@ -70,8 +76,12 @@ export default function OneShotRunner({
           if (event === 'line') {
             setLines((prev) => appendLine(prev, data as LogLine))
           } else if (event === 'exit') {
-            setExit(data as ExitEvent)
+            const result = data as ExitEvent
+            setExit(result)
             setRunning(null)
+            if (result.ok && result.action === 'approve') {
+              onApproved?.()
+            }
           } else if (event === 'error') {
             setError((data as { message: string }).message)
             setRunning(null)
@@ -88,6 +98,15 @@ export default function OneShotRunner({
 
   return (
     <div className="space-y-3">
+      {highlightPermit2 && (
+        <Banner tone="warning">
+          Before the first live start, run <strong>Approve allowances</strong>. That
+          grants Permit2 permission on each input token. The operator wallet needs a
+          little native gas for those one-time approval transactions — without them,
+          orders would post but fail to fill.
+        </Banner>
+      )}
+
       <div className="flex flex-wrap items-center gap-2">
         <Button
           busy={running === 'dry-run'}
@@ -103,7 +122,7 @@ export default function OneShotRunner({
           onClick={() => run('approve')}
           title={
             approveBlockedReason ??
-            'Grant the allowances the bot needs to trade. Sends transactions.'
+            'Approve input tokens to Permit2. Sends transactions and costs gas.'
           }
         >
           Approve allowances
@@ -122,8 +141,9 @@ export default function OneShotRunner({
       </div>
 
       <p className="text-xs text-faint">
-        Both run in a throwaway container with this bot's own config and key. A dry
-        run posts nothing; approve sends transactions and costs gas.
+        Both run in a throwaway container with this bot&apos;s own config and key. A
+        dry run posts nothing; Approve allowances sends Permit2 approval
+        transactions and costs a little gas.
       </p>
 
       {!canApprove && approveBlockedReason && (

web/src/components/OneShotRunner.tsx

@@ -269,7 +269,7 @@ function CorridorCard({
   async function apply() {
     if (
       !window.confirm(
-        `Switch ${bot.name} to a different corridor?\n\nThis replaces stitch.toml with the preset (your signer is kept). A running bot is stopped — approve tokens for the new corridor before starting.`,
+        `Switch ${bot.name} to a different corridor?\n\nThis replaces stitch.toml with the preset (your signer is kept). A running bot is stopped — approve Permit2 for the new corridor's tokens (needs a little gas) before starting.`,
       )
     ) {
       return

web/src/components/SettingsForm.tsx

@@ -93,7 +93,12 @@ export default function AddBot() {
       // Clear the secret from component state the moment it's no longer needed.
       setSigner(emptySigner)
       navigate(`/bots/${encodeURIComponent(res.bot.name)}`, {
-        state: { note: res.message },
+        state: {
+          note: res.message,
+          // From the create API — not `bot.running`. Docker can report running
+          // before the bot's Permit2 preflight finishes (and fails).
+          needsPermit2: res.needsPermit2Approval,
+        },
       })
     } catch (e) {
       setError(e instanceof ApiError ? e.message : String(e))
@@ -196,9 +201,10 @@ export default function AddBot() {
             />
             {!start && (
               <p className="text-xs text-faint">
-                Left off, the bot is created but stopped. Approve the router
-                allowance and dry-run it from its page first — that's the safer
-                order.
+                Left off, the bot is created but stopped. On its page, approve
+                Permit2 for the input tokens (needs a little gas on the operator
+                wallet), then dry-run — that&apos;s the safer order before the
+                first live start.
               </p>
             )}
 

web/src/pages/AddBot.tsx

@@ -36,10 +36,19 @@ export default function BotDetail() {
   const [error, setError] = useState<string | null>(null)
   // The wizard redirects here with what it just did, so its confirmation survives
   // the navigation.
-  const handoff = (useLocation().state as { note?: string } | null)?.note ?? null
-  const [note, setNote] = useState<string | null>(handoff)
+  const handoff = useLocation().state as {
+    note?: string
+    needsPermit2?: boolean
+  } | null
+  const [note, setNote] = useState<string | null>(handoff?.note ?? null)
+  const [showPermit2Banner, setShowPermit2Banner] = useState(
+    () => !!handoff?.needsPermit2,
+  )
   const [busy, setBusy] = useState<string | null>(null)
-  const [tab, setTab] = useState<Tab>('settings')
+  // After create, land on Tools so Approve allowances is the next obvious step.
+  const [tab, setTab] = useState<Tab>(() =>
+    handoff?.needsPermit2 ? 'tools' : 'settings',
+  )
   const [updates, setUpdates] = useState<UpdatesStatus | null>(null)
 
   const load = useCallback(async () => {
@@ -197,6 +206,30 @@ export default function BotDetail() {
         </Banner>
       )}
 
+      {showPermit2Banner && (
+        <Banner tone="warning" onDismiss={() => setShowPermit2Banner(false)}>
+          <div className="space-y-2">
+            <p>
+              <strong>Permit2 approval required.</strong> This bot cannot trade
+              until its operator wallet approves Permit2 for each input token.
+              That is a one-time on-chain step and needs a little native gas on
+              the wallet (for the approval transactions).
+            </p>
+            <p>
+              Open{' '}
+              <button
+                type="button"
+                className="font-bold underline hover:no-underline"
+                onClick={() => setTab('tools')}
+              >
+                Tools → Approve allowances
+              </button>
+              , then dry-run, then Start.
+            </p>
+          </div>
+        </Banner>
+      )}
+
       <Card>
         {/*
           On narrow screens a single flex+ml-auto row wraps badly: Update stays
@@ -366,6 +399,8 @@ export default function BotDetail() {
             bot={bot.name}
             canApprove={bot.canApprove}
             approveBlockedReason={bot.approveBlockedReason}
+            highlightPermit2={showPermit2Banner}
+            onApproved={() => setShowPermit2Banner(false)}
           />
         </Card>
       )}