dexe-mcp 0.5.7 → 0.6.0

package/README.md

@@ -1,56 +1,99 @@
-# dexe-mcp
+<p align="center">
+  <a href="https://www.npmjs.com/package/dexe-mcp">
+    <img src="./assets/hero.svg" alt="dexe-mcp — the runtime for autonomous DAOs" width="100%"/>
+  </a>
+</p>
 
-![npm](https://img.shields.io/npm/v/dexe-mcp.svg)
+<p align="center">
+  <a href="https://www.npmjs.com/package/dexe-mcp"><img alt="npm" src="https://img.shields.io/npm/v/dexe-mcp.svg?style=flat-square&labelColor=0b0f1e&color=9BB4FF"></a>
+  <a href="https://nodejs.org"><img alt="node" src="https://img.shields.io/node/v/dexe-mcp.svg?style=flat-square&labelColor=0b0f1e&color=E07AFF"></a>
+  <a href="https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/npm/l/dexe-mcp.svg?style=flat-square&labelColor=0b0f1e&color=FFC878"></a>
+  <a href="https://modelcontextprotocol.io"><img alt="MCP-compatible" src="https://img.shields.io/badge/MCP-compatible-9BB4FF?style=flat-square&labelColor=0b0f1e"></a>
+  <a href="https://github.com/edward-arinin-web-dev/dexe-mcp"><img alt="tools" src="https://img.shields.io/badge/tools-149-7CF2D1?style=flat-square&labelColor=0b0f1e"></a>
+  <a href="https://github.com/edward-arinin-web-dev/dexe-mcp"><img alt="proposal types" src="https://img.shields.io/badge/proposal--types-33-E07AFF?style=flat-square&labelColor=0b0f1e"></a>
+</p>
 
-MCP server that gives AI agents **full DeXe Protocol DAO operations coverage** — deploy DAOs, build any of the 33 proposal types the DeXe UI exposes, upload metadata to IPFS, stake/delegate/vote/execute/claim. Plus dev tooling: build/test/lint, contract introspection, ABI-aware calldata decoding.
+<h2 align="center">Governance, as a function call.</h2>
 
-**Two write modes, calldata-default.** Every write tool returns a ready-to-sign `TxPayload = { to, data, value, chainId, description }` that the agent's wallet (MetaMask, Safe, hardware, etc.) signs and submits — no key in the MCP. Power users who *want* the server to sign and broadcast can opt in by setting `DEXE_PRIVATE_KEY`; that unlocks `dexe_tx_send`, `dexe_tx_status`, and the auto-broadcast branch of `dexe_proposal_create` / `dexe_proposal_vote_and_execute`. Default stays calldata-only.
+<p align="center">
+  <code>dexe-mcp</code> turns the entire DeXe Protocol — every DAO, every proposal type, every read, every write — into <b>one Model Context Protocol server</b>.<br/>
+  Plug it into Claude, Cursor, ChatGPT, or any tool-using LLM and watch your agent <b>deploy DAOs, draft proposals, vote, delegate, execute, claim</b> — straight from natural language.<br/>
+  <sub>Calldata-first by default: keys stay in your wallet. Broadcast mode? One env var.</sub>
+</p>
 
-**126 tools** across 14 groups. Call `dexe_proposal_catalog` at runtime for the full proposal-type map, or browse the [catalog](#tool-catalog) below.
+<p align="center">
+  <a href="#quickstart"><b>Quickstart</b></a> &nbsp;·&nbsp;
+  <a href="#what-you-can-build">What you can build</a> &nbsp;·&nbsp;
+  <a href="#built-for-whats-next">Built for what's next</a> &nbsp;·&nbsp;
+  <a href="#tool-catalog">Tool catalog</a> &nbsp;·&nbsp;
+  <a href="#swarm-test-harness">Swarm tests</a> &nbsp;·&nbsp;
+  <a href="https://github.com/edward-arinin-web-dev/dexe-mcp/tree/main/docs">Docs</a>
+</p>
 
-> **End-to-end coverage.** Every proposal-builder tool ships with a swarm-test scenario that exercises it on BSC testnet. Latest pass (2026-05-12): **57 scenarios shipped**, broadcasts validated against two fixture DAOs (Polaris 50%-quorum + Sentinel 5%-quorum-with-validators). See [Swarm test harness](#swarm-test-harness) below.
+---
 
-## Prerequisites
+## The shift
 
-- **Node.js ≥ 20** with a working `npm` (`node --version` and `npm --version` must both succeed).
-- **Git** — only needed the first time a build tool runs, to clone DeXe-Protocol. Skippable if you point `DEXE_PROTOCOL_PATH` at an existing checkout.
+For a decade, DAOs lived behind dashboards. Every action was a click. Every read was a tab. Every coordination loop needed a human at the keyboard.
 
-## Install
+That era is ending.
 
-```bash
-npm install -g dexe-mcp
-```
+LLMs can now reason about voting power, weigh proposals against a mandate, draft calldata, simulate execution, and ask your wallet to sign — **continuously, across every DAO you care about, all at once.** What was a UI is becoming a conversation. What was a treasurer's spreadsheet is becoming an always-on agent.
 
-Register the server with your MCP client (`.mcp.json`, `claude_desktop_config.json`, etc.):
+**`dexe-mcp` is the substrate that makes it real for the DeXe stack — and now for external OpenZeppelin Governor DAOs as well.** One MCP server. 149 typed tools across 18 groups. Every flow the DeXe frontend exposes — plus a generic `dexe_gov_*` surface targeting Uniswap, Compound, and Optimism.
 
-```json
-{
-  "mcpServers": {
-    "dexe": {
-      "command": "dexe-mcp"
-    }
-  }
-}
-```
+|     | What you get |
+|-----|------|
+| **Total protocol coverage** | All **33 proposal types**. Validator chamber. Expert delegation. OTC multi-tier sales with merkle whitelists. Internal config. Off-chain backend. Nothing hand-rolled. Nothing missing. |
+| **Key-safe by default** | Every write returns `TxPayload = { to, data, value, chainId }`. Your wallet — MetaMask, Safe, Ledger, anything — signs. **No keys touch the MCP unless you explicitly set `DEXE_PRIVATE_KEY`.** |
+| **Battle-tested on-chain** | **57 swarm-test scenarios** running on BSC testnet against real fixture DAOs. Every builder validated end-to-end — draft → IPFS → propose → vote → execute. Latest pass: 2026-05-12. |
+| **AI-native, model-agnostic** | Tool names, argument schemas, and return shapes are tuned for LLM chaining. Works with Claude, GPT, Gemini, Mistral, Llama — anything that can call MCP tools. |
+| **Open source, no middleman** | MIT. Your RPC. Your wallet. Your keys. Your rules. No telemetry. No SaaS gatekeeper. No rate limits. Run it on your laptop or behind your agent fleet. |
 
-If your client can't spawn the bare `dexe-mcp` command directly (a known issue with some MCP clients on Windows when PATH-shim resolution is involved), point it at the installed script via Node:
+---
 
-```json
-{
-  "mcpServers": {
-    "dexe": {
-      "command": "node",
-      "args": ["<output of `npm root -g`>/dexe-mcp/dist/index.js"]
-    }
-  }
-}
-```
+## What you can build
+
+> **One MCP server. Dozens of products that didn't exist a year ago.**
+
+- **Governance copilots in chat** — *"Show every proposal I haven't voted on across all my DAOs, ranked by deadline."* The agent fans out `dexe_user_inbox`, ranks results, drafts your votes. You hit sign.
+- **Intent-driven proposal drafting** — *"Stream 50,000 USDT from treasury to the dev fund, vesting linearly over six months."* The agent picks the right builder (`_token_distribution`), assembles nested calldata, pins metadata to IPFS, returns one signable payload. What used to be a 14-field form is now a sentence.
+- **AI delegates that reason** — agents that read every proposal, weigh it against a written mandate, vote, and publish their reasoning on-chain. Real accountability for delegated power.
+- **24/7 autonomous treasury bots** — policy expressed as code, executed as proposals. Market triggers, runway thresholds, vesting schedules — all enforced without a human in the loop, every action a signed on-chain decision.
+- **Multi-DAO coalition orchestration** — one agent coordinating votes across allied protocols, tracking quorums, building coalitions, executing in lockstep.
+- **Conversational DAO frontends** — apps where there *is* no UI. The MCP server is the backend. The chat is the dashboard. The wallet is the only button.
+- **Adversarial governance simulators** — spin up swarms of AI proposers, voters, and validators to red-team a parameter change *before* it hits mainnet. The swarm harness ships with this already (see [Swarm tests](#swarm-test-harness)).
+- **OTC sale autopilots** — open multi-tier sales with merkle whitelists, manage buyer flows, fulfill vested payouts — all without a sale-management UI.
+- **Forensics and compliance** — `dexe_decode_proposal` + `_decode_calldata` make any historic on-chain proposal human-readable. Agents narrate every governance decision for audits, postmortems, and research.
+
+If you can describe a DeXe governance operation in a sentence, `dexe-mcp` has the tool.
+
+---
+
+## Built for what's next
+
+The next generation of DAOs will be **operated by language, not by clicks.**
+
+- **AI delegates will outvote human ones.** They read every proposal. They show their reasoning. They never miss a deadline.
+- **Treasuries will defend themselves.** Policy bots react to market moves, rebalance, claim, redelegate — all through governance, never around it.
+- **Cross-DAO coordination will be ambient.** Coalitions form in seconds via agent-to-agent negotiation, ratified by on-chain votes.
+- **Governance frontends will collapse into chat.** The dashboard moves into the conversation. The UI is the prompt.
+- **Every proposal will be simulated first.** Adversarial AI swarms stress-test changes before they reach mainnet.
+- **Audit will run continuously.** Compliance agents decode and narrate every historical decision in real time.
 
-Run `npm root -g` to resolve the path on your machine. Restart the MCP client and the `dexe_*` tools will appear.
+`dexe-mcp` is the connective tissue. Bring your model. Bring your wallet. Bring your DAO.
+
+---
 
 ## Quickstart
 
-Minimum config to get **read-only** access to a BSC mainnet DAO:
+**1.** Install:
+
+```bash
+npm install -g dexe-mcp
+```
+
+**2.** Register with your MCP client (`.mcp.json`, `claude_desktop_config.json`, Cursor settings, etc.):
 
 ```json
 {
@@ -66,35 +109,50 @@ Minimum config to get **read-only** access to a BSC mainnet DAO:
 }
 ```
 
-Add `DEXE_PINATA_JWT` for IPFS uploads, `DEXE_BACKEND_API_URL` for off-chain proposals, and per-chain subgraph URLs for `dexe_proposal_voters` and the DAO-list reads. Full matrix → [`docs/ENVIRONMENT.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/ENVIRONMENT.md).
+> **Windows note:** if your MCP client can't resolve the `dexe-mcp` shim on PATH, point it at the installed script directly:
+> ```json
+> { "command": "node", "args": ["<npm root -g>/dexe-mcp/dist/index.js"] }
+> ```
+> (Run `npm root -g` to get the absolute path.)
 
-Three first-call examples (full set in [`docs/USAGE.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/USAGE.md)):
+**3.** Ask your agent something governance-shaped:
 
 ```jsonc
-// 1) discover available proposal types
+// Discover every proposal type your DAO can run
 dexe_proposal_catalog({ category: "all", implementedOnly: true })
 
-// 2) read a DAO
+// Snapshot a DAO — treasury, voters, settings, validators, everything
 dexe_dao_info({ govPool: "0x..." })
 
-// 3) build a token-transfer proposal (calldata only)
+// Draft a token-transfer proposal (returns ready-to-sign calldata)
 dexe_proposal_build_token_transfer({
-  govPool: "0x...",
-  token:   "0x...",
+  govPool:   "0x...",
+  token:     "0x...",
   recipient: "0x...",
-  amount: "1000000000000000000"
+  amount:    "1000000000000000000"
 })
 ```
 
+The agent gets back a `TxPayload`. Pass it to your wallet. Sign. Submit. Done.
+
+**Want the MCP to broadcast too?** Set `DEXE_PRIVATE_KEY` and unlock the composite signing flow (`dexe_proposal_create`, `dexe_proposal_vote_and_execute`, `dexe_tx_send`, `dexe_tx_status`). Strictly opt-in — default stays calldata-only.
+
+---
+
+## Prerequisites
+
+- **Node.js ≥ 20** with a working `npm` (`node --version` and `npm --version` must both succeed).
+- **Git** — needed the first time a build tool (`dexe_compile` / `dexe_test` / `dexe_lint`) runs, to shallow-clone DeXe-Protocol. Skippable if you set `DEXE_PROTOCOL_PATH` to an existing checkout.
+
 ## First run
 
-The MCP server starts instantly. On the first build-tool call (`dexe_compile` / `dexe_test` / `dexe_lint`), dexe-mcp will automatically shallow-clone DeXe-Protocol into a platform cache directory and run `npm install` there once. If you prefer to reuse an existing checkout, set `DEXE_PROTOCOL_PATH` in the MCP `env` block and nothing will be cloned.
+The MCP server starts instantly. On the first build-tool call, dexe-mcp shallow-clones DeXe-Protocol into a platform cache directory and runs `npm install` there once. Most tools never need that checkout — reads, proposal builders, vote tools, and deploy only need an RPC URL.
 
-Most tools don't need the protocol checkout at all — read/proposal/vote/deploy builders only need an RPC URL. Only the dev-tooling group (`dexe_compile`, `dexe_test`, `dexe_coverage`, `dexe_lint`, and the introspection tools) depends on artifacts.
+---
 
 ## Environment variables
 
-All optional. Tools that need a missing variable fail with a clear message pointing at exactly what to set. Full matrix + per-tool requirements → [`docs/ENVIRONMENT.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/ENVIRONMENT.md).
+All optional. Tools that need a missing variable fail with a clear, actionable message pointing at exactly what to set. Full matrix → [`docs/ENVIRONMENT.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/ENVIRONMENT.md).
 
 | Variable | Required for | Purpose |
 |----------|--------------|---------|
@@ -103,86 +161,92 @@ All optional. Tools that need a missing variable fail with a clear message point
 | `DEXE_CHAIN_ID` | reads | Defaults to `56` (BSC mainnet). Override for other chains |
 | `DEXE_CONTRACTS_REGISTRY` | reads (optional) | Override the ContractsRegistry root; defaults to the known per-chain address |
 | `DEXE_PINATA_JWT` | IPFS uploads | Pinata JWT for pinning proposal/DAO metadata |
-| `DEXE_IPFS_GATEWAY` | IPFS fetch | **Dedicated** gateway URL (Pinata provides one alongside your JWT; Filebase / Quicknode / self-hosted also work). Public gateways are unreliable and NOT defaulted |
+| `DEXE_IPFS_GATEWAY` | IPFS fetch | **Dedicated** gateway URL (Pinata, Filebase, Quicknode, self-hosted). Public gateways are unreliable and NOT defaulted |
 | `DEXE_IPFS_GATEWAYS_FALLBACK` | IPFS fetch (optional) | Comma-separated public gateways tried sequentially after the primary |
-| `DEXE_SUBGRAPH_POOLS_URL` | `dexe_read_dao_list`, `dexe_read_dao_members`, `dexe_read_delegation_map`, `dexe_read_dao_experts`, `dexe_user_inbox`, `dexe_proposal_voters`, `dexe_dao_predict_addresses` | The Graph endpoint for the DeXe pools subgraph |
+| `DEXE_SUBGRAPH_POOLS_URL` | `dexe_read_dao_list`, `_dao_members`, `_delegation_map`, `_dao_experts`, `_user_inbox`, `_proposal_voters`, `_dao_predict_addresses` | The Graph endpoint for the DeXe pools subgraph |
 | `DEXE_SUBGRAPH_VALIDATORS_URL` | `dexe_read_validator_list` | The Graph endpoint for the DeXe validators subgraph |
 | `DEXE_SUBGRAPH_INTERACTIONS_URL` | `dexe_read_user_activity` | The Graph endpoint for the DeXe interactions subgraph |
-| `DEXE_GRAPH_API_KEY` | subgraph reads (optional) | Bearer token for `gateway.thegraph.com`. Required only when `DEXE_SUBGRAPH_*_URL` does not embed the key in the path (`/api/<key>/subgraphs/...`). Auto-extracted from the URL when present |
+| `DEXE_GRAPH_API_KEY` | subgraph reads (optional) | Bearer token for `gateway.thegraph.com`. Required only when the URL doesn't embed the key. Auto-extracted from `/api/<key>/...` URLs |
 | `DEXE_BACKEND_API_URL` | off-chain proposals | DeXe backend (e.g. `https://api.dexe.io`) |
+| `DEXE_PRIVATE_KEY` | broadcast mode (opt-in) | Enables `_tx_send`, `_tx_status`, and the broadcast branch of composite flows. Default stays calldata-only |
+
+---
 
 ## Documentation
 
 Full docs in [`docs/`](https://github.com/edward-arinin-web-dev/dexe-mcp/tree/main/docs):
 
-- [`docs/TOOLS.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/TOOLS.md) — complete catalog of all 126 tools, organized by category, with one-line descriptions and required envs per tool.
-- [`docs/USAGE.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/USAGE.md) — 10 worked examples (deploy DAO, create proposals, vote, delegate, validator chamber, decode calldata, off-chain proposals, multicall batching). Copy-pasteable JSON.
-- [`docs/ENVIRONMENT.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/ENVIRONMENT.md) — full env-var reference: minimum block to get started, per-category requirements, calldata vs signer mode, chain-specific config, IPFS gateway rationale, subgraph migration, swarm harness envs, common pitfalls.
-
-## Tool surface (high-level)
-
-| Group | Tools | What |
-|-------|-------|------|
-| Dev tooling | 4 | Hardhat wrappers: `dexe_compile`, `_test`, `_coverage`, `_lint` |
-| Contract introspection | 10 | `_list_contracts`, `_get_abi`, `_get_methods`, `_get_selectors`, `_find_selector`, `_get_natspec`, `_get_source`, `_decode_calldata`, `_decode_proposal`, `_list_gov_contract_types` |
-| DAO reads | 25 | `_dao_info`, `_dao_predict_addresses`, `_dao_registry_lookup`, `_proposal_state/_list/_voters`, `_vote_user_power/_get_votes`, `_read_*` family |
-| IPFS | 6 | Pinata uploads, gateway fetch, CID computation |
-| DAO deploy | 1 | `dexe_dao_build_deploy` (encodes `PoolFactory.deployGovPool` with full nested struct + predicted addr wiring) |
-| Proposal catalog + primitives | 5 | `dexe_proposal_catalog` enumerates **all 33** types; primitives: `_build_external`, `_build_internal`, `_build_custom_abi`, `_build_offchain` |
-| External proposal wrappers | 20 | Token transfer / distribution / sale (single + multi-tier), treasury withdraw, validators, experts, staking tier, math model, blacklist, reward multiplier, apply to DAO, modify profile, change voting settings, new proposal type, addToWhitelist, etc. |
-| Internal validator wrappers | 4 | `_change_validator_balances`, `_change_validator_settings`, `_monthly_withdraw`, `_offchain_internal_proposal` |
-| Off-chain backend | 8 | `_offchain_single_option/_multi_option/_for_against/_settings`, auth flow (`_auth_request_nonce`, `_auth_login_request`), `_offchain_build_vote/_cancel_vote` |
-| Vote / stake / delegate / execute / claim | 16 | `_vote_build_*` family — every direct EOA write on GovPool / Validators |
-| Composite signing flows | 5 | `_proposal_create`, `_proposal_vote_and_execute`, `_tx_send`, `_tx_status`, `_get_config` (signing tools opt-in via `DEXE_PRIVATE_KEY`; `_get_config` is read-only diagnostic for the multi-chain config) |
-| Subgraph reads | 7 | DAO list, members, experts, user activity, delegation map, distribution status, OTC sale tiers per DAO (decentralized network endpoints + RPC fallback) |
-| Merkle utility | 2 | `dexe_merkle_build`, `dexe_merkle_proof` — OZ `StandardMerkleTree`-compatible (sorted-pair commutative keccak, double-hash leaf) |
-| OTC composites | 4 | `dexe_otc_dao_open_sale`, `_buyer_status`, `_buyer_buy`, `_buyer_claim_all` — full project-owner + buyer flows over `TokenSaleProposal`. See [`docs/OTC.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/OTC.md) |
-| Simulator | 3 | `dexe_sim_calldata`, `_sim_proposal`, `_sim_buy` — `eth_call`-based preflight with revert-reason decoding. See [`docs/SIMULATOR.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/SIMULATOR.md) |
-| Multi-DAO inbox + forecast | 2 | `dexe_user_inbox` — pending items across N DAOs (unvoted proposals, claimable rewards, locked deposits). `_proposal_forecast` — pass-rate prediction with quorum projection + risk flags. See [`docs/INBOX.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/INBOX.md) |
-
-Total: **126**. Per-tool descriptions, args, return shapes → [`docs/TOOLS.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/TOOLS.md).
+- [**`docs/TOOLS.md`**](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/TOOLS.md) — complete catalog of all 149 tools, grouped, with one-line descriptions and required envs.
+- [**`docs/GOVERNOR.md`**](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/GOVERNOR.md) — external OpenZeppelin / Bravo Governor surface (Uniswap, Compound, Optimism). Family branching, fixture map, paste-able JSON examples, Tally parity harness.
+- [**`docs/USAGE.md`**](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/USAGE.md) — 10 worked examples (deploy DAO, create/vote/execute proposals, delegate, validator chamber, decode calldata, off-chain proposals, multicall batching). Copy-pasteable JSON.
+- [**`docs/ENVIRONMENT.md`**](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/ENVIRONMENT.md) — env-var reference: minimum block to get started, per-category requirements, calldata vs signer mode, chain config, IPFS gateway rationale, subgraph migration, swarm-harness envs, common pitfalls.
+- [**`docs/OTC.md`**](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/OTC.md) — multi-tier OTC sale flows (project-owner and buyer paths).
+- [**`docs/SIMULATOR.md`**](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/SIMULATOR.md) — `eth_call`-based preflight with revert-reason decoding.
+- [**`docs/INBOX.md`**](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/INBOX.md) — cross-DAO inbox and proposal forecast.
+
+---
+
+## Tool catalog
+
+**149 tools, 18 groups.** Run `dexe_proposal_catalog` at runtime for the live proposal-type map. Full per-tool reference → [`docs/TOOLS.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/TOOLS.md).
+
+| Group | # | What it gives you |
+|-------|---|------|
+| **Dev tooling** | 4 | One-command Hardhat lifecycle for the DeXe-Protocol monorepo — `dexe_compile`, `_test`, `_coverage`, `_lint`. Auto-clones the repo on first call. |
+| **Contract introspection** | 10 | Ask the protocol about itself — list contracts, fetch ABIs, look up selectors, read NatSpec, view source, decode arbitrary calldata or full proposal payloads. The agent's reverse-engineer toolkit. |
+| **DAO reads** | 19 | Everything you'd see on a DAO dashboard, returned as JSON — `dao_info`, predicted helper addresses, proposal state/list/voters, voting power, treasury, settings, validators, staking, distributions, privacy policy. |
+| **IPFS** | 9 | Pinata uploads for files / avatars / DAO + proposal metadata, smart metadata updates, deterministic identicon generation, gateway-fallback fetch, CID computation without uploading. |
+| **DAO deploy** | 1 | `dexe_dao_build_deploy` — encodes the full nested `PoolFactory.deployGovPool` struct with predicted helper addresses pre-wired. From idea to a live DAO in one signed tx. |
+| **Proposal catalog + primitives** | 5 | `dexe_proposal_catalog` enumerates **all 33** proposal types with metadata + gating. Primitives `_build_external`, `_build_internal`, `_build_custom_abi`, `_build_offchain` cover anything not in a named wrapper. |
+| **External proposal wrappers** | 20 | Named builders for every common action: token transfer / distribution / sale (single + multi-tier), treasury withdraw, validators, experts, staking tier, math model, blacklist, reward multiplier, apply to DAO, modify profile, change voting settings, new proposal type, whitelist, and more. |
+| **Internal validator wrappers** | 4 | Validator-chamber proposals: `_change_validator_balances`, `_change_validator_settings`, `_monthly_withdraw`, `_offchain_internal_proposal`. |
+| **Off-chain backend** | 8 | Full DeXe-backend integration — nonce + SIWE login, off-chain proposal creation (single-option / multi-option / for-against / settings), off-chain vote + cancel. |
+| **Vote / stake / delegate / execute / claim** | 26 | Every direct EOA write on `GovPool` and `Validators` — deposit, vote, delegate, undelegate, execute, claim rewards, micropool rewards, staking flows, token-sale buy/claim/vesting, distribution claim, NFT multiplier lock/unlock, privacy policy signing, multicall. |
+| **Composite signing flows** | 5 | High-level flows for power users: `_proposal_create`, `_proposal_vote_and_execute`, `_tx_send`, `_tx_status`, `_get_config`. Signing tools opt-in via `DEXE_PRIVATE_KEY`. |
+| **Subgraph reads** | 7 | The Graph queries: DAO list, members, experts, validator list, user activity, delegation map, OTC sale tiers. Decentralized-network endpoints + RPC fallback. |
+| **Merkle utility** | 2 | `dexe_merkle_build`, `dexe_merkle_proof` — OZ `StandardMerkleTree`-compatible. For whitelisted sales and airdrops. |
+| **OTC composites** | 4 | Full project-owner + buyer flows over `TokenSaleProposal`: open multi-tier sale, check buyer status, buy native or with merkle proof, claim vested payouts. See [`docs/OTC.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/OTC.md). |
+| **Safe multisig** | 2 | Queue a tx in the Safe Transaction Service for owners to co-sign instead of broadcasting — `dexe_safe_info` (on-chain nonce/threshold/owners + endpoint), `dexe_safe_propose_tx` (compute `safeTxHash`, sign as owner, POST to the queue; dry-run by default). See [`docs/SAFE.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/SAFE.md). |
+| **Simulator** | 3 | `eth_call`-based preflight with decoded revert reasons — `_sim_calldata`, `_sim_proposal`, `_sim_buy`. Catch reverts before you pay gas. See [`docs/SIMULATOR.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/SIMULATOR.md). |
+| **Multi-DAO inbox + forecast** | 2 | `dexe_user_inbox` aggregates pending items (unvoted proposals, claimable rewards, locked deposits) across N DAOs. `_proposal_forecast` predicts pass rate with quorum projection + risk flags. See [`docs/INBOX.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/INBOX.md). |
+| **External Governor DAOs** | 18 | `dexe_gov_*` — read, build, simulate, and decode against OpenZeppelin Governor + Compound Bravo DAOs. Tier-1: Uniswap, Compound, Optimism. Config-only addition for new DAOs. Family-aware (OZ vs Bravo) propose / castVote / queue / execute / cancel / delegate. Eth-call dry-run + vote-impact projection. hasVoted + state + hashProposal + decode + descriptionHash utilities. Tally state-enum parity harness. See [`docs/GOVERNOR.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/GOVERNOR.md). |
+
+---
 
 ## Swarm test harness
 
-`tests/swarm/` is a multi-agent DAO testing harness that exercises every dexe-mcp
-tool against real BSC-testnet DAOs. Scenarios are JSON specs; the orchestrator
-loads them, resolves agent wallets, and runs each step through either an inline
-ethers dispatcher or the dexe-mcp stdio bridge.
-
-**57 scenarios shipped** covering:
-
-- Reset + delegation chains (S00, S01, S06, S14)
-- Validator chamber pass / veto / full lifecycle (S02, S03, S07)
-- Read-only snapshots: expert state, participation, validators, cross-DAO,
-  catalog, multi-proposal state, user activity (S04, S05, S09, S10, S11, S13, S15)
-- Cancel-vote, decode-and-introspect (S08, S12)
-- Build-only sanity for every proposal type in `dexe_proposal_catalog`
-  (token transfer, blacklist, withdraw treasury, apply to dao, token
-  distribution, token sale + recover, manage validators, change validator
-  balances/settings, monthly withdraw, add/remove expert (local + global),
-  delegate/revoke from expert, reward multiplier (4 modes), change voting
-  settings, new proposal type, change math model, custom ABI, manual calldata,
-  create staking tier, off-chain validator + for/against + settings) (S16–S40)
-- OTC multi-tier sale flows: open sale, buyer buy native + merkle (S41–S46)
-- Simulator + inbox + per-DAO reads (S47, S48, S50, S51)
-- **Broadcast lifecycle for the v0.5.6 builder rewrites: `withdraw_treasury`,
-  `apply_to_dao`, `reward_multiplier mint` (S52–S54)**
-- **Broadcast lifecycle for the most-used proposal types: `token_transfer`,
-  `blacklist`, `add_expert` (S55–S57)**
+[`tests/swarm/`](https://github.com/edward-arinin-web-dev/dexe-mcp/tree/main/tests/swarm) is a multi-agent DAO testing harness that runs every `dexe-mcp` tool against real BSC-testnet DAOs. Scenarios are JSON specs; the orchestrator resolves agent wallets and runs each step through either an inline ethers dispatcher or the dexe-mcp stdio bridge.
+
+It's also a reference implementation of one of the futures we described above — **adversarial AI agents stress-testing a DAO before it ships.**
+
+**57 scenarios shipped.** Coverage:
+
+- **Reset + delegation chains** — S00, S01, S06, S14
+- **Validator chamber** — pass / veto / full lifecycle (S02, S03, S07)
+- **Read-only snapshots** — expert state, participation, validators, cross-DAO, catalog, multi-proposal state, user activity (S04, S05, S09–S15)
+- **Cancel-vote + decode-and-introspect** — S08, S12
+- **Build-only sanity for every proposal type** in `dexe_proposal_catalog` — token transfer, blacklist, withdraw treasury, apply to DAO, token distribution, token sale + recover, manage validators, change validator balances/settings, monthly withdraw, add/remove expert (local + global), delegate/revoke from expert, reward multiplier (4 modes), change voting settings, new proposal type, change math model, custom ABI, manual calldata, create staking tier, off-chain validator + for/against + settings (S16–S40)
+- **OTC multi-tier sale flows** — open sale, buyer buy native + merkle (S41–S46)
+- **Simulator + inbox + per-DAO reads** — S47, S48, S50, S51
+- **Broadcast lifecycle (v0.5.6 builder rewrites)** — `withdraw_treasury`, `apply_to_dao`, `reward_multiplier mint` (S52–S54)
+- **Broadcast lifecycle (most-used proposal types)** — `token_transfer`, `blacklist`, `add_expert` (S55–S57)
 
 ```bash
 # 1) generate 9 wallets (8 agents + funder), fund the funder from your wallet
 # 2) deploy fixture DAOs via dexe_dao_build_deploy (one 50% quorum + one with validators)
 # 3) configure SWARM_DAOS_TESTNET / SWARM_TOKENS_TESTNET / SWARM_RPC_URL_TESTNET
+
 npm run swarm:preflight                # red/green table per wallet
 npm run swarm:fund -- --confirm        # broadcast top-ups from funder
 npm run swarm:run                      # full sweep, all scenarios
 npm run swarm:run -- --scenarios=S00-reset,S01-delegation-chain-3hop --dry-run
 ```
 
-Setup runbook: [`tests/swarm/README.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/tests/swarm/README.md).
-Scenario schema: [`tests/swarm/scenarios/_schema.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/tests/swarm/scenarios/_schema.md).
-Per-role agent prompts: `tests/swarm/prompts/`.
+- Setup runbook → [`tests/swarm/README.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/tests/swarm/README.md)
+- Scenario schema → [`tests/swarm/scenarios/_schema.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/tests/swarm/scenarios/_schema.md)
+- Per-role agent prompts → [`tests/swarm/prompts/`](https://github.com/edward-arinin-web-dev/dexe-mcp/tree/main/tests/swarm/prompts)
+
+---
 
 ## Contributing
 
@@ -195,6 +259,31 @@ npm run typecheck
 npm run dev          # watch mode
 ```
 
+Issues, PRs, and proposal-type requests welcome → [GitHub issues](https://github.com/edward-arinin-web-dev/dexe-mcp/issues).
+
+## Security
+
+Supply-chain hardening is enforced in CI. See [SECURITY.md](SECURITY.md) for the full policy, threat model, and how to report a vulnerability. Highlights:
+
+- **Signed release tags.** Every release tag is GPG-signed and `release.yml` runs `git verify-tag` before publishing — an unsigned or untrusted tag aborts the release. Verify any tag yourself after cloning:
+
+  ```bash
+  gpg --recv-keys <MAINTAINER_KEY_ID>   # import maintainer key once
+  git verify-tag v0.5.9                 # or the shorthand: git tag -v v0.5.9
+  ```
+
+  A `Good signature` line is the only acceptable result; `no signature found` or `No public key` means do not trust the tag.
+- **npm provenance.** Releases publish with `npm publish --provenance`; verify with `npm audit signatures` against an installed copy.
+- **Reproducible installs.** A `verify-lockfile` CI job installs strictly from the committed `package-lock.json` and fails on any drift.
+- **Continuous scanning.** CodeQL (SAST) runs on every PR and weekly; OSSF Scorecard runs weekly and on push to `main`; Dependency Review runs on every PR.
+
 ## License
 
 MIT. See [LICENSE](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/LICENSE).
+
+---
+
+<p align="center">
+  <b>The runtime for autonomous DAOs.</b><br/>
+  <sub>Built for the DeXe Protocol governance stack on BNB Chain. Not affiliated with DeXe Network — independent open-source integration.</sub>
+</p>

package/SECURITY.md

@@ -0,0 +1,96 @@
+# Security Policy
+
+## Supported Versions
+
+Only the latest published version on npm receives security updates. Pin to the latest minor (`^0.5`) in your MCP client config.
+
+## Automated security checks
+
+The repo runs four GitHub Actions security workflows continuously:
+
+- **CI** (`ci.yml`) — typecheck and build on every push to `main` and every pull request, against Node 20 and 22, plus a `verify-lockfile` integrity job. The test step (`vitest`) runs whenever test files are present on the branch; it is currently a no-op via `--passWithNoTests` (the suite lives on `governor-adapter`) and becomes an enforcing gate once those tests merge. Read-only `GITHUB_TOKEN` scope.
+- **Dependency Review** (`dependency-review.yml`) — every PR is checked against the GitHub Advisory Database. Fails the PR check if any added/updated dependency carries a `high` or `critical` CVE, or if it introduces a forbidden license (GPL/AGPL).
+- **OSSF Scorecard** (`scorecard.yml`) — weekly + on push to `main`. Audits branch protection, signed releases, pinned dependencies, token permissions, and a dozen other supply-chain checks. Results uploaded to GitHub code-scanning (SARIF) and published as a public score at `https://api.securityscorecards.dev/projects/github.com/edward-arinin-web-dev/dexe-mcp/badge`.
+- **CodeQL** (`codeql.yml`) — GitHub-native SAST with the `security-extended` query suite. Runs on every PR/main push and weekly. Scans for prototype pollution, command injection, ReDoS, unsafe deserialization, path traversal, and other CWE patterns. Findings land in the repo's Security tab.
+
+## Release provenance
+
+Every npm release from `v0.5.9` onwards is published via `.github/workflows/release.yml` with `npm publish --provenance`. The signed attestation links the tarball to the exact git commit and GitHub Actions run that produced it. Verify in three ways:
+
+- The npmjs.com page for the package shows a "Provenance" badge with the source repo and workflow run.
+- `npm view dexe-mcp dist.signatures` returns Sigstore signatures.
+- `npm audit signatures` against an installed copy fails if the registry tarball was tampered with.
+
+If you ever install a `dexe-mcp` version that lacks a provenance attestation (and is not a pre-`v0.5.9` historical release), treat it as suspect and report.
+
+## Signed release tags
+
+Every release tag is GPG-signed by the maintainer, and `release.yml` runs `git verify-tag "$GITHUB_REF_NAME"` **before** the publish step — an unsigned tag, an invalid signature, or a tag signed by an unknown key aborts the release, so a pushed tag can never publish to npm without a valid maintainer signature.
+
+To verify a tag yourself after cloning the repo:
+
+```bash
+# Import the maintainer's public key once (key id published alongside releases).
+gpg --recv-keys <MAINTAINER_KEY_ID>
+
+# Verify a specific tag — exits non-zero if unsigned or signed by an unknown key.
+git verify-tag v0.5.9
+# Equivalent shorthand:
+git tag -v v0.5.9
+```
+
+A clean `gpg: Good signature from "<maintainer>"` line is the only acceptable result. `error: ... no signature found` (unsigned) or `Can't check signature: No public key` (unknown signer) means do not trust the tag.
+
+## Reporting a Vulnerability
+
+If you find a vulnerability in `dexe-mcp` — whether in the calldata builders, the optional signer (`DEXE_PRIVATE_KEY`), IPFS upload paths, or the Hardhat bridge — please **do not** open a public GitHub issue.
+
+Email: **edward.arinin@gmail.com**
+
+Include:
+
+- A description of the issue and its impact (what an attacker can do, under what conditions).
+- A minimal reproduction: the tool call, env vars (redacted), and the resulting behavior.
+- Affected version (`dexe-mcp --version` or check `package.json`).
+- Suggested mitigation, if you have one.
+
+You should expect an acknowledgement within 72 hours. A coordinated-disclosure timeline will be agreed before any public advisory is filed.
+
+## Scope
+
+In scope:
+
+- Calldata-builder tools (`dexe_proposal_build_*`, `dexe_vote_build_*`, `dexe_dao_build_deploy`) that produce calldata that does not match the intended action.
+- Signer mode (`dexe_tx_send`, auto-broadcast in `dexe_proposal_create` / `dexe_proposal_vote_and_execute`) leaking or misusing the configured private key.
+- IPFS upload paths that exfiltrate non-public data or accept unsafe input.
+- Hardhat bridge (`dexe_compile`, `dexe_test`, etc.) executing unintended shell commands.
+- Dependency vulnerabilities reachable through `dexe-mcp`'s exposed tool surface.
+
+Out of scope:
+
+- Vulnerabilities in the on-chain DeXe Protocol contracts (report at <https://github.com/dexe-network>).
+- Issues that require the operator to set obviously unsafe env values (e.g. `DEXE_PRIVATE_KEY=<a key the attacker already controls>`).
+- General npm-registry / npm-cli / Node.js issues unrelated to this package.
+
+## Threat Model
+
+`dexe-mcp` runs **locally** alongside an MCP client (Claude Desktop, Claude Code, etc.). It does not bind a network port and does not expose itself to the public internet. The interesting attack surfaces are:
+
+1. The operator's private key in signer mode — never logged, never sent off-host, only used by `ethers.Wallet` to sign payloads the operator has already approved at the agent level.
+2. Calldata correctness — every `_build_*` tool emits a `TxPayload` the operator can decode (`dexe_decode_calldata`, `dexe_decode_proposal`) and sign-verify before broadcasting.
+3. IPFS pinning credentials — keep `PINATA_JWT` scoped to a project-specific key.
+
+If you believe any of the above is broken, please report per the process above.
+
+## Signer broadcast guards
+
+When signer mode is enabled (`DEXE_PRIVATE_KEY`), `dexe_tx_send` runs four opt-in guards before broadcasting (`src/lib/broadcastGuards.ts`). They narrow the blast radius of a compromised or runaway MCP host — the host can still *call* the tool, but cannot send to arbitrary destinations, drain arbitrary value, pay gas for reverting txs, or loop unbounded. Each is a no-op unless its env var is set; a failed guard returns `{ status: "rejected", guard, reason }` with **no gas spent**.
+
+| Guard | Env var | What it blocks |
+|-------|---------|----------------|
+| **B6** destination allowlist | `DEXE_SIGNER_ALLOWLIST` | Broadcasts to any `to` not on the comma-separated list. |
+| **B7** value cap | `DEXE_SIGNER_MAX_VALUE_WEI` | Broadcasts whose `value` (wei) exceeds the cap. |
+| **B9** auto-simulation | _(always on in signer mode)_ | Doomed txs — `eth_call` preflight aborts with the decoded revert reason before gas is spent. |
+| **B10** rate limit | `DEXE_SIGNER_MAX_BROADCASTS_PER_MIN` | More than N broadcasts in a rolling 60s window. |
+
+These are defense-in-depth, **not** a substitute for keeping the key off-host. For prod governance/treasury actions, prefer calldata mode + Safe Multisig / Ledger. See `docs/ENVIRONMENT.md` §4 for the recommended config block.

package/dist/config.d.ts

@@ -34,6 +34,15 @@ export interface DexeConfig {
     forkBlock?: number;
     /** Private key for tx signing. When set, `dexe_tx_send` can broadcast. */
     privateKey?: string;
+    /**
+     * B6 — destination allowlist for `dexe_tx_send`. Lowercased, checksummed-then-
+     * lowercased addresses. Undefined/empty = no restriction.
+     */
+    signerAllowlist?: string[];
+    /** B7 — max wei value per broadcast. Undefined = no cap. */
+    signerMaxValueWei?: bigint;
+    /** B10 — max broadcasts per rolling minute. Undefined = no limit. */
+    signerMaxBroadcastsPerMin?: number;
 }
 /**
  * Reads environment and returns a frozen config. **Fast and side-effect-free**

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IACzB,mFAAmF;IACnF,YAAY,EAAE,MAAM,CAAC;IAErB,uEAAuE;IACvE,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACzC;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,UAAU,CAAC,CA4ItD;AAcD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,WAAW,CAW9E"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IACzB,mFAAmF;IACnF,YAAY,EAAE,MAAM,CAAC;IAErB,uEAAuE;IACvE,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACzC;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,4DAA4D;IAC5D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,qEAAqE;IACrE,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,UAAU,CAAC,CAwMtD;AAcD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,WAAW,CAW9E"}

package/dist/config.js

@@ -34,6 +34,20 @@ export async function loadConfig() {
     if (rpcMainnet) {
         chains.set(56, { chainId: 56, rpcUrl: rpcMainnet });
     }
+    // Generic per-chain RPC: DEXE_RPC_URL_<chainId> (e.g. DEXE_RPC_URL_1,
+    // DEXE_RPC_URL_10). Enables chains beyond BSC — notably the external
+    // Governor DAOs, which live on Ethereum (1) and Optimism (10). The numeric
+    // suffix never collides with the named *_TESTNET / *_MAINNET vars above.
+    for (const [key, val] of Object.entries(process.env)) {
+        const m = /^DEXE_RPC_URL_(\d+)$/.exec(key);
+        if (!m)
+            continue;
+        const url = val?.trim();
+        if (!url)
+            continue;
+        const cid = Number(m[1]);
+        chains.set(cid, { chainId: cid, rpcUrl: url });
+    }
     // Legacy single-chain env (still supported)
     const legacyRpc = process.env.DEXE_RPC_URL?.trim() || undefined;
     let legacyChainId;
@@ -106,6 +120,49 @@ export async function loadConfig() {
         const addr = new Wallet(privateKey).address;
         process.stderr.write(`[dexe-mcp] signing enabled for ${addr}\n`);
     }
+    // ---- signer broadcast guard B6 (destination allowlist) -----------------
+    // Opt-in; only meaningful in signer mode. Parses to undefined when unset,
+    // leaving the default posture unchanged.
+    let signerAllowlist;
+    const allowlistRaw = process.env.DEXE_SIGNER_ALLOWLIST?.trim();
+    if (allowlistRaw) {
+        const { isAddress, getAddress } = await import("ethers");
+        const normalized = [];
+        for (const entry of allowlistRaw.split(",").map(s => s.trim()).filter(Boolean)) {
+            if (!isAddress(entry)) {
+                fatal(`DEXE_SIGNER_ALLOWLIST contains an invalid address: ${entry}`);
+            }
+            normalized.push(getAddress(entry).toLowerCase());
+        }
+        if (normalized.length > 0)
+            signerAllowlist = normalized;
+    }
+    // ---- signer broadcast guard B7 (value cap) -----------------------------
+    let signerMaxValueWei;
+    const maxValueRaw = process.env.DEXE_SIGNER_MAX_VALUE_WEI?.trim();
+    if (maxValueRaw) {
+        let parsed;
+        try {
+            parsed = BigInt(maxValueRaw);
+        }
+        catch {
+            fatal(`DEXE_SIGNER_MAX_VALUE_WEI must be a non-negative integer (wei), got: ${maxValueRaw}`);
+        }
+        if (parsed < 0n) {
+            fatal(`DEXE_SIGNER_MAX_VALUE_WEI must be a non-negative integer (wei), got: ${maxValueRaw}`);
+        }
+        signerMaxValueWei = parsed;
+    }
+    // ---- signer broadcast guard B10 (rate limit) ---------------------------
+    let signerMaxBroadcastsPerMin;
+    const maxBroadcastsRaw = process.env.DEXE_SIGNER_MAX_BROADCASTS_PER_MIN?.trim();
+    if (maxBroadcastsRaw) {
+        const n = Number(maxBroadcastsRaw);
+        if (!Number.isInteger(n) || n <= 0) {
+            fatal(`DEXE_SIGNER_MAX_BROADCASTS_PER_MIN must be a positive integer, got: ${maxBroadcastsRaw}`);
+        }
+        signerMaxBroadcastsPerMin = n;
+    }
     let forkBlock;
     if (process.env.DEXE_FORK_BLOCK) {
         const n = Number(process.env.DEXE_FORK_BLOCK);
@@ -128,6 +185,9 @@ export async function loadConfig() {
         subgraphInteractionsUrl,
         forkBlock,
         privateKey,
+        signerAllowlist,
+        signerMaxValueWei,
+        signerMaxBroadcastsPerMin,
     });
 }
 /**