feat: bridges, PMM, flash workflow, token-aggregation, and deployment docs

- CCIP/trustless bridge contracts, GRU tokens, DEX/PMM tests, reserve vault.
- Token-aggregation service routes, planner, chain config, relay env templates.
- Config snapshots and multi-chain deployment markdown updates.
- gitignore services/btc-intake/dist/ (tsc output); do not track dist.

Run forge build && forge test before deploy (large solc graph).

Made-with: Cursor

docs/deployment/DVM_DEPLOYMENT_CHECK.md

@@ -1,30 +1,41 @@
 # DVM (DODO Vending Machine) Deployment Check — Chain 138
 
-**Date:** 2026-02-20
+**Date:** 2026-04-02
 
 ## Summary
 
-**There is no official DODO DVM factory deployment on Chain 138.**
+**Chain 138 now has a self-deployed official DODO V2 DVM stack, but it is not DODO-listed.**
 
-- DODO’s official contract list ([api.dodoex.io/dodo-contract/list?version=v1,v2](https://api.dodoex.io/dodo-contract/list?version=v1,v2)) includes chains such as **1** (Ethereum), **5** (Goerli), **10** (Optimism), **56** (BSC), **133** (Syscoin), **137** (Polygon), **8453** (Base), etc.  
-- **Chain ID 138 is not in that list**, so there is no canonical DVM factory address for Chain 138 from DODO.
+- DODO’s official contract list ([api.dodoex.io/dodo-contract/list?version=v1,v2](https://api.dodoex.io/dodo-contract/list?version=v1,v2)) includes chains such as **1** (Ethereum), **5** (Goerli), **10** (Optimism), **56** (BSC), **133** (Syscoin), **137** (Polygon), **8453** (Base), etc.
+- **Chain ID 138 is still not in that list**, so there is no DODO-published canonical DVM factory address for Chain 138.
+- This repo now operates a **self-deployed official DODO V2 DVM stack** on Chain 138:
+  - **DVMFactory:** `0xc93870594C7f83A0aE076c2e30b494Efc526b68E`
+  - **DVMFactoryAdapter / DODO_VENDING_MACHINE_ADDRESS:** `0xb6D9EF3575bc48De3f011C310DC24d87bEC6087C`
+  - **DODOPMMIntegration:** `0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895`
+  - **DODOPMMProvider:** `0x3f729632E9553EBacCdE2e9b4c8F2B285b014F2e`
+  - **Stable pools (canonical corrected stack):**
+    - `cUSDT/cUSDC`: `0x9e89bAe009adf128782E19e8341996c596ac40dC`
+    - `cUSDT/USDT`: `0x866Cb44b59303d8dc5f4F9E3E7A8e8b0bf238d66`
+    - `cUSDC/USDC`: `0xc39B7D0F40838cbFb54649d327f49a6DAC964062`
 
 ## Implications
 
-- **`DODO_VENDING_MACHINE_ADDRESS`** in `.env` must point to a DVM factory **you deploy or obtain** on Chain 138; it will not be an “official” DODO-listed address.
-- Until that address is set, **PMM (run-pmm-and-pools.sh)** and **DODOPMMIntegration** cannot be used on Chain 138.
+- **`DODO_VENDING_MACHINE_ADDRESS`** in `.env` must point to a Chain 138 factory adapter **you deploy or obtain**; it is not a DODO-listed public address.
+- The canonical Chain 138 PMM path is now the **official DODO V2 DVMFactoryAdapter** above, not the earlier mock DVM path.
 
 ## Options
 
-0. **Use mock DVM (this repo)**  
+0. **Use mock DVM (this repo, fallback only)**  
    - A minimal `MockDVMFactory` (and `MockDVMPool`) is provided so PMM can run on Chain 138 without official DODO. Deploy with:
    - `forge script script/dex/DeployMockDVMFactory.s.sol:DeployMockDVMFactory --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY" --legacy`
    - Set `DODO_VENDING_MACHINE_ADDRESS` in `.env` to the deployed address, then run `scripts/deployment/run-pmm-and-pools.sh`. Pools created are mocks (no real AMM); swap views return stubs.
+   - **Do not treat this as canonical anymore** unless you are intentionally testing without the official DVM stack.
 
 1. **Deploy official DODO DVM on Chain 138 (this repo)**  
    - Submodule **lib/dodo-contractV2** (DODOEX/contractV2) is used to deploy the official DVM stack via Truffle. Our **DVMFactoryAdapter** wraps `createDODOVendingMachine` as `createDVM` so `DODOPMMIntegration` works unchanged.
-   - **Blocker:** DODO contractV2 mixes Solidity 0.6.9 (DVM, Factory) and 0.8.16 (DODOGasSavingPool, SmartRoute). Truffle compiles the whole repo with one solc version, so `truffle compile` fails. Until DODO adds multi-compiler support or we vendor only the DVM 0.6.9 tree, use the **mock DVM** (option 0) or deploy from a DODO fork that compiles.
-   - **One-shot (when Truffle compiles):** `scripts/deployment/deploy-official-dvm-chain138.sh`  
+   - The repo deployment helper now runs the vendored DODO tree in a **DVM-only compile mode** by temporarily hiding unrelated Solidity `0.8.x` contracts during `truffle compile` / `truffle migrate`, then restoring them on exit. That allows the official DVM `0.6.9` stack to compile without forking the upstream repo.
+   - **One-shot:** `scripts/deployment/deploy-official-dvm-chain138.sh`  
+     - To verify compile before broadcast: `scripts/deployment/deploy-official-dvm-chain138.sh --compile-only`
      - Requires `lib/dodo-contractV2` deps: `cd lib/dodo-contractV2 && npm install` (if npm hits a registry/cert error, use `npm install --registry https://registry.npmjs.org/ --no-package-lock`).
    - **Manual:**  
      1) In `lib/dodo-contractV2`: set `privKey` and `RPC_URL_138` (e.g. from parent `.env`), then `npx truffle migrate -f 1 --to 1 --network chain138` and `npx truffle migrate -f 9 --to 9 --network chain138`.  
@@ -32,6 +43,8 @@
         `forge script script/dex/DeployDVMFactoryAdapter.s.sol:DeployDVMFactoryAdapter --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY" --legacy`  
      3) Set `DODO_VENDING_MACHINE_ADDRESS` in `.env` to the **DVMFactoryAdapter** address (not the DVMFactory address).  
    - Then run `scripts/deployment/run-pmm-and-pools.sh` (you may need to re-deploy DODOPMMIntegration if it was previously deployed with the mock DVM).
+   - **Current live Chain 138 result:** the repo has already deployed this path and currently uses the addresses listed in the Summary section above.
+   - **Stable-pair calibration note:** for equal-reserve stable pairs on the official DODO V2 DVM stack, the current canonical Chain 138 pools use `i = 1e18`, `k = 0`, `lpFeeRate = 10 bps`, `isOpenTWAP = false`. Earlier `k = 0.5e18` pools were removed because they priced above parity.
 
 2. **Deploy DVM factory yourself from DODO source (outside this repo)**  
    - DODO’s contracts are open source: [DODOEX GitHub](https://github.com/DODOEX) (contractV2).