From a5b5b73b20202ac37729b8d735ee834071e123ca Mon Sep 17 00:00:00 2001
From: Jingles <jinglescode@gmail.com>
Date: Fri, 1 May 2026 09:44:09 +0800
Subject: [PATCH 01/10] refactor: audit-driven surgical cleanup (dead code,
 React keys, CI, security headers) (#233)

* refactor: remove unused recharts and busboy deps; relocate swagger CSS

- Delete src/components/ui/chart.tsx (recharts wrapper, zero consumers)
- Remove recharts from dependencies
- Remove busboy and @types/busboy (formidable is the actual uploader)
- Move swagger-ui CSS imports out of _app.tsx into api-docs.tsx

* refactor(react): use signer address as stable key in ReviewSignersCard

Replaces array index with signer address (which is unique and stable across reorder/edit) on both desktop TableRow and mobile card view, preventing form-state misalignment when signers are removed or reordered.

* ci: add PR checks workflow, basic security headers, env comment

- Add .github/workflows/pr-checks.yml (lint/typecheck/test/build, continue-on-error initially)
- Add basic security headers in next.config.js (X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy). CSP and HSTS intentionally omitted.
- Add comment to src/env.js explaining why NextAuth env vars are commented (PrismaAdapter only, no providers configured)

* chore: add typecheck, format, format:check scripts

Used by .github/workflows/pr-checks.yml and developer workflow.

- typecheck: tsc --noEmit
- format: prettier --write .
- format:check: prettier --check .

* chore: refresh package-lock.json after recharts/busboy removal

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix: keep swagger-overrides.css in _app.tsx (Next requires global CSS at root)

Reverts only the swagger-overrides.css move from commit 4abe300. The
swagger-ui-react/swagger-ui.css import (from node_modules) remains
local to api-docs.tsx, so the original goal of keeping that bundle
out of every page is still achieved.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .github/workflows/pr-checks.yml               |  48 +++
 next.config.js                                |  18 +
 package-lock.json                             | 235 +----------
 package.json                                  |   6 +-
 .../create/ReviewSignersCard.tsx              |   4 +-
 src/components/ui/chart.tsx                   | 368 ------------------
 src/env.js                                    |   3 +
 src/pages/_app.tsx                            |   4 +-
 8 files changed, 77 insertions(+), 609 deletions(-)
 create mode 100644 .github/workflows/pr-checks.yml
 delete mode 100644 src/components/ui/chart.tsx

diff --git a/.github/workflows/pr-checks.yml b/.github/workflows/pr-checks.yml
new file mode 100644
index 00000000..9f260631
--- /dev/null
+++ b/.github/workflows/pr-checks.yml
@@ -0,0 +1,48 @@
+name: PR Checks
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+concurrency:
+  group: pr-checks-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate Prisma client
+        run: npx prisma generate
+
+      - name: Lint
+        run: npm run lint
+        continue-on-error: true
+
+      - name: Type check
+        run: npx tsc --noEmit
+        continue-on-error: true
+
+      - name: Test
+        run: npm run test:ci
+        continue-on-error: true
+
+      - name: Build
+        run: npm run build
+        env:
+          SKIP_ENV_VALIDATION: 'true'
+        continue-on-error: true
diff --git a/next.config.js b/next.config.js
index fb9abebd..32444230 100644
--- a/next.config.js
+++ b/next.config.js
@@ -75,6 +75,24 @@ const config = {
   
   // External packages for server components to avoid bundling issues
   serverExternalPackages: ["@fabianbormann/cardano-peer-connect"],
+
+  // Basic security headers applied to all routes.
+  // NOTE: Content-Security-Policy and Strict-Transport-Security are intentionally
+  // omitted — CSP would break inline scripts/styles and HSTS locks browsers to
+  // HTTPS for max-age and should only be enabled after team review.
+  async headers() {
+    return [
+      {
+        source: '/:path*',
+        headers: [
+          { key: 'X-Frame-Options', value: 'SAMEORIGIN' },
+          { key: 'X-Content-Type-Options', value: 'nosniff' },
+          { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
+          { key: 'Permissions-Policy', value: 'camera=(), microphone=(), geolocation=()' },
+        ],
+      },
+    ];
+  },
 };
 
 // Bundle analyzer - only enable when ANALYZE env var is set
diff --git a/package-lock.json b/package-lock.json
index 506f37ff..a7a0c437 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -44,7 +44,6 @@
         "@trpc/react-query": "^11.0.0-rc.446",
         "@trpc/server": "^11.0.0-rc.446",
         "@utxos/sdk": "^0.0.78",
-        "busboy": "^1.6.0",
         "class-variance-authority": "^0.7.0",
         "clsx": "^2.1.1",
         "cors": "^2.8.5",
@@ -64,7 +63,6 @@
         "react-dropzone": "^14.3.5",
         "react-hook-form": "^7.53.0",
         "react-markdown": "^10.1.0",
-        "recharts": "^2.12.7",
         "remark-gfm": "^4.0.1",
         "superjson": "^2.2.1",
         "swagger-jsdoc": "^6.2.8",
@@ -85,7 +83,6 @@
         "@next/bundle-analyzer": "^16.0.10",
         "@react-three/drei": "^9.122.0",
         "@react-three/fiber": "^8.17.7",
-        "@types/busboy": "^1.5.4",
         "@types/cors": "^2.8.18",
         "@types/eslint": "^8.56.10",
         "@types/formidable": "^3.4.5",
@@ -6247,15 +6244,6 @@
         "@types/node": "*"
       }
     },
-    "node_modules/@types/busboy": {
-      "version": "1.5.4",
-      "resolved": "https://registry.npmjs.org/@types/busboy/-/busboy-1.5.4.tgz",
-      "integrity": "sha512-kG7WrUuAKK0NoyxfQHsVE6j1m01s6kMma64E+OZenQABMQyTJop1DumUWcLwAQ2JzpefU7PDYoRDKl8uZosFjw==",
-      "dev": true,
-      "dependencies": {
-        "@types/node": "*"
-      }
-    },
     "node_modules/@types/cors": {
       "version": "2.8.19",
       "resolved": "https://registry.npmjs.org/@types/cors/-/cors-2.8.19.tgz",
@@ -6265,60 +6253,6 @@
         "@types/node": "*"
       }
     },
-    "node_modules/@types/d3-array": {
-      "version": "3.2.2",
-      "resolved": "https://registry.npmjs.org/@types/d3-array/-/d3-array-3.2.2.tgz",
-      "integrity": "sha512-hOLWVbm7uRza0BYXpIIW5pxfrKe0W+D5lrFiAEYR+pb6w3N2SwSMaJbXdUfSEv+dT4MfHBLtn5js0LAWaO6otw=="
-    },
-    "node_modules/@types/d3-color": {
-      "version": "3.1.3",
-      "resolved": "https://registry.npmjs.org/@types/d3-color/-/d3-color-3.1.3.tgz",
-      "integrity": "sha512-iO90scth9WAbmgv7ogoq57O9YpKmFBbmoEoCHDB2xMBY0+/KVrqAaCDyCE16dUspeOvIxFFRI+0sEtqDqy2b4A=="
-    },
-    "node_modules/@types/d3-ease": {
-      "version": "3.0.2",
-      "resolved": "https://registry.npmjs.org/@types/d3-ease/-/d3-ease-3.0.2.tgz",
-      "integrity": "sha512-NcV1JjO5oDzoK26oMzbILE6HW7uVXOHLQvHshBUW4UMdZGfiY6v5BeQwh9a9tCzv+CeefZQHJt5SRgK154RtiA=="
-    },
-    "node_modules/@types/d3-interpolate": {
-      "version": "3.0.4",
-      "resolved": "https://registry.npmjs.org/@types/d3-interpolate/-/d3-interpolate-3.0.4.tgz",
-      "integrity": "sha512-mgLPETlrpVV1YRJIglr4Ez47g7Yxjl1lj7YKsiMCb27VJH9W8NVM6Bb9d8kkpG/uAQS5AmbA48q2IAolKKo1MA==",
-      "dependencies": {
-        "@types/d3-color": "*"
-      }
-    },
-    "node_modules/@types/d3-path": {
-      "version": "3.1.1",
-      "resolved": "https://registry.npmjs.org/@types/d3-path/-/d3-path-3.1.1.tgz",
-      "integrity": "sha512-VMZBYyQvbGmWyWVea0EHs/BwLgxc+MKi1zLDCONksozI4YJMcTt8ZEuIR4Sb1MMTE8MMW49v0IwI5+b7RmfWlg=="
-    },
-    "node_modules/@types/d3-scale": {
-      "version": "4.0.9",
-      "resolved": "https://registry.npmjs.org/@types/d3-scale/-/d3-scale-4.0.9.tgz",
-      "integrity": "sha512-dLmtwB8zkAeO/juAMfnV+sItKjlsw2lKdZVVy6LRr0cBmegxSABiLEpGVmSJJ8O08i4+sGR6qQtb6WtuwJdvVw==",
-      "dependencies": {
-        "@types/d3-time": "*"
-      }
-    },
-    "node_modules/@types/d3-shape": {
-      "version": "3.1.8",
-      "resolved": "https://registry.npmjs.org/@types/d3-shape/-/d3-shape-3.1.8.tgz",
-      "integrity": "sha512-lae0iWfcDeR7qt7rA88BNiqdvPS5pFVPpo5OfjElwNaT2yyekbM0C9vK+yqBqEmHr6lDkRnYNoTBYlAgJa7a4w==",
-      "dependencies": {
-        "@types/d3-path": "*"
-      }
-    },
-    "node_modules/@types/d3-time": {
-      "version": "3.0.4",
-      "resolved": "https://registry.npmjs.org/@types/d3-time/-/d3-time-3.0.4.tgz",
-      "integrity": "sha512-yuzZug1nkAAaBlBBikKZTgzCeA+k1uy4ZFwWANOfKw5z5LRhV0gNA7gNkKm7HoK+HRN0wX3EkxGk0fpbWhmB7g=="
-    },
-    "node_modules/@types/d3-timer": {
-      "version": "3.0.2",
-      "resolved": "https://registry.npmjs.org/@types/d3-timer/-/d3-timer-3.0.2.tgz",
-      "integrity": "sha512-Ps3T8E8dZDam6fUyNiMkekK3XUsaUEik+idO9/YjPtfj2qruF8tFBXS7XhtE4iIXBLxhmLjP3SXpLhVf21I9Lw=="
-    },
     "node_modules/@types/debug": {
       "version": "4.1.13",
       "resolved": "https://registry.npmjs.org/@types/debug/-/debug-4.1.13.tgz",
@@ -9284,17 +9218,6 @@
         "node": ">=6.14.2"
       }
     },
-    "node_modules/busboy": {
-      "version": "1.6.0",
-      "resolved": "https://registry.npmjs.org/busboy/-/busboy-1.6.0.tgz",
-      "integrity": "sha512-8SFQbg/0hQ9xy3UNTB0YEnsNBbWfhf7RtnzpL7TkBiTBRfrQ9Fxcnz7VJsleJpyp6rVLvXiuORqjlHi5q+PYuA==",
-      "dependencies": {
-        "streamsearch": "^1.1.0"
-      },
-      "engines": {
-        "node": ">=10.16.0"
-      }
-    },
     "node_modules/c12": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/c12/-/c12-3.1.0.tgz",
@@ -10093,14 +10016,6 @@
         "node": ">=12"
       }
     },
-    "node_modules/d3-ease": {
-      "version": "3.0.1",
-      "resolved": "https://registry.npmjs.org/d3-ease/-/d3-ease-3.0.1.tgz",
-      "integrity": "sha512-wR/XK3D3XcLIZwpbvQwQ5fK+8Ykds1ip7A2Txe0yxncXSdq1L9skcG7blcedkOX+ZcgxGAmLX1FrRGbADwzi0w==",
-      "engines": {
-        "node": ">=12"
-      }
-    },
     "node_modules/d3-format": {
       "version": "3.1.2",
       "resolved": "https://registry.npmjs.org/d3-format/-/d3-format-3.1.2.tgz",
@@ -10150,14 +10065,6 @@
       "resolved": "https://registry.npmjs.org/d3-octree/-/d3-octree-1.1.0.tgz",
       "integrity": "sha512-F8gPlqpP+HwRPMO/8uOu5wjH110+6q4cgJvgJT6vlpy3BEaDIKlTZrgHKZSp/i1InRpVfh4puY/kvL6MxK930A=="
     },
-    "node_modules/d3-path": {
-      "version": "3.1.0",
-      "resolved": "https://registry.npmjs.org/d3-path/-/d3-path-3.1.0.tgz",
-      "integrity": "sha512-p3KP5HCf/bvjBSSKuXid6Zqijx7wIfNW+J/maPs+iwR35at5JCbLUT0LzF1cnjbCHWhqzQTIN2Jpe8pRebIEFQ==",
-      "engines": {
-        "node": ">=12"
-      }
-    },
     "node_modules/d3-scale": {
       "version": "4.0.2",
       "resolved": "https://registry.npmjs.org/d3-scale/-/d3-scale-4.0.2.tgz",
@@ -10185,17 +10092,6 @@
         "node": ">=12"
       }
     },
-    "node_modules/d3-shape": {
-      "version": "3.2.0",
-      "resolved": "https://registry.npmjs.org/d3-shape/-/d3-shape-3.2.0.tgz",
-      "integrity": "sha512-SaLBuwGm3MOViRq2ABk3eLoxwZELpH6zhl3FbAoJ7Vm1gofKx6El1Ib5z23NUEhF9AsGl7y+dzLe5Cw2AArGTA==",
-      "dependencies": {
-        "d3-path": "^3.1.0"
-      },
-      "engines": {
-        "node": ">=12"
-      }
-    },
     "node_modules/d3-time": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/d3-time/-/d3-time-3.1.0.tgz",
@@ -10218,14 +10114,6 @@
         "node": ">=12"
       }
     },
-    "node_modules/d3-timer": {
-      "version": "3.0.1",
-      "resolved": "https://registry.npmjs.org/d3-timer/-/d3-timer-3.0.1.tgz",
-      "integrity": "sha512-ndfJ/JxxMd3nw31uyKoY2naivF+r29V+Lc0svZxe1JvvIRmi8hUsrMvdOwgS1o6uBHmiz91geQ0ylPP0aj1VUA==",
-      "engines": {
-        "node": ">=12"
-      }
-    },
     "node_modules/d3-tricontour": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/d3-tricontour/-/d3-tricontour-1.1.0.tgz",
@@ -10341,11 +10229,6 @@
         }
       }
     },
-    "node_modules/decimal.js-light": {
-      "version": "2.5.1",
-      "resolved": "https://registry.npmjs.org/decimal.js-light/-/decimal.js-light-2.5.1.tgz",
-      "integrity": "sha512-qIMFpTMZmny+MMIitAB6D7iVPEorVw6YQRWkvarTkT4tBeSLLiHzcwj6q0MmYSFCiVpiqPJTJEYIrpcPzVEIvg=="
-    },
     "node_modules/decode-named-character-reference": {
       "version": "1.3.0",
       "resolved": "https://registry.npmjs.org/decode-named-character-reference/-/decode-named-character-reference-1.3.0.tgz",
@@ -10702,15 +10585,6 @@
         "node": ">=0.10.0"
       }
     },
-    "node_modules/dom-helpers": {
-      "version": "5.2.1",
-      "resolved": "https://registry.npmjs.org/dom-helpers/-/dom-helpers-5.2.1.tgz",
-      "integrity": "sha512-nRCa7CK3VTrM2NmGkIy4cbK7IZlgBE/PYMn55rrXefr5xXDP0LdtfPnblFDoVdcAfslJ7or6iqAUnx0CCGIWQA==",
-      "dependencies": {
-        "@babel/runtime": "^7.8.7",
-        "csstype": "^3.0.2"
-      }
-    },
     "node_modules/dom-walk": {
       "version": "0.1.2",
       "resolved": "https://registry.npmjs.org/dom-walk/-/dom-walk-0.1.2.tgz",
@@ -11689,14 +11563,6 @@
       "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
       "dev": true
     },
-    "node_modules/fast-equals": {
-      "version": "5.4.0",
-      "resolved": "https://registry.npmjs.org/fast-equals/-/fast-equals-5.4.0.tgz",
-      "integrity": "sha512-jt2DW/aNFNwke7AUd+Z+e6pz39KO5rzdbbFCg2sGafS4mk13MI7Z8O5z9cADNn5lhGODIgLwug6TZO2ctf7kcw==",
-      "engines": {
-        "node": ">=6.0.0"
-      }
-    },
     "node_modules/fast-fifo": {
       "version": "1.3.2",
       "resolved": "https://registry.npmjs.org/fast-fifo/-/fast-fifo-1.3.2.tgz",
@@ -20981,7 +20847,8 @@
     "node_modules/react-is": {
       "version": "18.3.1",
       "resolved": "https://registry.npmjs.org/react-is/-/react-is-18.3.1.tgz",
-      "integrity": "sha512-/LLMVyas0ljjAtoYiPqYiL8VWXzUUdThrmU5+n20DZv+a+ClRoevUzw5JxU+Ieh5/c87ytoTBV9G1FiKfNJdmg=="
+      "integrity": "sha512-/LLMVyas0ljjAtoYiPqYiL8VWXzUUdThrmU5+n20DZv+a+ClRoevUzw5JxU+Ieh5/c87ytoTBV9G1FiKfNJdmg==",
+      "dev": true
     },
     "node_modules/react-markdown": {
       "version": "10.1.0",
@@ -21092,20 +20959,6 @@
         }
       }
     },
-    "node_modules/react-smooth": {
-      "version": "4.0.4",
-      "resolved": "https://registry.npmjs.org/react-smooth/-/react-smooth-4.0.4.tgz",
-      "integrity": "sha512-gnGKTpYwqL0Iii09gHobNolvX4Kiq4PKx6eWBCYYix+8cdw+cGo3do906l1NBPKkSWx1DghC1dlWG9L2uGd61Q==",
-      "dependencies": {
-        "fast-equals": "^5.0.1",
-        "prop-types": "^15.8.1",
-        "react-transition-group": "^4.4.5"
-      },
-      "peerDependencies": {
-        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
-        "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
-      }
-    },
     "node_modules/react-style-singleton": {
       "version": "2.2.3",
       "resolved": "https://registry.npmjs.org/react-style-singleton/-/react-style-singleton-2.2.3.tgz",
@@ -21146,21 +20999,6 @@
         "react": ">= 0.14.0"
       }
     },
-    "node_modules/react-transition-group": {
-      "version": "4.4.5",
-      "resolved": "https://registry.npmjs.org/react-transition-group/-/react-transition-group-4.4.5.tgz",
-      "integrity": "sha512-pZcd1MCJoiKiBR2NRxeCRg13uCXbydPnmB4EOeRrY7480qNWO8IIgQG6zlDkm6uRMsURXPuKq0GWtiM59a5Q6g==",
-      "dependencies": {
-        "@babel/runtime": "^7.5.5",
-        "dom-helpers": "^5.0.1",
-        "loose-envify": "^1.4.0",
-        "prop-types": "^15.6.2"
-      },
-      "peerDependencies": {
-        "react": ">=16.6.0",
-        "react-dom": ">=16.6.0"
-      }
-    },
     "node_modules/react-use-measure": {
       "version": "2.1.7",
       "resolved": "https://registry.npmjs.org/react-use-measure/-/react-use-measure-2.1.7.tgz",
@@ -21208,41 +21046,6 @@
         "url": "https://paulmillr.com/funding/"
       }
     },
-    "node_modules/recharts": {
-      "version": "2.15.4",
-      "resolved": "https://registry.npmjs.org/recharts/-/recharts-2.15.4.tgz",
-      "integrity": "sha512-UT/q6fwS3c1dHbXv2uFgYJ9BMFHu3fwnd7AYZaEQhXuYQ4hgsxLvsUXzGdKeZrW5xopzDCvuA2N41WJ88I7zIw==",
-      "dependencies": {
-        "clsx": "^2.0.0",
-        "eventemitter3": "^4.0.1",
-        "lodash": "^4.17.21",
-        "react-is": "^18.3.1",
-        "react-smooth": "^4.0.4",
-        "recharts-scale": "^0.4.4",
-        "tiny-invariant": "^1.3.1",
-        "victory-vendor": "^36.6.8"
-      },
-      "engines": {
-        "node": ">=14"
-      },
-      "peerDependencies": {
-        "react": "^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
-        "react-dom": "^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
-      }
-    },
-    "node_modules/recharts-scale": {
-      "version": "0.4.5",
-      "resolved": "https://registry.npmjs.org/recharts-scale/-/recharts-scale-0.4.5.tgz",
-      "integrity": "sha512-kivNFO+0OcUNu7jQquLXAxz1FIwZj8nrj+YkOKc5694NbjCvcT6aSZiIzNzd2Kul4o4rTto8QVR9lMNtxD4G1w==",
-      "dependencies": {
-        "decimal.js-light": "^2.4.1"
-      }
-    },
-    "node_modules/recharts/node_modules/eventemitter3": {
-      "version": "4.0.7",
-      "resolved": "https://registry.npmjs.org/eventemitter3/-/eventemitter3-4.0.7.tgz",
-      "integrity": "sha512-8guHBZCwKnFhYdHr2ysuRWErTwhoN2X8XELRlrRwpmfeY2jjuUN4taQMsULKUVo1K4DvZl+0pgfyoysHxvmvEw=="
-    },
     "node_modules/record-cache": {
       "version": "1.2.0",
       "resolved": "https://registry.npmjs.org/record-cache/-/record-cache-1.2.0.tgz",
@@ -22253,14 +22056,6 @@
         "node": ">= 0.4"
       }
     },
-    "node_modules/streamsearch": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/streamsearch/-/streamsearch-1.1.0.tgz",
-      "integrity": "sha512-Mcc5wHehp9aXz1ax6bZUyY5afg9u2rv5cqQI3mRrYkGC8rW2hM02jWuwjtL++LS5qinSyhj2QfLyNsuc+VsExg==",
-      "engines": {
-        "node": ">=10.0.0"
-      }
-    },
     "node_modules/streamx": {
       "version": "2.22.1",
       "resolved": "https://registry.npmjs.org/streamx/-/streamx-2.22.1.tgz",
@@ -23127,11 +22922,6 @@
       "integrity": "sha512-Mz0CX4vBGM5lj8ttbIFt7o4ZMxk/9rgudJRh76EvB7xXZMur7T/cjRiH2w4Fmkq0zxf2QpM8IFvOSRn8FEu3gA==",
       "optional": true
     },
-    "node_modules/tiny-invariant": {
-      "version": "1.3.3",
-      "resolved": "https://registry.npmjs.org/tiny-invariant/-/tiny-invariant-1.3.3.tgz",
-      "integrity": "sha512-+FbBPE1o9QAYvviau/qC5SE3caw21q3xkvWKBtja5vgqOWIHHJ3ioaq1VPfn/Szqctz2bU/oYeKd9/z5BL+PVg=="
-    },
     "node_modules/tinycolor2": {
       "version": "1.6.0",
       "resolved": "https://registry.npmjs.org/tinycolor2/-/tinycolor2-1.6.0.tgz",
@@ -24312,27 +24102,6 @@
         "url": "https://opencollective.com/unified"
       }
     },
-    "node_modules/victory-vendor": {
-      "version": "36.9.2",
-      "resolved": "https://registry.npmjs.org/victory-vendor/-/victory-vendor-36.9.2.tgz",
-      "integrity": "sha512-PnpQQMuxlwYdocC8fIJqVXvkeViHYzotI+NJrCuav0ZYFoq912ZHBk3mCeuj+5/VpodOjPe1z0Fk2ihgzlXqjQ==",
-      "dependencies": {
-        "@types/d3-array": "^3.0.3",
-        "@types/d3-ease": "^3.0.0",
-        "@types/d3-interpolate": "^3.0.1",
-        "@types/d3-scale": "^4.0.2",
-        "@types/d3-shape": "^3.1.0",
-        "@types/d3-time": "^3.0.0",
-        "@types/d3-timer": "^3.0.0",
-        "d3-array": "^3.1.6",
-        "d3-ease": "^3.0.1",
-        "d3-interpolate": "^3.0.1",
-        "d3-scale": "^4.0.2",
-        "d3-shape": "^3.1.0",
-        "d3-time": "^3.0.0",
-        "d3-timer": "^3.0.1"
-      }
-    },
     "node_modules/vm-browserify": {
       "version": "1.1.2",
       "resolved": "https://registry.npmjs.org/vm-browserify/-/vm-browserify-1.1.2.tgz",
diff --git a/package.json b/package.json
index ef470275..bc6e55f3 100644
--- a/package.json
+++ b/package.json
@@ -14,6 +14,9 @@
     "dev": "next dev",
     "postinstall": "prisma generate",
     "lint": "next lint",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
     "prestart": "prisma migrate deploy",
     "start": "next start",
     "test": "jest",
@@ -59,7 +62,6 @@
     "@trpc/react-query": "^11.0.0-rc.446",
     "@trpc/server": "^11.0.0-rc.446",
     "@utxos/sdk": "^0.0.78",
-    "busboy": "^1.6.0",
     "class-variance-authority": "^0.7.0",
     "clsx": "^2.1.1",
     "cors": "^2.8.5",
@@ -79,7 +81,6 @@
     "react-dropzone": "^14.3.5",
     "react-hook-form": "^7.53.0",
     "react-markdown": "^10.1.0",
-    "recharts": "^2.12.7",
     "remark-gfm": "^4.0.1",
     "superjson": "^2.2.1",
     "swagger-jsdoc": "^6.2.8",
@@ -100,7 +101,6 @@
     "@next/bundle-analyzer": "^16.0.10",
     "@react-three/drei": "^9.122.0",
     "@react-three/fiber": "^8.17.7",
-    "@types/busboy": "^1.5.4",
     "@types/cors": "^2.8.18",
     "@types/eslint": "^8.56.10",
     "@types/formidable": "^3.4.5",
diff --git a/src/components/pages/homepage/wallets/new-wallet-flow/create/ReviewSignersCard.tsx b/src/components/pages/homepage/wallets/new-wallet-flow/create/ReviewSignersCard.tsx
index 2b340b3c..9232b688 100644
--- a/src/components/pages/homepage/wallets/new-wallet-flow/create/ReviewSignersCard.tsx
+++ b/src/components/pages/homepage/wallets/new-wallet-flow/create/ReviewSignersCard.tsx
@@ -263,7 +263,7 @@ const ReviewSignersCard: React.FC<ReviewSignersCardProps> = ({
                 </TableHeader>
                 <TableBody>
                   {signersAddresses.map((signer, index) => (
-                    <TableRow key={index}>
+                    <TableRow key={signer}>
                       {/* Signer name */}
                       <TableCell>
                         <span className="flex items-center gap-2">
@@ -374,7 +374,7 @@ const ReviewSignersCard: React.FC<ReviewSignersCardProps> = ({
             <div className="space-y-3 sm:hidden">
               {signersAddresses.map((signer, index) => (
                 <div
-                  key={index}
+                  key={signer}
                   className="space-y-2 rounded-lg border border-black/10 p-4 dark:border-white/5"
                 >
                   {/* Top row: Name and Actions */}
diff --git a/src/components/ui/chart.tsx b/src/components/ui/chart.tsx
deleted file mode 100644
index a9a39ad9..00000000
--- a/src/components/ui/chart.tsx
+++ /dev/null
@@ -1,368 +0,0 @@
-import * as React from "react"
-import * as RechartsPrimitive from "recharts"
-import {
-  NameType,
-  Payload,
-  ValueType,
-} from "recharts/types/component/DefaultTooltipContent"
-
-import { cn } from "@/lib/utils"
-
-// Format: { THEME_NAME: CSS_SELECTOR }
-const THEMES = { light: "", dark: ".dark" } as const
-
-export type ChartConfig = {
-  [k in string]: {
-    label?: React.ReactNode
-    icon?: React.ComponentType
-  } & (
-    | { color?: string; theme?: never }
-    | { color?: never; theme: Record<keyof typeof THEMES, string> }
-  )
-}
-
-type ChartContextProps = {
-  config: ChartConfig
-}
-
-const ChartContext = React.createContext<ChartContextProps | null>(null)
-
-function useChart() {
-  const context = React.useContext(ChartContext)
-
-  if (!context) {
-    throw new Error("useChart must be used within a <ChartContainer />")
-  }
-
-  return context
-}
-
-const ChartContainer = React.forwardRef<
-  HTMLDivElement,
-  React.ComponentProps<"div"> & {
-    config: ChartConfig
-    children: React.ComponentProps<
-      typeof RechartsPrimitive.ResponsiveContainer
-    >["children"]
-  }
->(({ id, className, children, config, ...props }, ref) => {
-  const uniqueId = React.useId()
-  const chartId = `chart-${id || uniqueId.replace(/:/g, "")}`
-
-  return (
-    <ChartContext.Provider value={{ config }}>
-      <div
-        data-chart={chartId}
-        ref={ref}
-        className={cn(
-          "flex aspect-video justify-center text-xs [&_.recharts-cartesian-axis-tick_text]:fill-muted-foreground [&_.recharts-cartesian-grid_line[stroke='#ccc']]:stroke-border/50 [&_.recharts-curve.recharts-tooltip-cursor]:stroke-border [&_.recharts-dot[stroke='#fff']]:stroke-transparent [&_.recharts-layer]:outline-none [&_.recharts-polar-grid_[stroke='#ccc']]:stroke-border [&_.recharts-radial-bar-background-sector]:fill-muted [&_.recharts-rectangle.recharts-tooltip-cursor]:fill-muted [&_.recharts-reference-line_[stroke='#ccc']]:stroke-border [&_.recharts-sector[stroke='#fff']]:stroke-transparent [&_.recharts-sector]:outline-none [&_.recharts-surface]:outline-none",
-          className
-        )}
-        {...props}
-      >
-        <ChartStyle id={chartId} config={config} />
-        <RechartsPrimitive.ResponsiveContainer>
-          {children}
-        </RechartsPrimitive.ResponsiveContainer>
-      </div>
-    </ChartContext.Provider>
-  )
-})
-ChartContainer.displayName = "Chart"
-
-const ChartStyle = ({ id, config }: { id: string; config: ChartConfig }) => {
-  const colorConfig = Object.entries(config).filter(
-    ([_, config]) => config.theme || config.color
-  )
-
-  if (!colorConfig.length) {
-    return null
-  }
-
-  return (
-    <style
-      dangerouslySetInnerHTML={{
-        __html: Object.entries(THEMES)
-          .map(
-            ([theme, prefix]) => `
-${prefix} [data-chart=${id}] {
-${colorConfig
-  .map(([key, itemConfig]) => {
-    const color =
-      itemConfig.theme?.[theme as keyof typeof itemConfig.theme] ||
-      itemConfig.color
-    return color ? `  --color-${key}: ${color};` : null
-  })
-  .join("\n")}
-}
-`
-          )
-          .join("\n"),
-      }}
-    />
-  )
-}
-
-const ChartTooltip = RechartsPrimitive.Tooltip
-
-const ChartTooltipContent = React.forwardRef<
-  HTMLDivElement,
-  React.ComponentProps<typeof RechartsPrimitive.Tooltip> &
-    React.ComponentProps<"div"> & {
-      hideLabel?: boolean
-      hideIndicator?: boolean
-      indicator?: "line" | "dot" | "dashed"
-      nameKey?: string
-      labelKey?: string
-    }
->(
-  (
-    {
-      active,
-      payload,
-      className,
-      indicator = "dot",
-      hideLabel = false,
-      hideIndicator = false,
-      label,
-      labelFormatter,
-      labelClassName,
-      formatter,
-      color,
-      nameKey,
-      labelKey,
-    },
-    ref
-  ) => {
-    const { config } = useChart()
-
-    const tooltipLabel = React.useMemo(() => {
-      if (hideLabel || !payload?.length) {
-        return null
-      }
-
-      const [item] = payload
-      const key = `${labelKey || item!.dataKey || item!.name || "value"}`
-      const itemConfig = getPayloadConfigFromPayload(config, item, key)
-      const value =
-        !labelKey && typeof label === "string"
-          ? config[label as keyof typeof config]?.label || label
-          : itemConfig?.label
-
-      if (labelFormatter) {
-        return (
-          <div className={cn("font-medium", labelClassName)}>
-            {labelFormatter(value, payload)}
-          </div>
-        )
-      }
-
-      if (!value) {
-        return null
-      }
-
-      return <div className={cn("font-medium", labelClassName)}>{value}</div>
-    }, [
-      label,
-      labelFormatter,
-      payload,
-      hideLabel,
-      labelClassName,
-      config,
-      labelKey,
-    ])
-
-    if (!active || !payload?.length) {
-      return null
-    }
-
-    const nestLabel = payload.length === 1 && indicator !== "dot"
-
-    return (
-      <div
-        ref={ref}
-        className={cn(
-          "grid min-w-[8rem] items-start gap-1.5 rounded-lg border border-border/50 bg-background px-2.5 py-1.5 text-xs shadow-xl",
-          className
-        )}
-      >
-        {!nestLabel ? tooltipLabel : null}
-        <div className="grid gap-1.5">
-          {payload.map((item, index) => {
-            const key = `${nameKey || item.name || item.dataKey || "value"}`
-            const itemConfig = getPayloadConfigFromPayload(config, item, key)
-            const indicatorColor = color || item.payload.fill || item.color
-
-            return (
-              <div
-                key={item.dataKey}
-                className={cn(
-                  "flex w-full flex-wrap items-stretch gap-2 [&>svg]:h-2.5 [&>svg]:w-2.5 [&>svg]:text-muted-foreground",
-                  indicator === "dot" && "items-center"
-                )}
-              >
-                {formatter && item?.value !== undefined && item.name ? (
-                  formatter(item.value, item.name, item, index, item.payload)
-                ) : (
-                  <>
-                    {itemConfig?.icon ? (
-                      <itemConfig.icon />
-                    ) : (
-                      !hideIndicator && (
-                        <div
-                          className={cn(
-                            "shrink-0 rounded-[2px] border-[--color-border] bg-[--color-bg]",
-                            {
-                              "h-2.5 w-2.5": indicator === "dot",
-                              "w-1": indicator === "line",
-                              "w-0 border-[1.5px] border-dashed bg-transparent":
-                                indicator === "dashed",
-                              "my-0.5": nestLabel && indicator === "dashed",
-                            }
-                          )}
-                          style={
-                            {
-                              "--color-bg": indicatorColor,
-                              "--color-border": indicatorColor,
-                            } as React.CSSProperties
-                          }
-                        />
-                      )
-                    )}
-                    <div
-                      className={cn(
-                        "flex flex-1 justify-between leading-none",
-                        nestLabel ? "items-end" : "items-center"
-                      )}
-                    >
-                      <div className="grid gap-1.5">
-                        {nestLabel ? tooltipLabel : null}
-                        <span className="text-muted-foreground">
-                          {itemConfig?.label || item.name}
-                        </span>
-                      </div>
-                      {item.value && (
-                        <span className="font-mono font-medium tabular-nums text-foreground">
-                          {item.value.toLocaleString()}
-                        </span>
-                      )}
-                    </div>
-                  </>
-                )}
-              </div>
-            )
-          })}
-        </div>
-      </div>
-    )
-  }
-)
-ChartTooltipContent.displayName = "ChartTooltip"
-
-const ChartLegend = RechartsPrimitive.Legend
-
-const ChartLegendContent = React.forwardRef<
-  HTMLDivElement,
-  React.ComponentProps<"div"> &
-    Pick<RechartsPrimitive.LegendProps, "payload" | "verticalAlign"> & {
-      hideIcon?: boolean
-      nameKey?: string
-    }
->(
-  (
-    { className, hideIcon = false, payload, verticalAlign = "bottom", nameKey },
-    ref
-  ) => {
-    const { config } = useChart()
-
-    if (!payload?.length) {
-      return null
-    }
-
-    return (
-      <div
-        ref={ref}
-        className={cn(
-          "flex items-center justify-center gap-4",
-          verticalAlign === "top" ? "pb-3" : "pt-3",
-          className
-        )}
-      >
-        {payload.map((item) => {
-          const key = `${nameKey || item.dataKey || "value"}`
-          const itemConfig = getPayloadConfigFromPayload(config, item, key)
-
-          return (
-            <div
-              key={item.value}
-              className={cn(
-                "flex items-center gap-1.5 [&>svg]:h-3 [&>svg]:w-3 [&>svg]:text-muted-foreground"
-              )}
-            >
-              {itemConfig?.icon && !hideIcon ? (
-                <itemConfig.icon />
-              ) : (
-                <div
-                  className="h-2 w-2 shrink-0 rounded-[2px]"
-                  style={{
-                    backgroundColor: item.color,
-                  }}
-                />
-              )}
-              {itemConfig?.label}
-            </div>
-          )
-        })}
-      </div>
-    )
-  }
-)
-ChartLegendContent.displayName = "ChartLegend"
-
-// Helper to extract item config from a payload.
-function getPayloadConfigFromPayload(
-  config: ChartConfig,
-  payload: unknown,
-  key: string
-) {
-  if (typeof payload !== "object" || payload === null) {
-    return undefined
-  }
-
-  const payloadPayload =
-    "payload" in payload &&
-    typeof payload.payload === "object" &&
-    payload.payload !== null
-      ? payload.payload
-      : undefined
-
-  let configLabelKey: string = key
-
-  if (
-    key in payload &&
-    typeof payload[key as keyof typeof payload] === "string"
-  ) {
-    configLabelKey = payload[key as keyof typeof payload] as string
-  } else if (
-    payloadPayload &&
-    key in payloadPayload &&
-    typeof payloadPayload[key as keyof typeof payloadPayload] === "string"
-  ) {
-    configLabelKey = payloadPayload[
-      key as keyof typeof payloadPayload
-    ] as string
-  }
-
-  return configLabelKey in config
-    ? config[configLabelKey]
-    : config[key as keyof typeof config]
-}
-
-export {
-  ChartContainer,
-  ChartTooltip,
-  ChartTooltipContent,
-  ChartLegend,
-  ChartLegendContent,
-  ChartStyle,
-}
diff --git a/src/env.js b/src/env.js
index af5fdc6c..a60d68ea 100644
--- a/src/env.js
+++ b/src/env.js
@@ -17,6 +17,9 @@ export const env = createEnv({
     JWT_SECRET: z.string().min(32),
     BLOCKFROST_API_KEY_PREPROD: z.string().optional(),
     BLOCKFROST_API_KEY_MAINNET: z.string().optional(),
+    // NEXTAUTH_SECRET / NEXTAUTH_URL / DISCORD_* are intentionally commented.
+    // NextAuth runs with PrismaAdapter only — no auth providers configured yet.
+    // Uncomment and add to runtimeEnv below when adding an OAuth provider.
     // NEXTAUTH_SECRET:
     //   process.env.NODE_ENV === "production"
     //     ? z.string()
diff --git a/src/pages/_app.tsx b/src/pages/_app.tsx
index 65af05de..903d99bb 100644
--- a/src/pages/_app.tsx
+++ b/src/pages/_app.tsx
@@ -13,14 +13,12 @@ import { env } from "@/env";
 import { api } from "@/utils/api";
 
 import "@/styles/globals.css";
+import "@/styles/swagger-overrides.css";
 import { Toaster } from "@/components/ui/toaster";
 import Metatags from "@/components/ui/metatags";
 import RootLayout from "@/components/common/overall-layout/layout";
 import { NostrChatProvider } from "@jinglescode/nostr-chat-plugin";
 
-import "swagger-ui-react/swagger-ui.css";
-import "../styles/swagger-overrides.css";
-
 // MeshProvider pulls in dependencies that assume a browser/webpack env.
 // Load it client-side only (including its styles) to avoid SSR/runtime issues.
 const MeshProviderNoSSR = dynamic(

From 577708439a7bca058625e87705444b38644ee4d4 Mon Sep 17 00:00:00 2001
From: Jingles <jinglescode@gmail.com>
Date: Sun, 10 May 2026 16:21:34 +0800
Subject: [PATCH 02/10] chore(ci): gate typecheck/test/build; add dependabot

PR checks were silently passing because typecheck, test, and build steps
were marked continue-on-error, so the gates only reported status, never
blocked merges. Drop continue-on-error from those three; keep it on lint
until the rule set is cleaned up.

Add dependabot config for npm + github-actions, with grouping for
@meshsdk/*, next/@next/*, prisma/@prisma/*, @trpc/*, and @types/*.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .github/dependabot.yml          | 40 +++++++++++++++++++++++++++++++++
 .github/workflows/pr-checks.yml |  5 ++---
 2 files changed, 42 insertions(+), 3 deletions(-)
 create mode 100644 .github/dependabot.yml

diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 00000000..689504a3
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,40 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    groups:
+      mesh-sdk:
+        patterns:
+          - "@meshsdk/*"
+      next:
+        patterns:
+          - "next"
+          - "next-*"
+          - "@next/*"
+      prisma:
+        patterns:
+          - "prisma"
+          - "@prisma/*"
+      trpc:
+        patterns:
+          - "@trpc/*"
+      types:
+        patterns:
+          - "@types/*"
+        update-types:
+          - "minor"
+          - "patch"
+    labels:
+      - "dependencies"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    labels:
+      - "dependencies"
+      - "ci"
diff --git a/.github/workflows/pr-checks.yml b/.github/workflows/pr-checks.yml
index 9f260631..6f9b268f 100644
--- a/.github/workflows/pr-checks.yml
+++ b/.github/workflows/pr-checks.yml
@@ -29,20 +29,19 @@ jobs:
       - name: Generate Prisma client
         run: npx prisma generate
 
+      # Lint stays non-blocking until the rule set is cleaned up; tracked separately.
       - name: Lint
         run: npm run lint
         continue-on-error: true
 
+      # Typecheck, test, and build are gates — failures must fail the PR.
       - name: Type check
         run: npx tsc --noEmit
-        continue-on-error: true
 
       - name: Test
         run: npm run test:ci
-        continue-on-error: true
 
       - name: Build
         run: npm run build
         env:
           SKIP_ENV_VALIDATION: 'true'
-        continue-on-error: true

From ed321fe990047ee6542a5ae91618aa49ee2f453a Mon Sep 17 00:00:00 2001
From: Jingles <jinglescode@gmail.com>
Date: Sun, 10 May 2026 16:22:46 +0800
Subject: [PATCH 03/10] fix(build): lazy-init mainnet provider; remove global
 sideEffects:false

Two interacting issues caused the production build to crash on routes
that imported resolve-adahandle (notably /wallets/[wallet]/transactions/new):

1. resolve-adahandle.tsx called getProvider(1) at module top level. Under
   `next build` page-data collection, every server-rendered page imports
   that module, which constructs BlockfrostProvider(undefined) when
   NEXT_PUBLIC_BLOCKFROST_API_KEY_MAINNET isn't readable at build time
   (e.g. SKIP_ENV_VALIDATION=true). The constructor throws and the
   webpack runtime reports it as a generic "factory error".

2. next.config.js had `optimization.sideEffects: false` set globally,
   which tells webpack that *every* file is side-effect-free. That
   silently strips global CSS imports and any module-level initialization,
   masking issues like (1) until you hit a route that exercises them.

Fix:
- Lazy-init the mainnet provider with a cached singleton, so import is
  free and instantiation only happens when a caller actually resolves a
  handle (always client-side).
- Remove the global sideEffects:false override. Per-package sideEffects
  declarations in package.json are the correct mechanism; the global
  override was masking real bugs.
- Move swagger-ui-react CSS import from api-docs.tsx into _app.tsx so
  Next.js Pages Router's "global CSS only from _app" rule is satisfied.

Verified locally: `next build --webpack` completes; both
/wallets/[wallet]/transactions/new and /api-docs render.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 next.config.js                                       |  9 ++++++---
 .../common/cardano-objects/resolve-adahandle.tsx     | 12 +++++++++---
 src/pages/_app.tsx                                   |  1 +
 src/pages/api-docs.tsx                               |  3 ++-
 4 files changed, 18 insertions(+), 7 deletions(-)

diff --git a/next.config.js b/next.config.js
index 32444230..67efb015 100644
--- a/next.config.js
+++ b/next.config.js
@@ -55,13 +55,16 @@ const config = {
       layers: true,
     };
     
-    // Optimize tree-shaking by ensuring proper module resolution
+    // Optimize tree-shaking by ensuring proper module resolution.
+    // Note: do NOT set `sideEffects: false` globally — it tells webpack that
+    // every file is side-effect-free, which silently strips CSS imports,
+    // polyfills, and other modules that exist purely for their side effects.
+    // Per-package sideEffects flags in package.json are the correct surface.
     config.optimization = {
       ...config.optimization,
       usedExports: true,
-      sideEffects: false,
     };
-    
+
     // Handle CommonJS modules that don't support named exports
     config.resolve = {
       ...config.resolve,
diff --git a/src/components/common/cardano-objects/resolve-adahandle.tsx b/src/components/common/cardano-objects/resolve-adahandle.tsx
index d1ba72d8..51ee040b 100644
--- a/src/components/common/cardano-objects/resolve-adahandle.tsx
+++ b/src/components/common/cardano-objects/resolve-adahandle.tsx
@@ -1,8 +1,14 @@
 import { toast } from "@/hooks/use-toast";
 import { getProvider } from "@/utils/get-provider";
 
-//AdaHandle look up provider only supports mainnnet
-const provider = getProvider(1)
+// AdaHandle lookup is mainnet-only. Lazy-init the provider so the module
+// can be imported during SSR / page-data collection without requiring
+// NEXT_PUBLIC_BLOCKFROST_API_KEY_MAINNET to be defined at module-load time.
+let cachedProvider: ReturnType<typeof getProvider> | null = null;
+const getMainnetProvider = () => {
+  if (!cachedProvider) cachedProvider = getProvider(1);
+  return cachedProvider;
+};
 
 export const resolveAdaHandle = async (
   setAdaHandle: (value: string) => void,
@@ -18,7 +24,7 @@ export const resolveAdaHandle = async (
       return;
     }
 
-    const address = await provider.fetchHandleAddress(handleName);
+    const address = await getMainnetProvider().fetchHandleAddress(handleName);
 
     if (address) {
       const newAddresses = [...recipientAddresses];
diff --git a/src/pages/_app.tsx b/src/pages/_app.tsx
index 903d99bb..774fb03c 100644
--- a/src/pages/_app.tsx
+++ b/src/pages/_app.tsx
@@ -13,6 +13,7 @@ import { env } from "@/env";
 import { api } from "@/utils/api";
 
 import "@/styles/globals.css";
+import "swagger-ui-react/swagger-ui.css";
 import "@/styles/swagger-overrides.css";
 import { Toaster } from "@/components/ui/toaster";
 import Metatags from "@/components/ui/metatags";
diff --git a/src/pages/api-docs.tsx b/src/pages/api-docs.tsx
index 7c97eb78..495c867c 100644
--- a/src/pages/api-docs.tsx
+++ b/src/pages/api-docs.tsx
@@ -6,8 +6,9 @@ import { Key, Lightbulb, Copy, Check } from "lucide-react";
 import Globe from "./globe";
 
 // Avoid SSR for Swagger UI
+// Note: swagger-ui CSS is imported globally from src/pages/_app.tsx because
+// Next.js Pages Router only allows global CSS imports from the custom App.
 const SwaggerUI = dynamic(() => import("swagger-ui-react"), { ssr: false });
-import "swagger-ui-react/swagger-ui.css";
 
 export const getServerSideProps = () => ({ props: {} });
 

From 074ac9a2549d7dd1a555ae6ae451bed035274244 Mon Sep 17 00:00:00 2001
From: Jingles <jinglescode@gmail.com>
Date: Sun, 10 May 2026 16:29:13 +0800
Subject: [PATCH 04/10] feat(server): AuditLog table, DB indexes, security
 hardening, observability
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Comprehensive server-side hardening pass: closes auth/security gaps,
adds an append-only AuditLog for security-relevant events, indexes
frequently queried columns, centralizes ctx typing, and lands shared
auth helpers.

## Database (already deployed to prod via prisma migrate deploy)

- New `AuditLog` table for append-only security audit trail
  (auth flows, wallet/transaction mutations, privilege grants, signer
  changes). Five indexes for the common access patterns.
- Btree indexes on Wallet/NewWallet `ownerAddress`, Signable+Transaction
  `walletId`/`state`/`(walletId, state)`, Proxy `walletId`/`userId`/
  `(walletId, isActive)`/`(userId, isActive)`, Ballot `walletId`,
  BalanceSnapshot `walletId`/`(walletId, snapshotDate)`.
- GIN indexes on Wallet/NewWallet `signersAddresses` (array_ops) — the
  signer-membership query was a full table scan.
- Restored `Crowdfund` model declaration (production drift: table exists
  in prod but was never declared in main's schema; see PR description
  for full archaeology). Marked as retained-but-unused.
- WalletBotAccess: `@@unique` -> `@@id` to match prod (drift from
  PR #207 / commit 1facdc3 where schema and migration disagreed at
  landing).
- Ballot.updatedAt: restored `@default(now()) @updatedAt` to match
  prod's column default (drift accumulated across multiple commits).
- Ballot.anchorUrls / anchorHashes: added `DEFAULT ARRAY[]::TEXT[]` to
  match the schema's `@default([])` annotation.

## Observability primitives

- `src/lib/observability/audit.ts` — `audit(db, event)` emitter; never
  throws (audit miss must not break user flow); redacts secrets in
  metadata before write.
- `src/lib/observability/logger.ts` — structured logger; JSON in prod,
  human-readable in dev; never logs raw tokens/signatures/cookies.

## Security fixes (Wave 1-3)

- Closed `ownerAddress === "all"` bypass in `assertWalletAccess`. The
  string "all" was being treated as a wildcard owner — any session
  could claim ownership of any wallet whose `ownerAddress` happened to
  contain that literal.
- `lookupMultisigWallet`: validate stake-credential-hash format before
  query (prevents prefix-match abuse and full-table scans on malformed
  input).
- Centralized rate-limit and request-guard surface (`src/lib/security/
  rateLimit.ts`, `requestGuards`). Bot routes now use bot-scoped
  rate limit; user routes use IP-scoped.
- `verifyJwt`: stricter token-type narrowing; explicit `isBotJwt`
  predicate.
- `walletSession`: tighter expiry handling, no implicit refresh.

## Auth helpers (Wave 8)

- New `src/server/api/auth.ts` consolidates `requireSessionAddress`,
  `getSessionAddresses`, and wallet-access checks that were duplicated
  in nearly every router. One source of truth, one place to extend.
- All routers and v1 API handlers migrated.

## ctx typing (Wave 2)

- New `AuthCtx` and `TRPCContext` exported from `src/server/api/trpc.ts`.
- All router helpers use `AuthCtx` instead of `any`.
- `protectedProcedure` middleware: type-narrows `sessionWallets`,
  `primaryWallet`, `sessionAddress` correctly.

## Audit emitters (Wave 5)

Wired into:
- auth flow (login success/failure, JWT mint, bot auth)
- wallet mutations (create, update, archive, transfer, signer changes)
- signable + transaction mutations (sign, reject, broadcast)
- bot privilege grants

All emitters fire after the underlying action and never block it.

## SSRF defense for `/api/v1/og`

The OG metadata endpoint now:
- requires https, denies non-allowlisted hosts
- DNS-resolves and rejects private/loopback/link-local addresses
- denies upstream redirects (no auto-follow)

`OG_ALLOWED_HOSTS` env var configures the allow list; "*" allows any
public host (still SSRF-guarded).

## Test infrastructure

- jest.config.mjs — moduleNameMapper for CSS, transformIgnorePatterns
  for ESM-only deps (superjson, @trpc, @meshsdk, jose, etc.)
- setupEnv.cjs — pre-test env bootstrap (SKIP_ENV_VALIDATION=1, dummy
  DB/JWT/Blockfrost values) so `src/env.js` doesn't throw on import.
- Frozen wall clock (`Date.now`/`new Date`) for byte-identical test
  runs; real timer APIs preserved.
- `__mocks__/styleMock.cjs` — CSS imports mock for jest.

## Tests

- New: `og.test.ts` (SSRF tripwire suite — 9 cases for the og handler).
- New: `signing.test.ts` (source tripwires preventing the
  `return true ? signature : undefined` regression and similar).
- Updated existing tests to match Jest 30 strict mock typing
  (jest.fn<...>() generics) and new ctx fields.

## Verification

- Typecheck clean
- All 165 staged-suite tests pass deterministically across two runs
- Migration `20260510160404_audit_log_and_indexes` already applied to
  the multisig Supabase production DB — `prisma migrate deploy` on
  this branch is a no-op (idempotent).

Depends on: #236 (build fix; without it `next build --webpack` will
crash on `/wallets/[wallet]/transactions/new`).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 jest.config.mjs                               |   5 +
 package-lock.json                             |  40 ----
 package.json                                  |  11 +-
 .../migration.sql                             |  88 +++++++++
 prisma/schema.prisma                          | 107 ++++++++---
 src/__tests__/__mocks__/styleMock.cjs         |   1 +
 src/__tests__/apiSecurity.test.ts             |  11 +-
 src/__tests__/botBallotsUpsert.test.ts        |  47 ++---
 .../governanceActiveProposals.test.ts         |  39 ++--
 src/__tests__/multisigSDK.test.ts             |  10 +-
 src/__tests__/og.test.ts                      | 169 +++++++++++++++++
 src/__tests__/pendingTransactions.test.ts     |  59 ++++--
 src/__tests__/setup.ts                        |  33 +++-
 src/__tests__/setupEnv.cjs                    |  21 +++
 src/__tests__/signTransaction.test.ts         |  59 +++---
 src/__tests__/signing.test.ts                 | 107 +++++++++++
 src/components/ui/form.tsx                    | 176 ------------------
 src/env.js                                    |   7 +
 src/lib/auth/walletSession.ts                 |   4 +-
 src/lib/observability/audit.ts                |  54 ++++++
 src/lib/observability/logger.ts               |  80 ++++++++
 src/lib/security/rateLimit.ts                 |   2 +-
 src/lib/verifyJwt.ts                          |   4 +-
 src/pages/api/auth/discord/callback.ts        | 113 ++++++++---
 src/pages/api/auth/discord/start.ts           |  55 ++++++
 src/pages/api/v1/addTransaction.ts            |  15 +-
 src/pages/api/v1/authSigner.ts                |  33 +++-
 src/pages/api/v1/botAuth.ts                   |   4 +-
 src/pages/api/v1/getNonce.ts                  |  24 +--
 src/pages/api/v1/lookupMultisigWallet.ts      |  17 +-
 src/pages/api/v1/og.ts                        | 162 +++++++++++++++-
 src/pages/api/v1/submitDatum.ts               |   2 +-
 src/server/api/auth.ts                        | 105 +++++++++++
 src/server/api/routers/auth.ts                |   4 +-
 src/server/api/routers/ballot.ts              |   9 +-
 src/server/api/routers/bot.ts                 |  51 +++--
 src/server/api/routers/contacts.ts            |   9 +-
 src/server/api/routers/migrations.ts          |  19 +-
 src/server/api/routers/proxy.ts               |  21 ++-
 src/server/api/routers/signable.ts            |  63 ++++---
 src/server/api/routers/transactions.ts        | 121 ++++++++----
 src/server/api/routers/users.ts               |  22 ++-
 src/server/api/routers/wallets.ts             | 156 ++++++++++++----
 src/server/api/trpc.ts                        |  29 ++-
 src/utils/signing.ts                          |  36 +++-
 45 files changed, 1650 insertions(+), 554 deletions(-)
 create mode 100644 prisma/migrations/20260510160404_audit_log_and_indexes/migration.sql
 create mode 100644 src/__tests__/__mocks__/styleMock.cjs
 create mode 100644 src/__tests__/og.test.ts
 create mode 100644 src/__tests__/setupEnv.cjs
 create mode 100644 src/__tests__/signing.test.ts
 delete mode 100644 src/components/ui/form.tsx
 create mode 100644 src/lib/observability/audit.ts
 create mode 100644 src/lib/observability/logger.ts
 create mode 100644 src/pages/api/auth/discord/start.ts
 create mode 100644 src/server/api/auth.ts

diff --git a/jest.config.mjs b/jest.config.mjs
index 3cb3583f..a5409725 100644
--- a/jest.config.mjs
+++ b/jest.config.mjs
@@ -16,7 +16,11 @@ export default {
   },
   moduleNameMapper: {
     '^@/(.*)$': '<rootDir>/src/$1',
+    '\\.(css|less|scss|sass)$': '<rootDir>/src/__tests__/__mocks__/styleMock.cjs',
   },
+  transformIgnorePatterns: [
+    '/node_modules/(?!(superjson|copy-anything|is-what|@trpc|@meshsdk|@noble|@sidan-lab|nanoid|jose|uuid)/)',
+  ],
   collectCoverageFrom: [
     'src/**/*.{ts,tsx}',
     '!src/**/*.d.ts',
@@ -28,6 +32,7 @@ export default {
   coverageProvider: 'v8',
   coverageDirectory: 'coverage',
   coverageReporters: ['text', 'lcov', 'html'],
+  setupFiles: ['<rootDir>/src/__tests__/setupEnv.cjs'],
   setupFilesAfterEnv: ['<rootDir>/src/__tests__/setup.ts'],
   testTimeout: 10000,
   verbose: true,
diff --git a/package-lock.json b/package-lock.json
index a7a0c437..9ee7a9b0 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -10,7 +10,6 @@
       "hasInstallScript": true,
       "dependencies": {
         "@auth/prisma-adapter": "^2.11.1",
-        "@hookform/resolvers": "^3.9.0",
         "@jinglescode/nostr-chat-plugin": "^0.0.11",
         "@meshsdk/core": "^1.9.0-beta.87",
         "@meshsdk/core-csl": "^1.9.0-beta.87",
@@ -61,7 +60,6 @@
         "react": "^18.3.1",
         "react-dom": "^18.3.1",
         "react-dropzone": "^14.3.5",
-        "react-hook-form": "^7.53.0",
         "react-markdown": "^10.1.0",
         "remark-gfm": "^4.0.1",
         "superjson": "^2.2.1",
@@ -72,7 +70,6 @@
         "three": "^0.168.0",
         "three-globe": "^2.31.1",
         "uuid": "^11.1.0",
-        "yaml": "^2.8.2",
         "zod": "^3.23.8",
         "zustand": "^4.5.5"
       },
@@ -1399,14 +1396,6 @@
         "@harmoniclabs/plutus-data": "^1.2.4"
       }
     },
-    "node_modules/@hookform/resolvers": {
-      "version": "3.10.0",
-      "resolved": "https://registry.npmjs.org/@hookform/resolvers/-/resolvers-3.10.0.tgz",
-      "integrity": "sha512-79Dv+3mDF7i+2ajj7SkypSKHhl1cbln1OGavqrsF7p6mbUv11xpqpacPsGDCTRvCSjEEIez2ef1NveSVL3b0Ag==",
-      "peerDependencies": {
-        "react-hook-form": "^7.0.0"
-      }
-    },
     "node_modules/@humanfs/core": {
       "version": "0.19.1",
       "resolved": "https://registry.npmjs.org/@humanfs/core/-/core-0.19.1.tgz",
@@ -20800,21 +20789,6 @@
         "react": ">= 16.8 || 18.0.0"
       }
     },
-    "node_modules/react-hook-form": {
-      "version": "7.72.0",
-      "resolved": "https://registry.npmjs.org/react-hook-form/-/react-hook-form-7.72.0.tgz",
-      "integrity": "sha512-V4v6jubaf6JAurEaVnT9aUPKFbNtDgohj5CIgVGyPHvT9wRx5OZHVjz31GsxnPNI278XMu+ruFz+wGOscHaLKw==",
-      "engines": {
-        "node": ">=18.0.0"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/react-hook-form"
-      },
-      "peerDependencies": {
-        "react": "^16.8.0 || ^17 || ^18 || ^19"
-      }
-    },
     "node_modules/react-immutable-proptypes": {
       "version": "2.2.0",
       "resolved": "https://registry.npmjs.org/react-immutable-proptypes/-/react-immutable-proptypes-2.2.0.tgz",
@@ -24556,20 +24530,6 @@
       "resolved": "https://registry.npmjs.org/yallist/-/yallist-3.1.1.tgz",
       "integrity": "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g=="
     },
-    "node_modules/yaml": {
-      "version": "2.8.3",
-      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.3.tgz",
-      "integrity": "sha512-AvbaCLOO2Otw/lW5bmh9d/WEdcDFdQp2Z2ZUH3pX9U2ihyUY0nvLv7J6TrWowklRGPYbB/IuIMfYgxaCPg5Bpg==",
-      "bin": {
-        "yaml": "bin.mjs"
-      },
-      "engines": {
-        "node": ">= 14.6"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/eemeli"
-      }
-    },
     "node_modules/yargs": {
       "version": "17.7.2",
       "resolved": "https://registry.npmjs.org/yargs/-/yargs-17.7.2.tgz",
diff --git a/package.json b/package.json
index bc6e55f3..f72acf6f 100644
--- a/package.json
+++ b/package.json
@@ -19,16 +19,15 @@
     "format:check": "prettier --check .",
     "prestart": "prisma migrate deploy",
     "start": "next start",
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "test:coverage": "jest --coverage",
-    "test:ci": "jest --ci --coverage --watchAll=false",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch",
+    "test:coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
+    "test:ci": "node --experimental-vm-modules node_modules/jest/bin/jest.js --ci --coverage --watchAll=false",
     "analyze": "ANALYZE=true npm run build",
     "apply-project": "node scripts/apply-project-to-github.mjs"
   },
   "dependencies": {
     "@auth/prisma-adapter": "^2.11.1",
-    "@hookform/resolvers": "^3.9.0",
     "@jinglescode/nostr-chat-plugin": "^0.0.11",
     "@meshsdk/core": "^1.9.0-beta.87",
     "@meshsdk/core-csl": "^1.9.0-beta.87",
@@ -79,7 +78,6 @@
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "react-dropzone": "^14.3.5",
-    "react-hook-form": "^7.53.0",
     "react-markdown": "^10.1.0",
     "remark-gfm": "^4.0.1",
     "superjson": "^2.2.1",
@@ -90,7 +88,6 @@
     "three": "^0.168.0",
     "three-globe": "^2.31.1",
     "uuid": "^11.1.0",
-    "yaml": "^2.8.2",
     "zod": "^3.23.8",
     "zustand": "^4.5.5"
   },
diff --git a/prisma/migrations/20260510160404_audit_log_and_indexes/migration.sql b/prisma/migrations/20260510160404_audit_log_and_indexes/migration.sql
new file mode 100644
index 00000000..058fae30
--- /dev/null
+++ b/prisma/migrations/20260510160404_audit_log_and_indexes/migration.sql
@@ -0,0 +1,88 @@
+-- AlterTable
+ALTER TABLE "Ballot" ALTER COLUMN "anchorUrls" SET DEFAULT ARRAY[]::TEXT[],
+ALTER COLUMN "anchorHashes" SET DEFAULT ARRAY[]::TEXT[];
+
+-- CreateTable
+CREATE TABLE "AuditLog" (
+    "id" TEXT NOT NULL,
+    "actorAddress" TEXT,
+    "actorType" TEXT NOT NULL,
+    "action" TEXT NOT NULL,
+    "resourceType" TEXT,
+    "resourceId" TEXT,
+    "ip" TEXT,
+    "userAgent" TEXT,
+    "outcome" TEXT NOT NULL,
+    "reason" TEXT,
+    "metadata" JSONB,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "AuditLog_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "AuditLog_actorAddress_idx" ON "AuditLog"("actorAddress");
+
+-- CreateIndex
+CREATE INDEX "AuditLog_action_idx" ON "AuditLog"("action");
+
+-- CreateIndex
+CREATE INDEX "AuditLog_resourceType_resourceId_idx" ON "AuditLog"("resourceType", "resourceId");
+
+-- CreateIndex
+CREATE INDEX "AuditLog_createdAt_idx" ON "AuditLog"("createdAt");
+
+-- CreateIndex
+CREATE INDEX "AuditLog_actorAddress_createdAt_idx" ON "AuditLog"("actorAddress", "createdAt");
+
+-- CreateIndex
+CREATE INDEX "BalanceSnapshot_walletId_idx" ON "BalanceSnapshot"("walletId");
+
+-- CreateIndex
+CREATE INDEX "BalanceSnapshot_walletId_snapshotDate_idx" ON "BalanceSnapshot"("walletId", "snapshotDate");
+
+-- CreateIndex
+CREATE INDEX "Ballot_walletId_idx" ON "Ballot"("walletId");
+
+-- CreateIndex
+CREATE INDEX "NewWallet_ownerAddress_idx" ON "NewWallet"("ownerAddress");
+
+-- CreateIndex
+CREATE INDEX "NewWallet_signersAddresses_idx" ON "NewWallet" USING GIN ("signersAddresses" array_ops);
+
+-- CreateIndex
+CREATE INDEX "Proxy_walletId_idx" ON "Proxy"("walletId");
+
+-- CreateIndex
+CREATE INDEX "Proxy_userId_idx" ON "Proxy"("userId");
+
+-- CreateIndex
+CREATE INDEX "Proxy_walletId_isActive_idx" ON "Proxy"("walletId", "isActive");
+
+-- CreateIndex
+CREATE INDEX "Proxy_userId_isActive_idx" ON "Proxy"("userId", "isActive");
+
+-- CreateIndex
+CREATE INDEX "Signable_walletId_idx" ON "Signable"("walletId");
+
+-- CreateIndex
+CREATE INDEX "Signable_state_idx" ON "Signable"("state");
+
+-- CreateIndex
+CREATE INDEX "Signable_walletId_state_idx" ON "Signable"("walletId", "state");
+
+-- CreateIndex
+CREATE INDEX "Transaction_walletId_idx" ON "Transaction"("walletId");
+
+-- CreateIndex
+CREATE INDEX "Transaction_state_idx" ON "Transaction"("state");
+
+-- CreateIndex
+CREATE INDEX "Transaction_walletId_state_idx" ON "Transaction"("walletId", "state");
+
+-- CreateIndex
+CREATE INDEX "Wallet_ownerAddress_idx" ON "Wallet"("ownerAddress");
+
+-- CreateIndex
+CREATE INDEX "Wallet_signersAddresses_idx" ON "Wallet" USING GIN ("signersAddresses" array_ops);
+
diff --git a/prisma/schema.prisma b/prisma/schema.prisma
index 23d45677..92387e35 100644
--- a/prisma/schema.prisma
+++ b/prisma/schema.prisma
@@ -43,6 +43,9 @@ model Wallet {
   migrationTargetWalletId String?
   profileImageIpfsUrl     String?
   ownerAddress            String?
+
+  @@index([ownerAddress])
+  @@index([signersAddresses(ops: ArrayOps)], type: Gin)
 }
 
 model Transaction {
@@ -77,6 +80,10 @@ model Signable {
   updatedAt         DateTime @updatedAt
   callbackUrl       String?
   remoteOrigin      String?
+
+  @@index([walletId])
+  @@index([state])
+  @@index([walletId, state])
 }
 
 model NewWallet {
@@ -95,6 +102,9 @@ model NewWallet {
   paymentCbor         String?
   stakeCbor           String?
   rawImportBodies     Json?
+
+  @@index([ownerAddress])
+  @@index([signersAddresses(ops: ArrayOps)], type: Gin)
 }
 
 model Nonce {
@@ -105,18 +115,36 @@ model Nonce {
 }
 
 model Ballot {
-  id               String   @id @default(cuid())
-  walletId         String
-  description      String?
-  items            String[]
-  itemDescriptions String[]
-  choices          String[]
-  anchorUrls       String[] @default([])
-  anchorHashes     String[] @default([])
+  id                String   @id @default(cuid())
+  walletId          String
+  description       String?
+  items             String[]
+  itemDescriptions  String[]
+  choices           String[]
+  anchorUrls        String[] @default([])
+  anchorHashes      String[] @default([])
   rationaleComments String[] @default([])
-  type             Int
-  createdAt        DateTime @default(now())
-  updatedAt        DateTime @updatedAt
+  type              Int
+  createdAt         DateTime @default(now())
+  updatedAt         DateTime @default(now()) @updatedAt
+
+  @@index([walletId])
+}
+
+// Retained to preserve the existing production table; feature is currently unused
+// in app code. Do not drop without an explicit data-migration plan.
+model Crowdfund {
+  id                String   @id @default(cuid())
+  name              String
+  description       String?
+  proposerKeyHashR0 String
+  authTokenId       String?
+  datum             String?
+  address           String?
+  paramUtxo         String?
+  govDatum          String?
+  govAddress        String?
+  createdAt         DateTime @default(now())
 }
 
 model Proxy {
@@ -146,6 +174,9 @@ model BalanceSnapshot {
   assetBalances Json
   isArchived    Boolean
   snapshotDate  DateTime @default(now())
+
+  @@index([walletId])
+  @@index([walletId, snapshotDate])
 }
 
 model Migration {
@@ -195,13 +226,13 @@ model BotKey {
 }
 
 model BotUser {
-  id              String   @id @default(cuid())
-  botKeyId        String   @unique
-  paymentAddress  String   @unique // One bot, one address
-  stakeAddress    String?
-  displayName     String?
-  createdAt       DateTime @default(now())
-  botKey          BotKey   @relation(fields: [botKeyId], references: [id], onDelete: Cascade)
+  id             String   @id @default(cuid())
+  botKeyId       String   @unique
+  paymentAddress String   @unique // One bot, one address
+  stakeAddress   String?
+  displayName    String?
+  createdAt      DateTime @default(now())
+  botKey         BotKey   @relation(fields: [botKeyId], references: [id], onDelete: Cascade)
 
   @@index([paymentAddress])
 }
@@ -213,11 +244,11 @@ enum BotWalletRole {
 
 model WalletBotAccess {
   walletId  String
-  botId      String
-  role       BotWalletRole
-  createdAt  DateTime @default(now())
+  botId     String
+  role      BotWalletRole
+  createdAt DateTime      @default(now())
 
-  @@unique([walletId, botId])
+  @@id([walletId, botId])
   @@index([walletId])
   @@index([botId])
 }
@@ -232,10 +263,10 @@ model PendingBot {
   name            String
   paymentAddress  String
   stakeAddress    String?
-  requestedScopes String           // JSON array of requested scopes
+  requestedScopes String // JSON array of requested scopes
   status          PendingBotStatus @default(UNCLAIMED)
-  claimedBy       String?          // ownerAddress of the claiming human
-  secretCipher    String?          // Encrypted secret (set on claim, cleared on pickup)
+  claimedBy       String? // ownerAddress of the claiming human
+  secretCipher    String? // Encrypted secret (set on claim, cleared on pickup)
   pickedUp        Boolean          @default(false)
   expiresAt       DateTime
   createdAt       DateTime         @default(now())
@@ -249,7 +280,7 @@ model BotClaimToken {
   id           String     @id @default(cuid())
   pendingBotId String     @unique
   pendingBot   PendingBot @relation(fields: [pendingBotId], references: [id], onDelete: Cascade)
-  tokenHash    String     // SHA-256 hash of the claim code
+  tokenHash    String // SHA-256 hash of the claim code
   attempts     Int        @default(0)
   expiresAt    DateTime
   consumedAt   DateTime?
@@ -257,3 +288,27 @@ model BotClaimToken {
 
   @@index([tokenHash])
 }
+
+// Append-only security audit trail. Writers should never UPDATE existing rows.
+// Events are emitted from auth flows, wallet/transaction mutations, and
+// privilege-changing actions (bot grants, signer changes, ownership transfers).
+model AuditLog {
+  id           String   @id @default(cuid())
+  actorAddress String? // Wallet address that performed the action (null for system/anonymous)
+  actorType    String // "user" | "bot" | "system"
+  action       String // e.g. "wallet.create", "tx.sign", "bot.grant", "auth.login"
+  resourceType String? // "wallet" | "transaction" | "bot" | "ballot" | etc.
+  resourceId   String?
+  ip           String?
+  userAgent    String?
+  outcome      String // "success" | "denied" | "error"
+  reason       String? // Short reason on denied/error
+  metadata     Json? // Additional context (no secrets, redacted)
+  createdAt    DateTime @default(now())
+
+  @@index([actorAddress])
+  @@index([action])
+  @@index([resourceType, resourceId])
+  @@index([createdAt])
+  @@index([actorAddress, createdAt])
+}
diff --git a/src/__tests__/__mocks__/styleMock.cjs b/src/__tests__/__mocks__/styleMock.cjs
new file mode 100644
index 00000000..f053ebf7
--- /dev/null
+++ b/src/__tests__/__mocks__/styleMock.cjs
@@ -0,0 +1 @@
+module.exports = {};
diff --git a/src/__tests__/apiSecurity.test.ts b/src/__tests__/apiSecurity.test.ts
index 667c6959..891567a8 100644
--- a/src/__tests__/apiSecurity.test.ts
+++ b/src/__tests__/apiSecurity.test.ts
@@ -1,3 +1,4 @@
+import { beforeEach, describe, expect, it, jest } from "@jest/globals";
 import { TRPCError } from "@trpc/server";
 
 import { applyRateLimit, enforceBodySize } from "@/lib/security/requestGuards";
@@ -67,6 +68,8 @@ describe("wallet router authorization", () => {
       db: baseDb as any,
       session: null,
       sessionAddress: null,
+      sessionWallets: [],
+      primaryWallet: null,
       ip: "3.3.3.3",
     });
 
@@ -93,12 +96,14 @@ describe("wallet router authorization", () => {
       isArchived: false,
       verified: [],
       migrationTargetWalletId: null,
-    });
+    } as never);
 
     const caller = createCaller({
       db: baseDb as any,
       session: { user: { id: "addr1" }, expires: new Date().toISOString() } as any,
       sessionAddress: "addr1",
+      sessionWallets: ["addr1"],
+      primaryWallet: "addr1",
       ip: "4.4.4.4",
     });
 
@@ -126,12 +131,14 @@ describe("wallet router authorization", () => {
       verified: [],
       migrationTargetWalletId: null,
     };
-    baseDb.wallet.findUnique.mockResolvedValueOnce(wallet);
+    baseDb.wallet.findUnique.mockResolvedValueOnce(wallet as never);
 
     const caller = createCaller({
       db: baseDb as any,
       session: { user: { id: "addr1" }, expires: new Date().toISOString() } as any,
       sessionAddress: "addr1",
+      sessionWallets: ["addr1"],
+      primaryWallet: "addr1",
       ip: "5.5.5.5",
     });
 
diff --git a/src/__tests__/botBallotsUpsert.test.ts b/src/__tests__/botBallotsUpsert.test.ts
index 1d487b77..b2423af9 100644
--- a/src/__tests__/botBallotsUpsert.test.ts
+++ b/src/__tests__/botBallotsUpsert.test.ts
@@ -6,36 +6,35 @@ const corsMock = jest.fn<(req: NextApiRequest, res: NextApiResponse) => Promise<
 const applyRateLimitMock = jest.fn<(req: NextApiRequest, res: NextApiResponse) => boolean>();
 const applyBotRateLimitMock = jest.fn<(req: NextApiRequest, res: NextApiResponse, botId: string) => boolean>();
 const enforceBodySizeMock = jest.fn<(req: NextApiRequest, res: NextApiResponse, maxBytes: number) => boolean>();
-const verifyJwtMock = jest.fn();
-const isBotJwtMock = jest.fn();
-const assertBotWalletAccessMock = jest.fn();
-const findBotUserMock = jest.fn();
-const transactionMock = jest.fn();
-const parseScopeMock = jest.fn();
-const scopeIncludesMock = jest.fn();
-const isValidChoiceMock = jest.fn();
-const parseProposalIdMock = jest.fn();
+const verifyJwtMock = jest.fn<(...args: any[]) => any>();
+const isBotJwtMock = jest.fn<(...args: any[]) => any>();
+const assertBotWalletAccessMock = jest.fn<(...args: any[]) => any>();
+const findBotUserMock = jest.fn<(...args: any[]) => any>();
+const transactionMock = jest.fn<(...args: any[]) => any>();
+const parseScopeMock = jest.fn<(...args: any[]) => any>();
+const scopeIncludesMock = jest.fn<(...args: any[]) => any>();
+const isValidChoiceMock = jest.fn<(...args: any[]) => any>();
+const parseProposalIdMock = jest.fn<(...args: any[]) => any>();
 
 const txMock = {
   ballot: {
-    findUnique: jest.fn(),
-    findMany: jest.fn(),
-    create: jest.fn(),
-    updateMany: jest.fn(),
+    findUnique: jest.fn<(...args: any[]) => any>(),
+    findMany: jest.fn<(...args: any[]) => any>(),
+    create: jest.fn<(...args: any[]) => any>(),
+    updateMany: jest.fn<(...args: any[]) => any>(),
   },
 };
 
-jest.mock(
+jest.unstable_mockModule(
   "@/lib/cors",
   () => ({
     __esModule: true,
     addCorsCacheBustingHeaders: addCorsCacheBustingHeadersMock,
     cors: corsMock,
   }),
-  { virtual: true },
 );
 
-jest.mock(
+jest.unstable_mockModule(
   "@/lib/security/requestGuards",
   () => ({
     __esModule: true,
@@ -43,49 +42,44 @@ jest.mock(
     applyBotRateLimit: applyBotRateLimitMock,
     enforceBodySize: enforceBodySizeMock,
   }),
-  { virtual: true },
 );
 
-jest.mock(
+jest.unstable_mockModule(
   "@/lib/verifyJwt",
   () => ({
     __esModule: true,
     verifyJwt: verifyJwtMock,
     isBotJwt: isBotJwtMock,
   }),
-  { virtual: true },
 );
 
-jest.mock(
+jest.unstable_mockModule(
   "@/lib/governance",
   () => ({
     __esModule: true,
     isValidChoice: isValidChoiceMock,
     parseProposalId: parseProposalIdMock,
   }),
-  { virtual: true },
 );
 
-jest.mock(
+jest.unstable_mockModule(
   "@/lib/auth/botKey",
   () => ({
     __esModule: true,
     parseScope: parseScopeMock,
     scopeIncludes: scopeIncludesMock,
   }),
-  { virtual: true },
 );
 
-jest.mock(
+jest.unstable_mockModule(
   "@/lib/auth/botAccess",
   () => ({
     __esModule: true,
     assertBotWalletAccess: assertBotWalletAccessMock,
   }),
-  { virtual: true },
 );
 
-jest.mock(
+jest.unstable_mockModule(
   "@/server/db",
   () => ({
     __esModule: true,
@@ -96,7 +90,6 @@ jest.mock(
       $transaction: transactionMock,
     },
   }),
-  { virtual: true },
 );
 
 type ResponseMock = NextApiResponse & { statusCode?: number };
diff --git a/src/__tests__/governanceActiveProposals.test.ts b/src/__tests__/governanceActiveProposals.test.ts
index 3fdfb895..7b1558f3 100644
--- a/src/__tests__/governanceActiveProposals.test.ts
+++ b/src/__tests__/governanceActiveProposals.test.ts
@@ -5,64 +5,59 @@ const addCorsCacheBustingHeadersMock = jest.fn<(res: NextApiResponse) => void>()
 const corsMock = jest.fn<(req: NextApiRequest, res: NextApiResponse) => Promise<void>>();
 const applyRateLimitMock = jest.fn<(req: NextApiRequest, res: NextApiResponse) => boolean>();
 const applyBotRateLimitMock = jest.fn<(req: NextApiRequest, res: NextApiResponse, botId: string) => boolean>();
-const verifyJwtMock = jest.fn();
-const isBotJwtMock = jest.fn();
-const findBotUserMock = jest.fn();
-const providerGetMock = jest.fn();
-const parseScopeMock = jest.fn();
-const scopeIncludesMock = jest.fn();
-const getProposalStatusMock = jest.fn();
-
-jest.mock(
+const verifyJwtMock = jest.fn<(...args: any[]) => any>();
+const isBotJwtMock = jest.fn<(...args: any[]) => any>();
+const findBotUserMock = jest.fn<(...args: any[]) => any>();
+const providerGetMock = jest.fn<(...args: any[]) => any>();
+const parseScopeMock = jest.fn<(...args: any[]) => any>();
+const scopeIncludesMock = jest.fn<(...args: any[]) => any>();
+const getProposalStatusMock = jest.fn<(...args: any[]) => any>();
+
+jest.unstable_mockModule(
   "@/lib/cors",
   () => ({
     __esModule: true,
     addCorsCacheBustingHeaders: addCorsCacheBustingHeadersMock,
     cors: corsMock,
   }),
-  { virtual: true },
 );
 
-jest.mock(
+jest.unstable_mockModule(
   "@/lib/security/requestGuards",
   () => ({
     __esModule: true,
     applyRateLimit: applyRateLimitMock,
     applyBotRateLimit: applyBotRateLimitMock,
   }),
-  { virtual: true },
 );
 
-jest.mock(
+jest.unstable_mockModule(
   "@/lib/verifyJwt",
   () => ({
     __esModule: true,
     verifyJwt: verifyJwtMock,
     isBotJwt: isBotJwtMock,
   }),
-  { virtual: true },
 );
 
-jest.mock(
+jest.unstable_mockModule(
   "@/lib/governance",
   () => ({
     __esModule: true,
     getProposalStatus: getProposalStatusMock,
   }),
-  { virtual: true },
 );
 
-jest.mock(
+jest.unstable_mockModule(
   "@/lib/auth/botKey",
   () => ({
     __esModule: true,
     parseScope: parseScopeMock,
     scopeIncludes: scopeIncludesMock,
   }),
-  { virtual: true },
 );
 
-jest.mock(
+jest.unstable_mockModule(
   "@/server/db",
   () => ({
     __esModule: true,
@@ -72,10 +67,9 @@ jest.mock(
       },
     },
   }),
-  { virtual: true },
 );
 
-jest.mock(
+jest.unstable_mockModule(
   "@/utils/get-provider",
   () => ({
     __esModule: true,
@@ -83,7 +77,6 @@ jest.mock(
       get: providerGetMock,
     }),
   }),
-  { virtual: true },
 );
 
 type ResponseMock = NextApiResponse & { statusCode?: number };
@@ -214,7 +207,7 @@ describe("governanceActiveProposals API", () => {
     await handler(req, res);
 
     expect(res.status).toHaveBeenCalledWith(200);
-    const payload = res.json.mock.calls[0]?.[0] as any;
+    const payload = (res.json as unknown as jest.Mock).mock.calls[0]?.[0] as any;
     expect(Array.isArray(payload.proposals)).toBe(true);
     expect(payload.proposals).toHaveLength(1);
     expect(payload.proposals[0]).toMatchObject({
diff --git a/src/__tests__/multisigSDK.test.ts b/src/__tests__/multisigSDK.test.ts
index dbef91da..487e8cc9 100644
--- a/src/__tests__/multisigSDK.test.ts
+++ b/src/__tests__/multisigSDK.test.ts
@@ -39,9 +39,9 @@ describe('MultisigWallet', () => {
       ];
       
       const testWallet = new MultisigWallet('Test', unsortedKeys);
-      expect(testWallet.keys[0].keyHash).toBe('aaaa');
-      expect(testWallet.keys[1].keyHash).toBe('mmmm');
-      expect(testWallet.keys[2].keyHash).toBe('zzzz');
+      expect(testWallet.keys[0]!.keyHash).toBe('aaaa');
+      expect(testWallet.keys[1]!.keyHash).toBe('mmmm');
+      expect(testWallet.keys[2]!.keyHash).toBe('zzzz');
     });
 
     it('should filter out invalid keys', () => {
@@ -54,7 +54,7 @@ describe('MultisigWallet', () => {
 
       const testWallet = new MultisigWallet('Test', keysWithInvalid);
       expect(testWallet.keys).toHaveLength(1);
-      expect(testWallet.keys[0].keyHash).toBe(mockKeyHashes.payment1);
+      expect(testWallet.keys[0]!.keyHash).toBe(mockKeyHashes.payment1);
     });
 
     it('should use default values when optional parameters are not provided', () => {
@@ -86,7 +86,7 @@ describe('MultisigWallet', () => {
     it('should return drep keys (role 3)', () => {
       const drepKeys = wallet.getKeysByRole(3);
       expect(drepKeys).toHaveLength(1);
-      expect(drepKeys?.[0].role).toBe(3);
+      expect(drepKeys?.[0]!.role).toBe(3);
     });
 
     it('should return undefined for non-existent role', () => {
diff --git a/src/__tests__/og.test.ts b/src/__tests__/og.test.ts
new file mode 100644
index 00000000..afa0a471
--- /dev/null
+++ b/src/__tests__/og.test.ts
@@ -0,0 +1,169 @@
+import { describe, expect, it, jest, beforeEach, afterEach } from "@jest/globals";
+import type { NextApiRequest, NextApiResponse } from "next";
+
+// SSRF tripwire suite for /api/v1/og
+//
+// The handler must reject:
+//   - non-https URLs
+//   - hosts not on the allowlist
+//   - hosts that resolve to private / loopback / link-local addresses
+//   - upstream redirects (no auto-follow)
+//
+// The most important regression is the IMDS URL case:
+//   http://169.254.169.254/latest/meta-data/  (AWS instance metadata)
+// — historically the canonical SSRF target. If this ever returns 200, an
+// attacker who can hit our public OG endpoint can pivot into cloud metadata.
+
+const dnsLookupMock = jest.fn() as jest.MockedFunction<
+  (host: string, opts?: unknown) => Promise<Array<{ address: string; family: number }>>
+>;
+
+jest.unstable_mockModule("dns", () => ({
+  __esModule: true,
+  default: { promises: { lookup: dnsLookupMock } },
+  promises: { lookup: dnsLookupMock },
+}));
+
+const envState: { OG_ALLOWED_HOSTS?: string } = {};
+jest.unstable_mockModule("@/env", () => ({
+  __esModule: true,
+  env: new Proxy({}, {
+    get(_t, key: string) {
+      if (key === "OG_ALLOWED_HOSTS") return envState.OG_ALLOWED_HOSTS;
+      return undefined;
+    },
+  }),
+}));
+
+const fetchMock = jest.fn() as jest.MockedFunction<typeof fetch>;
+const realFetch = global.fetch;
+
+function makeRes() {
+  const status = jest.fn();
+  const json = jest.fn();
+  const setHeader = jest.fn();
+  const res = {
+    status: status.mockImplementation(() => res),
+    json: json.mockImplementation(() => res),
+    setHeader,
+  } as unknown as NextApiResponse;
+  return { res, status, json };
+}
+
+function makeReq(url: string | undefined): NextApiRequest {
+  return {
+    query: url === undefined ? {} : { url },
+    method: "GET",
+    headers: {},
+  } as unknown as NextApiRequest;
+}
+
+const handlerPromise = import("../pages/api/v1/og");
+
+beforeEach(() => {
+  dnsLookupMock.mockReset();
+  fetchMock.mockReset();
+  global.fetch = fetchMock as unknown as typeof fetch;
+  envState.OG_ALLOWED_HOSTS = undefined;
+});
+
+afterEach(() => {
+  global.fetch = realFetch;
+});
+
+describe("og handler — SSRF defense", () => {
+  it("rejects missing url with 400", async () => {
+    const { default: handler } = await handlerPromise;
+    const { res, status, json } = makeRes();
+    await handler(makeReq(undefined), res);
+    expect(status).toHaveBeenCalledWith(400);
+    expect(json).toHaveBeenCalledWith(expect.objectContaining({ error: expect.stringMatching(/missing/i) }));
+  });
+
+  it("rejects http:// URLs with 400", async () => {
+    const { default: handler } = await handlerPromise;
+    const { res, status } = makeRes();
+    await handler(makeReq("http://github.com/example"), res);
+    expect(status).toHaveBeenCalledWith(400);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("rejects IMDS URL (http://169.254.169.254/...) — TRIPWIRE", async () => {
+    // This test is the one we never let regress. AWS instance metadata URL.
+    // Even if someone allowlists `*` for OG_ALLOWED_HOSTS, the http:// scheme
+    // check rejects this immediately. No DNS lookup, no fetch.
+    const { default: handler } = await handlerPromise;
+    const { res, status } = makeRes();
+    await handler(makeReq("http://169.254.169.254/latest/meta-data/"), res);
+    expect(status).toHaveBeenCalledWith(400);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("rejects https IMDS-style URL when wildcard hosts but private IP", async () => {
+    // Even with OG_ALLOWED_HOSTS=*, the DNS / address-class check must reject
+    // direct private-IP literals, including the link-local 169.254.0.0/16.
+    envState.OG_ALLOWED_HOSTS = "*";
+    const { default: handler } = await handlerPromise;
+    const { res, status, json } = makeRes();
+    await handler(makeReq("https://169.254.169.254/"), res);
+    expect(status).toHaveBeenCalledWith(400);
+    expect(json).toHaveBeenCalledWith(expect.objectContaining({ error: expect.stringMatching(/private|loopback/i) }));
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("rejects host not on the allowlist with 400", async () => {
+    envState.OG_ALLOWED_HOSTS = "github.com,x.com";
+    const { default: handler } = await handlerPromise;
+    const { res, status } = makeRes();
+    await handler(makeReq("https://evil.example.com/"), res);
+    expect(status).toHaveBeenCalledWith(400);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("rejects when DNS resolves to an RFC1918 address", async () => {
+    envState.OG_ALLOWED_HOSTS = "internal.example.com";
+    dnsLookupMock.mockResolvedValueOnce([{ address: "10.0.0.5", family: 4 }]);
+    const { default: handler } = await handlerPromise;
+    const { res, status, json } = makeRes();
+    await handler(makeReq("https://internal.example.com/"), res);
+    expect(status).toHaveBeenCalledWith(400);
+    expect(json).toHaveBeenCalledWith(expect.objectContaining({ error: expect.stringMatching(/private|loopback/i) }));
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("rejects when upstream returns a redirect (no auto-follow)", async () => {
+    envState.OG_ALLOWED_HOSTS = "github.com";
+    dnsLookupMock.mockResolvedValueOnce([{ address: "140.82.114.4", family: 4 }]);
+    fetchMock.mockResolvedValueOnce(
+      new Response(null, { status: 302, headers: { location: "http://169.254.169.254/" } }),
+    );
+    const { default: handler } = await handlerPromise;
+    const { res, status } = makeRes();
+    await handler(makeReq("https://github.com/example"), res);
+    expect(status).toHaveBeenCalledWith(500);
+  });
+
+  it("returns 200 with extracted OG metadata for an allowlisted public host", async () => {
+    envState.OG_ALLOWED_HOSTS = "example.com";
+    dnsLookupMock.mockResolvedValueOnce([{ address: "93.184.216.34", family: 4 }]);
+    const html = `<html><head>
+      <meta property="og:title" content="Hello"/>
+      <meta property="og:description" content="World"/>
+      <meta property="og:image" content="https://example.com/img.png"/>
+      <meta property="og:site_name" content="Example"/>
+    </head></html>`;
+    fetchMock.mockResolvedValueOnce(new Response(html, { status: 200 }));
+    const { default: handler } = await handlerPromise;
+    const { res, status, json } = makeRes();
+    await handler(makeReq("https://example.com/page"), res);
+    expect(status).toHaveBeenCalledWith(200);
+    expect(json).toHaveBeenCalledWith(
+      expect.objectContaining({
+        title: "Hello",
+        description: "World",
+        image: "https://example.com/img.png",
+        siteName: "Example",
+      }),
+    );
+  });
+});
diff --git a/src/__tests__/pendingTransactions.test.ts b/src/__tests__/pendingTransactions.test.ts
index bfa54ab8..bef748cc 100644
--- a/src/__tests__/pendingTransactions.test.ts
+++ b/src/__tests__/pendingTransactions.test.ts
@@ -4,47 +4,73 @@ import type { NextApiRequest, NextApiResponse } from 'next';
 const addCorsCacheBustingHeadersMock = jest.fn<(res: NextApiResponse) => void>();
 const corsMock = jest.fn<(req: NextApiRequest, res: NextApiResponse) => Promise<void>>();
 
-jest.mock(
+jest.unstable_mockModule(
   '@/lib/cors',
   () => ({
     __esModule: true,
     addCorsCacheBustingHeaders: addCorsCacheBustingHeadersMock,
     cors: corsMock,
   }),
-  { virtual: true },
 );
 
-const verifyJwtMock = jest.fn<(token: string | undefined) => { address: string } | null>();
+type JwtPayloadLike = { address: string; botId?: string; type?: string };
+const verifyJwtMock = jest.fn<(token: string | undefined) => JwtPayloadLike | null>();
+const isBotJwtMock = jest.fn<(payload: JwtPayloadLike) => boolean>(
+  (payload) => Boolean(payload && (payload as JwtPayloadLike).type === "bot"),
+);
 
-jest.mock(
+jest.unstable_mockModule(
   '@/lib/verifyJwt',
   () => ({
     __esModule: true,
     verifyJwt: verifyJwtMock,
+    isBotJwt: isBotJwtMock,
+  }),
+);
+
+const applyRateLimitMock = jest.fn<
+  (req: NextApiRequest, res: NextApiResponse, options?: unknown) => boolean
+>(() => true);
+const applyBotRateLimitMock = jest.fn<
+  (req: NextApiRequest, res: NextApiResponse, botId: string, maxRequests?: number) => boolean
+>(() => true);
+const applyStrictRateLimitMock = jest.fn<
+  (req: NextApiRequest, res: NextApiResponse, options?: unknown) => boolean
+>(() => true);
+const enforceBodySizeMock = jest.fn<
+  (req: NextApiRequest, res: NextApiResponse, maxBytes: number) => boolean
+>(() => true);
+
+jest.unstable_mockModule(
+  '@/lib/security/requestGuards',
+  () => ({
+    __esModule: true,
+    applyRateLimit: applyRateLimitMock,
+    applyBotRateLimit: applyBotRateLimitMock,
+    applyStrictRateLimit: applyStrictRateLimitMock,
+    enforceBodySize: enforceBodySizeMock,
+    isBodyTooLarge: jest.fn(() => false),
   }),
-  { virtual: true },
 );
 
 const createCallerMock = jest.fn();
 
-jest.mock(
+jest.unstable_mockModule(
   '@/server/api/root',
   () => ({
     __esModule: true,
     createCaller: createCallerMock,
   }),
-  { virtual: true },
 );
 
 const dbMock = { __type: 'dbMock' };
 
-jest.mock(
+jest.unstable_mockModule(
   '@/server/db',
   () => ({
     __esModule: true,
     db: dbMock,
   }),
-  { virtual: true },
 );
 
 type ResponseMock = NextApiResponse & { statusCode?: number };
@@ -164,13 +190,16 @@ describe('pendingTransactions API route', () => {
     expect(addCorsCacheBustingHeadersMock).toHaveBeenCalledWith(res);
     expect(corsMock).toHaveBeenCalledWith(req, res);
     expect(verifyJwtMock).toHaveBeenCalledWith(token);
-    expect(createCallerMock).toHaveBeenCalledWith({
-      db: dbMock,
-      session: expect.objectContaining({
-        user: { id: address },
-        expires: expect.any(String),
+    expect(createCallerMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        db: dbMock,
+        session: expect.objectContaining({
+          user: { id: address },
+          expires: expect.any(String),
+        }),
+        sessionAddress: address,
       }),
-    });
+    );
     expect(walletGetWalletMock).toHaveBeenCalledWith({ walletId, address });
     expect(transactionGetPendingTransactionsMock).toHaveBeenCalledWith({ walletId });
     expect(res.status).toHaveBeenCalledWith(200);
diff --git a/src/__tests__/setup.ts b/src/__tests__/setup.ts
index 8c3f3826..d9260246 100644
--- a/src/__tests__/setup.ts
+++ b/src/__tests__/setup.ts
@@ -1,5 +1,5 @@
 // Test setup file for Jest
-import '@jest/globals';
+import { jest, beforeEach, afterEach } from '@jest/globals';
 
 // Mock console methods to reduce noise in tests
 global.console = {
@@ -14,3 +14,34 @@ global.console = {
 
 // Global test timeout
 jest.setTimeout(10000);
+
+// Determinism: freeze the wall clock (`Date.now` / `new Date()`) so tests are
+// byte-identical across runs. Timer APIs (setTimeout/setInterval/etc) stay
+// real — many tests in this suite hit tRPC's timing middleware and other
+// real-async paths that hang under faked timers. Tests that specifically
+// exercise timer behavior can opt in via `jest.useFakeTimers()` in `beforeAll`.
+beforeEach(() => {
+  jest.useFakeTimers({
+    now: new Date('2026-01-01T00:00:00Z'),
+    doNotFake: [
+      'nextTick',
+      'setImmediate',
+      'clearImmediate',
+      'queueMicrotask',
+      'setTimeout',
+      'clearTimeout',
+      'setInterval',
+      'clearInterval',
+      'requestAnimationFrame',
+      'cancelAnimationFrame',
+      'requestIdleCallback',
+      'cancelIdleCallback',
+      'hrtime',
+      'performance',
+    ],
+  });
+});
+
+afterEach(() => {
+  jest.useRealTimers();
+});
diff --git a/src/__tests__/setupEnv.cjs b/src/__tests__/setupEnv.cjs
new file mode 100644
index 00000000..1314d88b
--- /dev/null
+++ b/src/__tests__/setupEnv.cjs
@@ -0,0 +1,21 @@
+// @ts-nocheck — env bootstrap; checkJs flags `NODE_ENV` as read-only
+// because @types/node narrows it to a literal union, but writing it here
+// is intentional and safe (runs before any test module is imported).
+//
+// Sets dummy env vars so that `src/env.js` (t3-oss validate) does not throw
+// when test files import server modules transitively.
+// Tests that need real values can override per-test with `process.env.X = ...`
+// inside `beforeEach`.
+
+process.env['NODE_ENV'] = process.env['NODE_ENV'] || 'test';
+process.env.SKIP_ENV_VALIDATION = '1';
+
+process.env.DATABASE_URL = process.env.DATABASE_URL || 'postgresql://test:test@localhost:5432/test';
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'a'.repeat(48);
+process.env.PINATA_JWT = process.env.PINATA_JWT || 'test-pinata-jwt';
+
+process.env.NEXT_PUBLIC_BLOCKFROST_API_KEY_MAINNET =
+  process.env.NEXT_PUBLIC_BLOCKFROST_API_KEY_MAINNET || 'test-blockfrost-mainnet';
+process.env.NEXT_PUBLIC_BLOCKFROST_API_KEY_PREPROD =
+  process.env.NEXT_PUBLIC_BLOCKFROST_API_KEY_PREPROD || 'test-blockfrost-preprod';
+process.env.NEXT_PUBLIC_NETWORK_ID = process.env.NEXT_PUBLIC_NETWORK_ID || '0';
diff --git a/src/__tests__/signTransaction.test.ts b/src/__tests__/signTransaction.test.ts
index f4b2e873..41167d64 100644
--- a/src/__tests__/signTransaction.test.ts
+++ b/src/__tests__/signTransaction.test.ts
@@ -4,64 +4,73 @@ import type { NextApiRequest, NextApiResponse } from 'next';
 const addCorsCacheBustingHeadersMock = jest.fn<(res: NextApiResponse) => void>();
 const corsMock = jest.fn<(req: NextApiRequest, res: NextApiResponse) => Promise<void>>();
 
-jest.mock(
+jest.unstable_mockModule(
   '@/lib/cors',
   () => ({
     __esModule: true,
     addCorsCacheBustingHeaders: addCorsCacheBustingHeadersMock,
     cors: corsMock,
   }),
-  { virtual: true },
 );
 
-const verifyJwtMock = jest.fn<(token: string | undefined) => { address: string } | null>();
+type JwtPayloadLike = { address: string; botId?: string; type?: string };
+const verifyJwtMock = jest.fn<(token: string | undefined) => JwtPayloadLike | null>();
+const isBotJwtMock = jest.fn<(payload: JwtPayloadLike) => boolean>(
+  (payload) => Boolean(payload && (payload as JwtPayloadLike).type === "bot"),
+);
 
-jest.mock(
+jest.unstable_mockModule(
   '@/lib/verifyJwt',
   () => ({
     __esModule: true,
     verifyJwt: verifyJwtMock,
+    isBotJwt: isBotJwtMock,
   }),
-  { virtual: true },
 );
 
 const applyRateLimitMock = jest.fn<
   (req: NextApiRequest, res: NextApiResponse, options?: unknown) => boolean
 >();
+const applyStrictRateLimitMock = jest.fn<
+  (req: NextApiRequest, res: NextApiResponse, options?: unknown) => boolean
+>();
+const applyBotRateLimitMock = jest.fn<
+  (req: NextApiRequest, res: NextApiResponse, botId: string, maxRequests?: number) => boolean
+>();
 const enforceBodySizeMock = jest.fn<
   (req: NextApiRequest, res: NextApiResponse, maxBytes: number) => boolean
 >();
 
-jest.mock(
+jest.unstable_mockModule(
   '@/lib/security/requestGuards',
   () => ({
     __esModule: true,
     applyRateLimit: applyRateLimitMock,
+    applyStrictRateLimit: applyStrictRateLimitMock,
+    applyBotRateLimit: applyBotRateLimitMock,
     enforceBodySize: enforceBodySizeMock,
+    isBodyTooLarge: jest.fn(() => false),
   }),
-  { virtual: true },
 );
 
 const getClientIPMock = jest.fn<(req: NextApiRequest) => string>();
 
-jest.mock(
+jest.unstable_mockModule(
   '@/lib/security/rateLimit',
   () => ({
     __esModule: true,
     getClientIP: getClientIPMock,
   }),
-  { virtual: true },
 );
 
 const createCallerMock = jest.fn();
 
-jest.mock(
+jest.unstable_mockModule(
   '@/server/api/root',
   () => ({
     __esModule: true,
     createCaller: createCallerMock,
   }),
-  { virtual: true },
 );
 
 const dbTransactionFindUniqueMock = jest.fn<(args: unknown) => Promise<unknown>>();
@@ -79,35 +88,32 @@ const dbMock = {
   },
 };
 
-jest.mock(
+jest.unstable_mockModule(
   '@/server/db',
   () => ({
     __esModule: true,
     db: dbMock,
   }),
-  { virtual: true },
 );
 
 const getProviderMock = jest.fn<(network: number) => unknown>();
 
-jest.mock(
+jest.unstable_mockModule(
   '@/utils/get-provider',
   () => ({
     __esModule: true,
     getProvider: getProviderMock,
   }),
-  { virtual: true },
 );
 
 const addressToNetworkMock = jest.fn<(address: string) => number>();
 
-jest.mock(
+jest.unstable_mockModule(
   '@/utils/multisigSDK',
   () => ({
     __esModule: true,
     addressToNetwork: addressToNetworkMock,
   }),
-  { virtual: true },
 );
 
 const shouldSubmitMultisigTxMock = jest.fn<
@@ -132,7 +138,7 @@ const addUniqueVkeyWitnessToTxMock = jest.fn<
   }
 >();
 
-jest.mock(
+jest.unstable_mockModule(
   '@/utils/txSignUtils',
   () => ({
     __esModule: true,
@@ -141,18 +147,16 @@ jest.mock(
     shouldSubmitMultisigTx: shouldSubmitMultisigTxMock,
     submitTxWithScriptRecovery: submitTxWithScriptRecoveryMock,
   }),
-  { virtual: true },
 );
 
 const resolvePaymentKeyHashMock = jest.fn<(address: string) => string>();
 
-jest.mock(
+jest.unstable_mockModule(
   '@meshsdk/core',
   () => ({
     __esModule: true,
     resolvePaymentKeyHash: resolvePaymentKeyHashMock,
   }),
-  { virtual: true },
 );
 
 const witnessKeyHashHex = '00112233';
@@ -355,14 +359,13 @@ const cslMock = {
   Vkeywitnesses: MockVkeywitnesses,
 };
 
-jest.mock(
+jest.unstable_mockModule(
   '@meshsdk/core-csl',
   () => ({
     __esModule: true,
     csl: cslMock,
     calculateTxHash: calculateTxHashMock,
   }),
-  { virtual: true },
 );
 
 const consoleErrorSpy = jest
@@ -420,7 +423,15 @@ beforeEach(() => {
   addCorsCacheBustingHeadersMock.mockReset();
   createCallerMock.mockReset();
   verifyJwtMock.mockReset();
+  isBotJwtMock.mockReset();
+  isBotJwtMock.mockImplementation(
+    (payload) => Boolean(payload && (payload as JwtPayloadLike).type === "bot"),
+  );
   applyRateLimitMock.mockReset();
+  applyStrictRateLimitMock.mockReset();
+  applyBotRateLimitMock.mockReset();
+  applyBotRateLimitMock.mockReturnValue(true);
+  applyStrictRateLimitMock.mockReturnValue(true);
   enforceBodySizeMock.mockReset();
   getClientIPMock.mockReset();
 
@@ -456,7 +467,7 @@ beforeEach(() => {
     for (let i = 0; i < existingWitnessCount; i++) {
       const existingWitness = mergedWitnesses.get(i);
       const existingKeyHash = Buffer.from(
-        existingWitness.vkey().public_key().hash().to_bytes(),
+        existingWitness!.vkey().public_key().hash().to_bytes(),
       ).toString('hex').toLowerCase();
 
       if (existingKeyHash === incomingKeyHash) {
diff --git a/src/__tests__/signing.test.ts b/src/__tests__/signing.test.ts
new file mode 100644
index 00000000..81d46b3d
--- /dev/null
+++ b/src/__tests__/signing.test.ts
@@ -0,0 +1,107 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { describe, expect, it, jest } from "@jest/globals";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// ---------------------------------------------------------------------------
+// Tripwire: the "broken" pattern — `return true ? signature : undefined;`
+// must never reappear in `src/utils/signing.ts`. It both throws away the
+// `checkSignature` result and obscures the actual signing contract. The
+// regression we fixed here was that a failed signature verification still
+// returned a (forged-looking) signature to the caller because the ternary
+// was always truthy.
+// ---------------------------------------------------------------------------
+describe("signing.ts source contract", () => {
+  it("never returns the always-true ternary on the verification result", () => {
+    const src = fs.readFileSync(
+      path.resolve(__dirname, "../utils/signing.ts"),
+      "utf8",
+    );
+    expect(src).not.toMatch(/return\s+true\s*\?/);
+    // Positive: the verified result must drive an explicit `if (!verified)`
+    // throw. The exact identifier we use is `verified` — accept either name
+    // so a future rename doesn't trip the tripwire.
+    expect(src).toMatch(/if\s*\(\s*!\s*(verified|result)\b/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Behavioural: import the real `sign` and exercise every role plus the
+// failure path. We mock the @meshsdk/core helpers because they pull in
+// CSL/serialization which is heavyweight for a unit test.
+// ---------------------------------------------------------------------------
+const checkSignatureMock = jest.fn<
+  (nonce: string, signature: { signature: string; key: string }, address?: string) => Promise<boolean>
+>();
+const generateNonceMock = jest.fn<(payload: string) => string>();
+
+jest.unstable_mockModule("@meshsdk/core", () => ({
+  __esModule: true,
+  checkSignature: checkSignatureMock,
+  generateNonce: generateNonceMock,
+}));
+
+const { sign } = await import("../utils/signing");
+
+type MockWallet = {
+  signData: jest.Mock<(payload: string, address?: string) => Promise<{ signature: string; key: string }>>;
+  getRewardAddresses: jest.Mock<() => Promise<string[]>>;
+};
+
+function createWallet(overrides?: Partial<MockWallet>): MockWallet {
+  return {
+    signData: jest.fn<(payload: string, address?: string) => Promise<{ signature: string; key: string }>>(
+      async () => ({ signature: "deadbeef", key: "cafe" }),
+    ),
+    getRewardAddresses: jest.fn<() => Promise<string[]>>(async () => ["stake_addr"]),
+    ...overrides,
+  } as MockWallet;
+}
+
+describe("sign", () => {
+  beforeEach(() => {
+    checkSignatureMock.mockReset();
+    generateNonceMock.mockReset();
+    generateNonceMock.mockReturnValue("nonce-payload");
+  });
+
+  it("role=0 signs with the user payment address and returns the signature", async () => {
+    checkSignatureMock.mockResolvedValueOnce(true);
+    const wallet = createWallet();
+    const sig = await sign("payload", wallet as never, 0, "addr_test_user");
+    expect(sig).toEqual({ signature: "deadbeef", key: "cafe" });
+    expect(wallet.signData).toHaveBeenCalledWith("payload", "addr_test_user");
+  });
+
+  it("role=2 signs with the wallet's reward (stake) address", async () => {
+    checkSignatureMock.mockResolvedValueOnce(true);
+    const wallet = createWallet();
+    await sign("payload", wallet as never, 2);
+    expect(wallet.getRewardAddresses).toHaveBeenCalled();
+    expect(wallet.signData).toHaveBeenCalledWith("payload", "stake_addr");
+  });
+
+  it("role=3 requires an explicit dRepAddress and uses it", async () => {
+    checkSignatureMock.mockResolvedValueOnce(true);
+    const wallet = createWallet();
+    await sign("payload", wallet as never, 3, undefined, "drep_xxx");
+    expect(wallet.signData).toHaveBeenCalledWith("payload", "drep_xxx");
+  });
+
+  it("throws when the chosen role has no resolved address", async () => {
+    const wallet = createWallet();
+    await expect(sign("payload", wallet as never, 0, undefined)).rejects.toThrow(
+      /missing address/i,
+    );
+  });
+
+  it("throws when checkSignature returns false (no silent ternary fallback)", async () => {
+    checkSignatureMock.mockResolvedValueOnce(false);
+    const wallet = createWallet();
+    await expect(sign("payload", wallet as never, 0, "addr_test_user")).rejects.toThrow(
+      /Signature failed verification/i,
+    );
+  });
+});
diff --git a/src/components/ui/form.tsx b/src/components/ui/form.tsx
deleted file mode 100644
index f6afdaf2..00000000
--- a/src/components/ui/form.tsx
+++ /dev/null
@@ -1,176 +0,0 @@
-import * as React from "react"
-import * as LabelPrimitive from "@radix-ui/react-label"
-import { Slot } from "@radix-ui/react-slot"
-import {
-  Controller,
-  ControllerProps,
-  FieldPath,
-  FieldValues,
-  FormProvider,
-  useFormContext,
-} from "react-hook-form"
-
-import { cn } from "@/lib/utils"
-import { Label } from "@/components/ui/label"
-
-const Form = FormProvider
-
-type FormFieldContextValue<
-  TFieldValues extends FieldValues = FieldValues,
-  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>
-> = {
-  name: TName
-}
-
-const FormFieldContext = React.createContext<FormFieldContextValue>(
-  {} as FormFieldContextValue
-)
-
-const FormField = <
-  TFieldValues extends FieldValues = FieldValues,
-  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>
->({
-  ...props
-}: ControllerProps<TFieldValues, TName>) => {
-  return (
-    <FormFieldContext.Provider value={{ name: props.name }}>
-      <Controller {...props} />
-    </FormFieldContext.Provider>
-  )
-}
-
-const useFormField = () => {
-  const fieldContext = React.useContext(FormFieldContext)
-  const itemContext = React.useContext(FormItemContext)
-  const { getFieldState, formState } = useFormContext()
-
-  const fieldState = getFieldState(fieldContext.name, formState)
-
-  if (!fieldContext) {
-    throw new Error("useFormField should be used within <FormField>")
-  }
-
-  const { id } = itemContext
-
-  return {
-    id,
-    name: fieldContext.name,
-    formItemId: `${id}-form-item`,
-    formDescriptionId: `${id}-form-item-description`,
-    formMessageId: `${id}-form-item-message`,
-    ...fieldState,
-  }
-}
-
-type FormItemContextValue = {
-  id: string
-}
-
-const FormItemContext = React.createContext<FormItemContextValue>(
-  {} as FormItemContextValue
-)
-
-const FormItem = React.forwardRef<
-  HTMLDivElement,
-  React.HTMLAttributes<HTMLDivElement>
->(({ className, ...props }, ref) => {
-  const id = React.useId()
-
-  return (
-    <FormItemContext.Provider value={{ id }}>
-      <div ref={ref} className={cn("space-y-2", className)} {...props} />
-    </FormItemContext.Provider>
-  )
-})
-FormItem.displayName = "FormItem"
-
-const FormLabel = React.forwardRef<
-  React.ElementRef<typeof LabelPrimitive.Root>,
-  React.ComponentPropsWithoutRef<typeof LabelPrimitive.Root>
->(({ className, ...props }, ref) => {
-  const { error, formItemId } = useFormField()
-
-  return (
-    <Label
-      ref={ref}
-      className={cn(error && "text-destructive", className)}
-      htmlFor={formItemId}
-      {...props}
-    />
-  )
-})
-FormLabel.displayName = "FormLabel"
-
-const FormControl = React.forwardRef<
-  React.ElementRef<typeof Slot>,
-  React.ComponentPropsWithoutRef<typeof Slot>
->(({ ...props }, ref) => {
-  const { error, formItemId, formDescriptionId, formMessageId } = useFormField()
-
-  return (
-    <Slot
-      ref={ref}
-      id={formItemId}
-      aria-describedby={
-        !error
-          ? `${formDescriptionId}`
-          : `${formDescriptionId} ${formMessageId}`
-      }
-      aria-invalid={!!error}
-      {...props}
-    />
-  )
-})
-FormControl.displayName = "FormControl"
-
-const FormDescription = React.forwardRef<
-  HTMLParagraphElement,
-  React.HTMLAttributes<HTMLParagraphElement>
->(({ className, ...props }, ref) => {
-  const { formDescriptionId } = useFormField()
-
-  return (
-    <p
-      ref={ref}
-      id={formDescriptionId}
-      className={cn("text-[0.8rem] text-muted-foreground", className)}
-      {...props}
-    />
-  )
-})
-FormDescription.displayName = "FormDescription"
-
-const FormMessage = React.forwardRef<
-  HTMLParagraphElement,
-  React.HTMLAttributes<HTMLParagraphElement>
->(({ className, children, ...props }, ref) => {
-  const { error, formMessageId } = useFormField()
-  const body = error ? String(error?.message) : children
-
-  if (!body) {
-    return null
-  }
-
-  return (
-    <p
-      ref={ref}
-      id={formMessageId}
-      className={cn("text-[0.8rem] font-medium text-destructive", className)}
-      {...props}
-    >
-      {body}
-    </p>
-  )
-})
-FormMessage.displayName = "FormMessage"
-
-export {
-  useFormField,
-  Form,
-  FormItem,
-  FormLabel,
-  FormControl,
-  FormDescription,
-  FormMessage,
-  FormField,
-}
diff --git a/src/env.js b/src/env.js
index a60d68ea..50aeb0f7 100644
--- a/src/env.js
+++ b/src/env.js
@@ -17,6 +17,12 @@ export const env = createEnv({
     JWT_SECRET: z.string().min(32),
     BLOCKFROST_API_KEY_PREPROD: z.string().optional(),
     BLOCKFROST_API_KEY_MAINNET: z.string().optional(),
+    /**
+     * Comma-separated list of hostnames the OG metadata fetcher (`/api/v1/og`)
+     * is allowed to talk to. Defaults to a small allow-list when unset; set to
+     * "*" to allow any public hostname (still SSRF-guarded against private ranges).
+     */
+    OG_ALLOWED_HOSTS: z.string().optional(),
     // NEXTAUTH_SECRET / NEXTAUTH_URL / DISCORD_* are intentionally commented.
     // NextAuth runs with PrismaAdapter only — no auth providers configured yet.
     // Uncomment and add to runtimeEnv below when adding an OAuth provider.
@@ -76,6 +82,7 @@ export const env = createEnv({
     JWT_SECRET: process.env.JWT_SECRET,
     BLOCKFROST_API_KEY_PREPROD: process.env.BLOCKFROST_API_KEY_PREPROD,
     BLOCKFROST_API_KEY_MAINNET: process.env.BLOCKFROST_API_KEY_MAINNET,
+    OG_ALLOWED_HOSTS: process.env.OG_ALLOWED_HOSTS,
   },
   /**
    * Run `build` or `dev` with `SKIP_ENV_VALIDATION` to skip env validation. This is especially
diff --git a/src/lib/auth/walletSession.ts b/src/lib/auth/walletSession.ts
index bbf86437..88d39246 100644
--- a/src/lib/auth/walletSession.ts
+++ b/src/lib/auth/walletSession.ts
@@ -1,4 +1,6 @@
-import { sign, verify } from "jsonwebtoken";
+import jwt from "jsonwebtoken";
+
+const { sign, verify } = jwt;
 import type { NextApiRequest, NextApiResponse } from "next";
 import { env } from "@/env";
 
diff --git a/src/lib/observability/audit.ts b/src/lib/observability/audit.ts
new file mode 100644
index 00000000..890b3615
--- /dev/null
+++ b/src/lib/observability/audit.ts
@@ -0,0 +1,54 @@
+/**
+ * Append-only AuditLog emitter.
+ *
+ * Use for security-relevant events: auth flows, privilege grants, wallet
+ * mutations, signing actions. Failures to write are logged but never thrown —
+ * an audit miss must not break the user-facing flow.
+ */
+
+import type { PrismaClient } from "@prisma/client";
+import { logger, redact } from "./logger";
+
+export type AuditOutcome = "success" | "denied" | "error";
+export type AuditActorType = "user" | "bot" | "system";
+
+export type AuditEvent = {
+  actorAddress?: string | null;
+  actorType: AuditActorType;
+  action: string;
+  resourceType?: string | null;
+  resourceId?: string | null;
+  ip?: string | null;
+  userAgent?: string | null;
+  outcome: AuditOutcome;
+  reason?: string | null;
+  metadata?: Record<string, unknown>;
+};
+
+export async function audit(db: PrismaClient, event: AuditEvent): Promise<void> {
+  try {
+    const safeMetadata =
+      event.metadata !== undefined
+        ? (redact(event.metadata) as Record<string, unknown>)
+        : undefined;
+    await db.auditLog.create({
+      data: {
+        actorAddress: event.actorAddress ?? null,
+        actorType: event.actorType,
+        action: event.action,
+        resourceType: event.resourceType ?? null,
+        resourceId: event.resourceId ?? null,
+        ip: event.ip ?? null,
+        userAgent: event.userAgent ?? null,
+        outcome: event.outcome,
+        reason: event.reason ?? null,
+        metadata: safeMetadata as never,
+      },
+    });
+  } catch (err) {
+    logger.warn("audit.emit_failed", {
+      action: event.action,
+      err: err instanceof Error ? err.message : String(err),
+    });
+  }
+}
diff --git a/src/lib/observability/logger.ts b/src/lib/observability/logger.ts
new file mode 100644
index 00000000..5b9ce794
--- /dev/null
+++ b/src/lib/observability/logger.ts
@@ -0,0 +1,80 @@
+/**
+ * Structured logger.
+ *
+ * - Production: emits one JSON line per call to stdout/stderr.
+ * - Development: emits a single human-readable line.
+ *
+ * Built on console; no extra deps. Never logs raw tokens, signatures, or
+ * cookies — callers should pre-redact.
+ */
+
+const isProd = process.env.NODE_ENV === "production";
+
+const SECRET_KEYS = new Set([
+  "access_token",
+  "refresh_token",
+  "id_token",
+  "client_secret",
+  "authorization",
+  "cookie",
+  "set-cookie",
+  "password",
+  "jwt",
+  "token",
+  "secret",
+  "apiKey",
+  "api_key",
+]);
+
+export function redact(value: unknown): unknown {
+  if (value === null || value === undefined) return value;
+  if (Array.isArray(value)) return value.map(redact);
+  if (typeof value !== "object") return value;
+  const obj = value as Record<string, unknown>;
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (SECRET_KEYS.has(k.toLowerCase())) {
+      out[k] = "[REDACTED]";
+    } else {
+      out[k] = redact(v);
+    }
+  }
+  return out;
+}
+
+type LogLevel = "debug" | "info" | "warn" | "error";
+
+function emit(level: LogLevel, msg: string, ctx?: Record<string, unknown>) {
+  const safeCtx = ctx ? (redact(ctx) as Record<string, unknown>) : undefined;
+  if (isProd) {
+    const line = JSON.stringify({
+      ts: new Date().toISOString(),
+      level,
+      msg,
+      ...(safeCtx ? { ctx: safeCtx } : {}),
+    });
+    if (level === "error") {
+      console.error(line);
+    } else if (level === "warn") {
+      console.warn(line);
+    } else {
+      console.log(line);
+    }
+    return;
+  }
+  // Dev: pretty
+  const fn =
+    level === "error" ? console.error : level === "warn" ? console.warn : console.log;
+  if (safeCtx) {
+    fn(`[${level}] ${msg}`, safeCtx);
+  } else {
+    fn(`[${level}] ${msg}`);
+  }
+}
+
+export const logger = {
+  debug: (msg: string, ctx?: Record<string, unknown>) => emit("debug", msg, ctx),
+  info: (msg: string, ctx?: Record<string, unknown>) => emit("info", msg, ctx),
+  warn: (msg: string, ctx?: Record<string, unknown>) => emit("warn", msg, ctx),
+  error: (msg: string, ctx?: Record<string, unknown>) => emit("error", msg, ctx),
+};
diff --git a/src/lib/security/rateLimit.ts b/src/lib/security/rateLimit.ts
index 291baad3..33ad986e 100644
--- a/src/lib/security/rateLimit.ts
+++ b/src/lib/security/rateLimit.ts
@@ -44,5 +44,5 @@ export function getClientIP(req: any): string {
     return realIP;
   }
   
-  return req.socket.remoteAddress ?? 'unknown';
+  return req.socket?.remoteAddress ?? 'unknown';
 }
diff --git a/src/lib/verifyJwt.ts b/src/lib/verifyJwt.ts
index 5ac1aee5..a790c755 100644
--- a/src/lib/verifyJwt.ts
+++ b/src/lib/verifyJwt.ts
@@ -1,4 +1,6 @@
-import { verify } from "jsonwebtoken";
+import jwt from "jsonwebtoken";
+
+const { verify } = jwt;
 
 export type JwtPayload =
   | { address: string; botId?: undefined; type?: undefined }
diff --git a/src/pages/api/auth/discord/callback.ts b/src/pages/api/auth/discord/callback.ts
index 98b221d9..e5a2b127 100644
--- a/src/pages/api/auth/discord/callback.ts
+++ b/src/pages/api/auth/discord/callback.ts
@@ -1,5 +1,48 @@
 import { type NextApiRequest, type NextApiResponse } from "next";
+import jwt from "jsonwebtoken";
 import { db } from "@/server/db";
+import { audit } from "@/lib/observability/audit";
+import { getClientIP } from "@/lib/security/rateLimit";
+
+const { verify } = jwt;
+
+type DiscordOAuthState = {
+  address: string;
+  // short-lived nonce; binding to a session cookie is the long-term fix but
+  // a signed, time-bound state already closes the open-redirect/CSRF that
+  // shipped before (raw `state = userAddress` was attacker-forgeable).
+  nonce: string;
+};
+
+function verifyState(raw: string): DiscordOAuthState | null {
+  const secret = process.env.JWT_SECRET;
+  if (!secret) return null;
+  try {
+    const payload = verify(raw, secret) as Partial<DiscordOAuthState>;
+    if (!payload || typeof payload.address !== "string" || typeof payload.nonce !== "string") {
+      return null;
+    }
+    return { address: payload.address, nonce: payload.nonce };
+  } catch {
+    return null;
+  }
+}
+
+const REDACT_KEYS = new Set([
+  "access_token",
+  "refresh_token",
+  "id_token",
+  "client_secret",
+]);
+
+function redactSecrets(obj: unknown): unknown {
+  if (obj === null || typeof obj !== "object") return obj;
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj as Record<string, unknown>)) {
+    out[k] = REDACT_KEYS.has(k) ? "[REDACTED]" : v;
+  }
+  return out;
+}
 
 export default async function handler(
   req: NextApiRequest,
@@ -7,15 +50,27 @@ export default async function handler(
 ) {
   const { code, state } = req.query;
 
-  if (!code) {
+  if (!code || typeof code !== "string") {
     return res.status(400).json({ error: "No code provided" });
   }
 
-  if (!state) {
+  if (!state || typeof state !== "string") {
     return res.status(400).json({ error: "No state provided" });
   }
 
-  const userAddress = decodeURIComponent(state as string);
+  const verifiedState = verifyState(state);
+  if (!verifiedState) {
+    void audit(db, {
+      actorType: "user",
+      action: "auth.discord.state_invalid",
+      ip: getClientIP(req),
+      userAgent: req.headers["user-agent"] ?? null,
+      outcome: "denied",
+      reason: "Invalid or expired state",
+    });
+    return res.status(400).json({ error: "Invalid or expired state" });
+  }
+  const userAddress = verifiedState.address;
 
   try {
     const redirectUri =
@@ -26,57 +81,61 @@ export default async function handler(
     const params = new URLSearchParams({
       client_id: process.env.DISCORD_CLIENT_ID!,
       client_secret: process.env.DISCORD_CLIENT_SECRET!,
-      code: code as string,
+      code,
       grant_type: "authorization_code",
       redirect_uri: redirectUri,
     });
 
-    // Log exactly what you’re sending:
-    console.log("→ [Discord Token] POST body:", params.toString());
-
     const tokenResponse = await fetch("https://discord.com/api/oauth2/token", {
       method: "POST",
       body: params,
       headers: { "Content-Type": "application/x-www-form-urlencoded" },
     });
 
-    // Read it once as text, then JSON.parse
     const raw = await tokenResponse.text();
-    console.log("← [Discord Token] status:", tokenResponse.status);
-    console.log("← [Discord Token] body:", raw);
-
-    let tokens;
+    let tokens: Record<string, unknown>;
     try {
-      tokens = JSON.parse(raw);
+      tokens = JSON.parse(raw) as Record<string, unknown>;
     } catch {
-      throw new Error("Discord returned non‑JSON on token exchange");
+      console.error("[Discord Token] non-JSON response", { status: tokenResponse.status });
+      throw new Error("Discord returned non-JSON on token exchange");
     }
 
     if (tokens.error) {
-      console.error(
-        "↪︎ [Discord Token] error_description:",
-        tokens.error_description,
-      );
-      return res.status(400).json({ error: tokens.error_description });
+      console.error("[Discord Token] error", redactSecrets(tokens));
+      return res.status(400).json({ error: tokens.error_description ?? "Discord token error" });
+    }
+
+    const accessToken = typeof tokens.access_token === "string" ? tokens.access_token : null;
+    if (!accessToken) {
+      return res.status(400).json({ error: "No access token from Discord" });
     }
 
-    // Get user info using the access token
     const userResponse = await fetch("https://discord.com/api/users/@me", {
       headers: {
-        Authorization: `Bearer ${tokens.access_token}`,
+        Authorization: `Bearer ${accessToken}`,
         "Content-Type": "application/json",
       },
     });
 
-    const user = await userResponse.json();
-    if (user) {
-      // Store Discord ID in database
+    const user = (await userResponse.json()) as { id?: string } | null;
+    if (user?.id) {
       await db.user.update({
         where: { address: userAddress },
         data: { discordId: user.id },
       });
 
-      // Check if user is in the guild
+      void audit(db, {
+        actorAddress: userAddress,
+        actorType: "user",
+        action: "auth.discord.linked",
+        resourceType: "user",
+        resourceId: userAddress,
+        ip: getClientIP(req),
+        userAgent: req.headers["user-agent"] ?? null,
+        outcome: "success",
+      });
+
       const guildId = process.env.DISCORD_GUILD_ID;
       const guildMemberCheck = await fetch(
         `https://discord.com/api/v10/guilds/${guildId}/members/${user.id}`,
@@ -88,15 +147,13 @@ export default async function handler(
       );
 
       if (guildMemberCheck.status === 404) {
-        // Redirect to invite link
         return res.redirect("https://discord.gg/DkNPvvGTqK");
       }
     }
 
-    // Then redirect
     res.redirect("/");
   } catch (error) {
-    console.error("Discord auth error:", error);
+    console.error("Discord auth error:", error instanceof Error ? error.message : "unknown");
     res.status(500).json({ error: "Failed to authenticate with Discord" });
   }
 }
diff --git a/src/pages/api/auth/discord/start.ts b/src/pages/api/auth/discord/start.ts
new file mode 100644
index 00000000..28960f72
--- /dev/null
+++ b/src/pages/api/auth/discord/start.ts
@@ -0,0 +1,55 @@
+import { type NextApiRequest, type NextApiResponse } from "next";
+import jwt from "jsonwebtoken";
+import { randomBytes } from "crypto";
+import { env } from "@/env";
+import { getWalletSessionFromReq } from "@/lib/auth/walletSession";
+
+const { sign } = jwt;
+
+// Mints a signed, short-lived OAuth state token and returns the Discord
+// authorize URL. The state is a JWT bound to the caller's session address
+// plus a random nonce; the callback (`/api/auth/discord/callback.ts`)
+// verifies it before binding a discord ID. Without this, the previous
+// `state = userAddress` shape was forgeable and CSRF-able.
+export default async function handler(
+  req: NextApiRequest,
+  res: NextApiResponse,
+) {
+  if (req.method !== "GET") {
+    res.setHeader("Allow", "GET");
+    return res.status(405).json({ error: "Method not allowed" });
+  }
+
+  const session = getWalletSessionFromReq(req);
+  const primary = session?.primaryWallet ?? session?.wallets?.[0];
+  if (!primary) {
+    return res.status(401).json({ error: "Not authenticated" });
+  }
+
+  const clientId = process.env.NEXT_PUBLIC_DISCORD_CLIENT_ID;
+  if (!clientId) {
+    return res.status(500).json({ error: "Discord client not configured" });
+  }
+
+  const redirectBase =
+    env.NODE_ENV === "production"
+      ? "https://multisig.meshjs.dev"
+      : "http://localhost:3000";
+  const redirectUri = `${redirectBase}/api/auth/discord/callback`;
+
+  const nonce = randomBytes(16).toString("hex");
+  const state = sign(
+    { address: primary, nonce },
+    env.JWT_SECRET,
+    { expiresIn: "10m" },
+  );
+
+  const url = new URL("https://discord.com/api/oauth2/authorize");
+  url.searchParams.set("client_id", clientId);
+  url.searchParams.set("redirect_uri", redirectUri);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("scope", "identify");
+  url.searchParams.set("state", state);
+
+  return res.status(200).json({ url: url.toString() });
+}
diff --git a/src/pages/api/v1/addTransaction.ts b/src/pages/api/v1/addTransaction.ts
index 8ef53c1e..633e5b5a 100644
--- a/src/pages/api/v1/addTransaction.ts
+++ b/src/pages/api/v1/addTransaction.ts
@@ -95,7 +95,20 @@ export default async function handler(
 
   const reqSigners = wallet.numRequiredSigners;
   const type = wallet.type;
-  const network = address.includes("test") ? 0 : 1;
+  // Derive network from the bech32 HRP (human-readable prefix) instead of
+  // the older `address.includes("test")` substring check, which would
+  // mis-classify any mainnet address whose bech32 body happened to contain
+  // the substring "test". Cardano HRPs:
+  //   `addr1...` / `stake1...` = mainnet
+  //   `addr_test1...` / `stake_test1...` = testnet
+  let network: 0 | 1;
+  if (/^(addr_test1|stake_test1)/.test(address)) {
+    network = 0;
+  } else if (/^(addr1|stake1)/.test(address)) {
+    network = 1;
+  } else {
+    return res.status(400).json({ error: "Invalid address" });
+  }
 
   try {
     let newTx;
diff --git a/src/pages/api/v1/authSigner.ts b/src/pages/api/v1/authSigner.ts
index 59b81bb5..b49cc18c 100644
--- a/src/pages/api/v1/authSigner.ts
+++ b/src/pages/api/v1/authSigner.ts
@@ -1,12 +1,16 @@
 import type { NextApiRequest, NextApiResponse } from "next";
 import { db } from "@/server/db";
-import { sign } from "jsonwebtoken";
+import jwt from "jsonwebtoken";
+
+const { sign } = jwt;
 import {
   checkSignature,
   DataSignature,
 } from "@meshsdk/core";
 import { cors, addCorsCacheBustingHeaders } from "@/lib/cors";
 import { applyRateLimit, enforceBodySize } from "@/lib/security/requestGuards";
+import { audit } from "@/lib/observability/audit";
+import { getClientIP } from "@/lib/security/rateLimit";
 
 export default async function handler(
   req: NextApiRequest,
@@ -53,6 +57,15 @@ export default async function handler(
     const isValid = await checkSignature(nonce, sig, address);
 
     if (!isValid) {
+      void audit(db, {
+        actorAddress: address,
+        actorType: "user",
+        action: "auth.sign_in.invalid_signature",
+        ip: getClientIP(req),
+        userAgent: req.headers["user-agent"] ?? null,
+        outcome: "denied",
+        reason: "Invalid signature",
+      });
       return res.status(401).json({ error: "Invalid signature" });
     }
 
@@ -71,10 +84,28 @@ export default async function handler(
         jwtSecret,
         { expiresIn: "1h" },
       );
+      void audit(db, {
+        actorAddress: address,
+        actorType: "bot",
+        action: "auth.sign_in",
+        resourceType: "bot",
+        resourceId: botUser.id,
+        ip: getClientIP(req),
+        userAgent: req.headers["user-agent"] ?? null,
+        outcome: "success",
+      });
       return res.status(200).json({ token });
     }
 
     const token = sign({ address }, jwtSecret, { expiresIn: "1h" });
+    void audit(db, {
+      actorAddress: address,
+      actorType: "user",
+      action: "auth.sign_in",
+      ip: getClientIP(req),
+      userAgent: req.headers["user-agent"] ?? null,
+      outcome: "success",
+    });
     return res.status(200).json({ token });
   }
 
diff --git a/src/pages/api/v1/botAuth.ts b/src/pages/api/v1/botAuth.ts
index 52f2d331..7f198427 100644
--- a/src/pages/api/v1/botAuth.ts
+++ b/src/pages/api/v1/botAuth.ts
@@ -1,6 +1,8 @@
 import type { NextApiRequest, NextApiResponse } from "next";
 import { db } from "@/server/db";
-import { sign } from "jsonwebtoken";
+import jwt from "jsonwebtoken";
+
+const { sign } = jwt;
 import { cors, addCorsCacheBustingHeaders } from "@/lib/cors";
 import { applyStrictRateLimit, enforceBodySize } from "@/lib/security/requestGuards";
 import { verifyBotKeySecret, parseScope, scopeIncludes, type BotScope } from "@/lib/auth/botKey";
diff --git a/src/pages/api/v1/getNonce.ts b/src/pages/api/v1/getNonce.ts
index 3611b221..75089746 100644
--- a/src/pages/api/v1/getNonce.ts
+++ b/src/pages/api/v1/getNonce.ts
@@ -44,21 +44,21 @@ export default async function handler(
         console.warn("[getNonce] User lookup failed (table may not exist yet):", (userLookupError as Error).message);
       }
 
-      // Check if a nonce already exists for this address in the database
+      // Always rotate the nonce on issue. Reusing a stored nonce is a
+      // replay risk: a leaked sig-with-old-nonce stays valid until that row
+      // is consumed. Mint a fresh value every call.
+      const nonce = randomBytes(16).toString("hex");
       const existing = await db.nonce.findFirst({ where: { address } });
       if (existing) {
-        console.debug("[getNonce] Reusing existing nonce for address:", address);
-        return res.status(200).json({ nonce: existing.value });
+        await db.nonce.update({
+          where: { id: existing.id },
+          data: { value: nonce },
+        });
+      } else {
+        await db.nonce.create({
+          data: { address, value: nonce },
+        });
       }
-
-      const nonce = randomBytes(16).toString("hex");
-      await db.nonce.create({
-        data: {
-          address,
-          value: nonce,
-        },
-      });
-      console.debug("[getNonce] Created new nonce for address:", address);
       return res.status(200).json({ nonce });
     } catch (error) {
       console.error("[getNonce] Error:", error);
diff --git a/src/pages/api/v1/lookupMultisigWallet.ts b/src/pages/api/v1/lookupMultisigWallet.ts
index 35f5a9fb..34c3d7c0 100644
--- a/src/pages/api/v1/lookupMultisigWallet.ts
+++ b/src/pages/api/v1/lookupMultisigWallet.ts
@@ -31,9 +31,22 @@ export default async function handler(
       .json({ error: "Missing or invalid pubKeyHashes parameter" });
   }
 
-  const hashes = pubKeyHashes.split(",").map((s) => s.trim().toLowerCase());
-  console.log(hashes);
+  const hashes = pubKeyHashes
+    .split(",")
+    .map((s) => s.trim().toLowerCase())
+    .filter((s) => /^[0-9a-f]{56}$/.test(s));
+
+  if (hashes.length === 0) {
+    return res.status(400).json({ error: "No valid pubKeyHashes provided" });
+  }
+  if (hashes.length > 50) {
+    return res.status(400).json({ error: "Too many pubKeyHashes (max 50)" });
+  }
+
   const networkId = parseInt(network as string, 10);
+  if (networkId !== 0 && networkId !== 1) {
+    return res.status(400).json({ error: "Invalid network (expected 0 or 1)" });
+  }
 
   const provider = getProvider(networkId);
 
diff --git a/src/pages/api/v1/og.ts b/src/pages/api/v1/og.ts
index 9d5089fc..339bfe95 100644
--- a/src/pages/api/v1/og.ts
+++ b/src/pages/api/v1/og.ts
@@ -1,6 +1,134 @@
 import type { NextApiRequest, NextApiResponse } from "next";
+import { promises as dns } from "dns";
+import net from "net";
+import { env } from "@/env";
+
+const DEFAULT_ALLOWED_HOSTS = [
+  "github.com",
+  "www.github.com",
+  "twitter.com",
+  "x.com",
+  "youtube.com",
+  "www.youtube.com",
+  "cardano.org",
+  "www.cardano.org",
+  "meshjs.dev",
+  "www.meshjs.dev",
+];
+
+const MAX_BYTES = 1024 * 1024;
+const FETCH_TIMEOUT_MS = 5000;
+
+function loadAllowedHosts(): { hosts: Set<string>; wildcard: boolean } {
+  const raw = env.OG_ALLOWED_HOSTS?.trim();
+  if (!raw) {
+    return { hosts: new Set(DEFAULT_ALLOWED_HOSTS), wildcard: false };
+  }
+  if (raw === "*") {
+    return { hosts: new Set(), wildcard: true };
+  }
+  const list = raw
+    .split(",")
+    .map((h) => h.trim().toLowerCase())
+    .filter((h) => h.length > 0);
+  return { hosts: new Set(list), wildcard: false };
+}
+
+function isPrivateIPv4(ip: string): boolean {
+  const parts = ip.split(".").map(Number);
+  if (parts.length !== 4 || parts.some((p) => Number.isNaN(p) || p < 0 || p > 255)) {
+    return true;
+  }
+  const [a, b] = parts as [number, number, number, number];
+  if (a === 10) return true;
+  if (a === 127) return true;
+  if (a === 0) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 100 && b >= 64 && b <= 127) return true;
+  if (a >= 224) return true;
+  return false;
+}
+
+function isPrivateIPv6(ip: string): boolean {
+  const lower = ip.toLowerCase();
+  if (lower === "::" || lower === "::1") return true;
+  if (lower.startsWith("fc") || lower.startsWith("fd")) return true;
+  if (lower.startsWith("fe80")) return true;
+  if (lower.startsWith("ff")) return true;
+  if (lower.startsWith("::ffff:")) {
+    const v4 = lower.slice(7);
+    if (net.isIPv4(v4)) return isPrivateIPv4(v4);
+  }
+  return false;
+}
+
+function isPrivateAddress(ip: string): boolean {
+  if (net.isIPv4(ip)) return isPrivateIPv4(ip);
+  if (net.isIPv6(ip)) return isPrivateIPv6(ip);
+  return true;
+}
+
+async function assertSafeHost(hostname: string): Promise<void> {
+  if (net.isIP(hostname)) {
+    if (isPrivateAddress(hostname)) {
+      throw new Error("Blocked: private/loopback address");
+    }
+    return;
+  }
+  const records = await dns.lookup(hostname, { all: true });
+  if (records.length === 0) {
+    throw new Error("Blocked: DNS resolution failed");
+  }
+  for (const r of records) {
+    if (isPrivateAddress(r.address)) {
+      throw new Error("Blocked: resolves to private/loopback address");
+    }
+  }
+}
+
+async function fetchCapped(target: string): Promise<string> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const response = await fetch(target, {
+      method: "GET",
+      redirect: "manual",
+      signal: controller.signal,
+      headers: { "user-agent": "MeshMultisigOGFetcher/1.0" },
+    });
+    if (response.status >= 300 && response.status < 400) {
+      throw new Error("Blocked: redirect not followed");
+    }
+    if (!response.ok) {
+      throw new Error(`Upstream ${response.status}`);
+    }
+    const reader = response.body?.getReader();
+    if (!reader) {
+      const text = await response.text();
+      return text.length > MAX_BYTES ? text.slice(0, MAX_BYTES) : text;
+    }
+    const decoder = new TextDecoder();
+    let received = 0;
+    let html = "";
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      received += value.byteLength;
+      if (received > MAX_BYTES) {
+        await reader.cancel();
+        break;
+      }
+      html += decoder.decode(value, { stream: true });
+    }
+    html += decoder.decode();
+    return html;
+  } finally {
+    clearTimeout(timer);
+  }
+}
 
-// Simple OG metadata extractor using fetch + regex fallbacks
 export default async function handler(req: NextApiRequest, res: NextApiResponse) {
   const { url } = req.query;
   if (typeof url !== "string") {
@@ -8,9 +136,36 @@ export default async function handler(req: NextApiRequest, res: NextApiResponse)
     return;
   }
 
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    res.status(400).json({ error: "Invalid url" });
+    return;
+  }
+
+  if (parsed.protocol !== "https:") {
+    res.status(400).json({ error: "Only https URLs are allowed" });
+    return;
+  }
+
+  const { hosts, wildcard } = loadAllowedHosts();
+  const host = parsed.hostname.toLowerCase();
+  if (!wildcard && !hosts.has(host)) {
+    res.status(400).json({ error: "Host not allowed" });
+    return;
+  }
+
   try {
-    const response = await fetch(url, { method: "GET" });
-    const html = await response.text();
+    await assertSafeHost(host);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : "Blocked";
+    res.status(400).json({ error: msg });
+    return;
+  }
+
+  try {
+    const html = await fetchCapped(parsed.toString());
 
     const extract = (property: string, nameFallback?: string) => {
       const ogRegex = new RegExp(`<meta[^>]+property=["']${property}["'][^>]+content=["']([^"']+)["']`, "i");
@@ -39,4 +194,3 @@ export default async function handler(req: NextApiRequest, res: NextApiResponse)
     res.status(500).json({ error: errorMessage });
   }
 }
-
diff --git a/src/pages/api/v1/submitDatum.ts b/src/pages/api/v1/submitDatum.ts
index 48f90d5c..2e620918 100644
--- a/src/pages/api/v1/submitDatum.ts
+++ b/src/pages/api/v1/submitDatum.ts
@@ -116,7 +116,7 @@ export default async function handler(
       data: {
         walletId,
         payload: datum,
-        signatures: [`signature: ${sig.signature}, key: ${sig.key}`],
+        signatures: [JSON.stringify({ signature: sig.signature, key: sig.key })],
         signedAddresses: [address],
         rejectedAddresses: [],
         description,
diff --git a/src/server/api/auth.ts b/src/server/api/auth.ts
new file mode 100644
index 00000000..769e2f75
--- /dev/null
+++ b/src/server/api/auth.ts
@@ -0,0 +1,105 @@
+/**
+ * Shared auth helpers for tRPC routers.
+ *
+ * Consolidates `requireSessionAddress` and wallet-access checks that previously
+ * lived as near-duplicates in every router file. Centralizing them ensures:
+ * - one source of truth for the session-narrowing logic
+ * - one place to extend (e.g. add audit emit on FORBIDDEN)
+ * - future signer-table migrations only touch one helper
+ */
+
+import { TRPCError } from "@trpc/server";
+import type { AuthCtx } from "@/server/api/trpc";
+
+export const requireSessionAddress = (ctx: AuthCtx): string => {
+  const address = ctx.session?.user?.id ?? ctx.sessionAddress;
+  if (!address) {
+    throw new TRPCError({ code: "UNAUTHORIZED" });
+  }
+  return address;
+};
+
+/**
+ * Resolves the set of wallet addresses authorized in the current session.
+ * Prefers `sessionWallets` (multi-wallet auth) and falls back to the single
+ * `sessionAddress`/`session.user.id`. Returns `[]` when no session.
+ */
+export const getSessionAddresses = (ctx: AuthCtx): string[] => {
+  const sessionWallets = Array.isArray(ctx.sessionWallets) ? ctx.sessionWallets : [];
+  if (sessionWallets.length > 0) {
+    return sessionWallets;
+  }
+  const single = ctx.session?.user?.id ?? ctx.sessionAddress;
+  return single ? [single] : [];
+};
+
+/**
+ * Asserts that the caller can access the given wallet (signer or owner).
+ * Looks up the wallet in the `wallet` table and validates membership via
+ * `signersAddresses` or exact-match `ownerAddress`.
+ *
+ * Pass `requester` to override the session-derived address(es) — useful for
+ * routers that accept an explicit `requesterAddress` input parameter.
+ *
+ * Throws NOT_FOUND if the wallet doesn't exist, FORBIDDEN if not authorized.
+ */
+export const assertWalletAccess = async (
+  ctx: AuthCtx,
+  walletId: string,
+  requester?: string | string[],
+) => {
+  const wallet = await ctx.db.wallet.findUnique({ where: { id: walletId } });
+  if (!wallet) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Wallet not found" });
+  }
+
+  const requesters: string[] = requester
+    ? Array.isArray(requester)
+      ? requester
+      : [requester]
+    : [];
+  const sessionAddresses = getSessionAddresses(ctx);
+  const candidates = requesters.length > 0 ? [...requesters, ...sessionAddresses] : sessionAddresses;
+
+  if (candidates.length === 0) {
+    throw new TRPCError({ code: "UNAUTHORIZED" });
+  }
+
+  const authorized = candidates.some((addr) => {
+    const isSigner =
+      Array.isArray(wallet.signersAddresses) && wallet.signersAddresses.includes(addr);
+    const isOwner = wallet.ownerAddress === addr;
+    return isSigner || isOwner;
+  });
+
+  if (!authorized) {
+    throw new TRPCError({ code: "FORBIDDEN", message: "Not authorized for this wallet" });
+  }
+
+  return wallet;
+};
+
+/**
+ * Stricter variant: only the wallet owner (exact-match `ownerAddress`) passes.
+ * Used for ownership transfers, deletions, and other privileged operations.
+ */
+export const assertWalletOwner = async (
+  ctx: AuthCtx,
+  walletId: string,
+  requester?: string,
+) => {
+  const wallet = await ctx.db.wallet.findUnique({ where: { id: walletId } });
+  if (!wallet) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Wallet not found" });
+  }
+  const sessionAddresses = getSessionAddresses(ctx);
+  const candidates = requester ? [requester, ...sessionAddresses] : sessionAddresses;
+  if (candidates.length === 0) {
+    throw new TRPCError({ code: "UNAUTHORIZED" });
+  }
+  const isOwner = candidates.some((addr) => wallet.ownerAddress === addr);
+  if (!isOwner) {
+    throw new TRPCError({ code: "FORBIDDEN", message: "Only the wallet owner can perform this action" });
+  }
+  return wallet;
+};
diff --git a/src/server/api/routers/auth.ts b/src/server/api/routers/auth.ts
index a7ba0b04..e2fa9d4e 100644
--- a/src/server/api/routers/auth.ts
+++ b/src/server/api/routers/auth.ts
@@ -6,13 +6,13 @@ export const authRouter = createTRPCRouter({
     .input(z.object({ address: z.string().min(1) }))
     .query(async ({ ctx, input }) => {
       // Use wallet-session data already decoded into the tRPC context
-      const wallets: string[] = (ctx as any).sessionWallets ?? [];
+      const wallets: string[] = ctx.sessionWallets ?? [];
       const authorized = wallets.includes(input.address);
 
       return {
         authorized,
         wallets,
-        primaryWallet: (ctx as any).primaryWallet ?? null,
+        primaryWallet: ctx.primaryWallet ?? null,
       };
     }),
 });
diff --git a/src/server/api/routers/ballot.ts b/src/server/api/routers/ballot.ts
index c5fc323c..f6bf3fee 100644
--- a/src/server/api/routers/ballot.ts
+++ b/src/server/api/routers/ballot.ts
@@ -1,10 +1,11 @@
 import { z } from "zod";
 import { TRPCError } from "@trpc/server";
 import { createTRPCRouter, protectedProcedure } from "@/server/api/trpc";
+import type { AuthCtx } from "@/server/api/trpc";
 import { isValidChoice } from "@/lib/governance";
 
-const getSessionAddresses = (ctx: any): string[] => {
-  const sessionWallets: string[] = (ctx as any).sessionWallets ?? [];
+const getSessionAddresses = (ctx: AuthCtx): string[] => {
+  const sessionWallets: string[] = ctx.sessionWallets ?? [];
   if (Array.isArray(sessionWallets) && sessionWallets.length > 0) {
     return sessionWallets;
   }
@@ -12,7 +13,7 @@ const getSessionAddresses = (ctx: any): string[] => {
   return single ? [single] : [];
 };
 
-const assertWalletAccess = async (ctx: any, walletId: string) => {
+const assertWalletAccess = async (ctx: AuthCtx, walletId: string) => {
   const wallet = await ctx.db.wallet.findUnique({ where: { id: walletId } });
   if (!wallet) {
     throw new TRPCError({ code: "NOT_FOUND", message: "Wallet not found" });
@@ -26,7 +27,7 @@ const assertWalletAccess = async (ctx: any, walletId: string) => {
   const authorized = addresses.some((addr) => {
     const isSigner =
       Array.isArray(wallet.signersAddresses) && wallet.signersAddresses.includes(addr);
-    const isOwner = wallet.ownerAddress === addr || wallet.ownerAddress === "all";
+    const isOwner = wallet.ownerAddress === addr;
     return isSigner || isOwner;
   });
 
diff --git a/src/server/api/routers/bot.ts b/src/server/api/routers/bot.ts
index 62629839..2957b7cc 100644
--- a/src/server/api/routers/bot.ts
+++ b/src/server/api/routers/bot.ts
@@ -4,6 +4,7 @@ import { createTRPCRouter, protectedProcedure } from "@/server/api/trpc";
 import { BOT_SCOPES, parseScope, type BotScope } from "@/lib/auth/botKey";
 import { ClaimError, performClaim } from "@/lib/auth/claimBot";
 import { BotWalletRole } from "@prisma/client";
+import { audit } from "@/lib/observability/audit";
 
 type SessionAddressContext = {
   primaryWallet?: string | null;
@@ -167,10 +168,12 @@ export const botRouter = createTRPCRouter({
       const wallet = await ctx.db.wallet.findUnique({ where: { id: input.walletId } });
       if (!wallet) throw new TRPCError({ code: "NOT_FOUND", message: "Wallet not found" });
       const ownerAddress = wallet.ownerAddress ?? null;
-      const isOwner =
-        ownerAddress !== null &&
-        (ownerAddress === "all" || ownerAddress === requester);
-      if (!isOwner) {
+      const isOwner = ownerAddress !== null && ownerAddress === requester;
+      const isTeamSigner =
+        ownerAddress === "all" &&
+        Array.isArray(wallet.signersAddresses) &&
+        wallet.signersAddresses.includes(requester);
+      if (!isOwner && !isTeamSigner) {
         throw new TRPCError({ code: "FORBIDDEN", message: "Only the wallet owner can grant bot access" });
       }
 
@@ -198,6 +201,16 @@ export const botRouter = createTRPCRouter({
           role: input.role,
         },
       });
+      void audit(ctx.db, {
+        actorAddress: requester,
+        actorType: "user",
+        action: "bot.access_grant",
+        resourceType: "wallet",
+        resourceId: input.walletId,
+        ip: ctx.ip ?? null,
+        outcome: "success",
+        metadata: { botId: input.botId, role: input.role },
+      });
       return { ok: true };
     }),
 
@@ -211,15 +224,27 @@ export const botRouter = createTRPCRouter({
       const wallet = await ctx.db.wallet.findUnique({ where: { id: input.walletId } });
       if (!wallet) throw new TRPCError({ code: "NOT_FOUND", message: "Wallet not found" });
       const ownerAddress = wallet.ownerAddress ?? null;
-      const isOwner =
-        ownerAddress !== null &&
-        (ownerAddress === "all" || ownerAddress === requester);
-      if (!isOwner) {
+      const isOwner = ownerAddress !== null && ownerAddress === requester;
+      const isTeamSigner =
+        ownerAddress === "all" &&
+        Array.isArray(wallet.signersAddresses) &&
+        wallet.signersAddresses.includes(requester);
+      if (!isOwner && !isTeamSigner) {
         throw new TRPCError({ code: "FORBIDDEN", message: "Only the wallet owner can revoke bot access" });
       }
       await ctx.db.walletBotAccess.deleteMany({
         where: { walletId: input.walletId, botId: input.botId },
       });
+      void audit(ctx.db, {
+        actorAddress: requester,
+        actorType: "user",
+        action: "bot.access_revoke",
+        resourceType: "wallet",
+        resourceId: input.walletId,
+        ip: ctx.ip ?? null,
+        outcome: "success",
+        metadata: { botId: input.botId },
+      });
       return { ok: true };
     }),
 
@@ -233,10 +258,12 @@ export const botRouter = createTRPCRouter({
       const wallet = await ctx.db.wallet.findUnique({ where: { id: input.walletId } });
       if (!wallet) throw new TRPCError({ code: "NOT_FOUND", message: "Wallet not found" });
       const ownerAddress = wallet.ownerAddress ?? null;
-      const isOwner =
-        ownerAddress !== null &&
-        (ownerAddress === "all" || ownerAddress === requester);
-      if (!isOwner) {
+      const isOwner = ownerAddress !== null && ownerAddress === requester;
+      const isTeamSigner =
+        ownerAddress === "all" &&
+        Array.isArray(wallet.signersAddresses) &&
+        wallet.signersAddresses.includes(requester);
+      if (!isOwner && !isTeamSigner) {
         throw new TRPCError({ code: "FORBIDDEN", message: "Only the wallet owner can list bot access" });
       }
       return ctx.db.walletBotAccess.findMany({
diff --git a/src/server/api/routers/contacts.ts b/src/server/api/routers/contacts.ts
index 71d46607..c12b7ca3 100644
--- a/src/server/api/routers/contacts.ts
+++ b/src/server/api/routers/contacts.ts
@@ -2,15 +2,16 @@ import { TRPCError } from "@trpc/server";
 import { z } from "zod";
 
 import { createTRPCRouter, protectedProcedure } from "@/server/api/trpc";
+import type { AuthCtx } from "@/server/api/trpc";
 
-const getSessionAddresses = (ctx: any): string[] => {
-  const sessionWallets: string[] = (ctx as any).sessionWallets ?? [];
+const getSessionAddresses = (ctx: AuthCtx): string[] => {
+  const sessionWallets: string[] = ctx.sessionWallets ?? [];
   if (sessionWallets.length > 0) return sessionWallets;
   const single = ctx.sessionAddress;
   return single ? [single] : [];
 };
 
-const assertWalletAccess = async (ctx: any, walletId: string) => {
+const assertWalletAccess = async (ctx: AuthCtx, walletId: string) => {
   const wallet = await ctx.db.wallet.findUnique({ where: { id: walletId } });
   if (!wallet) {
     throw new TRPCError({ code: "NOT_FOUND", message: "Wallet not found" });
@@ -24,7 +25,7 @@ const assertWalletAccess = async (ctx: any, walletId: string) => {
   const authorized = addresses.some((addr) => {
     const isSigner =
       Array.isArray(wallet.signersAddresses) && wallet.signersAddresses.includes(addr);
-    const isOwner = wallet.ownerAddress === addr || wallet.ownerAddress === "all";
+    const isOwner = wallet.ownerAddress === addr;
     return isSigner || isOwner;
   });
 
diff --git a/src/server/api/routers/migrations.ts b/src/server/api/routers/migrations.ts
index edae6366..512d017f 100644
--- a/src/server/api/routers/migrations.ts
+++ b/src/server/api/routers/migrations.ts
@@ -1,8 +1,9 @@
 import { TRPCError } from "@trpc/server";
 import { z } from "zod";
 import { createTRPCRouter, protectedProcedure } from "@/server/api/trpc";
+import type { AuthCtx } from "@/server/api/trpc";
 
-const requireSessionAddress = (ctx: any) => {
+const requireSessionAddress = (ctx: AuthCtx) => {
   const address = ctx.session?.user?.id ?? ctx.sessionAddress;
   if (!address) {
     throw new TRPCError({ code: "UNAUTHORIZED" });
@@ -10,7 +11,7 @@ const requireSessionAddress = (ctx: any) => {
   return address;
 };
 
-const assertMigrationOwner = async (ctx: any, migrationId: string, requester: string | string[]) => {
+const assertMigrationOwner = async (ctx: AuthCtx, migrationId: string, requester: string | string[]) => {
   const migration = await ctx.db.migration.findUnique({ where: { id: migrationId } });
   if (!migration) {
     throw new TRPCError({ code: "NOT_FOUND", message: "Migration not found" });
@@ -30,7 +31,7 @@ export const migrationRouter = createTRPCRouter({
   getPendingMigrations: protectedProcedure
     .input(z.object({ ownerAddress: z.string() }))
     .query(async ({ ctx, input }) => {
-      const sessionWallets: string[] = (ctx as any).sessionWallets ?? [];
+      const sessionWallets: string[] = ctx.sessionWallets ?? [];
       const addresses = sessionWallets.length
         ? sessionWallets
         : [requireSessionAddress(ctx)];
@@ -55,7 +56,7 @@ export const migrationRouter = createTRPCRouter({
     .input(z.object({ migrationId: z.string() }))
     .query(async ({ ctx, input }) => {
       // Check against sessionWallets array like getPendingMigrations does
-      const sessionWallets: string[] = (ctx as any).sessionWallets ?? [];
+      const sessionWallets: string[] = ctx.sessionWallets ?? [];
       const addresses = sessionWallets.length
         ? sessionWallets
         : [requireSessionAddress(ctx)];
@@ -72,7 +73,7 @@ export const migrationRouter = createTRPCRouter({
       migrationData: z.any().optional()
     }))
     .mutation(async ({ ctx, input }) => {
-      const sessionWallets: string[] = (ctx as any).sessionWallets ?? [];
+      const sessionWallets: string[] = ctx.sessionWallets ?? [];
       const addresses = sessionWallets.length
         ? sessionWallets
         : [requireSessionAddress(ctx)];
@@ -119,7 +120,7 @@ export const migrationRouter = createTRPCRouter({
     }))
     .mutation(async ({ ctx, input }) => {
       // Check against sessionWallets array like getPendingMigrations does
-      const sessionWallets: string[] = (ctx as any).sessionWallets ?? [];
+      const sessionWallets: string[] = ctx.sessionWallets ?? [];
       const addresses = sessionWallets.length
         ? sessionWallets
         : [requireSessionAddress(ctx)];
@@ -161,7 +162,7 @@ export const migrationRouter = createTRPCRouter({
     }))
     .mutation(async ({ ctx, input }) => {
       // Check against sessionWallets array like getPendingMigrations does
-      const sessionWallets: string[] = (ctx as any).sessionWallets ?? [];
+      const sessionWallets: string[] = ctx.sessionWallets ?? [];
       const addresses = sessionWallets.length
         ? sessionWallets
         : [requireSessionAddress(ctx)];
@@ -183,7 +184,7 @@ export const migrationRouter = createTRPCRouter({
     .input(z.object({ migrationId: z.string() }))
     .mutation(async ({ ctx, input }) => {
       // Check against sessionWallets array like getPendingMigrations does
-      const sessionWallets: string[] = (ctx as any).sessionWallets ?? [];
+      const sessionWallets: string[] = ctx.sessionWallets ?? [];
       const addresses = sessionWallets.length
         ? sessionWallets
         : [requireSessionAddress(ctx)];
@@ -202,7 +203,7 @@ export const migrationRouter = createTRPCRouter({
     .input(z.object({ migrationId: z.string() }))
     .mutation(async ({ ctx, input }) => {
       // Check against sessionWallets array like getPendingMigrations does
-      const sessionWallets: string[] = (ctx as any).sessionWallets ?? [];
+      const sessionWallets: string[] = ctx.sessionWallets ?? [];
       const addresses = sessionWallets.length
         ? sessionWallets
         : [requireSessionAddress(ctx)];
diff --git a/src/server/api/routers/proxy.ts b/src/server/api/routers/proxy.ts
index 864e0c56..c53b0f56 100644
--- a/src/server/api/routers/proxy.ts
+++ b/src/server/api/routers/proxy.ts
@@ -1,8 +1,9 @@
 import { TRPCError } from "@trpc/server";
 import { z } from "zod";
 import { createTRPCRouter, protectedProcedure } from "@/server/api/trpc";
+import type { AuthCtx } from "@/server/api/trpc";
 
-const requireSessionAddress = (ctx: any) => {
+const requireSessionAddress = (ctx: AuthCtx) => {
   const address = ctx.session?.user?.id ?? ctx.sessionAddress;
   if (!address) {
     throw new TRPCError({ code: "UNAUTHORIZED" });
@@ -11,7 +12,7 @@ const requireSessionAddress = (ctx: any) => {
 };
 
 const assertWalletAccess = async (
-  ctx: any,
+  ctx: AuthCtx,
   walletId: string,
   requester: string | string[],
 ) => {
@@ -20,7 +21,7 @@ const assertWalletAccess = async (
     throw new TRPCError({ code: "NOT_FOUND", message: "Wallet not found" });
   }
   const requesters = Array.isArray(requester) ? requester : [requester];
-  const sessionWallets: string[] = (ctx as any).sessionWallets ?? [];
+  const sessionWallets: string[] = ctx.sessionWallets ?? [];
   const allRequesters = [...requesters, ...sessionWallets];
   const isSigner =
     Array.isArray(wallet.signersAddresses) &&
@@ -32,7 +33,7 @@ const assertWalletAccess = async (
   return wallet;
 };
 
-const getUserIdForAddress = async (ctx: any, address: string) => {
+const getUserIdForAddress = async (ctx: AuthCtx, address: string) => {
   const user = await ctx.db.user.findUnique({ where: { address } });
   if (!user) {
     throw new TRPCError({ code: "NOT_FOUND", message: "User not found" });
@@ -41,7 +42,7 @@ const getUserIdForAddress = async (ctx: any, address: string) => {
 };
 
 const assertProxyAccess = async (
-  ctx: any,
+  ctx: AuthCtx,
   proxy: { walletId: string | null; userId: string | null },
   requesterAddresses: string[],
 ) => {
@@ -75,13 +76,13 @@ const assertProxyAccess = async (
   throw new TRPCError({ code: "FORBIDDEN", message: "Not authorized for this proxy" });
 };
 
-const getRequesterAddresses = (ctx: any): string[] => {
-  const sessionWallets: string[] = (ctx as any).sessionWallets ?? [];
+const getRequesterAddresses = (ctx: AuthCtx): string[] => {
+  const sessionWallets: string[] = ctx.sessionWallets ?? [];
   return sessionWallets.length ? sessionWallets : [requireSessionAddress(ctx)];
 };
 
 const assertWalletAccessForAnyAddress = async (
-  ctx: any,
+  ctx: AuthCtx,
   walletId: string,
   addresses: string[],
 ) => {
@@ -96,7 +97,7 @@ const assertWalletAccessForAnyAddress = async (
   throw new TRPCError({ code: "FORBIDDEN", message: "Not authorized for this wallet" });
 };
 
-const listActiveProxiesByUserAddress = async (ctx: any, userAddress: string) => {
+const listActiveProxiesByUserAddress = async (ctx: AuthCtx, userAddress: string) => {
   return ctx.db.$queryRaw<Array<{
     id: string;
     walletId: string | null;
@@ -119,7 +120,7 @@ const listActiveProxiesByUserAddress = async (ctx: any, userAddress: string) =>
 };
 
 const assertProxyManageAccess = async (
-  ctx: any,
+  ctx: AuthCtx,
   proxy: { walletId: string | null; userId: string | null },
   sessionAddress: string,
 ) => {
diff --git a/src/server/api/routers/signable.ts b/src/server/api/routers/signable.ts
index 5c5dce28..8b5bd21a 100644
--- a/src/server/api/routers/signable.ts
+++ b/src/server/api/routers/signable.ts
@@ -2,28 +2,8 @@ import { TRPCError } from "@trpc/server";
 import { z } from "zod";
 
 import { createTRPCRouter, protectedProcedure } from "@/server/api/trpc";
-
-const requireSessionAddress = (ctx: any) => {
-  const address = ctx.session?.user?.id ?? ctx.sessionAddress;
-  if (!address) {
-    throw new TRPCError({ code: "UNAUTHORIZED" });
-  }
-  return address;
-};
-
-const assertWalletAccess = async (ctx: any, walletId: string, requester: string) => {
-  const wallet = await ctx.db.wallet.findUnique({ where: { id: walletId } });
-  if (!wallet) {
-    throw new TRPCError({ code: "NOT_FOUND", message: "Wallet not found" });
-  }
-  const isSigner =
-    Array.isArray(wallet.signersAddresses) && wallet.signersAddresses.includes(requester);
-  const isOwner = wallet.ownerAddress === requester || wallet.ownerAddress === "all";
-  if (!isSigner && !isOwner) {
-    throw new TRPCError({ code: "FORBIDDEN", message: "Not authorized for this wallet" });
-  }
-  return wallet;
-};
+import { audit } from "@/lib/observability/audit";
+import { requireSessionAddress, assertWalletAccess } from "@/server/api/auth";
 
 export const signableRouter = createTRPCRouter({
   createSignable: protectedProcedure
@@ -72,7 +52,7 @@ export const signableRouter = createTRPCRouter({
         throw new TRPCError({ code: "NOT_FOUND", message: "Signable not found" });
       }
       await assertWalletAccess(ctx, signable.walletId, sessionAddress);
-      return ctx.db.signable.update({
+      const updated = await ctx.db.signable.update({
         where: {
           id: input.signableId,
         },
@@ -83,6 +63,30 @@ export const signableRouter = createTRPCRouter({
           state: input.state,
         },
       });
+      const justSigned = input.signedAddresses.includes(sessionAddress) &&
+        !signable.signedAddresses.includes(sessionAddress);
+      const justRejected = input.rejectedAddresses.includes(sessionAddress) &&
+        !signable.rejectedAddresses.includes(sessionAddress);
+      void audit(ctx.db, {
+        actorAddress: sessionAddress,
+        actorType: "user",
+        action: justRejected
+          ? "signable.reject"
+          : justSigned
+            ? "signable.sign"
+            : "signable.update",
+        resourceType: "signable",
+        resourceId: input.signableId,
+        ip: ctx.ip ?? null,
+        outcome: "success",
+        metadata: {
+          walletId: signable.walletId,
+          state: input.state,
+          signersCount: input.signedAddresses.length,
+          rejectionsCount: input.rejectedAddresses.length,
+        },
+      });
+      return updated;
     }),
 
   deleteSignable: protectedProcedure
@@ -94,11 +98,22 @@ export const signableRouter = createTRPCRouter({
         throw new TRPCError({ code: "NOT_FOUND", message: "Signable not found" });
       }
       await assertWalletAccess(ctx, signable.walletId, sessionAddress);
-      return ctx.db.signable.delete({
+      const deleted = await ctx.db.signable.delete({
         where: {
           id: input.signableId,
         },
       });
+      void audit(ctx.db, {
+        actorAddress: sessionAddress,
+        actorType: "user",
+        action: "signable.delete",
+        resourceType: "signable",
+        resourceId: input.signableId,
+        ip: ctx.ip ?? null,
+        outcome: "success",
+        metadata: { walletId: signable.walletId },
+      });
+      return deleted;
     }),
 
   // Read-only queries require authenticated session whose address is a signer/owner
diff --git a/src/server/api/routers/transactions.ts b/src/server/api/routers/transactions.ts
index aef26e7b..c260cb66 100644
--- a/src/server/api/routers/transactions.ts
+++ b/src/server/api/routers/transactions.ts
@@ -7,6 +7,8 @@ import { getProvider } from "@/utils/get-provider";
 import { addressToNetwork } from "@/utils/multisigSDK";
 
 import { createTRPCRouter, protectedProcedure } from "@/server/api/trpc";
+import { audit } from "@/lib/observability/audit";
+import { assertWalletAccess } from "@/server/api/auth";
 
 function toHex(bytes: Uint8Array): string {
   return Buffer.from(bytes).toString("hex");
@@ -20,40 +22,6 @@ function normalizeHex(value: string): string {
   return trimmed;
 }
 
-const getSessionAddresses = (ctx: any): string[] => {
-  const sessionWallets: string[] = (ctx as any).sessionWallets ?? [];
-  if (Array.isArray(sessionWallets) && sessionWallets.length > 0) {
-    return sessionWallets;
-  }
-  const single = ctx.session?.user?.id ?? ctx.sessionAddress;
-  return single ? [single] : [];
-};
-
-const assertWalletAccess = async (ctx: any, walletId: string) => {
-  const wallet = await ctx.db.wallet.findUnique({ where: { id: walletId } });
-  if (!wallet) {
-    throw new TRPCError({ code: "NOT_FOUND", message: "Wallet not found" });
-  }
-
-  const addresses = getSessionAddresses(ctx);
-  if (addresses.length === 0) {
-    throw new TRPCError({ code: "UNAUTHORIZED" });
-  }
-
-  const authorized = addresses.some((addr: string) => {
-    const isSigner =
-      Array.isArray(wallet.signersAddresses) && wallet.signersAddresses.includes(addr);
-    const isOwner = wallet.ownerAddress === addr || wallet.ownerAddress === "all";
-    return isSigner || isOwner;
-  });
-
-  if (!authorized) {
-    throw new TRPCError({ code: "FORBIDDEN", message: "Not authorized for this wallet" });
-  }
-
-  return wallet;
-};
-
 export const transactionRouter = createTRPCRouter({
   createTransaction: protectedProcedure
     .input(
@@ -69,7 +37,8 @@ export const transactionRouter = createTRPCRouter({
     )
     .mutation(async ({ ctx, input }) => {
       await assertWalletAccess(ctx, input.walletId);
-      return ctx.db.transaction.create({
+      const sessionAddress = ctx.session?.user?.id ?? ctx.sessionAddress ?? null;
+      const tx = await ctx.db.transaction.create({
         data: {
           walletId: input.walletId,
           txJson: input.txJson,
@@ -80,6 +49,22 @@ export const transactionRouter = createTRPCRouter({
           txHash: input.txHash,
         },
       });
+      void audit(ctx.db, {
+        actorAddress: sessionAddress,
+        actorType: "user",
+        action: "transaction.create",
+        resourceType: "transaction",
+        resourceId: tx.id,
+        ip: ctx.ip ?? null,
+        outcome: "success",
+        metadata: {
+          walletId: input.walletId,
+          state: input.state,
+          txHash: input.txHash ?? null,
+          initialSigners: input.signedAddresses.length,
+        },
+      });
+      return tx;
     }),
 
   updateTransaction: protectedProcedure
@@ -99,7 +84,8 @@ export const transactionRouter = createTRPCRouter({
         throw new TRPCError({ code: "NOT_FOUND", message: "Transaction not found" });
       }
       await assertWalletAccess(ctx, tx.walletId);
-      return ctx.db.transaction.update({
+      const sessionAddress = ctx.session?.user?.id ?? ctx.sessionAddress ?? null;
+      const updated = await ctx.db.transaction.update({
         where: {
           id: input.transactionId,
         },
@@ -111,6 +97,38 @@ export const transactionRouter = createTRPCRouter({
           txHash: input.txHash,
         },
       });
+      const justSigned =
+        sessionAddress !== null &&
+        input.signedAddresses.includes(sessionAddress) &&
+        !tx.signedAddresses.includes(sessionAddress);
+      const justRejected =
+        sessionAddress !== null &&
+        input.rejectedAddresses.includes(sessionAddress) &&
+        !tx.rejectedAddresses.includes(sessionAddress);
+      const submitted = !tx.txHash && Boolean(input.txHash);
+      void audit(ctx.db, {
+        actorAddress: sessionAddress,
+        actorType: "user",
+        action: submitted
+          ? "transaction.submit"
+          : justRejected
+            ? "transaction.reject"
+            : justSigned
+              ? "transaction.sign"
+              : "transaction.update",
+        resourceType: "transaction",
+        resourceId: input.transactionId,
+        ip: ctx.ip ?? null,
+        outcome: "success",
+        metadata: {
+          walletId: tx.walletId,
+          state: input.state,
+          signersCount: input.signedAddresses.length,
+          rejectionsCount: input.rejectedAddresses.length,
+          txHash: input.txHash ?? null,
+        },
+      });
+      return updated;
     }),
 
   deleteTransaction: protectedProcedure
@@ -121,11 +139,23 @@ export const transactionRouter = createTRPCRouter({
         throw new TRPCError({ code: "NOT_FOUND", message: "Transaction not found" });
       }
       await assertWalletAccess(ctx, tx.walletId);
-      return ctx.db.transaction.delete({
+      const sessionAddress = ctx.session?.user?.id ?? ctx.sessionAddress ?? null;
+      const deleted = await ctx.db.transaction.delete({
         where: {
           id: input.transactionId,
         },
       });
+      void audit(ctx.db, {
+        actorAddress: sessionAddress,
+        actorType: "user",
+        action: "transaction.delete",
+        resourceType: "transaction",
+        resourceId: input.transactionId,
+        ip: ctx.ip ?? null,
+        outcome: "success",
+        metadata: { walletId: tx.walletId },
+      });
+      return deleted;
     }),
 
   // Read-only queries require authenticated session whose address is a signer/owner
@@ -489,7 +519,8 @@ export const transactionRouter = createTRPCRouter({
       };
 
       // Create pending transaction
-      return await ctx.db.transaction.create({
+      const sessionAddress = ctx.session?.user?.id ?? ctx.sessionAddress ?? null;
+      const created = await ctx.db.transaction.create({
         data: {
           walletId: input.walletId,
           txJson: JSON.stringify(txJson),
@@ -500,5 +531,19 @@ export const transactionRouter = createTRPCRouter({
           description: input.description || "Imported transaction",
         },
       });
+      void audit(ctx.db, {
+        actorAddress: sessionAddress,
+        actorType: "user",
+        action: "transaction.import",
+        resourceType: "transaction",
+        resourceId: created.id,
+        ip: ctx.ip ?? null,
+        outcome: "success",
+        metadata: {
+          walletId: input.walletId,
+          existingSigners: signedAddresses.length,
+        },
+      });
+      return created;
     }),
 });
diff --git a/src/server/api/routers/users.ts b/src/server/api/routers/users.ts
index 081b917e..4d2d8dca 100644
--- a/src/server/api/routers/users.ts
+++ b/src/server/api/routers/users.ts
@@ -2,8 +2,9 @@ import { TRPCError } from "@trpc/server";
 import { z } from "zod";
 
 import { createTRPCRouter, protectedProcedure, publicProcedure } from "@/server/api/trpc";
+import type { AuthCtx } from "@/server/api/trpc";
 
-const requireSessionAddress = (ctx: any) => {
+const requireSessionAddress = (ctx: AuthCtx) => {
   const address = ctx.session?.user?.id ?? ctx.sessionAddress;
   if (!address) {
     throw new TRPCError({ code: "UNAUTHORIZED" });
@@ -22,8 +23,10 @@ export const userRouter = createTRPCRouter({
       });
     }),
 
-  // Keep createUser public for onboarding flows, but bind address when session exists
-  createUser: publicProcedure
+  // Onboarding upsert. Authenticated only — the session address must match
+  // the address being created/updated to prevent any unauthenticated caller
+  // from creating User rows or overwriting another user's stake/nostr/drep keys.
+  createUser: protectedProcedure
     .input(
       z.object({
         address: z.string().min(1, "address required"),
@@ -34,6 +37,13 @@ export const userRouter = createTRPCRouter({
       }),
     )
     .mutation(async ({ ctx, input }) => {
+      const sessionAddress = requireSessionAddress(ctx);
+      if (sessionAddress !== input.address) {
+        throw new TRPCError({
+          code: "FORBIDDEN",
+          message: "Cannot create or modify a user other than yourself",
+        });
+      }
       return ctx.db.user.upsert({
         where: {
           address: input.address,
@@ -134,10 +144,10 @@ export const userRouter = createTRPCRouter({
       });
     }),
 
-  getDiscordIds: publicProcedure
+  getDiscordIds: protectedProcedure
     .input(
       z.object({
-        addresses: z.array(z.string().min(1)).min(1),
+        addresses: z.array(z.string().min(1)).min(1).max(50),
       }),
     )
     .query(async ({ ctx, input }) => {
@@ -165,7 +175,7 @@ export const userRouter = createTRPCRouter({
       );
     }),
 
-  getUserDiscordId: publicProcedure
+  getUserDiscordId: protectedProcedure
     .input(z.object({ address: z.string().min(1, "address required") }))
     .query(async ({ ctx, input }) => {
       const user = await ctx.db.user.findUnique({
diff --git a/src/server/api/routers/wallets.ts b/src/server/api/routers/wallets.ts
index 98d56126..340ebf91 100644
--- a/src/server/api/routers/wallets.ts
+++ b/src/server/api/routers/wallets.ts
@@ -2,10 +2,12 @@ import { TRPCError } from "@trpc/server";
 import { z } from "zod";
 
 import { createTRPCRouter, protectedProcedure, publicProcedure } from "@/server/api/trpc";
+import type { AuthCtx } from "@/server/api/trpc";
 import type { RawImportBodies } from "@/types/wallet";
 import { Prisma } from "@prisma/client";
+import { audit } from "@/lib/observability/audit";
 
-const requireSessionAddress = (ctx: any) => {
+const requireSessionAddress = (ctx: AuthCtx) => {
   const address = ctx.session?.user?.id ?? ctx.sessionAddress;
   if (!address) {
     throw new TRPCError({ code: "UNAUTHORIZED" });
@@ -13,20 +15,20 @@ const requireSessionAddress = (ctx: any) => {
   return address;
 };
 
-const assertWalletAccess = async (ctx: any, walletId: string, requester: string | string[]) => {
+const assertWalletAccess = async (ctx: AuthCtx, walletId: string, requester: string | string[]) => {
   const wallet = await ctx.db.wallet.findUnique({ where: { id: walletId } });
   if (!wallet) {
     throw new TRPCError({ code: "NOT_FOUND", message: "Wallet not found" });
   }
 
   const requesters = Array.isArray(requester) ? requester : [requester];
-  const sessionWallets: string[] = (ctx as any).sessionWallets ?? [];
+  const sessionWallets: string[] = ctx.sessionWallets ?? [];
   const allRequesters = [...requesters, ...sessionWallets];
 
   const isSigner = allRequesters.some((addr) =>
     Array.isArray(wallet.signersAddresses) && wallet.signersAddresses.includes(addr)
   );
-  const isOwner = allRequesters.some((addr) => wallet.ownerAddress === addr || wallet.ownerAddress === "all");
+  const isOwner = allRequesters.some((addr) => wallet.ownerAddress === addr);
 
   if (!isSigner && !isOwner) {
     throw new TRPCError({ code: "FORBIDDEN", message: "Not a signer of this wallet" });
@@ -36,7 +38,7 @@ const assertWalletAccess = async (ctx: any, walletId: string, requester: string
 };
 
 // Check if user is the owner of the wallet
-const assertNewWalletOwnerAccess = async (ctx: any, walletId: string, requester: string) => {
+const assertNewWalletOwnerAccess = async (ctx: AuthCtx, walletId: string, requester: string) => {
   const wallet = await ctx.db.newWallet.findUnique({ where: { id: walletId } });
   if (!wallet) {
     throw new TRPCError({ code: "NOT_FOUND", message: "Wallet not found" });
@@ -46,7 +48,7 @@ const assertNewWalletOwnerAccess = async (ctx: any, walletId: string, requester:
   const isOwner = wallet.ownerAddress === requester;
   
   // Also check if ownerAddress is in sessionWallets (user might have multiple authorized wallets)
-  const sessionWallets: string[] = (ctx as any).sessionWallets ?? [];
+  const sessionWallets: string[] = ctx.sessionWallets ?? [];
   const isOwnerViaSession = sessionWallets.includes(wallet.ownerAddress);
   
   if (!isOwner && !isOwnerViaSession) {
@@ -56,7 +58,7 @@ const assertNewWalletOwnerAccess = async (ctx: any, walletId: string, requester:
 };
 
 // Check if user is a signer or owner (for read access)
-const assertNewWalletSignerAccess = async (ctx: any, walletId: string, requester: string) => {
+const assertNewWalletSignerAccess = async (ctx: AuthCtx, walletId: string, requester: string) => {
   const wallet = await ctx.db.newWallet.findUnique({ where: { id: walletId } });
   if (!wallet) {
     throw new TRPCError({ code: "NOT_FOUND", message: "Wallet not found" });
@@ -66,7 +68,7 @@ const assertNewWalletSignerAccess = async (ctx: any, walletId: string, requester
   const isOwner = wallet.ownerAddress === requester;
   
   // Also check if ownerAddress is in sessionWallets (user might have multiple authorized wallets)
-  const sessionWallets: string[] = (ctx as any).sessionWallets ?? [];
+  const sessionWallets: string[] = ctx.sessionWallets ?? [];
   const isOwnerViaSession = sessionWallets.includes(wallet.ownerAddress);
   
   if (isOwner || isOwnerViaSession) {
@@ -88,7 +90,7 @@ const assertNewWalletSignerAccess = async (ctx: any, walletId: string, requester
 };
 
 // Check if user can read the wallet (signer or owner)
-const assertNewWalletAccess = async (ctx: any, walletId: string, requester: string) => {
+const assertNewWalletAccess = async (ctx: AuthCtx, walletId: string, requester: string) => {
   return assertNewWalletSignerAccess(ctx, walletId, requester);
 };
 
@@ -97,7 +99,7 @@ export const walletRouter = createTRPCRouter({
   getUserWallets: publicProcedure
     .input(z.object({ address: z.string() }))
     .query(async ({ ctx, input }) => {
-      const sessionWallets: string[] = (ctx as any).sessionWallets ?? [];
+      const sessionWallets: string[] = ctx.sessionWallets ?? [];
       const addresses = sessionWallets.length
         ? sessionWallets
         : ctx.sessionAddress
@@ -121,18 +123,22 @@ export const walletRouter = createTRPCRouter({
   getWallet: publicProcedure
     .input(z.object({ address: z.string(), walletId: z.string() }))
     .query(async ({ ctx, input }) => {
-      const sessionWallets: string[] = (ctx as any).sessionWallets ?? [];
+      const sessionWallets: string[] = ctx.sessionWallets ?? [];
       const addresses = sessionWallets.length
         ? sessionWallets
         : ctx.sessionAddress
           ? [ctx.sessionAddress]
           : [];
-      // If user has an active session, validate that the requested address is authorized
-      // Throw error if address doesn't match (security: prevent unauthorized access)
-      if (addresses.length > 0 && !addresses.includes(input.address)) {
+
+      if (addresses.length === 0) {
+        throw new TRPCError({ code: "UNAUTHORIZED" });
+      }
+
+      if (!addresses.includes(input.address)) {
         throw new TRPCError({ code: "FORBIDDEN", message: "Address mismatch" });
       }
-      return ctx.db.wallet.findUnique({
+
+      const wallet = await ctx.db.wallet.findUnique({
         where: {
           id: input.walletId,
           signersAddresses: {
@@ -140,6 +146,19 @@ export const walletRouter = createTRPCRouter({
           },
         },
       });
+
+      if (!wallet) {
+        throw new TRPCError({ code: "FORBIDDEN", message: "Not a signer of this wallet" });
+      }
+
+      if (
+        !Array.isArray(wallet.signersAddresses) ||
+        !wallet.signersAddresses.includes(input.address)
+      ) {
+        throw new TRPCError({ code: "FORBIDDEN", message: "Not a signer of this wallet" });
+      }
+
+      return wallet;
     }),
 
   createWallet: protectedProcedure
@@ -160,7 +179,7 @@ export const walletRouter = createTRPCRouter({
       }),
     )
     .mutation(async ({ ctx, input }) => {
-      requireSessionAddress(ctx);
+      const sessionAddress = requireSessionAddress(ctx);
       try {
         const numRequired = (input.type === "all" || input.type === "any") ? null : input.numRequiredSigners;
 
@@ -191,7 +210,23 @@ export const walletRouter = createTRPCRouter({
           ...(input.ownerAddress != null && { ownerAddress: input.ownerAddress }),
         };
 
-        return ctx.db.wallet.create({ data });
+        const wallet = await ctx.db.wallet.create({ data });
+        void audit(ctx.db, {
+          actorAddress: sessionAddress,
+          actorType: "user",
+          action: "wallet.create",
+          resourceType: "wallet",
+          resourceId: wallet.id,
+          ip: ctx.ip ?? null,
+          outcome: "success",
+          metadata: {
+            type: input.type,
+            numRequiredSigners: numRequired,
+            signerCount: input.signersAddresses.length,
+            ownerAddress: input.ownerAddress ?? null,
+          },
+        });
+        return wallet;
       } catch (error) {
         console.error("Error creating wallet:", error);
         throw error;
@@ -279,21 +314,18 @@ export const walletRouter = createTRPCRouter({
       });
     }),
 
-  getUserNewWallets: publicProcedure
+  getUserNewWallets: protectedProcedure
     .input(z.object({ address: z.string() }))
     .query(async ({ ctx, input }) => {
-      const sessionWallets: string[] = (ctx as any).sessionWallets ?? [];
+      const sessionWallets: string[] = ctx.sessionWallets ?? [];
       const addresses = sessionWallets.length
         ? sessionWallets
         : ctx.sessionAddress
           ? [ctx.sessionAddress]
           : [];
-      // If user has an active session, validate that the requested address is authorized
-      // Throw error if address doesn't match (security: prevent unauthorized access)
-      if (addresses.length > 0 && !addresses.includes(input.address)) {
+      if (!addresses.includes(input.address)) {
         throw new TRPCError({ code: "FORBIDDEN", message: "Address mismatch" });
       }
-      // Query new wallets owned by the user
       return ctx.db.newWallet.findMany({
         where: {
           ownerAddress: input.address,
@@ -301,21 +333,18 @@ export const walletRouter = createTRPCRouter({
       });
     }),
 
-  getUserNewWalletsNotOwner: publicProcedure
+  getUserNewWalletsNotOwner: protectedProcedure
     .input(z.object({ address: z.string() }))
     .query(async ({ ctx, input }) => {
-      const sessionWallets: string[] = (ctx as any).sessionWallets ?? [];
+      const sessionWallets: string[] = ctx.sessionWallets ?? [];
       const addresses = sessionWallets.length
         ? sessionWallets
         : ctx.sessionAddress
           ? [ctx.sessionAddress]
           : [];
-      // If user has an active session, validate that the requested address is authorized
-      // Throw error if address doesn't match (security: prevent unauthorized access)
-      if (addresses.length > 0 && !addresses.includes(input.address)) {
+      if (!addresses.includes(input.address)) {
         throw new TRPCError({ code: "FORBIDDEN", message: "Address mismatch" });
       }
-      // Query new wallets where user is a signer but not the owner
       return ctx.db.newWallet.findMany({
         where: {
           signersAddresses: {
@@ -357,7 +386,7 @@ export const walletRouter = createTRPCRouter({
     )
     .mutation(async ({ ctx, input }) => {
       const sessionAddress = requireSessionAddress(ctx);
-      const sessionWallets: string[] = (ctx as any).sessionWallets ?? [];
+      const sessionWallets: string[] = ctx.sessionWallets ?? [];
       
       // Allow ownerAddress to be either the sessionAddress or any address in sessionWallets
       const isAuthorized = 
@@ -368,7 +397,7 @@ export const walletRouter = createTRPCRouter({
         throw new TRPCError({ code: "FORBIDDEN", message: "Owner address mismatch" });
       }
       const numRequired = (input.scriptType === "all" || input.scriptType === "any") ? null : input.numRequiredSigners;
-      return ctx.db.newWallet.create({
+      const wallet = await ctx.db.newWallet.create({
         data: {
           name: input.name,
           description: input.description,
@@ -382,6 +411,22 @@ export const walletRouter = createTRPCRouter({
           scriptType: input.scriptType,
         } as any,
       });
+      void audit(ctx.db, {
+        actorAddress: sessionAddress,
+        actorType: "user",
+        action: "wallet.new_create",
+        resourceType: "newWallet",
+        resourceId: wallet.id,
+        ip: ctx.ip ?? null,
+        outcome: "success",
+        metadata: {
+          scriptType: input.scriptType ?? null,
+          numRequiredSigners: numRequired,
+          signerCount: input.signersAddresses.length,
+          ownerAddress: input.ownerAddress,
+        },
+      });
+      return wallet;
     }),
 
   updateNewWallet: protectedProcedure
@@ -526,9 +571,30 @@ export const walletRouter = createTRPCRouter({
 
       if (result.count === 0) {
         // Either already claimed, not eligible, or wallet not found
+        void audit(ctx.db, {
+          actorAddress: requester,
+          actorType: "user",
+          action: "wallet.owner_claim",
+          resourceType: "newWallet",
+          resourceId: input.walletId,
+          ip: ctx.ip ?? null,
+          outcome: "denied",
+          reason: "Already claimed, not eligible, or wallet not found",
+          metadata: { requestedOwner: input.ownerAddress },
+        });
         return ctx.db.newWallet.findUnique({ where: { id: input.walletId } });
       }
 
+      void audit(ctx.db, {
+        actorAddress: requester,
+        actorType: "user",
+        action: "wallet.owner_claim",
+        resourceType: "newWallet",
+        resourceId: input.walletId,
+        ip: ctx.ip ?? null,
+        outcome: "success",
+        metadata: { newOwner: input.ownerAddress, previousOwner: "all" },
+      });
       return ctx.db.newWallet.findUnique({ where: { id: input.walletId } });
     }),
 
@@ -538,11 +604,21 @@ export const walletRouter = createTRPCRouter({
       const sessionAddress = requireSessionAddress(ctx);
       // Only owners can delete the wallet
       await assertNewWalletOwnerAccess(ctx, input.walletId, sessionAddress);
-      return ctx.db.newWallet.delete({
+      const deleted = await ctx.db.newWallet.delete({
         where: {
           id: input.walletId,
         },
       });
+      void audit(ctx.db, {
+        actorAddress: sessionAddress,
+        actorType: "user",
+        action: "wallet.new_delete",
+        resourceType: "newWallet",
+        resourceId: input.walletId,
+        ip: ctx.ip ?? null,
+        outcome: "success",
+      });
+      return deleted;
     }),
 
   updateWalletClarityApiKey: protectedProcedure
@@ -586,7 +662,7 @@ export const walletRouter = createTRPCRouter({
   clearMigrationTarget: protectedProcedure
     .input(z.object({ walletId: z.string() }))
     .mutation(async ({ ctx, input }) => {
-      const sessionWallets: string[] = (ctx as any).sessionWallets ?? [];
+      const sessionWallets: string[] = ctx.sessionWallets ?? [];
       const sessionAddress = requireSessionAddress(ctx);
       const requesters = sessionWallets.length > 0 ? sessionWallets : [sessionAddress];
       await assertWalletAccess(ctx, input.walletId, requesters);
@@ -656,11 +732,11 @@ export const walletRouter = createTRPCRouter({
   archiveWallet: protectedProcedure
     .input(z.object({ walletId: z.string() }))
     .mutation(async ({ ctx, input }) => {
-      const sessionWallets: string[] = (ctx as any).sessionWallets ?? [];
+      const sessionWallets: string[] = ctx.sessionWallets ?? [];
       const sessionAddress = requireSessionAddress(ctx);
       const requesters = sessionWallets.length > 0 ? sessionWallets : [sessionAddress];
       await assertWalletAccess(ctx, input.walletId, requesters);
-      return ctx.db.wallet.update({
+      const updated = await ctx.db.wallet.update({
         where: {
           id: input.walletId,
         },
@@ -668,5 +744,15 @@ export const walletRouter = createTRPCRouter({
           isArchived: true,
         },
       });
+      void audit(ctx.db, {
+        actorAddress: sessionAddress,
+        actorType: "user",
+        action: "wallet.archive",
+        resourceType: "wallet",
+        resourceId: input.walletId,
+        ip: ctx.ip ?? null,
+        outcome: "success",
+      });
+      return updated;
     }),
 });
diff --git a/src/server/api/trpc.ts b/src/server/api/trpc.ts
index 5f4fba67..86adb02c 100644
--- a/src/server/api/trpc.ts
+++ b/src/server/api/trpc.ts
@@ -74,6 +74,30 @@ const createInnerTRPCContext = (opts: CreateContextOptions) => ({
   db,
 });
 
+/**
+ * Inferred shape of the context every tRPC procedure receives. Used as the
+ * type of `ctx` in helper functions that previously had to use `any`.
+ */
+export type TRPCContext = ReturnType<typeof createInnerTRPCContext>;
+
+/**
+ * Structural ctx shape accepted by router helpers. `protectedProcedure`'s
+ * middleware narrows `session.expires` to optional, which is not assignable
+ * to the base TRPCContext. Helpers consuming ctx use this looser shape so
+ * they accept both base and narrowed contexts.
+ */
+export type AuthCtx = {
+  db: TRPCContext["db"];
+  ip: string;
+  sessionAddress: string | null;
+  sessionWallets: string[];
+  primaryWallet: string | null;
+  session:
+    | (Omit<Session, "expires"> & { expires?: string })
+    | Session
+    | null;
+};
+
 /**
  * This is the actual context you will use in your router. It will be used to process every request
  * that goes through your tRPC endpoint.
@@ -235,7 +259,7 @@ export const protectedProcedure = t.procedure
   .use(({ ctx, next }) => {
     const hasNextAuth = !!ctx.session?.user;
     const hasWalletSession =
-      Array.isArray((ctx as any).sessionWallets) && (ctx as any).sessionWallets.length > 0;
+      Array.isArray(ctx.sessionWallets) && ctx.sessionWallets.length > 0;
 
     if (!hasNextAuth && !hasWalletSession) {
       throw new TRPCError({ code: "UNAUTHORIZED" });
@@ -248,8 +272,7 @@ export const protectedProcedure = t.procedure
     if (hasNextAuth) {
       sessionAddress = ctx.session?.user?.id ?? sessionAddress;
     } else if (!sessionAddress && hasWalletSession) {
-      const wallets = (ctx as any).sessionWallets as string[];
-      sessionAddress = wallets[0] ?? null;
+      sessionAddress = ctx.sessionWallets[0] ?? null;
     }
 
     return next({
diff --git a/src/utils/signing.ts b/src/utils/signing.ts
index 85cea045..bc8ad9b4 100644
--- a/src/utils/signing.ts
+++ b/src/utils/signing.ts
@@ -1,12 +1,20 @@
-import { checkSignature, generateNonce, IWallet } from "@meshsdk/core";
+import {
+  checkSignature,
+  DataSignature,
+  generateNonce,
+  IWallet,
+} from "@meshsdk/core";
+
+export type SignRole = 0 | 2 | 3;
 
 export async function sign(
   payload: string,
   wallet: IWallet,
-  role: number = 0,
+  role: SignRole = 0,
   userAddress?: string,
-) {
-  let address;
+  dRepAddress?: string,
+): Promise<DataSignature> {
+  let address: string | undefined;
   switch (role) {
     case 0:
       address = userAddress;
@@ -15,13 +23,25 @@ export async function sign(
       address = (await wallet.getRewardAddresses())[0];
       break;
     case 3:
-      address = "dRep address from role 3.";
+      address = dRepAddress;
+      break;
+    default: {
+      const _exhaustive: never = role;
+      throw new Error(`sign: unsupported role ${String(_exhaustive)}`);
+    }
+  }
+
+  if (!address) {
+    throw new Error("sign: missing address for the chosen role");
   }
 
   const nonce = generateNonce(payload);
   const signature = await wallet.signData(payload, address);
-  //ToDo improve signing capabilities.
-  const result = await checkSignature(nonce, signature, address);
+  const verified = await checkSignature(nonce, signature, address);
+
+  if (!verified) {
+    throw new Error("Signature failed verification");
+  }
 
-  return true ? signature : undefined;
+  return signature;
 }

From 749c59370d119de73e5ea41f13dfc0776fec64bf Mon Sep 17 00:00:00 2001
From: Jingles <jinglescode@gmail.com>
Date: Sun, 10 May 2026 16:32:05 +0800
Subject: [PATCH 05/10] refactor(wallet-flow): stable signerIds for React keys;
 tripwire test
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The new-wallet-flow and wallet-migration flow used the raw signer
address as a React key in ReviewSignersCard. Two issues:

1. The address can be empty/undefined while the user is editing, which
   makes the key non-unique → React reuses inputs across rows, swapping
   names and addresses while typing.
2. Two signers can momentarily share the same partial input, again
   producing duplicate keys.

Fix: every row gets a stable opaque `signerId` generated when the row
is created; the component uses `signerId` as the React key. Address
becomes regular state, free to be empty/duplicate transiently without
breaking React identity.

The same fix applied to both `useWalletFlowState` (new wallet) and
`useMigrationWalletFlowState` (migration). The shared `signerRows.ts`
module emits the id and keeps the parallel arrays in sync.

`reviewSignersCardKey.test.ts` is a tripwire suite that:
- greps the source to assert the raw address is never used as a key
- verifies both flow-state hooks expose signerIds parallel to
  signersAddresses

This catches future regressions structurally — the type system can't
enforce \"don't use address as key\", but a regex over source can.

Test plan
- 171/171 tests pass deterministically on top of #237
- Typecheck clean

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/__tests__/reviewSignersCardKey.test.ts    | 289 ++++++++++++++++++
 .../create/ReviewSignersCard.tsx              |  15 +-
 .../wallets/new-wallet-flow/create/index.tsx  |   1 +
 .../new-wallet-flow/shared/signerRows.ts      |  23 ++
 .../shared/useWalletFlowState.tsx             | 109 +++++--
 .../info/migration/NewWalletCreationStep.tsx  |   1 +
 .../migration/useMigrationWalletFlowState.tsx | 120 ++++++--
 7 files changed, 509 insertions(+), 49 deletions(-)
 create mode 100644 src/__tests__/reviewSignersCardKey.test.ts
 create mode 100644 src/components/pages/homepage/wallets/new-wallet-flow/shared/signerRows.ts

diff --git a/src/__tests__/reviewSignersCardKey.test.ts b/src/__tests__/reviewSignersCardKey.test.ts
new file mode 100644
index 00000000..c55c5f9c
--- /dev/null
+++ b/src/__tests__/reviewSignersCardKey.test.ts
@@ -0,0 +1,289 @@
+/**
+ * Regression test for Finding 1.1 (rocksolid/harden-pr-233):
+ * React key collision when multiple empty signer rows exist.
+ *
+ * The fix introduced a parallel `signerIds: string[]` array in
+ * useWalletFlowState / useMigrationWalletFlowState that is used as the
+ * React `key` on each signer row, instead of the (possibly empty,
+ * possibly duplicated) address string.
+ *
+ * This test pins the invariant on two layers:
+ *   1. The data-shape invariants of the React-key fix — exercised here
+ *      by inline simulation of the hook's add/remove array logic. We
+ *      cannot drive the hook itself in a node-environment jest run
+ *      (the hook depends on next/router, zustand, tRPC, and toast
+ *      providers), so this layer pins the *shape* the hook is
+ *      contracted to maintain: synthetic ids stay distinct across
+ *      empty-row collisions, and removal preserves index alignment
+ *      across all five parallel arrays.
+ *   2. A source-level tripwire (separate describe block below) that
+ *      catches anyone reverting the JSX back to address-as-key, or
+ *      removing the parallel signerIds array from either hook. The
+ *      React-key behavior itself — that the JSX consumes signerIds
+ *      and that the hook exposes it — is pinned by that tripwire.
+ *
+ * Why no `renderHook`: `useWalletFlowState` depends on next/router,
+ * zustand, tRPC, and toast providers, none of which exist in jest's
+ * `node` test environment. Adding `@testing-library/react` + jsdom
+ * would be substantial scaffolding and out of scope for this change.
+ */
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { makeSignerId } from "@/components/pages/homepage/wallets/new-wallet-flow/shared/signerRows";
+
+// ESM equivalent of CJS __dirname. Tests run under
+// node --experimental-vm-modules so CJS globals are unavailable.
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Mirror the splice-based array logic that addSigner / removeSigner
+// implement inside the two flow-state hooks. We cannot import the hooks
+// directly because they pull in next/router, zustand, tRPC, and toast
+// providers — none of which exist in jest's node test environment. So
+// we replicate the data flow at the same level of abstraction the hook
+// uses, and pin the invariant: after add/remove cycles, each parallel
+// array stays index-aligned with the others.
+type SignerRow = {
+  address: string;
+  description: string;
+  stakeKey: string;
+  drepKey: string;
+  id: string;
+};
+
+function applyAdd(rows: SignerRow[], newId: string): SignerRow[] {
+  // Mirrors addSigner: pushes empty fields with a fresh synthetic id.
+  return [
+    ...rows,
+    { address: "", description: "", stakeKey: "", drepKey: "", id: newId },
+  ];
+}
+
+function applyRemove(rows: SignerRow[], index: number): SignerRow[] {
+  // Mirrors removeSigner: splices the same index out of every parallel
+  // array. With address-as-key, two empty rows would collide on key=""
+  // and React could splice the wrong one — synthetic ids prevent that.
+  const next = rows.slice();
+  next.splice(index, 1);
+  return next;
+}
+
+describe("ReviewSignersCard signer-row key invariant", () => {
+  test("removing the middle of three signers keeps remaining rows aligned", () => {
+    const initial: SignerRow[] = [
+      {
+        address: "addr1qx_creator",
+        description: "Alice",
+        stakeKey: "stake1_alice",
+        drepKey: "drep_alice",
+        id: "id-creator",
+      },
+    ];
+
+    // User clicks "Add Signer" twice. Both new rows have address "" —
+    // the bug case. Synthetic ids must still differ.
+    const afterAdd1 = applyAdd(initial, "id-bob");
+    const afterAdd2 = applyAdd(afterAdd1, "id-carol");
+
+    expect(afterAdd2).toHaveLength(3);
+    // Two empty addresses, but ids are distinct.
+    expect(afterAdd2[1]!.address).toBe("");
+    expect(afterAdd2[2]!.address).toBe("");
+    expect(afterAdd2[1]!.id).not.toBe(afterAdd2[2]!.id);
+
+    // Fill them in so we can tell which row is which.
+    afterAdd2[1] = { ...afterAdd2[1]!, address: "addr1_bob", description: "Bob", stakeKey: "stake1_bob" };
+    afterAdd2[2] = { ...afterAdd2[2]!, address: "addr1_carol", description: "Carol", stakeKey: "stake1_carol" };
+
+    // Remove Bob (index 1).
+    const afterRemove = applyRemove(afterAdd2, 1);
+
+    expect(afterRemove).toHaveLength(2);
+    // Alice still at index 0, Carol now at index 1 — descriptions and
+    // stake keys must follow the same row, NOT slip out of alignment.
+    expect(afterRemove[0]!.description).toBe("Alice");
+    expect(afterRemove[0]!.stakeKey).toBe("stake1_alice");
+    expect(afterRemove[1]!.description).toBe("Carol");
+    expect(afterRemove[1]!.stakeKey).toBe("stake1_carol");
+    expect(afterRemove[1]!.address).toBe("addr1_carol");
+  });
+
+  test("two consecutive Add Signer clicks produce distinct synthetic ids", () => {
+    // The exact bug case: with key={signer} (address) two empty rows
+    // would collide. Synthetic ids must differ regardless of address.
+    let rows: SignerRow[] = [];
+    rows = applyAdd(rows, "id-1");
+    rows = applyAdd(rows, "id-2");
+
+    const ids = rows.map((r) => r.id);
+    expect(new Set(ids).size).toBe(rows.length);
+  });
+
+  test(
+    "addSigner-then-removeSigner: surviving row keeps its synthetic id, " +
+      "data-shape invariant pinned via inline simulation",
+    () => {
+      // Mirrors the array-manipulation contract the hook's `addSigner`
+      // / `removeSigner` setters apply, inline. `makeSignerId` runs
+      // unmocked so we exercise real id minting (crypto.randomUUID
+      // under Node >= 14.17, fallback otherwise).
+      //
+      // Scenario: start with one creator-seeded row (the first-user
+      // effect), append two empty rows, capture the id of the third
+      // row (the survivor), then splice index 1 — a mid-array empty
+      // remove. Assert that ids[1] is the survivor's *original* id
+      // (not a re-issued one) and that every parallel array stays
+      // index-aligned with ids.
+
+      type Arrays = {
+        addresses: string[];
+        descriptions: string[];
+        stakeKeys: string[];
+        drepKeys: string[];
+        ids: string[];
+      };
+
+      // Seed three rows. Index 0 is the creator (Alice). Index 1 is an
+      // empty row (Bob, never filled in) — preserves the empty-row
+      // collision scenario this test was originally written for. Index
+      // 2 (Carol, the survivor) carries distinct, non-empty values in
+      // every parallel array. After removing index 1, index 1 must
+      // hold Carol's distinct values; an off-by-one that mis-spliced
+      // any single non-id array would leave "" in that array's slot
+      // and fail the assertion.
+      let state: Arrays = {
+        addresses: ["addr1_creator", "", "addr1_carol"],
+        descriptions: ["Alice", "", "Carol"],
+        stakeKeys: ["stake1_creator", "", "stake1_carol"],
+        drepKeys: ["", "", "drep1_carol"],
+        ids: [makeSignerId(), makeSignerId(), makeSignerId()],
+      };
+
+      expect(state.ids).toHaveLength(3);
+      // Three distinct synthetic ids — the bug case (two empty rows
+      // sharing key="") cannot reproduce when ids are minted per-row.
+      expect(new Set(state.ids).size).toBe(3);
+
+      // Survivor: the row currently at index 2. Its id must follow the
+      // row, not the index, after we remove index 1.
+      const survivorOriginalId = state.ids[2]!;
+
+      // Splice index 1 out of every parallel array, mirroring
+      // removeSigner.
+      const spliceOut = <T,>(arr: T[], i: number): T[] => {
+        const next = arr.slice();
+        next.splice(i, 1);
+        return next;
+      };
+      state = {
+        addresses: spliceOut(state.addresses, 1),
+        descriptions: spliceOut(state.descriptions, 1),
+        stakeKeys: spliceOut(state.stakeKeys, 1),
+        drepKeys: spliceOut(state.drepKeys, 1),
+        ids: spliceOut(state.ids, 1),
+      };
+
+      expect(state.ids).toHaveLength(2);
+      // The id now at index 1 must be the survivor's original id —
+      // proving identity follows the row, not the position. If the hook
+      // re-minted ids on remove (the broken pattern), this would fail.
+      expect(state.ids[1]).toBe(survivorOriginalId);
+      // Every parallel array stays index-aligned with ids AND the
+      // survivor's distinct values land at index 1. An off-by-one that
+      // spliced index 2 instead of index 1 would leave "" here in any
+      // single array — making the splice direction directly testable.
+      expect(state.addresses[1]).toBe("addr1_carol");
+      expect(state.descriptions[1]).toBe("Carol");
+      expect(state.stakeKeys[1]).toBe("stake1_carol");
+      expect(state.drepKeys[1]).toBe("drep1_carol");
+      // Creator row at index 0 untouched.
+      expect(state.ids[0]).not.toBe(survivorOriginalId);
+      expect(state.addresses[0]).toBe("addr1_creator");
+      expect(state.descriptions[0]).toBe("Alice");
+      expect(state.stakeKeys[0]).toBe("stake1_creator");
+    },
+  );
+});
+
+describe("ReviewSignersCard tripwire on source", () => {
+  // Pin the source-level fix: anyone reverting back to address-as-key
+  // (or removing the parallel signerIds) will see this test fail.
+  const SOURCE_PATH = path.resolve(
+    __dirname,
+    "../components/pages/homepage/wallets/new-wallet-flow/create/ReviewSignersCard.tsx",
+  );
+  const HOOK_PATH = path.resolve(
+    __dirname,
+    "../components/pages/homepage/wallets/new-wallet-flow/shared/useWalletFlowState.tsx",
+  );
+  const MIGRATION_HOOK_PATH = path.resolve(
+    __dirname,
+    "../components/pages/wallet/info/migration/useMigrationWalletFlowState.tsx",
+  );
+
+  test("ReviewSignersCard never uses the raw address as a React key", () => {
+    const src = fs.readFileSync(SOURCE_PATH, "utf8");
+
+    // ---- Negative tripwire ----
+    //
+    // Nothing within `key={ ... }` may start with the bare identifier
+    // `signer` (the per-iteration address). The boundary class
+    // `(\s|\}|[^a-zA-Z_0-9])` after `signer` rejects the entire
+    // address-as-key family:
+    //   - `key={signer}`             (the original bug)
+    //   - `key={ signer }`           (whitespace variant)
+    //   - `key={signer ?? ""}`       (nullish-coalescing fallback)
+    //   - `key={signer.address}`     (member-access — different revert)
+    //   - `key={String(signer)}`     ('(' is non-alphanumeric)
+    //
+    // It deliberately does NOT trip on the synthetic forms
+    // `key={signerIds[index]}` or `key={signerIds[index] ?? "..."}`
+    // because the `I` in `Ids` is a-zA-Z and falls outside the
+    // boundary class — `signer` followed by a word char is fine.
+    expect(src).not.toMatch(/key=\{\s*signer(\s|\}|[^a-zA-Z_0-9])/);
+
+    // ---- Positive tripwire ----
+    //
+    // Within 200 chars of an opening `<TableRow`, the `key={...}`
+    // expression must reference either the synthetic-id helper
+    // (`rowKey(`) OR the parallel ids array directly (`signerIds`).
+    // Accepting both forms lets a future refactor inline the helper as
+    //   <TableRow key={signerIds[index] ?? `signer-row-${index}`}>
+    // without breaking this test (the synthetic-id behavior survives).
+    // It still fails if anyone reverts to the bare address or to a
+    // bare index-as-key.
+    expect(src).toMatch(
+      /<TableRow[\s\S]{0,200}key=\{[\s\S]{0,80}(signerIds|rowKey\()/,
+    );
+
+    // Same shape for the mobile card branch (a div inside the
+    // `signersAddresses.map(...)` mobile loop, identifiable by its
+    // unique class `rounded-lg border`). The order of attributes on
+    // the JSX element isn't fixed (key may come before or after
+    // className), so we check that within an opening `<div` block
+    // both the class marker and a synthetic-id key co-occur within
+    // 300 chars of each other. Without this, only one of the two
+    // render branches is pinned and a partial revert could slip
+    // through.
+    const divMobileBlocks = src.match(/<div[\s\S]{0,300}?>/g) ?? [];
+    const mobileCardBlock = divMobileBlocks.find(
+      (block) =>
+        /rounded-lg border/.test(block) &&
+        /key=\{[\s\S]{0,80}(signerIds|rowKey\()/.test(block),
+    );
+    expect(mobileCardBlock).toBeDefined();
+  });
+
+  test("useWalletFlowState exposes signerIds parallel to signersAddresses", () => {
+    const src = fs.readFileSync(HOOK_PATH, "utf8");
+    expect(src).toMatch(/signerIds/);
+    expect(src).toMatch(/setSignerIds/);
+  });
+
+  test("useMigrationWalletFlowState exposes signerIds parallel to signersAddresses", () => {
+    const src = fs.readFileSync(MIGRATION_HOOK_PATH, "utf8");
+    expect(src).toMatch(/signerIds/);
+    expect(src).toMatch(/setSignerIds/);
+  });
+});
diff --git a/src/components/pages/homepage/wallets/new-wallet-flow/create/ReviewSignersCard.tsx b/src/components/pages/homepage/wallets/new-wallet-flow/create/ReviewSignersCard.tsx
index 9232b688..e96c685d 100644
--- a/src/components/pages/homepage/wallets/new-wallet-flow/create/ReviewSignersCard.tsx
+++ b/src/components/pages/homepage/wallets/new-wallet-flow/create/ReviewSignersCard.tsx
@@ -52,10 +52,20 @@ interface SignerConfig {
   setSignerStakeKeys: React.Dispatch<React.SetStateAction<string[]>>;
   signersDRepKeys: string[];
   setSignerDRepKeys: React.Dispatch<React.SetStateAction<string[]>>;
+  signerIds?: string[];
   addSigner: () => void;
   removeSigner?: (index: number) => void;
 }
 
+// Synthetic React-key helper. The on-chain address is unique per signer in the
+// happy path, but during edits or paste flows it can briefly collide; using
+// the address as a key triggers React reconciliation bugs (lost focus,
+// duplicated DOM nodes). `signerIds` is kept index-aligned by the host hook
+// (`useWalletFlowState` / `useMigrationWalletFlowState`); this fallback runs
+// only when a caller hasn't wired it through yet.
+const rowKey = (signerIds: string[] | undefined, index: number): string =>
+  signerIds?.[index] ?? `signer-row-${index}`;
+
 interface ReviewSignersCardProps {
   signerConfig: SignerConfig;
   currentUserAddress?: string;
@@ -85,6 +95,7 @@ const ReviewSignersCard: React.FC<ReviewSignersCardProps> = ({
     setSignerStakeKeys,
     signersDRepKeys = [],
     setSignerDRepKeys,
+    signerIds,
     addSigner,
     removeSigner,
   } = signerConfig;
@@ -263,7 +274,7 @@ const ReviewSignersCard: React.FC<ReviewSignersCardProps> = ({
                 </TableHeader>
                 <TableBody>
                   {signersAddresses.map((signer, index) => (
-                    <TableRow key={signer}>
+                    <TableRow key={rowKey(signerIds, index)}>
                       {/* Signer name */}
                       <TableCell>
                         <span className="flex items-center gap-2">
@@ -374,7 +385,7 @@ const ReviewSignersCard: React.FC<ReviewSignersCardProps> = ({
             <div className="space-y-3 sm:hidden">
               {signersAddresses.map((signer, index) => (
                 <div
-                  key={signer}
+                  key={rowKey(signerIds, index)}
                   className="space-y-2 rounded-lg border border-black/10 p-4 dark:border-white/5"
                 >
                   {/* Top row: Name and Actions */}
diff --git a/src/components/pages/homepage/wallets/new-wallet-flow/create/index.tsx b/src/components/pages/homepage/wallets/new-wallet-flow/create/index.tsx
index 68b0e44d..29a73531 100644
--- a/src/components/pages/homepage/wallets/new-wallet-flow/create/index.tsx
+++ b/src/components/pages/homepage/wallets/new-wallet-flow/create/index.tsx
@@ -37,6 +37,7 @@ export default function PageReviewWallet() {
               setSignerStakeKeys: walletFlow.setSignerStakeKeys,
               signersDRepKeys: walletFlow.signersDRepKeys,
               setSignerDRepKeys: walletFlow.setSignerDRepKeys,
+              signerIds: walletFlow.signerIds,
               addSigner: walletFlow.addSigner,
               removeSigner: walletFlow.removeSigner,
             }}
diff --git a/src/components/pages/homepage/wallets/new-wallet-flow/shared/signerRows.ts b/src/components/pages/homepage/wallets/new-wallet-flow/shared/signerRows.ts
new file mode 100644
index 00000000..e908067f
--- /dev/null
+++ b/src/components/pages/homepage/wallets/new-wallet-flow/shared/signerRows.ts
@@ -0,0 +1,23 @@
+/**
+ * Shared synthetic-id minter for the parallel signer arrays that
+ * `useWalletFlowState` and `useMigrationWalletFlowState` maintain
+ * (signersAddresses / signersDescriptions / signersStakeKeys /
+ * signersDRepKeys / signerIds).
+ *
+ * Lives in a standalone module — with no React, next/router, zustand,
+ * tRPC, or toast imports — so it can be unit-tested without rendering
+ * either hook. Both hooks import `makeSignerId` directly when
+ * appending a new row.
+ */
+
+/**
+ * Generate a stable synthetic id for a signer row. `crypto.randomUUID`
+ * is available in modern browsers and Node >= 14.17; fall back to a
+ * timestamp+random string in environments where it isn't.
+ */
+export function makeSignerId(): string {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `signer-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
diff --git a/src/components/pages/homepage/wallets/new-wallet-flow/shared/useWalletFlowState.tsx b/src/components/pages/homepage/wallets/new-wallet-flow/shared/useWalletFlowState.tsx
index 3759303d..b52dc5f3 100644
--- a/src/components/pages/homepage/wallets/new-wallet-flow/shared/useWalletFlowState.tsx
+++ b/src/components/pages/homepage/wallets/new-wallet-flow/shared/useWalletFlowState.tsx
@@ -16,6 +16,7 @@ import { useUserStore } from "@/lib/zustand/user";
 import { useSiteStore } from "@/lib/zustand/site";
 import { useToast } from "@/hooks/use-toast";
 import useUser from "@/hooks/useUser";
+import { makeSignerId } from "./signerRows";
 
 export interface WalletFlowState {
   // Core wallet data
@@ -35,9 +36,23 @@ export interface WalletFlowState {
   setSignerStakeKeys: React.Dispatch<React.SetStateAction<string[]>>;
   signersDRepKeys: string[];
   setSignerDRepKeys: React.Dispatch<React.SetStateAction<string[]>>;
-  addSigner: () => void;
+  // Stable synthetic identifiers for each signer row, parallel to
+  // signersAddresses. Used as React `key` so duplicate / empty addresses
+  // do not collide and stomp form state on re-render. Never sent to the
+  // backend — purely local UI identity.
+  signerIds: string[];
+  // Optional positional params let callers (e.g. ReviewSignersCard's
+  // "Add signer" dialog) push a fully-populated row through the hook so
+  // signerIds stays index-aligned with signersAddresses. Called with no
+  // args, it appends an empty row (legacy behavior).
+  addSigner: (
+    address?: string,
+    stakeKey?: string,
+    drepKey?: string,
+    description?: string,
+  ) => void;
   removeSigner: (index: number) => void;
-  
+
   // Signature rules
   numRequiredSigners: number;
   setNumRequiredSigners: React.Dispatch<React.SetStateAction<number>>;
@@ -99,12 +114,14 @@ export interface WalletFlowState {
   handleSaveAdvanced: (newStakeKey: string, scriptType: "all" | "any" | "atLeast") => void;
 }
 
+
 export function useWalletFlowState(): WalletFlowState {
   const router = useRouter();
   const [signersAddresses, setSignerAddresses] = useState<string[]>([]);
   const [signersDescriptions, setSignerDescriptions] = useState<string[]>([]);
   const [signersStakeKeys, setSignerStakeKeys] = useState<string[]>([]);
   const [signersDRepKeys, setSignerDRepKeys] = useState<string[]>([]);
+  const [signerIds, setSignerIds] = useState<string[]>([]);
   const [numRequiredSigners, setNumRequiredSigners] = useState<number>(1);
   const [name, setName] = useState<string>("");
   const [description, setDescription] = useState<string>("");
@@ -303,6 +320,7 @@ export function useWalletFlowState(): WalletFlowState {
       setSignerStakeKeys([stakeKey ? "" : user.stakeAddress]);
       // Import DRep key from user data
       setSignerDRepKeys([(user as any).drepKeyHash || ""]);
+      setSignerIds([makeSignerId()]);
     }
   }, [user, stakeKey, pathIsWalletInvite]);
 
@@ -363,6 +381,20 @@ export function useWalletFlowState(): WalletFlowState {
           : [];
       setSignerStakeKeys(incomingStakeKeys);
       setSignerDRepKeys((walletInvite as any).signersDRepKeys ?? []);
+      // Keep synthetic ids stable across refetches: only mint new ids
+      // for rows that grow the array, trim if it shrinks. Re-minting on
+      // every refetch would unmount in-flight description inputs and
+      // drop focus / IME state. Mirrors handleSaveSigners' pattern.
+      setSignerIds((prev) => {
+        const incoming = walletInvite.signersAddresses ?? [];
+        if (prev.length === incoming.length) return prev;
+        if (prev.length < incoming.length) {
+          const next = prev.slice();
+          while (next.length < incoming.length) next.push(makeSignerId());
+          return next;
+        }
+        return prev.slice(0, incoming.length);
+      });
       setNumRequiredSigners(walletInvite.numRequiredSigners!);
       setStakeKey((walletInvite as any).stakeCredentialHash ?? "");
       setNativeScriptType((walletInvite as any).scriptType ?? "atLeast");
@@ -371,30 +403,58 @@ export function useWalletFlowState(): WalletFlowState {
 
   // Utility functions
 
-  function addSigner() {
-    setSignerAddresses([...signersAddresses, ""]);
-    setSignerDescriptions([...signersDescriptions, ""]);
-    // Always add empty stake key when external stake credential is set, otherwise add empty string
-    setSignerStakeKeys([...signersStakeKeys, stakeKey ? "" : ""]);
-    setSignerDRepKeys([...signersDRepKeys, ""]);
+  function addSigner(
+    address: string = "",
+    newStakeKey: string = "",
+    drepKey: string = "",
+    description: string = "",
+  ) {
+    // Functional updaters so two synchronous addSigner() calls in the
+    // same render append two rows. With closure-reading non-functional
+    // setters, both calls would read the same `signersAddresses` and
+    // collapse into a single appended row, leaving signerIds.length
+    // out of sync with the other arrays.
+    const stakeKeyForRow = stakeKey ? "" : newStakeKey;
+    setSignerAddresses((arr) => [...arr, address]);
+    setSignerDescriptions((arr) => [...arr, description]);
+    // Always blank the per-signer stake key when an external stake
+    // credential is set, regardless of what was passed in.
+    setSignerStakeKeys((arr) => [...arr, stakeKeyForRow]);
+    setSignerDRepKeys((arr) => [...arr, drepKey]);
+    setSignerIds((arr) => [...arr, makeSignerId()]);
   }
 
   function removeSigner(index: number) {
-    const updatedAddresses = [...signersAddresses];
-    updatedAddresses.splice(index, 1);
-    setSignerAddresses(updatedAddresses);
-
-    const updatedDescriptions = [...signersDescriptions];
-    updatedDescriptions.splice(index, 1);
-    setSignerDescriptions(updatedDescriptions);
-
-    const updatedStakeKeys = [...signersStakeKeys];
-    updatedStakeKeys.splice(index, 1);
-    setSignerStakeKeys(updatedStakeKeys);
-
-    const updatedDRepKeys = [...signersDRepKeys];
-    updatedDRepKeys.splice(index, 1);
-    setSignerDRepKeys(updatedDRepKeys);
+    // Functional updaters mirror the Pass 3 fix in addSigner: two
+    // synchronous removeSigner() calls in the same render must each
+    // see the previous batch's update, otherwise the second call would
+    // splice from a stale closure-read array and the five parallel
+    // arrays could drift out of alignment.
+    setSignerAddresses((arr) => {
+      const next = arr.slice();
+      next.splice(index, 1);
+      return next;
+    });
+    setSignerDescriptions((arr) => {
+      const next = arr.slice();
+      next.splice(index, 1);
+      return next;
+    });
+    setSignerStakeKeys((arr) => {
+      const next = arr.slice();
+      next.splice(index, 1);
+      return next;
+    });
+    setSignerDRepKeys((arr) => {
+      const next = arr.slice();
+      next.splice(index, 1);
+      return next;
+    });
+    setSignerIds((arr) => {
+      const next = arr.slice();
+      next.splice(index, 1);
+      return next;
+    });
   }
 
   function createNativeScript() {
@@ -666,9 +726,10 @@ export function useWalletFlowState(): WalletFlowState {
     setSignerStakeKeys,
     signersDRepKeys,
     setSignerDRepKeys,
+    signerIds,
     addSigner,
     removeSigner,
-    
+
     // Signature rules
     numRequiredSigners,
     setNumRequiredSigners,
diff --git a/src/components/pages/wallet/info/migration/NewWalletCreationStep.tsx b/src/components/pages/wallet/info/migration/NewWalletCreationStep.tsx
index 6c8c6aae..b9a2aa99 100644
--- a/src/components/pages/wallet/info/migration/NewWalletCreationStep.tsx
+++ b/src/components/pages/wallet/info/migration/NewWalletCreationStep.tsx
@@ -200,6 +200,7 @@ export default function NewWalletCreationStep({
           setSignerStakeKeys: walletFlow.setSignerStakeKeys,
           signersDRepKeys: walletFlow.signersDRepKeys,
           setSignerDRepKeys: walletFlow.setSignerDRepKeys,
+          signerIds: walletFlow.signerIds,
           addSigner: walletFlow.addSigner,
           removeSigner: walletFlow.removeSigner,
         }}
diff --git a/src/components/pages/wallet/info/migration/useMigrationWalletFlowState.tsx b/src/components/pages/wallet/info/migration/useMigrationWalletFlowState.tsx
index 5a796a00..2683683e 100644
--- a/src/components/pages/wallet/info/migration/useMigrationWalletFlowState.tsx
+++ b/src/components/pages/wallet/info/migration/useMigrationWalletFlowState.tsx
@@ -15,6 +15,7 @@ import { useUserStore } from "@/lib/zustand/user";
 import { useSiteStore } from "@/lib/zustand/site";
 import { useToast } from "@/hooks/use-toast";
 import type { Wallet } from "@/types/wallet";
+import { makeSignerId } from "@/components/pages/homepage/wallets/new-wallet-flow/shared/signerRows";
 
 const apiClient = api;
 
@@ -34,9 +35,23 @@ export interface MigrationWalletFlowState {
   setSignerStakeKeys: React.Dispatch<React.SetStateAction<string[]>>;
   signersDRepKeys: string[];
   setSignerDRepKeys: React.Dispatch<React.SetStateAction<string[]>>;
-  addSigner: () => void;
+  // Stable synthetic identifiers for each signer row, parallel to
+  // signersAddresses. Used as React `key` so duplicate / empty addresses
+  // do not collide and stomp form state on re-render. Never sent to the
+  // backend — purely local UI identity.
+  signerIds: string[];
+  // Optional positional params let callers (e.g. ReviewSignersCard's
+  // "Add signer" dialog) push a fully-populated row through the hook so
+  // signerIds stays index-aligned with signersAddresses. Called with no
+  // args, it appends an empty row (legacy behavior).
+  addSigner: (
+    address?: string,
+    stakeKey?: string,
+    drepKey?: string,
+    description?: string,
+  ) => void;
   removeSigner: (index: number) => void;
-  
+
   // Signature rules
   numRequiredSigners: number;
   setNumRequiredSigners: React.Dispatch<React.SetStateAction<number>>;
@@ -81,6 +96,7 @@ export function useMigrationWalletFlowState(appWallet: Wallet, migrationId?: str
   const [signersDescriptions, setSignerDescriptions] = useState<string[]>([]);
   const [signersStakeKeys, setSignerStakeKeys] = useState<string[]>([]);
   const [signersDRepKeys, setSignerDRepKeys] = useState<string[]>([]);
+  const [signerIds, setSignerIds] = useState<string[]>([]);
   const [numRequiredSigners, setNumRequiredSigners] = useState<number>(1);
   const [name, setName] = useState<string>("");
   const [description, setDescription] = useState<string>("");
@@ -147,6 +163,18 @@ export function useMigrationWalletFlowState(appWallet: Wallet, migrationId?: str
       setName(`${walletData.name} - Migration in Progress`);
       setDescription(walletData.description ?? "");
       setSignerAddresses(walletData.signersAddresses ?? []);
+      // Stable across refetches — only grow / shrink, never re-mint, so
+      // an in-flight description input does not lose focus / IME state.
+      setSignerIds((prev) => {
+        const incoming = walletData.signersAddresses ?? [];
+        if (prev.length === incoming.length) return prev;
+        if (prev.length < incoming.length) {
+          const next = prev.slice();
+          while (next.length < incoming.length) next.push(makeSignerId());
+          return next;
+        }
+        return prev.slice(0, incoming.length);
+      });
       setSignerDescriptions(walletData.signersDescriptions ?? []);
       setNumRequiredSigners(walletData.numRequiredSigners ?? 1);
       setNativeScriptType((walletData.type as "atLeast" | "all" | "any") ?? "atLeast");
@@ -183,6 +211,18 @@ export function useMigrationWalletFlowState(appWallet: Wallet, migrationId?: str
       setName(existingNewWallet.name);
       setDescription(existingNewWallet.description ?? "");
       setSignerAddresses(existingNewWallet.signersAddresses ?? []);
+      // Stable across refetches — only grow / shrink, never re-mint, so
+      // an in-flight description input does not lose focus / IME state.
+      setSignerIds((prev) => {
+        const incoming = existingNewWallet.signersAddresses ?? [];
+        if (prev.length === incoming.length) return prev;
+        if (prev.length < incoming.length) {
+          const next = prev.slice();
+          while (next.length < incoming.length) next.push(makeSignerId());
+          return next;
+        }
+        return prev.slice(0, incoming.length);
+      });
       setSignerDescriptions(existingNewWallet.signersDescriptions ?? []);
       setSignerStakeKeys(existingNewWallet.signersStakeKeys ?? []);
       setSignerDRepKeys(
@@ -354,29 +394,55 @@ export function useMigrationWalletFlowState(appWallet: Wallet, migrationId?: str
   });
 
   // Utility functions
-  function addSigner() {
-    setSignerAddresses([...signersAddresses, ""]);
-    setSignerDescriptions([...signersDescriptions, ""]);
-    setSignerStakeKeys([...signersStakeKeys, ""]);
-    setSignerDRepKeys([...signersDRepKeys, ""]);
+  function addSigner(
+    address: string = "",
+    newStakeKey: string = "",
+    drepKey: string = "",
+    description: string = "",
+  ) {
+    // Functional updaters so two synchronous addSigner() calls in the
+    // same render append two rows. With closure-reading non-functional
+    // setters, both calls would read the same `signersAddresses` and
+    // collapse into a single appended row, leaving signerIds.length
+    // out of sync with the other arrays.
+    setSignerAddresses((arr) => [...arr, address]);
+    setSignerDescriptions((arr) => [...arr, description]);
+    setSignerStakeKeys((arr) => [...arr, newStakeKey]);
+    setSignerDRepKeys((arr) => [...arr, drepKey]);
+    setSignerIds((arr) => [...arr, makeSignerId()]);
   }
 
   function removeSigner(index: number) {
-    const updatedAddresses = [...signersAddresses];
-    updatedAddresses.splice(index, 1);
-    setSignerAddresses(updatedAddresses);
-
-    const updatedDescriptions = [...signersDescriptions];
-    updatedDescriptions.splice(index, 1);
-    setSignerDescriptions(updatedDescriptions);
-
-    const updatedStakeKeys = [...signersStakeKeys];
-    updatedStakeKeys.splice(index, 1);
-    setSignerStakeKeys(updatedStakeKeys);
-
-    const updatedDRepKeys = [...signersDRepKeys];
-    updatedDRepKeys.splice(index, 1);
-    setSignerDRepKeys(updatedDRepKeys);
+    // Functional updaters mirror the Pass 3 fix in addSigner: two
+    // synchronous removeSigner() calls in the same render must each
+    // see the previous batch's update, otherwise the second call would
+    // splice from a stale closure-read array and the five parallel
+    // arrays could drift out of alignment.
+    setSignerAddresses((arr) => {
+      const next = arr.slice();
+      next.splice(index, 1);
+      return next;
+    });
+    setSignerDescriptions((arr) => {
+      const next = arr.slice();
+      next.splice(index, 1);
+      return next;
+    });
+    setSignerStakeKeys((arr) => {
+      const next = arr.slice();
+      next.splice(index, 1);
+      return next;
+    });
+    setSignerDRepKeys((arr) => {
+      const next = arr.slice();
+      next.splice(index, 1);
+      return next;
+    });
+    setSignerIds((arr) => {
+      const next = arr.slice();
+      next.splice(index, 1);
+      return next;
+    });
   }
 
   // Adjust numRequiredSigners if it exceeds the number of signers
@@ -629,6 +695,13 @@ export function useMigrationWalletFlowState(appWallet: Wallet, migrationId?: str
     setSignerDescriptions(paddedDescriptions);
     setSignerStakeKeys(paddedStakeKeys);
     setSignerDRepKeys(paddedDRepKeys);
+    // Keep synthetic ids parallel to the address array. Reuse existing ids
+    // for the rows that survive, mint fresh ones for any newly-added rows.
+    setSignerIds((prevIds) => {
+      const next = prevIds.slice(0, paddedAddresses.length);
+      while (next.length < paddedAddresses.length) next.push(makeSignerId());
+      return next;
+    });
     
     if (newWalletId) {
       const updateData = {
@@ -778,9 +851,10 @@ export function useMigrationWalletFlowState(appWallet: Wallet, migrationId?: str
     setSignerStakeKeys,
     signersDRepKeys,
     setSignerDRepKeys,
+    signerIds,
     addSigner,
     removeSigner,
-    
+
     // Signature rules
     numRequiredSigners,
     setNumRequiredSigners,

From c9fb61bab6c4bcaff3cf230f7edf9ec8c55e9833 Mon Sep 17 00:00:00 2001
From: Jingles <jinglescode@gmail.com>
Date: Sun, 10 May 2026 16:33:17 +0800
Subject: [PATCH 06/10] chore(ui): a11y skip-link, useMemo transaction parse,
 cleanup deletions

Small UI/hook cleanup that fell out of the audit:

- overall-layout: add skip-link + main-content anchor; aria-label on the
  main form. Trims unused legacy nav code.
- transaction-card: useMemo the JSON.parse(transaction.txJson) so the
  parse only runs when txJson changes, not on every render. Removes a
  dead `import { get } from \"http\"` that was sneaking into the client
  bundle.
- signable-card: defensive parse for legacy payload shapes.
- card-show-signers, signing/index: small render fixes.
- ImgDragAndDrop, MeshProviderClient, BotManagementCard, background.tsx:
  drop dead state vars / unused imports surfaced by the audit.
- useAppWallet, useMultisigWallet: stable returns; missing-wallet path
  no longer spins indefinitely.
- Delete `src/components/multisig/proxy/ProxyControlExample.tsx`. It was
  example-only code, not exported from the proxy index, never rendered
  anywhere. The barrel import is updated.

Test plan
- 165/165 staged-suite tests pass on top of #237
- Typecheck clean

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/components/common/ImgDragAndDrop.tsx      |   1 +
 src/components/common/MeshProviderClient.tsx  |   2 -
 .../common/overall-layout/layout.tsx          |  67 +++--------
 .../multisig/proxy/ProxyControlExample.tsx    | 107 ------------------
 src/components/multisig/proxy/index.ts        |   1 -
 .../pages/user/BotManagementCard.tsx          |   2 -
 .../wallet/info/signers/card-show-signers.tsx |  30 ++---
 src/components/pages/wallet/signing/index.tsx |   2 +-
 .../pages/wallet/signing/signable-card.tsx    |  21 +++-
 .../wallet/transactions/transaction-card.tsx  |   3 +-
 src/components/ui/background.tsx              |   2 -
 src/hooks/useAppWallet.ts                     |  11 +-
 src/hooks/useMultisigWallet.ts                |  11 +-
 13 files changed, 59 insertions(+), 201 deletions(-)
 delete mode 100644 src/components/multisig/proxy/ProxyControlExample.tsx

diff --git a/src/components/common/ImgDragAndDrop.tsx b/src/components/common/ImgDragAndDrop.tsx
index d5cfdbd3..227a69e3 100644
--- a/src/components/common/ImgDragAndDrop.tsx
+++ b/src/components/common/ImgDragAndDrop.tsx
@@ -225,6 +225,7 @@ export default function ImgDragAndDrop({ onImageUpload, initialUrl }: ImgDragAnd
       </div>
       <Input
         type="url"
+        aria-label="Image URL"
         className="w-full rounded-md border border-gray-300 p-2"
         placeholder="Enter your own image URL..."
         value={filePath}
diff --git a/src/components/common/MeshProviderClient.tsx b/src/components/common/MeshProviderClient.tsx
index 1d8cd2a0..51b2776d 100644
--- a/src/components/common/MeshProviderClient.tsx
+++ b/src/components/common/MeshProviderClient.tsx
@@ -1,5 +1,3 @@
- "use client";
-
 import "@meshsdk/react/styles.css";
 import { MeshProvider } from "@meshsdk/react";
 
diff --git a/src/components/common/overall-layout/layout.tsx b/src/components/common/overall-layout/layout.tsx
index 2f2da2f8..9f6585c3 100644
--- a/src/components/common/overall-layout/layout.tsx
+++ b/src/components/common/overall-layout/layout.tsx
@@ -94,56 +94,6 @@ class WalletErrorBoundary extends Component<
   }
 }
 
-// Component to track layout content changes
-function LayoutContentTracker({ 
-  children, 
-  router, 
-  pageIsPublic, 
-  userAddress 
-}: { 
-  children: ReactNode; 
-  router: ReturnType<typeof useRouter>;
-  pageIsPublic: boolean;
-  userAddress: string | undefined;
-}) {
-  const prevPathRef = useRef<string>(router.pathname);
-  const prevQueryRef = useRef<string>(JSON.stringify(router.query));
-  
-  useEffect(() => {
-    const handleRouteChangeStart = (url: string) => {
-      // Route change started
-    };
-    
-    const handleRouteChangeComplete = (url: string) => {
-      prevPathRef.current = router.pathname;
-      prevQueryRef.current = JSON.stringify(router.query);
-    };
-    
-    const handleRouteChangeError = (err: Error, url: string) => {
-      // Route change error
-    };
-    
-    router.events.on('routeChangeStart', handleRouteChangeStart);
-    router.events.on('routeChangeComplete', handleRouteChangeComplete);
-    router.events.on('routeChangeError', handleRouteChangeError);
-    
-    return () => {
-      router.events.off('routeChangeStart', handleRouteChangeStart);
-      router.events.off('routeChangeComplete', handleRouteChangeComplete);
-      router.events.off('routeChangeError', handleRouteChangeError);
-    };
-  }, [router]);
-  
-  useEffect(() => {
-    if (router.pathname !== prevPathRef.current || JSON.stringify(router.query) !== prevQueryRef.current) {
-      prevPathRef.current = router.pathname;
-      prevQueryRef.current = JSON.stringify(router.query);
-    }
-  }, [router.pathname, router.query]);
-  
-  return <>{children}</>;
-}
-
 export default function RootLayout({
   children,
 }: {
@@ -552,6 +502,13 @@ export default function RootLayout({
 
   return (
     <div className="flex h-screen w-screen flex-col overflow-hidden">
+      {/* Skip link for keyboard users */}
+      <a
+        href="#main-content"
+        className="sr-only focus:not-sr-only focus:fixed focus:left-4 focus:top-4 focus:z-[200] focus:rounded-md focus:bg-primary focus:px-4 focus:py-2 focus:text-primary-foreground focus:shadow-lg focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2"
+      >
+        Skip to main content
+      </a>
       {(shouldShowBackgroundLoading || showPostAuthLoading) && (
         <div className="fixed inset-0 z-50 transition-opacity duration-300 ease-in-out opacity-100">
           <Loading />
@@ -677,7 +634,11 @@ export default function RootLayout({
         )}
 
         {/* Main content */}
-        <main className="relative flex flex-1 flex-col gap-4 overflow-y-auto overflow-x-hidden p-4 md:p-8">
+        <main
+          id="main-content"
+          tabIndex={-1}
+          className="relative flex flex-1 flex-col gap-4 overflow-y-auto overflow-x-hidden p-4 md:p-8 focus:outline-none"
+        >
           <WalletErrorBoundary
             fallback={
               <div className="flex flex-col items-center justify-center h-full min-h-[400px] px-4">
@@ -712,9 +673,7 @@ export default function RootLayout({
               </div>
             }
           >
-            <LayoutContentTracker router={router} pageIsPublic={pageIsPublic} userAddress={userAddress}>
-              {pageIsPublic || userAddress ? children : <PageHomepage />}
-            </LayoutContentTracker>
+            {pageIsPublic || userAddress ? children : <PageHomepage />}
           </WalletErrorBoundary>
         </main>
       </div>
diff --git a/src/components/multisig/proxy/ProxyControlExample.tsx b/src/components/multisig/proxy/ProxyControlExample.tsx
deleted file mode 100644
index 7c110a04..00000000
--- a/src/components/multisig/proxy/ProxyControlExample.tsx
+++ /dev/null
@@ -1,107 +0,0 @@
-import React from "react";
-import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
-import { Alert, AlertDescription } from "@/components/ui/alert";
-import { Info } from "lucide-react";
-import ProxyControl from "./ProxyControl";
-
-/**
- * Example page demonstrating how to use the ProxyControl component
- * 
- * This component shows how to integrate the ProxyControl into your application
- * and provides context about what the proxy system does.
- */
-export default function ProxyControlExample() {
-  return (
-    <div className="container mx-auto p-6 space-y-6">
-      <div className="space-y-4">
-        <h1 className="text-3xl font-bold">Proxy Control System</h1>
-        <p className="text-lg text-muted-foreground">
-          Manage your Cardano proxy contract for automated and controlled transactions.
-        </p>
-      </div>
-
-      <Alert>
-        <Info className="h-4 w-4" />
-        <AlertDescription>
-          <strong>What is a Proxy Contract?</strong><br />
-          A proxy contract allows you to create a controlled address that can be managed through auth tokens. 
-          This enables automated transactions while maintaining security through your multisig wallet. 
-          The proxy can hold assets and execute transactions when you have the required auth tokens.
-        </AlertDescription>
-      </Alert>
-
-      <Card>
-        <CardHeader>
-          <CardTitle>How it Works</CardTitle>
-          <CardDescription>
-            Understanding the proxy system workflow
-          </CardDescription>
-        </CardHeader>
-        <CardContent className="space-y-4">
-          <div className="grid gap-4 md:grid-cols-3">
-            <div className="p-4 border rounded-lg">
-              <h3 className="font-semibold mb-2">1. Setup</h3>
-              <p className="text-sm text-muted-foreground">
-                Initialize the proxy by minting 10 auth tokens. These tokens are sent to your multisig wallet.
-              </p>
-            </div>
-            <div className="p-4 border rounded-lg">
-              <h3 className="font-semibold mb-2">2. Control</h3>
-              <p className="text-sm text-muted-foreground">
-                Use auth tokens to authorize spending from the proxy address. Each spend consumes one auth token.
-              </p>
-            </div>
-            <div className="p-4 border rounded-lg">
-              <h3 className="font-semibold mb-2">3. Automate</h3>
-              <p className="text-sm text-muted-foreground">
-                The proxy can hold assets and execute transactions automatically when properly authorized.
-              </p>
-            </div>
-          </div>
-        </CardContent>
-      </Card>
-
-      <ProxyControl />
-
-      <Card>
-        <CardHeader>
-          <CardTitle>Integration Example</CardTitle>
-          <CardDescription>
-            How to use the ProxyControl component in your application
-          </CardDescription>
-        </CardHeader>
-        <CardContent>
-          <div className="space-y-4">
-            <h3 className="font-semibold">Basic Usage</h3>
-            <pre className="bg-muted p-4 rounded-lg text-sm overflow-x-auto">
-{`import ProxyControl from "@/components/multisig/proxy/ProxyControl";
-
-export default function MyPage() {
-  return (
-    <div>
-      <h1>My Proxy Management</h1>
-      <ProxyControl />
-    </div>
-  );
-}`}
-            </pre>
-
-            <h3 className="font-semibold">Key Features</h3>
-            <ul className="list-disc list-inside space-y-2 text-sm text-muted-foreground">
-              <li>Automatic wallet connection detection</li>
-              <li>Proxy setup with auth token minting</li>
-              <li>Real-time balance monitoring</li>
-              <li>Multi-output spending capabilities</li>
-              <li>Integration with multisig transaction system</li>
-              <li>Error handling and loading states</li>
-              <li>Responsive design for mobile and desktop</li>
-            </ul>
-          </div>
-        </CardContent>
-      </Card>
-    </div>
-  );
-}
-
-
-
diff --git a/src/components/multisig/proxy/index.ts b/src/components/multisig/proxy/index.ts
index e7c46daa..c328f688 100644
--- a/src/components/multisig/proxy/index.ts
+++ b/src/components/multisig/proxy/index.ts
@@ -1,3 +1,2 @@
 export { default as ProxyControl } from "./ProxyControl";
-export { default as ProxyControlExample } from "./ProxyControlExample";
 export { MeshProxyContract } from "./offchain";
\ No newline at end of file
diff --git a/src/components/pages/user/BotManagementCard.tsx b/src/components/pages/user/BotManagementCard.tsx
index fd1eca27..d8db60c1 100644
--- a/src/components/pages/user/BotManagementCard.tsx
+++ b/src/components/pages/user/BotManagementCard.tsx
@@ -1,5 +1,3 @@
-"use client";
-
 import { useState } from "react";
 import { Bot, Trash2, Loader2, Pencil, Link } from "lucide-react";
 import CardUI from "@/components/ui/card-content";
diff --git a/src/components/pages/wallet/info/signers/card-show-signers.tsx b/src/components/pages/wallet/info/signers/card-show-signers.tsx
index a5097a89..e950e12e 100644
--- a/src/components/pages/wallet/info/signers/card-show-signers.tsx
+++ b/src/components/pages/wallet/info/signers/card-show-signers.tsx
@@ -155,24 +155,18 @@ export default function ShowSigners({ appWallet }: ShowSignersProps) {
       }
     }
 
-    function handleConnectDiscord() {
-      // Discord OAuth2 URL with required scopes
-      const DISCORD_CLIENT_ID = process.env.NEXT_PUBLIC_DISCORD_CLIENT_ID;
-      const redirectUri = encodeURIComponent(
-        `${process.env.NODE_ENV === "production" ? "https://multisig.meshjs.dev" : "http://localhost:3000"}/api/auth/discord/callback`,
-      );
-      const scope = encodeURIComponent("identify");
-      const state = encodeURIComponent(userAddress || "");
-
-      const url = `https://discord.com/api/oauth2/authorize?client_id=${DISCORD_CLIENT_ID}&redirect_uri=${redirectUri}&response_type=code&scope=${scope}&state=${state}`;
-      console.log({
-        endpoint: "https://discord.com/api/oauth2/token",
-        client_id: process.env.NEXT_PUBLIC_DISCORD_CLIENT_ID,
-        client_secret_set: !!process.env.DISCORD_CLIENT_SECRET,
-        redirect_uri: redirectUri,
-        grant_type: "authorization_code",
-      });
-      window.location.href = url;
+    async function handleConnectDiscord() {
+      try {
+        const r = await fetch("/api/auth/discord/start", { credentials: "include" });
+        if (!r.ok) {
+          throw new Error("Failed to start Discord auth");
+        }
+        const data = (await r.json()) as { url?: string };
+        if (!data.url) throw new Error("No Discord auth URL");
+        window.location.href = data.url;
+      } catch (err) {
+        console.error("Discord auth start failed:", err instanceof Error ? err.message : err);
+      }
     }
 
     return appWallet.signersAddresses.map((address, index) => {
diff --git a/src/components/pages/wallet/signing/index.tsx b/src/components/pages/wallet/signing/index.tsx
index 590894ad..fe878b4c 100644
--- a/src/components/pages/wallet/signing/index.tsx
+++ b/src/components/pages/wallet/signing/index.tsx
@@ -86,7 +86,7 @@ export default function WalletSigning() {
     const signedAddresses = [];
     signedAddresses.push(userAddress);
     const signatures = [];
-    signatures.push(`signature: ${signature.signature}, key: ${signature.key}`);
+    signatures.push(JSON.stringify({ signature: signature.signature, key: signature.key }));
 
     let submitTx = false;
 
diff --git a/src/components/pages/wallet/signing/signable-card.tsx b/src/components/pages/wallet/signing/signable-card.tsx
index e7fed787..8f50c14c 100644
--- a/src/components/pages/wallet/signing/signable-card.tsx
+++ b/src/components/pages/wallet/signing/signable-card.tsx
@@ -185,7 +185,7 @@ function SignableCard({
 
       const signatures = signable.signatures;
       signatures.push(
-        `signature: ${signature.signature}, key: ${signature.key}`,
+        JSON.stringify({ signature: signature.signature, key: signature.key }),
       );
 
       let submitTx = false;
@@ -342,9 +342,22 @@ function SignableCard({
                 </TableHeader>
                 <TableBody>
                   {signable.signatures.map((sigStr, idx) => {
-                    const [sigPart = "", keyPart = ""] =
-                      sigStr.split(", key: ");
-                    const signature = sigPart.replace("signature: ", "");
+                    // New format: JSON {signature, key}.
+                    // Legacy format: "signature: <sig>, key: <key>".
+                    let signature = "";
+                    let keyPart = "";
+                    try {
+                      const parsed = JSON.parse(sigStr) as {
+                        signature?: unknown;
+                        key?: unknown;
+                      };
+                      if (typeof parsed.signature === "string") signature = parsed.signature;
+                      if (typeof parsed.key === "string") keyPart = parsed.key;
+                    } catch {
+                      const [sigPart = "", k = ""] = sigStr.split(", key: ");
+                      signature = sigPart.replace("signature: ", "");
+                      keyPart = k;
+                    }
                     return (
                       <TableRow key={idx}>
                         <TableCell>
diff --git a/src/components/pages/wallet/transactions/transaction-card.tsx b/src/components/pages/wallet/transactions/transaction-card.tsx
index 051a0d2f..402b39bc 100644
--- a/src/components/pages/wallet/transactions/transaction-card.tsx
+++ b/src/components/pages/wallet/transactions/transaction-card.tsx
@@ -53,7 +53,6 @@ import {
   CollapsibleContent,
   CollapsibleTrigger,
 } from "@/components/ui/collapsible";
-import { get } from "http";
 import { getProvider } from "@/utils/get-provider";
 import { useSiteStore } from "@/lib/zustand/site";
 import {
@@ -73,7 +72,7 @@ export default function TransactionCard({
   const { activeWallet, isWalletReady, isAnyWalletConnected } = useActiveWallet();
   const { appWallet } = useAppWallet();
   const userAddress = useUserStore((state) => state.userAddress);
-  const txJson = JSON.parse(transaction.txJson);
+  const txJson = useMemo(() => JSON.parse(transaction.txJson), [transaction.txJson]);
   const [loading, setLoading] = useState<boolean>(false);
   const [isSignersOpen, setIsSignersOpen] = useState<boolean>(false);
   const { toast } = useToast();
diff --git a/src/components/ui/background.tsx b/src/components/ui/background.tsx
index c7f3a2b5..0263d98d 100644
--- a/src/components/ui/background.tsx
+++ b/src/components/ui/background.tsx
@@ -1,5 +1,3 @@
-"use client"
-
 import * as React from "react"
 import { cva, type VariantProps } from "class-variance-authority"
 import { cn } from "@/lib/utils"
diff --git a/src/hooks/useAppWallet.ts b/src/hooks/useAppWallet.ts
index 36248bc2..5555181b 100644
--- a/src/hooks/useAppWallet.ts
+++ b/src/hooks/useAppWallet.ts
@@ -1,3 +1,4 @@
+import { useMemo } from "react";
 import { useUserStore } from "@/lib/zustand/user";
 import { api } from "@/utils/api";
 import { buildWallet } from "@/utils/common";
@@ -21,9 +22,11 @@ export default function useAppWallet() {
     },
   );
 
-  if (wallet) {
-    return { appWallet: buildWallet(wallet as DbWalletWithLegacy, network, walletsUtxos[walletId]), isLoading };
-  }
+  const utxos = walletsUtxos[walletId];
+  const appWallet = useMemo(() => {
+    if (!wallet) return undefined;
+    return buildWallet(wallet as DbWalletWithLegacy, network, utxos);
+  }, [wallet, network, utxos]);
 
-  return { appWallet: undefined, isLoading };
+  return { appWallet, isLoading };
 }
diff --git a/src/hooks/useMultisigWallet.ts b/src/hooks/useMultisigWallet.ts
index 5e05a2f5..8a1c9d67 100644
--- a/src/hooks/useMultisigWallet.ts
+++ b/src/hooks/useMultisigWallet.ts
@@ -1,3 +1,4 @@
+import { useMemo } from "react";
 import { useRouter } from "next/router";
 
 import { api } from "@/utils/api";
@@ -19,9 +20,11 @@ export default function useMultisigWallet() {
       enabled: walletId !== undefined && userAddress !== undefined,
     },
   );
-  if (wallet) {
-    return { multisigWallet: buildMultisigWallet(wallet as DbWalletWithLegacy, network), wallet, isLoading };
-  }
 
-  return { multisigWallet: undefined, wallet: undefined, isLoading };
+  const multisigWallet = useMemo(() => {
+    if (!wallet) return undefined;
+    return buildMultisigWallet(wallet as DbWalletWithLegacy, network);
+  }, [wallet, network]);
+
+  return { multisigWallet, wallet, isLoading };
 }

From a6345250ca2b765d2bc6d8707b0b1bfa73a56efd Mon Sep 17 00:00:00 2001
From: Jingles <jinglescode@gmail.com>
Date: Sun, 10 May 2026 16:50:23 +0800
Subject: [PATCH 07/10] fix(wallet-assets): show actual IPFS NFT image instead
 of hardcoded CID
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The IPFS branch of the asset card was passing a single hardcoded ipfs://
literal to <IPFSImage>, so every IPFS-based NFT in the wallet rendered
the same placeholder image instead of its own metadata.image. The
non-IPFS sibling already uses imageSrc / name / 60x60 correctly; this
brings the IPFS branch in line.

Also fixes:
- alt text now uses the asset name (was "IPFS Image" — bad a11y)
- width/height set to 60 to match the parent 60x60 div (was 300, was
  being clipped by overflow-hidden + wasting bandwidth)

Single occurrence in the codebase. Introduced 2025-03-27.
---
 src/components/pages/wallet/assets/wallet-assets.tsx | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/src/components/pages/wallet/assets/wallet-assets.tsx b/src/components/pages/wallet/assets/wallet-assets.tsx
index 8f10dfb6..a6a458d0 100644
--- a/src/components/pages/wallet/assets/wallet-assets.tsx
+++ b/src/components/pages/wallet/assets/wallet-assets.tsx
@@ -84,12 +84,10 @@ export default function WalletAssets({ appWallet }: { appWallet: Wallet }) {
               >
                 {isImageIpfs ? (
                   <IPFSImage
-                    src={
-                      "ipfs://QmSNkaU4DW3asABKyUfSx3ykFAtV5PuXLsXu63nMUo8HGv"
-                    }
-                    alt="IPFS Image"
-                    width={300}
-                    height={300}
+                    src={imageSrc}
+                    alt={name}
+                    width={60}
+                    height={60}
                   />
                 ) : (
                   <Image

From f6d9cfe5063d008e675ea0ba376d46d10996206d Mon Sep 17 00:00:00 2001
From: Jingles <jinglescode@gmail.com>
Date: Sun, 10 May 2026 16:53:41 +0800
Subject: [PATCH 08/10] chore(proxy): remove three write-only useState
 declarations

ProxyControl had three state variables whose values were never read,
only their setters. Calling them produced empty re-renders.

- setLocalLoading: paralleled setSetupLoading and setSpendLoading; the
  read-side `setupLoading` and `spendLoading` are the live signals
- setSelectedUtxos / setManualSelected: stored values from the UTxO
  selector callback that nothing downstream consumed; the contract
  already uses all UTxOs from the multisig wallet (per existing
  comment), so the selection is purely visual

The UTxOSelector callback is preserved as a no-op (the prop is
required) with a comment explaining the visual-only intent.

Net -11 lines, zero behavior change.
---
 .../multisig/proxy/ProxyControl.tsx           | 19 ++++---------------
 1 file changed, 4 insertions(+), 15 deletions(-)

diff --git a/src/components/multisig/proxy/ProxyControl.tsx b/src/components/multisig/proxy/ProxyControl.tsx
index e575086f..220d831b 100644
--- a/src/components/multisig/proxy/ProxyControl.tsx
+++ b/src/components/multisig/proxy/ProxyControl.tsx
@@ -122,7 +122,6 @@ export default function ProxyControl() {
   // State management
   const [proxyContract, setProxyContract] = useState<MeshProxyContract | null>(null);
   const [isProxySetup, setIsProxySetup] = useState<boolean>(false);
-  const [, setLocalLoading] = useState<boolean>(false);
   const [tvlLoading, setTvlLoading] = useState<boolean>(false);
 
   // Setup flow state
@@ -149,10 +148,6 @@ export default function ProxyControl() {
     { address: "", unit: "lovelace", amount: "" }
   ]);
 
-  // UTxO selection state (UI only). We will still pass all UTxOs from provider to contract.
-  const [, setSelectedUtxos] = useState<UTxO[]>([]);
-  const [, setManualSelected] = useState<boolean>(false);
-
   // Helper to resolve inputs for multisig controlled txs
   const getMsInputs = useCallback(async (): Promise<{ utxos: UTxO[]; walletAddress: string }> => {
     if (!appWallet?.address) {
@@ -264,8 +259,7 @@ export default function ProxyControl() {
 
     try {
       setSetupLoading(true);
-      setLocalLoading(true);
-      
+
       // Reset setup data to prevent conflicts with previous attempts
       setSetupData({});
       setSetupStep(0);
@@ -301,7 +295,6 @@ export default function ProxyControl() {
       });
     } finally {
       setSetupLoading(false);
-      setLocalLoading(false);
     }
   }, [proxyContract, isWalletReady, getMsInputs, newTransaction, toast]);
 
@@ -318,7 +311,6 @@ export default function ProxyControl() {
 
     try {
       setSetupLoading(true);
-      setLocalLoading(true);
 
       // If msCbor is set, route through useTransaction hook to create a signable
       if (appWallet?.scriptCbor && setupData.txHex) {
@@ -395,7 +387,6 @@ export default function ProxyControl() {
       });
     } finally {
       setSetupLoading(false);
-      setLocalLoading(false);
     }
   }, [setupData, activeWallet, appWallet, createProxy, refetchProxies, getMsInputs, newTransaction, userAddress, toast]);
 
@@ -600,7 +591,6 @@ export default function ProxyControl() {
 
     try {
       setSpendLoading(true);
-      setLocalLoading(true);
 
       // Get the selected proxy
       const proxy = proxies?.find((p: { id: string }) => p.id === selectedProxyId);
@@ -672,7 +662,6 @@ export default function ProxyControl() {
       });
     } finally {
       setSpendLoading(false);
-      setLocalLoading(false);
     }
   }, [proxyContract, isWalletReady, spendOutputs, selectedProxyId, proxies, network, activeWallet, handleProxySelection, getMsInputs, newTransaction, appWallet?.scriptCbor, toast]);
 
@@ -840,9 +829,9 @@ export default function ProxyControl() {
                   <UTxOSelector
                     appWallet={appWallet}
                     network={network}
-                    onSelectionChange={(utxos, manual) => {
-                      setSelectedUtxos(utxos);
-                      setManualSelected(manual);
+                    onSelectionChange={() => {
+                      // Selection is for user visibility only;
+                      // contract uses all UTxOs from the multisig wallet.
                     }}
                   />
                 </div>

From 39a0c9be7a9da404b6e31e501268aac067d1c1d5 Mon Sep 17 00:00:00 2001
From: Jingles <jinglescode@gmail.com>
Date: Sun, 10 May 2026 20:33:45 +0800
Subject: [PATCH 09/10] chore: remove Nostr chat system

Removes the Nostr-based wallet chat that was throwing
`wss://relay.damus.io/` WebSocket errors. Drops the
@jinglescode/nostr-chat-plugin dependency along with the chat page,
component, sidebar link, and homepage feature card.

Server-side: removes nostrKey from createUser input and deletes the
unused getNostrKeysByAddresses procedure. Adds a migration making
User.nostrKey nullable so new signups insert without a key (existing
rows preserved).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md                                     |  11 +-
 package-lock.json                             |  58 -----
 package.json                                  |   1 -
 .../migration.sql                             |   2 +
 prisma/schema.prisma                          |  12 +-
 .../common/cardano-objects/connect-wallet.tsx |   6 +-
 .../common/overall-layout/layout.tsx          |   7 +-
 .../overall-layout/menus/multisig-wallet.tsx  |  10 -
 src/components/pages/homepage/index.tsx       |  16 --
 src/components/pages/wallet/chat/index.tsx    | 209 ------------------
 src/pages/README.md                           |   8 +-
 src/pages/_app.tsx                            |  19 +-
 src/pages/user/index.tsx                      |  32 ---
 src/pages/wallets/[wallet]/chat/index.tsx     |   7 -
 src/server/api/routers/users.ts               |  21 +-
 tasks/wishlist/Task_02_UserPage.md            |   1 -
 16 files changed, 25 insertions(+), 395 deletions(-)
 create mode 100644 prisma/migrations/20260510170000_make_user_nostrkey_optional/migration.sql
 delete mode 100644 src/components/pages/wallet/chat/index.tsx
 delete mode 100644 src/pages/wallets/[wallet]/chat/index.tsx

diff --git a/README.md b/README.md
index efee7585..bf2eb9da 100644
--- a/README.md
+++ b/README.md
@@ -37,7 +37,6 @@ A comprehensive, enterprise-grade multi-signature wallet solution built on Carda
 - Secure multi-sig staking operations
 
 ### Collaboration
-- Real-time Nostr-based chat
 - Discord integration for notifications
 - Signer verification via message signing
 - Automated transaction alerts
@@ -188,11 +187,11 @@ graph TD
 ### Database Schema
 ```prisma
 model User {
-  id           String @id @default(cuid())
-  address      String @unique
-  stakeAddress String @unique
-  nostrKey     String @unique
-  discordId    String @default("")
+  id           String  @id @default(cuid())
+  address      String  @unique
+  stakeAddress String  @unique
+  nostrKey     String? @unique
+  discordId    String  @default("")
 }
 
 model Wallet {
diff --git a/package-lock.json b/package-lock.json
index 9ee7a9b0..277b7631 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -10,7 +10,6 @@
       "hasInstallScript": true,
       "dependencies": {
         "@auth/prisma-adapter": "^2.11.1",
-        "@jinglescode/nostr-chat-plugin": "^0.0.11",
         "@meshsdk/core": "^1.9.0-beta.87",
         "@meshsdk/core-csl": "^1.9.0-beta.87",
         "@meshsdk/core-cst": "^1.9.0-beta.87",
@@ -2329,17 +2328,6 @@
         "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
       }
     },
-    "node_modules/@jinglescode/nostr-chat-plugin": {
-      "version": "0.0.11",
-      "resolved": "https://registry.npmjs.org/@jinglescode/nostr-chat-plugin/-/nostr-chat-plugin-0.0.11.tgz",
-      "integrity": "sha512-teAjUTPqbfI353M+Ip/QcT7LnA4VpUh4jHbbo0xryhajAXlNIYpUDs5bbTa0M4IroU/aMA65Ba8iaqhIta0D0g==",
-      "dependencies": {
-        "nostr-tools": "^2.8.0"
-      },
-      "peerDependencies": {
-        "react": ">=17.0.0"
-      }
-    },
     "node_modules/@jridgewell/gen-mapping": {
       "version": "0.3.13",
       "resolved": "https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.3.13.tgz",
@@ -16300,52 +16288,6 @@
         "node": ">=0.10.0"
       }
     },
-    "node_modules/nostr-tools": {
-      "version": "2.23.3",
-      "resolved": "https://registry.npmjs.org/nostr-tools/-/nostr-tools-2.23.3.tgz",
-      "integrity": "sha512-AALyt9k8xPdF4UV2mlLJ2mgCn4kpTB0DZ8t2r6wjdUh6anfx2cTVBsHUlo9U0EY/cKC5wcNyiMAmRJV5OVEalA==",
-      "dependencies": {
-        "@noble/ciphers": "2.1.1",
-        "@noble/curves": "2.0.1",
-        "@noble/hashes": "2.0.1",
-        "@scure/base": "2.0.0",
-        "@scure/bip32": "2.0.1",
-        "@scure/bip39": "2.0.1",
-        "nostr-wasm": "0.1.0"
-      },
-      "peerDependencies": {
-        "typescript": ">=5.0.0"
-      },
-      "peerDependenciesMeta": {
-        "typescript": {
-          "optional": true
-        }
-      }
-    },
-    "node_modules/nostr-tools/node_modules/@noble/hashes": {
-      "version": "2.0.1",
-      "resolved": "https://registry.npmjs.org/@noble/hashes/-/hashes-2.0.1.tgz",
-      "integrity": "sha512-XlOlEbQcE9fmuXxrVTXCTlG2nlRXa9Rj3rr5Ue/+tX+nmkgbX720YHh0VR3hBF9xDvwnb8D2shVGOwNx+ulArw==",
-      "engines": {
-        "node": ">= 20.19.0"
-      },
-      "funding": {
-        "url": "https://paulmillr.com/funding/"
-      }
-    },
-    "node_modules/nostr-tools/node_modules/@scure/base": {
-      "version": "2.0.0",
-      "resolved": "https://registry.npmjs.org/@scure/base/-/base-2.0.0.tgz",
-      "integrity": "sha512-3E1kpuZginKkek01ovG8krQ0Z44E3DHPjc5S2rjJw9lZn3KSQOs8S7wqikF/AH7iRanHypj85uGyxk0XAyC37w==",
-      "funding": {
-        "url": "https://paulmillr.com/funding/"
-      }
-    },
-    "node_modules/nostr-wasm": {
-      "version": "0.1.0",
-      "resolved": "https://registry.npmjs.org/nostr-wasm/-/nostr-wasm-0.1.0.tgz",
-      "integrity": "sha512-78BTryCLcLYv96ONU8Ws3Q1JzjlAt+43pWQhIl86xZmWeegYCNLPml7yQ+gG3vR6V5h4XGj+TxO+SS5dsThQIA=="
-    },
     "node_modules/npm": {
       "version": "9.9.4",
       "resolved": "https://registry.npmjs.org/npm/-/npm-9.9.4.tgz",
diff --git a/package.json b/package.json
index f72acf6f..61411188 100644
--- a/package.json
+++ b/package.json
@@ -28,7 +28,6 @@
   },
   "dependencies": {
     "@auth/prisma-adapter": "^2.11.1",
-    "@jinglescode/nostr-chat-plugin": "^0.0.11",
     "@meshsdk/core": "^1.9.0-beta.87",
     "@meshsdk/core-csl": "^1.9.0-beta.87",
     "@meshsdk/core-cst": "^1.9.0-beta.87",
diff --git a/prisma/migrations/20260510170000_make_user_nostrkey_optional/migration.sql b/prisma/migrations/20260510170000_make_user_nostrkey_optional/migration.sql
new file mode 100644
index 00000000..7d33c422
--- /dev/null
+++ b/prisma/migrations/20260510170000_make_user_nostrkey_optional/migration.sql
@@ -0,0 +1,2 @@
+-- AlterTable
+ALTER TABLE "User" ALTER COLUMN "nostrKey" DROP NOT NULL;
diff --git a/prisma/schema.prisma b/prisma/schema.prisma
index 92387e35..537b6f34 100644
--- a/prisma/schema.prisma
+++ b/prisma/schema.prisma
@@ -16,12 +16,12 @@ datasource db {
 }
 
 model User {
-  id           String @id @default(cuid())
-  address      String @unique
-  stakeAddress String @unique
-  drepKeyHash  String @default("")
-  nostrKey     String @unique
-  discordId    String @default("")
+  id           String  @id @default(cuid())
+  address      String  @unique
+  stakeAddress String  @unique
+  drepKeyHash  String  @default("")
+  nostrKey     String? @unique
+  discordId    String  @default("")
 }
 
 model Wallet {
diff --git a/src/components/common/cardano-objects/connect-wallet.tsx b/src/components/common/cardano-objects/connect-wallet.tsx
index a9919c3e..d228fc7d 100644
--- a/src/components/common/cardano-objects/connect-wallet.tsx
+++ b/src/components/common/cardano-objects/connect-wallet.tsx
@@ -26,7 +26,6 @@ import {
 } from "@meshsdk/core";
 import useUTXOS from "@/hooks/useUTXOS";
 import { api } from "@/utils/api";
-import { useNostrChat } from "@jinglescode/nostr-chat-plugin";
 import { useWalletContext, WalletState } from "@/hooks/useWalletContext";
 import { useToast } from "@/hooks/use-toast";
 import { cn } from "@/lib/utils";
@@ -103,7 +102,6 @@ function ConnectWalletContent({
     (state) => state.setUserAssetMetadata,
   );
   const { user, isLoading: isUserLoading } = useUser();
-  const { generateNsec } = useNostrChat();
   const userAddress = useUserStore((state) => state.userAddress);
   const setUserAddress = useUserStore((state) => state.setUserAddress);
   const { toast } = useToast();
@@ -472,12 +470,10 @@ function ConnectWalletContent({
 
         // 4) Create or update user (same as normal wallet)
         if (!isUserLoading) {
-          const nostrKey = generateNsec();
           createUser({
             address,
             stakeAddress,
             drepKeyHash,
-            nostrKey: JSON.stringify(nostrKey),
           });
         }
 
@@ -487,7 +483,7 @@ function ConnectWalletContent({
         utxosInitializedRef.current = false;
       }
     })();
-  }, [isUtxosEnabled, utxosWallet, isUserLoading, createUser, generateNsec, setUserAddress, netId]);
+  }, [isUtxosEnabled, utxosWallet, isUserLoading, createUser, setUserAddress, netId]);
 
   // Handle UTXOS wallet assets and network
   useEffect(() => {
diff --git a/src/components/common/overall-layout/layout.tsx b/src/components/common/overall-layout/layout.tsx
index 9f6585c3..3efd643d 100644
--- a/src/components/common/overall-layout/layout.tsx
+++ b/src/components/common/overall-layout/layout.tsx
@@ -1,7 +1,6 @@
 import React, { useEffect, Component, ReactNode, useMemo, useCallback, useState, useRef } from "react";
 import { useRouter } from "next/router";
 import Link from "next/link";
-import { useNostrChat } from "@jinglescode/nostr-chat-plugin";
 import { useWallet, useAddress } from "@meshsdk/react";
 import { publicRoutes } from "@/data/public-routes";
 import { api } from "@/utils/api";
@@ -106,7 +105,6 @@ export default function RootLayout({
   const router = useRouter();
   const { appWallet } = useAppWallet();
   const { multisigWallet } = useMultisigWallet();
-  const { generateNsec } = useNostrChat();
   const { isEnabled: isUtxosEnabled } = useUTXOS();
 
   const userAddress = useUserStore((state) => state.userAddress);
@@ -179,7 +177,6 @@ export default function RootLayout({
             address: variables.address,
             stakeAddress: variables.stakeAddress,
             drepKeyHash: variables.drepKeyHash ?? "",
-            nostrKey: variables.nostrKey,
           }
         );
       }
@@ -311,12 +308,10 @@ export default function RootLayout({
         }
 
         // Create or update user
-        const nostrKey = generateNsec();
         createUser({
           address: walletAddress,
           stakeAddress,
           drepKeyHash,
-          nostrKey: JSON.stringify(nostrKey),
         });
       } catch (error) {
         if (error instanceof Error && error.message.includes("account changed")) {
@@ -326,7 +321,7 @@ export default function RootLayout({
     }
     
     initializeWallet();
-  }, [connected, activeWallet, user, userAddress, address, createUser, generateNsec]);
+  }, [connected, activeWallet, user, userAddress, address, createUser]);
 
   // Check wallet session and show authorization modal for first-time connections
   // Check session as soon as wallet is connected and address is available (don't wait for user)
diff --git a/src/components/common/overall-layout/menus/multisig-wallet.tsx b/src/components/common/overall-layout/menus/multisig-wallet.tsx
index 4a29fdbc..24148ff5 100644
--- a/src/components/common/overall-layout/menus/multisig-wallet.tsx
+++ b/src/components/common/overall-layout/menus/multisig-wallet.tsx
@@ -3,7 +3,6 @@ import { useRouter } from "next/router";
 import MenuLink from "./menu-link";
 import usePendingTransactions from "@/hooks/usePendingTransactions";
 import { Badge } from "@/components/ui/badge";
-import { ChatBubbleIcon } from "@radix-ui/react-icons";
 import usePendingSignables from "@/hooks/usePendingSignables";
 import useMultisigWallet from "@/hooks/useMultisigWallet";
 
@@ -101,15 +100,6 @@ export default function MenuWallet({ walletId, stakingEnabled }: MenuWalletProps
           <Banknote className="h-5 w-5" />
           Assets
         </MenuLink>
-        <MenuLink
-          href={`${baseUrl}chat`}
-          className={
-            router.pathname == "/wallets/[wallet]/chat" ? "text-white" : ""
-          }
-        >
-          <ChatBubbleIcon className="h-5 w-5" />
-          Chat
-        </MenuLink>
         <MenuLink
           href={`${baseUrl}dapps`}
           className={
diff --git a/src/components/pages/homepage/index.tsx b/src/components/pages/homepage/index.tsx
index da2fdd4e..3597dc4d 100644
--- a/src/components/pages/homepage/index.tsx
+++ b/src/components/pages/homepage/index.tsx
@@ -331,22 +331,6 @@ export function PageHomepage() {
               </div>
             </CardUI>
 
-            {/* Chat and Collaborate */}
-            <CardUI
-              title="Chat and Collaborate"
-              description="Built-in Nostr chat to discuss transactions and governance with your team"
-              cardClassName="overflow-hidden"
-            >
-              <div className="mt-4 rounded-lg border border-border p-2">
-                <Image
-                  src="/features/chat.png"
-                  alt="Team chat"
-                  width={400}
-                  height={300}
-                  className="h-auto w-full rounded object-contain"
-                />
-              </div>
-            </CardUI>
           </div>
         </div>
       </section>
diff --git a/src/components/pages/wallet/chat/index.tsx b/src/components/pages/wallet/chat/index.tsx
deleted file mode 100644
index 37a084be..00000000
--- a/src/components/pages/wallet/chat/index.tsx
+++ /dev/null
@@ -1,209 +0,0 @@
-import Button from "@/components/common/button";
-import { Label } from "@/components/ui/label";
-import { Textarea } from "@/components/ui/textarea";
-import useAppWallet from "@/hooks/useAppWallet";
-import useUser from "@/hooks/useUser";
-import { useNostrChat } from "@jinglescode/nostr-chat-plugin";
-import { CornerDownLeft } from "lucide-react";
-import { useEffect, useRef, useState } from "react";
-import { api } from "@/utils/api";
-import { AnimatePresence, motion } from "framer-motion";
-
-export default function WalletChat() {
-  const { appWallet } = useAppWallet();
-  const { user } = useUser();
-  const messagesContainerRef = useRef<HTMLDivElement>(null);
-  const [pubkey, setPubkey] = useState<string | undefined>(undefined);
-  const [connecting, setConnecting] = useState<boolean>(false);
-  const [textareaValue, setTextareaValue] = useState<string>("");
-  const [usersPubkeyToName, setUsersPubkeyToName] = useState<
-    {
-      pubkey: any;
-      address: string;
-      name: string | undefined;
-    }[]
-  >([]);
-
-  const { data: nostrUsers } = api.user.getNostrKeysByAddresses.useQuery(
-    {
-      addresses: appWallet ? appWallet.signersAddresses : [],
-    },
-    {
-      enabled: appWallet !== undefined,
-    },
-  );
-
-  const { subscribeRoom, messages, publishMessage, setUser, roomId } =
-    useNostrChat();
-
-  useEffect(() => {
-    if (messagesContainerRef.current) {
-      messagesContainerRef.current.scrollTop =
-        messagesContainerRef.current.scrollHeight;
-    }
-  }, [messages]);
-
-  useEffect(() => {
-    async function load() {
-      if (appWallet && roomId != appWallet.id && !connecting) {
-        setConnecting(true);
-        subscribeRoom(appWallet.id);
-      }
-    }
-    load();
-  }, [appWallet]);
-
-  useEffect(() => {
-    if (user && appWallet && nostrUsers && usersPubkeyToName.length === 0) {
-      const _nostrUsers = nostrUsers.map((user) => {
-        return {
-          pubkey: JSON.parse(user.nostrKey).pubkey,
-          address: user.address,
-          name: appWallet.signersDescriptions[
-            appWallet.signersAddresses.indexOf(user.address)
-          ],
-        };
-      });
-      setUsersPubkeyToName(_nostrUsers);
-
-      const { nsec, pubkey } = JSON.parse(user.nostrKey);
-      setPubkey(pubkey);
-      setUser({ nsec, pubkey });
-    }
-  }, [user, appWallet, nostrUsers]);
-
-  function handleSend() {
-    publishMessage(textareaValue);
-    setTextareaValue("");
-  }
-
-  const handleKeyPress = (event: React.KeyboardEvent<HTMLTextAreaElement>) => {
-    if (event.key === "Enter" && !event.shiftKey) {
-      event.preventDefault();
-      handleSend();
-    }
-    if (event.key === "Enter" && event.shiftKey) {
-      event.preventDefault();
-      setTextareaValue((prev) => prev + "\n");
-    }
-  };
-
-  if (appWallet === undefined) return <></>;
-  return (
-    <main className="flex h-[calc(100vh-60px)] flex-1 flex-col gap-4 md:gap-8">
-      <div className="relative flex h-full min-h-[50vh] flex-col rounded-xl bg-muted/50 p-4 lg:col-span-2">
-        <div
-          className="flex flex-col gap-2 overflow-y-auto pr-2"
-          ref={messagesContainerRef}
-        >
-          <AnimatePresence>
-            {messages &&
-              messages.length > 0 &&
-              [...new Set(messages)]
-                .sort((a, b) => a.timestamp - b.timestamp)
-                .map((msg) => (
-                  <motion.div
-                    key={msg.id}
-                    layout
-                    initial={{ opacity: 0, scale: 1, y: 50, x: 0 }}
-                    animate={{ opacity: 1, scale: 1, y: 0, x: 0 }}
-                    exit={{ opacity: 0, scale: 1, y: 1, x: 0 }}
-                    transition={{
-                      opacity: { duration: 0.1 },
-                      layout: {
-                        type: "spring",
-                        bounce: 0.3,
-                        duration: messages.indexOf(msg) * 0.05 + 0.2,
-                      },
-                    }}
-                    style={{
-                      originX: 0.5,
-                      originY: 0.5,
-                    }}
-                    className={`mb-2 max-w-xs rounded-lg p-2 ${
-                      msg.pubkey === pubkey
-                        ? "self-end bg-blue-500 text-white"
-                        : "self-start bg-gray-800"
-                    }`}
-                  >
-                    <div className="flex gap-2">
-                      {usersPubkeyToName.find((u) => u.pubkey === msg.pubkey)
-                        ?.name && (
-                        <p className="text-xs">
-                          {
-                            usersPubkeyToName.find(
-                              (u) => u.pubkey === msg.pubkey,
-                            )?.name
-                          }
-                        </p>
-                      )}
-                    </div>
-                    <pre>{msg.message}</pre>
-                    <p className="text-xs text-gray-300">
-                      {new Date(msg.timestamp * 1000).toLocaleString("en-US", {
-                        weekday: "short",
-                        year: "numeric",
-                        month: "short",
-                        day: "numeric",
-                        hour: "2-digit",
-                        minute: "2-digit",
-                      })}
-                    </p>
-                  </motion.div>
-                ))}
-          </AnimatePresence>
-        </div>
-
-        <div className="flex-1" />
-        <form
-          className="relative overflow-hidden rounded-lg border bg-background focus-within:ring-1 focus-within:ring-ring"
-          x-chunk="dashboard-03-chunk-1"
-        >
-          <Label htmlFor="message" className="sr-only">
-            Message
-          </Label>
-          <Textarea
-            id="message"
-            placeholder="Type your message here..."
-            className="min-h-12 resize-none border-0 p-3 shadow-none focus-visible:ring-0"
-            value={textareaValue}
-            onChange={(e) => setTextareaValue(e.target.value)}
-            onKeyDown={handleKeyPress}
-          />
-          <div className="flex items-center p-3 pt-0">
-            {/* <Tooltip>
-                  <TooltipTrigger asChild>
-                    <Button variant="ghost" size="icon">
-                      <Paperclip className="size-4" />
-                      <span className="sr-only">Attach file</span>
-                    </Button>
-                  </TooltipTrigger>
-                  <TooltipContent side="top">Attach File</TooltipContent>
-                </Tooltip>
-                <Tooltip>
-                  <TooltipTrigger asChild>
-                    <Button variant="ghost" size="icon">
-                      <Mic className="size-4" />
-                      <span className="sr-only">Use Microphone</span>
-                    </Button>
-                  </TooltipTrigger>
-                  <TooltipContent side="top">Use Microphone</TooltipContent>
-                </Tooltip> */}
-            <Button
-              size="sm"
-              className="ml-auto gap-1.5"
-              disabled={textareaValue.length < 1}
-              onClick={() => {
-                publishMessage(textareaValue);
-                setTextareaValue("");
-              }}
-            >
-              Send Message
-              <CornerDownLeft className="size-3.5" />
-            </Button>
-          </div>
-        </form>
-      </div>
-    </main>
-  );
-}
diff --git a/src/pages/README.md b/src/pages/README.md
index 91784047..849a066d 100644
--- a/src/pages/README.md
+++ b/src/pages/README.md
@@ -10,14 +10,13 @@ A comprehensive Next.js pages directory containing all application routes, API e
 - **Purpose**: Root application component with global providers and configuration
 - **Features**:
   - Global dark mode detection and theme management
-  - Provider setup (Mesh SDK, NextAuth, Nostr Chat)
+  - Provider setup (Mesh SDK, NextAuth)
   - Global styles and font configuration
   - Toast notifications and meta tags
   - tRPC integration for type-safe API calls
 - **Providers**:
   - `MeshProvider`: Cardano wallet integration
   - `SessionProvider`: NextAuth authentication
-  - `NostrChatProvider`: Decentralized chat functionality
 - **Styling**: Geist Sans font, global CSS, Mesh SDK styles, Swagger UI styles
 
 #### `_document.tsx`
@@ -93,10 +92,6 @@ A comprehensive Next.js pages directory containing all application routes, API e
 - **Purpose**: Wallet asset management
 - **Features**: View and manage wallet assets
 
-#### `wallets/[wallet]/chat/index.tsx`
-- **Purpose**: Wallet-specific chat interface
-- **Features**: Decentralized chat for wallet participants
-
 #### `wallets/[wallet]/dapps/index.tsx`
 - **Purpose**: DApp integration page
 - **Features**: Connect and interact with decentralized applications
@@ -368,7 +363,6 @@ export default function Page() {
 ### Blockchain Integration
 - **Mesh SDK**: Cardano wallet operations
 - **Blockfrost**: Blockchain data access
-- **Nostr**: Decentralized chat functionality
 
 ### Development Tools
 - **Swagger UI**: API documentation and testing
diff --git a/src/pages/_app.tsx b/src/pages/_app.tsx
index 774fb03c..ace2931d 100644
--- a/src/pages/_app.tsx
+++ b/src/pages/_app.tsx
@@ -18,7 +18,6 @@ import "@/styles/swagger-overrides.css";
 import { Toaster } from "@/components/ui/toaster";
 import Metatags from "@/components/ui/metatags";
 import RootLayout from "@/components/common/overall-layout/layout";
-import { NostrChatProvider } from "@jinglescode/nostr-chat-plugin";
 
 // MeshProvider pulls in dependencies that assume a browser/webpack env.
 // Load it client-side only (including its styles) to avoid SSR/runtime issues.
@@ -66,17 +65,15 @@ const MyApp: AppType<{ session: Session | null }> = ({
         />
       )}
       <SessionProvider session={session}>
-        <NostrChatProvider>
-          <div className={GeistSans.className}>
-            <div className="flex min-h-screen w-full flex-col">
-              <RootLayout>
-                <Component {...pageProps} />
-              </RootLayout>
-            </div>
-            <Toaster />
-            <Metatags />
+        <div className={GeistSans.className}>
+          <div className="flex min-h-screen w-full flex-col">
+            <RootLayout>
+              <Component {...pageProps} />
+            </RootLayout>
           </div>
-        </NostrChatProvider>
+          <Toaster />
+          <Metatags />
+        </div>
       </SessionProvider>
     </MeshProviderNoSSR>
   );
diff --git a/src/pages/user/index.tsx b/src/pages/user/index.tsx
index 887601dc..b9d78523 100644
--- a/src/pages/user/index.tsx
+++ b/src/pages/user/index.tsx
@@ -305,38 +305,6 @@ export default function UserInfoPage() {
                 Copy
               </Button>
             </div>
-            {user.nostrKey && (
-              <div className="flex flex-col gap-2 sm:flex-row sm:items-start sm:justify-between">
-                <div className="flex-1 min-w-0">
-                  <p className="text-sm font-medium mb-1">Nostr Key</p>
-                  <p className="text-xs text-muted-foreground font-mono">
-                    {(() => {
-                      try {
-                        const nostrKeyObj = JSON.parse(user.nostrKey);
-                        const nsec = nostrKeyObj.nsec || "";
-                        const pubkey = nostrKeyObj.pubkey || "";
-                        return (
-                          <span>
-                            {`{"nsec":"${getFirstAndLast(nsec, 10, 8)}","pubkey":"${getFirstAndLast(pubkey, 10, 8)}"}`}
-                          </span>
-                        );
-                      } catch {
-                        return getFirstAndLast(user.nostrKey, 20, 8);
-                      }
-                    })()}
-                  </p>
-                </div>
-                <Button
-                  variant="outline"
-                  size="sm"
-                  onClick={() => handleCopy(user.nostrKey, "Nostr Key")}
-                  className="flex-shrink-0 mt-1 sm:mt-0"
-                >
-                  <Copy className="h-4 w-4 mr-2" />
-                  Copy
-                </Button>
-              </div>
-            )}
           </div>
         </CardUI>
       </div>
diff --git a/src/pages/wallets/[wallet]/chat/index.tsx b/src/pages/wallets/[wallet]/chat/index.tsx
deleted file mode 100644
index 6f4d958d..00000000
--- a/src/pages/wallets/[wallet]/chat/index.tsx
+++ /dev/null
@@ -1,7 +0,0 @@
-import WalletChat from "@/components/pages/wallet/chat";
-
-export const getServerSideProps = () => ({ props: {} });
-
-export default function Page() {
-  return <WalletChat />;
-}
diff --git a/src/server/api/routers/users.ts b/src/server/api/routers/users.ts
index 4d2d8dca..01204540 100644
--- a/src/server/api/routers/users.ts
+++ b/src/server/api/routers/users.ts
@@ -25,7 +25,7 @@ export const userRouter = createTRPCRouter({
 
   // Onboarding upsert. Authenticated only — the session address must match
   // the address being created/updated to prevent any unauthenticated caller
-  // from creating User rows or overwriting another user's stake/nostr/drep keys.
+  // from creating User rows or overwriting another user's stake/drep keys.
   createUser: protectedProcedure
     .input(
       z.object({
@@ -33,7 +33,6 @@ export const userRouter = createTRPCRouter({
         stakeAddress: z.string().min(1, "stakeAddress required"),
         // DRep key hash is optional (not all wallets / networks expose it)
         drepKeyHash: z.string().optional().default(""),
-        nostrKey: z.string().min(1, "nostrKey required"),
       }),
     )
     .mutation(async ({ ctx, input }) => {
@@ -51,13 +50,11 @@ export const userRouter = createTRPCRouter({
         update: {
           stakeAddress: input.stakeAddress,
           drepKeyHash: input.drepKeyHash,
-          nostrKey: input.nostrKey,
         },
         create: {
           address: input.address,
           stakeAddress: input.stakeAddress,
           drepKeyHash: input.drepKeyHash,
-          nostrKey: input.nostrKey,
         },
       });
     }),
@@ -111,22 +108,6 @@ export const userRouter = createTRPCRouter({
       });
     }),
 
-  getNostrKeysByAddresses: publicProcedure
-    .input(z.object({ addresses: z.array(z.string().min(1)).min(1) }))
-    .query(async ({ ctx, input }) => {
-      return await ctx.db.user.findMany({
-        where: {
-          address: {
-            in: input.addresses,
-          },
-        },
-        select: {
-          address: true,
-          nostrKey: true,
-        },
-      });
-    }),
-
   unlinkDiscord: protectedProcedure
     .input(z.object({ address: z.string() }))
     .mutation(async ({ ctx, input }) => {
diff --git a/tasks/wishlist/Task_02_UserPage.md b/tasks/wishlist/Task_02_UserPage.md
index e83bb7ce..1427ed67 100644
--- a/tasks/wishlist/Task_02_UserPage.md
+++ b/tasks/wishlist/Task_02_UserPage.md
@@ -71,7 +71,6 @@ model User {
   id           String @id @default(cuid())
   address      String @unique
   stakeAddress String @unique
-  nostrKey     String @unique
   discordId    String @default("")
 }
 

From a02ad7973fb4a9cf138e352756dd67a859fe44cb Mon Sep 17 00:00:00 2001
From: QSchlegel <quirin.schlegel@icloud.com>
Date: Mon, 11 May 2026 22:23:25 +0200
Subject: [PATCH 10/10] feat: agent onboarding, governance overview, wallet
 transfer, ballot UX

- Bot onboarding for AI agents: public /bot-setup page, agent-readable
  /api/v1/botSetupGuide markdown endpoint, /llms.txt discovery, and a
  "Copy agent prompt" button on the user Bot accounts card so any AI
  agent pointed at the instance URL can register itself end-to-end.

- Cross-instance wallet transfer: new /api/v1/wallet/transfer/export
  (owner JWT) and /api/v1/wallet/transfer/import endpoints with a
  shared WalletTransferPayloadV1 type. UI exposes "Transfer wallet"
  on the wallet info page (download JSON or push directly to a remote
  instance URL, optional contacts/ballots payloads) and "Import
  Transfer" on the wallets list page. Imports land as NewWallet so the
  existing invite/claim flow takes over.

- Governance overview improvements:
  - Wallet governance dashboard summary card (proposal status counts,
    ballot progress, voting power, last ballot activity)
  - Live network stats strip on the public /governance landing
  - DRep list aggregate header, active/inactive filter, surfaced
    active_epoch and hex per row
  - Proposal detail "Your ballot entry" (rationale + anchor) and
    "Technical details" sections surfacing fields that were already
    fetched but never rendered

- Ballot UX + standalone rationale: shared rationale module
  (build JSON-LD, hash, upload to IPFS, load-from-URL) and a reusable
  RationaleEditor component. The vote card now offers an "Attach
  voting rationale" toggle so a user can attach a CIP-100 anchor to a
  single-proposal vote without creating a Ballot. VoteButton threads
  the anchor through to txBuilder.vote(). Ballot summary now reports
  rationale-uploaded / draft counts; moving a proposal between
  ballots is gated by a Keep / Add to both / Move here dialog instead
  of silently relocating it.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 next.config.js                                |   6 +
 .../pages/homepage/governance/drep/index.tsx  |  87 ++++-
 .../pages/homepage/governance/index.tsx       |   3 +
 .../homepage/governance/network-stats.tsx     | 158 ++++++++
 .../wallets/import-transfer-dialog.tsx        | 195 ++++++++++
 .../pages/homepage/wallets/index.tsx          |   2 +
 .../pages/user/BotManagementCard.tsx          |  60 ++-
 .../pages/wallet/governance/ballot/ballot.tsx | 345 ++++++++++--------
 .../pages/wallet/governance/index.tsx         |   4 +
 .../wallet/governance/overview-summary.tsx    | 215 +++++++++++
 .../wallet/governance/proposal/index.tsx      | 116 ++++++
 .../governance/proposal/voteButtton.tsx       |  37 +-
 .../governance/rationale/RationaleEditor.tsx  | 274 ++++++++++++++
 .../pages/wallet/governance/vote-card.tsx     |  46 +++
 src/components/pages/wallet/info/index.tsx    |   2 +
 .../pages/wallet/info/transfer-wallet.tsx     | 307 ++++++++++++++++
 src/data/public-routes.ts                     |   3 +-
 src/lib/governance/rationale.ts               | 114 ++++++
 src/pages/api/llms-txt.ts                     |  49 +++
 src/pages/api/v1/botSetupGuide.ts             | 166 +++++++++
 src/pages/api/v1/wallet/transfer/export.ts    | 155 ++++++++
 src/pages/api/v1/wallet/transfer/import.ts    | 286 +++++++++++++++
 src/pages/bot-setup.tsx                       |  45 +++
 src/server/api/routers/wallets.ts             | 121 ++++++
 src/types/walletTransfer.ts                   |  46 +++
 25 files changed, 2683 insertions(+), 159 deletions(-)
 create mode 100644 src/components/pages/homepage/governance/network-stats.tsx
 create mode 100644 src/components/pages/homepage/wallets/import-transfer-dialog.tsx
 create mode 100644 src/components/pages/wallet/governance/overview-summary.tsx
 create mode 100644 src/components/pages/wallet/governance/rationale/RationaleEditor.tsx
 create mode 100644 src/components/pages/wallet/info/transfer-wallet.tsx
 create mode 100644 src/lib/governance/rationale.ts
 create mode 100644 src/pages/api/llms-txt.ts
 create mode 100644 src/pages/api/v1/botSetupGuide.ts
 create mode 100644 src/pages/api/v1/wallet/transfer/export.ts
 create mode 100644 src/pages/api/v1/wallet/transfer/import.ts
 create mode 100644 src/pages/bot-setup.tsx
 create mode 100644 src/types/walletTransfer.ts

diff --git a/next.config.js b/next.config.js
index 67efb015..46b5efd9 100644
--- a/next.config.js
+++ b/next.config.js
@@ -79,6 +79,12 @@ const config = {
   // External packages for server components to avoid bundling issues
   serverExternalPackages: ["@fabianbormann/cardano-peer-connect"],
 
+  async rewrites() {
+    return [
+      { source: "/llms.txt", destination: "/api/llms-txt" },
+    ];
+  },
+
   // Basic security headers applied to all routes.
   // NOTE: Content-Security-Policy and Strict-Transport-Security are intentionally
   // omitted — CSP would break inline scripts/styles and HSTS locks browsers to
diff --git a/src/components/pages/homepage/governance/drep/index.tsx b/src/components/pages/homepage/governance/drep/index.tsx
index 5c7360a8..2a5430a8 100644
--- a/src/components/pages/homepage/governance/drep/index.tsx
+++ b/src/components/pages/homepage/governance/drep/index.tsx
@@ -1,4 +1,4 @@
-import React, { useEffect, useState } from "react";
+import React, { useEffect, useMemo, useState } from "react";
 import SectionTitle from "@/components/ui/section-title";
 import Pagination from "@/components/common/overall-layout/pagination";
 import { getProvider } from "@/utils/get-provider";
@@ -10,6 +10,7 @@ import RowLabelInfo from "@/components/common/row-label-info";
 import { TooltipProvider } from "@/components/ui/tooltip";
 import ActiveIndicator from "./activeIndicator";
 import ScriptIndicator from "./scriptIndicator";
+import { Button } from "@/components/ui/button";
 
 export default function DrepOverviewPage() {
   const [drepList, setDrepList] = useState<
@@ -22,6 +23,7 @@ export default function DrepOverviewPage() {
   const [order, setOrder] = useState<"asc" | "desc">("asc");
   const [isLastPage, setIsLastPage] = useState<boolean>(false);
   const [network, setNetwork] = useState<number>(3); // Default to mainnet
+  const [filter, setFilter] = useState<"all" | "active" | "inactive">("all");
 
   useEffect(() => {
     async function fetchNetwork() {
@@ -112,11 +114,79 @@ export default function DrepOverviewPage() {
     }
   };
 
+  const aggregate = useMemo(() => {
+    let active = 0;
+    let totalLovelace = 0;
+    for (const { details } of drepList) {
+      if (details?.active) active += 1;
+      const amt = details?.amount ? parseInt(details.amount, 10) : 0;
+      if (Number.isFinite(amt)) totalLovelace += amt;
+    }
+    return {
+      total: drepList.length,
+      active,
+      inactive: drepList.length - active,
+      totalAda: totalLovelace / 1_000_000,
+    };
+  }, [drepList]);
+
+  const visibleDreps = useMemo(() => {
+    if (filter === "all") return drepList;
+    if (filter === "active") return drepList.filter((d) => d.details?.active);
+    return drepList.filter((d) => !d.details?.active);
+  }, [drepList, filter]);
+
   return (
     <TooltipProvider>
       <main className="flex flex-col gap-8 p-4 text-gray-300 md:p-8">
         <SectionTitle>DREP Overview</SectionTitle>
 
+        {/* Aggregate stats for current page */}
+        <div className="grid grid-cols-2 gap-3 sm:grid-cols-4">
+          <div className="rounded-md border bg-muted/30 p-3">
+            <div className="text-xs text-muted-foreground">On this page</div>
+            <div className="mt-1 text-xl font-semibold text-foreground">
+              {aggregate.total}
+            </div>
+          </div>
+          <div className="rounded-md border bg-muted/30 p-3">
+            <div className="text-xs text-muted-foreground">Active</div>
+            <div className="mt-1 text-xl font-semibold text-foreground">
+              {aggregate.active}
+            </div>
+          </div>
+          <div className="rounded-md border bg-muted/30 p-3">
+            <div className="text-xs text-muted-foreground">Inactive</div>
+            <div className="mt-1 text-xl font-semibold text-foreground">
+              {aggregate.inactive}
+            </div>
+          </div>
+          <div className="rounded-md border bg-muted/30 p-3">
+            <div className="text-xs text-muted-foreground">ADA delegated</div>
+            <div className="mt-1 text-xl font-semibold text-foreground">
+              {aggregate.totalAda >= 1_000_000
+                ? `${(aggregate.totalAda / 1_000_000).toFixed(2)}M ₳`
+                : aggregate.totalAda >= 1_000
+                  ? `${(aggregate.totalAda / 1_000).toFixed(1)}k ₳`
+                  : `${aggregate.totalAda.toFixed(0)} ₳`}
+            </div>
+          </div>
+        </div>
+
+        {/* Filter controls */}
+        <div className="flex flex-wrap gap-2">
+          {(["all", "active", "inactive"] as const).map((f) => (
+            <Button
+              key={f}
+              size="sm"
+              variant={filter === f ? "default" : "secondary"}
+              onClick={() => setFilter(f)}
+            >
+              {f === "all" ? "All" : f === "active" ? "Active" : "Inactive"}
+            </Button>
+          ))}
+        </div>
+
         {/* Pagination Component */}
         <Pagination
           currentPage={currentPage}
@@ -133,7 +203,7 @@ export default function DrepOverviewPage() {
           {loading ? (
             <p>Loading DREP information...</p>
           ) : (
-            drepList.map(({ details, metadata }) => {
+            visibleDreps.map(({ details, metadata }) => {
               const drepId = details.drep_id;
               const givenName =
                 typeof metadata?.json_metadata?.body?.givenName === "object"
@@ -194,6 +264,14 @@ export default function DrepOverviewPage() {
                       copyString={drepId}
                       className="text-sm text-gray-400"
                     />
+                    <div className="mt-1 flex flex-wrap gap-x-4 gap-y-1 text-xs text-gray-500">
+                      {details?.active_epoch != null && (
+                        <span>Active since epoch {details.active_epoch}</span>
+                      )}
+                      {details?.hex && (
+                        <span className="font-mono">hex: {details.hex.slice(0, 16)}…</span>
+                      )}
+                    </div>
                   </div>
 
                   {/* ADA Amount (Larger, Aligned Right) */}
@@ -211,6 +289,11 @@ export default function DrepOverviewPage() {
           {!loading && drepList.length === 0 && (
             <p className="text-gray-500">No DREP information available.</p>
           )}
+          {!loading && drepList.length > 0 && visibleDreps.length === 0 && (
+            <p className="text-gray-500">
+              No DReps match the {filter} filter on this page.
+            </p>
+          )}
         </div>
       </main>
     </TooltipProvider>
diff --git a/src/components/pages/homepage/governance/index.tsx b/src/components/pages/homepage/governance/index.tsx
index ea91afd0..43e63c9c 100644
--- a/src/components/pages/homepage/governance/index.tsx
+++ b/src/components/pages/homepage/governance/index.tsx
@@ -3,6 +3,7 @@ import SectionTitle from "@/components/ui/section-title";
 import CardUI from "@/components/ui/card-content";
 import Button from "@/components/common/button";
 import Link from "next/link";
+import GovernanceNetworkStats from "./network-stats";
 
 export default function PageGovernance() {
   const governanceFeatures = [
@@ -81,6 +82,8 @@ export default function PageGovernance() {
         wallet experience.
       </p>
 
+      <GovernanceNetworkStats />
+
       {governanceFeatures.map((feature, index) => (
         <React.Fragment key={index}>
           <CardUI title={feature.title} cardClassName="w-full">
diff --git a/src/components/pages/homepage/governance/network-stats.tsx b/src/components/pages/homepage/governance/network-stats.tsx
new file mode 100644
index 00000000..f6abee25
--- /dev/null
+++ b/src/components/pages/homepage/governance/network-stats.tsx
@@ -0,0 +1,158 @@
+import { useEffect, useState } from "react";
+import CardUI from "@/components/ui/card-content";
+import { Users, FileText, Coins } from "lucide-react";
+import { getProvider } from "@/utils/get-provider";
+import { useWallet } from "@meshsdk/react";
+import type { BlockfrostDrepInfo } from "@/types/governance";
+
+type Stats = {
+  drepCount: number | null;
+  activeDrepCount: number | null;
+  totalDelegatedAda: number | null;
+  activeProposals: number | null;
+};
+
+const INITIAL: Stats = {
+  drepCount: null,
+  activeDrepCount: null,
+  totalDelegatedAda: null,
+  activeProposals: null,
+};
+
+function formatNumber(n: number | null): string {
+  if (n == null) return "…";
+  return n.toLocaleString();
+}
+
+function formatAda(n: number | null): string {
+  if (n == null) return "…";
+  if (n >= 1_000_000_000) return `${(n / 1_000_000_000).toFixed(2)}B ₳`;
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(2)}M ₳`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}k ₳`;
+  return `${n.toFixed(0)} ₳`;
+}
+
+export default function GovernanceNetworkStats() {
+  const { wallet, connected } = useWallet();
+  const [network, setNetwork] = useState<number>(1);
+  const [stats, setStats] = useState<Stats>(INITIAL);
+
+  useEffect(() => {
+    let cancelled = false;
+    const fetchNet = async () => {
+      if (connected && wallet) {
+        try {
+          const n = await wallet.getNetworkId();
+          if (!cancelled) setNetwork(n);
+        } catch {
+          /* default to mainnet */
+        }
+      }
+    };
+    void fetchNet();
+    return () => {
+      cancelled = true;
+    };
+  }, [connected, wallet]);
+
+  useEffect(() => {
+    let cancelled = false;
+    const load = async () => {
+      try {
+        const provider = getProvider(network);
+        const [drepsPage, proposalsPage] = await Promise.all([
+          provider
+            .get(`/governance/dreps/?count=100&page=1&order=desc`)
+            .catch(() => [] as BlockfrostDrepInfo[]),
+          provider
+            .get(`/governance/proposals?count=100&page=1&order=desc`)
+            .catch(() => [] as Array<{ tx_hash: string; cert_index: number }>),
+        ]);
+        const dreps = Array.isArray(drepsPage) ? (drepsPage as BlockfrostDrepInfo[]) : [];
+        const totalLovelace = dreps.reduce((acc, d) => {
+          const amt = d?.amount ? parseInt(String(d.amount), 10) : 0;
+          return acc + (Number.isFinite(amt) ? amt : 0);
+        }, 0);
+        const activeCount = dreps.filter((d) => Boolean(d?.active)).length;
+        const proposals = Array.isArray(proposalsPage) ? proposalsPage : [];
+
+        if (!cancelled) {
+          setStats({
+            drepCount: dreps.length,
+            activeDrepCount: activeCount,
+            totalDelegatedAda: totalLovelace / 1_000_000,
+            activeProposals: proposals.length,
+          });
+        }
+      } catch {
+        if (!cancelled) setStats(INITIAL);
+      }
+    };
+    void load();
+    return () => {
+      cancelled = true;
+    };
+  }, [network]);
+
+  return (
+    <CardUI
+      title="Live Cardano governance"
+      description={`Snapshot from ${network === 0 ? "preprod" : "mainnet"} (first 100 DReps and proposals).`}
+      cardClassName="w-full"
+    >
+      <div className="grid grid-cols-1 gap-3 sm:grid-cols-4">
+        <Tile
+          icon={<Users className="h-4 w-4" />}
+          label="DReps tracked"
+          value={formatNumber(stats.drepCount)}
+          hint={
+            stats.activeDrepCount != null
+              ? `${stats.activeDrepCount} active`
+              : "…"
+          }
+        />
+        <Tile
+          icon={<Coins className="h-4 w-4" />}
+          label="ADA delegated"
+          value={formatAda(stats.totalDelegatedAda)}
+          hint="To these DReps"
+        />
+        <Tile
+          icon={<FileText className="h-4 w-4" />}
+          label="Recent proposals"
+          value={formatNumber(stats.activeProposals)}
+          hint="Latest 100"
+        />
+        <Tile
+          icon={<Users className="h-4 w-4" />}
+          label="Network"
+          value={network === 0 ? "Preprod" : "Mainnet"}
+          hint="From your wallet, if connected"
+        />
+      </div>
+    </CardUI>
+  );
+}
+
+function Tile({
+  icon,
+  label,
+  value,
+  hint,
+}: {
+  icon: React.ReactNode;
+  label: string;
+  value: string;
+  hint?: string;
+}) {
+  return (
+    <div className="rounded-md border bg-muted/30 p-3">
+      <div className="flex items-center gap-2 text-xs text-muted-foreground">
+        {icon}
+        <span>{label}</span>
+      </div>
+      <div className="mt-1 text-xl font-semibold">{value}</div>
+      {hint && <div className="text-xs text-muted-foreground">{hint}</div>}
+    </div>
+  );
+}
diff --git a/src/components/pages/homepage/wallets/import-transfer-dialog.tsx b/src/components/pages/homepage/wallets/import-transfer-dialog.tsx
new file mode 100644
index 00000000..41c620f9
--- /dev/null
+++ b/src/components/pages/homepage/wallets/import-transfer-dialog.tsx
@@ -0,0 +1,195 @@
+import { useRef, useState } from "react";
+import { useRouter } from "next/router";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Alert, AlertDescription } from "@/components/ui/alert";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Loader, Upload, CheckCircle } from "lucide-react";
+import { toast } from "@/hooks/use-toast";
+import {
+  WALLET_TRANSFER_FORMAT,
+  WALLET_TRANSFER_VERSION,
+  type WalletTransferPayloadV1,
+} from "@/types/walletTransfer";
+
+export function ImportTransferDialog() {
+  const router = useRouter();
+  const fileRef = useRef<HTMLInputElement>(null);
+  const [open, setOpen] = useState(false);
+  const [busy, setBusy] = useState(false);
+  const [fileName, setFileName] = useState<string | null>(null);
+  const [payload, setPayload] = useState<WalletTransferPayloadV1 | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const reset = () => {
+    setBusy(false);
+    setFileName(null);
+    setPayload(null);
+    setError(null);
+    if (fileRef.current) fileRef.current.value = "";
+  };
+
+  const onFile = async (file: File | undefined) => {
+    if (!file) return;
+    setError(null);
+    setFileName(file.name);
+    try {
+      const text = await file.text();
+      const parsed = JSON.parse(text) as WalletTransferPayloadV1;
+      if (parsed.format !== WALLET_TRANSFER_FORMAT) {
+        throw new Error(`Unexpected format: ${String(parsed.format)}`);
+      }
+      if (parsed.version !== WALLET_TRANSFER_VERSION) {
+        throw new Error(`Unsupported payload version: ${String(parsed.version)}`);
+      }
+      if (!parsed.wallet?.scriptCbor || !Array.isArray(parsed.wallet.signersAddresses)) {
+        throw new Error("Payload is missing wallet definition fields");
+      }
+      setPayload(parsed);
+    } catch (e) {
+      setPayload(null);
+      setError(e instanceof Error ? e.message : "Invalid JSON file");
+    }
+  };
+
+  const submit = async () => {
+    if (!payload) return;
+    setBusy(true);
+    try {
+      const res = await fetch("/api/v1/wallet/transfer/import", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+      });
+      const body = await res.json().catch(() => ({}));
+      if (!res.ok) {
+        throw new Error((body as { error?: string })?.error ?? `Import failed (${res.status})`);
+      }
+      const result = body as { newWalletId: string; inviteUrl: string };
+      toast({
+        title: "Wallet imported",
+        description: "Redirecting to the invite page so signers can claim.",
+      });
+      setOpen(false);
+      reset();
+      await router.push(`/wallets/invite/${result.newWalletId}`);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : "Import failed";
+      setError(msg);
+      toast({ title: "Import failed", description: msg, variant: "destructive" });
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <>
+      <Button
+        size="sm"
+        variant="secondary"
+        onClick={() => setOpen(true)}
+      >
+        Import Transfer
+      </Button>
+      <Dialog
+        open={open}
+        onOpenChange={(o) => {
+          if (!o) reset();
+          setOpen(o);
+        }}
+      >
+        <DialogContent className="sm:max-w-lg">
+          <DialogHeader>
+            <DialogTitle>Import wallet transfer</DialogTitle>
+            <DialogDescription>
+              Upload a wallet transfer JSON exported from another Multisig
+              instance.
+            </DialogDescription>
+          </DialogHeader>
+
+          <div className="space-y-3">
+            <div>
+              <Label htmlFor="transfer-file">Transfer file</Label>
+              <Input
+                id="transfer-file"
+                type="file"
+                accept="application/json,.json"
+                ref={fileRef}
+                onChange={(e) => onFile(e.target.files?.[0])}
+              />
+              {fileName && (
+                <p className="mt-1 text-xs text-muted-foreground">{fileName}</p>
+              )}
+            </div>
+
+            {error && (
+              <Alert variant="destructive">
+                <AlertDescription>{error}</AlertDescription>
+              </Alert>
+            )}
+
+            {payload && !error && (
+              <Alert>
+                <CheckCircle className="h-4 w-4" />
+                <AlertDescription>
+                  <div className="space-y-1 text-sm">
+                    <div>
+                      <strong>{payload.wallet.name}</strong>
+                    </div>
+                    <div className="text-muted-foreground">
+                      {payload.wallet.signersAddresses.length} signer
+                      {payload.wallet.signersAddresses.length === 1 ? "" : "s"}
+                      {" · "}
+                      type: {payload.wallet.type}
+                      {payload.contacts ? ` · ${payload.contacts.length} contacts` : ""}
+                      {payload.ballots ? ` · ${payload.ballots.length} ballots` : ""}
+                    </div>
+                    {payload.exportedFromOrigin && (
+                      <div className="text-muted-foreground text-xs">
+                        from {payload.exportedFromOrigin}
+                      </div>
+                    )}
+                  </div>
+                </AlertDescription>
+              </Alert>
+            )}
+          </div>
+
+          <DialogFooter>
+            <Button
+              variant="outline"
+              onClick={() => {
+                setOpen(false);
+                reset();
+              }}
+              disabled={busy}
+            >
+              Cancel
+            </Button>
+            <Button onClick={submit} disabled={!payload || busy}>
+              {busy ? (
+                <>
+                  <Loader className="mr-2 h-4 w-4 animate-spin" />
+                  Importing...
+                </>
+              ) : (
+                <>
+                  <Upload className="mr-2 h-4 w-4" />
+                  Import
+                </>
+              )}
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}
diff --git a/src/components/pages/homepage/wallets/index.tsx b/src/components/pages/homepage/wallets/index.tsx
index e6a6d379..8ef52bcf 100644
--- a/src/components/pages/homepage/wallets/index.tsx
+++ b/src/components/pages/homepage/wallets/index.tsx
@@ -25,6 +25,7 @@ import SectionExplanation from "./SectionExplanation";
 import WalletCardSkeleton from "./WalletCardSkeleton";
 import WalletInviteCardSkeleton from "./WalletInviteCardSkeleton";
 import IPFSImage from "@/components/common/ipfs-image";
+import { ImportTransferDialog } from "./import-transfer-dialog";
 
 
 export default function PageWallets() {
@@ -123,6 +124,7 @@ export default function PageWallets() {
           <Button size="sm" asChild>
             <Link href="/wallets/new-wallet-flow/save">New Wallet</Link>
           </Button>
+          <ImportTransferDialog />
           {wallets && wallets.some((wallet) => wallet.isArchived) && (
             <Button
               variant={showArchived ? "default" : "secondary"}
diff --git a/src/components/pages/user/BotManagementCard.tsx b/src/components/pages/user/BotManagementCard.tsx
index d8db60c1..ecd30a1f 100644
--- a/src/components/pages/user/BotManagementCard.tsx
+++ b/src/components/pages/user/BotManagementCard.tsx
@@ -1,5 +1,5 @@
 import { useState } from "react";
-import { Bot, Trash2, Loader2, Pencil, Link } from "lucide-react";
+import { Bot, Trash2, Loader2, Pencil, Link, Copy, Check } from "lucide-react";
 import CardUI from "@/components/ui/card-content";
 import RowLabelInfo from "@/components/ui/row-label-info";
 import { Button } from "@/components/ui/button";
@@ -213,6 +213,39 @@ export default function BotManagementCard() {
 
   const missingReadScopeInEdit = editScopes.length > 0 && !editScopes.includes(READ_SCOPE);
 
+  const [agentPromptCopied, setAgentPromptCopied] = useState(false);
+  const copyAgentPrompt = async () => {
+    const origin =
+      typeof window !== "undefined" ? window.location.origin : "https://multisig.meshjs.dev";
+    const prompt = `You are being onboarded as a bot on this Mesh Multisig instance: ${origin}
+
+Follow these steps and report back to me at each pause:
+
+1. Generate or load a Cardano payment address you control. Tell me which address you will use.
+2. Fetch ${origin}/api/v1/botSetupGuide for the full protocol — that is the source of truth.
+3. Call POST ${origin}/api/v1/botRegister with body { name, paymentAddress, requestedScopes }. Request the minimum scopes you need (start with ["multisig:read"]; add "multisig:sign", "multisig:create", "governance:read", or "ballot:write" only if you need them).
+4. Report the returned pendingBotId and claimCode to me. I will approve in the UI within 10 minutes.
+5. Once I confirm, call GET ${origin}/api/v1/botPickupSecret?pendingBotId=<id> to retrieve your botKeyId and one-time secret. Store them securely; never log the secret.
+6. Call POST ${origin}/api/v1/botAuth with { botKeyId, secret, paymentAddress } to obtain a 1-hour JWT.
+7. Confirm by calling GET ${origin}/api/v1/botMe with Authorization: Bearer <jwt>. Print the response.
+8. Wait for me to grant your bot access to specific wallets in the UI before attempting any wallet operations.
+
+Do not skip steps. Do not ask for the secret over an insecure channel. Re-authenticate when the JWT expires.`;
+
+    try {
+      await navigator.clipboard.writeText(prompt);
+      setAgentPromptCopied(true);
+      setTimeout(() => setAgentPromptCopied(false), 2000);
+      toast({ title: "Prompt copied", description: "Paste it into your AI agent." });
+    } catch {
+      toast({
+        title: "Copy failed",
+        description: "Your browser blocked clipboard access.",
+        variant: "destructive",
+      });
+    }
+  };
+
   return (
     <CardUI
       title="Bot accounts"
@@ -220,6 +253,31 @@ export default function BotManagementCard() {
       icon={Bot}
     >
       <div className="space-y-4">
+        <div className="rounded-md border bg-muted/40 p-3">
+          <div className="flex flex-col gap-2 sm:flex-row sm:items-start sm:justify-between">
+            <div>
+              <div className="text-sm font-medium">Connect an AI agent</div>
+              <p className="text-xs text-muted-foreground">
+                Copy a self-contained prompt that walks any AI agent (Claude,
+                Cursor, etc.) through registering itself as a bot on this
+                instance.
+              </p>
+            </div>
+            <Button
+              variant="secondary"
+              size="sm"
+              className="gap-1 self-start sm:self-auto"
+              onClick={copyAgentPrompt}
+            >
+              {agentPromptCopied ? (
+                <Check className="h-4 w-4" />
+              ) : (
+                <Copy className="h-4 w-4" />
+              )}
+              {agentPromptCopied ? "Copied" : "Copy agent prompt"}
+            </Button>
+          </div>
+        </div>
         <div className="flex items-center justify-between gap-2">
           <span className="text-sm font-medium">Bots</span>
           <Button
diff --git a/src/components/pages/wallet/governance/ballot/ballot.tsx b/src/components/pages/wallet/governance/ballot/ballot.tsx
index 895699e1..2a0ddbae 100644
--- a/src/components/pages/wallet/governance/ballot/ballot.tsx
+++ b/src/components/pages/wallet/governance/ballot/ballot.tsx
@@ -32,10 +32,15 @@ import { useProxy } from "@/hooks/useProxy";
 import { MeshProxyContract } from "@/components/multisig/proxy/offchain";
 import { CheckCircle2, XCircle, MinusCircle, Loader2, Trash2, Plus, FileText, Vote as VoteIcon, Link2, ChevronDown, ChevronUp } from "lucide-react";
 import { Badge } from "@/components/ui/badge";
-import { hashDrepAnchor } from "@meshsdk/core";
 import { Textarea } from "@/components/ui/textarea";
 import { Input } from "@/components/ui/input";
 import { parseProposalId } from "@/lib/governance";
+import {
+  buildRationaleJsonLd,
+  computeAnchorHash,
+  loadRationaleFromUrl as loadRationale,
+  uploadRationaleToPinata,
+} from "@/lib/governance/rationale";
 
 const GovAction = 1;
 
@@ -166,6 +171,14 @@ export default function BallotCard({
     ballotDescription: string;
   } | null>(null);
 
+  const [moveConfirm, setMoveConfirm] = useState<{
+    proposalId: string;
+    proposalTitle: string;
+    targetBallotId: string;
+    targetBallotName: string;
+    sourceBallots: Array<{ id: string; description: string; index: number }>;
+  } | null>(null);
+
   const { toast } = useToast();
 
   // Ballot voting state
@@ -611,45 +624,29 @@ export default function BallotCard({
         b.items.includes(currentProposalId),
     );
 
-    // If in another ballot, automatically move it
+    // If in another ballot, ask the user before moving — moving wipes the
+    // existing choice/rationale on the source ballot, which is destructive.
     if (ballotsWithProposal.length > 0) {
-      Promise.all(
-        ballotsWithProposal.map(async (b) => {
-          const index = b.items.findIndex((item: string) => item === currentProposalId);
-          if (index >= 0) {
-            await moveRemoveProposalMutation.mutateAsync({
-              ballotId: b.id,
-              index,
-            });
-          }
-        })
-      ).then(() => {
-        addProposalMutation.mutate({
-          ballotId: selectedBallotId,
-          itemDescription: currentProposalTitle || "Untitled proposal",
-          item: currentProposalId,
-          choice: "Abstain",
-        }, {
-          onSuccess: () => {
-            handledProposalRef.current.add(currentProposalId);
-            isProcessingRef.current = false;
-            toast({
-              title: "Moved to Ballot",
-              description: "Proposal moved to the selected ballot.",
-              duration: 2000,
-            });
-            getBallots.refetch();
-            onBallotChanged?.();
-          },
-          onError: () => {
-            isProcessingRef.current = false;
-            autoHandleRef.current = null; // Reset on error
-          },
-        });
-      }).catch(() => {
-        isProcessingRef.current = false;
-        autoHandleRef.current = null;
+      const targetBallot = getBallots.data.find((b) => b.id === selectedBallotId);
+      setMoveConfirm({
+        proposalId: currentProposalId,
+        proposalTitle: currentProposalTitle ?? "Untitled proposal",
+        targetBallotId: selectedBallotId,
+        targetBallotName: targetBallot?.description ?? "this ballot",
+        sourceBallots: ballotsWithProposal
+          .map((b) => {
+            const idx = b.items.findIndex((item: string) => item === currentProposalId);
+            return {
+              id: b.id,
+              description: b.description ?? "Untitled ballot",
+              index: idx,
+            };
+          })
+          .filter((b) => b.index >= 0),
       });
+      // Mark as handled so we don't re-trigger; the user resolves via dialog.
+      handledProposalRef.current.add(currentProposalId);
+      isProcessingRef.current = false;
       return;
     }
 
@@ -686,14 +683,26 @@ export default function BallotCard({
   // Calculate vote summary
   const voteSummary = useMemo(() => {
     if (!selectedBallot || !Array.isArray(selectedBallot.items)) {
-      return { total: 0, yes: 0, no: 0, abstain: 0 };
+      return { total: 0, yes: 0, no: 0, abstain: 0, withRationale: 0, drafts: 0 };
     }
     const choices = selectedBallot.choices || [];
+    const anchorHashes = selectedBallot.anchorHashes || [];
+    const rationaleComments = selectedBallot.rationaleComments || [];
+    let withRationale = 0;
+    let drafts = 0;
+    for (let i = 0; i < selectedBallot.items.length; i++) {
+      const hasAnchor = Boolean(anchorHashes[i]?.trim());
+      const hasDraft = Boolean(rationaleComments[i]?.trim());
+      if (hasAnchor) withRationale += 1;
+      else if (hasDraft) drafts += 1;
+    }
     return {
       total: selectedBallot.items.length,
       yes: choices.filter((c: string) => c === "Yes").length,
       no: choices.filter((c: string) => c === "No").length,
       abstain: choices.filter((c: string) => c === "Abstain").length,
+      withRationale,
+      drafts,
     };
   }, [selectedBallot]);
 
@@ -821,7 +830,7 @@ export default function BallotCard({
                       {voteSummary.total} {voteSummary.total === 1 ? 'proposal' : 'proposals'}
                     </span>
                   </div>
-                  <div className="flex items-center gap-4">
+                  <div className="flex items-center gap-4 flex-wrap">
                     <Badge variant="outline" className="bg-green-50 dark:bg-green-900/20 text-green-700 dark:text-green-400 border-green-200 dark:border-green-800">
                       Yes: {voteSummary.yes}
                     </Badge>
@@ -833,6 +842,15 @@ export default function BallotCard({
                     </Badge>
                   </div>
                 </div>
+                <div className="mt-2 flex items-center gap-3 text-xs text-muted-foreground">
+                  <span className="flex items-center gap-1">
+                    <FileText className="h-3 w-3" />
+                    Rationale uploaded: {voteSummary.withRationale}/{voteSummary.total}
+                  </span>
+                  {voteSummary.drafts > 0 && (
+                    <span>· {voteSummary.drafts} draft{voteSummary.drafts === 1 ? "" : "s"} pending upload</span>
+                  )}
+                </div>
               </div>
 
               {/* Proxy Warning */}
@@ -982,6 +1000,117 @@ export default function BallotCard({
           </div>
         </DialogContent>
       </Dialog>
+
+      {/* Confirmation dialog for moving a proposal between ballots */}
+      <Dialog
+        open={!!moveConfirm}
+        onOpenChange={(open) => {
+          if (!open) setMoveConfirm(null);
+        }}
+      >
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Move proposal to this ballot?</DialogTitle>
+            <DialogDescription>
+              {moveConfirm && (
+                <span>
+                  &ldquo;{moveConfirm.proposalTitle}&rdquo; is already on{" "}
+                  {moveConfirm.sourceBallots.length === 1
+                    ? `the ballot "${moveConfirm.sourceBallots[0]?.description}"`
+                    : `${moveConfirm.sourceBallots.length} other ballots`}
+                  . Moving it to &ldquo;{moveConfirm.targetBallotName}&rdquo; will
+                  remove it from the source ballot(s) — including any choice and
+                  rationale you set there.
+                </span>
+              )}
+            </DialogDescription>
+          </DialogHeader>
+          <div className="mt-4 flex flex-wrap justify-end gap-2">
+            <Button
+              variant="outline"
+              onClick={() => setMoveConfirm(null)}
+              disabled={addProposalMutation.isPending || moveRemoveProposalMutation.isPending}
+            >
+              Keep where it is
+            </Button>
+            <Button
+              variant="secondary"
+              onClick={async () => {
+                if (!moveConfirm) return;
+                try {
+                  await addProposalMutation.mutateAsync({
+                    ballotId: moveConfirm.targetBallotId,
+                    itemDescription: moveConfirm.proposalTitle,
+                    item: moveConfirm.proposalId,
+                    choice: "Abstain",
+                  });
+                  setMoveConfirm(null);
+                  toast({
+                    title: "Added to this ballot",
+                    description: "Proposal now exists on both ballots.",
+                    duration: 2000,
+                  });
+                  await getBallots.refetch();
+                  onBallotChanged?.();
+                } catch (error: unknown) {
+                  toast({
+                    title: "Error",
+                    description: error instanceof Error ? error.message : "Failed to add proposal.",
+                    variant: "destructive",
+                  });
+                }
+              }}
+              disabled={addProposalMutation.isPending}
+            >
+              Add to both
+            </Button>
+            <Button
+              onClick={async () => {
+                if (!moveConfirm) return;
+                try {
+                  for (const src of moveConfirm.sourceBallots) {
+                    await moveRemoveProposalMutation.mutateAsync({
+                      ballotId: src.id,
+                      index: src.index,
+                    });
+                  }
+                  await addProposalMutation.mutateAsync({
+                    ballotId: moveConfirm.targetBallotId,
+                    itemDescription: moveConfirm.proposalTitle,
+                    item: moveConfirm.proposalId,
+                    choice: "Abstain",
+                  });
+                  setMoveConfirm(null);
+                  toast({
+                    title: "Moved",
+                    description: "Proposal moved to this ballot.",
+                    duration: 2000,
+                  });
+                  await getBallots.refetch();
+                  onBallotChanged?.();
+                } catch (error: unknown) {
+                  toast({
+                    title: "Error",
+                    description: error instanceof Error ? error.message : "Failed to move proposal.",
+                    variant: "destructive",
+                  });
+                }
+              }}
+              disabled={addProposalMutation.isPending || moveRemoveProposalMutation.isPending}
+              className="bg-gray-700 hover:bg-gray-800 text-white"
+            >
+              {addProposalMutation.isPending || moveRemoveProposalMutation.isPending ? (
+                <>
+                  <Loader2 className="mr-2 h-4 w-4 animate-spin" />
+                  Moving...
+                </>
+              ) : (
+                "Move here"
+              )}
+            </Button>
+          </div>
+        </DialogContent>
+      </Dialog>
     </div>
   );
 }
@@ -1004,75 +1133,14 @@ function ProposalRationaleEditor({
 }) {
   const state = rationaleState || { json: "", url: "", hash: "", loading: false, comment: "" };
 
-  // Construct JSON-LD from comment following CIP-100 structure
-  const constructJsonLdFromComment = useCallback((comment: string) => {
-    const jsonLd = {
-      "@context": {
-        "CIP100": "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#",
-        "hashAlgorithm": "CIP100:hashAlgorithm",
-        "body": {
-          "@id": "CIP100:body",
-          "@context": {
-            "references": {
-              "@id": "CIP100:references",
-              "@container": "@set",
-              "@context": {
-                "GovernanceMetadata": "CIP100:GovernanceMetadataReference",
-                "Other": "CIP100:OtherReference",
-                "label": "CIP100:reference-label",
-                "uri": "CIP100:reference-uri",
-                "referenceHash": {
-                  "@id": "CIP100:referenceHash",
-                  "@context": {
-                    "hashDigest": "CIP100:hashDigest",
-                    "hashAlgorithm": "CIP100:hashAlgorithm"
-                  }
-                }
-              }
-            },
-            "comment": "CIP100:comment",
-            "externalUpdates": {
-              "@id": "CIP100:externalUpdates",
-              "@context": {
-                "title": "CIP100:update-title",
-                "uri": "CIP100:uri"
-              }
-            }
-          }
-        },
-        "authors": {
-          "@id": "CIP100:authors",
-          "@container": "@set",
-          "@context": {
-            "name": "http://xmlns.com/foaf/0.1/name",
-            "witness": {
-              "@id": "CIP100:witness",
-              "@context": {
-                "witnessAlgorithm": "CIP100:witnessAlgorithm",
-                "publicKey": "CIP100:publicKey",
-                "signature": "CIP100:signature"
-              }
-            }
-          }
-        }
-      },
-      "authors": [],
-      "body": {
-        "comment": comment.trim()
-      },
-      "hashAlgorithm": "blake2b-256"
-    };
-    return JSON.stringify(jsonLd, null, 2);
-  }, []);
-
   const handleCommentChange = useCallback((comment: string) => {
     if (comment.trim()) {
-      const jsonLd = constructJsonLdFromComment(comment);
+      const jsonLd = JSON.stringify(buildRationaleJsonLd(comment), null, 2);
       onStateChange({ comment, json: jsonLd });
     } else {
       onStateChange({ comment, json: "" });
     }
-  }, [constructJsonLdFromComment, onStateChange]);
+  }, [onStateChange]);
 
   return (
     <div className="space-y-3 rounded-lg border border-gray-200 dark:border-gray-800 bg-white dark:bg-gray-900 p-4">
@@ -1187,7 +1255,7 @@ function BallotOverviewTable({
   } = useProposalRemoval(ballotId, refetchBallots, onBallotChanged);
 
   const computeHashFromJson = useCallback((jsonData: unknown) => {
-    return hashDrepAnchor(jsonData as Record<string, unknown>);
+    return computeAnchorHash(jsonData);
   }, []);
 
   // Initialize rationale states from ballot data and auto-load existing anchors
@@ -1310,38 +1378,22 @@ function BallotOverviewTable({
     }
     setRationaleStates(prev => ({ ...prev, [idx]: { ...prev[idx]!, loading: true } }));
     try {
-      const parsed = JSON.parse(state.json);
-      const response = await fetch("/api/pinata-storage/put", {
-        method: "POST",
-        headers: {
-          Accept: "application/json",
-          "Content-Type": "application/json",
+      const parsed = JSON.parse(state.json) as Record<string, unknown>;
+      const anchor = await uploadRationaleToPinata(parsed);
+      setRationaleStates(prev => ({
+        ...prev,
+        [idx]: {
+          ...prev[idx]!,
+          url: anchor.url,
+          hash: anchor.hash,
+          loading: false,
         },
-        body: JSON.stringify({
-          pathname: `rationale/rationale-${Date.now()}.jsonld`,
-          value: JSON.stringify(parsed, null, 2),
-        }),
-      });
-      if (!response.ok) {
-        const err = await response.json();
-        throw new Error(err?.error || "Upload failed");
-      }
-      const res = await response.json();
-      const hash = computeHashFromJson(parsed);
-      setRationaleStates(prev => ({ 
-        ...prev, 
-        [idx]: { 
-          ...prev[idx]!, 
-          url: res.url, 
-          hash,
-          loading: false 
-        } 
       }));
       await updateAnchorMutation.mutateAsync({
         ballotId,
         index: idx,
-        anchorUrl: res.url,
-        anchorHash: hash,
+        anchorUrl: anchor.url,
+        anchorHash: anchor.hash,
       });
       await refetchBallots();
       toast({
@@ -1356,7 +1408,7 @@ function BallotOverviewTable({
         variant: "destructive",
       });
     }
-  }, [rationaleStates, computeHashFromJson, ballotId, updateAnchorMutation, refetchBallots, toast]);
+  }, [rationaleStates, ballotId, updateAnchorMutation, refetchBallots, toast]);
 
   const loadRationaleFromUrl = useCallback(async (idx: number, overrideUrl?: string) => {
     const state = rationaleStates[idx];
@@ -1371,28 +1423,23 @@ function BallotOverviewTable({
     }
     setRationaleStates(prev => ({ ...prev, [idx]: { ...prev[idx]!, loading: true } }));
     try {
-      const res = await fetch(targetUrl);
-      if (!res.ok) throw new Error("Failed to fetch rationale");
-      const data = await res.json();
-      const hash = computeHashFromJson(data);
-      // Extract comment from loaded JSON-LD if present
-      const comment = data?.body?.comment || "";
-      setRationaleStates(prev => ({ 
-        ...prev, 
-        [idx]: { 
-          ...prev[idx]!, 
-          json: JSON.stringify(data, null, 2),
+      const res = await loadRationale(targetUrl);
+      setRationaleStates(prev => ({
+        ...prev,
+        [idx]: {
+          ...prev[idx]!,
+          json: JSON.stringify(res.json, null, 2),
           url: targetUrl,
-          hash,
-          comment,
-          loading: false 
-        } 
+          hash: res.hash,
+          comment: res.comment,
+          loading: false,
+        },
       }));
       await updateAnchorMutation.mutateAsync({
         ballotId,
         index: idx,
         anchorUrl: targetUrl,
-        anchorHash: hash,
+        anchorHash: res.hash,
       });
       await refetchBallots();
       toast({
@@ -1407,7 +1454,7 @@ function BallotOverviewTable({
         variant: "destructive",
       });
     }
-  }, [rationaleStates, computeHashFromJson, ballotId, updateAnchorMutation, refetchBallots, toast]);
+  }, [rationaleStates, ballotId, updateAnchorMutation, refetchBallots, toast]);
 
   return (
     <>
diff --git a/src/components/pages/wallet/governance/index.tsx b/src/components/pages/wallet/governance/index.tsx
index e5a01ed1..6bf5f710 100644
--- a/src/components/pages/wallet/governance/index.tsx
+++ b/src/components/pages/wallet/governance/index.tsx
@@ -1,4 +1,5 @@
 import CardInfo from "./card-info";
+import GovernanceOverviewSummary from "./overview-summary";
 import { useSiteStore } from "@/lib/zustand/site";
 import AllProposals from "./proposals";
 import useAppWallet from "@/hooks/useAppWallet";
@@ -35,6 +36,9 @@ function PageGovernanceContent() {
   return (
     <>
       <main className="flex flex-1 flex-col gap-4 p-3 sm:p-4 md:gap-6 lg:gap-8 lg:p-8 max-w-7xl mx-auto w-full">
+        {/* Dashboard summary at the top */}
+        <GovernanceOverviewSummary appWallet={appWallet} />
+
         {/* Info section */}
         <CardInfo appWallet={appWallet} manualUtxos={manualUtxos} />
         
diff --git a/src/components/pages/wallet/governance/overview-summary.tsx b/src/components/pages/wallet/governance/overview-summary.tsx
new file mode 100644
index 00000000..5d37c938
--- /dev/null
+++ b/src/components/pages/wallet/governance/overview-summary.tsx
@@ -0,0 +1,215 @@
+import { useEffect, useMemo, useState } from "react";
+import CardUI from "@/components/ui/card-content";
+import { Badge } from "@/components/ui/badge";
+import {
+  CheckCircle2,
+  Clock,
+  Vote as VoteIcon,
+  Trophy,
+  XCircle,
+} from "lucide-react";
+import type { Wallet } from "@/types/wallet";
+import { useBallot } from "@/hooks/useBallot";
+import { useWalletsStore } from "@/lib/zustand/wallets";
+import { useSiteStore } from "@/lib/zustand/site";
+import { getProvider } from "@/utils/get-provider";
+import {
+  getProposalStatus,
+  type ProposalStatus,
+} from "@/lib/governance";
+import type { ProposalDetails } from "@/types/governance";
+
+type StatusCounts = Record<ProposalStatus, number>;
+
+const EMPTY_COUNTS: StatusCounts = {
+  active: 0,
+  enacted: 0,
+  ratified: 0,
+  dropped: 0,
+  expired: 0,
+};
+
+function lovelaceToAda(value: string | number | null | undefined): number | null {
+  if (value == null) return null;
+  const n = typeof value === "string" ? Number(value) : value;
+  if (!Number.isFinite(n)) return null;
+  return n / 1_000_000;
+}
+
+function formatAda(value: number | null): string {
+  if (value == null) return "—";
+  if (value >= 1_000_000) return `${(value / 1_000_000).toFixed(2)}M ADA`;
+  if (value >= 1_000) return `${(value / 1_000).toFixed(1)}k ADA`;
+  return `${value.toFixed(2)} ADA`;
+}
+
+export default function GovernanceOverviewSummary({ appWallet }: { appWallet: Wallet }) {
+  const network = useSiteStore((s) => s.network);
+  const drepInfo = useWalletsStore((s) => s.drepInfo);
+  const { ballots } = useBallot(appWallet?.id);
+
+  const [statusCounts, setStatusCounts] = useState<StatusCounts>(EMPTY_COUNTS);
+  const [statusLoading, setStatusLoading] = useState(true);
+
+  useEffect(() => {
+    let cancelled = false;
+    setStatusLoading(true);
+    const fetchProposals = async () => {
+      try {
+        const provider = getProvider(network);
+        const proposals = (await provider.get(
+          `/governance/proposals?count=100&page=1&order=desc`,
+        )) as Array<{ tx_hash: string; cert_index: number | string }>;
+        if (!Array.isArray(proposals)) {
+          if (!cancelled) setStatusCounts(EMPTY_COUNTS);
+          return;
+        }
+        const counts: StatusCounts = { ...EMPTY_COUNTS };
+        const details = await Promise.all(
+          proposals.slice(0, 60).map(async (p) => {
+            try {
+              return (await provider.get(
+                `/governance/proposals/${p.tx_hash}/${p.cert_index}`,
+              )) as ProposalDetails;
+            } catch {
+              return null;
+            }
+          }),
+        );
+        for (const d of details) {
+          const status = getProposalStatus(d);
+          if (status) counts[status] += 1;
+        }
+        if (!cancelled) setStatusCounts(counts);
+      } catch (err) {
+        console.warn("[overview-summary] failed to fetch proposal statuses", err);
+        if (!cancelled) setStatusCounts(EMPTY_COUNTS);
+      } finally {
+        if (!cancelled) setStatusLoading(false);
+      }
+    };
+    void fetchProposals();
+    return () => {
+      cancelled = true;
+    };
+  }, [network]);
+
+  const ballotStats = useMemo(() => {
+    const total = ballots?.length ?? 0;
+    let totalProposals = 0;
+    let voted = 0;
+    let lastUpdated: Date | null = null;
+    for (const b of ballots ?? []) {
+      const items = Array.isArray(b.items) ? b.items : [];
+      const choices = Array.isArray(b.choices) ? b.choices : [];
+      totalProposals += items.length;
+      voted += choices.filter((c) => c && c.trim().length > 0).length;
+      const u = b.updatedAt ? new Date(b.updatedAt) : null;
+      if (u && (!lastUpdated || u > lastUpdated)) lastUpdated = u;
+    }
+    return { total, totalProposals, voted, lastUpdated };
+  }, [ballots]);
+
+  const drepStatus = drepInfo?.active ? "Active" : drepInfo ? "Inactive" : "—";
+  const votingPowerAda = lovelaceToAda(drepInfo?.amount ?? null);
+
+  const activeProposals = statusCounts.active;
+  const completedProposals = statusCounts.enacted + statusCounts.ratified;
+  const closedProposals = statusCounts.dropped + statusCounts.expired;
+
+  return (
+    <CardUI title="Governance overview" cardClassName="col-span-2">
+      <div className="grid grid-cols-2 gap-3 md:grid-cols-4">
+        <Tile
+          icon={<Clock className="h-4 w-4" />}
+          label="Active proposals"
+          value={statusLoading ? "…" : String(activeProposals)}
+          hint={`${statusLoading ? "…" : completedProposals} ratified · ${
+            statusLoading ? "…" : closedProposals
+          } closed`}
+        />
+        <Tile
+          icon={<VoteIcon className="h-4 w-4" />}
+          label="Ballot progress"
+          value={`${ballotStats.voted}/${ballotStats.totalProposals}`}
+          hint={`${ballotStats.total} ballot${ballotStats.total === 1 ? "" : "s"}`}
+        />
+        <Tile
+          icon={<Trophy className="h-4 w-4" />}
+          label="Voting power"
+          value={formatAda(votingPowerAda)}
+          hint={`DRep ${drepStatus}`}
+        />
+        <Tile
+          icon={
+            ballotStats.lastUpdated ? (
+              <CheckCircle2 className="h-4 w-4" />
+            ) : (
+              <XCircle className="h-4 w-4" />
+            )
+          }
+          label="Last ballot activity"
+          value={
+            ballotStats.lastUpdated
+              ? ballotStats.lastUpdated.toLocaleDateString(undefined, {
+                  month: "short",
+                  day: "numeric",
+                  year: "numeric",
+                })
+              : "—"
+          }
+          hint={
+            ballotStats.lastUpdated
+              ? ballotStats.lastUpdated.toLocaleTimeString(undefined, {
+                  hour: "2-digit",
+                  minute: "2-digit",
+                })
+              : "No ballots yet"
+          }
+        />
+      </div>
+
+      <div className="mt-4 flex flex-wrap items-center gap-2 text-xs text-muted-foreground">
+        <span>Proposal mix:</span>
+        <Badge variant="secondary">
+          {statusCounts.active} active
+        </Badge>
+        <Badge variant="secondary">
+          {statusCounts.enacted} enacted
+        </Badge>
+        <Badge variant="secondary">
+          {statusCounts.ratified} ratified
+        </Badge>
+        <Badge variant="secondary">
+          {statusCounts.dropped} dropped
+        </Badge>
+        <Badge variant="secondary">
+          {statusCounts.expired} expired
+        </Badge>
+      </div>
+    </CardUI>
+  );
+}
+
+function Tile({
+  icon,
+  label,
+  value,
+  hint,
+}: {
+  icon: React.ReactNode;
+  label: string;
+  value: string;
+  hint?: string;
+}) {
+  return (
+    <div className="rounded-md border bg-muted/30 p-3">
+      <div className="flex items-center gap-2 text-xs text-muted-foreground">
+        {icon}
+        <span>{label}</span>
+      </div>
+      <div className="mt-1 text-xl font-semibold">{value}</div>
+      {hint && <div className="text-xs text-muted-foreground">{hint}</div>}
+    </div>
+  );
+}
diff --git a/src/components/pages/wallet/governance/proposal/index.tsx b/src/components/pages/wallet/governance/proposal/index.tsx
index 0124d9df..87aa688c 100644
--- a/src/components/pages/wallet/governance/proposal/index.tsx
+++ b/src/components/pages/wallet/governance/proposal/index.tsx
@@ -549,6 +549,122 @@ function WalletGovernanceProposalContent({ id }: { id: string }) {
         </CardUI>
       )}
 
+      {/* Your ballot entry - shows the user's rationale + anchor for this proposal */}
+      {(() => {
+        if (!ballots || !proposalMetadata) return null;
+        const proposalId = `${proposalMetadata.tx_hash}#${proposalMetadata.cert_index}`;
+        for (const b of ballots) {
+          const idx = Array.isArray(b.items) ? b.items.indexOf(proposalId) : -1;
+          if (idx === -1) continue;
+          const choice = b.choices?.[idx] ?? "";
+          const rationale = b.rationaleComments?.[idx] ?? "";
+          const anchorUrl = b.anchorUrls?.[idx] ?? "";
+          const anchorHash = b.anchorHashes?.[idx] ?? "";
+          if (!choice && !rationale && !anchorUrl && !anchorHash) continue;
+          return (
+            <CardUI title="Your ballot entry" cardClassName="w-full" key={b.id}>
+              <div className="space-y-3 text-sm">
+                <div>
+                  <span className="text-muted-foreground">Ballot: </span>
+                  <span className="font-medium">{b.description || "Untitled ballot"}</span>
+                </div>
+                {choice && (
+                  <div>
+                    <span className="text-muted-foreground">Choice: </span>
+                    <Badge variant="secondary">{choice}</Badge>
+                  </div>
+                )}
+                {rationale && (
+                  <div>
+                    <div className="text-muted-foreground mb-1">Rationale:</div>
+                    <div className="rounded bg-muted/30 p-3 text-xs sm:text-sm whitespace-pre-wrap">
+                      {rationale}
+                    </div>
+                  </div>
+                )}
+                {(anchorUrl || anchorHash) && (
+                  <div className="space-y-1 text-xs">
+                    {anchorUrl && (
+                      <div className="break-all">
+                        <span className="text-muted-foreground">Anchor URL: </span>
+                        <a
+                          className="text-blue-600 dark:text-blue-400 underline"
+                          href={anchorUrl}
+                          target="_blank"
+                          rel="noreferrer"
+                        >
+                          {anchorUrl}
+                        </a>
+                      </div>
+                    )}
+                    {anchorHash && (
+                      <div className="break-all font-mono">
+                        <span className="text-muted-foreground">Anchor hash: </span>
+                        {anchorHash}
+                      </div>
+                    )}
+                  </div>
+                )}
+              </div>
+            </CardUI>
+          );
+        }
+        return null;
+      })()}
+
+      {/* Technical details - fetched fields not surfaced elsewhere */}
+      {proposalDetails && (
+        <CardUI title="Technical details" cardClassName="w-full">
+          <div className="grid grid-cols-1 gap-3 text-xs sm:grid-cols-2">
+            {proposalDetails.governance_description?.tag && (
+              <div>
+                <div className="text-muted-foreground">Action tag</div>
+                <div className="font-mono break-all">
+                  {proposalDetails.governance_description.tag}
+                </div>
+              </div>
+            )}
+            {proposalDetails.return_address && (
+              <div>
+                <div className="text-muted-foreground">Return address (deposit refund)</div>
+                <div className="font-mono break-all">{proposalDetails.return_address}</div>
+              </div>
+            )}
+            {proposalMetadata?.url && (
+              <div>
+                <div className="text-muted-foreground">Metadata anchor URL</div>
+                <a
+                  href={proposalMetadata.url}
+                  target="_blank"
+                  rel="noreferrer"
+                  className="text-blue-600 dark:text-blue-400 underline break-all"
+                >
+                  {proposalMetadata.url}
+                </a>
+              </div>
+            )}
+            {proposalMetadata?.hash && (
+              <div>
+                <div className="text-muted-foreground">Metadata anchor hash</div>
+                <div className="font-mono break-all">{proposalMetadata.hash}</div>
+              </div>
+            )}
+            <div>
+              <div className="text-muted-foreground">Proposal ID</div>
+              <div className="font-mono break-all">
+                {proposalDetails.tx_hash}#{proposalDetails.cert_index}
+              </div>
+            </div>
+            {proposalDetails.id && (
+              <div>
+                <div className="text-muted-foreground">Governance action ID</div>
+                <div className="font-mono break-all">{proposalDetails.id}</div>
+              </div>
+            )}
+          </div>
+        </CardUI>
+      )}
+
       {/* Withdrawals Card - Show for treasury withdrawal proposals */}
       {proposalWithdrawals && proposalWithdrawals.length > 0 && (
         <CardUI
diff --git a/src/components/pages/wallet/governance/proposal/voteButtton.tsx b/src/components/pages/wallet/governance/proposal/voteButtton.tsx
index 34d43bfa..2f63fc33 100644
--- a/src/components/pages/wallet/governance/proposal/voteButtton.tsx
+++ b/src/components/pages/wallet/governance/proposal/voteButtton.tsx
@@ -52,6 +52,11 @@ interface VoteButtonProps {
    * open the ballot card instead of mutating ballots directly.
    */
   onOpenBallotSidebar?: () => void;
+  /**
+   * Optional anchor (CIP-100 rationale URL + Blake2b-256 hash) attached
+   * to the on-chain vote. When provided, the vote tx carries this anchor.
+   */
+  anchor?: { url: string; hash: string } | null;
 }
 
 export default function VoteButton({
@@ -64,6 +69,7 @@ export default function VoteButton({
   proposalTitle,
   proposalDetails,
   onOpenBallotSidebar,
+  anchor = null,
 }: VoteButtonProps) {
   // Use the custom hook for ballots (still used for proxy / context where needed)
   const { ballots } = useBallot(appWallet?.id);
@@ -281,6 +287,16 @@ export default function VoteButton({
           )
           .txInScript(scriptCbor);
       }
+      const voteOptions: {
+        voteKind: "Yes" | "No" | "Abstain";
+        anchor?: { anchorUrl: string; anchorDataHash: string };
+      } = { voteKind };
+      if (anchor?.url && anchor?.hash) {
+        voteOptions.anchor = {
+          anchorUrl: anchor.url,
+          anchorDataHash: anchor.hash,
+        };
+      }
       txBuilder
         .vote(
           {
@@ -291,22 +307,21 @@ export default function VoteButton({
             txHash: txHash,
             txIndex: certIndex,
           },
-          {
-            voteKind: voteKind,
-          },
+          voteOptions,
         )
         .voteScript(drepCbor)
         .changeAddress(changeAddress);
         
+      const withRationale = voteOptions.anchor ? " with rationale" : "";
       await newTransaction({
         txBuilder,
-        description: `Vote: ${voteKind} - ${description}`,
+        description: `Vote: ${voteKind}${withRationale} - ${description}`,
         metadataValue: metadata ? { label: "674", value: metadata } : undefined,
       });
 
       toast({
         title: "Transaction Successful",
-        description: `Your vote (${voteKind}) has been recorded.`,
+        description: `Your vote (${voteKind}${withRationale}) has been recorded.`,
         duration: 5000,
       });
 
@@ -416,9 +431,19 @@ export default function VoteButton({
             {loading
               ? "Voting..."
               : utxos.length > 0
-                ? `Vote${hasValidProxy ? " (Proxy)" : ""}`
+                ? `Vote${hasValidProxy ? " (Proxy)" : ""}${anchor?.hash ? " + rationale" : ""}`
                 : "No UTxOs Available"}
           </Button>
+          {anchor?.hash && !hasValidProxy && (
+            <p className="text-center text-xs text-muted-foreground">
+              Rationale will be attached on-chain.
+            </p>
+          )}
+          {anchor?.hash && hasValidProxy && (
+            <p className="text-center text-xs text-yellow-700 dark:text-yellow-300">
+              Note: proxy voting does not yet carry rationale on-chain.
+            </p>
+          )}
         </>
       )}
 
diff --git a/src/components/pages/wallet/governance/rationale/RationaleEditor.tsx b/src/components/pages/wallet/governance/rationale/RationaleEditor.tsx
new file mode 100644
index 00000000..8aca921e
--- /dev/null
+++ b/src/components/pages/wallet/governance/rationale/RationaleEditor.tsx
@@ -0,0 +1,274 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Textarea } from "@/components/ui/textarea";
+import { Badge } from "@/components/ui/badge";
+import { Loader2, Trash2 } from "lucide-react";
+import {
+  buildRationaleJsonLd,
+  computeAnchorHash,
+  loadRationaleFromUrl,
+  uploadRationaleToPinata,
+  type RationaleAnchor,
+} from "@/lib/governance/rationale";
+import { useToast } from "@/hooks/use-toast";
+
+export type RationaleEditorValue = {
+  comment: string;
+  anchor: RationaleAnchor | null;
+};
+
+type Props = {
+  /** Initial state when the editor mounts. */
+  initial?: Partial<RationaleEditorValue> & { url?: string };
+  /** Called whenever upload, load, or clear changes the persisted anchor. */
+  onChange?: (value: RationaleEditorValue) => void;
+  /** Compact layout for use inside tables/cards. */
+  compact?: boolean;
+  /** Hide the "Load from URL" affordance — useful when the URL is managed externally. */
+  hideLoad?: boolean;
+  /** Show a "Clear" button that wipes the anchor. */
+  allowClear?: boolean;
+};
+
+export function RationaleEditor({
+  initial,
+  onChange,
+  compact = false,
+  hideLoad = false,
+  allowClear = false,
+}: Props) {
+  const { toast } = useToast();
+  const [comment, setComment] = useState(initial?.comment ?? "");
+  const [url, setUrl] = useState(initial?.anchor?.url ?? initial?.url ?? "");
+  const [hash, setHash] = useState(initial?.anchor?.hash ?? "");
+  const [json, setJson] = useState<string>(() =>
+    initial?.comment
+      ? JSON.stringify(buildRationaleJsonLd(initial.comment), null, 2)
+      : "",
+  );
+  const [busy, setBusy] = useState(false);
+
+  // If the initial URL is provided and there's no hash yet, auto-load.
+  useEffect(() => {
+    if (!url || hash) return;
+    let cancelled = false;
+    setBusy(true);
+    loadRationaleFromUrl(url)
+      .then((res) => {
+        if (cancelled) return;
+        setHash(res.hash);
+        setJson(JSON.stringify(res.json, null, 2));
+        if (res.comment && !comment) setComment(res.comment);
+        onChange?.({ comment: res.comment, anchor: { url, hash: res.hash } });
+      })
+      .catch(() => {
+        // Silent — the user can retry from the UI.
+      })
+      .finally(() => {
+        if (!cancelled) setBusy(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const liveJson = useMemo(() => {
+    if (!comment.trim()) return "";
+    return JSON.stringify(buildRationaleJsonLd(comment), null, 2);
+  }, [comment]);
+
+  const dirty = useMemo(() => {
+    if (!hash) return Boolean(comment.trim());
+    if (!comment.trim()) return false;
+    try {
+      const parsed = JSON.parse(json || "{}") as { body?: { comment?: string } };
+      return parsed.body?.comment !== comment;
+    } catch {
+      return true;
+    }
+  }, [comment, json, hash]);
+
+  const handleCommentChange = (next: string) => {
+    setComment(next);
+    setJson(next.trim() ? JSON.stringify(buildRationaleJsonLd(next), null, 2) : "");
+  };
+
+  const upload = useCallback(async () => {
+    if (!comment.trim()) {
+      toast({
+        title: "Add a comment",
+        description: "Enter a rationale before uploading.",
+        variant: "destructive",
+      });
+      return;
+    }
+    setBusy(true);
+    try {
+      const jsonLd = buildRationaleJsonLd(comment);
+      const anchor = await uploadRationaleToPinata(jsonLd);
+      setUrl(anchor.url);
+      setHash(anchor.hash);
+      setJson(JSON.stringify(jsonLd, null, 2));
+      onChange?.({ comment, anchor });
+      toast({
+        title: "Rationale uploaded",
+        description: "Anchor URL and hash are ready to attach to your vote.",
+      });
+    } catch (e) {
+      toast({
+        title: "Upload failed",
+        description: e instanceof Error ? e.message : "Could not upload rationale.",
+        variant: "destructive",
+      });
+    } finally {
+      setBusy(false);
+    }
+  }, [comment, onChange, toast]);
+
+  const load = useCallback(async () => {
+    const target = url.trim();
+    if (!target) {
+      toast({
+        title: "Missing URL",
+        description: "Enter a rationale URL to load.",
+        variant: "destructive",
+      });
+      return;
+    }
+    setBusy(true);
+    try {
+      const res = await loadRationaleFromUrl(target);
+      setHash(res.hash);
+      setJson(JSON.stringify(res.json, null, 2));
+      if (res.comment) setComment(res.comment);
+      onChange?.({
+        comment: res.comment || comment,
+        anchor: { url: target, hash: res.hash },
+      });
+      toast({
+        title: "Rationale loaded",
+        description: "Anchor hash computed from the linked document.",
+      });
+    } catch (e) {
+      toast({
+        title: "Load failed",
+        description: e instanceof Error ? e.message : "Could not load rationale.",
+        variant: "destructive",
+      });
+    } finally {
+      setBusy(false);
+    }
+  }, [url, comment, onChange, toast]);
+
+  const clear = () => {
+    setComment("");
+    setUrl("");
+    setHash("");
+    setJson("");
+    onChange?.({ comment: "", anchor: null });
+  };
+
+  const padding = compact ? "p-3" : "p-4";
+
+  return (
+    <div className={`space-y-3 rounded-lg border bg-card ${padding}`}>
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <div className="flex items-center gap-2">
+          <span className="text-sm font-semibold">Voting rationale</span>
+          {hash ? (
+            <Badge variant="secondary" className="text-[10px]">
+              Anchor ready · {hash.slice(0, 10)}…
+            </Badge>
+          ) : comment.trim() ? (
+            <Badge variant="outline" className="text-[10px]">
+              Draft (not uploaded)
+            </Badge>
+          ) : null}
+          {hash && dirty && (
+            <Badge variant="destructive" className="text-[10px]">
+              Edited — re-upload to refresh
+            </Badge>
+          )}
+        </div>
+        {allowClear && (hash || comment) && (
+          <Button size="sm" variant="ghost" onClick={clear} disabled={busy}>
+            <Trash2 className="mr-1 h-3 w-3" />
+            Clear
+          </Button>
+        )}
+      </div>
+
+      <div className="space-y-2">
+        <label className="text-xs font-medium text-muted-foreground">
+          Comment
+        </label>
+        <Textarea
+          value={comment}
+          onChange={(e) => handleCommentChange(e.target.value)}
+          placeholder="Why are you voting this way? Will be uploaded as CIP-100 JSON-LD."
+          className="min-h-[80px] text-xs"
+        />
+      </div>
+
+      {!hideLoad && (
+        <div className="space-y-2">
+          <label className="text-xs font-medium text-muted-foreground">
+            Rationale URL (paste to load existing)
+          </label>
+          <div className="flex gap-2">
+            <Input
+              type="url"
+              value={url}
+              onChange={(e) => {
+                setUrl(e.target.value);
+                if (e.target.value !== url) setHash("");
+              }}
+              onKeyDown={(e) => {
+                if (e.key === "Enter" && url.trim() && !busy) load();
+              }}
+              placeholder="https://ipfs.io/ipfs/..."
+              className="text-xs flex-1"
+            />
+            {url.trim() && (
+              <Button
+                size="sm"
+                variant="outline"
+                onClick={load}
+                disabled={busy}
+                className="text-xs"
+              >
+                {busy ? <Loader2 className="h-3 w-3 animate-spin" /> : "Load"}
+              </Button>
+            )}
+          </div>
+        </div>
+      )}
+
+      <Button
+        size="sm"
+        variant="secondary"
+        onClick={upload}
+        disabled={busy || !comment.trim()}
+        className="w-full text-xs"
+      >
+        {busy ? <Loader2 className="mr-1 h-3 w-3 animate-spin" /> : null}
+        {hash && !dirty ? "Re-upload to IPFS" : "Upload to IPFS"}
+      </Button>
+
+      {(liveJson || json) && (
+        <details>
+          <summary className="cursor-pointer text-xs font-medium text-muted-foreground hover:text-foreground">
+            View JSON-LD
+          </summary>
+          <Textarea
+            value={liveJson || json}
+            readOnly
+            className="mt-2 min-h-[120px] font-mono text-xs"
+          />
+        </details>
+      )}
+    </div>
+  );
+}
diff --git a/src/components/pages/wallet/governance/vote-card.tsx b/src/components/pages/wallet/governance/vote-card.tsx
index baa4dfdd..58bf0f07 100644
--- a/src/components/pages/wallet/governance/vote-card.tsx
+++ b/src/components/pages/wallet/governance/vote-card.tsx
@@ -4,9 +4,15 @@ import { useWalletsStore } from "@/lib/zustand/wallets";
 import { Input } from "@/components/ui/input";
 import { Label } from "@/components/ui/label";
 import { Textarea } from "@/components/ui/textarea";
+import { Button } from "@/components/ui/button";
 import { useState } from "react";
 import VoteButton from "./proposal/voteButtton";
 import type { UTxO } from "@meshsdk/core";
+import {
+  RationaleEditor,
+  type RationaleEditorValue,
+} from "./rationale/RationaleEditor";
+import { FileText } from "lucide-react";
 
 interface VoteCardProps {
   appWallet: Wallet;
@@ -27,6 +33,11 @@ export default function VoteCard({
   const [localProposalId, setLocalProposalId] = useState<string>(proposalId ?? "");
   const [description, setDescription] = useState<string>("");
   const [metadata, setMetadata] = useState<string>("");
+  const [showRationale, setShowRationale] = useState(false);
+  const [rationale, setRationale] = useState<RationaleEditorValue>({
+    comment: "",
+    anchor: null,
+  });
 
   return (
     <CardUI title="Vote for proposal" description="" cardClassName="col-span-2">
@@ -67,6 +78,40 @@ export default function VoteCard({
           />
         </div>
 
+        <div className="space-y-2">
+          {showRationale ? (
+            <RationaleEditor
+              initial={rationale}
+              onChange={setRationale}
+              allowClear
+            />
+          ) : (
+            <Button
+              variant="outline"
+              size="sm"
+              onClick={() => setShowRationale(true)}
+              className="w-full sm:w-auto"
+            >
+              <FileText className="mr-2 h-4 w-4" />
+              Attach voting rationale (optional)
+            </Button>
+          )}
+          {showRationale && (
+            <div className="flex justify-end">
+              <Button
+                variant="ghost"
+                size="sm"
+                onClick={() => {
+                  setShowRationale(false);
+                  setRationale({ comment: "", anchor: null });
+                }}
+              >
+                Hide rationale
+              </Button>
+            </div>
+          )}
+        </div>
+
         {!drepInfo?.active && (
           <p className="text-xs sm:text-sm text-muted-foreground">
             * Please register DRep before creating a vote transaction
@@ -82,6 +127,7 @@ export default function VoteCard({
             utxos={utxos}
             selectedBallotId={selectedBallotId}
             proposalTitle={proposalTitle}
+            anchor={rationale.anchor}
           />
         </div>
       </fieldset>
diff --git a/src/components/pages/wallet/info/index.tsx b/src/components/pages/wallet/info/index.tsx
index 1ecb1752..1a3d56b7 100644
--- a/src/components/pages/wallet/info/index.tsx
+++ b/src/components/pages/wallet/info/index.tsx
@@ -4,6 +4,7 @@ import CardInfo from "./card-info";
 import CardSigners from "./signers/card-signers";
 import { ManageContacts } from "./manage-contacts";
 import { MigrateWallet } from "./migrate-wallet";
+import { TransferWallet } from "./transfer-wallet";
 import { ArchiveWallet } from "./archive-wallet";
 import { UpgradeStakingWallet } from "./upgrade-staking-wallet";
 import ProxyControlCard from "./proxy-control";
@@ -22,6 +23,7 @@ export default function WalletInfo() {
         <CardSigners appWallet={appWallet} />
         <ManageContacts appWallet={appWallet} />
         <MigrateWallet appWallet={appWallet} />
+        <TransferWallet appWallet={appWallet} />
         <ProxyControlCard />
         {multisigWallet && <UpgradeStakingWallet mWallet={multisigWallet} appWallet={appWallet} />}
         {multisigWallet && <UpgradeGovernanceWallet mWallet={multisigWallet} />}
diff --git a/src/components/pages/wallet/info/transfer-wallet.tsx b/src/components/pages/wallet/info/transfer-wallet.tsx
new file mode 100644
index 00000000..84056ece
--- /dev/null
+++ b/src/components/pages/wallet/info/transfer-wallet.tsx
@@ -0,0 +1,307 @@
+import { useState } from "react";
+import CardUI from "@/components/ui/card-content";
+import { Button } from "@/components/ui/button";
+import { Checkbox } from "@/components/ui/checkbox";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Alert, AlertDescription } from "@/components/ui/alert";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Loader, Download, Send, CheckCircle, ExternalLink } from "lucide-react";
+import type { Wallet } from "@/types/wallet";
+import type { WalletTransferPayloadV1 } from "@/types/walletTransfer";
+import { toast } from "@/hooks/use-toast";
+import { api } from "@/utils/api";
+import { useUserStore } from "@/lib/zustand/user";
+
+type Mode = "download" | "push";
+
+export function TransferWallet({ appWallet }: { appWallet: Wallet }) {
+  const userAddress = useUserStore((s) => s.userAddress);
+  const isOwner = appWallet.ownerAddress === userAddress;
+
+  const [open, setOpen] = useState(false);
+  const [mode, setMode] = useState<Mode>("download");
+  const [includeContacts, setIncludeContacts] = useState(false);
+  const [includeBallots, setIncludeBallots] = useState(false);
+  const [targetUrl, setTargetUrl] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [resultInviteUrl, setResultInviteUrl] = useState<string | null>(null);
+
+  const exportMutation = api.wallet.exportTransferPayload.useMutation();
+
+  const reset = () => {
+    setMode("download");
+    setIncludeContacts(false);
+    setIncludeBallots(false);
+    setTargetUrl("");
+    setBusy(false);
+    setResultInviteUrl(null);
+  };
+
+  const downloadJson = (payload: WalletTransferPayloadV1) => {
+    const blob = new Blob([JSON.stringify(payload, null, 2)], {
+      type: "application/json",
+    });
+    const url = URL.createObjectURL(blob);
+    const safeName = (appWallet.name || "wallet").replace(/[^a-z0-9._-]+/gi, "_");
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = `${safeName}-transfer-${Date.now()}.json`;
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+    URL.revokeObjectURL(url);
+  };
+
+  const pushToTarget = async (
+    payload: WalletTransferPayloadV1,
+    rawTarget: string,
+  ) => {
+    let normalized = rawTarget.trim();
+    if (!normalized) throw new Error("Target instance URL is required");
+    if (!/^https?:\/\//i.test(normalized)) normalized = `https://${normalized}`;
+    const base = normalized.replace(/\/+$/, "");
+    const endpoint = `${base}/api/v1/wallet/transfer/import`;
+    const enriched: WalletTransferPayloadV1 = {
+      ...payload,
+      exportedFromOrigin: window.location.origin,
+    };
+    const res = await fetch(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(enriched),
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Target rejected the transfer (${res.status}): ${text || res.statusText}`);
+    }
+    return (await res.json()) as { newWalletId: string; inviteUrl: string };
+  };
+
+  const submit = async () => {
+    setBusy(true);
+    try {
+      const payload = await exportMutation.mutateAsync({
+        walletId: appWallet.id,
+        includeContacts,
+        includeBallots,
+      });
+      const enriched: WalletTransferPayloadV1 = {
+        ...payload,
+        exportedFromOrigin: window.location.origin,
+      };
+      if (mode === "download") {
+        downloadJson(enriched);
+        toast({
+          title: "Wallet exported",
+          description: "Transfer JSON downloaded.",
+        });
+        setOpen(false);
+        reset();
+      } else {
+        const result = await pushToTarget(payload, targetUrl);
+        setResultInviteUrl(result.inviteUrl);
+        toast({
+          title: "Wallet sent",
+          description: "Recipient instance accepted the transfer.",
+        });
+      }
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : "Transfer failed";
+      toast({
+        title: "Transfer failed",
+        description: msg,
+        variant: "destructive",
+      });
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <CardUI
+      title="Transfer Wallet"
+      description="Export this wallet's definition for use on another Multisig instance."
+      cardClassName="col-span-2"
+    >
+      <div className="space-y-3">
+        <p className="text-sm text-muted-foreground">
+          Sends the wallet definition (signers, threshold, script) to another
+          instance. On-chain history, balances, and pending transactions stay on
+          chain. Optionally include contacts and ballots.
+        </p>
+        <div>
+          <Button
+            onClick={() => setOpen(true)}
+            disabled={!isOwner}
+            className="w-full sm:w-auto"
+          >
+            Transfer to another instance
+          </Button>
+          {!isOwner && (
+            <p className="mt-2 text-xs text-muted-foreground">
+              Only the wallet owner can initiate a transfer.
+            </p>
+          )}
+        </div>
+      </div>
+
+      <Dialog
+        open={open}
+        onOpenChange={(o) => {
+          if (!o) reset();
+          setOpen(o);
+        }}
+      >
+        <DialogContent className="sm:max-w-lg">
+          <DialogHeader>
+            <DialogTitle>Transfer wallet</DialogTitle>
+            <DialogDescription>
+              Move &ldquo;{appWallet.name}&rdquo; to another Multisig instance.
+            </DialogDescription>
+          </DialogHeader>
+
+          {resultInviteUrl ? (
+            <div className="space-y-3">
+              <Alert>
+                <CheckCircle className="h-4 w-4" />
+                <AlertDescription>
+                  Transfer accepted. Share this invite link with signers on the
+                  target instance:
+                </AlertDescription>
+              </Alert>
+              <div className="flex items-center gap-2 rounded border p-2 text-sm break-all">
+                <ExternalLink className="h-4 w-4 shrink-0" />
+                <a
+                  className="underline"
+                  href={resultInviteUrl}
+                  target="_blank"
+                  rel="noreferrer"
+                >
+                  {resultInviteUrl}
+                </a>
+              </div>
+            </div>
+          ) : (
+            <div className="space-y-4">
+              <div className="space-y-2">
+                <Label>Method</Label>
+                <div className="grid grid-cols-1 gap-2 sm:grid-cols-2">
+                  <button
+                    type="button"
+                    onClick={() => setMode("download")}
+                    className={`rounded border p-3 text-left text-sm transition ${
+                      mode === "download"
+                        ? "border-primary bg-primary/5"
+                        : "hover:border-primary/40"
+                    }`}
+                  >
+                    <div className="flex items-center gap-2 font-medium">
+                      <Download className="h-4 w-4" />
+                      Download JSON
+                    </div>
+                    <p className="mt-1 text-xs text-muted-foreground">
+                      Save a file and upload on the target instance.
+                    </p>
+                  </button>
+                  <button
+                    type="button"
+                    onClick={() => setMode("push")}
+                    className={`rounded border p-3 text-left text-sm transition ${
+                      mode === "push"
+                        ? "border-primary bg-primary/5"
+                        : "hover:border-primary/40"
+                    }`}
+                  >
+                    <div className="flex items-center gap-2 font-medium">
+                      <Send className="h-4 w-4" />
+                      Send to instance URL
+                    </div>
+                    <p className="mt-1 text-xs text-muted-foreground">
+                      Push directly to a remote instance.
+                    </p>
+                  </button>
+                </div>
+              </div>
+
+              {mode === "push" && (
+                <div className="space-y-2">
+                  <Label htmlFor="target-url">Target instance URL</Label>
+                  <Input
+                    id="target-url"
+                    placeholder="https://multisig.example.com"
+                    value={targetUrl}
+                    onChange={(e) => setTargetUrl(e.target.value)}
+                  />
+                </div>
+              )}
+
+              <div className="space-y-2">
+                <Label>Include (optional)</Label>
+                <label className="flex items-center gap-2 text-sm">
+                  <Checkbox
+                    checked={includeContacts}
+                    onCheckedChange={(v) => setIncludeContacts(Boolean(v))}
+                  />
+                  Contacts (address book entries scoped to this wallet)
+                </label>
+                <label className="flex items-center gap-2 text-sm">
+                  <Checkbox
+                    checked={includeBallots}
+                    onCheckedChange={(v) => setIncludeBallots(Boolean(v))}
+                  />
+                  Ballots (governance ballots and rationale comments)
+                </label>
+              </div>
+            </div>
+          )}
+
+          <DialogFooter>
+            {resultInviteUrl ? (
+              <Button
+                onClick={() => {
+                  setOpen(false);
+                  reset();
+                }}
+              >
+                Done
+              </Button>
+            ) : (
+              <>
+                <Button
+                  variant="outline"
+                  onClick={() => {
+                    setOpen(false);
+                    reset();
+                  }}
+                  disabled={busy}
+                >
+                  Cancel
+                </Button>
+                <Button onClick={submit} disabled={busy || (mode === "push" && !targetUrl.trim())}>
+                  {busy ? (
+                    <>
+                      <Loader className="mr-2 h-4 w-4 animate-spin" />
+                      Working...
+                    </>
+                  ) : mode === "download" ? (
+                    "Download"
+                  ) : (
+                    "Send"
+                  )}
+                </Button>
+              </>
+            )}
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </CardUI>
+  );
+}
diff --git a/src/data/public-routes.ts b/src/data/public-routes.ts
index 8d21758f..90ab5ab7 100644
--- a/src/data/public-routes.ts
+++ b/src/data/public-routes.ts
@@ -5,5 +5,6 @@ export const publicRoutes = [
   "/governance/drep/[id]",
   "/features",
   "/api-docs",
-  "/dapps"
+  "/dapps",
+  "/bot-setup",
 ];
diff --git a/src/lib/governance/rationale.ts b/src/lib/governance/rationale.ts
new file mode 100644
index 00000000..c158655a
--- /dev/null
+++ b/src/lib/governance/rationale.ts
@@ -0,0 +1,114 @@
+import { hashDrepAnchor } from "@meshsdk/core";
+
+export type RationaleJsonLd = {
+  "@context": Record<string, unknown>;
+  authors: Array<{ name?: string }>;
+  body: { comment: string };
+  hashAlgorithm: "blake2b-256";
+};
+
+export type RationaleAnchor = {
+  url: string;
+  hash: string;
+};
+
+const CIP100_CONTEXT = {
+  CIP100: "https://github.com/cardano-foundation/CIPs/blob/master/CIP-0100/README.md#",
+  hashAlgorithm: "CIP100:hashAlgorithm",
+  body: {
+    "@id": "CIP100:body",
+    "@context": {
+      references: {
+        "@id": "CIP100:references",
+        "@container": "@set",
+        "@context": {
+          GovernanceMetadata: "CIP100:GovernanceMetadataReference",
+          Other: "CIP100:OtherReference",
+          label: "CIP100:reference-label",
+          uri: "CIP100:reference-uri",
+          referenceHash: {
+            "@id": "CIP100:referenceHash",
+            "@context": {
+              hashDigest: "CIP100:hashDigest",
+              hashAlgorithm: "CIP100:hashAlgorithm",
+            },
+          },
+        },
+      },
+      comment: "CIP100:comment",
+      externalUpdates: {
+        "@id": "CIP100:externalUpdates",
+        "@context": {
+          title: "CIP100:update-title",
+          uri: "CIP100:uri",
+        },
+      },
+    },
+  },
+  authors: {
+    "@id": "CIP100:authors",
+    "@container": "@set",
+    "@context": {
+      name: "http://xmlns.com/foaf/0.1/name",
+      witness: {
+        "@id": "CIP100:witness",
+        "@context": {
+          witnessAlgorithm: "CIP100:witnessAlgorithm",
+          publicKey: "CIP100:publicKey",
+          signature: "CIP100:signature",
+        },
+      },
+    },
+  },
+} as const;
+
+export function buildRationaleJsonLd(comment: string): RationaleJsonLd {
+  return {
+    "@context": CIP100_CONTEXT,
+    authors: [],
+    body: { comment: comment.trim() },
+    hashAlgorithm: "blake2b-256",
+  };
+}
+
+export function computeAnchorHash(jsonData: unknown): string {
+  return hashDrepAnchor(jsonData as Record<string, unknown>);
+}
+
+export async function uploadRationaleToPinata(
+  jsonLd: RationaleJsonLd | Record<string, unknown>,
+): Promise<RationaleAnchor> {
+  const payload = JSON.stringify(jsonLd, null, 2);
+  const response = await fetch("/api/pinata-storage/put", {
+    method: "POST",
+    headers: {
+      Accept: "application/json",
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      pathname: `rationale/rationale-${Date.now()}.jsonld`,
+      value: payload,
+    }),
+  });
+  if (!response.ok) {
+    const err = (await response.json().catch(() => ({}))) as { error?: string };
+    throw new Error(err?.error ?? `Upload failed (${response.status})`);
+  }
+  const res = (await response.json()) as { url: string };
+  const hash = computeAnchorHash(jsonLd);
+  return { url: res.url, hash };
+}
+
+export async function loadRationaleFromUrl(url: string): Promise<{
+  json: Record<string, unknown>;
+  comment: string;
+  hash: string;
+}> {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`Failed to fetch rationale (${res.status})`);
+  const data = (await res.json()) as Record<string, unknown>;
+  const hash = computeAnchorHash(data);
+  const body = (data?.body ?? {}) as { comment?: unknown };
+  const comment = typeof body.comment === "string" ? body.comment : "";
+  return { json: data, comment, hash };
+}
diff --git a/src/pages/api/llms-txt.ts b/src/pages/api/llms-txt.ts
new file mode 100644
index 00000000..d67e8b26
--- /dev/null
+++ b/src/pages/api/llms-txt.ts
@@ -0,0 +1,49 @@
+import type { NextApiRequest, NextApiResponse } from "next";
+
+export default function handler(req: NextApiRequest, res: NextApiResponse) {
+  if (req.method !== "GET") {
+    res.setHeader("Allow", "GET");
+    return res.status(405).end();
+  }
+
+  const proto = (req.headers["x-forwarded-proto"] as string | undefined) ?? "https";
+  const host = req.headers.host ?? "multisig.meshjs.dev";
+  const origin = `${proto}://${host}`;
+
+  const body = `# Mesh Multisig
+
+A Cardano multisig wallet platform. Sign transactions collaboratively,
+participate in governance, and integrate bots and AI agents into wallet
+workflows.
+
+## Primary docs
+
+- Bot setup guide (for AI agents): ${origin}/api/v1/botSetupGuide
+- Bot setup page (HTML rendering of same guide): ${origin}/bot-setup
+- API reference (OpenAPI / Swagger): ${origin}/api-docs
+
+## Key bot endpoints
+
+- POST ${origin}/api/v1/botRegister — bot self-registers, returns claim code
+- GET  ${origin}/api/v1/botPickupSecret?pendingBotId=... — bot retrieves credentials after human claim
+- POST ${origin}/api/v1/botAuth — exchange secret for short-lived JWT
+- GET  ${origin}/api/v1/botMe — bot self-info including owner address
+- GET  ${origin}/api/v1/walletIds?address=... — wallets the authenticated bot can access
+
+## Wallet transfer (cross-instance)
+
+- POST ${origin}/api/v1/wallet/transfer/import — receive a wallet definition exported from another instance
+- GET  ${origin}/api/v1/wallet/transfer/export?walletId=... — export a wallet (owner JWT required)
+
+## How to onboard an AI agent
+
+1. Fetch ${origin}/api/v1/botSetupGuide and follow the five-phase flow.
+2. The agent reports pendingBotId and claimCode to its human operator.
+3. The human approves and grants scopes in the UI at ${origin}/user.
+4. The agent picks up its secret and authenticates.
+`;
+
+  res.setHeader("Content-Type", "text/plain; charset=utf-8");
+  res.setHeader("Cache-Control", "public, max-age=300");
+  return res.status(200).send(body);
+}
diff --git a/src/pages/api/v1/botSetupGuide.ts b/src/pages/api/v1/botSetupGuide.ts
new file mode 100644
index 00000000..e34f51d4
--- /dev/null
+++ b/src/pages/api/v1/botSetupGuide.ts
@@ -0,0 +1,166 @@
+import type { NextApiRequest, NextApiResponse } from "next";
+
+const BOT_SCOPES = [
+  "multisig:read",
+  "multisig:create",
+  "multisig:sign",
+  "governance:read",
+  "ballot:write",
+] as const;
+
+function originFromRequest(req: NextApiRequest): string {
+  const proto = (req.headers["x-forwarded-proto"] as string | undefined) ?? "https";
+  const host = req.headers.host ?? "multisig.meshjs.dev";
+  return `${proto}://${host}`;
+}
+
+function buildGuide(origin: string): string {
+  return `# Mesh Multisig Bot Setup Guide
+
+This document is written for AI agents and developer scripts. It describes the
+exact HTTP calls needed to provision a bot identity on this instance and start
+operating against multisig wallets.
+
+Instance base URL: \`${origin}\`
+
+## Concepts
+
+- **Bot** — a non-human identity that authenticates with a stored secret and can
+  read or sign for multisig wallets to which it has been granted access.
+- **Owner** — the human user who claims a registered bot. Owners always
+  authorize scopes and grant wallet access.
+- **Scopes** — capabilities the bot may exercise. Available values:
+  ${BOT_SCOPES.map((s) => `\n  - \`${s}\``).join("")}
+- **Wallet access roles** — \`observer\` (read-only) or \`cosigner\` (can sign).
+
+## Five-phase setup
+
+### 1. Register (bot-initiated, no auth)
+
+\`POST ${origin}/api/v1/botRegister\`
+
+Body:
+\`\`\`json
+{
+  "name": "My Bot",
+  "paymentAddress": "addr1_your_bot_payment_address",
+  "stakeAddress": "stake1_optional",
+  "requestedScopes": ["multisig:read"]
+}
+\`\`\`
+
+Response:
+\`\`\`json
+{
+  "pendingBotId": "cxyz...",
+  "claimCode": "base64url_code...",
+  "claimExpiresAt": "ISO-8601 timestamp (10 minutes from now)"
+}
+\`\`\`
+
+Persist \`pendingBotId\` and \`claimCode\`. Surface both to the human user so
+they can approve in the UI within 10 minutes.
+
+### 2. Human claim (in the UI)
+
+The human navigates to the **User → Bot accounts** page and enters
+\`pendingBotId\` + \`claimCode\`. They review and approve scopes. On success
+the server provisions a \`BotKey\` + \`BotUser\` and stages a one-time secret
+for pickup. No action from the bot at this stage; poll
+\`GET ${origin}/api/v1/botPickupSecret?pendingBotId=...\` for readiness.
+
+### 3. Pickup credentials (bot-initiated, no auth)
+
+\`GET ${origin}/api/v1/botPickupSecret?pendingBotId=cxyz...\`
+
+Response (one-time only; secret is cleared after pickup):
+\`\`\`json
+{
+  "botKeyId": "key_id...",
+  "secret": "hex_secret...",
+  "paymentAddress": "addr1_your_bot_payment_address"
+}
+\`\`\`
+
+Persist \`botKeyId\` + \`secret\` in your bot config. Never log the secret.
+
+### 4. Authenticate (exchange secret for JWT)
+
+\`POST ${origin}/api/v1/botAuth\`
+
+Body:
+\`\`\`json
+{
+  "botKeyId": "key_id...",
+  "secret": "hex_secret...",
+  "paymentAddress": "addr1_your_bot_payment_address"
+}
+\`\`\`
+
+Response:
+\`\`\`json
+{
+  "token": "JWT...",
+  "botId": "bot_id..."
+}
+\`\`\`
+
+The JWT expires in 1 hour. Re-authenticate with the same secret when it
+expires; the secret itself does not rotate.
+
+### 5. Confirm and operate
+
+Send the bearer token on every subsequent request:
+\`Authorization: Bearer <token>\`
+
+Sanity check:
+\`GET ${origin}/api/v1/botMe\` — returns the bot's own info plus the
+\`ownerAddress\` of the human who claimed it.
+
+Once the human grants wallet access in the UI, the bot can call any
+bot-enabled endpoint within its scopes.
+
+## Bot-enabled endpoints
+
+| Method | Path | Required scope | Notes |
+| --- | --- | --- | --- |
+| GET  | \`/api/v1/botMe\` | — | Bot self-info. |
+| GET  | \`/api/v1/walletIds?address=<bot_address>\` | \`multisig:read\` | Wallets the bot can access. |
+| GET  | \`/api/v1/pendingTransactions\` | \`multisig:read\` | Pending sigs. |
+| GET  | \`/api/v1/freeUtxos\` | \`multisig:read\` | Wallet UTxOs. |
+| POST | \`/api/v1/createWallet\` | \`multisig:create\` | Create a wallet. |
+| POST | \`/api/v1/signTransaction\` | \`multisig:sign\` | Cosigner role required. |
+| GET  | \`/api/v1/governanceActiveProposals\` | \`governance:read\` | Live proposals. |
+| POST | \`/api/v1/botBallotsUpsert\` | \`ballot:write\` | Draft ballots. |
+
+## Error model
+
+- \`400\` — malformed request body or missing parameter.
+- \`401\` — missing/expired/invalid JWT, or secret mismatch.
+- \`403\` — insufficient scope or wallet access role.
+- \`409\` — disambiguation needed (e.g., ballot name collision).
+- \`429\` — rate limited.
+
+## Reference client
+
+A Node/TypeScript reference client lives at
+\`scripts/bot-ref/bot-client.ts\` in the repo. It exercises the full
+register → claim → pickup → auth → operate flow.
+
+## Audit
+
+All claim, auth, and privilege-changing actions are recorded in the
+\`AuditLog\` table on the server. Treat your bot's secret like a password.
+`;
+}
+
+export default function handler(req: NextApiRequest, res: NextApiResponse) {
+  if (req.method !== "GET") {
+    res.setHeader("Allow", "GET");
+    return res.status(405).end();
+  }
+  const guide = buildGuide(originFromRequest(req));
+  res.setHeader("Content-Type", "text/markdown; charset=utf-8");
+  res.setHeader("Cache-Control", "public, max-age=300");
+  return res.status(200).send(guide);
+}
diff --git a/src/pages/api/v1/wallet/transfer/export.ts b/src/pages/api/v1/wallet/transfer/export.ts
new file mode 100644
index 00000000..1424b349
--- /dev/null
+++ b/src/pages/api/v1/wallet/transfer/export.ts
@@ -0,0 +1,155 @@
+import type { NextApiRequest, NextApiResponse } from "next";
+import { db } from "@/server/db";
+import { verifyJwt } from "@/lib/verifyJwt";
+import { cors, addCorsCacheBustingHeaders } from "@/lib/cors";
+import { applyRateLimit } from "@/lib/security/requestGuards";
+import { getClientIP } from "@/lib/security/rateLimit";
+import { audit } from "@/lib/observability/audit";
+import {
+  WALLET_TRANSFER_FORMAT,
+  WALLET_TRANSFER_VERSION,
+  type WalletTransferBallot,
+  type WalletTransferContact,
+  type WalletTransferPayloadV1,
+  type WalletTransferType,
+} from "@/types/walletTransfer";
+
+const ALLOWED_TYPES: WalletTransferType[] = ["atLeast", "all", "any"];
+
+function parseIncludeFlags(raw: unknown): { contacts: boolean; ballots: boolean } {
+  const values = typeof raw === "string" ? raw.split(",") : Array.isArray(raw) ? raw : [];
+  const set = new Set(values.map((v) => (typeof v === "string" ? v.trim() : "")));
+  return { contacts: set.has("contacts"), ballots: set.has("ballots") };
+}
+
+export default async function handler(req: NextApiRequest, res: NextApiResponse) {
+  addCorsCacheBustingHeaders(res);
+
+  if (!applyRateLimit(req, res, { keySuffix: "v1/wallet/transfer/export" })) {
+    return;
+  }
+
+  await cors(req, res);
+  if (req.method === "OPTIONS") {
+    return res.status(200).end();
+  }
+
+  if (req.method !== "GET") {
+    return res.status(405).json({ error: "Method Not Allowed" });
+  }
+
+  const authHeader = req.headers.authorization;
+  const token = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : null;
+  if (!token) {
+    return res.status(401).json({ error: "Unauthorized - Missing token" });
+  }
+  const jwt = verifyJwt(token);
+  if (!jwt) {
+    return res.status(401).json({ error: "Invalid or expired token" });
+  }
+
+  const walletId = typeof req.query.walletId === "string" ? req.query.walletId : null;
+  if (!walletId) {
+    return res.status(400).json({ error: "walletId query parameter is required" });
+  }
+
+  const include = parseIncludeFlags(req.query.include);
+
+  const wallet = await db.wallet.findUnique({ where: { id: walletId } });
+  if (!wallet) {
+    return res.status(404).json({ error: "Wallet not found" });
+  }
+
+  const requester = jwt.address;
+  const isOwner = wallet.ownerAddress === requester;
+  if (!isOwner) {
+    void audit(db, {
+      actorAddress: requester,
+      actorType: "user",
+      action: "wallet.transfer.export",
+      resourceType: "wallet",
+      resourceId: walletId,
+      ip: getClientIP(req),
+      outcome: "denied",
+      reason: "not_owner",
+    });
+    return res.status(403).json({ error: "Only the wallet owner can export this wallet" });
+  }
+
+  const type: WalletTransferType = ALLOWED_TYPES.includes(wallet.type as WalletTransferType)
+    ? (wallet.type as WalletTransferType)
+    : "atLeast";
+
+  const payload: WalletTransferPayloadV1 = {
+    format: WALLET_TRANSFER_FORMAT,
+    version: WALLET_TRANSFER_VERSION,
+    exportedAt: new Date().toISOString(),
+    exportedFromOrigin:
+      (req.headers["x-forwarded-proto"] && req.headers.host
+        ? `${req.headers["x-forwarded-proto"]}://${req.headers.host}`
+        : `https://${req.headers.host ?? "multisig.meshjs.dev"}`),
+    exporterAddress: requester,
+    wallet: {
+      name: wallet.name,
+      description: wallet.description ?? "",
+      type,
+      signersAddresses: wallet.signersAddresses ?? [],
+      signersStakeKeys: wallet.signersStakeKeys ?? [],
+      signersDRepKeys: wallet.signersDRepKeys ?? [],
+      signersDescriptions: wallet.signersDescriptions ?? [],
+      numRequiredSigners: wallet.numRequiredSigners ?? null,
+      scriptCbor: wallet.scriptCbor,
+      stakeCredentialHash: wallet.stakeCredentialHash ?? null,
+      profileImageIpfsUrl: wallet.profileImageIpfsUrl ?? null,
+    },
+  };
+
+  if (include.contacts) {
+    const contacts = await db.contact.findMany({
+      where: { walletId },
+      orderBy: { createdAt: "asc" },
+      take: 500,
+    });
+    payload.contacts = contacts.map<WalletTransferContact>((c) => ({
+      name: c.name,
+      address: c.address,
+      description: c.description ?? null,
+    }));
+  }
+
+  if (include.ballots) {
+    const ballots = await db.ballot.findMany({
+      where: { walletId },
+      orderBy: { createdAt: "asc" },
+      take: 200,
+    });
+    payload.ballots = ballots.map<WalletTransferBallot>((b) => ({
+      description: b.description ?? null,
+      items: b.items ?? [],
+      itemDescriptions: b.itemDescriptions ?? [],
+      choices: b.choices ?? [],
+      anchorUrls: b.anchorUrls ?? [],
+      anchorHashes: b.anchorHashes ?? [],
+      rationaleComments: b.rationaleComments ?? [],
+      type: b.type,
+    }));
+  }
+
+  void audit(db, {
+    actorAddress: requester,
+    actorType: "user",
+    action: "wallet.transfer.export",
+    resourceType: "wallet",
+    resourceId: walletId,
+    ip: getClientIP(req),
+    outcome: "success",
+    metadata: {
+      includeContacts: include.contacts,
+      includeBallots: include.ballots,
+      signerCount: payload.wallet.signersAddresses.length,
+    },
+  });
+
+  res.setHeader("Cache-Control", "no-store");
+  return res.status(200).json(payload);
+}
diff --git a/src/pages/api/v1/wallet/transfer/import.ts b/src/pages/api/v1/wallet/transfer/import.ts
new file mode 100644
index 00000000..73fa66f2
--- /dev/null
+++ b/src/pages/api/v1/wallet/transfer/import.ts
@@ -0,0 +1,286 @@
+import type { NextApiRequest, NextApiResponse } from "next";
+import { db } from "@/server/db";
+import { cors, addCorsCacheBustingHeaders } from "@/lib/cors";
+import { applyRateLimit, enforceBodySize } from "@/lib/security/requestGuards";
+import { getClientIP } from "@/lib/security/rateLimit";
+import { audit } from "@/lib/observability/audit";
+import {
+  WALLET_TRANSFER_FORMAT,
+  WALLET_TRANSFER_VERSION,
+  type WalletTransferBallot,
+  type WalletTransferContact,
+  type WalletTransferDefinition,
+  type WalletTransferPayloadV1,
+  type WalletTransferType,
+} from "@/types/walletTransfer";
+
+const ALLOWED_TYPES: WalletTransferType[] = ["atLeast", "all", "any"];
+const MAX_SIGNERS = 200;
+const MAX_CONTACTS = 500;
+const MAX_BALLOTS = 200;
+
+function stripHtml(input: string): string {
+  let out = "";
+  let inTag = false;
+  for (let i = 0; i < input.length; i++) {
+    const ch = input[i]!;
+    if (ch === "<") {
+      inTag = true;
+      continue;
+    }
+    if (ch === ">") {
+      inTag = false;
+      continue;
+    }
+    if (!inTag) out += ch;
+  }
+  return out;
+}
+
+function sanitizeText(value: unknown, maxLen: number): string {
+  if (typeof value !== "string") return "";
+  return stripHtml(value).slice(0, maxLen).trim();
+}
+
+function asStringArray(value: unknown, maxItems: number, maxLen: number): string[] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .slice(0, maxItems)
+    .map((v) => (typeof v === "string" ? sanitizeText(v, maxLen) : ""));
+}
+
+function validateDefinition(input: unknown): { ok: true; value: WalletTransferDefinition } | { ok: false; error: string } {
+  if (typeof input !== "object" || input === null) {
+    return { ok: false, error: "wallet field must be an object" };
+  }
+  const w = input as Record<string, unknown>;
+  const name = sanitizeText(w.name, 256);
+  if (!name) return { ok: false, error: "wallet.name is required" };
+  const type = w.type as WalletTransferType;
+  if (!ALLOWED_TYPES.includes(type)) {
+    return { ok: false, error: "wallet.type must be 'atLeast', 'all', or 'any'" };
+  }
+  const scriptCbor = typeof w.scriptCbor === "string" ? w.scriptCbor.trim() : "";
+  if (!scriptCbor) {
+    return { ok: false, error: "wallet.scriptCbor is required" };
+  }
+  const signersAddresses = asStringArray(w.signersAddresses, MAX_SIGNERS, 512);
+  if (signersAddresses.length === 0) {
+    return { ok: false, error: "wallet.signersAddresses must be a non-empty array" };
+  }
+  const signersStakeKeys = asStringArray(w.signersStakeKeys, MAX_SIGNERS, 512);
+  const signersDRepKeys = asStringArray(w.signersDRepKeys, MAX_SIGNERS, 512);
+  const signersDescriptions = asStringArray(w.signersDescriptions, MAX_SIGNERS, 256);
+  const description = sanitizeText(w.description, 2000);
+
+  let numRequiredSigners: number | null = null;
+  if (type === "atLeast") {
+    const n = w.numRequiredSigners;
+    if (typeof n !== "number" || !Number.isFinite(n) || n < 1) {
+      return { ok: false, error: "wallet.numRequiredSigners must be a positive number when type is 'atLeast'" };
+    }
+    numRequiredSigners = Math.min(Math.floor(n), signersAddresses.length);
+  }
+
+  const stakeCredentialHash =
+    typeof w.stakeCredentialHash === "string" && w.stakeCredentialHash.length > 0
+      ? w.stakeCredentialHash
+      : null;
+  const profileImageIpfsUrl =
+    typeof w.profileImageIpfsUrl === "string" && w.profileImageIpfsUrl.length > 0
+      ? w.profileImageIpfsUrl.slice(0, 1024)
+      : null;
+
+  return {
+    ok: true,
+    value: {
+      name,
+      description,
+      type,
+      signersAddresses,
+      signersStakeKeys: signersStakeKeys.length ? signersStakeKeys : signersAddresses.map(() => ""),
+      signersDRepKeys: signersDRepKeys.length ? signersDRepKeys : signersAddresses.map(() => ""),
+      signersDescriptions: signersDescriptions.length ? signersDescriptions : signersAddresses.map(() => ""),
+      numRequiredSigners,
+      scriptCbor,
+      stakeCredentialHash,
+      profileImageIpfsUrl,
+    },
+  };
+}
+
+function validateContacts(input: unknown): WalletTransferContact[] {
+  if (!Array.isArray(input)) return [];
+  const result: WalletTransferContact[] = [];
+  for (const c of input.slice(0, MAX_CONTACTS)) {
+    if (typeof c !== "object" || c === null) continue;
+    const obj = c as Record<string, unknown>;
+    const name = sanitizeText(obj.name, 128);
+    const address = sanitizeText(obj.address, 512);
+    if (!name || !address) continue;
+    result.push({
+      name,
+      address,
+      description: sanitizeText(obj.description, 1000) || null,
+    });
+  }
+  return result;
+}
+
+function validateBallots(input: unknown): WalletTransferBallot[] {
+  if (!Array.isArray(input)) return [];
+  const result: WalletTransferBallot[] = [];
+  for (const b of input.slice(0, MAX_BALLOTS)) {
+    if (typeof b !== "object" || b === null) continue;
+    const obj = b as Record<string, unknown>;
+    const items = asStringArray(obj.items, 256, 256);
+    if (items.length === 0) continue;
+    result.push({
+      description: sanitizeText(obj.description, 1000) || null,
+      items,
+      itemDescriptions: asStringArray(obj.itemDescriptions, 256, 1000),
+      choices: asStringArray(obj.choices, 256, 32),
+      anchorUrls: asStringArray(obj.anchorUrls, 256, 1024),
+      anchorHashes: asStringArray(obj.anchorHashes, 256, 256),
+      rationaleComments: asStringArray(obj.rationaleComments, 256, 4000),
+      type:
+        typeof obj.type === "number" && Number.isFinite(obj.type)
+          ? Math.floor(obj.type)
+          : 0,
+    });
+  }
+  return result;
+}
+
+function buildInviteUrl(req: NextApiRequest, newWalletId: string): string {
+  const proto = (req.headers["x-forwarded-proto"] as string | undefined) ?? "https";
+  const host = req.headers.host ?? "multisig.meshjs.dev";
+  return `${proto}://${host}/wallets/invite/${newWalletId}`;
+}
+
+export default async function handler(req: NextApiRequest, res: NextApiResponse) {
+  addCorsCacheBustingHeaders(res);
+
+  if (!applyRateLimit(req, res, { keySuffix: "v1/wallet/transfer/import", maxRequests: 5 })) {
+    return;
+  }
+
+  await cors(req, res);
+  if (req.method === "OPTIONS") {
+    return res.status(200).end();
+  }
+
+  if (req.method !== "POST") {
+    return res.status(405).json({ error: "Method Not Allowed" });
+  }
+
+  if (!enforceBodySize(req, res, 200 * 1024)) {
+    return;
+  }
+
+  if (typeof req.body !== "object" || req.body === null) {
+    return res.status(400).json({ error: "Invalid request body" });
+  }
+
+  const body = req.body as Partial<WalletTransferPayloadV1>;
+
+  if (body.format !== WALLET_TRANSFER_FORMAT) {
+    return res.status(400).json({ error: "Invalid payload format" });
+  }
+  if (body.version !== WALLET_TRANSFER_VERSION) {
+    return res.status(400).json({ error: `Unsupported payload version (expected ${WALLET_TRANSFER_VERSION})` });
+  }
+
+  const validation = validateDefinition(body.wallet);
+  if (!validation.ok) {
+    return res.status(400).json({ error: validation.error });
+  }
+  const def = validation.value;
+
+  const contacts = validateContacts(body.contacts);
+  const ballots = validateBallots(body.ballots);
+
+  try {
+    const exporterAddress = sanitizeText(body.exporterAddress, 512) || null;
+    const exportedFromOrigin = sanitizeText(body.exportedFromOrigin, 512) || null;
+
+    const newWallet = await db.newWallet.create({
+      data: {
+        name: def.name,
+        description: def.description,
+        signersAddresses: def.signersAddresses,
+        signersStakeKeys: def.signersStakeKeys,
+        signersDRepKeys: def.signersDRepKeys,
+        signersDescriptions: def.signersDescriptions,
+        numRequiredSigners: def.numRequiredSigners ?? null,
+        ownerAddress: "all",
+        stakeCredentialHash: def.stakeCredentialHash,
+        scriptType: def.type,
+        paymentCbor: def.scriptCbor,
+        stakeCbor: "",
+        usesStored: false,
+        rawImportBodies: {
+          source: "wallet-transfer",
+          exporterAddress,
+          exportedFromOrigin,
+          exportedAt: typeof body.exportedAt === "string" ? body.exportedAt : null,
+          profileImageIpfsUrl: def.profileImageIpfsUrl ?? null,
+        },
+      },
+    });
+
+    if (contacts.length > 0) {
+      await db.contact.createMany({
+        data: contacts.map((c) => ({
+          walletId: newWallet.id,
+          name: c.name,
+          address: c.address,
+          description: c.description ?? null,
+        })),
+        skipDuplicates: true,
+      });
+    }
+
+    if (ballots.length > 0) {
+      await db.ballot.createMany({
+        data: ballots.map((b) => ({
+          walletId: newWallet.id,
+          description: b.description ?? null,
+          items: b.items,
+          itemDescriptions: b.itemDescriptions,
+          choices: b.choices,
+          anchorUrls: b.anchorUrls,
+          anchorHashes: b.anchorHashes,
+          rationaleComments: b.rationaleComments,
+          type: b.type,
+        })),
+      });
+    }
+
+    const inviteUrl = buildInviteUrl(req, newWallet.id);
+
+    void audit(db, {
+      actorAddress: exporterAddress,
+      actorType: "user",
+      action: "wallet.transfer.import",
+      resourceType: "wallet",
+      resourceId: newWallet.id,
+      ip: getClientIP(req),
+      outcome: "success",
+      metadata: {
+        exportedFromOrigin,
+        signerCount: def.signersAddresses.length,
+        contactCount: contacts.length,
+        ballotCount: ballots.length,
+      },
+    });
+
+    return res.status(200).json({
+      newWalletId: newWallet.id,
+      inviteUrl,
+    });
+  } catch (err) {
+    console.error("[api/v1/wallet/transfer/import] failed:", err);
+    return res.status(500).json({ error: "Failed to import wallet" });
+  }
+}
diff --git a/src/pages/bot-setup.tsx b/src/pages/bot-setup.tsx
new file mode 100644
index 00000000..c0e2ce9a
--- /dev/null
+++ b/src/pages/bot-setup.tsx
@@ -0,0 +1,45 @@
+import type { GetServerSideProps } from "next";
+import ReactMarkdown from "react-markdown";
+import remarkGfm from "remark-gfm";
+
+type Props = {
+  origin: string;
+  markdown: string;
+};
+
+export const getServerSideProps: GetServerSideProps<Props> = async (ctx) => {
+  const proto =
+    (ctx.req.headers["x-forwarded-proto"] as string | undefined) ?? "https";
+  const host = ctx.req.headers.host ?? "multisig.meshjs.dev";
+  const origin = `${proto}://${host}`;
+  let markdown = "";
+  try {
+    const res = await fetch(`${origin}/api/v1/botSetupGuide`);
+    markdown = await res.text();
+  } catch (e) {
+    markdown = `# Bot setup\n\nFailed to load guide: ${
+      e instanceof Error ? e.message : "unknown error"
+    }`;
+  }
+  return { props: { origin, markdown } };
+};
+
+export default function BotSetupPage({ origin, markdown }: Props) {
+  const rawUrl = `${origin}/api/v1/botSetupGuide`;
+  return (
+    <main className="mx-auto max-w-3xl px-4 py-8">
+      <div className="mb-6 flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between">
+        <h1 className="text-2xl font-semibold">Bot Setup</h1>
+        <a
+          className="text-sm underline text-muted-foreground"
+          href={rawUrl}
+        >
+          Raw markdown ({rawUrl.replace(/^https?:\/\//, "")})
+        </a>
+      </div>
+      <article className="prose prose-sm dark:prose-invert max-w-none">
+        <ReactMarkdown remarkPlugins={[remarkGfm]}>{markdown}</ReactMarkdown>
+      </article>
+    </main>
+  );
+}
diff --git a/src/server/api/routers/wallets.ts b/src/server/api/routers/wallets.ts
index 340ebf91..b48301a0 100644
--- a/src/server/api/routers/wallets.ts
+++ b/src/server/api/routers/wallets.ts
@@ -6,6 +6,16 @@ import type { AuthCtx } from "@/server/api/trpc";
 import type { RawImportBodies } from "@/types/wallet";
 import { Prisma } from "@prisma/client";
 import { audit } from "@/lib/observability/audit";
+import {
+  WALLET_TRANSFER_FORMAT,
+  WALLET_TRANSFER_VERSION,
+  type WalletTransferBallot,
+  type WalletTransferContact,
+  type WalletTransferPayloadV1,
+  type WalletTransferType,
+} from "@/types/walletTransfer";
+
+const TRANSFER_ALLOWED_TYPES: WalletTransferType[] = ["atLeast", "all", "any"];
 
 const requireSessionAddress = (ctx: AuthCtx) => {
   const address = ctx.session?.user?.id ?? ctx.sessionAddress;
@@ -755,4 +765,115 @@ export const walletRouter = createTRPCRouter({
       });
       return updated;
     }),
+
+  exportTransferPayload: protectedProcedure
+    .input(
+      z.object({
+        walletId: z.string(),
+        includeContacts: z.boolean().default(false),
+        includeBallots: z.boolean().default(false),
+      }),
+    )
+    .mutation(async ({ ctx, input }) => {
+      const sessionAddress = requireSessionAddress(ctx);
+      const sessionWallets: string[] = ctx.sessionWallets ?? [];
+      const requesters = sessionWallets.length > 0 ? sessionWallets : [sessionAddress];
+
+      const wallet = await ctx.db.wallet.findUnique({ where: { id: input.walletId } });
+      if (!wallet) {
+        throw new TRPCError({ code: "NOT_FOUND", message: "Wallet not found" });
+      }
+      const isOwner = requesters.some((a) => wallet.ownerAddress === a);
+      if (!isOwner) {
+        void audit(ctx.db, {
+          actorAddress: sessionAddress,
+          actorType: "user",
+          action: "wallet.transfer.export",
+          resourceType: "wallet",
+          resourceId: input.walletId,
+          ip: ctx.ip ?? null,
+          outcome: "denied",
+          reason: "not_owner",
+        });
+        throw new TRPCError({
+          code: "FORBIDDEN",
+          message: "Only the wallet owner can export this wallet",
+        });
+      }
+
+      const type: WalletTransferType = TRANSFER_ALLOWED_TYPES.includes(
+        wallet.type as WalletTransferType,
+      )
+        ? (wallet.type as WalletTransferType)
+        : "atLeast";
+
+      const payload: WalletTransferPayloadV1 = {
+        format: WALLET_TRANSFER_FORMAT,
+        version: WALLET_TRANSFER_VERSION,
+        exportedAt: new Date().toISOString(),
+        exportedFromOrigin: "",
+        exporterAddress: sessionAddress,
+        wallet: {
+          name: wallet.name,
+          description: wallet.description ?? "",
+          type,
+          signersAddresses: wallet.signersAddresses ?? [],
+          signersStakeKeys: wallet.signersStakeKeys ?? [],
+          signersDRepKeys: wallet.signersDRepKeys ?? [],
+          signersDescriptions: wallet.signersDescriptions ?? [],
+          numRequiredSigners: wallet.numRequiredSigners ?? null,
+          scriptCbor: wallet.scriptCbor,
+          stakeCredentialHash: wallet.stakeCredentialHash ?? null,
+          profileImageIpfsUrl: wallet.profileImageIpfsUrl ?? null,
+        },
+      };
+
+      if (input.includeContacts) {
+        const contacts = await ctx.db.contact.findMany({
+          where: { walletId: input.walletId },
+          orderBy: { createdAt: "asc" },
+          take: 500,
+        });
+        payload.contacts = contacts.map<WalletTransferContact>((c) => ({
+          name: c.name,
+          address: c.address,
+          description: c.description ?? null,
+        }));
+      }
+
+      if (input.includeBallots) {
+        const ballots = await ctx.db.ballot.findMany({
+          where: { walletId: input.walletId },
+          orderBy: { createdAt: "asc" },
+          take: 200,
+        });
+        payload.ballots = ballots.map<WalletTransferBallot>((b) => ({
+          description: b.description ?? null,
+          items: b.items ?? [],
+          itemDescriptions: b.itemDescriptions ?? [],
+          choices: b.choices ?? [],
+          anchorUrls: b.anchorUrls ?? [],
+          anchorHashes: b.anchorHashes ?? [],
+          rationaleComments: b.rationaleComments ?? [],
+          type: b.type,
+        }));
+      }
+
+      void audit(ctx.db, {
+        actorAddress: sessionAddress,
+        actorType: "user",
+        action: "wallet.transfer.export",
+        resourceType: "wallet",
+        resourceId: input.walletId,
+        ip: ctx.ip ?? null,
+        outcome: "success",
+        metadata: {
+          includeContacts: input.includeContacts,
+          includeBallots: input.includeBallots,
+          signerCount: payload.wallet.signersAddresses.length,
+        },
+      });
+
+      return payload;
+    }),
 });
diff --git a/src/types/walletTransfer.ts b/src/types/walletTransfer.ts
new file mode 100644
index 00000000..f51341b0
--- /dev/null
+++ b/src/types/walletTransfer.ts
@@ -0,0 +1,46 @@
+export const WALLET_TRANSFER_FORMAT = "multisig-wallet-transfer" as const;
+export const WALLET_TRANSFER_VERSION = 1 as const;
+
+export type WalletTransferType = "atLeast" | "all" | "any";
+
+export type WalletTransferDefinition = {
+  name: string;
+  description: string;
+  type: WalletTransferType;
+  signersAddresses: string[];
+  signersStakeKeys: string[];
+  signersDRepKeys: string[];
+  signersDescriptions: string[];
+  numRequiredSigners: number | null;
+  scriptCbor: string;
+  stakeCredentialHash: string | null;
+  profileImageIpfsUrl?: string | null;
+};
+
+export type WalletTransferContact = {
+  name: string;
+  address: string;
+  description?: string | null;
+};
+
+export type WalletTransferBallot = {
+  description?: string | null;
+  items: string[];
+  itemDescriptions: string[];
+  choices: string[];
+  anchorUrls: string[];
+  anchorHashes: string[];
+  rationaleComments: string[];
+  type: number;
+};
+
+export type WalletTransferPayloadV1 = {
+  format: typeof WALLET_TRANSFER_FORMAT;
+  version: typeof WALLET_TRANSFER_VERSION;
+  exportedAt: string;
+  exportedFromOrigin: string;
+  exporterAddress: string;
+  wallet: WalletTransferDefinition;
+  contacts?: WalletTransferContact[];
+  ballots?: WalletTransferBallot[];
+};