d-bis/proxmox
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Sync workspace: config, docs, scripts, CI, operator rules, and submodule pointers.

Browse Source 
- Update dbis_core, cross-chain-pmm-lps, explorer-monorepo, metamask-integration, pr-workspace/chains
- Omit embedded publish git dirs and empty placeholders from index

Made-with: Cursor
This commit is contained in:
defiQUG
2026-04-12 06:12:20 -07:00
parent 6fb6bd3993
commit dbd517b279
2935 changed files with 327972 additions and 5533 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/03-deployment/ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK.md
View File

@@ -1,6 +1,6 @@
# Add Liquidity to PMM Pools (Chain 138) — Runbook
> Historical note (2026-03-26): this runbook originated during the earlier three-pool PMM phase. Current canonical Chain 138 PMM addresses are `DODOPMMIntegration=0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d` and `DODOPMMProvider=0x5CAe6Ce155b7f08D3a956F5Dc82fC9945f29B381`.
> Historical note (2026-04-02): this runbook originated during the earlier three-pool PMM phase. Current canonical Chain 138 PMM addresses are `DODOPMMIntegration=0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895` and `DODOPMMProvider=0x3f729632E9553EBacCdE2e9b4c8F2B285b014F2e`.
**Purpose:** Add base/quote liquidity to the three DODO PMM pools on Chain 138 (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC).
@@ -38,9 +38,9 @@ Add or set in `smom-dbis-138/.env`:
```bash
# Pool addresses (from PRE_DEPLOYMENT_CHECKLIST / create-all-pmm-pools-chain138.sh)
POOL_CUSDTCUSDC=0xff8d3b8fDF7B112759F076B69f4271D4209C0849
POOL_CUSDTUSDT=0x6fc60DEDc92a2047062294488539992710b99D71
POOL_CUSDCUSDC=0x9f74Be42725f2Aa072a9E0CdCce0E7203C510263
POOL_CUSDTCUSDC=0x9e89bAe009adf128782E19e8341996c596ac40dC
POOL_CUSDTUSDT=0x866Cb44b59303d8dc5f4F9E3E7A8e8b0bf238d66
POOL_CUSDCUSDC=0xc39B7D0F40838cbFb54649d327f49a6DAC964062
# Amounts in base units (6 decimals): 1M tokens = 1000000000000
ADD_LIQUIDITY_BASE_AMOUNT=1000000000000

131
docs/03-deployment/ALL_NETWORK_CONTRACT_VERIFICATION_AND_PUBLICATION_RUNBOOK.md Normal file
View File

@@ -0,0 +1,131 @@
# All-Network Contract Verification And Publication Runbook
**Last updated:** 2026-04-10
**Scope:** Chain 138, Ethereum mainnet, and every cross-chain deployment currently tracked in the repo inventories.
## Purpose
This runbook defines the repo-standard meaning of **verified and published** for deployed contracts on all tracked networks.
Use it together with:
- [CONTRACT_VERIFICATION_AND_PUBLICATION_MATRIX_ALL_NETWORKS](../11-references/CONTRACT_VERIFICATION_AND_PUBLICATION_MATRIX_ALL_NETWORKS.md)
- [PUBLICATION_PACK_EXPLORER_STATUS](../11-references/PUBLICATION_PACK_EXPLORER_STATUS.md)
- [PUBLICATION_ACTIONABLE_BACKLOG](../11-references/PUBLICATION_ACTIONABLE_BACKLOG.md)
- `reports/status/contract_verification_publish_matrix.json`
## Definition of done
A deployment is only considered closed when all of the following are true:
1. The contract address is present in the correct repo inventory.
2. The deployed runtime exists on the target chain.
3. Source code or equivalent explorer verification is completed on the target chain explorer.
4. The address is published in every required repo-facing surface:
- `config/smart-contracts-master.json` when canonical
- `cross-chain-pmm-lps/config/deployment-status.json` when part of PMM/cW rollout
- token list or mapping docs when user-facing
- deployment/status docs where operators rely on them
## Chain 138
### Canonical verification
Run from a host that can reach Blockscout and the Chain 138 RPC:
```bash
bash scripts/verify/run-contract-verification-with-proxy.sh
bash scripts/verify/check-contracts-on-chain-138.sh
```
### DODO v3 / pilot verification
```bash
bash scripts/verify/verify-dodo-v3-chain138-blockscout.sh
```
### Publication
After Blockscout verification completes:
1. Confirm the address set in `config/smart-contracts-master.json`
2. Confirm the route/token/pool surfaces that depend on it
3. Regenerate the all-network matrix:
```bash
node scripts/verify/generate-contract-verification-publish-matrix.mjs
```
## Other EVM chains
The repo currently tracks cross-chain deployments and inventory on:
- Ethereum mainnet (`1`)
- Optimism (`10`)
- Cronos (`25`)
- BSC (`56`)
- Gnosis (`100`)
- Polygon (`137`)
- Wemix (`1111`)
- Arbitrum (`42161`)
- Celo (`42220`)
- Avalanche (`43114`)
- Base (`8453`)
### Required steps
1. Open the chain explorer shown in the generated matrix.
2. Verify source or deployment metadata for repo-owned contracts.
3. If the address is an external anchor/reference venue, mark it as reference-only in operator notes rather than pretending the repo owns verification.
4. Regenerate the matrix and update the chain-specific runbook or token mapping if anything changed.
### Ethereum mainnet historical-source example
`DODOPMMIntegration (Mainnet)` at `0xa9F284eD010f4F7d7F8F201742b49b9f58e29b84` was closed on 2026-04-11 by verifying against the historical `smom-dbis-138` source snapshot that actually matches the deployed bytecode, not current HEAD. Keep the provenance note in [ETHEREUM_MAINNET_DODOPMMINTEGRATION_VERIFICATION.md](ETHEREUM_MAINNET_DODOPMMINTEGRATION_VERIFICATION.md) with the matching commit, constructor arguments, and create transaction. Explorer-side public name tags remain a manual Etherscan account workflow after source verification passes.
### Requested publication packs
For the current execution pass, the requested packs are:
- Ethereum mainnet
- Optimism
- BSC
- Polygon
- Base
Use the generated artifacts to distinguish what is actually closable from the repo:
```bash
ETHERSCAN_API_KEY=... node scripts/verify/check-publication-pack-explorer-status.mjs
node scripts/verify/generate-publication-actionable-backlog.mjs
```
Closure rule for these five packs:
1. **Auto-submittable backlog empty** in `PUBLICATION_ACTIONABLE_BACKLOG.md` means the repo-owned automatic submission pass is complete.
2. Remaining `manual-or-external` rows are not honest candidates for automatic closure until source provenance or explorer ownership is established.
3. `inventory-only` and `reference-only` rows must stay aligned in repo inventories, but should not be misrepresented as repo-owned verification work.
## ALL Mainnet / non-EVM adjacent inventories
Not every tracked address lands on a conventional EVM verification path.
- `651940` (ALL Mainnet) still needs publication and documentation closure even where explorer verification is manual or non-standard.
- Non-EVM reference inventories should still be published consistently in the repo, even when source verification uses a different platform.
## Canonical inventory refresh
Regenerate the repo-wide matrix after any deployment or publication sweep:
```bash
node scripts/verify/generate-contract-verification-publish-matrix.mjs
```
This writes:
- `reports/status/contract_verification_publish_matrix.json`
- `docs/11-references/CONTRACT_VERIFICATION_AND_PUBLICATION_MATRIX_ALL_NETWORKS.md`
## Honest limits
This runbook improves closure and removes ambiguity, but it does not magically invent missing constructor arguments, compiler settings, or third-party explorer API credentials. Where those are missing, the matrix should remain **pending** until the source bundle is assembled and the publication step is actually completed.

106
docs/03-deployment/AUSDT_CAUSDT_CWAUSDT_BRIDGE_CHECKLIST.md Normal file
View File

@@ -0,0 +1,106 @@
# AUSDT (ALL Mainnet) -> cWAUSDT -> cAUSDT — Practical Checklist
**Status:** `cAUSDT` is live on Chain 138, BSC / Polygon / Avalanche / Celo `cWAUSDT` mirrors are deployed and bridge-wired, and the GRU transport lane is now active in repo config. Public edge PMM pools remain a separate rollout.
**Primary source token:** [ALL_MAINNET_TOKEN_ADDRESSES.md](../11-references/ALL_MAINNET_TOKEN_ADDRESSES.md)
---
## 1. Pin the ALL Mainnet origin token (done in repo)
The source-of-truth object is now `config/token-mapping-multichain.json -> alltraAusdtOrigin`.
| Chain | Role | Address |
|-------|------|---------|
| 651940 | Native ALL Mainnet `AUSDT` origin | `0x015B1897Ed5279930bC2Be46F661894d219292A6` |
| 56 | Existing `cWAUSDT` bridge mirror | `0xe1a51Bc037a79AB36767561B147eb41780124934` |
| 43114 | Existing `cWAUSDT` bridge mirror | `0xff3084410A732231472Ee9f93F5855dA89CC5254` |
| 137 | Polygon `cWAUSDT` bridge mirror | `0xf12e262F85107df26741726b074606CaFa24AAe7` |
| 42220 | Celo `cWAUSDT` bridge mirror | `0xC158b6cD3A3088C52F797D41f5Aa02825361629e` |
**Important distinction:** unlike the USDW path, this corridor originates on **ALL Mainnet**. Public-chain `cWAUSDT` is treated as a **bridge mirror / transport token**, not as a native-public collateral wrapper.
---
## 2. Reuse existing cWAUSDT where available (done in repo)
| Chain | `cWAUSDT` status | Use for GRU transport? |
|-------|------------------|------------------------|
| BSC 56 | Already deployed | **Yes** — reuse for the planned `cAUSDT` corridor |
| Avalanche 43114 | Already deployed | **Yes** — reuse for the planned `cAUSDT` corridor |
| Polygon 137 | Deployed | **Yes** — live `cWAUSDT` mirror for the AUSDT corridor |
| Celo 42220 | Deployed | **Yes** — live `cWAUSDT` mirror for the AUSDT corridor |
Do **not** redeploy BSC/Avalanche `cWAUSDT` unless you are intentionally splitting bridge supply from GRU transport supply.
---
## 3. Repo mapping now in place
The following are now wired:
- `config/token-mapping-multichain.json`
- `cToCwSymbolMapping.cAUSDT = cWAUSDT`
- `alltraAusdtOrigin` source object
- `Compliant_AUSDT_cW` route rows for:
- `138 -> 56`
- `138 -> 137`
- `138 -> 43114`
- `138 -> 42220`
- `smom-dbis-138/services/token-aggregation/src/config/canonical-tokens.ts`
- env-gated `cAUSDT` on Chain 138
- public-edge `cWAUSDT` surfacing on BSC, Polygon, Avalanche, and Celo via fallback addresses
---
## 4. Live deployment completed
1. Deployed **`cAUSDT`** on Chain 138 at `0x5fdDF65733e3d590463F68f93Cf16E8c04081271`.
2. Registered `cAUSDT` in the Universal Asset Registry on Chain 138.
3. Deployed Polygon **`cWAUSDT`** at `0xf12e262F85107df26741726b074606CaFa24AAe7`.
4. Set:
- `CAUSDT_ADDRESS_138`
- `CWAUSDT_ADDRESS_137`
- `alltraAusdtOrigin.chains.137.cwAusdtBridgeMirror`
- `Compliant_AUSDT_cW.addressTo` for `138 -> 137`
5. Granted bridge mint/burn roles on BSC, Polygon, Avalanche, and Celo `cWAUSDT`.
6. Activated the bridge-live GRU transport config for `cAUSDT -> cWAUSDT` on BSC, Polygon, Avalanche, and Celo.
---
## 5. Activation gate
The lane is now active in `config/gru-transport-active.json` because all of the following are true:
1. `cAUSDT` is actually deployed on Chain 138.
2. Each intended destination `cWAUSDT` token is deployed and recorded.
3. Mint/burn roles are wired to the bridge surfaces.
4. Outstanding limits / reserve checks are defined for the new corridor.
5. `bash scripts/validation/validate-config-files.sh` passes after the address updates.
6. Public edge PMM pools remain optional and are still inactive until separately deployed.
---
## 6. Env surface
The templates now expose:
- `AUSDT_ADDRESS_651940`
- `CAUSDT_ADDRESS_138`
- `CWAUSDT_ADDRESS_56`
- `CWAUSDT_ADDRESS_137`
- `CWAUSDT_ADDRESS_43114`
- `CWAUSDT_ADDRESS_42220`
These are documented in:
- `.env.master.example`
- `smom-dbis-138/env.additions.example`
- `smom-dbis-138/services/token-aggregation/.env.example`
---
## Related
- `docs/04-configuration/C_TO_CW_MAPPER_MAPPING.md`
- `docs/11-references/TOKEN_CATEGORIES_CANONICAL.md`
- `cross-chain-pmm-lps/config/deployment-status.json`

151
docs/03-deployment/CHAIN138_EOA_NONCE_RECOVERY_AND_CANCELLATION.md Normal file
View File

@@ -0,0 +1,151 @@
# Chain 138 EOA Nonce Recovery And Cancellation
This note captures the two operator paths for a Chain 138 EOA whose transactions are stuck in Besu txpool state.
Context from the live investigation:
- EOA: `0xB2dEA0e264ddfFf91057A3415112e57A1a5Eac14`
- Public Blockscout and public RPC did not know about the originally tested hash `0x14d7259e6e75bbcd8979dc9e19f3001b0f328bbcdb730937f8cc2e6a52f26da6`
- VMID `2103` did show pending transactions from that EOA
- VMID `2201` only partially saw those pending transactions
- The account had enough balance and peers were healthy
- The main blocker was nonce continuity, not balance or gas
## What We Found
- On-chain account state stayed low:
- `latest = 0x1`
- `pending = 0x1`
- But VMID `2103` was holding future pending transactions from the EOA at:
- nonce `0x3`
- nonce `0x4`
- nonce `0x7`
- nonce `0x8`
- That means at least these nonce gaps were missing:
- `1`
- `2`
- `5`
- `6`
- Because of that, later transactions could not execute.
- There was also mempool divergence:
- `2103` had more local pending transactions than `2201`
- some attempts were only visible on `2103`
## Important Interpretation
This looked less like "persistent on-chain nonces are broken" and more like:
1. the EOA had a broken pending sequence
2. later transactions were stuck behind missing nonce gaps
3. some pending transactions persisted only in a local node view
That creates two different recovery strategies.
## Option 1: Complete The Queued Attempts
Use this when the owner still wants the old deployment or transaction attempts to go through.
Script:
- [`recover-chain138-eoa-nonce-gaps.sh`](/home/intlc/projects/proxmox/scripts/deployment/recover-chain138-eoa-nonce-gaps.sh)
What it does:
1. derives the owner address from the private key
2. reads `latest` nonce plus `txpool_besuPendingTransactions`
3. detects nonce gaps between the mined nonce and the highest pending nonce
4. in `--apply` mode, sends `0`-value self-transfers to fill those missing nonces
Dry-run example:
```bash
PRIVATE_KEY=0x... \
bash /home/intlc/projects/proxmox/scripts/deployment/recover-chain138-eoa-nonce-gaps.sh \
--rpc http://192.168.11.217:8545
```
Apply example:
```bash
PRIVATE_KEY=0x... \
bash /home/intlc/projects/proxmox/scripts/deployment/recover-chain138-eoa-nonce-gaps.sh \
--rpc http://192.168.11.217:8545 \
--apply
```
Expected behavior for this specific EOA:
- it should detect the missing nonce chain before the future pending transactions
- after the gaps are filled, the later queued attempts may start executing
Risk:
- if the owner no longer wants the old transactions to execute, this is the wrong tool
- filling the gaps may allow older deployment attempts to mine immediately
## Option 2: Cancel The Whole Queued Nonce Range
Use this when the owner does **not** want the old attempts to execute and wants to invalidate the full queued sequence.
Script:
- [`cancel-chain138-eoa-nonce-range.sh`](/home/intlc/projects/proxmox/scripts/deployment/cancel-chain138-eoa-nonce-range.sh)
What it does:
1. derives the owner address from the private key
2. reads owner pending txs from `txpool_besuPendingTransactions`
3. plans a cancel range from `--from-nonce` to `--to-nonce`
4. in `--apply` mode, sends `0`-value self-transfers at each nonce in that range
Dry-run example:
```bash
PRIVATE_KEY=0x... \
bash /home/intlc/projects/proxmox/scripts/deployment/cancel-chain138-eoa-nonce-range.sh \
--rpc http://192.168.11.217:8545 \
--from-nonce 1 \
--to-nonce 8
```
Apply example:
```bash
PRIVATE_KEY=0x... \
bash /home/intlc/projects/proxmox/scripts/deployment/cancel-chain138-eoa-nonce-range.sh \
--rpc http://192.168.11.217:8545 \
--from-nonce 1 \
--to-nonce 8 \
--apply
```
Why this is often safer:
- it cancels the queued window intentionally
- it avoids accidentally reviving old deployment attempts
- it gives the owner a clean path to restart from a known nonce state later
## Recommended Decision Rule
Use the nonce-gap recovery script when:
- the owner still wants the existing pending attempts to complete
- the queued deployment attempts are still intended
Use the cancel-range script when:
- the owner is unsure what those old attempts will do
- the owner does not want old queued deployments to suddenly execute
- the goal is to reset and start fresh
## Practical Summary
For the investigated EOA, the safer default is:
1. run the cancel-range script in dry-run mode
2. confirm the nonce range to neutralize
3. if correct, run with `--apply`
4. verify the queue is cleared
5. only then submit fresh intended transactions
If the owner explicitly wants the old attempts to continue, use the gap-filler instead.

193
docs/03-deployment/CHAIN138_ETH_WETH_ORACLE_PEG_AND_LIQUIDITY_PLAN.md Normal file
View File

@@ -0,0 +1,193 @@
# Chain 138 ETH / WETH Oracle, Peg, and Liquidity Plan
**Last Updated:** 2026-04-07
**Purpose:** Add the missing ETH-priced market-data, peg, and liquidity work needed so `ETH`, `WETH9`, and `WETH10` are first-class execution and pricing surfaces in the Chain 138 and GRU v2 rollout.
---
## 1. Why this work is required
- `ETH` has an economic value on Chain 138 and should be treated as a visible market reference asset, not only as transport collateral.
- `WETH9` and `WETH10` should share the same real-time value reference as `ETH` unless an explicit wrapper premium/discount policy is documented.
- The current repo already uses an `ETH/USD` oracle surface for routing and D3MM, but the completion program still needs:
- explicit real-time feed policy
- explicit peg-control policy
- explicit liquidity depth targets
- explicit pool inventory for `ETH` / `WETH`
This plan makes those requirements concrete without claiming they are already fully live.
---
## 2. Completion target
For completion, Chain 138 should truthfully support all of the following:
1. `ETH`, `WETH9`, and `WETH10` all have current price visibility from approved oracle sources.
2. `WETH9` and `WETH10` are monitored against `ETH` with a very tight wrapper-peg threshold.
3. The routing layer can surface `ETH` / `WETH` pricing and liquidity publicly.
4. The canonical Chain 138 pool inventory includes enough `ETH` / `WETH` depth to make the market feed meaningful rather than cosmetic.
5. The peg-management and automation layer can detect and respond to wrapper divergence before the market degrades.
---
## 3. Ordered execution plan
### Phase 1. Freeze the oracle truth surface
1. Freeze the approved Chain 138 price-feed inventory for:
- `ETH/USD`
- `WETH9/USD`
- `WETH10/USD`
2. Document whether `WETH9` and `WETH10` both inherit the canonical `ETH/USD` reference or whether they have wrapper-specific derived feeds.
3. Confirm the live addresses and metadata surfaces in:
- `config/smart-contracts-master.json`
- public status docs
- verifier scripts
4. Remove any ambiguity between production feeds and bootstrap/mock feeds.
### Phase 2. Define the wrapper-peg policy
5. Add an explicit peg policy for:
- `ETH <-> WETH9`
- `ETH <-> WETH10`
- `WETH9 <-> WETH10`
6. Treat `0.00001` as the maximum tolerated wrapper deviation target unless governance intentionally changes it.
7. Record the policy in docs as:
- target deviation
- warning threshold
- intervention threshold
- cooldown / circuit-break behavior
8. Hook the wrapper-peg policy into the existing peg-management surfaces where appropriate:
- `StablecoinPegManager`
- `CommodityPegManager`
- keeper/oracle automation
### Phase 3. Make the market feed public and operator-visible
9. Ensure the public routing/status surfaces show live `ETH`, `WETH9`, and `WETH10` pricing inputs.
10. Ensure the explorer or token-aggregation publication layer can show:
- active oracle source
- latest reference price
- venue-backed market price
- divergence between oracle and venue
11. Add a dedicated verifier or extend an existing verifier to report:
- oracle freshness
- wrapper parity
- pool depth
- route visibility
### Phase 4. Complete the Chain 138 liquidity base
12. Add the missing Chain 138 pool inventory required for meaningful `ETH` / `WETH` price discovery.
13. Prioritize these pool families first:
- `cUSDT / WETH`
- `cUSDC / WETH`
- `USDT / WETH`
- `USDC / WETH`
14. Then extend into the broader GRU mesh:
- `c* / WETH` for the 12-token compliant set
- optional `c* / ETH` presentation surfaces where the execution token is still `WETH`
15. Keep pool creation aligned with the full-mesh plan in `PMM_FULL_MESH_AND_PUBLIC_SINGLE_SIDED_PLAN.md`.
### Phase 5. Fund for depth, not just existence
16. Define minimum launch depth for the first `ETH` / `WETH` anchor pools.
17. Fund both sides deeply enough that the public quote path is a real market signal.
18. Publish the target inventory bands for:
- base inventory
- quote inventory
- rebalance thresholds
19. Add operator checks so low-depth pools do not get reported as healthy pricing venues.
### Phase 6. Promote into D3MM and router policy
20. Keep the current `WETH10 <-> USDT` D3MM lane healthy and verified.
21. Extend D3MM or the canonical venue policy so `ETH` / `WETH` pricing is not dependent on a single pilot lane.
22. Decide which of these become canonical execution venues:
- D3MM
- DODO PMM
- Uniswap v3
- Balancer
- Curve 3
- 1inch as an overlay only
23. Update route-matrix and planner visibility once those venues are approved.
### Phase 7. Automation and peg defense
24. Add or extend automation to monitor:
- oracle freshness
- `ETH` vs `WETH9`
- `ETH` vs `WETH10`
- `WETH9` vs `WETH10`
- market depth and spread
25. Trigger alerts when the wrapper deviation exceeds the `0.00001` target band.
26. Define the operator response ladder:
- add liquidity
- rebalance inventory
- pause route exposure
- pause venue exposure if needed
### Phase 8. Public proof and documentation
27. Update the canonical status docs once oracle + peg + liquidity are actually live.
28. Keep the following docs aligned with the live state:
- `docs/11-references/PMM_DEX_ROUTING_STATUS.md`
- `docs/11-references/GRU_V2_PUBLIC_PROTOCOL_DEPLOYMENT_STATUS.md`
- `docs/00-meta/GRU_V2_D3MM_EDGE_AND_PROTOCOL_ASSURANCE_TASKS.md`
29. Do not call the ETH/WETH market surface complete until:
- oracle feeds are live
- pools exist
- pools are funded
- route visibility is live
- peg checks are green
---
## 4. Priority pool list
The first required Chain 138 price-anchor pools should be treated as a completion gate:
- `cUSDT / WETH`
- `cUSDC / WETH`
- `USDT / WETH`
- `USDC / WETH`
- `WETH9 / WETH10` visibility or parity-monitor surface
Then expand to:
- `cEURC / WETH`
- `cEURT / WETH`
- `cGBPC / WETH`
- `cGBPT / WETH`
- `cAUDC / WETH`
- `cJPYC / WETH`
- `cCHFC / WETH`
- `cCADC / WETH`
- `cXAUC / WETH`
- `cXAUT / WETH`
---
## 5. Verifier expectations
Completion should be tested with a verifier surface that proves:
- bytecode exists for the oracle and venue contracts
- the live feed is not a bootstrap/mock feed
- `WETH9` and `WETH10` resolve to the approved ETH value policy
- the anchor pools are funded
- the planner and public routing layer expose the `ETH` / `WETH` lanes
- the peg stays inside the configured `0.00001` target band
---
## 6. Boundary
This plan does not mean that Chain 138 already has:
- fully real-time public ETH/WETH market publication
- fully funded `ETH` / `WETH` anchor depth across all required pools
- fully automated wrapper-peg defense at the `0.00001` target
It means the repo now has an explicit ordered completion path for that work.

156
docs/03-deployment/CHAIN138_UNISWAP_V3_UPSTREAM_NATIVE_RUNBOOK.md Normal file
View File

@@ -0,0 +1,156 @@
# Chain 138 Uniswap V3 Upstream-Native Deployment & Cutover Runbook
**Purpose:** Record the upstream-native Uniswap v3 deployment on Chain 138, the corrected fee-500 canonical pool seeding, and the public planner cutover from the earlier pilot-compatible venue.
**Status:** Deployed, correctly re-seeded, and cut over on Chain 138.
**Current live state:** Chain 138 now routes the canonical public `WETH -> USDT` lane through the upstream-native Uniswap v3 router `0xde9cD8ee2811E6E64a41D5F68Be315d33995975E`, QuoterV2 `0x6abbB1CEb2468e748a03A00CD6aA9BFE893AFa1f`, and canonical fee-500 pool `0xa893add35aEfe6A6d858EB01828bE4592f12C9F5`. The older pilot router `0xD164D9cCfAcf5D9F91698f296aE0cd245D964384` remains deployed only as a superseded fallback surface.
---
## 1. Current baseline
- **Live today:** `EnhancedSwapRouterV2` plus the canonical upstream-native `Uniswap_v3` lane and the funded pilot-compatible `Balancer`, `Curve_3`, and `1inch` venues is public and healthy.
- **Cutover is already complete:** keep `UNISWAP_V3_ROUTER` and `UNISWAP_QUOTER_ADDRESS` pointed at the native router/quoter unless you are deliberately rolling back.
- **Verification for current live state:** `bash scripts/verify/check-chain138-pilot-dex-venues.sh`
---
## 2. Local source trees
Use the official upstream repos:
- `v3-core` at `/home/intlc/projects/uniswap-v3-core`
- `v3-periphery` at `/home/intlc/projects/uniswap-v3-periphery`
Bootstrap or refresh them with:
```bash
bash scripts/deployment/prepare-chain138-uniswap-v3-upstream-worktree.sh
```
---
## 3. Preflight
Run the readiness check before and after deployment work:
```bash
bash scripts/verify/check-chain138-uniswap-v3-upstream-native-readiness.sh
```
This verifies:
1. The upstream core/periphery worktrees exist locally.
2. The target RPC really points at Chain 138.
3. The deployer has native gas and baseline token balances.
4. Any deployed native Uniswap v3 addresses actually have bytecode.
5. The native QuoterV2 returns non-zero quotes for both seeded canonical pools.
6. The public planner’s current baseline lane still resolves through the live pilot path until cutover.
---
## 4. Env surface
Canonical upstream-native env surface:
```bash
CHAIN138_UNISWAP_V3_NATIVE_CORE_REPO=/home/intlc/projects/uniswap-v3-core
CHAIN138_UNISWAP_V3_NATIVE_PERIPHERY_REPO=/home/intlc/projects/uniswap-v3-periphery
CHAIN138_UNISWAP_V3_NATIVE_FACTORY=0x2f7219276e3ce367dB9ec74C1196a8ecEe67841C
CHAIN138_UNISWAP_V3_NATIVE_NFT_DESCRIPTOR_LIBRARY=0x6F5fdE32DD2aC66B27e296EC9D6F4E79A3dE2947
CHAIN138_UNISWAP_V3_NATIVE_TOKEN_DESCRIPTOR=0xca66DCAC4633555033F6fDDBE4234B6913c7ff51
CHAIN138_UNISWAP_V3_NATIVE_POSITION_MANAGER=0x31b68BE5af4Df565Ce261dfe53D529005D947B48
CHAIN138_UNISWAP_V3_NATIVE_SWAP_ROUTER=0xde9cD8ee2811E6E64a41D5F68Be315d33995975E
CHAIN138_UNISWAP_V3_NATIVE_QUOTER_V2=0x6abbB1CEb2468e748a03A00CD6aA9BFE893AFa1f
CHAIN138_UNISWAP_V3_NATIVE_WETH_USDT_POOL=0xa893add35aEfe6A6d858EB01828bE4592f12C9F5
CHAIN138_UNISWAP_V3_NATIVE_WETH_USDC_POOL=0xEC745bfb6b3cd32f102d594E5F432d8d85B19391
CHAIN138_UNISWAP_V3_NATIVE_FEE_TIER=500
CHAIN138_NATIVE_GAS_PRICE=1000
CHAIN138_NATIVE_DEPLOY_GAS_LIMIT=12000000
CHAIN138_NATIVE_POOL_TX_GAS_LIMIT=12000000
```
Live publication vars now point at the native public path:
```bash
UNISWAP_V3_ROUTER=0xde9cD8ee2811E6E64a41D5F68Be315d33995975E
UNISWAP_QUOTER_ADDRESS=0x6abbB1CEb2468e748a03A00CD6aA9BFE893AFa1f
UNISWAP_V3_WETH_USDT_POOL=0xa893add35aEfe6A6d858EB01828bE4592f12C9F5
UNISWAP_V3_WETH_USDC_POOL=0xEC745bfb6b3cd32f102d594E5F432d8d85B19391
UNISWAP_V3_WETH_USDT_FEE=500
UNISWAP_V3_WETH_USDC_FEE=500
```
---
## 5. Deployment order
### Phase A — upstream-native core/periphery contracts
The upstream-native Uniswap v3 stack deployed on Chain 138 as:
1. `UniswapV3Factory` `0x2f7219276e3ce367dB9ec74C1196a8ecEe67841C`
2. `NFTDescriptor` `0x6F5fdE32DD2aC66B27e296EC9D6F4E79A3dE2947`
3. `NonfungibleTokenPositionDescriptor` `0xca66DCAC4633555033F6fDDBE4234B6913c7ff51`
4. `NonfungiblePositionManager` `0x31b68BE5af4Df565Ce261dfe53D529005D947B48`
5. `SwapRouter` `0xde9cD8ee2811E6E64a41D5F68Be315d33995975E`
6. `QuoterV2` `0x6abbB1CEb2468e748a03A00CD6aA9BFE893AFa1f`
**Chain 138 note:** wrapped native asset `WETH` already exists at `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`. Do not confuse this with the separate `CCIPWETH9Bridge` / `CCIPWETH10Bridge` transport addresses.
### Phase B — canonical pools
Created and seeded:
1. `WETH / USDT` at `0xa893add35aEfe6A6d858EB01828bE4592f12C9F5` with `~50 WETH` and `105,830 USDT`
2. `WETH / USDC` at `0xEC745bfb6b3cd32f102d594E5F432d8d85B19391` with `~50 WETH` and `105,830 USDC`
Fee tier: `500`. Native `QuoterV2` returns non-zero quotes for both canonical pools (`0.1 WETH -> 211.132116 USDT/USDC` at the time of cutover).
**Historical note:** the earlier fee-3000 bootstrap pools `0x97eB...` and `0xfc62...` are preserved only as deployment artifacts from the first native seeding pass, which used incorrect decimal/price initialization. Do not treat them as canonical after the corrected fee-500 cutover.
### Phase C — publication cutover
Completed:
1. `CHAIN138_UNISWAP_V3_NATIVE_*` vars now point at the native addresses above.
2. The public `UNISWAP_V3_ROUTER` / `UNISWAP_QUOTER_ADDRESS` surface now points at the native router/quoter.
3. Token-aggregation on CT 5000 was redeployed and restarted on 2026-04-03.
4. The public `/token-aggregation/api/v2` planner now resolves the canonical `WETH -> USDT` lane through target `0xde9...` with fee `500`.
---
## 6. Funding checklist
Minimum practical funding requirements:
- native ETH for deployment gas
- `WETH` for both native pools
- `USDT` for `WETH / USDT`
- `USDC` for `WETH / USDC`
**This blocker is cleared:** deployer official `USDC` was funded and the native `WETH / USDC` pool is now seeded.
---
## 7. Cutover criteria
Keep the native cutover healthy by asserting all of the following:
1. Upstream-native factory/router/quoter/position manager all have bytecode on Chain 138.
2. Both native pools exist and are seeded with non-zero reserves.
3. Native `QuoterV2` returns non-zero quotes for `WETH -> USDT` and `WETH -> USDC`.
4. Public planner can resolve `WETH -> USDT` and `USDT -> WETH` using the native target.
5. Internal execution plans emit router-v2 calldata against the native router target.
6. `bash scripts/verify/check-chain138-pilot-dex-venues.sh` passes after any funding, publication, or inventory change.
---
## 8. Related files
- [DEX_AND_CROSS_CHAIN_CONTRACTS_NEEDED.md](../11-references/DEX_AND_CROSS_CHAIN_CONTRACTS_NEEDED.md)
- [PMM_DEX_ROUTING_STATUS.md](../11-references/PMM_DEX_ROUTING_STATUS.md)
- [CONTRACT_DEPLOYMENT_RUNBOOK.md](CONTRACT_DEPLOYMENT_RUNBOOK.md)
- [CONTRACT_ADDRESSES_REFERENCE.md](../11-references/CONTRACT_ADDRESSES_REFERENCE.md)
- [check-chain138-pilot-dex-venues.sh](/home/intlc/projects/proxmox/scripts/verify/check-chain138-pilot-dex-venues.sh)
- [check-chain138-uniswap-v3-upstream-native-readiness.sh](/home/intlc/projects/proxmox/scripts/verify/check-chain138-uniswap-v3-upstream-native-readiness.sh)

2
docs/03-deployment/CHAIN138_XAU_POOL_STATUS_AND_PUBLIC_CREATION_PATH.md
View File

@@ -3,6 +3,8 @@
**Date:** 2026-03-26
**Scope:** Verify live private and public XAU pools on Chain 138 and record the exact creation/funding path used.
> Historical note (2026-04-02): the public XAU pools documented here remain live on the older PMM phase. The canonical April 2026 stable stack is `DODOPMMIntegration=0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895` and `DODOPMMProvider=0x3f729632E9553EBacCdE2e9b4c8F2B285b014F2e`; do not overwrite the XAU-specific addresses below unless you are explicitly migrating those pools. The older `0x5BDc...` integration documented here should not be used by the explorer fallback, token-aggregation, or stable-pool routing.
## Current live state
### Private XAU pools: live on-chain now

34
docs/03-deployment/CHAIN138_XDC_ZERO_BRIDGE_RUNBOOK.md
View File

@@ -1,6 +1,6 @@
# Chain 138 + XDC Zero Endpoint (XDC Network mainnet RPC + optional testnet)
**Last updated:** 2026-03-31
**Last updated:** 2026-04-01
**Purpose:** Register **DBIS Chain 138** as an additional peer in the [XDC-Zero](https://github.com/XinFinOrg/XDC-Zero) pattern while keeping **stock XDC-CSC + XDC-Relayer** semantics: reuse `IFullCheckpoint.getRoots` and a **dedicated second** relayer/oracle process for the **parent ↔ 138** pair. **Do not** repoint or tear down an existing XDC **subnet ↔ parent** relayer.
**XDC mainnet:** Use **XDC Network** JSON-RPC — default `https://rpc.xinfin.network` (chain id **0x32 / 50**). This is **not** Ethereum mainnet RPC (`ETHEREUM_MAINNET_RPC` is unrelated to the XDC-Relayer parent URL).
@@ -17,10 +17,12 @@
| Profile | Set `PARENTNET_URL` / `XDC_PARENTNET_URL` to | Notes |
|---------|-----------------------------------------------|--------|
| **XDC mainnet (default)** | `https://rpc.xinfin.network` | Official XDC Network HTTP JSON-RPC. Production: fund relayer with **XDC** for CSC txs. Alternate enterprise mirror OK if XinFin-approved. |
| **Apothem (testnet)** | `https://rpc.apothem.network` | Lower risk for spikes; not mainnet. |
| **Apothem (testnet)** | `https://rpc.apothem.network` | Chain id **51** (`0x33`). Lower risk for spikes; not mainnet. |
| **Devnet shortcuts** | `devnet` / `testnet` strings | XDC-Zero `cicd` maps these to Apothem-style URLs — confirm before production. |
**Chain 138:** Prefer LAN deploy RPC (`RPC_URL_138` from project dotenv, e.g. Core Besu). For monitoring from outside LAN, use a controlled public RPC (e.g. `rpc-http-pub.d-bis.org`) if policy allows.
**XDC reference (operators):** Native gas token is **XDC** (not ETH). [Chainlist — XDC mainnet (50)](https://chainid.network/chain/50/) lists additional RPC mirrors (`erpc.xinfin.network`, `rpc1.xinfin.network`, community providers). Explorers: [xdcscan.com](https://xdcscan.com), [xdcscan.io](https://xdcscan.io). Network hub: [xinfin.org](https://xinfin.org).
**Chain 138:** Split the RPC roles clearly. Use Core Besu at `http://192.168.11.211:8545` for **operator-only** deploy and proof-sensitive work (`RPC_URL_138`). Use the public HTTPS FQDN `https://rpc-http-pub.d-bis.org` for **external services and long-running relayers** (`SUBNET_URL` in XDC-Relayer). Do not point external services at the Core node.
**Other public mainnets (Ethereum, BSC, etc.):** They are **not** part of stock XDC-Relayer. This runbook does not mix them into one relayer process. If you later add **separate** Zero-style pairs (e.g. 138 ↔ Ethereum), treat each as **another** two-URL relayer/CSC stack and document it independently. Repo dotenv already supports `ETHEREUM_MAINNET_RPC` etc. for **verification** and CCIP workflows — use [`xdc-zero-chain138-preflight.sh`](../../scripts/verify/xdc-zero-chain138-preflight.sh) optional checks.
@@ -50,7 +52,7 @@
then the same command without `--dry-run` (backs up the file). Or pass the file explicitly: `bash scripts/xdc-zero/merge-endpointconfig-chain138.sh /path/to/endpointconfig.json --dry-run`. Replace placeholder addresses in [`config/xdc-zero/`](../../config/xdc-zero/) (or edit merged JSON) after CSC/Endpoint deploy. **Do not** run `endpointandregisterchain.js` unmodified after manual merge — it overwrites JSON for two networks only.
5. **Register chains:** Owner calls `registerChain` on parent and on 138.
6. **Apps:** Deploy SUA/RUA (or Subswap) on both sides; fill `applications`; run `registerapplications.js` (or multisig) on **both** chains.
7. **Operate second relayer:** Env from [`config/xdc-zero/xdc-zero-chain138-pair.example.env`](../../config/xdc-zero/xdc-zero-chain138-pair.example.env); point `CHECKPOINT_CONTRACT` / `REVERSE_CHECKPOINT_CONTRACT` at the **new** CSCs only.
7. **Operate second relayer:** Start from [`config/xdc-zero/xdc-zero-chain138-pair.example.env`](../../config/xdc-zero/xdc-zero-chain138-pair.example.env) for operator values and chain selection. If running under systemd, materialize those values into [`config/xdc-zero/xdc-zero-relayer-138-pair.example.defaults`](../../config/xdc-zero/xdc-zero-relayer-138-pair.example.defaults) for `/etc/default/xdc-zero-relayer-138-pair`; use [`config/xdc-zero/xdc-relayer.dotenv.example`](../../config/xdc-zero/xdc-relayer.dotenv.example) only for a clone-local relayer `.env`. For the relayer itself, set `SUBNET_URL=https://rpc-http-pub.d-bis.org`; reserve `RPC_URL_138=http://192.168.11.211:8545` for operator-only deploy/proof tasks. Point `CHECKPOINT_CONTRACT` / `REVERSE_CHECKPOINT_CONTRACT` at the **new** CSCs only.
8. **E2E:** Send/receive one packet with real proofs; monitor `getRoots` lag.
---
@@ -70,7 +72,29 @@ If **XDC subnet** apps must talk to **138** directly (not via parent), you need
---
## 6. References
## 6. Completion checklist (repo automation)
| Step | Command / artifact |
|------|---------------------|
| Full sequence (printed) | `bash scripts/xdc-zero/run-xdc-zero-138-operator-sequence.sh` |
| RPC | `bash scripts/verify/xdc-zero-chain138-preflight.sh` (also prints deployer balances when `PRIVATE_KEY` is available; parent deploy/register stays blocked until the deployer has native XDC on XDC mainnet) |
| Config JSON | `bash scripts/validation/validate-xdc-zero-config.sh` (also in `validate-config-files.sh`) |
| Build relayer | `bash scripts/xdc-zero/clone-and-build-xdc-relayer.sh` → `node dist/server.js` + Redis + [`xdc-relayer.dotenv.example`](../../config/xdc-zero/xdc-relayer.dotenv.example) for clone-local `.env`, or [`xdc-zero-relayer-138-pair.example.defaults`](../../config/xdc-zero/xdc-zero-relayer-138-pair.example.defaults) for `/etc/default` under systemd |
| Deploy Endpoint on 138 | `XDC_ZERO_REPO=~/projects/XDC-Zero bash scripts/xdc-zero/deploy-endpoint-chain138.sh` (`--dry-run` first). If Hardhat hangs, rerun with `--manual`; see [CHAIN138_XDC_ZERO_DEPLOYMENT_TROUBLESHOOTING.md](CHAIN138_XDC_ZERO_DEPLOYMENT_TROUBLESHOOTING.md). Record the landed stack in `config/xdc-zero/deployed/endpoint-chain138.env`. |
| Spike CSC (lab only) | `bash scripts/xdc-zero/cast-deploy-simplecsc-chain138.sh` |
| Addresses → fragments | `bash scripts/xdc-zero/set-fragment-addresses.sh` → writes `config/xdc-zero/deployed/*.json`. If only the Chain 138 side is live so far, use `ENDPOINT_ON_138=... bash scripts/xdc-zero/set-fragment-addresses.sh --chain138-only` to stage the 138 endpoint while leaving parent values as zero placeholders. |
| Merge `endpointconfig.json` | `XDC_ZERO_CHAIN138_FRAG=.../deployed/endpointconfig.fragment.chain138.json` `XDC_ZERO_REG_FRAG=.../deployed/xdcparentnet-register-chain138.fragment.json` `bash scripts/xdc-zero/merge-endpointconfig-chain138.sh --dry-run …` then without `--dry-run` |
| `registerChain` | `XDC_ZERO_ENDPOINT_DIR=.../endpoint bash scripts/xdc-zero/run-registerchain-both.sh` |
| `approveApplication` | `… bash scripts/xdc-zero/run-registerapplications-both.sh` |
| systemd | [`config/systemd/xdc-zero-relayer-138-pair.example.service`](../../config/systemd/xdc-zero-relayer-138-pair.example.service) — `ExecStart=/usr/bin/node dist/server.js`, `WorkingDirectory=` your relayer clone (e.g. `/opt/xdc-relayer`) |
**Troubleshooting:** [CHAIN138_XDC_ZERO_DEPLOYMENT_TROUBLESHOOTING.md](CHAIN138_XDC_ZERO_DEPLOYMENT_TROUBLESHOOTING.md) (pending tx / replacement underpriced, SimpleCsc vs production CSC).
Hardhat `chain138` and `network.config.json` → `chain138` live in your **XDC-Zero** clone (`endpoint/`).
---
## 7. References
- XDC-Zero: `endpoint/README.md`, `cicd/README.md` (clone locally).
- CCIP / Chain 138 (parallel path): [docs/07-ccip/](07-ccip/), [docs/11-references/CCIP_138_DESTINATION_RECEIVER_BY_CHAIN_AND_TOKEN.md](../11-references/CCIP_138_DESTINATION_RECEIVER_BY_CHAIN_AND_TOKEN.md).

44
docs/03-deployment/CHAIN138_XDC_ZERO_DEPLOYMENT_TROUBLESHOOTING.md Normal file
View File

@@ -0,0 +1,44 @@
# XDC Zero + Chain 138 — deployment troubleshooting
**Last updated:** 2026-04-01
## 1. `Replacement transaction underpriced` (Chain 138 / Besu)
A prior deploy (e.g. Hardhat `yarn hardhat run …`) may have left a **pending** transaction at the deployer nonce. The next `cast send` reuses that nonce and Besu rejects a “cheap” replacement.
**Fix (operator):**
1. Identify the deployer: `cast wallet address --private-key "$PRIVATE_KEY"`.
2. Inspect the latest block / explorer / `eth_getBlockByNumber` for stuck txs from that address.
3. Either **wait** for the pending tx to mine, or submit a **replacement** with the **same nonce** and **strictly higher** effective gas price (per your Besu/miner policy), or coordinate a **nonce reset** on a test chain only.
Until the mempool clears, prefer **no new deploys** from the same key.
## 2. Hardhat appears to hang after “Compiled successfully”
Some Besu JSON-RPC setups are slow to return receipts for large contract creation batches. Options:
- Increase `timeout` on the `chain138` network in `endpoint/hardhat.config.js` (already raised to 600s in this workspace’s XDC-Zero patch).
- Use the repo wrapper with the manual fallback: `XDC_ZERO_REPO=~/projects/XDC-Zero bash scripts/xdc-zero/deploy-endpoint-chain138.sh --manual`
- This deploys directly from the compiled artifacts with explicit gas settings and library linking.
- If overlapping retries already consumed nonces, reuse the landed library addresses via `ETHEREUM_TRIE_DB_ADDRESS=...` and `MERKLE_PATRICIA_ADDRESS=...` before rerunning the manual script.
- Deploy with **Foundry `cast send --create`** using bytecode from `artifacts/contracts/.../*.json` (one contract at a time) if you want to bypass Node entirely.
- Use `scripts/xdc-zero/cast-deploy-simplecsc-chain138.sh` for **SimpleCsc** only (spike / lab).
When overlapping retries leave multiple library instances, record the final coherent stack in `config/xdc-zero/deployed/endpoint-chain138.env` and use those values for the next parent-side / merge steps.
## 3. SimpleCsc vs production CSC
`SimpleCsc` in XDC-Zero tests is **not** a production checkpoint: `setRoots` is unpermissioned. For mainnet or institutional use, deploy **stock XDC-CSC** (or equivalent) and wire the relayer/oracle as in XinFin subnet docs.
## 4. XDC-Relayer prerequisites
Upstream expects **Redis** and a full `.env` (see `config/xdc-zero/xdc-relayer.dotenv.example` for a clone-local relayer `.env`, or `config/xdc-zero/xdc-zero-relayer-138-pair.example.defaults` for `/etc/default` under systemd, plus the [XDC-Relayer README](https://github.com/XinFinOrg/XDC-Relayer)). After `npm run build`, production start is:
`node dist/server.js` from the relayer repo root (same as `npm run start`).
## 5. Parent-side deploys fail immediately or cannot start
The Chain 138 deployer key can be well funded on 138 and still be unusable on **XDC mainnet** if it holds `0 XDC`.
Before you attempt the parent Endpoint / CSC deploy, confirm the deployer has **XDC** (native gas on chain id **50**) on `https://rpc.xinfin.network` or another [listed mainnet RPC](https://chainid.network/chain/50/). Check the address on [xdcscan.com](https://xdcscan.com) or [xdcscan.io](https://xdcscan.io). If not funded, stop after the Chain 138 deploy, record the 138 addresses, fund the parent deployer, and resume with the parent-side runbook steps later.

118
docs/03-deployment/CONTRACT_DEPLOYMENT_RUNBOOK.md
View File

@@ -1,6 +1,6 @@
# Contract Deployment Runbook
**Last Updated:** 2026-02-12
**Last Updated:** 2026-04-03
**Full deployment order:** For the canonical sequence (prerequisites → core → PMM/pools → provider → optional → cW* → verification) and remaining recommendations, see [DEPLOYMENT_ORDER_OF_OPERATIONS.md](DEPLOYMENT_ORDER_OF_OPERATIONS.md).
@@ -138,6 +138,120 @@ forge create contracts/mirror/TransactionMirror.sol:TransactionMirror \
Or run the helper script (from repo root, **from a host on LAN** that can reach `RPC_URL_138` e.g. 192.168.11.211:8545): `./scripts/deployment/deploy-transaction-mirror-chain138.sh`. The script exports `ETH_RPC_URL` so Forge uses the correct RPC and, on success, updates or appends `TRANSACTION_MIRROR_ADDRESS` in `smom-dbis-138/.env`.
## Cross-chain flash borrow / bridge / repay helpers (Chain 138)
For the cross-chain flash path, the repo now has a dedicated deploy script for:
- `UniversalCCIPFlashBridgeAdapter`
- `CrossChainFlashRepayReceiver`
- `CrossChainFlashVaultCreditReceiver`
**Foundry deploy script:** `smom-dbis-138/script/deploy/DeployCrossChainFlashInfrastructure.s.sol`
**Operator wrapper (recommended):**
```bash
source scripts/lib/load-project-env.sh
./scripts/deployment/deploy-cross-chain-flash-infra-chain138.sh --dry-run
./scripts/deployment/deploy-cross-chain-flash-infra-chain138.sh
```
**Required env:**
- `PRIVATE_KEY`
- `RPC_URL_138`
- `UNIVERSAL_CCIP_BRIDGE` or `FLASH_UNIVERSAL_CCIP_BRIDGE`
- `CCIP_ROUTER` or `CCIP_ROUTER_ADDRESS` or `CCIP_ROUTER_CHAIN138` or `FLASH_CCIP_ROUTER`
**Optional env overrides:**
- `FLASH_REPAY_RECEIVER_ROUTER`
- `FLASH_VAULT_CREDIT_ROUTER`
The deploy script logs and exports:
- `CROSS_CHAIN_FLASH_BRIDGE_ADAPTER`
- `CROSS_CHAIN_FLASH_REPAY_RECEIVER`
- `CROSS_CHAIN_FLASH_VAULT_CREDIT_RECEIVER`
**Live deployment (2026-04-03):**
- `CROSS_CHAIN_FLASH_BRIDGE_ADAPTER=0xBe9e0B2d4cF6A3b2994d6f2f0904D2B165eB8ffC`
- `CROSS_CHAIN_FLASH_REPAY_RECEIVER=0xD084b68cB4B1ef2cBA09CF99FB1B6552fd9b4859`
- `CROSS_CHAIN_FLASH_VAULT_CREDIT_RECEIVER=0x89F7a1fcbBe104BeE96Da4b4b6b7d3AF85f7E661`
**Blockscout verification (2026-04-03):**
- `UniversalCCIPFlashBridgeAdapter` verified at `2026-04-03T03:15:53Z`
- `CrossChainFlashRepayReceiver` verified at `2026-04-03T03:11:16Z`
- `CrossChainFlashVaultCreditReceiver` verified at `2026-04-03T03:15:34Z`
Post-deploy verification:
```bash
bash scripts/verify/check-cross-chain-flash-infra-chain138.sh
```
Design reminder:
- `CrossChainFlashBorrower` still handles the same-tx ERC-3156 borrow/repay path on the borrow chain.
- `CrossChainFlashRepayReceiver` is the destination-side CCIP delivery leg.
- `CrossChainFlashVaultCreditReceiver` is the source-side or same-chain CCIP vault refill leg after async settlement.
## DODO v3 / D3MM pilot verification (Chain 138 private venue)
The private Chain 138 DODO v3 pilot is tracked separately from the public canonical DODO V2 stable-routing stack.
**Current pilot addresses:**
- `D3Oracle=0xD7459aEa8bB53C83a1e90262777D730539A326F0`
- `D3Vault=0x42b6867260Fb9eE6d09B7E0233A1fAD65D0133D1`
- `D3MMFactory=0x78470C7d2925B6738544E2DD4FE7c07CcA21AC31`
- `D3Proxy=0xc9a11abB7C63d88546Be24D58a6d95e3762cB843`
- `WETH10 / ETH-USD oracle source=0x99b3511a2d315a497c8112c1fdd8d508d4b1e506`
- `USDT/USD managed feed=0x7c2Cb2667f0f97f4004aae04B67d94A085E6f0f1`
- `USDC/USD managed feed=0xf072Ac13D45e6c83296ca18F3E04185B747DD6aa`
- `cUSDT/USD managed feed=0x7c96E66F4a0713e327F9e73Cf2721f13DB29036C`
- `cUSDC/USD managed feed=0x291694095232CA80077125F64f6f73076e7910C1`
- Canonical `WETH10` pilot pool `D3MM=0x6550A3a59070061a262a893A1D6F3F490afFDBDA`
**Health check:**
```bash
bash scripts/verify/check-dodo-v3-chain138.sh
```
**Blockscout source-verification workflow:**
```bash
bash scripts/verify/verify-dodo-v3-chain138-blockscout.sh
```
This verifies:
- the canonical D3MM pool returns `D3MM 1.0.0`
- `D3Vault` still recognizes the canonical pool
- `D3Oracle` has a non-zero, whitelisted `WETH10` source and it no longer points at the bootstrap `WETH10` mock
- `D3Oracle` no longer points the stable assets at the older bootstrap mock feeds
- `querySellTokens(WETH10 -> USDT, 0.1)` returns a healthy non-zero quote
- `D3Oracle`, `D3Vault`, `DODOApprove`, and `DODOApproveProxy` are source-verified on Blockscout
- `D3MMFactory` and `D3Proxy` verification submissions have been sent through the saved standard-input path; Blockscout currently returns bytecode-only metadata for those two addresses rather than the full source-verification metadata
**Current posture:** the DODO v3 pilot oracle stack is now promoted onto the live Chain 138 oracle surfaces. Planner-v2 capability, generated route-matrix visibility, public `/token-aggregation/api/v2` publication, and `EnhancedSwapRouterV2` execution are now in place for the canonical `WETH10 <-> USDT` pilot lane. The public canonical stable execution stack for Chain 138 remains the DODO V2 DVM-backed PMM set, while DODO v3 stays a private pilot venue with a live execution path.
**Live router-v2 execution stack (2026-04-03):**
- `ENHANCED_SWAP_ROUTER_V2_ADDRESS=0xF1c93F54A5C2fc0d7766Ccb0Ad8f157DFB4C99Ce`
- `INTENT_BRIDGE_COORDINATOR_V2_ADDRESS=0x7D0022B7e8360172fd9C0bB6778113b7Ea3674E7`
- `DODO_ROUTE_EXECUTOR_ADAPTER=0x88495B3dccEA93b0633390fDE71992683121Fa62`
- `DODO_V3_ROUTE_EXECUTOR_ADAPTER=0x9Cb97adD29c52e3B81989BcA2E33D46074B530eF`
- `UNISWAP_V3_ROUTE_EXECUTOR_ADAPTER=0x960D6db4E78705f82995690548556fb2266308EA`
- `BALANCER_ROUTE_EXECUTOR_ADAPTER=0x4E1B71B69188Ab45021c797039b4887a4924157A`
- `CURVE_ROUTE_EXECUTOR_ADAPTER=0x5f0E07071c41ACcD2A1b1032D3bd49b323b9ADE6`
- `ONEINCH_ROUTE_EXECUTOR_ADAPTER=0x8168083d29b3293F215392A49D16e7FeF4a02600`
**Proof swap (2026-04-03):**
- approval tx: `0xac36fc7c1f8b50a847101276c33404bfa6e4a53ddfc13f7296fbddedd87a5277`
- router-v2 execution tx: `0x14cd60a226dbab0c96765fff23171569e5a2fc0e35bded03f92668951ced4b57`
- result: `100 USDT -> 0.047130507214977987 WETH10`
## AlltraAdapter — setBridgeFee after deploy
After deploying or using AlltraAdapter (138 ↔ ALL Mainnet 651940), set the bridge fee to match ALL Mainnet fee structure.
@@ -195,7 +309,7 @@ This helper loads `smom-dbis-138/.env`, verifies the minimum required env (`PRIV
- `cUSDC ↔ cXAUC`
- `cEURT ↔ cXAUC`
If provider env vars like `DODOEX_ROUTER`, `DODO_PMM_PROVIDER_ADDRESS`, `UNISWAP_V3_ROUTER`, `BALANCER_VAULT`, `CURVE_3POOL`, or `ONEINCH_ROUTER` are unset, the deploy script uses placeholders and disables those providers after deployment. This keeps the Chain 138 deployment honest: token-to-token DODO pairs are registered immediately, while `swapToStablecoin()` still requires real `WETH -> stable` routes before it is operational.
If provider env vars like `DODOEX_ROUTER`, `DODO_PMM_PROVIDER_ADDRESS`, `UNISWAP_V3_ROUTER`, `BALANCER_VAULT`, `CURVE_3POOL`, or `ONEINCH_ROUTER` are unset, the deploy path now falls back to the live Chain 138 pilot-compatible venue addresses for `Uniswap_v3`, `Balancer`, `Curve_3`, and `1inch`. This keeps the Chain 138 deployment honest: the venues are funded and router-v2 wired on-chain, but they remain explicitly documented as pilot-compatible surfaces rather than upstream canonical protocol deployments.
For current Chain 138, prefer `DODO_PMM_PROVIDER_ADDRESS` when the deployed `DODOPMMProvider` is available. The router now supports that provider as its DODO backend on Chain 138. If neither `DODO_PMM_PROVIDER_ADDRESS` nor `DODOEX_ROUTER` is set, the router can still deploy and register the live pair map, but the DODO provider will be disabled and no DODO execution path will remain enabled.

84
docs/03-deployment/CUSDW_CUSDC_V2_HUB_POOL_RUNBOOK.md Normal file
View File

@@ -0,0 +1,84 @@
# Chain 138 cUSDW / cUSDC V2 Hub Pool Runbook
**Status:** Planned execution path
**Purpose:** Create and fund a Chain 138 DODO PMM hub pool for repo-native `cUSDW` against `cUSDC V2`, then surface the resulting inventory through token-aggregation and downstream edge-pool planning.
## Assumptions
- `cUSDW` is the Chain 138 hub-side GRU-aligned D-WIN USD representation.
- `cUSDC V2` is the preferred quote leg for x402 / permit-capable cutover work, even though current live PMM liquidity is still primarily on V1 `cUSDC`.
- `cWUSDW` edge rollout is currently evidenced in this repo for:
- BSC: `0xC2FA05F12a75Ac84ea778AF9D6935cA807275E55`
- Avalanche: `0xcfdCe5E660FC2C8052BDfa7aEa1865DD753411Ae`
## Known deployed addresses
| Symbol | Chain | Address | Decimals |
|--------|-------|---------|----------|
| `cUSDW` | 138 | `0xcA6BFa614935f1AB71c9aB106bAA6FBB6057095e` | `6` |
| `cUSDC_V2` | 138 | `0x219522c60e83dEe01FC5b0329d6fA8fD84b9D13d` | `6` |
| `cWUSDW` | 56 | `0xC2FA05F12a75Ac84ea778AF9D6935cA807275E55` | `6` |
| `cWUSDW` | 43114 | `0xcfdCe5E660FC2C8052BDfa7aEa1865DD753411Ae` | `6` |
## Required env
Add these to `smom-dbis-138/.env` or export before running the scripts:
```bash
DODO_DVM_FACTORY=0xc93870594C7f83A0aE076c2e30b494Efc526b68E
DODO_VENDING_MACHINE_ADDRESS=0xb6D9EF3575bc48De3f011C310DC24d87bEC6087C
DODO_PMM_INTEGRATION=0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895
CUSDW_ADDRESS_138=0xcA6BFa614935f1AB71c9aB106bAA6FBB6057095e
CUSDC_V2_ADDRESS_138=0x219522c60e83dEe01FC5b0329d6fA8fD84b9D13d
# Optional pool parameters
DODO_LP_FEE_BPS=3
DODO_INITIAL_PRICE_1E18=1000000000000000000
DODO_K_FACTOR_1E18=500000000000000000
DODO_ENABLE_TWAP=true
```
For liquidity funding:
```bash
POOL_CUSDWCUSDCV2=0x...
ADD_LIQUIDITY_CUSDWCUSDCV2_BASE=1000000000000
ADD_LIQUIDITY_CUSDWCUSDCV2_QUOTE=1000000000000
```
Both tokens use `6` decimals, so `1000000000000` means `1,000,000` full tokens.
## Create the pool
```bash
cd smom-dbis-138
forge script script/dex/CreateCUSDWCUSDCV2Pool.s.sol:CreateCUSDWCUSDCV2Pool \
--rpc-url "$RPC_URL_138" \
--broadcast
```
Then record the resulting pool address in `POOL_CUSDWCUSDCV2`.
The current canonical Chain 138 PMM stack is the **official DODO V2 DVM-backed** deployment above, not the earlier mock-backed integration.
## Add liquidity
```bash
cd smom-dbis-138
forge script script/dex/AddLiquidityCUSDWCUSDCV2PoolChain138.s.sol:AddLiquidityCUSDWCUSDCV2PoolChain138 \
--rpc-url "$RPC_URL_138" \
--broadcast
```
## Follow-on alignment
1. Token aggregation:
Set `CUSDW_ADDRESS_138`, `CWUSDW_ADDRESS_56`, and `CWUSDW_ADDRESS_43114` (or legacy aliases) where the token-aggregation service runs so `/api/v1/report/token-list` and `/api/v1/report/canonical` surface the inventory.
2. Edge-pool planning:
Use `cross-chain-pmm-lps/config/pool-matrix.json` for `cWUSDW/USDT` on BSC and `cWUSDW/USDC` on Avalanche as the first concrete edge follow-ons for this repo.
3. Mapping discipline:
Keep D-WIN `USDW` and `cUSDW` distinct in listings and explorer labels. `USDW` is the ISO-4217 W-token family; `cUSDW` / `cWUSDW` are the PMM and transport surfaces.
**CMC-listed USD DWIN** on BSC/Polygon (native ERC-20, post-swap addresses) vs Cronos ISO-4217W: see **`docs/03-deployment/USD_DWIN_CUSDW_CWUSDW_BRIDGE_CHECKLIST.md`** and **`config/token-mapping-multichain.json`** (`dwinUsdWinPublic`).

81
docs/03-deployment/CXAUC_CXAUT_CWAXAUC_CWAXAUT_ALLTRA_BRIDGE_CHECKLIST.md Normal file
View File

@@ -0,0 +1,81 @@
# cXAUC / cXAUT -> cWAXAUC / cWAXAUT -> cAXAUC / cAXAUT (ALL Mainnet) Checklist
**Purpose:** Define the operator-ready activation path for the ALL Mainnet inbound gold corridor from Chain 138.
**Canonical flow**
1. **Chain 138 canonical gold:** `cXAUC` / `cXAUT`
2. **Source-leg wrapped transport semantics:** `cWXAUC` / `cWXAUT`
3. **ALL Mainnet bridge-minted wrapped assets:** `cWAXAUC` / `cWAXAUT`
4. **ALL Mainnet native-unwrapped landing assets:** `cAXAUC` / `cAXAUT`
This is an intentional **651940 naming exception**. Generic public-chain `cWXAUC` / `cWXAUT` naming still applies elsewhere.
## Current repo status
- **Canonical Chain 138 gold assets live:** `cXAUC` and `cXAUT`
- **ALL Mainnet destination naming defined:** yes
- **ALL Mainnet destination contracts deployed:** not yet
- **Transport active in `gru-transport-active.json`:** no
## Source of truth
- Mapper + placeholders: [`config/token-mapping-multichain.json`](../../config/token-mapping-multichain.json)
- Naming standard: [`../04-configuration/ISO4217_COMPLIANT_TOKEN_MATRIX.md`](../04-configuration/ISO4217_COMPLIANT_TOKEN_MATRIX.md)
- c* -> cW* mapping notes: [`../04-configuration/C_TO_CW_MAPPER_MAPPING.md`](../04-configuration/C_TO_CW_MAPPER_MAPPING.md)
- Canonical token categories: [`../11-references/TOKEN_CATEGORIES_CANONICAL.md`](../11-references/TOKEN_CATEGORIES_CANONICAL.md)
## Required operator steps
1. **Deploy ALL Mainnet wrapped gold tokens**
- Deploy `cWAXAUC`
- Deploy `cWAXAUT`
2. **Deploy ALL Mainnet native-unwrapped gold tokens**
- Deploy `cAXAUC`
- Deploy `cAXAUT`
3. **Deploy or configure unwrap vault / bridge handler on ALL Mainnet**
- `cWAXAUC -> cAXAUC`
- `cWAXAUT -> cAXAUT`
4. **Wire bridge roles**
- Grant bridge mint/burn authority on `cWAXAUC`
- Grant bridge mint/burn authority on `cWAXAUT`
- Grant unwrap authority to the vault/handler that materializes `cAXAUC` / `cAXAUT`
5. **Fill repo env/config placeholders**
- `.env` / `.env.master.example`
- `CAXAUC_ADDRESS_651940`
- `CAXAUT_ADDRESS_651940`
- `CWAXAUC_ADDRESS_651940`
- `CWAXAUT_ADDRESS_651940`
- `config/token-mapping-multichain.json`
- `alltraXauDestination.chains.651940.*`
- `Compliant_XAUC_cW.addressTo`
- `Compliant_XAUT_cW.addressTo`
- `AXAUC_Compliant.addressFrom`
- `AXAUT_Compliant.addressFrom`
6. **Optional reporting exposure**
- Token aggregation will surface these automatically once the `*_ADDRESS_651940` env vars are set:
- `cAXAUC`
- `cAXAUT`
- `cWAXAUC`
- `cWAXAUT`
## Activation gate
Do **not** activate this lane in `config/gru-transport-active.json` until all of the following are true:
- `cWAXAUC` and `cWAXAUT` are deployed on `651940`
- `cAXAUC` and `cAXAUT` are deployed on `651940`
- unwrap path is tested end to end
- bridge mint/burn roles are wired
- repo placeholders are replaced with live addresses
- transport/redeemability policy is signed off
## Notes
- This checklist defines the **gold** exception only for **ALL Mainnet (651940)**.
- It does **not** rename generic `cWXAUC` / `cWXAUT` on ordinary public chains.

149
docs/03-deployment/DBIS_HYPERLEDGER_PRODUCT_INTEGRATION_CHECKLIST.md Normal file
View File

@@ -0,0 +1,149 @@
# DBIS Hyperledger Product Integration Checklist
**Last updated:** 2026-04-05
**Purpose:** Concrete closure checklist for the Hyperledger products that already exist in the DBIS Proxmox ecosystem. This is narrower than the RTGS-wide matrix: it answers one question per product, "what exact work remains before we can call this fully configured and integrated?"
## Current reality
| Product | Live runtime today | Ecosystem role today | Fully integrated? |
|---------|--------------------|----------------------|-------------------|
| Cacti | `5200` healthy gateway, `5201/5202` healthy public surfaces | Besu-facing interoperability sidecar plus public Alltra/HYBX Cacti surfaces | No |
| FireFly | `6200` healthy minimal local API; `6201` retired / standby | Workflow/orchestration candidate | No |
| Fabric | `6000` restored sample network on `mychannel`; `6001/6002` placeholders | Permissioned DLT sidecar candidate | No |
| Indy | `6400` healthy four-node local pool; `6401/6402` placeholders | Identity-ledger candidate | No |
| Aries | `6500` healthy ACA-Py agent | Identity-agent candidate | No |
| AnonCreds | Active indirectly through ACA-Py `askar-anoncreds` | Credential model candidate | No |
| Ursa | No separately managed runtime | Indirect crypto dependency only | No |
| Caliper | `6600` healthy workspace and Besu binding | Benchmark harness | No |
## Operator verification anchors
- Runtime truth: [DBIS_HYPERLEDGER_RUNTIME_STATUS.md](DBIS_HYPERLEDGER_RUNTIME_STATUS.md)
- Canonical production readiness: [DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md](DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md)
- Identity scope decision: [DBIS_HYPERLEDGER_IDENTITY_STACK_DECISION.md](DBIS_HYPERLEDGER_IDENTITY_STACK_DECISION.md)
- Multi-chain contract/app scope: [smom-dbis-138/MULTI_CHAIN_DEPLOYMENT_COMPLETE.md](../../smom-dbis-138/MULTI_CHAIN_DEPLOYMENT_COMPLETE.md)
## Product checklists
### Cacti
Current proof:
- `5200` returns a healthy Cacti API.
- `5201` and `5202` serve the public Alltra/HYBX Cacti surfaces and local `:4000` APIs.
Required to call fully integrated:
- [ ] Freeze whether Cacti is in scope for the first production RTGS slice.
- [ ] Deploy and validate the canonical `CactiAdapter` contract path.
- [ ] Freeze the cross-ledger contract: what transaction/event shape Cacti must observe and what downstream action it must trigger.
- [ ] Validate one real DBIS cross-ledger path end to end, not just a healthcheck.
- [ ] Archive the evidence path and rollback/retry behavior for operator use.
Helpful commands:
```bash
bash scripts/maintenance/ensure-cacti-web-via-ssh.sh
curl -fsS http://127.0.0.1:4000/api/v1/api-server/healthcheck
```
### FireFly
Current proof:
- `6200` returns `HTTP 200` on `/api/v1/status`.
- Postgres and IPFS are present behind the local FireFly footprint.
Required to call fully integrated:
- [ ] Decide whether FireFly is mandatory for the first production slice or only an optional orchestration sidecar.
- [ ] Define the canonical event/correlation model across FireFly, sidecars, OMNL, and Chain 138.
- [ ] Validate one real multiparty workflow that proves FireFly is doing useful production work.
- [ ] Decide whether `6201` must be rebuilt as a real secondary or remain explicitly retired.
- [ ] Add failover/HA evidence if FireFly stays in scope.
Helpful commands:
```bash
bash scripts/maintenance/ensure-firefly-primary-via-ssh.sh
curl -fsS http://127.0.0.1:5000/api/v1/status
```
### Fabric
Current proof:
- `6000` now runs the restored `fabric-samples` test network.
- `peer channel getinfo -c mychannel` succeeds again.
- `6001` and `6002` remain placeholders only.
Required to call fully integrated:
- [ ] Decide whether the sample network on `6000` is only a validation harness or the base of a real DBIS Fabric role.
- [ ] Deploy and validate the intended chaincode, not just the upstream sample network.
- [ ] Run or deploy the Fabric event listener in `smom-dbis-138/services/fabric-bridge/`.
- [ ] Prove one canonical Fabric-to-Besu or Fabric-backed business flow end to end.
- [ ] Freeze the production peer/orderer/CA topology if Fabric remains in scope.
Helpful commands:
```bash
bash scripts/maintenance/ensure-fabric-sample-network-via-ssh.sh
```
### Indy
Current proof:
- `6400` runs the local validator pool and binds all expected node/client ports.
- `6401` and `6402` remain placeholders only.
Required to call fully integrated:
- [ ] Decide whether Indy is a required production identity ledger or only an optional capability.
- [ ] Freeze the genesis, governance, and validator-role model if Indy remains in scope.
- [ ] Validate one real issuer / holder / verifier flow against the live pool.
- [ ] Connect the live pool explicitly to the chosen Aries/AnonCreds production path.
### Aries
Current proof:
- `6500` runs a healthy ACA-Py agent.
Required to call fully integrated:
- [ ] Freeze whether Aries is in or out of scope for the first production slice.
- [ ] Define agent placement, DID model, wallet model, and mediation/routing policy.
- [ ] Validate one real agent-to-agent or institution-facing credential exchange.
- [ ] Add operator runbooks and health/alerting tied to the chosen production role.
### AnonCreds
Current proof:
- ACA-Py is using the `askar-anoncreds` wallet path today.
Required to call fully integrated:
- [ ] Freeze schema and credential-definition lifecycle.
- [ ] Define issuer, holder, and verifier roles.
- [ ] Validate issuance, presentation, verification, and revocation end to end.
- [ ] Archive reproducible evidence for the chosen credential lifecycle.
### Ursa
Current proof:
- No separately managed Ursa daemon or operator-facing runtime is evidenced.
Required to call fully integrated:
- [ ] Decide whether Ursa will ever be an explicit operator-managed dependency.
- [ ] If yes, define packaging, upgrade, and cryptographic-control responsibilities.
- [ ] If no, document it as an indirect dependency only and remove any implied direct-runtime claims.
### Caliper
Current proof:
- `6600` has a working upstream Caliper workspace with the Besu `1.4` binding.
Required to call fully integrated:
- [ ] Freeze the benchmark workloads that matter for RTGS and Chain 138 settlement.
- [ ] Execute the approved read/write benchmark suite.
- [ ] Store benchmark evidence and acceptance thresholds.
- [ ] Tie the benchmark suite to the canonical production gate.
Helpful commands:
```bash
pct exec 6600 -- bash -lc 'cd /opt/caliper/workspace && npx caliper --version'
```
## Recommended next order
1. Freeze scope: decide which of FireFly, Fabric, Indy, Aries, AnonCreds, and Ursa are actually mandatory for the first production slice.
2. Convert runtime-only products into one validated business path each: Cacti, FireFly, Fabric, Indy/Aries.
3. Archive operator evidence and acceptance criteria so the RTGS gate can move from `Partial` to `Complete`.

22
docs/03-deployment/DBIS_HYPERLEDGER_RUNTIME_STATUS.md
View File

@@ -1,6 +1,6 @@
# DBIS Hyperledger Runtime Status
**Last Reviewed:** 2026-03-29
**Last Reviewed:** 2026-04-05
**Purpose:** Concise app-level status table for the non-Besu Hyperledger footprint currently hosted on Proxmox. This complements the VMID inventory and discovery runbooks by recording what was actually verified inside the running containers.
## Scope
@@ -28,11 +28,11 @@ The checks were based on:
| VMID | Service family | CT status | App-level status | Listening ports / probe | Notes |
|------|----------------|-----------|------------------|--------------------------|-------|
| `5200` | Cacti primary | Running | Healthy Besu connector gateway | `4000/tcp` Cacti API, `5000/tcp` local gRPC sidecar | Reworked from the stale two-container template into a live `ghcr.io/hyperledger/cactus-connector-besu:2024-07-04-8c030ae` runtime; container health is `healthy`; `GET /api/v1/api-server/healthcheck` returned `200`; Besu connector plugin loaded against `http://192.168.11.211:8545` / `ws://192.168.11.211:8546` |
| `5201` | Cacti secondary | Stopped | Reserved placeholder | None verified | CT exists in inventory, but no active Cacti payload was validated in this run. Treat as standby metadata until intentionally built. |
| `5202` | Cacti tertiary | Stopped | Reserved placeholder | None verified | Same disposition as `5201`: no proven Cacti workload in this review. |
| `6200` | FireFly primary | Running | Healthy minimal local gateway | `5000/tcp` FireFly API, `5432/tcp` Postgres, `5001/tcp` IPFS | `firefly-core` restored on `ghcr.io/hyperledger/firefly:v1.2.0`; `GET /api/v1/status` returned `200`; Postgres `pg_isready` passed; IPFS version probe passed |
| `5201` | Cacti secondary | Running | Healthy public Cacti surface | `80/tcp` landing page, `4000/tcp` local Cacti API | `GET /` returned `200`; `GET /api/v1/api-server/healthcheck` returned `200`; intended public surface for `cacti-alltra.d-bis.org` with the local Hyperledger Cacti API kept healthy behind it. |
| `5202` | Cacti tertiary | Running | Healthy public Cacti surface | `80/tcp` landing page, `4000/tcp` local Cacti API | Same disposition as `5201`, but for `cacti-hybx.d-bis.org`; both the web landing page and the local Cacti API are healthy. |
| `6200` | FireFly primary | Running | Healthy minimal local gateway | `5000/tcp` FireFly API, `5432/tcp` Postgres, `5001/tcp` IPFS | `firefly-core` is healthy on `ghcr.io/hyperledger/firefly:v1.2.0`; `GET /api/v1/status` returned `200`; Postgres `pg_isready` passed; IPFS version probe passed. On 2026-04-05 the CT was reconciled into an idempotent mixed stack: compose now manages Postgres/IPFS, a helper-backed `firefly.service` treats the existing legacy `firefly-core` container as canonical instead of trying to recreate it, and all three containers use `restart=unless-stopped`. |
| `6201` | FireFly secondary | Stopped | Formally retired until rebuilt | None verified | CT exists in inventory, but the rootfs is effectively empty and no valid FireFly deployment footprint was found. Treat this as retired / standby metadata only until it is intentionally rebuilt as a real secondary node. |
| `6000` | Fabric primary | Running | Operational sample network | `7050/tcp` orderer, `7051/tcp` org1 peer, `9051/tcp` org2 peer, `9443` / `9444` / `9445` operations ports | Official `fabric-samples` payload staged under `/opt/fabric`; `orderer.example.com`, `peer0.org1.example.com`, and `peer0.org2.example.com` are running; `peer channel getinfo -c mychannel` returned height `1` for both orgs. Nested LXC requires the `docker run --security-opt apparmor=unconfined` wrapper that is now part of the working setup. |
| `6000` | Fabric primary | Running | Operational sample network | `7050/tcp` orderer, `7051/tcp` org1 peer, `9051/tcp` org2 peer, `9443` / `9444` / `9445` operations ports | Official `fabric-samples` payload staged under `/opt/fabric`; the sample network was restored and reverified on 2026-04-05; `orderer.example.com`, `peer0.org1.example.com`, and `peer0.org2.example.com` are running again; `peer channel getinfo -c mychannel` now returns height `1`. Nested LXC requires `features: nesting=1,keyctl=1`, and `fabric-sample-network.service` is now installed to re-ensure the sample network after CT restarts. |
| `6001` | Fabric secondary | Stopped | Reserved placeholder | None active | Same disposition as `6000`: no proven Fabric application payload or listeners, now stopped and reserved only as placeholder inventory. |
| `6002` | Fabric tertiary | Stopped | Reserved placeholder | None active | Same disposition as `6000`: no proven Fabric application payload or listeners, now stopped and reserved only as placeholder inventory. |
| `6400` | Indy primary | Running | Healthy four-node local validator pool | `9701`-`9708/tcp` validator and client listeners | `hyperledgerlabs/indy-node:latest` now runs `indy-node-1` through `indy-node-4` under `/opt/indy/docker-compose.yml`; `systemctl is-active indy` returned `active` and `systemctl is-enabled indy` returned `enabled`; all expected `start_indy_node` listeners are bound on `0.0.0.0`. |
@@ -46,6 +46,7 @@ The checks were based on:
### Confirmed working now
- Cacti primary (`5200`) is live as a local Cacti API with the Besu connector plugin loaded and healthy.
- Cacti public surfaces (`5201` and `5202`) are live as landing pages plus local Hyperledger Cacti APIs for the Alltra and HYBX edges.
- FireFly primary (`6200`) is restored enough to provide a working local FireFly API backed by Postgres and IPFS.
- Fabric primary (`6000`) now runs a verified official sample network with one orderer and two peers joined to `mychannel`.
- Indy primary (`6400`) now runs a verified four-node local validator pool with all expected node and client listeners active.
@@ -54,7 +55,6 @@ The checks were based on:
### Present only as reserved placeholders right now
- Cacti CTs (`5201`-`5202`)
- Fabric CTs (`6001`-`6002`)
- Indy CTs (`6401`-`6402`)
@@ -66,10 +66,12 @@ These should be described as reserved placeholder inventory only. The primaries
## Operational follow-up
1. Keep `5200`, `6000`, `6200`, and `6400` under observation and preserve their working images, config paths, and nested-Docker allowances.
2. Keep `6500` and `6600` under observation as primaries for identity-agent and benchmark-harness work, and preserve the Indy genesis handoff plus the Caliper workspace state.
3. Do not force `6201`, `5201`, `5202`, `6001`, `6002`, `6401`, or `6402` online unless their intended roles and deployment assets are re-established from scratch.
3. Any governance or architecture document should distinguish:
1. Keep `5200`, `5201`, `5202`, `6000`, `6200`, and `6400` under observation and preserve their working images, config paths, and nested-Docker allowances.
2. Use `scripts/maintenance/ensure-fabric-sample-network-via-ssh.sh` when the Fabric sample network on `6000` drifts back to stopped peer/orderer containers or after unit-level changes.
3. Use `scripts/maintenance/ensure-firefly-primary-via-ssh.sh` when `6200` shows a failed `firefly.service` state, a compose-version mismatch, or drift between the compose-managed dependencies and the existing `firefly-core` container.
4. Keep `6500` and `6600` under observation as primaries for identity-agent and benchmark-harness work, and preserve the Indy genesis handoff plus the Caliper workspace state.
5. Do not force `6201`, `6001`, `6002`, `6401`, or `6402` online unless their intended roles and deployment assets are re-established from scratch.
6. Any governance or architecture document should distinguish:
- `deployed and app-healthy`
- `container present only`
- `planned / aspirational`

11
docs/03-deployment/DBIS_PHASE3_E2E_PRODUCTION_SIMULATION_RUNBOOK.md
View File

@@ -1,6 +1,6 @@
# DBIS Phase 3 — End-to-end production simulation
**Last updated:** 2026-03-28
**Last updated:** 2026-04-05
**Purpose:** Operationalize [dbis_chain_138_technical_master_plan.md](../../dbis_chain_138_technical_master_plan.md) Section 18 (example flow) and Sections 14, 17 as **repeatable liveness and availability checks** — not a single product build or a full business-E2E execution harness.
**Prerequisites:** LAN access where noted; [DBIS_NODE_ROLE_MATRIX.md](../02-architecture/DBIS_NODE_ROLE_MATRIX.md) for IPs/VMIDs; operator env via `scripts/lib/load-project-env.sh` for on-chain steps.
@@ -11,12 +11,12 @@
| Step | Master plan | Verification (repo-aligned) |
|------|-------------|-----------------------------|
| 1 | Identity issued (Indy) | Indy steward / node RPC on VMID **6400** (192.168.11.64); pool genesis tools — **manual** until automated issuer script exists. Current CTs `6400/6401/6402` are present, but app-level Indy listener verification is still pending. |
| 1 | Identity issued (Indy) | Indy steward / node RPC on VMID **6400** (192.168.11.64); pool genesis tools — **manual** until automated issuer script exists. Primary Indy listener verification is now proven on `6400`, but issuer / holder / verifier business flow is still manual. |
| 2 | Credential verified (Aries) | Aries agents (if colocated): confirm stack on Indy/FireFly integration path — **TBD** per deployment. |
| 3 | Workflow triggered (FireFly) | FireFly API on **6200** (currently restored as a minimal local gateway profile at `http://192.168.11.35:5000`). VMID **6201** is presently stopped / standby and should not be assumed active. |
| 4 | Settlement executed (Besu) | JSON-RPC `eth_chainId`, `eth_blockNumber`, optional test transaction via `smom-dbis-138` with `RPC_URL_138=http://192.168.11.211:8545`. PMM/oracle: [ORACLE_AND_KEEPER_CHAIN138.md](../../smom-dbis-138/docs/integration/ORACLE_AND_KEEPER_CHAIN138.md). |
| 5 | Cross-chain sync (Cacti) | Cacti = network monitoring here (VMID **5200**); **Hyperledger Cacti** interoperability is **future/optional** — track separately if deployed. **CCIP:** relay on r630-01 per [CCIP_RELAY_DEPLOYMENT.md](../07-ccip/CCIP_RELAY_DEPLOYMENT.md). |
| 6 | Compliance recorded (Fabric) | Fabric CTs `6000/6001/6002` are present, but current app-level verification has not yet proven active peer / orderer workloads inside those CTs. Treat Fabric business-flow validation as manual until that gap is closed. |
| 5 | Cross-chain sync (Cacti) | Hyperledger Cacti is live on `5200` as a Besu-facing gateway, and `5201/5202` serve the Alltra/HYBX public Cacti surfaces. Production cross-ledger business flow is still optional / manual until a canonical DBIS path is frozen. **CCIP:** relay on r630-01 per [CCIP_RELAY_DEPLOYMENT.md](../07-ccip/CCIP_RELAY_DEPLOYMENT.md). |
| 6 | Compliance recorded (Fabric) | Fabric sample network on `6000` is now active again with one orderer and two peers on `mychannel`, but Fabric chaincode / listener / RTGS business-flow validation remains manual until the canonical integration path is proven. |
| 7 | Final settlement confirmed | Re-check Besu head on **2101** and **2201**; Blockscout **5000** for tx receipt if applicable. |
---
@@ -72,5 +72,8 @@ Use [OPERATOR_READY_CHECKLIST.md](../00-meta/OPERATOR_READY_CHECKLIST.md) sectio
## Related
- [PHASE1_DISCOVERY_RUNBOOK.md](PHASE1_DISCOVERY_RUNBOOK.md)
- [DBIS_HYPERLEDGER_RUNTIME_STATUS.md](DBIS_HYPERLEDGER_RUNTIME_STATUS.md)
- [DBIS_HYPERLEDGER_PRODUCT_INTEGRATION_CHECKLIST.md](DBIS_HYPERLEDGER_PRODUCT_INTEGRATION_CHECKLIST.md)
- [DBIS_PHASES_1_TO_3_PRODUCTION_GATE.md](DBIS_PHASES_1_TO_3_PRODUCTION_GATE.md)
- [DBIS_PHASE2_PROXMOX_SOVEREIGNIZATION_ROADMAP.md](../02-architecture/DBIS_PHASE2_PROXMOX_SOVEREIGNIZATION_ROADMAP.md)
- [verify-end-to-end-routing.sh](../../scripts/verify/verify-end-to-end-routing.sh) — public/private ingress

19
docs/03-deployment/DBIS_PHASES_1_TO_3_PRODUCTION_GATE.md
View File

@@ -1,6 +1,6 @@
# DBIS Chain 138 — Phases 1-3 Production Gate
**Last updated:** 2026-03-28
**Last updated:** 2026-04-05
**Purpose:** Convert the DBIS master plan into an operational production gate. This document records which Phase 1-3 conditions are currently satisfied, which are partially satisfied, and which still block an honest production declaration.
## Overall status
@@ -22,8 +22,8 @@
### What is not yet proven production-ready
- FireFly secondary failover footprint (`6201`) is not deployed; it is currently retired / standby until rebuilt
- Fabric peer / orderer workload health inside `6000-6002`; those CTs are now intentionally stopped as reserved placeholders
- Indy validator / node listener health inside `6400-6402`; those CTs are now intentionally stopped as reserved placeholders
- Fabric business-role integration beyond the restored sample network on `6000`
- Indy identity-role integration beyond the healthy validator pool on `6400`
- Sovereignized Phase 2 platform baseline:
- Ceph-backed storage
- final VLAN segmentation
@@ -71,8 +71,8 @@
| Automated liveness wrapper exists | Complete | [scripts/verify/run-dbis-phase3-e2e-simulation.sh](../../scripts/verify/run-dbis-phase3-e2e-simulation.sh) |
| Besu liveness passes | Complete | direct script output and [scripts/verify/check-chain138-rpc-health.sh](../../scripts/verify/check-chain138-rpc-health.sh) |
| FireFly HTTP liveness passes | Complete | `6200` returns `HTTP 200` on `/api/v1/status` |
| Fabric app-native business flow validation passes | Blocked | Current checks found no active Fabric payload, processes, or listeners; CTs are now intentionally stopped as reserved placeholders |
| Indy app-native business flow validation passes | Blocked | Current checks found no active Indy payload, processes, or listeners; CTs are now intentionally stopped as reserved placeholders |
| Fabric app-native business flow validation passes | Blocked | `6000` now runs a restored sample network again, but Fabric chaincode / listener / RTGS business flows are still not validated end to end |
| Indy app-native business flow validation passes | Blocked | `6400` now runs a healthy validator pool, but issuer / holder / verifier business flows are still not validated end to end |
| Cross-chain / Cacti business flow validation passes | Blocked | not currently proven as deployed live DBIS path |
| Full business E2E has been demonstrated | Blocked | current wrapper is intentionally liveness-only |
@@ -85,8 +85,8 @@
The following items still prevent a full “DBIS Chain 138 production complete” declaration:
1. `6201` is not a verified active secondary FireFly node and is currently treated as retired / standby until rebuilt.
2. Fabric `6000-6002` are not active peer/orderer workloads; current evidence showed placeholder CTs only, and they have now been stopped and retained as reserve inventory.
3. Indy `6400-6402` are not active validator workloads; current evidence showed placeholder CTs only, and they have now been stopped and retained as reserve inventory.
2. Fabric `6000` is only a restored sample network today; `6001` and `6002` remain reserve inventory, and no canonical business workflow is yet validated through Fabric.
3. Indy `6400` is a healthy validator pool today; `6401` and `6402` remain reserve inventory, and no canonical identity business workflow is yet validated through Indy.
4. Phase 2 sovereignization is still roadmap work, not completed platform state.
5. The current Phase 3 wrapper is liveness validation, not end-to-end business certification.
@@ -107,8 +107,8 @@ It is **not** yet accurate to declare:
## Next production-closing actions
1. Decide whether `6201` is to be rebuilt as a real secondary FireFly node or left retired as a reserve inventory slot.
2. Either deploy real Fabric workloads inside `6000-6002` and validate them, or leave those CTs stopped as reserved placeholders.
3. Either deploy real Indy workloads inside `6400-6402` and validate them, or leave those CTs stopped as reserved placeholders.
2. Decide whether the restored Fabric sample network on `6000` remains only a validation sidecar or evolves into a canonical workload, then validate the corresponding chaincode / listener / business flow.
3. Decide whether the healthy Indy validator pool on `6400` remains optional or becomes a canonical identity dependency, then validate the corresponding issuer / holder / verifier flow.
4. Execute the first real Phase 2 platform milestone:
- fleet expansion, or
- Ceph pilot, or
@@ -121,4 +121,5 @@ It is **not** yet accurate to declare:
- [docs/03-deployment/PHASE1_DISCOVERY_RUNBOOK.md](PHASE1_DISCOVERY_RUNBOOK.md)
- [docs/03-deployment/DBIS_PHASE3_E2E_PRODUCTION_SIMULATION_RUNBOOK.md](DBIS_PHASE3_E2E_PRODUCTION_SIMULATION_RUNBOOK.md)
- [docs/03-deployment/DBIS_HYPERLEDGER_RUNTIME_STATUS.md](DBIS_HYPERLEDGER_RUNTIME_STATUS.md)
- [docs/03-deployment/DBIS_HYPERLEDGER_PRODUCT_INTEGRATION_CHECKLIST.md](DBIS_HYPERLEDGER_PRODUCT_INTEGRATION_CHECKLIST.md)
- [docs/02-architecture/DBIS_PHASE2_PROXMOX_SOVEREIGNIZATION_ROADMAP.md](../02-architecture/DBIS_PHASE2_PROXMOX_SOVEREIGNIZATION_ROADMAP.md)

6
docs/03-deployment/DEFI_AGGREGATOR_DEX_ROUTING_FLOWS_DIAGRAM.md
View File

@@ -142,7 +142,7 @@ sequenceDiagram
| **MCP reads pool state** | AI/MCP → Allowlist → get_pool_state (RPC) → DODOPMMIntegration (138) or cW* pool or Uniswap (public) | One MCP per chain or multi-chain allowlist. |
| **MCP / AI maintenance** | AI → MCP quote_add_liquidity / add_liquidity / remove_liquidity → DODOPMMIntegration or public DEX | Dedicated MCP/AI for Dodoex + Uniswap pool management. |
| **Bot peg maintenance** | Bot → Deviation watcher (pool vs oracle) → buy/sell cW* or inventory adjust → cW* / HUB pools on public chain | State machine: IDLE, ABOVE_BAND, BELOW_BAND, COOLDOWN, CIRCUIT_BREAK. |
| **Multi-provider (future)** | User / Contract → EnhancedSwapRouter → DODOPMMProvider + Uniswap + Balancer + Curve (by size/slippage) → Pools on 138 | When EnhancedSwapRouter deployed and pools exist. |
| **Multi-provider (live pilot layer)** | User / Contract → EnhancedSwapRouterV2 → DODOPMMProvider + DODO v3 pilot + pilot-compatible Uniswap/Balancer/Curve/1inch venues (by size/slippage / planner-v2 selection) → Pools on 138 | Live on Chain 138. Public planner visibility is under `/token-aggregation/api/v2/*`; canonical `WETH` routing asset lanes use the funded pilot venue layer. |
---
@@ -154,11 +154,11 @@ sequenceDiagram
| **DODOPMMIntegration** | Creates pools, adds liquidity, executes swaps (legacy pairs + swapExactIn for full mesh). |
| **DODOPMMProvider** | Routing front: getQuote, executeSwap; registers pools; uses integration for execution. |
| **Bridge quote API** | Orchestrates source swap + bridge + destination swap; uses token-aggregation or destination DEX for quotes. |
| **External aggregators** | 1inch, 0x, ParaSwap: multi-DEX routing on supported chains; 138 not supported until they add it. |
| **External aggregators** | Upstream-native 1inch, 0x, ParaSwap: multi-DEX routing on supported chains; Chain 138 still uses repo-managed pilot-compatible venues instead of upstream public deployments. |
| **Bridge aggregator** | Explorer backend: Li.Fi, Socket, etc., for bridge routes only. |
| **MCP** | Read (and optionally execute) pool state and liquidity ops; allowlist per chain or multi-chain. |
| **Bot** | Maintains cW* peg on public chains via single-sided cW* / HUB pools; deviation and inventory. |
| **EnhancedSwapRouter** | (Optional) Multi-provider router on 138 when Uniswap/Balancer/Curve pools exist. |
| **EnhancedSwapRouterV2** | Live multi-provider router on 138 with DODO V2 PMM, DODO v3 pilot, and funded pilot-compatible `Uniswap_v3`, `Balancer`, `Curve_3`, and `1inch` venues. |
---

5
docs/03-deployment/DEPLOYER_GAS_AUTO_ROUTE_RUNBOOK.md
View File

@@ -1,6 +1,6 @@
# Deployer Gas Auto-Route Runbook
**Purpose:** Convert deployer wallet ERC-20 (or compliant) tokens to **native gas tokens** on each target chain where balance is below threshold. Uses internal path (Chain 138), Protocolink (public chains), or manual/LiFi (Wemix).
**Purpose:** Convert deployer wallet ERC-20 (or compliant) tokens to **native gas tokens** on each target EIP-155 chain where balance is below threshold. Uses internal path (Chain 138), Protocolink (public chains), or manual/LiFi (Wemix). Non-EVM planning targets such as Solana are tracked separately in the same config, but are not auto-routed by the current script.
**Deployer address:** `0x4A666F96fC8764181194447A7dFdb7d471b301C8`
@@ -12,7 +12,7 @@
2. **Environment:** `smom-dbis-138/.env` (or project env loaded by `scripts/lib/load-project-env.sh`) with:
- `PRIVATE_KEY` or `DEPLOYER_ADDRESS`
- Per-chain RPC URLs: `RPC_URL_138`, `ETHEREUM_MAINNET_RPC`, `BSC_RPC_URL`, `POLYGON_MAINNET_RPC`, `GNOSIS_MAINNET_RPC`, `ARBITRUM_MAINNET_RPC`, `OPTIMISM_MAINNET_RPC`, `BASE_MAINNET_RPC`, `AVALANCHE_RPC_URL`, `CRONOS_RPC_URL`, `CELO_RPC_URL`, `WEMIX_RPC`, `GNOSIS_RPC`. For ALL Mainnet (651940) and Etherlink (42793): set `RPC_URL_651940` and `RPC_URL_42793` (or equivalent) when present so the orchestrator can show balance/route for those chains; otherwise they appear as "no RPC configured".
3. **Config:** [config/deployer-gas-routes.json](../../config/deployer-gas-routes.json) — chain-to-method mapping and thresholds. **Multiple swap routes for CRO and WEMIX:** [config/cro-wemix-swap-routes.json](../../config/cro-wemix-swap-routes.json) — SwapSpace, ChangeNOW, SimpleSwap, StealthEX and others; used by `acquire-cro-and-wemix-gas.sh`.
3. **Config:** [config/deployer-gas-routes.json](../../config/deployer-gas-routes.json) — chain-to-method mapping and thresholds. **Multiple swap routes for CRO and WEMIX:** [config/cro-wemix-swap-routes.json](../../config/cro-wemix-swap-routes.json) — SwapSpace, ChangeNOW, SimpleSwap, StealthEX and others; used by `acquire-cro-and-wemix-gas.sh`. Non-EVM desired targets (currently **Solana**) live under the config's `nonEvmNetworks` section as manual/planning entries.
---
@@ -65,6 +65,7 @@ The orchestrator:
| **Protocolink (public chains)** | Use the quote/output from `protocolink-swap-to-gas.cjs`. Build transaction via [Protocolink API](https://docs.protocolink.com/protocolink-api/overview) (estimate router data, build tx); sign with deployer key and submit. |
| **Cronos (25)** | **Manual (multiple routes):** Protocolink does not support Cronos. Use any aggregator from [config/cro-wemix-swap-routes.json](../../config/cro-wemix-swap-routes.json) (SwapSpace, ChangeNOW, SimpleSwap, StealthEX) to swap ETH/BNB/USDT/USDC → CRO; send to deployer on Cronos. Required ~15 CRO. List all routes: `./scripts/deployment/acquire-cro-and-wemix-gas.sh` or `--list`. |
| **Wemix (1111)** | **Manual (multiple routes):** Use any aggregator from [config/cro-wemix-swap-routes.json](../../config/cro-wemix-swap-routes.json) (SwapSpace, ChangeNOW, SimpleSwap, StealthEX) to swap ETH/BNB/POL → WEMIX; send to deployer on chain 1111. Required ~0.4 WEMIX. List all routes: `./scripts/deployment/acquire-cro-and-wemix-gas.sh` or `--list`. Then run `deploy-bridges-config-ready-chains.sh wemix` and complete-config. See [WEMIX_ACQUISITION_TABLED.md](WEMIX_ACQUISITION_TABLED.md). |
| **Solana (planning target)** | **Manual / non-EVM:** Acquire SOL for the assigned Solana deployer or relay signer when the Solana rollout wave is opened. This repo currently tracks Solana as a desired non-EVM deployment network, but `deployer-gas-auto-route.sh` does not execute non-EVM funding. |
---

22
docs/03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md
View File

@@ -1,8 +1,8 @@
# Full Deployment Order of Operations
> Historical note (2026-03-26): this run order includes earlier PMM deployment phases. The current canonical Chain 138 PMM stack is `DODOPMMIntegration=0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d` and `DODOPMMProvider=0x5CAe6Ce155b7f08D3a956F5Dc82fC9945f29B381`. Use [ADDRESS_MATRIX_AND_STATUS.md](../11-references/ADDRESS_MATRIX_AND_STATUS.md) for live addresses.
> Historical note (2026-04-02): this run order includes earlier PMM deployment phases. The current canonical Chain 138 PMM stable stack is `DODOPMMIntegration=0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895` and `DODOPMMProvider=0x3f729632E9553EBacCdE2e9b4c8F2B285b014F2e`. Public XAU pools remain on the older PMM phase until explicitly migrated. Use [ADDRESS_MATRIX_AND_STATUS.md](../11-references/ADDRESS_MATRIX_AND_STATUS.md) for live addresses.
**Last Updated:** 2026-02-28
**Last Updated:** 2026-04-03
**Purpose:** Single canonical sequence for deploying and completing the system: prerequisites → Chain 138 core → PMM/pools → provider → optional → cW* → verification. Use this as the master order; other runbooks give per-step detail.
**Related:** [RECOMMENDATIONS_AND_FIXES_BEFORE_DEPLOY.md](RECOMMENDATIONS_AND_FIXES_BEFORE_DEPLOY.md) (all recommendations & fixes before deploy) | [PRE_DEPLOYMENT_CHECKLIST.md](PRE_DEPLOYMENT_CHECKLIST.md) (PMM/pools focus) | [CONTRACT_DEPLOYMENT_RUNBOOK.md](CONTRACT_DEPLOYMENT_RUNBOOK.md) (per-script detail) | [RECOMMENDATIONS_OPERATOR_CHECKLIST.md](../00-meta/RECOMMENDATIONS_OPERATOR_CHECKLIST.md) (R1–R24)
@@ -31,7 +31,7 @@ Before any Chain 138 deployment, follow these four rules:
| **2** | TransactionMirror + PMM pools (Chain 138) | Required for PMM routing |
| **3** | Liquidity + DODOPMMProvider | After pools exist |
| **4** | Optional: EnhancedSwapRouter, trustless, CCIP other chains | When dependencies exist |
| **5** | cW* edge pools (11 public chains) | When cW* tokens and infra exist |
| **5** | cW* edge pools (11 public EVM chains) | When cW* tokens and infra exist |
| **6** | Post-deploy verification & recommendations | After each phase and ongoing |
---
@@ -44,7 +44,7 @@ Execute in any order where no dependency; all must be satisfied before Phase 1
|---|------|--------|
| 0.1 | **RPC 2101 (Core) writable** | If read-only: `./scripts/maintenance/make-rpc-vmids-writable-via-ssh.sh` then `./scripts/maintenance/health-check-rpc-2101.sh`. See [RPC_2101_READONLY_FIX.md](RPC_2101_READONLY_FIX.md). |
| 0.2 | **Deployer wallet funded (Chain 138)** | ≥ ~0.006 ETH (recommended 1–2 ETH). Check: `cd smom-dbis-138 && ./scripts/deployment/check-balances-gas-and-deploy.sh`. |
| 0.3 | **Env configured** | `smom-dbis-138/.env` only: `PRIVATE_KEY`, `RPC_URL_138` (Core); for PMM: `DODO_PMM_INTEGRATION_ADDRESS=0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d`, `DODO_PMM_PROVIDER_ADDRESS=0x5CAe6Ce155b7f08D3a956F5Dc82fC9945f29B381`. Optional: `GAS_PRICE_138`, `GAS_PRICE`. Run: `cd smom-dbis-138 && ./scripts/deployment/check-env-required.sh`. Or from repo root: `./scripts/deployment/preflight-chain138-deploy.sh`. |
| 0.3 | **Env configured** | `smom-dbis-138/.env` only: `PRIVATE_KEY`, `RPC_URL_138` (Core); for PMM: `DODO_PMM_INTEGRATION_ADDRESS=0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895`, `DODO_PMM_PROVIDER_ADDRESS=0x3f729632E9553EBacCdE2e9b4c8F2B285b014F2e`. Optional: `GAS_PRICE_138`, `GAS_PRICE`. Run: `cd smom-dbis-138 && ./scripts/deployment/check-env-required.sh`. Or from repo root: `./scripts/deployment/preflight-chain138-deploy.sh`. |
| 0.4 | **Gas / cost estimate** | Run cost estimate before deploy: `cd smom-dbis-138 && ./scripts/deployment/calculate-costs-consolidated.sh` (or see [DEPLOYMENT_GAS_COSTS_REALTIME](../11-references/DEPLOYMENT_GAS_COSTS_REALTIME.md)). Chain 138 uses min 1 gwei; script gives estimated total cost. |
| 0.5 | **POOL_MANAGER_ROLE** | Deployer must have POOL_MANAGER_ROLE on DODOPMMIntegration for pool creation and provider registration. |
| 0.6 | **No stuck transactions** | If nonce has pending txs or "Replacement transaction underpriced": run `./scripts/clear-all-transaction-pools.sh` then wait ~60s. Use Core RPC only (no Public fallback). Prefer deploy scripts that check nonce (e.g. `deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh`). |
@@ -55,7 +55,7 @@ Execute in any order where no dependency; all must be satisfied before Phase 1
## Phase 1 — Chain 138 core (if not already deployed)
If core contracts are already deployed (e.g. **64/64** present per check-contracts-on-chain-138.sh), skip to Phase 2. Otherwise follow this order.
If core contracts are already deployed (e.g. **88/88** present per check-contracts-on-chain-138.sh on the current canonical inventory), skip to Phase 2. Otherwise follow this order.
| # | Item | Script / command | Depends on |
|---|------|------------------|------------|
@@ -90,7 +90,7 @@ Required for PMM routing. Full steps: [PRE_DEPLOYMENT_CHECKLIST.md](PRE_DEPLOYME
| 3.1 | **Add liquidity (optional)** | Per pool: approve base/quote to DODOPMMIntegration, then `addLiquidity(pool, baseAmount, quoteAmount)`. See [DODO_PMM_INTEGRATION.md](../../smom-dbis-138/docs/integration/DODO_PMM_INTEGRATION.md). |
| 3.2 | **Deploy DODOPMMProvider** | `forge script script/liquidity/DeployDODOPMMProvider.s.sol:DeployDODOPMMProvider --rpc-url $RPC_URL_138 --broadcast --private-key $PRIVATE_KEY --with-gas-price 1000000000`. Set `DODO_PMM_PROVIDER_ADDRESS` in .env. |
| 3.3 | **Register pools** | Register every created pool in DODOPMMProvider (legacy three at minimum; full mesh when used). |
| 3.4 | **Token-aggregation** | Set `CHAIN_138_DODO_PMM_INTEGRATION` where the token-aggregation service runs; ensure indexer runs so API exposes pools. |
| 3.4 | **Token-aggregation** | Set `CHAIN_138_DODO_PMM_INTEGRATION` where the token-aggregation service runs; ensure indexer runs so API exposes pools. The live explorer deployment now persists the three canonical stable pools via the standalone lightweight schema bootstrap. |
| 3.5 | **MCP allowlist (optional)** | Use `ai-mcp-pmm-controller/config/allowlist-138.json` (Chain 138 pools). Run with `ALLOWLIST_PATH=config/allowlist-138.json CHAIN=138`. See [README-allowlist-138.md](../../ai-mcp-pmm-controller/config/README-allowlist-138.md). |
---
@@ -101,14 +101,16 @@ Only when dependencies exist (Uniswap/Balancer on 138, or mainnet/other-chain RP
| # | Item | When / command |
|---|------|----------------|
| 4.1 | **EnhancedSwapRouter (Chain 138)** | When Uniswap V3 / Balancer pools exist on 138: deploy with chain-138–aware script (env quoter/poolId); configure post-deploy. See CONTRACT_DEPLOYMENT_RUNBOOK § EnhancedSwapRouter. |
| 4.1 | **EnhancedSwapRouter (Chain 138)** | Deployment dry-run is now healthy with the standard project env loader. Broadcast only when at least one live WETH-to-stable route exists if `swapToStablecoin()` is required; otherwise the router is DODO-only. See CONTRACT_DEPLOYMENT_RUNBOOK § EnhancedSwapRouter. |
| 4.2 | **Trustless stack (Lockbox138 + Mainnet)** | When Mainnet RPC and keys available: deploy trustless bridge contracts; set INBOX_ETH, BOND_MANAGER, etc. See [OPTIONAL_DEPLOYMENTS_START_HERE.md](../07-ccip/OPTIONAL_DEPLOYMENTS_START_HERE.md) §2C. |
| 4.3 | **CCIP other chains (Gnosis, Celo, Wemix)** | Deploy WETH bridges per chain; add destinations 138↔chain; fund LINK. See [CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md](../07-ccip/CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md). |
| 4.4 | **LINK on Mainnet relay** | [RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md](../07-ccip/RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md). |
---
## Phase 5 — cW* edge pools (11 public chains)
## Phase 5 — cW* edge pools (11 public EVM chains)
Desired non-EVM rollout targets such as **Solana** sit **outside** this phase. They are tracked under `config/token-mapping-multichain.json -> nonEvmNetworks` and the GRU rollout queue, and require adapter / relay wiring plus an SPL or bridge-wrapped asset representation rather than the EVM PMM edge-pool recipe.
Design and pool matrix: [POOLS_AND_NETWORKS_FULL_DESIGN.md](../11-references/POOLS_AND_NETWORKS_FULL_DESIGN.md). Per chain: deploy cW* tokens (or bridge), then create 6 “poolsFirst” + optional pools per [pool-matrix.json](../../cross-chain-pmm-lps/config/pool-matrix.json) and [06-deployment-recipe.md](../../cross-chain-pmm-lps/docs/06-deployment-recipe.md).
@@ -125,7 +127,7 @@ After each deployment phase and periodically.
| # | Item | Command / doc |
|---|------|----------------|
| 6.1 | **On-chain verification (Chain 138)** | `./scripts/verify/check-contracts-on-chain-138.sh [RPC_URL]`. Target **64/64** when TransactionMirror, all three PMM pools, vault/reserve, CompliantFiatTokens, ISO20022Router, and **canonical + legacy** CCIP router/WETH9 bridge slots exist (see `config/smart-contracts-master.json`). |
| 6.1 | **On-chain verification (Chain 138)** | `./scripts/verify/check-contracts-on-chain-138.sh [RPC_URL]`. Target **88/88** on the current canonical inventory in `config/smart-contracts-master.json`, including the stable PMM stack, ISO20022Router, canonical + legacy CCIP router/WETH9 bridge slots, the cross-chain flash trio, GRU V2 USD pair, router-v2 execution stack, upstream-native Uniswap v3 stack, and the funded pilot-compatible secondary venues. |
| 6.2 | **Blockscout verification** | When Blockscout reachable: `./scripts/verify/run-contract-verification-with-proxy.sh`. See [BLOCKSCOUT_VERIFICATION_GUIDE.md](../08-monitoring/BLOCKSCOUT_VERIFICATION_GUIDE.md). |
| 6.3 | **Update address docs** | Update [CONTRACT_ADDRESSES_REFERENCE.md](../11-references/CONTRACT_ADDRESSES_REFERENCE.md), [LIQUIDITY_POOLS_MASTER_MAP.md](../11-references/LIQUIDITY_POOLS_MASTER_MAP.md) with new pool and provider addresses. |
| 6.4 | **Recommendations (R1–R24)** | Follow [RECOMMENDATIONS_OPERATOR_CHECKLIST.md](../00-meta/RECOMMENDATIONS_OPERATOR_CHECKLIST.md): verify on Blockscout, keep address refs updated, use correct RPC/gas, manage nonce, runbooks in sync, monitoring, testing, token mapping. |
@@ -175,7 +177,7 @@ For a single page of exact commands (CCIP bridges, LINK relay, Blockscout verify
1. **Prerequisites:** RPC writable (Core only), deployer funded, **smom-dbis-138/.env** (no other dotenv), gas/cost estimate run, POOL_MANAGER_ROLE, **no stuck txs** (clear pool if needed), forge build.
2. **Chain 138 core:** 01_DeployCore → set env → 02_DeployBridges (or unified script); WETH9 bridge; deterministic if needed.
3. **PMM:** TransactionMirror + create mesh-first pools on Chain 138 (`create-pmm-full-mesh-chain138.sh`), or legacy three as minimum fallback.
4. **Provider:** Add liquidity (optional) → deploy DODOPMMProvider → register all created pools → token-aggregation env → MCP allowlist (optional).
4. **Provider:** Add liquidity (optional) → deploy DODOPMMProvider or sync current mappings → register all created pools → token-aggregation env → MCP allowlist (optional).
5. **Optional:** EnhancedSwapRouter (when Uniswap/Balancer on 138), trustless stack, CCIP other chains, LINK relay.
6. **cW*:** Per chain: deploy/bridge cW* tokens, create and fund pools per pool-matrix.
7. **Verify & recommendations:** check-contracts-on-chain-138.sh, Blockscout verify, update address docs, R1–R24, full recommendations list.

3
docs/03-deployment/DEPLOYMENT_RUNBOOK.md
View File

@@ -75,7 +75,7 @@ export REDIS_URL=redis://redis.example.com:6379
# RPC
export RPC_URL=https://rpc.d-bis.org
export WS_URL=wss://rpc.d-bis.org
export WS_URL=wss://ws.rpc.d-bis.org
# Application
export CHAIN_ID=138
@@ -455,4 +455,3 @@ curl https://api.d-bis.org/api/v1/track2/stats
**Document Version**: 1.0.0
**Last Reviewed**: $(date)
**Next Review**: $(date -d "+3 months")

6
docs/03-deployment/DEPLOYMENT_STATUS_MASTER.md
View File

@@ -1,6 +1,6 @@
# Deployment Status Master - Complete Overview
**Last Updated:** 2026-02-12
**Last Updated:** 2026-04-03
**Status:** 🚀 **ACTIVE DEPLOYMENT**
**Progress:** Foundation Complete → Service Migration In Progress
@@ -78,14 +78,14 @@
### r630-01 (192.168.11.11)
**Running Containers:**
- Infrastructure: 100-108 (proxmox-mail-gateway, datacenter-manager, cloudflared, omada, gitea, nginxproxymanager, redis-rpc-translator, web3signer-rpc-translator, vault-rpc-translator)
- Infrastructure: 100-108 (proxmox-mail-gateway, datacenter-manager, cloudflared, gitea, nginxproxymanager, redis-rpc-translator, web3signer-rpc-translator, vault-rpc-translator); **VMID 103 (Omada) removed 2026-04-04**
- Monitoring: 130 (monitoring-1)
- **Besu RPC: 2503, 2504, 2505** (besu-rpc-hybx-1/2/3)
- **Hyperledger: 5200 (cacti-1), 6000 (fabric-1), 6400 (indy-1)**
**Host Services (not LXC):**
- **CCIP Relay Service** — `/opt/smom-dbis-138/services/relay` (Node.js); relays Chain 138 → Mainnet; uses VMID 2201 RPC. See [07-ccip/CCIP_RELAY_DEPLOYMENT.md](../07-ccip/CCIP_RELAY_DEPLOYMENT.md).
- **Chain 138 smart contracts** — 36-address on-chain check: `./scripts/verify/check-contracts-on-chain-138.sh`; AddressMapper, MirrorManager deployed 2026-02-12. Deploy with `--with-gas-price 1000000000`. See [CONTRACT_ADDRESSES_REFERENCE](../11-references/CONTRACT_ADDRESSES_REFERENCE.md), [CONTRACT_DEPLOYMENT_RUNBOOK](CONTRACT_DEPLOYMENT_RUNBOOK.md).
- **Chain 138 smart contracts** — current canonical on-chain check is `88/88` via `./scripts/verify/check-contracts-on-chain-138.sh`; deploy with `--with-gas-price 1000000000`. See [CONTRACT_ADDRESSES_REFERENCE](../11-references/CONTRACT_ADDRESSES_REFERENCE.md) and [CONTRACT_DEPLOYMENT_RUNBOOK](CONTRACT_DEPLOYMENT_RUNBOOK.md).
**Stopped Containers (30+):**
- DBIS services: 10100-10151

72
docs/03-deployment/ETHEREUM_MAINNET_DODOPMMINTEGRATION_VERIFICATION.md Normal file
View File

@@ -0,0 +1,72 @@
# Ethereum Mainnet DODOPMMIntegration Verification
**Closed:** 2026-04-11
**Contract:** `DODOPMMIntegration`
**Address:** `0xa9F284eD010f4F7d7F8F201742b49b9f58e29b84`
**Network:** Ethereum Mainnet (`1`)
**Explorer:** <https://etherscan.io/address/0xa9F284eD010f4F7d7F8F201742b49b9f58e29b84#code>
## Outcome
- Etherscan source verification passed on 2026-04-11.
- The contract page now shows `Contract Name: DODOPMMIntegration`.
- Compiler metadata confirmed on Etherscan:
- `v0.8.20+commit.a1b79de6`
- optimizer enabled
- `200` runs
- `london` EVM version
## Why historical source was required
Current `smom-dbis-138` HEAD no longer matched the deployed init code. Verification succeeded only after rebuilding against the historical source snapshot from:
- `smom-dbis-138` commit `1511f33857829b762de5deeea135ce5af117997f`
This is the source revision that matched both the deployment bytecode and the on-chain runtime.
## Deployment provenance
- **Creator / admin:** `0x4A666F96fC8764181194447A7dFdb7d471b301C8`
- **Create tx:** `0xeba51be6aa35825acfaedea122317a24951c4480e1f0fe610361bfab3dc1cea3`
Constructor arguments used for verification:
```text
admin 0x4A666F96fC8764181194447A7dFdb7d471b301C8
dodoVendingMachine 0x9b55D9Bc2337f53aaF76AD923CCd01f0D2e4d07D
dodoApprove 0x0000000000000000000000000000000000000000
officialUSDT 0xdAC17F958D2ee523a2206206994597C13D831ec7
officialUSDC 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
compliantUSDT 0xaF5017d0163ecb99D9B5D94e3b4D7b09Af44D8AE
compliantUSDC 0x2de5F116bFcE3d0f922d9C8351e0c5Fc24b9284a
```
ABI-encoded constructor arguments:
```text
0x0000000000000000000000004a666f96fc8764181194447a7dfdb7d471b301c80000000000000000000000009b55d9bc2337f53aaf76ad923ccd01f0d2e4d07d0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000dac17f958d2ee523a2206206994597c13d831ec7000000000000000000000000a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48000000000000000000000000af5017d0163ecb99d9b5d94e3b4d7b09af44d8ae0000000000000000000000002de5f116bfce3d0f922d9c8351e0c5fc24b9284a
```
## Verification command
Run from a worktree or checkout whose `contracts/dex/DODOPMMIntegration.sol` matches commit `1511f33857829b762de5deeea135ce5af117997f`:
```bash
forge verify-contract \
0xa9F284eD010f4F7d7F8F201742b49b9f58e29b84 \
contracts/dex/DODOPMMIntegration.sol:DODOPMMIntegration \
--chain-id 1 \
--num-of-optimizations 200 \
--constructor-args 0x0000000000000000000000004a666f96fc8764181194447a7dfdb7d471b301c80000000000000000000000009b55d9bc2337f53aaf76ad923ccd01f0d2e4d07d0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000dac17f958d2ee523a2206206994597c13d831ec7000000000000000000000000a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48000000000000000000000000af5017d0163ecb99d9b5d94e3b4d7b09af44d8ae0000000000000000000000002de5f116bfce3d0f922d9c8351e0c5fc24b9284a \
--watch
```
## Remaining manual step
Source verification is complete. If a public explorer tag / label is still desired, that is a separate manual Etherscan account workflow:
1. Open the contract page on Etherscan.
2. Use `Update Name Tag or Label`.
3. Complete ownership / support flow required by Etherscan.
Do not treat the manual name-tag step as blocking source-verification closure in repo inventories.

265
docs/03-deployment/EXPLORER_ACCESS_AND_RPC_PRODUCTS_RUNBOOK.md Normal file
View File

@@ -0,0 +1,265 @@
# Explorer Access And RPC Products Runbook
## Purpose
This runbook explains the explorer access layer that now sits alongside the public Chain 138 explorer. It covers:
- user sign-up and login for the `/access` console
- RPC product catalog behavior
- subscription and approval flow
- API key issuance and revocation
- current limits of the commercial/control plane
## Audience
- operators managing access to Chain 138 RPC lanes
- developers consuming RPC products through the explorer
- admins reviewing whether a product is self-service or approval-gated
## Current products
The access plane currently models three RPC products:
| Product | Slug | Provider | VMID | Access model | Billing model |
|---|---|---|---:|---|---|
| Core RPC | `core-rpc` | `besu-core` | 2101 | approval required | `contract` |
| Alltra RPC | `alltra-rpc` | `alltra` | 2102 | self-service | `subscription` |
| Thirdweb RPC | `thirdweb-rpc` | `thirdweb` | 2103 | self-service | `subscription` |
## User flow
### 1. Register or log in
Users open the explorer access console at `/access` and either:
- register with email, username, and password
- log in with email and password
Successful registration or login returns a user session token. The frontend stores this token locally and uses it for `/api/v1/access/*` endpoints.
### 2. Review products
The product catalog is public and can be read without logging in:
- `GET /api/v1/access/products`
Each product currently exposes:
- provider
- VMID
- HTTP and WebSocket URLs
- default tier
- approval requirement
- billing model
- intended use cases
- management features
### 3. Request or activate access
Logged-in users can request a subscription for a product:
- `POST /api/v1/access/subscriptions`
Behavior differs by product type:
- self-service products (`alltra-rpc`, `thirdweb-rpc`) become `active` immediately
- approval-gated products (`core-rpc`) become `pending`
### 4. Create an API key
After a subscription is active, the user can create an API key:
- `POST /api/v1/access/api-keys`
The current implementation assigns:
- default scopes per product unless the user chooses a narrower scope set
- tier-based quotas
- tier-based rate limits
- optional expiry presets or no-expiry
- optional quota override for controlled issuance
For approval-gated products, key creation is blocked until the product subscription becomes active.
### 4.1 Rotate an API key
The access console now supports rotation directly from the issued-keys list:
1. mint a replacement key with the same tier/product/scopes/quota posture
2. show the new plaintext key once
3. revoke the old key
This is intentionally simple, but it is vastly preferable to pretending revoke-and-recreate is an acceptable operator ritual with no UI support.
### 5. Revoke an API key
Users can revoke their own keys from the access console or API:
- `POST /api/v1/access/api-keys/{id}`
- `DELETE /api/v1/access/api-keys/{id}`
## Tiers and quotas
The current tier defaults are:
| Tier | Approx. monthly quota | Requests/sec | Requests/minute |
|---|---:|---:|---:|
| `free` | 10,000 | 5 | 100 |
| `pro` | 100,000 | 20 | 1,000 |
| `enterprise` | 1,000,000 | 100 | 10,000 |
These values are enforced in the explorer data model and API key records. Edge-level enforcement is still a separate infrastructure task.
## Current API surfaces
### Public endpoints
- `GET /api/v1/access/products`
### Authenticated user-session endpoints
- `GET /api/v1/access/me`
- `GET /api/v1/access/subscriptions`
- `POST /api/v1/access/subscriptions`
- `GET /api/v1/access/api-keys`
- `POST /api/v1/access/api-keys`
- `POST /api/v1/access/api-keys/{id}`
- `DELETE /api/v1/access/api-keys/{id}`
- `GET /api/v1/access/usage`
- `GET /api/v1/access/audit`
## Approval model
The present implementation distinguishes between:
- immediate activation for self-service products
- pending approval for restricted/operator-grade products
At the moment, `core-rpc` is the only modeled approval-gated product. The explorer now exposes an admin review surface for these subscriptions when the signed-in user's email is included in the `ACCESS_ADMIN_EMAILS` allowlist.
Admin-only access feeds now also include:
- `GET /api/v1/access/admin/subscriptions`
- `GET /api/v1/access/admin/audit`
### Admin allowlist
Set a comma-separated allowlist in the explorer API environment:
```bash
ACCESS_ADMIN_EMAILS=ops@example.com,infra@example.com
```
Admins can then:
- review pending restricted-product subscriptions
- approve them to `active`
- suspend them
- revoke them
This is intentionally narrow and explicit. It is not a full RBAC system, but it is far less vulgar than pretending approvals happen by osmosis.
## What this does not yet do
The access layer is intentionally honest about its current limits.
It already provides:
- user identity for the access console
- product modeling
- subscriptions
- API key lifecycle
- usage summaries from stored key records
It does not yet provide full production commercial enforcement by itself:
- no Stripe or invoice collection is wired here yet
- no x402 payment settlement is wired here yet
- no nginx/Besu/relay key validation middleware is enforced by this runbook alone
- usage is summarized from application records, not yet from live edge metering
## Recommended next operational steps
1. Wire API key validation and quota checks into the RPC edge serving `2102` and `2103`.
2. Set `ACCESS_ADMIN_EMAILS` and use the access console to review `core-rpc` requests.
3. Connect billing collection for subscription products.
4. Feed live edge traffic into `api_key_usage_logs` and quota counters.
5. Add key rotation, expiry presets, and scoped permissions in the UI.
## Edge enforcement sketch
The explorer access plane now models users, subscriptions, approvals, quotas, and API keys. To enforce that at the edge:
1. Require `X-API-Key` or `Authorization: Bearer <api-key>` at the RPC ingress for `2102` and `2103`.
2. Validate the presented key against the explorer access API or a replicated access store.
3. Reject revoked, expired, or unapproved keys.
4. Increment usage counters and/or append `api_key_usage_logs`.
5. Apply per-tier rate ceilings using the stored per-second and per-minute limits.
### Internal validation hook
The explorer API now exposes:
- `POST /api/v1/access/internal/validate-key`
- `GET /api/v1/access/internal/validate-key`
This endpoint is meant for internal ingress or relay enforcement, not browsers. It requires:
- `X-Access-Internal-Secret: <shared-secret>`
- `ACCESS_INTERNAL_SECRET` configured on the explorer API
Request body:
```json
{
"api_key": "ek_...",
"method_name": "eth_call",
"request_count": 1,
"last_ip": "203.0.113.10"
}
```
On success it returns validated key metadata and increments usage counters/log rows.
For nginx `auth_request`, use the `GET` form instead:
- `X-Access-Internal-Secret: <shared-secret>`
- `X-API-Key: ek_...` or `Authorization: Bearer ek_...`
- `X-Access-Method: eth_call`
- `X-Access-Request-Count: 1`
That flow returns `200` or `401` and also exports headers such as:
- `X-Validated-Product`
- `X-Validated-Tier`
- `X-Validated-Scopes`
- `X-Quota-Remaining`
Canonical operator references:
- [explorer-monorepo/deployment/ACCESS_EDGE_ENFORCEMENT_RUNBOOK.md](../../explorer-monorepo/deployment/ACCESS_EDGE_ENFORCEMENT_RUNBOOK.md)
- [explorer-monorepo/deployment/common/nginx-rpc-api-key-gate.conf](../../explorer-monorepo/deployment/common/nginx-rpc-api-key-gate.conf)
- [explorer-monorepo/scripts/verify-explorer-access-edge-hook.sh](../../explorer-monorepo/scripts/verify-explorer-access-edge-hook.sh)
Until that layer is wired, the explorer access plane is authoritative for management state, not yet for hard traffic enforcement.
## Thirdweb deployment note
For `thirdweb-rpc`, treat the explorer access console as:
- identity
- RPC subscription and API-key management
- future deploy permissions and audit surface
Do not treat it as if Thirdweb's dashboard alone provides private-repo deployment orchestration.
The correct model is:
1. repo access and compile happen in your CI or worker
2. the backend holds the Thirdweb secret
3. deploy happens through Thirdweb Engine/API or approved CLI flow
4. verification happens against Blockscout
Canonical reference:
- [THIRDWEB_EXPLORER_PORTAL_DEPLOYMENT_MODEL.md](../04-configuration/THIRDWEB_EXPLORER_PORTAL_DEPLOYMENT_MODEL.md)

466
docs/03-deployment/EXPLORER_COMPETITIVE_AUDIT_2026-04-09.md Normal file
View File

@@ -0,0 +1,466 @@
# Explorer Competitive Audit
Date: 2026-04-09
Scope:
- Product under review: SolaceScanScout / Chain 138 explorer in `explorer-monorepo/`
- Comparison set: Etherscan, Blockscout, Blockchain.com Explorer, Solscan, and the general top-explorer market
- Goal: translate the prior qualitative review into a decision-grade audit with a weighted rubric, a feature matrix, and a roadmap from the current `5.8/10` state to category-leading quality
## Executive Summary
The current explorer is not weak, but it is mispositioned if judged as a direct Etherscan replacement.
Today it scores:
- `5.8/10` as a public blockchain explorer product
- `7.1/10` as a Chain 138-specific explorer plus operator cockpit
The product is strongest where general explorers are weakest:
- Chain 138-specific workflows
- mission-control and operator-adjacent monitoring
- bridge, liquidity, routing, wallet, and command-center tie-ins
The product is weakest where users expect top explorers to be strongest:
- transaction depth
- address depth
- token intelligence
- contract tooling
- analytics richness
- trust, polish, and “power-user completeness”
Important interpretation:
- `10/10` means category-leading explorer quality on a normal scale
- `14/10` is not a literal score; it is a shorthand for “best-in-class explorer plus differentiated platform moat”
- The realistic path is:
1. move from `5.8/10` to `8/10` by closing obvious explorer gaps
2. move from `8/10` to `10/10` by reaching explorer-category parity
3. move from `10/10` to the “`14/10`” vision by adding unique Chain 138 and operator-native capabilities no major explorer currently combines
## Evidence Base
This audit is based on:
- Local product surface in:
- `explorer-monorepo/frontend/src/pages/`
- `explorer-monorepo/frontend/src/components/`
- `explorer-monorepo/frontend/src/services/api/`
- `explorer-monorepo/backend/api/rest/swagger.yaml`
- Recent public benchmark sources:
- Etherscan feature index: <https://info.etherscan.com/25-etherscan-features-in-2025>
- Etherscan watch list: <https://info.etherscan.com/watch-list/>
- Etherscan private tags: <https://info.etherscan.com/private-address-name-tags/>
- Blockscout verification docs: <https://docs.blockscout.com/devs/verification>
- Blockscout verification API: <https://docs.blockscout.com/devs/verification/blockscout-smart-contract-verification-api>
- Blockscout contract interaction docs: <https://docs.blockscout.com/devs/verification/interacting-with-smart-contracts>
- Blockscout watch list docs: <https://docs.blockscout.com/using-blockscout/my-account/watchlist>
- Blockchain.com Explorer: <https://www.blockchain.com/explorer>
- Blockchain.com charts: <https://www.blockchain.com/explorer/charts/n-transactions>
- Blockchain.com mempool charts: <https://www.blockchain.com/explorer/charts/mempool-size>
- Solscan analytics dashboard docs: <https://docs.solscan.io/browsing-the-site/solscan-knowledge-base/general/analytic-dashboard>
## Current Product Snapshot
The explorer already provides a real product skeleton, not just a demo:
- core navigation and route coverage
- blocks, transactions, addresses, search, tokens, and watchlist pages
- mission-control, routes, bridge, liquidity, pools, analytics, operator, and wallet surfaces
- Blockscout-backed explorer data with a Chain 138 RPC-aware fallback for missing transactions
- stronger dead-end handling than before the recent fixes
Representative local implementation points:
- navigation: `explorer-monorepo/frontend/src/components/common/Navbar.tsx`
- tx detail: `explorer-monorepo/frontend/src/pages/transactions/[hash].tsx`
- address detail: `explorer-monorepo/frontend/src/pages/addresses/[address].tsx`
- search: `explorer-monorepo/frontend/src/pages/search/index.tsx`
- tokens: `explorer-monorepo/frontend/src/pages/tokens/index.tsx`
- watchlist: `explorer-monorepo/frontend/src/pages/watchlist/index.tsx`
- analytics shell: `explorer-monorepo/frontend/src/components/explorer/AnalyticsOperationsPage.tsx`
- API contract: `explorer-monorepo/backend/api/rest/swagger.yaml`
## Weighted Score Rubric
Scoring model:
- Each category is scored from `0` to `10`
- Weighted total is the sum of `score/10 * weight`
- Maximum weighted total = `100`
- Final product score = weighted total divided by `10`
### Category Weights
| Category | Weight | What “10/10” Means |
| --- | ---: | --- |
| Core navigation and discoverability | 10 | Users can move anywhere important with near-zero dead ends or ambiguity |
| Search and entity resolution | 10 | Fast, accurate, direct, and forgiving lookup across addresses, txs, blocks, tokens, contracts, labels |
| Transaction detail depth | 15 | Rich tx page with internal txs, logs, decoded methods/events, token transfers, traces, failure diagnostics |
| Address and account intelligence | 15 | Portfolio, holdings, activity segmentation, labels, approvals, analytics, exports, and useful pivots |
| Token and asset explorer quality | 10 | Holders, transfers, metadata, market context, trust signals, supply, and route/liquidity context |
| Contract and developer tooling | 10 | Verification, source browsing, ABI UX, read/write contract, API confidence, docs, and developer trust |
| Analytics and data storytelling | 10 | Charts, dashboards, trends, protocol/network insights, and explainable metrics |
| Performance, reliability, and dead-end handling | 10 | Pages load consistently, degraded states are explicit, broken routes are rare, and fallbacks are credible |
| UX polish and trustworthiness | 10 | Feels premium, coherent, legible, and “safe to rely on” for serious work |
### Current Weighted Scores
| Category | Weight | Current Score | Weighted Result | Notes |
| --- | ---: | ---: | ---: | --- |
| Core navigation and discoverability | 10 | 7.5 | 7.5 | Good routing coverage and better onward navigation than before |
| Search and entity resolution | 10 | 7.0 | 7.0 | Strong direct matching, but broad search depth is still limited |
| Transaction detail depth | 15 | 4.5 | 6.75 | Lacks traces, decoded logs, token transfer tabs, and contract interaction context |
| Address and account intelligence | 15 | 5.0 | 7.5 | Useful basics, but not a power-user account page |
| Token and asset explorer quality | 10 | 3.5 | 3.5 | Mostly shortcut/search behavior, not a mature token explorer |
| Contract and developer tooling | 10 | 3.5 | 3.5 | Some backend signals exist, but not exposed as top-tier user tooling |
| Analytics and data storytelling | 10 | 4.5 | 4.5 | Thin dashboard, limited explanatory analytics |
| Performance, reliability, and dead-end handling | 10 | 6.5 | 6.5 | Improved meaningfully, but still not elite |
| UX polish and trustworthiness | 10 | 5.3 | 5.3 | Coherent enough, but still feels niche and partially assembled |
| Total | 100 | | 58.05 | `5.8/10` overall |
## Competitive Positioning
### Score Summary
| Product | Score | Position |
| --- | ---: | --- |
| Etherscan | 9.4 | Category leader for general EVM explorer utility |
| Strong Blockscout deployment | 8.2 | Best open-source explorer baseline, especially for teams that expose full contract tooling well |
| Solscan | 8.0 | Strong ecosystem-native explorer with better analytics and account views |
| Blockchain.com Explorer | 7.0 | Strong macro-market and network-stat presentation, weaker as an EVM contract explorer benchmark |
| SolaceScanScout current | 5.8 | Good niche product, not yet a category-leading explorer |
### Feature-By-Feature Competitor Matrix
Legend:
- `Strong` = mature, expected, competitive
- `Partial` = present but thin, inconsistent, or not power-user grade
- `Weak` = noticeable gap
- `Unique` = differentiator not commonly found in the comparison set
| Capability | SolaceScanScout | Etherscan | Strong Blockscout | Blockchain.com | Solscan | Notes |
| --- | --- | --- | --- | --- | --- | --- |
| Global nav clarity | Partial | Strong | Strong | Strong | Strong | Current nav is good, but product identity is split between explorer and ops console |
| Direct address / tx / block search | Strong | Strong | Strong | Strong | Strong | Current direct-match behavior is solid |
| Fuzzy / broad search depth | Partial | Strong | Strong | Partial | Strong | Needs better entity breadth and ranking |
| Block list and block detail | Partial | Strong | Strong | Strong | Strong | Adequate, but not insight-rich |
| Transaction detail basics | Partial | Strong | Strong | Partial | Strong | Hash, from/to, status, gas are present |
| Internal transactions / traces | Weak | Strong | Strong | Weak | Partial | Major gap |
| Decoded method and event logs | Weak | Strong | Strong | Weak | Strong | Major gap |
| Token transfer tabs in tx view | Weak | Strong | Strong | Weak | Strong | Major gap |
| Tx failure diagnostics | Partial | Strong | Partial | Weak | Partial | Current missing-tx diagnosis is a good start, but not full execution diagnostics |
| Address overview basics | Partial | Strong | Strong | Partial | Strong | Present but shallow |
| Address holdings / balances view | Weak | Strong | Strong | Partial | Strong | Major gap |
| Address analytics tab | Weak | Strong | Partial | Weak | Strong | Major gap |
| Labels / tags / private notes | Partial | Strong | Strong | Weak | Partial | Watchlist exists, but labeling workflow is light |
| Watchlist | Strong | Strong | Strong | Weak | Strong | Local watchlist is a meaningful strength |
| Token pages | Weak | Strong | Strong | Partial | Strong | Current token page is mostly search scaffolding |
| Token holders / transfers | Weak | Strong | Strong | Weak | Strong | Major gap |
| Contract verification UX | Weak | Strong | Strong | Weak | Partial | Backend hints exist, but user-facing flow is not there |
| Read / write contract | Weak | Strong | Strong | Weak | Partial | Major gap |
| API and docs trust | Partial | Strong | Strong | Partial | Strong | Swagger exists, but developer experience is not yet elite |
| Network / macro analytics | Partial | Strong | Partial | Strong | Strong | Current analytics are useful but thin |
| Chain-specific operational tooling | Unique | Weak | Partial | Weak | Partial | This is where the product can win |
| Bridge / liquidity / route intelligence | Unique | Weak | Weak | Weak | Partial | Real differentiation opportunity |
| Graceful degraded states | Partial | Strong | Partial | Strong | Strong | Improved recently, still not best-in-class |
| Overall trust and polish | Partial | Strong | Strong | Strong | Strong | The product still feels niche instead of inevitable |
## Strengths To Preserve
These are not just “nice extras”; they are the seeds of the product moat:
- Chain 138-aware transaction diagnostics
- explorer plus bridge plus liquidity plus routes plus mission-control in one place
- operator-adjacent functionality that can grow into a real command surface
- watchlist and navigation improvements that reduce dead ends
- practical bridge and route orientation for actual chain usage, not just passive observation
## Biggest Gaps
These are the highest-impact reasons the product trails top explorers:
1. Transaction pages are not yet “investigation pages.”
They show basics, but not the execution narrative users expect.
2. Address pages are not yet “entity pages.”
They do not explain what an address holds, does, approves, or influences.
3. Token pages are not yet real token explorer pages.
They are mostly routing/search entry points.
4. Contract and developer tooling are too hidden or too thin.
The product does not yet feel developer-serious in the way Etherscan and top Blockscout deployments do.
5. Analytics are present as tiles, not as a real data product.
They inform, but they do not yet reveal.
## Exact Roadmap
This roadmap is ordered by score impact, user value, and implementation leverage.
### Phase 1: Move From 5.8/10 To 8/10
Target outcome:
- eliminate the most obvious reasons a serious user bounces back to Etherscan or a raw Blockscout page
#### 1. Make transaction pages investigation-grade
Add to `transactions/[hash].tsx` and supporting APIs:
- token transfer section
- internal transactions / trace section
- decoded method name and arguments
- decoded event logs
- revert reason or failure summary when available
- expandable raw input and receipt JSON
- next/previous pivots:
- block
- from address
- to address
- created contract
Expected score lift:
- transaction detail from `4.5` to `7.5`
#### 2. Make address pages entity-grade
Add to `addresses/[address].tsx` and supporting APIs:
- token balances section
- contract vs EOA behavior summary
- incoming vs outgoing activity summary
- latest token transfers
- internal tx tab
- approvals / allowances tab if data is available
- labels / notes / watchlist metadata layer
- export CSV / JSON for recent activity
Expected score lift:
- address intelligence from `5.0` to `7.0`
#### 3. Replace the token shortcut page with real token explorer pages
Implement:
- token detail route by address
- token overview with symbol, supply, holders count, transfers count
- holders table
- recent transfers
- related pools / routes / liquidity context
- trust and provenance badges for Chain 138-curated assets
Expected score lift:
- token quality from `3.5` to `7.0`
#### 4. Tighten search into an explorer-grade finder
Add:
- entity grouping in results
- better ranking for exact match vs partial match
- support for token symbols, labels, and curated contract aliases
- “did you mean” behavior for malformed inputs
- explicit no-result fallback actions per entity type
Expected score lift:
- search from `7.0` to `8.0`
#### 5. Remove remaining trust dents
Finish:
- full dead-link audit
- all public links verified
- uniform loading / empty / error states
- ensure every page has onward navigation
- no route that returns a vague failure without recommended next action
Expected score lift:
- reliability/dead-end handling from `6.5` to `8.0`
- UX trust from `5.3` to `6.5`
### Phase 2: Move From 8/10 To 10/10
Target outcome:
- the product feels credible beside a strong Blockscout deployment and respectable beside Etherscan for daily use
#### 6. Ship contract and developer power tools
Add:
- verified contract page enhancements
- source code browser
- ABI tab
- read contract
- write contract
- verification submission UX
- contract diff / similar-match support where possible
- first-class API docs and working examples
Expected score lift:
- contract/developer tooling from `3.5` to `8.0`
#### 7. Make analytics a real product surface
Add:
- chain activity charts
- transaction throughput and gas trends
- token and bridge flows
- top contracts / top tokens / top counterparties
- route and liquidity health trends
- anomaly callouts
- downloadable snapshots for operators and analysts
Expected score lift:
- analytics from `4.5` to `8.0`
#### 8. Add account intelligence features users expect from leaders
Add:
- saved labels and notes
- notification hooks or webhook/email alerts
- approval risk surfaces
- address clustering or relationship hints
- better wallet-oriented views
Expected score lift:
- address intelligence from `7.0` to `8.5`
- UX trust from `6.5` to `8.0`
### Phase 3: Move Beyond 10/10 Into The “14/10” Vision
Target outcome:
- the explorer is no longer trying to be a smaller Etherscan
- it becomes the canonical Chain 138 intelligence and action layer
This phase should not be interpreted as “add more random features.”
It means creating a product class that top explorers do not currently own.
#### 9. Fuse explorer data with actionability
Turn pages into decision surfaces:
- from a token page:
- inspect
- route
- add to wallet
- view liquidity
- simulate swap
- from an address page:
- inspect
- label
- alert
- export
- route to related pools and contracts
- from a failed tx page:
- diagnose
- compare RPC views
- suggest likely cause
- point to next operator action
This is the product bridge between explorer and command center.
#### 10. Make Chain 138 provenance and trust visible everywhere
Add first-class trust surfaces:
- canonical asset registry badges
- official / partner / community provenance states
- deployment source and verification lineage
- bridge origin and wrapped-asset lineage
- liquidity health and route confidence
- chain-specific token warnings that are not generic scam heuristics
This is a major opportunity because generic explorers are chain-agnostic and usually weaker here.
#### 11. Build mission-control-quality chain intelligence into normal explorer pages
Expose:
- bridge health inline on affected asset pages
- route quality inline on token and pool pages
- chain head / indexing lag confidence on tx and block pages
- mempool, nonce, and propagation diagnostics for operators and power users
- public and operator views with progressive disclosure instead of separate product worlds
#### 12. Create a best-in-class Chain 138 analytics graph
Add differentiated analytics no mainstream explorer fully combines:
- token flow graph for canonical assets
- bridge flow graph
- liquidity topology graph
- route availability and degradation history
- deployment and contract registry coverage maps
- “what changed today” chain summary for operators and analysts
#### 13. Become the Chain 138 developer home, not just the public explorer
Add:
- SDK snippets from every relevant page
- verified ABI download and copy surfaces
- per-page API examples
- explorer-linked runbooks for operator-grade diagnostics
- issue reporting and metadata correction workflow
## Recommended Score Targets By Phase
| Phase | Target Score | Meaning |
| --- | ---: | --- |
| Current | 5.8 | Useful niche explorer, clearly below top-tier leaders |
| Phase 1 complete | 8.0 | Strong public explorer for daily Chain 138 use |
| Phase 2 complete | 9.5 to 10.0 | Category-leading explorer for its ecosystem |
| Phase 3 complete | “14/10” vision | Explorer plus command center plus asset-intelligence moat |
## What To Build First
If only a few streams can run immediately, the highest-yield order is:
1. transaction detail depth
2. address intelligence
3. real token pages
4. contract tooling
5. analytics overhaul
6. provenance / trust layer
7. explorer-to-action workflows
## Product Recommendation
Do not market this as “another Etherscan.”
The stronger positioning is:
- the canonical Chain 138 explorer
- the intelligence layer for Chain 138 assets, routes, and bridge state
- the command surface for both public users and serious operators
That positioning supports the “14/10” roadmap because it aims at a broader and more defensible product than a generic explorer clone.
## Short Conclusion
The explorer is already good enough to be useful.
It is not yet good enough to feel inevitable.
The shortest path to a much stronger product is not visual redesign alone.
It is deeper transaction pages, deeper address pages, real token intelligence, and contract/developer tooling.
The path to “14/10” is then to stop competing on generic parity alone and win on Chain 138-native intelligence, trust, and actionability.

512
docs/03-deployment/EXPLORER_EXECUTION_PLAN_2026-04-09.md Normal file
View File

@@ -0,0 +1,512 @@
# Explorer Execution Plan
Date: 2026-04-09
Companion documents:
- [Explorer Competitive Audit](/home/intlc/projects/proxmox/docs/03-deployment/EXPLORER_COMPETITIVE_AUDIT_2026-04-09.md)
- [Chain 138 EOA Nonce Recovery And Cancellation](/home/intlc/projects/proxmox/docs/03-deployment/CHAIN138_EOA_NONCE_RECOVERY_AND_CANCELLATION.md)
Purpose:
- convert the competitive audit into an execution-ready plan
- define the fastest path from the current `5.8/10` explorer score toward `8/10`, then `10/10`, then the “`14/10`” vision
- map roadmap items to likely implementation surfaces in this repo
## Outcome Targets
### Phase A: Reach 8/10
Success means:
- public users can investigate transactions and addresses without immediately leaving for another explorer
- tokens feel like real explorer entities, not just shortcuts
- search and degraded states feel deliberate
### Phase B: Reach 10/10
Success means:
- the explorer is credible beside strong Blockscout deployments
- developers and power users can verify, inspect, and interact with contracts from the product
- analytics become a real product surface, not a dashboard garnish
### Phase C: Reach the “14/10” vision
Success means:
- the explorer becomes the canonical Chain 138 intelligence and action layer
- public explorer, operator awareness, route intelligence, and trust/provenance are fused into one product
## Product Principles
These principles should constrain implementation decisions:
1. Every page must answer “what do I do next?”
2. Every important state must degrade clearly and honestly.
3. Deep data should be progressively disclosed, not hidden behind separate products.
4. Chain 138-specific context is not a sidecar. It is the differentiator.
5. Do not chase Etherscan parity blindly. Match the essentials, then exceed it with Chain 138-native intelligence.
## Current Leverage In The Codebase
Important existing surfaces:
- Frontend pages:
- `explorer-monorepo/frontend/src/pages/transactions/[hash].tsx`
- `explorer-monorepo/frontend/src/pages/addresses/[address].tsx`
- `explorer-monorepo/frontend/src/pages/search/index.tsx`
- `explorer-monorepo/frontend/src/pages/tokens/index.tsx`
- `explorer-monorepo/frontend/src/pages/analytics/index.tsx`
- Frontend data layer:
- `explorer-monorepo/frontend/src/services/api/transactions.ts`
- `explorer-monorepo/frontend/src/services/api/addresses.ts`
- `explorer-monorepo/frontend/src/services/api/blockscout.ts`
- `explorer-monorepo/frontend/src/services/api/missionControl.ts`
- `explorer-monorepo/frontend/src/services/api/routes.ts`
- Backend REST:
- `explorer-monorepo/backend/api/rest/transactions.go`
- `explorer-monorepo/backend/api/rest/addresses.go`
- `explorer-monorepo/backend/api/rest/search.go`
- `explorer-monorepo/backend/api/rest/mission_control.go`
- `explorer-monorepo/backend/api/rest/swagger.yaml`
- Backend GraphQL:
- `explorer-monorepo/backend/api/graphql/schema.graphql`
- `explorer-monorepo/backend/api/graphql/resolvers.go`
Important note:
- `schema.graphql` already declares `Transaction.logs` and `Transaction.trace`
- that suggests there is already a conceptual contract for deeper tx pages
- the shortest path may be to wire missing data rather than invent the entire model from scratch
## Execution Order
The highest-yield order is:
1. transaction investigation depth
2. address intelligence
3. token explorer overhaul
4. contract and developer tooling
5. analytics overhaul
6. provenance and trust layer
7. explorer-to-action workflows
This order is chosen because it:
- raises perceived quality quickly
- closes the biggest benchmark gaps first
- creates reusable backend primitives for later phases
## Workstreams
## Workstream 1: Transaction Investigation Depth
Goal:
- turn transaction pages into investigation pages
### Scope
- token transfer section
- logs section
- decoded method and arguments
- decoded event logs
- trace or internal call tree
- receipt and raw payload expansions
- richer failure and revert diagnostics
### Primary files
- `explorer-monorepo/frontend/src/pages/transactions/[hash].tsx`
- `explorer-monorepo/frontend/src/services/api/transactions.ts`
- `explorer-monorepo/frontend/src/services/api/blockscout.ts`
- `explorer-monorepo/backend/api/rest/transactions.go`
- `explorer-monorepo/backend/api/graphql/schema.graphql`
- `explorer-monorepo/backend/api/graphql/resolvers.go`
### Suggested ticket slices
1. Add transaction receipt and token transfer support to the frontend API layer.
2. Add logs and trace support to the backend API contract.
3. Render tabs or sections on the tx detail page for:
- overview
- token transfers
- logs
- trace
- raw
4. Add human-readable failure diagnostics when status is failed.
5. Add unit tests for normalized tx payloads and missing/degraded states.
### KPI
- a power user can answer “what happened in this tx?” without leaving the explorer
## Workstream 2: Address Intelligence
Goal:
- turn address pages into entity pages
### Scope
- holdings summary
- token balances list
- incoming vs outgoing segmentation
- latest token transfers
- internal tx tab
- approvals and allowances if available
- better contract-vs-EOA summaries
- saved labels and notes scaffolding
### Primary files
- `explorer-monorepo/frontend/src/pages/addresses/[address].tsx`
- `explorer-monorepo/frontend/src/services/api/addresses.ts`
- `explorer-monorepo/frontend/src/services/api/blockscout.ts`
- `explorer-monorepo/backend/api/rest/addresses.go`
- `explorer-monorepo/backend/api/rest/addresses_list.go`
- `explorer-monorepo/backend/api/graphql/schema.graphql`
### Suggested ticket slices
1. Add token balances and token transfer retrieval.
2. Add address activity summary aggregation.
3. Add contract profile surfaces:
- verified status
- label
- token/contract classification
4. Add tabs or section navigation:
- overview
- transactions
- token transfers
- internal txs
- holdings
5. Extend watchlist into metadata-backed saved entities.
### KPI
- a user can answer “what is this address and what does it hold or do?” from one page
## Workstream 3: Token Explorer Overhaul
Goal:
- replace the current token shortcut page with real token explorer functionality
### Scope
- token detail route
- token overview
- holders table
- transfers table
- supply and metadata
- liquidity and route context
- trust/provenance badges
### Primary files
- `explorer-monorepo/frontend/src/pages/tokens/index.tsx`
- new route likely needed:
- `explorer-monorepo/frontend/src/pages/tokens/[address].tsx`
- `explorer-monorepo/frontend/src/services/api/blockscout.ts`
- likely new frontend service:
- `explorer-monorepo/frontend/src/services/api/tokens.ts`
- backend:
- either new REST handlers or proxied Blockscout surfaces via `backend/api/rest/`
### Suggested ticket slices
1. Add token API service for overview, holders, and transfers.
2. Create token detail route by contract address.
3. Rework `/tokens` into:
- token discovery
- curated token index
- top token categories
4. Add liquidity and route modules on token pages.
5. Add asset provenance badges backed by the Chain 138 registry.
### KPI
- token pages become destinations, not just redirect helpers
## Workstream 4: Contract And Developer Tooling
Goal:
- make the explorer developer-serious
### Scope
- verification status
- source code browsing
- ABI access
- read contract
- write contract
- verification submission flow
- API examples and developer docs
### Primary files
- `explorer-monorepo/backend/api/rest/features.go`
- `explorer-monorepo/backend/api/rest/swagger.yaml`
- `explorer-monorepo/backend/api/rest/addresses.go`
- `explorer-monorepo/backend/api/graphql/schema.graphql`
- frontend:
- new contract sections in address pages
- likely new reusable components under `frontend/src/components/`
### Suggested ticket slices
1. Surface contract verification state on address pages.
2. Add ABI and source tabs for verified contracts.
3. Add read-contract UI for common methods.
4. Add write-contract UX only when the security model is explicit and safe.
5. Publish API examples linked from relevant explorer pages.
### KPI
- developers can inspect and interact with contracts without defaulting to a different explorer
## Workstream 5: Analytics Overhaul
Goal:
- turn analytics into a real product surface
### Scope
- chain activity charts
- gas and throughput trends
- bridge flow analytics
- token flow analytics
- liquidity and route health trends
- notable changes and anomaly callouts
### Primary files
- `explorer-monorepo/frontend/src/components/explorer/AnalyticsOperationsPage.tsx`
- `explorer-monorepo/frontend/src/pages/analytics/index.tsx`
- `explorer-monorepo/frontend/src/services/api/stats.ts`
- `explorer-monorepo/frontend/src/services/api/missionControl.ts`
- backend:
- `explorer-monorepo/backend/api/rest/stats.go`
- `explorer-monorepo/backend/api/rest/mission_control.go`
- `explorer-monorepo/backend/api/track1/bridge_status_data.go`
### Suggested ticket slices
1. Add timeseries endpoints for chain stats.
2. Add chart modules for throughput, gas, and indexing health.
3. Add route/liquidity health history.
4. Add top entities dashboards:
- top contracts
- top tokens
- top bridge corridors
5. Add downloadable snapshots for operator and analyst use.
### KPI
- analytics explain what changed, not just what exists
## Workstream 6: Provenance And Trust Layer
Goal:
- make Chain 138 trust and provenance visible everywhere
### Scope
- canonical asset indicators
- verified deployment lineage
- wrapped-asset origin
- partner or official labels
- route confidence and liquidity confidence
- public warnings for risky or unofficial assets
### Primary files
- `explorer-monorepo/backend/api/rest/config/metamask/DUAL_CHAIN_TOKEN_LIST.tokenlist.json`
- `explorer-monorepo/backend/api/rest/config/metamask/GRU_V2_PUBLIC_DEPLOYMENT_STATUS.json`
- `explorer-monorepo/backend/api/rest/config/metamask/CHAIN138_RPC_CAPABILITIES.json`
- `explorer-monorepo/frontend/src/services/api/missionControl.ts`
- token, address, route, and liquidity pages on the frontend
### Suggested ticket slices
1. Define provenance badge taxonomy.
2. Add registry-backed trust metadata API.
3. Render badges on token, address, pool, and route pages.
4. Add warning copy for unofficial or incomplete assets.
5. Add route confidence visuals tied to actual backend health.
### KPI
- users can tell which assets and routes are canonical, partner-backed, or uncertain at a glance
## Workstream 7: Explorer-To-Action Flows
Goal:
- make the explorer actionable, not just informative
### Scope
- add-to-wallet from token and contract pages
- route or swap simulation from token pages
- liquidity pivots from token and pool pages
- mission-control pivots from failed tx or route pages
- operator-safe diagnostics for advanced users
### Primary files
- `explorer-monorepo/frontend/src/components/wallet/AddToMetaMask.tsx`
- `explorer-monorepo/frontend/src/services/api/routes.ts`
- `explorer-monorepo/frontend/src/services/api/liquidity.ts`
- `explorer-monorepo/frontend/src/services/api/planner.ts`
- route, pool, token, transaction, and address pages
### Suggested ticket slices
1. Add “next action” modules to token pages.
2. Add route simulation hooks where data exists.
3. Add tx troubleshooting suggestions for degraded states.
4. Add operator-depth panels with progressive disclosure.
### KPI
- users can move from understanding to action without changing products
## Milestone Plan
## Milestone M1: Investigation Core
Goal:
- complete Workstreams 1 and 2 at baseline depth
Expected score movement:
- `5.8` to about `7.2`
Definition of done:
- transaction pages have logs, transfers, and trace or internal-call context
- address pages have holdings and transfer depth
- all degraded states have explicit next actions
## Milestone M2: Real Token Explorer
Goal:
- complete Workstream 3
Expected score movement:
- `7.2` to about `8.0`
Definition of done:
- tokens have detail pages
- holders and transfers are visible
- Chain 138 token trust metadata is visible
## Milestone M3: Developer Credibility
Goal:
- complete Workstream 4
Expected score movement:
- `8.0` to about `8.8`
Definition of done:
- verified contracts are first-class entities
- ABI/source/read-contract are present
- API docs link directly from the explorer
## Milestone M4: Analytics And Trust
Goal:
- complete Workstreams 5 and 6
Expected score movement:
- `8.8` to about `9.6`
Definition of done:
- analytics show trends and top entities
- provenance is visible across tokens, routes, and addresses
- trust and health are obvious, not buried
## Milestone M5: Action Layer
Goal:
- complete Workstream 7
Expected score movement:
- `9.6` to the “`14/10`” differentiated vision
Definition of done:
- token, address, tx, and route pages guide the user into the right action
- mission-control quality intelligence is embedded into normal explorer workflows
- the explorer becomes the operational home of Chain 138, not just its index
## Suggested Initial Backlog
These are the first ten tickets I would create immediately.
1. Add normalized transaction receipt, logs, and token transfer models in `frontend/src/services/api/transactions.ts`.
2. Extend tx detail UI in `frontend/src/pages/transactions/[hash].tsx` with overview, logs, transfers, and raw-data sections.
3. Wire backend tx trace or internal transaction support through `backend/api/rest/transactions.go` and `backend/api/graphql/`.
4. Extend `frontend/src/services/api/addresses.ts` to fetch holdings, token transfers, and richer counters.
5. Rebuild `frontend/src/pages/addresses/[address].tsx` into a tabbed entity page.
6. Introduce `frontend/src/services/api/tokens.ts` and create `frontend/src/pages/tokens/[address].tsx`.
7. Replace the current `/tokens` page with a curated token explorer index and top-asset entry points.
8. Add contract verification and ABI/source visibility to address pages.
9. Expand `AnalyticsOperationsPage.tsx` with timeseries charts and top-entity modules.
10. Define and expose Chain 138 provenance badges from backend registry sources.
## Teaming Recommendation
If work is split across multiple engineers, divide by write scope:
- Engineer 1: transaction and address depth
- Engineer 2: tokens and provenance
- Engineer 3: contract/developer tooling
- Engineer 4: analytics and route/liquidity intelligence
This reduces merge overlap and aligns with the biggest score lifts.
## Risks
1. UX sprawl.
If too many new surfaces are added without clear hierarchy, the explorer will feel more confusing, not more powerful.
2. Data inconsistency.
If REST, GraphQL, Blockscout proxies, and RPC fallbacks disagree, trust will erode quickly.
3. Security exposure.
Read/write contract and operator-depth tooling must be introduced carefully.
4. Product identity drift.
If the team chases generic parity only, it may lose the Chain 138-specific advantage that makes the explorer special.
## Recommendation
The best possible outcome is not just a prettier explorer.
It is:
- an investigator-grade explorer
- a trusted Chain 138 asset and route intelligence layer
- an action surface for both public users and advanced operators
The immediate move is to start Workstreams 1 through 3, because that is the fastest route to a visibly stronger product and the most credible path toward the larger “`14/10`” vision.

104
docs/03-deployment/EXPLORER_PUBLIC_REVIEW_CLOSURE_MATRIX_2026-04-09.md Normal file
View File

@@ -0,0 +1,104 @@
# Explorer Public Review Closure Matrix
Last updated: 2026-04-09
Scope: public unauthenticated explorer surface on `https://blockscout.defi-oracle.io`
Method:
- local code review in `explorer-monorepo/frontend`
- live verification against public HTML and JSON responses
- status buckets:
- `Resolved`
- `Partial`
- `Open`
## Matrix
| # | Review item | Status | What changed | Live evidence |
|---|---|---|---|---|
| 1 | Core explorer data missing on homepage / primary pages | Resolved | Added server-first data to `/`, `/blocks`, `/transactions`, `/addresses`, `/wallet`, `/tokens`, `/search` and seeded analytics/routes/system/operator/weth. | `/`, `/blocks`, `/transactions`, `/addresses`, `/wallet`, `/search?q=cUSDT`, `/analytics`, `/routes`, `/system`, `/operator`, `/weth` now ship real public HTML content and `__NEXT_DATA__` payloads. |
| 2 | Major routes are empty shells | Resolved | Added substantive public first-paint content to `/bridge`, `/operations`, `/analytics`, `/routes`, `/system`, `/operator`, `/weth`. | Route HTML now includes section titles and seeded data instead of chrome-only output. |
| 3 | Command center / visual map instability | Resolved | Added runtime Mermaid fallback plus an explicit no-diagram fallback path into the main operational surfaces. | `/chain138-command-center.html` now explains the fallback behavior and links directly to `/operations`, `/bridge`, `/routes`, `/system`, and `/operator` if diagram rendering is unavailable. |
| 4 | Product over-promises relative to public functionality | Resolved | Restored public data planes on the flagship explorer routes and aligned public docs/marketing copy around the now-working surfaces. | Homepage, blocks, transactions, addresses, wallet, tokens, search, bridge, routes, analytics, operations, system, operator, and weth routes all render substantive public HTML. |
| 5 | Token discovery story incomplete | Resolved | `/tokens` now prerenders curated token content; `/wallet` now receives real token-list metadata; `/search` direct token flows render on first paint. | `/tokens`, `/wallet`, and `/search?q=cUSDT` expose token data in public HTML. |
| 6 | Wallet messaging contradicted runtime fallback state | Resolved | Wallet page now seeds networks, token list, and capabilities from public config endpoints instead of first-painting fallback/unknown/zero states. | `/wallet` no longer shows `frontend fallback values`, `unknown`, or `0 token entries`. |
| 7 | Token-list endpoint unhealthy or empty | Resolved | Confirmed endpoint health and connected it properly to wallet/tokens/search first-paint flows. | `GET /api/config/token-list` returns structured JSON; wallet/tokens/search consume it publicly. |
| 8 | Product identity still fragmented | Resolved | Standardized the public-facing story around `SolaceScan`, `Chain 138 Explorer by DBIS`, and `DBIS / Defi Oracle`, then added an explicit operator-and-domains explanation in docs, footer, and legal pages. | `/docs`, footer copy, `/privacy.html`, `/terms.html`, `/acknowledgments.html`, and `/api/config/capabilities` now explain how `blockscout.defi-oracle.io` and `explorer.d-bis.org` fit the same explorer surface. |
| 9 | Tone too snarky / unprofessional | Resolved | Removed the remaining visible sarcastic and self-conscious phrasing from the main public pages, docs, and supporting copy. | Public home/docs/legal/footer copy is now neutral and operator-grade on the live site. |
| 10 | Docs too abstract / doctrinal | Resolved | Added concrete verification paths, live token examples, search examples, and explicit explorer-page pivots so the docs demonstrate features instead of describing them in isolation. | `/docs`, `/docs/gru`, and `/docs/transaction-review` now contain live-example links such as `Search cUSDT`, direct GRU token pages, and transaction-review verification steps. |
| 11 | “Transaction Compliance Matrix” too risky | Resolved | Renamed the visible feature to `Transaction Review Matrix`, softened its grading language, and made `/docs/transaction-review` canonical while keeping the old slug as a redirect. | `/docs/transaction-compliance` now redirects to `/docs/transaction-review`, which renders `Transaction Review Matrix` and stronger non-regulatory disclaimers. |
| 12 | IA improved, but leaf pages unfinished | Resolved | Public leaf pages that were still visibly hollow are now server-seeded and content-bearing. | `/analytics`, `/routes`, `/bridge`, `/operations`, `/system`, `/operator`, `/weth` all render meaningful public page content. |
| 13 | Decorative shortcuts without productive data | Resolved | Restored the underlying data surfaces so shortcut/navigation patterns lead into working explorer pages. | Blocks, transactions, addresses, search, tokens, analytics, and routes now first-paint with useful data. |
| 14 | Legal pages too thin | Resolved | Expanded privacy and terms with operator identity, wallet interactions, logging posture, third-party infrastructure categories, acceptable use, service boundaries, dispute interpretation, and change-management language. | `/privacy.html`, `/terms.html`, and `/acknowledgments.html` now read as real policy pages rather than placeholders, while remaining appropriately scoped to a public explorer. |
| 15 | Acknowledgments may overstate integration maturity | Resolved | Added explicit qualification that inclusion does not imply every related public workflow is fully implemented on every page. | `/acknowledgments.html` now contains that qualifier. |
## Files Changed In This Closure Pass
Frontend public-first data and route work:
- `explorer-monorepo/frontend/src/pages/blocks/index.tsx`
- `explorer-monorepo/frontend/src/pages/transactions/index.tsx`
- `explorer-monorepo/frontend/src/pages/addresses/index.tsx`
- `explorer-monorepo/frontend/src/pages/wallet/index.tsx`
- `explorer-monorepo/frontend/src/pages/tokens/index.tsx`
- `explorer-monorepo/frontend/src/pages/search/index.tsx`
- `explorer-monorepo/frontend/src/pages/analytics/index.tsx`
- `explorer-monorepo/frontend/src/pages/routes/index.tsx`
- `explorer-monorepo/frontend/src/pages/system/index.tsx`
- `explorer-monorepo/frontend/src/pages/operator/index.tsx`
- `explorer-monorepo/frontend/src/pages/weth/index.tsx`
- `explorer-monorepo/frontend/src/utils/publicExplorer.ts`
Component and copy cleanup:
- `explorer-monorepo/frontend/src/components/home/HomePage.tsx`
- `explorer-monorepo/frontend/src/components/access/AccessManagementPage.tsx`
- `explorer-monorepo/frontend/src/components/wallet/AddToMetaMask.tsx`
- `explorer-monorepo/frontend/src/components/explorer/AnalyticsOperationsPage.tsx`
- `explorer-monorepo/frontend/src/components/explorer/RoutesMonitoringPage.tsx`
- `explorer-monorepo/frontend/src/components/explorer/SystemOperationsPage.tsx`
- `explorer-monorepo/frontend/src/components/explorer/OperatorOperationsPage.tsx`
- `explorer-monorepo/frontend/src/components/explorer/WethOperationsPage.tsx`
- `explorer-monorepo/frontend/src/pages/docs/index.tsx`
- `explorer-monorepo/frontend/src/pages/docs/gru.tsx`
- `explorer-monorepo/frontend/src/pages/docs/transaction-compliance.tsx`
- `explorer-monorepo/frontend/src/pages/transactions/[hash].tsx`
- `explorer-monorepo/frontend/src/pages/addresses/[address].tsx`
- `explorer-monorepo/frontend/src/pages/tokens/[address].tsx`
- `explorer-monorepo/frontend/src/utils/transactionCompliance.ts`
Static/legal/docs cleanup:
- `explorer-monorepo/frontend/public/privacy.html`
- `explorer-monorepo/frontend/public/terms.html`
- `explorer-monorepo/frontend/public/acknowledgments.html`
- `explorer-monorepo/frontend/public/docs.html`
- `explorer-monorepo/frontend/public/explorer-spa.js`
Explorer config metadata:
- `explorer-monorepo/backend/api/rest/config/metamask/DUAL_CHAIN_NETWORKS.json`
- `explorer-monorepo/backend/api/rest/config/metamask/CHAIN138_RPC_CAPABILITIES.json`
## Remaining Honest Gaps
No items from the 15-point public review remain open or partially closed in this matrix.
What remains after closure is normal product evolution rather than unresolved review debt:
1. Companion properties can still be refined further.
The domain/operator story is now explicit and coherent, but companion surfaces can always be streamlined more over time.
2. Policies can always deepen.
The legal pages now meet the needs of this public explorer review, while still leaving room for a broader enterprise policy program if the service scope grows.
3. Docs can keep getting richer.
The guides are now example-led and verifiable, but screenshots, video captures, or deeper walkthroughs would be optional enhancements rather than closure blockers.
## Closure Summary
This pass closes the entire second-pass public review:
- the explorer now behaves like an explorer on first paint
- the previously hollow top-nav routes now render substantive public content
- wallet/token/search public flows are operationally credible
- the public legal/identity surface is cleaner and less contradictory
- the riskiest “compliance” terminology has been softened into a review model
- the docs now prove the product with live examples instead of describing it from a distance
- the command-center companion page now has a safer fallback story
The remaining work from here is iterative product improvement, not unresolved public-review debt.

10
docs/03-deployment/FINAL_UNBLOCK_CHECKLIST_MAINNET_BSC.md
View File

@@ -75,6 +75,12 @@ There is no hardcoded repo target for relay inventory, so use a small bootstrap
- Current: `0.002634280582011289 WETH`
- **Top up:** `0.007365719417988711 WETH`
Operator check / unpause helpers:
- Read-only lane readiness: [`check-mainnet-weth-relay-lane.sh`](../../scripts/verify/check-mainnet-weth-relay-lane.sh)
- Bridge top-up plan/apply: [`fund-mainnet-relay-bridge.sh`](../../scripts/bridge/fund-mainnet-relay-bridge.sh)
- Off-chain worker unpause plan/apply: [`unpause-mainnet-weth-relay-lane.sh`](../../scripts/deployment/unpause-mainnet-weth-relay-lane.sh)
### 5. BSC deployer gas reserve
Repo recommendation: keep **`0.06 BNB`** on the deployer.
@@ -112,10 +118,10 @@ If you are operating the BSC relay flow from `services/relay/.env.bsc`, top up t
- `MAINNET_CCIP_WETH9_BRIDGE`
- `MAINNET_CCIP_WETH10_BRIDGE`
3. Fund Mainnet LP to `1 ETH` and `0.5 WETH`.
4. Fund Mainnet relay bridge to `0.01 WETH` minimum.
4. Fund Mainnet relay bridge to at least the largest intended direct `138 -> Mainnet` send amount, with `0.01 WETH` as the current working floor.
5. Fund BSC deployer to `0.06 BNB`.
6. Fund BSC CCIP bridges to `10 LINK` each.
7. If relay mode is used on BSC, fund the BSC relay bridge with at least `0.01 WETH`.
7. If relay mode is used on BSC, fund the BSC relay bridge to at least the largest intended direct `138 -> BSC` send amount, with `0.01 WETH` as the current working floor.
8. Set `BOND_MANAGER_MAINNET` and `CHALLENGE_MANAGER_MAINNET` in `.env`.
9. Run the full live bridge test from [`live-test-trustless-bridge.sh`](../../smom-dbis-138/scripts/deployment/live-test-trustless-bridge.sh).

174
docs/03-deployment/GAS_NATIVE_C_STAR_CW_ROLLOUT_RUNBOOK.md Normal file
View File

@@ -0,0 +1,174 @@
# Gas-Native `c*` / `cW*` Rollout Runbook
**Purpose:** Safely activate the Wave 1 gas-native compliant families without breaking existing live corridors. This runbook covers the operator sequence for registry, env, API publication, bridge readiness, and venue exposure.
## 1. Scope
Wave 1 families:
- `eth_mainnet` on Ethereum Mainnet
- `eth_l2` on Optimism, Arbitrum One, and Base
- `bnb` on BSC
- `pol` on Polygon
- `avax` on Avalanche C-Chain
- `cro` on Cronos
- `xdai` on Gnosis Chain
- `celo` on Celo
- `wemix` on Wemix
Canonical gas-family assets live on Chain 138 as `c*`. Mirrored assets live on destination chains as `cW*`. DODO PMM is the compliant edge venue; Uniswap v3 is the mandatory reference venue; Balancer and Curve are same-window only where the protocol exists and the basket design is valid; 1inch is routing exposure only after underlying venues are live.
## 2. Safety Rules
- Do not overwrite working bridge env or live pool addresses with placeholders.
- Do not mark Balancer, Curve, or 1inch live until the required DODO and Uniswap lanes are already funded and indexed.
- Do not promote a lane from `hybrid_cap` to `strict_escrow` by renaming symbols or swapping token identities. Promotion is policy and verifier wiring, not a registry rename.
- Keep `eth_mainnet` and `eth_l2` isolated. Cross-lane redemption is only allowed inside the `eth_l2` family.
## 3. Config Sources
- Registry: [`config/token-mapping-multichain.json`](../../config/token-mapping-multichain.json)
- Runtime transport overlay: [`config/gru-transport-active.json`](../../config/gru-transport-active.json)
- Public deployment graph: [`cross-chain-pmm-lps/config/deployment-status.json`](../../cross-chain-pmm-lps/config/deployment-status.json)
- Publication runtime: [`smom-dbis-138/services/token-aggregation/.env.example`](../../smom-dbis-138/services/token-aggregation/.env.example)
## 4. Operator Sequence
1. Confirm config integrity.
```bash
bash scripts/validation/validate-config-files.sh
node cross-chain-pmm-lps/scripts/validate-deployment-status.cjs
```
2. Sync publication env for token-aggregation without touching live operator RPCs.
```bash
bash scripts/deploy-token-aggregation-for-publication.sh /tmp/token-aggregation-gas-rollout
```
The deploy helper now reads `config/gru-transport-active.json` and syncs every referenced `env` key into the published `.env`, including the gas-family `CW_GAS_*` and `CW_MAX_OUTSTANDING_*` keys.
It also publishes `CW_ASSET_RESERVE_VERIFIER_DEPLOYED_CHAIN138` as a neutral reference to the deployed generic gas verifier without auto-activating the live gas-verifier envs.
When you want the non-secret gas runtime scaffold locally, run `bash scripts/verify/print-gas-runtime-env-canonical.sh`. It derives per-lane caps from the registry and uses the live canonical `totalSupply()` as the zero-supply baseline for outstanding / escrowed defaults.
3. Verify the explorer-facing publication surface.
```bash
SKIP_BRIDGE_ROUTES=0 SKIP_BRIDGE_PREFLIGHT=0 SKIP_GAS_REGISTRY=0 \
bash scripts/verify/check-public-report-api.sh https://explorer.d-bis.org
bash scripts/verify/check-token-aggregation-chain138-api.sh
ALLOW_BLOCKED=1 bash scripts/verify/check-gru-transport-preflight.sh https://explorer.d-bis.org
```
4. Inspect gas-lane deployment state before activating routing.
```bash
bash scripts/verify/check-gas-public-pool-status.sh
bash scripts/verify/check-gas-rollout-deployment-matrix.sh
```
The gas rollout verifier summarizes:
- runtime-ready vs blocked gas transport pairs
- strict-escrow vs hybrid-cap lanes
- DODO wrapped-native and stable-quote pool coverage
- Uniswap v3 reference visibility
- Balancer / Curve support flags
- 1inch routing visibility
- missing env refs or supply-accounting blockers per lane
The deployment matrix adds the contract-level audit:
- whether the canonical gas token actually exists on Chain 138
- whether the mirrored gas token actually exists on the destination chain
- whether the currently loaded L1/L2 bridge refs resolve to bytecode
- whether the gas verifier and vault refs resolve to bytecode
- the next deploy or config command for each blocked lane
Current live baseline as of 2026-04-05:
- `CWAssetReserveVerifier` is deployed on Chain 138 at `0xbf26a679586663f87f3bf3f52c79479b8aa8d854`, but it is not attached to the live L1 bridge yet.
- All 9 Wave 1 canonical gas-family tokens are deployed on Chain 138.
- 10 of 11 public mirrors are deployed and have bridge `MINTER_ROLE` / `BURNER_ROLE` granted.
- The only undeployed mirror is `cWWEMIX` on chain `1111`.
- `wemix` is now carried as **deferred staged metadata** in the registry, not an active transport lane. The active gas rollout matrix therefore covers `10` active transport pairs and `1` deferred pair.
- `scripts/verify/check-gas-rollout-deployment-matrix.sh` now also probes each active lane's destination CCIP selector on the live Chain 138 bridge. Current live status is `0/10` destinations wired and the observed Chain 138 bridge exposes only `admin` + `destinations(...)` read paths, so it is reported as `partial_destination_only` rather than full accounting introspection.
- `scripts/deployment/print-gas-l1-destination-wiring-commands.sh` prints the exact `configureDestination(address,uint64,address,bool)` commands still needed for the 10 active non-Wemix gas lanes, using the selector metadata resolved from the active GRU transport overlay.
- `scripts/deployment/run-gas-l1-destination-wiring.sh` wraps those same 10 commands into a single operator-ready runner. It is echo-only by default and only broadcasts when `EXECUTE_GAS_L1_DESTINATIONS=1` is set.
5. Only after the verifier is clean for a lane, activate public routing in this order:
1. DODO wrapped-native pool live
2. DODO stable-quote pool live
3. Uniswap v3 reference live
4. Balancer and Curve when supported and funded
5. 1inch routing visibility
## 5. Required Env Groups
Publication and operator surfaces should provide:
- `CHAIN138_L1_BRIDGE`
- `CW_BRIDGE_*` for every enabled destination, including `CW_BRIDGE_WEMIX`
- `CW_RESERVE_VERIFIER_CHAIN138`
- `CW_STABLECOIN_RESERVE_VAULT`
- `CW_RESERVE_SYSTEM`
- `CW_GAS_STRICT_ESCROW_VERIFIER_CHAIN138`
- `CW_GAS_HYBRID_CAP_VERIFIER_CHAIN138`
- `CW_GAS_ESCROW_VAULT_CHAIN138`
- `CW_GAS_TREASURY_SYSTEM`
- `CW_MAX_OUTSTANDING_*`
- `CW_GAS_OUTSTANDING_*`
- `CW_GAS_ESCROWED_*`
- `CW_GAS_TREASURY_BACKED_*`
- `CW_GAS_TREASURY_CAP_*`
For publication-only environments, zero-valued gas accounting is acceptable when the lane has no outstanding supply yet. Live operators should replace those zeros with authoritative values before enabling routing or claiming runtime readiness.
`CW_ASSET_RESERVE_VERIFIER_DEPLOYED_CHAIN138` is safe to publish as a neutral reference, but it does not mean the live bridge has been attached to that verifier yet.
## 6. Lane Promotion Checklist
To promote a gas lane from `hybrid_cap` to `strict_escrow`:
1. Deploy or confirm the strict escrow verifier.
2. Confirm wrapped-native custody or equivalent escrow source.
3. Update the verifier and accounting env refs.
4. Keep the same `familyKey`, canonical symbol, mirrored symbol, and pool addresses.
5. If you use the generic verifier path, it is valid to point both `CW_GAS_STRICT_ESCROW_VERIFIER_CHAIN138` and `CW_GAS_HYBRID_CAP_VERIFIER_CHAIN138` at the same deployed `CWAssetReserveVerifier` instance and configure the token-specific rules inside that verifier.
5. Re-run:
```bash
bash scripts/validation/validate-config-files.sh
node cross-chain-pmm-lps/scripts/validate-deployment-status.cjs
bash scripts/verify/check-gas-public-pool-status.sh
bash scripts/verify/check-gru-transport-preflight.sh https://explorer.d-bis.org
```
## 7. Manual / Live-Only Steps
The repo and live deploys now cover the token-contract layer. These steps still require operator execution:
- fund DODO and Uniswap lanes
- fund the deployer with at least `0.4 WEMIX`, deploy the Wemix CCIP bridges, and set `CW_BRIDGE_WEMIX` before deploying the Wemix mirror
- replace the remaining Wemix placeholder mirror address
- decide when to attach the generic gas verifier to the live L1 bridge
- promote Balancer / Curve / 1inch only after venue proof
- wire live treasury and escrow accounting feeds
- perform fork or live-dry-run execution for each new lane
## 8. Related Commands
```bash
# Local rollout integrity
bash scripts/validation/validate-config-files.sh
node cross-chain-pmm-lps/scripts/validate-deployment-status.cjs
# Publication health
SKIP_BRIDGE_ROUTES=0 SKIP_BRIDGE_PREFLIGHT=0 SKIP_GAS_REGISTRY=0 \
bash scripts/verify/check-public-report-api.sh https://explorer.d-bis.org
# Runtime readiness
bash scripts/verify/check-gru-transport-preflight.sh https://explorer.d-bis.org
bash scripts/verify/check-gas-public-pool-status.sh
```

214
docs/03-deployment/GRU_V2_BLOCKER_RESOLUTION_MATRIX.md Normal file
View File

@@ -0,0 +1,214 @@
# GRU V2 Blocker Resolution Matrix
**Last Updated:** 2026-04-04
**Purpose:** Canonical remediation map for the remaining public-network GRU v2 blockers. This translates the blocker list from the queue/status verifiers into concrete operator actions, dependencies, and exit criteria.
---
## Canonical sources
- Queue verifier: `bash scripts/verify/check-gru-v2-deployment-queue.sh`
- Public status verifier: `bash scripts/verify/check-gru-v2-public-protocols.sh`
- Funding verifier: `bash scripts/verify/check-gru-v2-deployer-funding-status.sh`
- Explorer queue JSON: `https://explorer.d-bis.org/config/GRU_V2_DEPLOYMENT_QUEUE.json`
- Explorer status JSON: `https://explorer.d-bis.org/config/GRU_V2_PUBLIC_DEPLOYMENT_STATUS.json`
The queue JSON now includes a machine-readable `resolutionMatrix` section that mirrors this document.
---
## Resolution matrix
### 1. Missing public `cW*` suites on desired EVM targets
**Current blocker**
- `Wemix`
**Resolution**
1. Deploy the full public `cW*` core suite on the missing destination chain.
2. Grant bridge mint/burn roles and mark the corridor live in `cross-chain-pmm-lps/config/deployment-status.json`.
3. Update token lists and explorer config.
4. Re-run `check-cw-evm-deployment-mesh.sh` and `check-cw-public-pool-status.sh`.
**Runbooks / scripts**
- [CW_DEPLOY_AND_WIRE_RUNBOOK.md](../07-ccip/CW_DEPLOY_AND_WIRE_RUNBOOK.md)
- [PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK.md](PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK.md)
- [run-cw-remaining-steps.sh](/home/intlc/projects/proxmox/scripts/deployment/run-cw-remaining-steps.sh)
- [check-cw-evm-deployment-mesh.sh](/home/intlc/projects/proxmox/scripts/verify/check-cw-evm-deployment-mesh.sh)
**Exit criteria**
- `Wemix` has a non-zero `cW*` suite recorded
- `bridgeAvailable=true`
- they no longer appear in the queue blocker list
### 2. Wave 1 transport still pending
**Current blocker**
- `EUR`
- `JPY`
- `GBP`
- `AUD`
- `CAD`
- `CHF`
- `XAU`
**Resolution**
1. Enable bridge controls and supervision policy for each Wave 1 canonical asset on Chain 138.
2. Set max-outstanding / capacity controls.
3. Promote the canonical symbols into `config/gru-transport-active.json`.
4. Re-run the GRU rollout and readiness verifiers before attaching public liquidity.
**Runbooks / scripts**
- [GRU_GLOBAL_PRIORITY_CROSS_CHAIN_ROLLOUT.md](../04-configuration/GRU_GLOBAL_PRIORITY_CROSS_CHAIN_ROLLOUT.md)
- [GRU_TRANSPORT_ACTIVE_JSON.md](../04-configuration/GRU_TRANSPORT_ACTIVE_JSON.md)
- [check-gru-global-priority-rollout.sh](/home/intlc/projects/proxmox/scripts/verify/check-gru-global-priority-rollout.sh)
- [check-gru-v2-chain138-readiness.sh](/home/intlc/projects/proxmox/scripts/verify/check-gru-v2-chain138-readiness.sh)
**Exit criteria**
- `Wave 1 transport pending` reaches `0`
- the seven non-USD Wave 1 assets move from `canonical_only` to `live_transport`
### 3. First-tier Wave 1 public `cW*` rollout still incomplete
**Current blocker**
- `110` Wave 1 first-tier pools are planned
- `1` is recorded live
**Current nuance**
- The first Mainnet `DODO PMM` bootstrap pools are now recorded live for `cWUSDT/USDC`, `cWUSDC/USDC`, `cWUSDT/USDT`, and `cWUSDC/USDT`
- The first non-USD Wave 1 row is now also live on Mainnet: `cWEURC / USDC` → `0x0bC750F9c6DbDcd76B205695A356491b1B9ef098`
- That initial seed does **not** close the Wave 1 blocker, because the Wave 1 queue still spans the broader non-USD wrapped set across the tracked public mesh
**Resolution**
1. Extend the first-tier `cW* / hub stable` pairs from `cross-chain-pmm-lps/config/pool-matrix.json` beyond the seeded Mainnet `cWEURC / USDC` row.
2. Seed the pools with initial liquidity.
3. Write pool addresses back into `cross-chain-pmm-lps/config/deployment-status.json`.
4. Re-run the public pool verifier and only then surface those venues as live.
**Runbooks / scripts**
- [SINGLE_SIDED_LPS_PUBLIC_NETWORKS_RUNBOOK.md](SINGLE_SIDED_LPS_PUBLIC_NETWORKS_RUNBOOK.md)
- [PMM_FULL_MESH_AND_PUBLIC_SINGLE_SIDED_PLAN.md](PMM_FULL_MESH_AND_PUBLIC_SINGLE_SIDED_PLAN.md)
- [pool-matrix.json](/home/intlc/projects/proxmox/cross-chain-pmm-lps/config/pool-matrix.json)
- [check-cw-public-pool-status.sh](/home/intlc/projects/proxmox/scripts/verify/check-cw-public-pool-status.sh)
**Exit criteria**
- `deployment-status.json` records expanding first-tier non-USD `pmmPools`
- `check-cw-public-pool-status.sh` reports expanding public pool coverage beyond the current Mainnet seed
### 4. Public protocols still queued / partial
**Current blocker**
- `Uniswap v3`
- `DODO PMM` is now partially live through the Mainnet bootstrap pool wave
- `Balancer`
- `Curve 3`
- `1inch`
**Resolution**
1. **Stage 1:** activate `Uniswap v3` and `DODO PMM` after first-tier public pools exist.
2. **Stage 2:** activate `Balancer` and `Curve 3` after first-tier stable liquidity is already live.
3. **Stage 3:** expose `1inch` only after underlying pools, routing/indexer visibility, and public capability wiring are in place.
**Runbooks / scripts**
- [GRU_V2_PUBLIC_PROTOCOL_DEPLOYMENT_STATUS.md](../11-references/GRU_V2_PUBLIC_PROTOCOL_DEPLOYMENT_STATUS.md)
- [gru-v2-public-protocol-rollout-plan.json](/home/intlc/projects/proxmox/config/gru-v2-public-protocol-rollout-plan.json)
- [check-gru-v2-public-protocols.sh](/home/intlc/projects/proxmox/scripts/verify/check-gru-v2-public-protocols.sh)
**Exit criteria**
- public protocol status reports non-zero active `cW*` pools for the staged venues
### 5. Global-priority backlog still open
**Current blocker**
- `29` backlog assets remain outside the live manifest
**Resolution**
1. Finish Wave 1 transport and first-tier liquidity first.
2. Add each backlog asset to the canonical + wrapped manifest/rollout surfaces.
3. Deploy contracts, extend the public pool matrix, and promote transport the same way as Wave 1.
**Runbooks / scripts**
- [GRU_GLOBAL_PRIORITY_CROSS_CHAIN_ROLLOUT.md](../04-configuration/GRU_GLOBAL_PRIORITY_CROSS_CHAIN_ROLLOUT.md)
- [gru-global-priority-currency-rollout.json](/home/intlc/projects/proxmox/config/gru-global-priority-currency-rollout.json)
- [gru-iso4217-currency-manifest.json](/home/intlc/projects/proxmox/config/gru-iso4217-currency-manifest.json)
- [check-gru-global-priority-rollout.sh](/home/intlc/projects/proxmox/scripts/verify/check-gru-global-priority-rollout.sh)
**Exit criteria**
- backlog count reaches `0`
### 6. Solana remains planned / relay-dependent
**Current blocker**
- `Solana`
**Resolution**
1. Define the Solana-side token/program model first.
2. Implement the relay/program path and authority model.
3. Add a dedicated verifier before promoting Solana into any live transport or explorer surface.
**Runbooks / docs**
- [ADDITIONAL_PATHS_AND_EXTENSIONS.md](../04-configuration/ADDITIONAL_PATHS_AND_EXTENSIONS.md)
- [GRU_GLOBAL_PRIORITY_CROSS_CHAIN_ROLLOUT.md](../04-configuration/GRU_GLOBAL_PRIORITY_CROSS_CHAIN_ROLLOUT.md)
**Exit criteria**
- Solana has a real relay/program implementation and is no longer only a desired target
### 7. Deployer wallet funding still needs top-ups on some public deployment surfaces
**Current blocker**
- Arbitrum deploy gas: below the repo threshold
- Mainnet gas: very low for follow-on public deployment work
- Mainnet `WETH9` public fan-out is currently blocked at the live source bridge/router path
- Chain 138 public reads must use the stable public RPC (`rpc-http-pub.d-bis.org`) because `rpc.public-0138.defi-oracle.io` is currently returning `502`
**Resolution**
1. Top up Arbitrum gas before any new Arbitrum deployment branch.
2. Top up Mainnet gas before beginning additional public pool/protocol deployment work there.
3. Repair or replace the current Mainnet source bridge path before treating `Mainnet ->` any public-chain `WETH9` corridor as live. The latest source attempt from `MAINNET_CCIP_WETH9_BRIDGE=0xc9901ce2Ddb6490FAA183645147a87496d8b20B6` failed on tx `0x97df657f0e31341ca852666766e553650531bbcc86621246d041985d7261bb07`, and tracing shows the revert occurs inside Mainnet router `0x80226fc0Ee2b096224EeAc085Bb9a8cba1146f7D` before any bridge event is emitted. Read-only `calculateFee()` preflights also currently revert for the tracked selectors `BSC`, `Avalanche`, `Gnosis`, `Cronos`, `Celo`, `Polygon`, `Arbitrum`, `Optimism`, and `Base`.
4. Keep using the stable Chain 138 public RPC for funding reads until the alternate public endpoint is healthy again.
**Runbooks / scripts**
- [GRU_V2_DEPLOYER_FUNDING_STATUS.md](GRU_V2_DEPLOYER_FUNDING_STATUS.md)
- [DEPLOYER_WALLET_FUNDING_PLAN_PMM_POOLS.md](../11-references/DEPLOYER_WALLET_FUNDING_PLAN_PMM_POOLS.md)
- [check-gru-v2-deployer-funding-status.sh](/home/intlc/projects/proxmox/scripts/verify/check-gru-v2-deployer-funding-status.sh)
**Exit criteria**
- Arbitrum no longer reports under the deploy threshold
- Mainnet is no longer at a near-zero operational balance for rollout work
- the Mainnet `WETH9` public fan-out no longer fails inside the source bridge/router path
- the Chain 138 funding verifier resolves a healthy RPC without returning unknown balances
---
## Bottom line
The remaining GRU v2 public rollout blockers are now all mapped to concrete resolution paths. The unresolved work is operational deployment, bridge promotion, and liquidity creation, not missing documentation or unclear sequencing.

123
docs/03-deployment/GRU_V2_DEPLOYER_FUNDING_STATUS.md Normal file
View File

@@ -0,0 +1,123 @@
# GRU V2 Deployer Funding Status
**Last Updated:** 2026-04-03
**Purpose:** Canonical operator reference for the deployer wallet funding posture that still gates the remaining GRU v2 public rollout work.
---
## Canonical verifier
Run:
```bash
bash scripts/verify/check-gru-v2-deployer-funding-status.sh
```
Machine-readable:
```bash
bash scripts/verify/check-gru-v2-deployer-funding-status.sh --json
```
This verifier complements the rollout queue and protocol status surfaces:
- [GRU_V2_PUBLIC_DEPLOYMENT_QUEUE.md](GRU_V2_PUBLIC_DEPLOYMENT_QUEUE.md)
- [GRU_V2_PUBLIC_PROTOCOL_DEPLOYMENT_STATUS.md](../11-references/GRU_V2_PUBLIC_PROTOCOL_DEPLOYMENT_STATUS.md)
- [GRU_V2_BLOCKER_RESOLUTION_MATRIX.md](GRU_V2_BLOCKER_RESOLUTION_MATRIX.md)
---
## Current wallet state
Deployer:
- `0x4A666F96fC8764181194447A7dFdb7d471b301C8`
Observed after the latest funding and route checks on 2026-04-03 (Mainnet route txs finalized 2026-04-04 UTC):
- Mainnet: `0.001216982 ETH`
- Mainnet `WETH`: `0.005`
- Mainnet `LINK`: `0.1171400175`
- Cronos: `28.8106257165` native
- Arbitrum: `0.000775448 ETH`
- Chain 138 native: `989,399,860.565456 ETH`
- Chain 138 `WETH`: `22,845.815258`
- Chain 138 `WETH10`: `0.047131`
- Chain 138 `LINK`: `994,714.509915`
- Chain 138 `cUSDT`: `697,178,939.09`
- Chain 138 `cUSDC`: `698,412,990.30`
The verifier now prefers the stable public RPC `https://rpc-http-pub.d-bis.org` because `https://rpc.public-0138.defi-oracle.io` is currently returning `502` and can produce false “empty wallet” readings.
---
## Funding blockers this creates
### 1. Arbitrum deploy gas remains below the repo threshold
The existing deployer-balance checker already treats Arbitrum as underfunded for fresh deployment work at the repo threshold of about `0.44 ETH`.
### 2. Mainnet gas is still limited for follow-on public deployment work
Mainnet is no longer near-zero, but `0.001216982 ETH` is still a tight operational balance for repeated public deployment and bridge-repair work.
### 3. Public Mainnet `WETH9` fan-out is blocked by route health, not just gas
Even with enough Mainnet-side `WETH` and `LINK` to test the hub route, the live `Mainnet -> Arbitrum` send from `MAINNET_CCIP_WETH9_BRIDGE=0xc9901ce2Ddb6490FAA183645147a87496d8b20B6` failed on tx `0x97df657f0e31341ca852666766e553650531bbcc86621246d041985d7261bb07`.
The failure is not a wallet-balance issue:
- WETH allowance was set
- LINK allowance was set
- WETH and LINK balances were unchanged after the failed send except for gas
Tracing shows the revert occurs inside Mainnet router `0x80226fc0Ee2b096224EeAc085Bb9a8cba1146f7D` before any bridge event is emitted.
Read-only `calculateFee()` preflights now also revert for the tracked public-chain selectors `BSC`, `Avalanche`, `Gnosis`, `Cronos`, `Celo`, `Polygon`, `Arbitrum`, `Optimism`, and `Base`, so this should be treated as a broader Mainnet `WETH9` public fan-out blocker rather than an Arbitrum-only symptom.
### 4. Chain 138 is funded, but only when checked against the stable public RPC
Chain 138 is not currently a funding blocker for canonical liquidity or gas operations when read through `https://rpc-http-pub.d-bis.org`.
This is particularly relevant for the canonical DODO-backed funding surfaces documented in:
- [DEPLOYER_WALLET_FUNDING_PLAN_PMM_POOLS.md](../11-references/DEPLOYER_WALLET_FUNDING_PLAN_PMM_POOLS.md)
- [LIQUIDITY_POOLS_MASTER_MAP.md](../11-references/LIQUIDITY_POOLS_MASTER_MAP.md)
Cronos is also clearly funded today.
---
## What this does and does not block
### Blocked by current funding
- Arbitrum deployer-funded deployment work
- follow-on public-chain pool/protocol deployment work that expects comfortable Mainnet gas from the deployer wallet
- public-chain funding or deployment work that assumes the current Mainnet `WETH9` fan-out leg is live
### Not blocked by current funding
- fresh Chain 138 deployer-funded liquidity actions
- repo/documentation/explorer updates
- verifier generation and status publication
- read-only RPC checks
- planning and queue refinement
---
## Recommended order
1. Repair or replace the current Mainnet `WETH9` source bridge/router path before planning any new hub-based public-chain top-up from Mainnet.
2. Fund Arbitrum deploy gas to at least the repo threshold before any new Arbitrum deployment branch.
3. Top up Mainnet gas before beginning repeated public `cW*` pool and protocol deployment work there.
4. Keep using the stable Chain 138 public RPC for funding reads until `rpc.public-0138.defi-oracle.io` is healthy again.
---
## Related
- [DEPLOYER_WALLET_FUNDING_PLAN_PMM_POOLS.md](../11-references/DEPLOYER_WALLET_FUNDING_PLAN_PMM_POOLS.md)
- [GRU_V2_BLOCKER_RESOLUTION_MATRIX.md](GRU_V2_BLOCKER_RESOLUTION_MATRIX.md)
- [GRU_V2_PUBLIC_DEPLOYMENT_QUEUE.md](GRU_V2_PUBLIC_DEPLOYMENT_QUEUE.md)
- [REMAINING_SUMMARY.md](../00-meta/REMAINING_SUMMARY.md)

136
docs/03-deployment/GRU_V2_PUBLIC_DEPLOYMENT_QUEUE.md Normal file
View File

@@ -0,0 +1,136 @@
# GRU V2 Public Deployment Queue
**Last Updated:** 2026-04-04
**Purpose:** Operator-grade queue for the remaining public-network GRU v2 rollout: Wave 1 transport activation, public-chain `cW*` pools, and protocol staging across `Uniswap v3`, `DODO PMM`, `Balancer`, `Curve 3`, and `1inch`.
---
## Bottom line
The remaining deployment work is now cleanly split into three layers:
1. **Wave 1 transport activation** on top of the already-deployed token mesh
2. **First-tier public `cW* / hub stable` pools** on the tracked public EVM chains
3. **Protocol staging** after those pools exist
The public EVM `cW*` token mesh is no longer the blocker. The blocker is everything that comes after token deployment.
There is one important nuance now:
- the first Mainnet `DODO PMM` bootstrap pools for `cWUSDT/cWUSDC` against `USDC` and `USDT` are already recorded live
- the first six non-USD Wave 1 Mainnet rows `cWEURC / USDC`, `cWGBPC / USDC`, `cWAUDC / USDC`, `cWCADC / USDC`, `cWJPYC / USDC`, and `cWCHFC / USDC` are now also recorded live
- but the rollout is still far from complete, because only `6` first-tier **Wave 1** pools are live while the broader matrix still spans `110` planned rows
---
## Canonical queue
Run:
```bash
bash scripts/verify/check-gru-v2-deployment-queue.sh
```
Machine-readable:
```bash
bash scripts/verify/check-gru-v2-deployment-queue.sh --json
```
Explorer-published JSON:
- `https://explorer.d-bis.org/config/GRU_V2_DEPLOYMENT_QUEUE.json`
The queue JSON also includes a machine-readable `resolutionMatrix` for every currently open blocker category.
---
## What this queue answers
### 1. Wave 1 assets
The queue tracks the remaining non-USD Wave 1 GRU assets:
- `EUR`
- `JPY`
- `GBP`
- `AUD`
- `CAD`
- `CHF`
- `XAU`
For each asset it shows:
- canonical `c*` symbols
- wrapped `cW*` symbols
- whether transport is already live
- whether the public pool matrix covers its wrapped symbols
- the next operator steps
### 2. Destination chains
The queue covers the desired public EVM rollout surface from the GRU rollout plan:
- `1`
- `10`
- `25`
- `56`
- `100`
- `137`
- `42161`
- `42220`
- `43114`
- `8453`
- `1111`
For each chain it shows:
- hub stable
- whether the cW suite is already loaded in `deployment-status.json`
- the planned first-tier Wave 1 pool pairs
- how many of those pools are actually recorded live
### 3. Protocol staging
The queue also records protocol roles:
- `Uniswap v3` — primary public pool venue
- `DODO PMM` — primary PMM edge venue
- `Balancer` — secondary basket liquidity
- `Curve 3` — secondary stable curve
- `1inch` — routing layer after underlying pools are live
This keeps the protocol story honest: `1inch` is not a substitute for missing pools, and `Balancer` / `Curve` should not be marked live before first-tier liquidity exists.
---
## Important design update
The repo’s `pool-matrix.json` now covers the **full Wave 1 wrapped set**, not only the older USD / AUSDT / USDW lanes.
That means the public pool design now explicitly includes:
- `cWEURC`
- `cWEURT`
- `cWGBPC`
- `cWGBPT`
- `cWAUDC`
- `cWJPYC`
- `cWCHFC`
- `cWCADC`
- `cWXAUC`
- `cWXAUT`
across the tracked public EVM chain set, using each chain’s hub stable (`USDC` or `USDT`).
This does **not** mean those pools are live yet. It means the design/config blocker is closed and the remaining work is operator deployment.
---
## Related
- [GRU_GLOBAL_PRIORITY_CROSS_CHAIN_ROLLOUT.md](../04-configuration/GRU_GLOBAL_PRIORITY_CROSS_CHAIN_ROLLOUT.md)
- [GRU_V2_BLOCKER_RESOLUTION_MATRIX.md](GRU_V2_BLOCKER_RESOLUTION_MATRIX.md)
- [PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK.md](PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK.md)
- [SINGLE_SIDED_LPS_PUBLIC_NETWORKS_RUNBOOK.md](SINGLE_SIDED_LPS_PUBLIC_NETWORKS_RUNBOOK.md)
- [GRU_V2_PUBLIC_PROTOCOL_DEPLOYMENT_STATUS.md](../11-references/GRU_V2_PUBLIC_PROTOCOL_DEPLOYMENT_STATUS.md)

113
docs/03-deployment/GRU_V2_WAVE1_CHAIN138_DEPLOYMENT_PLAN.md Normal file
View File

@@ -0,0 +1,113 @@
# GRU V2 Wave 1 Chain 138 Deployment Plan
**Purpose:** Turn the remaining non-USD Wave 1 GRU assets on Chain 138 into a concrete V2 deployment queue using the generic `CompliantFiatTokenV2` deployment path.
**Machine-readable plan:** [`../../config/gru-v2-chain138-wave1-v2-plan.json`](../../config/gru-v2-chain138-wave1-v2-plan.json)
**Command helper:** [`../../scripts/deployment/plan-gru-v2-wave1-chain138.sh`](../../scripts/deployment/plan-gru-v2-wave1-chain138.sh)
**Generic deploy wrapper:** [`../../scripts/deployment/deploy-gru-v2-generic-chain138.sh`](../../scripts/deployment/deploy-gru-v2-generic-chain138.sh)
**Batch runner:** [`../../scripts/deployment/run-gru-v2-wave1-chain138.sh`](../../scripts/deployment/run-gru-v2-wave1-chain138.sh)
**Post-deploy verifier:** [`../../scripts/verify/check-gru-v2-token-standard-surface.sh`](../../scripts/verify/check-gru-v2-token-standard-surface.sh)
---
## Current truth
As of April 7, 2026:
- `USD` GRU V2 is live on Chain 138 through `cUSDT V2` and `cUSDC V2`
- the remaining Wave 1 assets are still `canonical_only`
- they exist on Chain 138 as legacy canonical assets, but they are not yet deployed as generic GRU V2 contracts
Verifier:
```bash
bash scripts/verify/check-gru-global-priority-rollout.sh --wave=wave1
```
Current expected output:
- `EUR`, `JPY`, `GBP`, `AUD`, `CAD`, `CHF`, `XAU` all show `canonical_only`
---
## What this plan covers
Wave 1 V2 candidates:
- `cEURC`
- `cEURT`
- `cGBPC`
- `cGBPT`
- `cAUDC`
- `cJPYC`
- `cCHFC`
- `cCADC`
- `cXAUC`
- `cXAUT`
These are the assets that should move onto the generic `CompliantFiatTokenV2` base if the goal is full V2 standardization on Chain 138.
---
## Print the commands
All Wave 1 dry-runs:
```bash
bash scripts/deployment/plan-gru-v2-wave1-chain138.sh
```
Single currency:
```bash
bash scripts/deployment/plan-gru-v2-wave1-chain138.sh --code=EUR
```
Batch dry-run for all Wave 1 assets:
```bash
bash scripts/deployment/run-gru-v2-wave1-chain138.sh
```
Live broadcast only when you intentionally want production mutation:
```bash
bash scripts/deployment/run-gru-v2-wave1-chain138.sh --apply
```
---
## Operator sequence
For each planned deployment:
1. Publish token/disclosure/reporting metadata to IPFS if needed.
2. Dry-run the generic deployment command.
3. Broadcast the deployment to Chain 138.
4. Register the V2 asset in `UniversalAssetRegistry`.
5. Add explorer/token-list metadata and version-aware aliases.
6. Update GRU manifest and transport overlay to reflect:
- forward-canonical version
- active liquidity version
- x402-ready version
7. Re-run:
- `bash scripts/verify/check-gru-v2-chain138-readiness.sh --report-only`
- `bash scripts/verify/check-gru-global-priority-rollout.sh --wave=wave1`
- `bash scripts/verify/check-gru-v2-token-standard-surface.sh --token SYMBOL=ADDRESS --strict`
---
## Boundary
This plan does **not** mean those Wave 1 assets are already deployed as V2 on Chain 138.
It means:
- the repo now has a generic deployment path for them
- the candidate list is explicit
- the commands are reproducible
- the remaining step is deliberate operator broadcast on production infrastructure

24
docs/03-deployment/IT_OPERATIONS_BILLING_STRIPE_OUTLINE.md Normal file
View File

@@ -0,0 +1,24 @@
# IT operations — billing and Stripe webhook (Phase 4 outline)
**Schema:** [`config/it-operations/entitlements-schema.sql`](../../config/it-operations/entitlements-schema.sql)
**Spec:** [SANKOFA_IT_OPERATIONS_CONTROLLER_SPEC.md](../02-architecture/SANKOFA_IT_OPERATIONS_CONTROLLER_SPEC.md) sections 3.4 and roadmap Phase 4.
## Model
- **`entitlement`** rows represent seats/SKUs bound to an `org_id`, optionally linked to **`dbis_core`** via `external_sku_id` (mirror `IruOffering` or catalog id).
- **`usage_snapshot`** rows are appended by a nightly Proxmox metering job (VMID → vCPU/RAM/disk).
- **`stripe_webhook_event`** stores raw events for idempotency (`id` = Stripe `event.id`).
## Webhook handler (future BFF)
1. Verify signature with `STRIPE_WEBHOOK_SECRET`.
2. On `customer.subscription.updated` / `deleted`, upsert **`entitlement`** (`valid_to`, `seat_count`, `stripe_subscription_id`).
3. Mark event **`processed`**; on failure store **`error`** for replay.
## Keycloak
- Map paid SKUs to optional group claims (e.g. `sankofa-it-admin` only via HR-approved assignment; billing does not auto-grant super-admin).
## Finance export
- Nightly job: aggregate **`usage_snapshot`** + open **`entitlement`** → CSV or QuickBooks/NetSuite API — out of scope for v1 code in this repo; schema supports it.

1532
docs/03-deployment/MAINNET_CWUSD_HYBRID_FLASH_LOOP_CALCULATION_WHITEPAPER.md Normal file
View File

File diff suppressed because it is too large Load Diff

244
docs/03-deployment/MAINNET_PMM_TRUU_CWUSD_PEG_AND_BOT_RUNBOOK.md Normal file
View File

@@ -0,0 +1,244 @@
# Mainnet PMM: TRUU liquidity, cWUSD* peg, deeper pools, and bots
**Purpose:** Single operator surface for Ethereum mainnet: deepen **TRUU** liquidity, keep **cWUSDT/cWUSDC** (and related USD cW rails) pegged to hub stables, improve liquidity on already-deployed DODO PMM pools, and run bots safely against those pools.
**Related:** `cross-chain-pmm-lps/docs/04-bot-policy.md`, `cross-chain-pmm-lps/docs/11-safe-inventory-sizing.md`, `cross-chain-pmm-lps/config/peg-bands.json`, `cross-chain-pmm-lps/config/deployment-status.json` (chain `1`), `scripts/deployment/deploy-mainnet-public-dodo-wave1-pool.sh`, `scripts/deployment/run-mainnet-public-dodo-cw-swap.sh`, `scripts/deployment/plan-mainnet-cw-stabilization.sh`, `scripts/verify/check-mainnet-public-dodo-cw-bootstrap-pools.sh`, `scripts/verify/check-mainnet-pmm-peg-bot-readiness.sh`.
**Hybrid loop calculations:** [MAINNET_CWUSD_HYBRID_FLASH_LOOP_CALCULATION_WHITEPAPER.md](/home/intlc/projects/proxmox/docs/03-deployment/MAINNET_CWUSD_HYBRID_FLASH_LOOP_CALCULATION_WHITEPAPER.md)
---
## 1. TRUU — depth and tradability
- [ ] **1.1** Prefer one deep **TRUU/USDT** (or primary) Uniswap v3 book for organic flow; add **cWUSD\*/TRUU** PMM only with a clear role (compliant rail), avoiding many shallow duplicates.
- [ ] **1.2** Seed PMM with **both** legs sized to a target **TRUU/USD** mid (cW leg = USD numeraire; TRUU leg matches market).
- [ ] **1.3** Define a **primary TRUU/USD reference** (plus sanity checks) for bot bounds and PMM **`i`** updates.
- [ ] **1.4** Automate **`i`** refresh on TRUU pools with caps on max change per period; never leave **`i`** stale through large market moves.
- [ ] **1.5** Rehearse **createPool → addLiquidity → swap** on a **mainnet fork** with correct decimals (**TRUU 10**, cW USD wrappers **6**).
- [ ] **1.6** Bots that trade TRUU: always use **minAmountOut**, reserve checks, and max trade size vs pool depth.
---
## 2. cWUSD* — peg maintenance (hub rails)
- [ ] **2.1** Treat **cWUSDT/USDT**, **cWUSDC/USDC**, and **cW\*/USDC** / **cW\*/USDT** hub pairs as the **peg contract**; do not use TRUU pools to fix cW drift.
- [ ] **2.2** Align bot behavior with **`cross-chain-pmm-lps/config/peg-bands.json`**: normal vs stress vs **circuit** (e.g. 200 bps USD circuit in config); define **pause** when circuit trips.
- [ ] **2.3** Combine **deviation vs oracle** with **cW inventory vs target** (inventory-first), per bot policy doc.
- [ ] **2.4** Reserve a **small gas budget** for **micro-trades** on matched-quote rails (**cWUSDC/USDC**, **cWUSDT/USDT**) for observability without becoming primary volume.
- [ ] **2.5** Size per-chain inventory targets using **`11-safe-inventory-sizing.md`** (refill latency, bridge **β/γ**, shock multiplier **σ**).
- [ ] **2.6** Ensure **mint/burn/bridge** roles and SLOs can refill inventory before pools empty under expected flow.
- [ ] **2.7** Monitor **USDC/USDT basis** on-chain so bots do not confuse stable basis with cW peg failure.
---
## 3. Existing deployed pools — more liquidity
- [ ] **3.1** Add liquidity in **tranches**; after each, read **`getVaultReserve`** and estimate price impact for a reference trade size.
- [ ] **3.2** Prioritize capital on pools that **routers and aggregators** actually hit; unfunded side pools do not improve real liquidity.
- [ ] **3.3** Keep **`cross-chain-pmm-lps/config/deployment-status.json`** (`chains."1".pmmPools`) and any **router/registry** mappings aligned with on-chain truth.
- [ ] **3.4** After material changes, run **`scripts/verify/check-mainnet-public-dodo-cw-bootstrap-pools.sh`** and **`scripts/verify/check-mainnet-pmm-peg-bot-readiness.sh`**.
- [ ] **3.5** For **cW vs USDC/USDT** hub pools, prefer **deepening reserves** over frequent **fee/k** changes unless analytics show misfit.
---
## 4. Bots against PMM pools — safety
- [ ] **4.1** Use a **single coordinator** (or strict role split) so multiple bots do not fight the same pool or double-send.
- [ ] **4.2** On **oracle staleness** or divergence vs pool mid: **widen bands or pause**; do not increase size into bad data.
- [ ] **4.3** **Gas policy**: max fee per tx/day, nonce management, and backoff on congestion.
- [ ] **4.4** Cap per-block / per-pool trade size vs reserves to limit **sandwich / JIT** damage on public legs.
- [ ] **4.5** Alert on **δ**, **reserves**, **failed txs**, **bridge queue**, **bot budget vs PnL**; bots without telemetry are an operational risk.
- [ ] **4.6** Before changing bands, fees, or inventory targets, run **cross-chain-pmm-lps** simulations / scorecard where applicable.
---
## 5. Governance split
- [ ] **5.1** **Peg bots** optimize **cW vs hub stables**; **TRUU bots** optimize **TRUU pricing and inventory** — do not merge policy in one unconstrained loop.
- [ ] **5.2** Align public messaging and constraints with **compliance/market-making** policy where relevant; mechanics do not replace legal review.
---
## 6. Quick commands
```bash
# Env: ETHEREUM_MAINNET_RPC, DODO_PMM_INTEGRATION_MAINNET (and pool env vars as in bootstrap script)
source smom-dbis-138/scripts/load-env.sh
bash scripts/verify/check-mainnet-public-dodo-cw-bootstrap-pools.sh
bash scripts/verify/check-mainnet-pmm-peg-bot-readiness.sh
bash scripts/deployment/plan-mainnet-cw-stabilization.sh
# Full deployment summary (Chain 138 + GRU + optional mainnet PMM peg check when mainnet env is set)
bash scripts/verify/check-full-deployment-status.sh
# Optional: stricter reserve floor (wei-like raw units, both legs)
# MIN_POOL_RESERVE_RAW=1000000000 bash scripts/verify/check-mainnet-pmm-peg-bot-readiness.sh
# Optional: after deploying cW/TRUU PMM, set token addresses for an extra check
# PMM_TRUU_BASE_TOKEN=0x... PMM_TRUU_QUOTE_TOKEN=0x... bash scripts/verify/check-mainnet-pmm-peg-bot-readiness.sh
# Equal USD on each side (not equal raw 1:1 tokens) — set TRUU_USD_PRICE from spot/TWAP
# TRUU_USD_PRICE=0.00004 USD_NOTIONAL_PER_LEG=5000 bash scripts/deployment/compute-mainnet-truu-pmm-seed-amounts.sh
# Create + seed cWUSDT/TRUU or cWUSDC/TRUU (dry-run first; set initial-price from DODO math / fork test)
# bash scripts/deployment/deploy-mainnet-pmm-cw-truu-pool.sh \
# --pair=cwusdt-truu --initial-price=<I> --base-amount=... --quote-amount=... --dry-run
# Top up existing cW/TRUU PMM using max wallet balances at the reference USD ratio (section 11)
# bash scripts/deployment/add-mainnet-truu-pmm-topup.sh --pair=cwusdc-truu
```
---
## 7. Operational note
Checklist items **1–5** are organizational and technical guardrails. Fulfilling them is **ongoing operations** (capital, bots, oracles), not a one-shot contract deploy. Use **section 6** scripts on a schedule or in CI when RPC and env are available.
For live Mainnet public DODO cW pools, do not assume the full public DVM surface is available. Some rows should be treated as **partial DODO surface / integration-only**: reserve and mid-price getters work, but direct `querySellBase` / `querySellQuote` reads can revert and raw `sellBase` / `sellQuote` fallbacks are not considered safe. Prefer the repo-supported integration path and reserve-based quoting helpers for live operations.
---
## 8. Implemented defaults (recommended baseline)
These are the repo’s **default recommendations**; override with governance and fork tests.
| Topic | Default |
|--------|---------|
| Volatile cW / TRUU pairs | **Both `cwusdt-truu` and `cwusdc-truu` are live** on Ethereum (see section 11). Keep **`publicRoutingEnabled: false`** in `deployment-status.json` until routers/GRU intentionally expose them; deepen reserves before scaling bots. |
| TRUU/USD reference | **Uniswap v3 TRUU/USDT** mid with short **TWAP/median**; second sanity source if available. |
| **`i` (initial price)** | Derive from DODO math for **base = cW (6 dp), quote = TRUU (10 dp)**; validate on **mainnet fork** before size. |
| Fee / k / TWAP | **30 bps**, **`k = 0.5e18`**, **TWAP off** (`deploy-mainnet-pmm-cw-truu-pool.sh` / `PMM_TRUU_*` env). |
| Peg rails | Keep **cW↔USDC/USDT** hub pools as peg venue; use **`peg-bands.json`** (normal / stress / circuit). |
| Bots | **Coordinator**; peg bots on hub rails **before** scaling TRUU/cW PMM; max trade **~0.25–0.5%** of smaller reserve (tune). |
| `deployment-status.json` | Mainnet **TRUU** anchor: `anchorAddresses.TRUU`. Live volatile rows: **`pmmPoolsVolatile[]`** with `role: "truu_routing"`, **`publicRoutingEnabled: false`** until routed. |
| Pilot | Small seed + **48–72h** observe with tight caps before scaling. |
| Compliance | Internal policy + counsel for public claims and scaled MM. |
---
## 9. Can we go 1:1 cWUSD* with TRUU?
**Yes for dollars, no for raw token counts** (unless TRUU happens to trade at exactly **$1.00 per full token**, which it does not today).
- **cWUSDT / cWUSDC** are **USD-numeraire** wrappers (6 decimals): **1 unit ≈ 1 USD**.
- **TRUU** (10 decimals) trades at a **small USD price per full token** (e.g. on the order of **$0.00004** historically on Uniswap — always use a **fresh** reference).
So:
- **1:1 USD notional (recommended):** deposit **the same dollar value** of cW as of TRUU. Raw amounts differ: you need **far more TRUU units** than cW units for equal USD.
- **1:1 raw token amount:** would imply **1 TRUU ≈ 1 USD**, which is **inconsistent** with a market-priced TRUU unless you intentionally misprice the pool.
**Raw amounts for equal USD per leg:**
```text
base_amount_raw = usd_per_leg × 10^6 (cW, 6 decimals)
truu_tokens = usd_per_leg / truu_usd_price
quote_amount_raw = truu_tokens × 10^10 (TRUU, 10 decimals)
```
Use:
```bash
TRUU_USD_PRICE=<spot or TWAP, USD per 1 full TRUU> \
USD_NOTIONAL_PER_LEG=<dollars per side> \
bash scripts/deployment/compute-mainnet-truu-pmm-seed-amounts.sh
```
Then pass `--base-amount` / `--quote-amount` into `deploy-mainnet-pmm-cw-truu-pool.sh` (still set `--initial-price` from DODO fork).
---
## 10. Recording a live TRUU PMM pool
After `createPool` + `addLiquidity`, append an object to **`chains."1".pmmPoolsVolatile`** in `cross-chain-pmm-lps/config/deployment-status.json`:
```json
{
"base": "cWUSDT",
"quote": "TRUU",
"poolAddress": "0xYourPoolFromCast",
"feeBps": 30,
"k": 500000000000000000,
"role": "truu_routing",
"publicRoutingEnabled": false
}
```
(`k` is the on-chain raw scalar `0.5e18`, same as in `deploy-mainnet-pmm-cw-truu-pool.sh`.)
Run `node cross-chain-pmm-lps/scripts/validate-deployment-status.cjs` and `bash scripts/verify/check-mainnet-pmm-peg-bot-readiness.sh`.
If the pool is also listed as **active** under `publicPools` in `config/gru-transport-active.json`, `scripts/validation/validate-config-files.sh` resolves the address against **both** `pmmPools` and `pmmPoolsVolatile` on that chain.
---
## 11. Live inventory (Ethereum mainnet, 2026-04)
| Item | Value |
|------|--------|
| **DODO PMM integration** | `DODO_PMM_INTEGRATION_MAINNET` = `0xa9F284eD010f4F7d7F8F201742b49b9f58e29b84` |
| **TRUU (anchor)** | `0xDAe0faFD65385E7775Cf75b1398735155EF6aCD2` (10 decimals) |
| **cWUSDT / TRUU pool** | `0x508E5e80B66204b8CD9869323Fdd3A289ea50993` |
| **cWUSDC / TRUU pool** | `0x9A632F35078b6A4A9bf27806Bb7aFfAA2F16C846` |
| **Shared `i` used at create** | `2482326199339289065` (align with fork/oracle before large adds if spot moves) |
| **Fee / k / TWAP** | 30 bps / `5e17` / off |
**Last operator liquidity add (split across both volatile pools):** 2026-04-05 — cWUSDC/TRUU `addLiquidity` tx `0x014c5bb5f95550139ee63e2b290d3836766346f7cc1b6c145a2c9557d8b31833`; cWUSDT/TRUU `addLiquidity` tx `0x33ddde8b6b166552084debc40fc243ec1b46a1960898ba8520e37d50ed516dea`. Reserves move with trades; confirm live with `cast call <pool> "getVaultReserve()(uint256,uint256)" --rpc-url $ETHEREUM_MAINNET_RPC`.
**Canonical JSON:** `cross-chain-pmm-lps/config/deployment-status.json` → `chains."1".pmmPoolsVolatile[]`.
**Top up existing pools (ratio-matched add):**
```bash
source smom-dbis-138/scripts/load-env.sh
# Wallet must hold both cW (6 dp) and TRUU (10 dp); uses max amounts that fit the reference ratio
bash scripts/deployment/add-mainnet-truu-pmm-topup.sh --pair=cwusdt-truu
bash scripts/deployment/add-mainnet-truu-pmm-topup.sh --pair=cwusdc-truu
```
**Keep wallet inventory for trading (same ratio, partial add):** `--reserve-bps=2000` keeps **20%** of the computed ratio-matched bundle on the deployer and adds **80%** (adjust bps to taste).
```bash
bash scripts/deployment/add-mainnet-truu-pmm-topup.sh --pair=cwusdt-truu --reserve-bps=2000
bash scripts/deployment/add-mainnet-truu-pmm-fund-both-pools.sh --reserve-bps=2000
```
Or call `deploy-mainnet-pmm-cw-truu-pool.sh` directly with explicit `--base-amount` / `--quote-amount` (skips `createPool` when the pair exists).
### 11.1 Large adds (under **$125k cW per pool**, 1:1 USD legs)
Operator-confirmed cap: **up to $125,000** notional on the **cW** leg **per** volatile pool (cWUSDT/TRUU and cWUSDC/TRUU are separate — full cap needs **both** cW tokens and **two** TRUU quote legs).
**Compute `base_raw` / `quote_raw` for any USD per leg:**
```bash
bash scripts/deployment/compute-mainnet-truu-liquidity-amounts.sh --usd-per-leg=125000
```
**Reference ladder (same ratio as historical seeds, `B_ref=1_500_000`, `Q_ref=372_348_929_900_893`):**
| cW USD / leg | `base_raw` | `quote_raw` (TRUU) |
|--------------|------------|---------------------|
| 50,000 | `50000000000` | `12411630996696433333` |
| 100,000 | `100000000000` | `24823261993392866666` |
| 125,000 | `125000000000` | `31029077491741083333` |
**Pre-flight (deployer must hold balances + ETH gas):**
```bash
source smom-dbis-138/scripts/load-env.sh
D=$(cast wallet address --private-key "$PRIVATE_KEY")
# cWUSDT, cWUSDC, TRUU balances ≥ planned add; TRUU for *both* pools = 2× quote if same USD each
```
**Before max adds:** re-validate **`i`** vs Uniswap TRUU/USDT (TWAP/median) and/or **mainnet fork** — stale `i` at **$100k+** clips is high risk.
**Optional verifier pair** (extra cast check beyond `pmmPoolsVolatile[]`):
```bash
PMM_TRUU_BASE_TOKEN=0x... PMM_TRUU_QUOTE_TOKEN=0xDAe0faFD65385E7775Cf75b1398735155EF6aCD2 \
bash scripts/verify/check-mainnet-pmm-peg-bot-readiness.sh
```
**Still optional / operational (not closed by deploy alone):** checklist sections 1–5 (oracle/TWAP for TRUU, `i` refresh automation, peg bots on hub rails, coordinator, telemetry). **Security:** rotate deployer key if `PRIVATE_KEY` was ever echoed to logs. **Stricter depth gate:** `MIN_POOL_RESERVE_RAW=1000000 bash scripts/verify/check-mainnet-pmm-peg-bot-readiness.sh` (tune threshold to policy).

112
docs/03-deployment/MAINNET_STANDARD_DODO_POOL_MIGRATION_PLAN.md Normal file
View File

@@ -0,0 +1,112 @@
# Mainnet Standard DODO Pool Migration Plan
**Purpose:** replace partial-surface Mainnet cW public pools with canonical full-surface DODO pools so routing, explorers, and indexers can treat them as ordinary DODO venues.
## 1. Audit the current factory path
Run:
```bash
bash scripts/verify/audit-mainnet-dodo-standard-pool-readiness.sh
```
This reports:
- `DODO_PMM_INTEGRATION_MAINNET`
- `dodoVendingMachine()` on the live integration
- runtime code size for the integration, factory, and each recorded pool
- integration mapping vs env-backed pool address
- `querySellBase` / `querySellQuote` probe status
- whether `hasStandardPoolSurface(pool)` is set
## 2. Target state
Each replacement pool should satisfy all of the following:
- canonical factory-backed creation path
- `_BASE_TOKEN_` / `_QUOTE_TOKEN_` match the intended pair
- `getVaultReserve`, `getMidPrice`, `_BASE_RESERVE_`, `_QUOTE_RESERVE_` succeed
- `querySellBase` and `querySellQuote` succeed after liquidity is added
- `refreshPoolSurface(pool)` returns `true`
The integration now enforces this for future create-and-seed flows in `smom-dbis-138/contracts/dex/DODOPMMIntegration.sol`.
## 3. Files and scripts to update during replacement rollout
### 3.1 Canonical creation and verification path
- `smom-dbis-138/contracts/dex/DODOPMMIntegration.sol`
This is now the contract-level guardrail. Future replacement pools should be created through this integration and validated after liquidity.
- `smom-dbis-138/script/dex/DeployDODOPMMIntegration.s.sol`
Confirms which `DODO_VENDING_MACHINE_ADDRESS` is wired into the integration deployment.
- `scripts/deployment/deploy-mainnet-public-dodo-wave1-pool.sh`
Main operator entrypoint for creating and seeding replacement Mainnet cW public pools.
- `scripts/verify/check-mainnet-public-dodo-cw-bootstrap-pools.sh`
Post-migration verification for mapping, reserves, and dry-run routability.
- `scripts/verify/audit-mainnet-dodo-standard-pool-readiness.sh`
Migration audit for factory path and standard-surface readiness.
### 3.2 Address and env inventory
Update the env-backed pool address references used by scripts and operators:
- root `.env`
- `.env.master.example`
Pool keys to review and replace as each migration lands:
- `POOL_CWUSDT_USDC_MAINNET`
- `POOL_CWUSDC_USDC_MAINNET`
- `POOL_CWUSDT_USDT_MAINNET`
- `POOL_CWUSDC_USDT_MAINNET`
- `POOL_CWEURC_USDC_MAINNET`
- `POOL_CWGBPC_USDC_MAINNET`
- `POOL_CWAUDC_USDC_MAINNET`
- `POOL_CWCADC_USDC_MAINNET`
- `POOL_CWJPYC_USDC_MAINNET`
- `POOL_CWCHFC_USDC_MAINNET`
Also confirm:
- `DODO_PMM_INTEGRATION_MAINNET`
- `DODO_VENDING_MACHINE_ADDRESS` for the deployment context that creates replacement pools
- any explicit mainnet DODO factory env, if introduced for stricter deployment controls
### 3.3 Routing and public status surfaces
Update the public inventories that describe the active pool set:
- `config/smart-contracts-master.json`
Add or replace canonical Mainnet DODO pool references if this file is used as the public address source of truth.
- `config/aggregator-route-matrix.csv`
- `config/aggregator-route-matrix.json`
Update any rows that embed legacy pool addresses or notes.
- `docs/11-references/PMM_DEX_ROUTING_STATUS.md`
- `docs/03-deployment/MAINNET_PMM_TRUU_CWUSD_PEG_AND_BOT_RUNBOOK.md`
Remove partial-surface caveats only after every active public pool in scope has been replaced and validated.
### 3.4 Swap and operational helpers
Review helpers that may have embedded assumptions or pool references:
- `scripts/deployment/run-mainnet-public-dodo-cw-swap.sh`
- `scripts/deployment/plan-mainnet-cw-stabilization.sh`
- `scripts/verify/check-mainnet-pmm-peg-bot-readiness.sh`
- `scripts/verify/check-full-deployment-status.sh`
- `scripts/README.md`
- `scripts/verify/README.md`
## 4. Recommended rollout sequence
1. Audit the current integration/factory/pool path with `audit-mainnet-dodo-standard-pool-readiness.sh`.
2. Confirm the live integration is wired to the intended canonical DODO factory or adapter.
3. Deploy one replacement pool for a single pair through the integration.
4. Seed liquidity through `addLiquidity(...)`; this now fails unless the pool exposes the standard quote surface.
5. Call `refreshPoolSurface(pool)` and confirm `hasStandardPoolSurface(pool) == true`.
6. Update env/config references for that pair.
7. Run `check-mainnet-public-dodo-cw-bootstrap-pools.sh` and the relevant dry-run/live swap checks.
8. Repeat pair-by-pair, then retire the legacy pool references from public docs and route inventories.
## 5. Immediate migration risk to watch
Because replacement is address-based, any public explorer, route matrix, or env file that still points at the old pool will continue to show the legacy partial-surface behavior even after a correct replacement pool exists. The migration only becomes visible to routers and indexers after those references are updated.

16
docs/03-deployment/NEXT_STEPS_PMM_FULL_PARITY_AND_ALL_POOLS.md
View File

@@ -1,6 +1,6 @@
# Next Steps: Full Parity and Deploy All PMM Pools
> Historical note (2026-03-26): this document captures an earlier parity plan. The current canonical Chain 138 PMM stack is `DODOPMMIntegration=0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d` and `DODOPMMProvider=0x5CAe6Ce155b7f08D3a956F5Dc82fC9945f29B381`, with the desired-state mesh reconciled. Use [ADDRESS_MATRIX_AND_STATUS.md](../11-references/ADDRESS_MATRIX_AND_STATUS.md) and [LIQUIDITY_POOLS_MASTER_MAP.md](../11-references/LIQUIDITY_POOLS_MASTER_MAP.md) for live status.
> Historical note (2026-04-02): this document captures an earlier parity plan. The current canonical Chain 138 PMM stack is `DODOPMMIntegration=0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895` and `DODOPMMProvider=0x3f729632E9553EBacCdE2e9b4c8F2B285b014F2e`, with the desired-state mesh reconciled. Use [ADDRESS_MATRIX_AND_STATUS.md](../11-references/ADDRESS_MATRIX_AND_STATUS.md) and [LIQUIDITY_POOLS_MASTER_MAP.md](../11-references/LIQUIDITY_POOLS_MASTER_MAP.md) for live status.
**Last Updated:** 2026-02-28
**Purpose:** Ordered list of steps to achieve full PMM parity and deploy all DODO PMM pools (Chain 138 first, then multichain).
@@ -11,7 +11,7 @@
| Scope | DODOPMMIntegration | Pools (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC) | DODOPMMProvider | Liquidity |
|-------|--------------------|-----------------------------------------------|-----------------|-----------|
| **Chain 138** | Deployed (`0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d`) | Reconciled (addresses in ADDRESS_MATRIX / LIQUIDITY_POOLS_MASTER_MAP) | Deployed (`0x5CAe6Ce155b7f08D3a956F5Dc82fC9945f29B381`) | Public stable and XAU pools funded |
| **Chain 138** | Deployed (`0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895`) | Reconciled (addresses in ADDRESS_MATRIX / LIQUIDITY_POOLS_MASTER_MAP) | Deployed (`0x3f729632E9553EBacCdE2e9b4c8F2B285b014F2e`) | Public stable and XAU pools funded |
| **L2s (BSC, Polygon, Base, etc.)** | Script exists (`deploy-pmm-all-l2s.sh`) | Not created | Not deployed | N/A |
| **cW* mesh (11 chains)** | Design only | 111 pools in design | Not deployed | N/A |
@@ -30,9 +30,9 @@
2. **Verify or create the three PMM pools**
- Pools (from PRE_DEPLOYMENT_CHECKLIST / .env):
- cUSDT/cUSDC: `0xff8d3b8fDF7B112759F076B69f4271D4209C0849`
- cUSDT/USDT: `0x6fc60DEDc92a2047062294488539992710b99D71`
- cUSDC/USDC: `0x9f74Be42725f2Aa072a9E0CdCce0E7203C510263`
- cUSDT/cUSDC: `0x9e89bAe009adf128782E19e8341996c596ac40dC`
- cUSDT/USDT: `0x866Cb44b59303d8dc5f4F9E3E7A8e8b0bf238d66`
- cUSDC/USDC: `0xc39B7D0F40838cbFb54649d327f49a6DAC964062`
- If any pool is missing on-chain, create it:
- `forge script script/dex/CreateCUSDTCUSDCPool.s.sol:CreateCUSDTCUSDCPool --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY"`
- `forge script script/dex/CreateCUSDTUSDTPool.s.sol:CreateCUSDTUSDTPool --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY"`
@@ -44,12 +44,12 @@
- Run: `forge script script/liquidity/RegisterDODOPools.s.sol:RegisterDODOPools --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY"`.
4. **Add liquidity to all three pools**
- Approve base/quote tokens to `DODOPMMIntegration` (`0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d`).
- Approve base/quote tokens to `DODOPMMIntegration` (`0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895`).
- Call `DODOPMMIntegration.addLiquidity(pool, baseAmount, quoteAmount)` for each pool. See [DODO_PMM_INTEGRATION.md](../../smom-dbis-138/docs/integration/DODO_PMM_INTEGRATION.md).
- **Forge script:** `forge script script/dex/AddLiquidityPMMPoolsChain138.s.sol:AddLiquidityPMMPoolsChain138 --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY"` with env `ADD_LIQUIDITY_BASE_AMOUNT` and `ADD_LIQUIDITY_QUOTE_AMOUNT` (e.g. `1000000e6`). Or use **full-parity runner:** `./scripts/deployment/run-pmm-full-parity-all-phases.sh` (Phase 1 creates pools in parallel, registers, then adds liquidity when amounts are set).
5. **Optional: Deploy EnhancedSwapRouter (Chain 138)**
- Only after Uniswap/Balancer (or other DEX) pools exist on 138; configure quoter and pool IDs. See [PMM_DEX_ROUTING_STATUS.md](../11-references/PMM_DEX_ROUTING_STATUS.md) §5.
5. **Optional: Keep router-v2 and the pilot venue layer verified**
- `EnhancedSwapRouterV2` plus the funded pilot-compatible `Uniswap_v3`, `Balancer`, `Curve_3`, and `1inch` venues are already live on Chain 138. Re-run `bash scripts/verify/check-chain138-pilot-dex-venues.sh` after venue funding, planner publication, or token-aggregation changes.
6. **Update docs**
- Set [PMM_DEX_ROUTING_STATUS.md](../11-references/PMM_DEX_ROUTING_STATUS.md) to “pools created” and “liquidity added” when done.

2
docs/03-deployment/OMNL_DBIS_CORE_CHAIN138_SMART_VAULT_RTGS_RUNBOOK.md
View File

@@ -241,7 +241,7 @@ Indonesia / BNI slice (executable tasks): [DBIS_OMNL_INDONESIA_BNI_E2E_EXECUTABL
|------------|---------|--------|
| **IBAN**, **BBAN**, **national account** | **`fiat_rail_ref`** (normalized + hash for display) | RTGS and correspondent legs; ISO 20022 account servicer references. |
| **BIC / BEI** | Same bundle as IBAN | Institution routing. |
| **WEB3-ETH-IBAN** (or institution-specific *Ethereum account alias* schemes) | **Alias** that **resolves** to `vault_root_address` or an allowed EOA/smart account | Not a replacement for LEI: it is a **routing/presentation** layer. Store: `alias_type`, `alias_value`, `resolved_address`, `chain_id` (138), `valid_from` / `valid_to`, `lei` (parent entity). |
| **WEB3-ETH-IBAN** (or institution-specific *Ethereum account alias* schemes) | **Alias** that **resolves** to `vault_root_address` or an allowed EOA/smart account | Not a replacement for LEI: it is a **routing/presentation** layer. Store: `alias_type`, `alias_value`, `resolved_address`, `chain_id` (138), `valid_from` / `valid_to`, `lei` (parent entity). Schema: `web3_eth_iban` in [`address-registry-entry.schema.json`](../../config/dbis-institutional/schemas/address-registry-entry.schema.json). **XE… encoding** (vs bank IBAN) and validation: [`config/dbis-institutional/README.md`](../../config/dbis-institutional/README.md). |
### 13.3 Instruments and custody (what is held)

30
docs/03-deployment/OPERATIONAL_RUNBOOKS.md
View File

@@ -210,7 +210,12 @@ If an RPC node returns wrong chain ID or block 0 / no block: use the dedicated r
## Liquidity & Multi-Chain (cUSDT/cUSDC)
- **[CUSDT_CUSDC_MULTICHAIN_LIQUIDITY_RUNBOOK.md](../../smom-dbis-138/docs/deployment/CUSDT_CUSDC_MULTICHAIN_LIQUIDITY_RUNBOOK.md)** — Deploy cUSDT/cUSDC to other chains (Ethereum, BSC, Polygon, Base, etc.); create Dodo PMM and Uniswap pools; add to Balancer, Curve. Scripts: `deploy-cusdt-cusdc-all-chains.sh`, `deploy-pmm-all-l2s.sh`, `create-uniswap-v3-pool-cusdt-cusdc.sh`.
- **[USDW_PUBLIC_WRAP_VAULT_RUNBOOK.md](USDW_PUBLIC_WRAP_VAULT_RUNBOOK.md)** — Deploy native public-chain `USDW` -> `cWUSDW` wrap vault and share `cWUSDW` roles with the GRU bridge; BSC re-use, Polygon-first deployment gate.
- **[AUSDT_CAUSDT_CWAUSDT_BRIDGE_CHECKLIST.md](AUSDT_CAUSDT_CWAUSDT_BRIDGE_CHECKLIST.md)** — ALL Mainnet `AUSDT` origin pins, public `cWAUSDT` mirrors, and the activation gate for landing on Chain 138 as `cAUSDT`.
- **[CXAUC_CXAUT_CWAXAUC_CWAXAUT_ALLTRA_BRIDGE_CHECKLIST.md](CXAUC_CXAUT_CWAXAUC_CWAXAUT_ALLTRA_BRIDGE_CHECKLIST.md)** — ALL Mainnet gold corridor: `cXAUC/cXAUT` source assets, `cWAXAUC/cWAXAUT` bridge-minted ALL Mainnet wrappers, `cAXAUC/cAXAUT` unwrapped landing assets, and the activation gate.
- **[WORMHOLE_NTT_EXECUTOR_OPERATOR_RUNBOOK.md](WORMHOLE_NTT_EXECUTOR_OPERATOR_RUNBOOK.md)** — Wormhole NTT + Executor operator preparation, NTT CLI bootstrap, and the current Chain 138 support boundary.
- **[LIQUIDITY_POOL_CONTROLS_RUNBOOK.md](LIQUIDITY_POOL_CONTROLS_RUNBOOK.md)** — Trustless LiquidityPoolETH, DODO PMM, PoolManager, LiquidityManager controls and funding.
- **[MAINNET_PMM_TRUU_CWUSD_PEG_AND_BOT_RUNBOOK.md](MAINNET_PMM_TRUU_CWUSD_PEG_AND_BOT_RUNBOOK.md)** — Ethereum mainnet: TRUU PMM liquidity, cWUSD* peg maintenance, deeper deployed pools, bot guardrails; verifier `scripts/verify/check-mainnet-pmm-peg-bot-readiness.sh`; deploy `scripts/deployment/deploy-mainnet-pmm-cw-truu-pool.sh`; USD-notional seed helper `scripts/deployment/compute-mainnet-truu-pmm-seed-amounts.sh`; ratio-matched top-up `scripts/deployment/add-mainnet-truu-pmm-topup.sh` (section 11 live inventory); large 1:1 USD legs `scripts/deployment/compute-mainnet-truu-liquidity-amounts.sh` (section 11.1).
- **Runbooks master index:** [../RUNBOOKS_MASTER_INDEX.md](../RUNBOOKS_MASTER_INDEX.md) — All runbooks across the repo.
---
@@ -272,7 +277,20 @@ ssh root@192.168.11.11 "tail -f /opt/smom-dbis-138/services/relay/relay-service.
ssh root@192.168.11.11 "pkill -f 'node index.js' 2>/dev/null; sleep 2; cd /opt/smom-dbis-138/services/relay && nohup ./start-relay.sh >> relay-service.log 2>&1 &"
```
**Configuration:** Uses **RPC_URL_138_PUBLIC** (VMID 2201, 192.168.11.221:8545) for Chain 138; `START_BLOCK=latest`.
**Configuration:** Uses **RPC_URL_138_PUBLIC** for Chain 138 (VMID 2201). On the relay host (LAN): `http://192.168.11.221:8545`. For **published** URLs and checks from the internet, use **HTTPS FQDN** `https://rpc-http-pub.d-bis.org`. `START_BLOCK=latest`.
### XDC Zero + Chain 138 (parallel to CCIP)
- **[CHAIN138_XDC_ZERO_BRIDGE_RUNBOOK.md](CHAIN138_XDC_ZERO_BRIDGE_RUNBOOK.md)** — Endpoint + CSC + second relayer pair (XDC mainnet `https://rpc.xinfin.network` ↔ Chain 138); does **not** replace subnet↔parent XDC-Relayer.
- **Troubleshooting:** [CHAIN138_XDC_ZERO_DEPLOYMENT_TROUBLESHOOTING.md](CHAIN138_XDC_ZERO_DEPLOYMENT_TROUBLESHOOTING.md) (pending txs, Hardhat hangs, SimpleCsc vs production CSC).
### OP Stack Standard Rollup (Ethereum mainnet, Superchain registry)
- **[OP_STACK_STANDARD_ROLLUP_SUPERCHAIN_RUNBOOK.md](OP_STACK_STANDARD_ROLLUP_SUPERCHAIN_RUNBOOK.md)** — Greenfield OP Stack L2 on Ethereum mainnet, Standard Rollup / `superchain_level = 2` path; **parallel** to Besu Chain 138.
- **L2 ↔ Besu 138 (optional bridging):** [OP_STACK_L2_AND_BESU138_BRIDGE_NOTES.md](OP_STACK_L2_AND_BESU138_BRIDGE_NOTES.md)
- **Config / scripts:** [`config/op-stack-superchain/README.md`](../../config/op-stack-superchain/README.md), [`scripts/op-stack/README.md`](../../scripts/op-stack/README.md)
- **Pointer:** [../07-ccip/XDC_ZERO_CHAIN138.md](../07-ccip/XDC_ZERO_CHAIN138.md) · [`config/xdc-zero/`](../../config/xdc-zero/) · [`scripts/xdc-zero/`](../../scripts/xdc-zero/) · `bash scripts/xdc-zero/run-xdc-zero-138-operator-sequence.sh`
- **systemd:** [`config/systemd/xdc-zero-relayer-138-pair.example.service`](../../config/systemd/xdc-zero-relayer-138-pair.example.service) (`node dist/server.js`) + [`config/xdc-zero/xdc-zero-relayer-138-pair.example.defaults`](../../config/xdc-zero/xdc-zero-relayer-138-pair.example.defaults). Use [`config/xdc-zero/xdc-relayer.dotenv.example`](../../config/xdc-zero/xdc-relayer.dotenv.example) only for a clone-local relayer `.env`. Core `192.168.11.211:8545` is operator-only; relayer/service `SUBNET_URL` should use `https://rpc-http-pub.d-bis.org`.
### CCIP Deployment
@@ -379,7 +397,7 @@ ssh root@192.168.11.11 "pkill -f 'node index.js' 2>/dev/null; sleep 2; cd /opt/s
| # | Task | Frequency | Command / Script |
|---|------|------------|------------------|
| 135 | Monitor explorer sync status | Daily | `curl -s http://192.168.11.140:4000/api/v1/stats | jq .indexer` or Blockscout admin; check indexer lag |
| 136 | Monitor RPC node health (e.g. VMID 2201) | Daily | `bash scripts/verify/verify-backend-vms.sh`; `curl -s -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' $RPC_URL_138_PUBLIC` (or http://192.168.11.221:8545) |
| 136 | Monitor RPC node health (e.g. VMID 2201) | Daily | `bash scripts/verify/verify-backend-vms.sh`; `curl -s -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'` to **`$RPC_URL_138_PUBLIC`** — prefer **`https://rpc-http-pub.d-bis.org`** when not on LAN; on LAN, `http://192.168.11.221:8545` is OK |
| 137 | Check config API uptime | Weekly | `curl -sI https://dbis-api.d-bis.org/health` or target config API URL |
| 138 | Review explorer logs **(O-4)** | Weekly | See **O-4** below. `ssh root@<explorer-host> "journalctl -u blockscout -n 200 --no-pager"` or `pct exec 5000 -- journalctl -u blockscout -n 200 --no-pager`. Explorer: VMID 5000 (r630-02, 192.168.11.140). |
| 139 | Update token list **(O-5)** | As needed | See **O-5** below. Canonical list: `token-lists/lists/dbis-138.tokenlist.json`. Guide: [TOKEN_LIST_AUTHORING_GUIDE.md](../11-references/TOKEN_LIST_AUTHORING_GUIDE.md). Bump `version` and `timestamp`; validate schema; deploy/public URL per runbook. |
@@ -388,15 +406,15 @@ ssh root@192.168.11.11 "pkill -f 'node index.js' 2>/dev/null; sleep 2; cd /opt/s
**O-5 (Update token list, as needed):** Edit `token-lists/lists/dbis-138.tokenlist.json`; bump `version.major|minor|patch` and `timestamp`; run validation (see TOKEN_LIST_AUTHORING_GUIDE); update any public URL (e.g. tokens.d-bis.org) and explorer/config API token list reference.
**Script:** `scripts/maintenance/daily-weekly-checks.sh [daily|weekly|all]` — daily: explorer, RPC, indexer lag, in-CT disk (138b); weekly: config API, thin pool all hosts (138a), fstrim (138c), journal vacuum (138d). **Cron:** `schedule-daily-weekly-cron.sh --install` (daily 08:00, weekly Sun 09:00). **Storage:** `schedule-storage-growth-cron.sh --install` (collect every 6h, prune snapshots+history Sun 08:00); `schedule-storage-monitor-cron.sh --install` (host alerts daily 07:00). See [04-configuration/STORAGE_GROWTH_AND_HEALTH.md](../04-configuration/STORAGE_GROWTH_AND_HEALTH.md).
**Script:** `scripts/maintenance/daily-weekly-checks.sh [daily|weekly|all]` — daily: explorer, RPC, indexer lag, in-CT disk (138b); weekly: config API, thin pool all hosts (138a), fstrim (138c), journal vacuum (138d). **Cron:** install from a persistent host checkout, e.g. `CRON_PROJECT_ROOT=/srv/proxmox bash scripts/maintenance/schedule-daily-weekly-cron.sh --install` (daily 08:00, weekly Sun 09:00). **Storage:** `CRON_PROJECT_ROOT=/srv/proxmox bash scripts/maintenance/schedule-storage-growth-cron.sh --install` (collect every 6h, prune snapshots+history Sun 08:00); `CRON_PROJECT_ROOT=/srv/proxmox bash scripts/maintenance/schedule-storage-monitor-cron.sh --install` (host alerts daily 07:00). See [04-configuration/STORAGE_GROWTH_AND_HEALTH.md](../04-configuration/STORAGE_GROWTH_AND_HEALTH.md).
### When decommissioning or changing RPC nodes
**Explorer (VMID 5000) depends on RPC** at `ETHEREUM_JSONRPC_HTTP_URL` (use **RPC_URL_138_PUBLIC** = VMID 2201, 192.168.11.221:8545). When you **decommission or change the IP of an RPC node** that Blockscout might use:
**Explorer (VMID 5000) depends on RPC** at `ETHEREUM_JSONRPC_HTTP_URL`. Point it at **VMID 2201** (public Besu). Prefer **`https://rpc-http-pub.d-bis.org`** in Blockscout when the indexer reaches RPC over NPM/tunnel; on-LAN-only installs may use `http://192.168.11.221:8545`. When you **decommission or change the IP of an RPC node** that Blockscout might use:
1. **Check** Blockscout env on VM 5000:
`pct exec 5000 -- bash -c 'grep -E "ETHEREUM_JSONRPC|RPC" /opt/blockscout/.env 2>/dev/null || docker inspect blockscout 2>/dev/null | grep -A5 Env'` (run from root@r630-02, 192.168.11.12).
2. **If** it points to the affected node, **update** to a live RPC (set to `$RPC_URL_138_PUBLIC` or http://192.168.11.221:8545) in Blockscout env and **restart** Blockscout.
2. **If** it points to the affected node, **update** to a live RPC (set `ETHEREUM_JSONRPC_HTTP_URL` to **`https://rpc-http-pub.d-bis.org`** or, on LAN, `http://192.168.11.221:8545`) in Blockscout env and **restart** Blockscout.
3. **Update** any script defaults and `config/ip-addresses.conf` / docs that reference the old RPC.
See **[BLOCKSCOUT_FIX_RUNBOOK.md](BLOCKSCOUT_FIX_RUNBOOK.md)** § "Proactive: When changing RPC or decommissioning nodes" and **[SOLACESCANSCOUT_DEEP_DIVE_FIXES_AND_TIMING.md](../04-configuration/verification-evidence/SOLACESCANSCOUT_DEEP_DIVE_FIXES_AND_TIMING.md)**.
@@ -540,6 +558,8 @@ See [BLOCKSCOUT_FIX_RUNBOOK.md](BLOCKSCOUT_FIX_RUNBOOK.md).
| Update token list **(O-5)** | As needed | Runbook [139] above; `token-lists/lists/dbis-138.tokenlist.json`; [TOKEN_LIST_AUTHORING_GUIDE.md](../11-references/TOKEN_LIST_AUTHORING_GUIDE.md) |
| NPMplus backup | When NPMplus is up | `scripts/verify/backup-npmplus.sh` |
| Validator key/config backup | Per backup policy | W1-8; [BACKUP_AND_RESTORE.md](BACKUP_AND_RESTORE.md) |
| Ensure FireFly primary (6200) | As needed | `scripts/maintenance/ensure-firefly-primary-via-ssh.sh` (r630-02) |
| Ensure Fabric sample network (6000) | As needed | `scripts/maintenance/ensure-fabric-sample-network-via-ssh.sh` (r630-02) |
| Start firefly-ali-1 (6201) | Optional, when needed | `scripts/maintenance/start-firefly-6201.sh` (r630-02) |
---

29
docs/03-deployment/OP_STACK_L2_AND_BESU138_BRIDGE_NOTES.md Normal file
View File

@@ -0,0 +1,29 @@
# OP Stack L2 ↔ Besu Chain 138 — integration notes
**Last updated:** 2026-04-01
**Purpose:** Optional follow-on after a **Standard Rollup** L2 is live on Ethereum. **Not** part of superchain-registry listing. **Does not** extend [XDC-Zero](CHAIN138_XDC_ZERO_BRIDGE_RUNBOOK.md) unless you design a separate pairing.
## Architecture reminder
| Network | Stack | Role in DBIS landscape |
|---------|--------|-------------------------|
| Besu **Chain 138** (EIP-155:138) | Besu + contracts + XDC-Zero | Core DBIS chain; XDC parent ↔ 138 via XDC-Relayer pattern |
| New **OP Stack L2** | `op-node` / `op-geth` + L1 Ethereum | Superchain-aligned rollup; **separate chain ID** from 138 |
## If you need asset or message flow L2 ↔ 138
1. **Treat as a new bridge program** — pick one or combine:
- **CCIP** (patterns in `smom-dbis-138` / [ALL_MAINNETS_DEPLOYMENT_RUNBOOK.md](../../smom-dbis-138/docs/deployment/ALL_MAINNETS_DEPLOYMENT_RUNBOOK.md)) once router/onramps exist for **your** L2 chain id.
- **Custom lock/mint** or **canonical bridge** contracts audited for your token policy.
2. **Update machine-readable config after addresses exist**
- [`config/token-mapping-multichain.json`](../../config/token-mapping-multichain.json) — add the L2 chain id and pairs.
- [`docs/11-references/CONTRACT_ADDRESSES_REFERENCE.md`](../11-references/CONTRACT_ADDRESSES_REFERENCE.md) / [`ADDRESS_MATRIX_AND_STATUS.md`](../11-references/ADDRESS_MATRIX_AND_STATUS.md) as your process requires.
3. **Keep XDC-Zero scope clear**
- XDC-Zero runbooks address **XDC Network ↔ Chain 138**.
- Do not repoint the 138↔XDC relayer to serve the OP L2 without a dedicated design review.
## Ordering
Complete [OP_STACK_STANDARD_ROLLUP_SUPERCHAIN_RUNBOOK.md](OP_STACK_STANDARD_ROLLUP_SUPERCHAIN_RUNBOOK.md) through **Phase 4** (registry) before investing in L2↔138 bridging.

150
docs/03-deployment/OP_STACK_STANDARD_ROLLUP_SUPERCHAIN_RUNBOOK.md Normal file
View File

@@ -0,0 +1,150 @@
# OP Stack Standard Rollup — Ethereum mainnet E2E (Superchain)
**Last updated:** 2026-04-01
**Purpose:** Operator end-to-end path for a **greenfield** OP Stack L2 on **Ethereum mainnet** targeting **Standard Rollup** status (`superchain_level = 2`) in [superchain-registry](https://github.com/ethereum-optimism/superchain-registry). Runs **in parallel** to Besu **Chain 138**; see [OP_STACK_L2_AND_BESU138_BRIDGE_NOTES.md](OP_STACK_L2_AND_BESU138_BRIDGE_NOTES.md).
**Scaffolding:** [`config/op-stack-superchain/`](../../config/op-stack-superchain/) · **Scripts:** [`scripts/op-stack/README.md`](../../scripts/op-stack/README.md)
**Official references:**
- [Deploy the OP Stack](https://docs.optimism.io/)
- [Blockspace and Standard Rollup Charters](https://docs.optimism.io/op-stack/protocol/blockspace-charter)
- [superchain-registry](https://docs.optimism.io/op-stack/protocol/superchain-registry)
- [op-deployer](https://docs.optimism.io/chain-operators/tools/op-deployer/overview)
- [Adding a chain (registry ops)](https://github.com/ethereum-optimism/superchain-registry/blob/main/docs/ops.md#adding-a-chain)
- [Standard Rollup Charter](https://github.com/ethereum-optimism/OPerating-manual/blob/main/policies/Standard%20Rollup%20Charter.md)
---
## Phase 0 — Prerequisites (before mainnet)
1. **Freeze governance inputs**
- Run `bash scripts/op-stack/fetch-standard-mainnet-toml.sh` and diff against prior cache.
- Record pins in `config/op-stack-superchain/pinned-versions.manifest.example.yaml` → copy to `deployed/pinned-versions.manifest.yaml` (gitignored).
2. **L2 chain ID**
- Choose a **unique** L2 chain ID **distinct from** Besu `138` unless you explicitly accept tooling collision. Document in the manifest.
3. **Keys and roles**
- Complete [`config/op-stack-superchain/key-custody-checklist.example.md`](../../config/op-stack-superchain/key-custody-checklist.example.md) internally.
- Align admin/upgrade roles with [standard-config-roles-mainnet.toml](https://github.com/ethereum-optimism/superchain-registry/blob/main/validation/standard/standard-config-roles-mainnet.toml).
4. **Capacity**
- L1 ETH for deployment, batch posting, proposals, challenger assumptions.
- HA capacity for sequencer pair, batcher, proposer, challenger, replicas.
5. **Standard Rollup constraints (summary)**
- Ethereum **canonical** DA (not alt-DA).
- No custom modified **system** contracts for Standard status.
- OP Stack **version / bytecode** must match governance-approved [standard-versions-mainnet.toml](https://github.com/ethereum-optimism/superchain-registry/blob/main/validation/standard/standard-versions-mainnet.toml).
### Recommended operator landing zone (Proxmox)
To keep deployment/runtime work **off** an operator workstation, provision the dedicated OP Stack CTs on **`r630-02`** using **`thin5`**:
- **5751** `op-stack-deployer-1` — `192.168.11.69` — `op-deployer`, `op-validator`, manifest and artifact handling
- **5752** `op-stack-ops-1` — `192.168.11.70` — sequencer/runtime bootstrap, service envs, systemd staging
Create and bootstrap them with:
```bash
bash scripts/deployment/provision-op-stack-operator-lxcs.sh
```
That script installs baseline tooling, enables SSH for `opuser`, and copies the repo's OP Stack scaffolding into `/opt/op-stack-bootstrap/` inside each CT.
Live landing-zone state as of **2026-04-01**:
- **5751** `op-stack-deployer-1` is provisioned on **`r630-02`** (`192.168.11.12`) at **`192.168.11.69`**
- **5752** `op-stack-ops-1` is provisioned on **`r630-02`** (`192.168.11.12`) at **`192.168.11.70`**
- the bootstrap cache is already seeded inside `/opt/op-stack-bootstrap/config/op-stack-superchain/cache/`, so a rerun does not need to re-fetch TOMLs unless `OP_STACK_REFRESH_TOMLS=1`
---
## Phase 1 — Sepolia rehearsal (gate before mainnet)
Use the **same** `op-deployer` / contract **release** you intend for mainnet.
1. Install tooling per [Optimism chain operator docs](https://docs.optimism.io/) (`op-deployer`, `op-node`, `op-reth`, `op-batcher`, `op-proposer`, `op-challenger`, `op-validator` — exact packages follow your pinned version). Keep `op-geth` only as a temporary legacy fallback.
2. Deploy L1 system contracts + L2 genesis on **Sepolia** via `op-deployer` (follow current CLI in upstream docs).
3. Run `op-validator` against generated artifacts; fix until clean.
4. Start **sequencer** (`op-node` + `op-reth`), **op-batcher**, **op-proposer**, **op-challenger**.
5. **E2E on test L2:** deposit / withdraw, failover drill (sequencer or batcher), 24–72h soak.
6. **Exit gate:** signed-off validator output, soak logs, frozen version manifest committed to CMDB.
**Checklist:** `bash scripts/op-stack/print-sepolia-rehearsal-checklist.sh`
---
## Phase 2 — Mainnet deploy
1. Verify manifest pins still match **mainnet** `standard-versions-mainnet.toml`.
2. Run `op-deployer` against **Ethereum mainnet**; capture all L1 addresses and L2 genesis / rollup config.
3. Run `op-validator` on **mainnet** artifacts **before** registry PR.
4. Record non-secret outputs under `config/op-stack-superchain/deployed/` (see [`deployed/README.md`](../../config/op-stack-superchain/deployed/README.md)).
**Checklist:** `bash scripts/op-stack/print-mainnet-deploy-checklist.sh`
---
## Phase 3 — Mainnet operations
1. Start sequencer (HA as required), batcher, proposer, challenger.
2. Expose **replica RPC** (and optional WS) with rate limits and monitoring: sync lag, L1 gas, batch submission, proposals, challenger health.
3. **Mainnet E2E:** small production deposit/withdraw; document comms and rollback posture.
**Checklist:** `bash scripts/op-stack/print-mainnet-ops-checklist.sh`
4. **systemd templates:** [`op-stack-op-reth.example.service`](../../config/systemd/op-stack-op-reth.example.service) (preferred execution), [`op-stack-sequencer.example.service`](../../config/systemd/op-stack-sequencer.example.service) (legacy `op-geth` fallback), [`op-stack-op-node.example.service`](../../config/systemd/op-stack-op-node.example.service) (consensus), [`op-stack-batcher.example.service`](../../config/systemd/op-stack-batcher.example.service), [`op-stack-proposer.example.service`](../../config/systemd/op-stack-proposer.example.service), [`op-stack-challenger.example.service`](../../config/systemd/op-stack-challenger.example.service) — adjust `User`, `WorkingDirectory`, `EnvironmentFile`, and binary paths to match your install.
---
## Phase 4 — Superchain registry (Standard status)
1. Follow [Adding a chain](https://github.com/ethereum-optimism/superchain-registry/blob/main/docs/ops.md#adding-a-chain): local validation, then PR to [superchain-registry](https://github.com/ethereum-optimism/superchain-registry).
2. Complete **Optimism Foundation** off-chain checks (unique chain ID, security configuration, governance authenticity) per [charter / docs](https://docs.optimism.io/op-stack/protocol/blockspace-charter).
3. Target `superchain_level = 2` only after automated + governance promotion.
4. After merge, use `--network` / `--op-network` flags per [registry hard-fork inheritance docs](https://docs.optimism.io/op-stack/protocol/superchain-registry).
**Checklist script:** `bash scripts/op-stack/registry-pr-checklist.sh`
---
## Phase 5 — Besu Chain 138 (optional)
Not required for Standard Rollup. See [OP_STACK_L2_AND_BESU138_BRIDGE_NOTES.md](OP_STACK_L2_AND_BESU138_BRIDGE_NOTES.md). **XDC-Zero** remains [CHAIN138_XDC_ZERO_BRIDGE_RUNBOOK.md](CHAIN138_XDC_ZERO_BRIDGE_RUNBOOK.md) (XDC ↔ Besu 138).
---
## E2E completion table
| Gate | Evidence |
|------|----------|
| Sepolia | `op-validator` OK, soak logs, frozen manifest |
| Mainnet L1/L2 | Address list + rollup/genesis artifacts |
| Live stack | Sequencer, batcher, proposer, challenger healthy |
| Mainnet validate | `op-validator` on mainnet configs |
| Registry | PR merged; `superchain_level = 2` when promoted |
| Ops | Runbooks, monitoring, incident contacts |
---
## Related repo docs
| Topic | Doc |
|-------|-----|
| Besu Chain 138 + XDC | [CHAIN138_XDC_ZERO_BRIDGE_RUNBOOK.md](CHAIN138_XDC_ZERO_BRIDGE_RUNBOOK.md) |
| CCIP (138 ↔ public L1/L2s) | [../07-ccip/](../07-ccip/), `smom-dbis-138` deployment runbooks |

19
docs/03-deployment/PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK.md
View File

@@ -9,9 +9,14 @@
## C.1 Deploy or bridge cW* tokens per chain
Chains (current pool-matrix scope): 1, 10, 56, 100, 137, 250, 324, 8453, 42161, 42220, 43114, 59144.
Note: Wemix (1111) may still be part of bridge-coverage phases, but it is not currently in `cross-chain-pmm-lps/config/pool-matrix.json`.
Tokens: cWUSDT, cWUSDC, cWAUSDT, cWEURC, cWEURT, cWUSDW (per pool-matrix).
Chains (current repo rollout scope): 1, 10, 25, 56, 100, 137, 42161, 42220, 43114, 8453, 1111.
Tokens (current pool-matrix): `cWUSDT`, `cWUSDC`, `cWAUSDT`, `cWEURC`, `cWEURT`, `cWUSDW`, `cWGBPC`, `cWGBPT`, `cWAUDC`, `cWJPYC`, `cWCHFC`, `cWCADC`, `cWXAUC`, `cWXAUT`.
Important update:
- the pool matrix now covers the full GRU Wave 1 wrapped set
- this closes the design/config gap for Wave 1 public liquidity
- it does **not** mark those pools live until addresses are written into `deployment-status.json`
**Steps:** (1) Use cross-chain-pmm-lps config/chains.json and pool-matrix.json. (2) Deploy CompliantWrappedToken (cW*) per chain or use bridge; set addresses in deployment-status.json and smom-dbis-138/.env. (3) Ref: TOKEN_CONTRACT_DEPLOYMENTS_REMAINING §3, CW_DEPLOY_AND_WIRE_RUNBOOK.
@@ -19,7 +24,13 @@ Tokens: cWUSDT, cWUSDC, cWAUSDT, cWEURC, cWEURT, cWUSDW (per pool-matrix).
## C.2 Create and fund PMM edge pools per chain
**Steps:** (1) From pool-matrix poolsFirst (e.g. cWUSDT/USDC), create DODO PMM or Uniswap pools per chain. (2) Add initial liquidity. (3) Record pool addresses in deployment-status.json chains[chainId].pmmPools. (4) Ensure token-aggregation/heatmap use deployment-status.
**Steps:** (1) From pool-matrix `poolsFirst` (for example `cWEURC/USDC`, `cWGBPC/USDT`, `cWXAUC/USDC`), create DODO PMM or Uniswap pools per chain. (2) Add initial liquidity. (3) Record pool addresses in deployment-status.json `chains[chainId].pmmPools`. (4) Ensure token-aggregation/heatmap use deployment-status.
Use the deployment queue for the remaining operator breakdown:
```bash
bash scripts/verify/check-gru-v2-deployment-queue.sh
```
**Ref:** LIQUIDITY_POOLS_MASTER_MAP § Public-chain cW*, pool-matrix.json.

8
docs/03-deployment/PMM_FULL_MESH_AND_PUBLIC_SINGLE_SIDED_PLAN.md
View File

@@ -1,5 +1,7 @@
# PMM Full Mesh (Chain 138) and Single-Sided LPs (Public Networks) — Plan
> Historical note (2026-04-02): this document spans the full-mesh plan as well as the current live stable stack. The canonical Chain 138 PMM stable stack is `DODOPMMIntegration=0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895` and `DODOPMMProvider=0x3f729632E9553EBacCdE2e9b4c8F2B285b014F2e`. Public XAU pools remain on the older PMM phase until explicitly migrated.
**Purpose:** Define and run the full PMM pool mesh on Chain 138 and the single-sided LP deployment on public networks for aggregator and DEX routing.
---
@@ -16,14 +18,14 @@
- Adds up to **12** pools (12×1) when `WETH_ADDRESS_138` (or `QUOTE_TOKEN_ADDRESS`) is configured.
- **official vs ETH (on-chain as WETH, optional):** official USDT/WETH and official USDC/WETH.
- Adds up to **2** pools when official token addresses and WETH are configured.
- **Already created:** The three legacy pools (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC) are created separately; the script skips any pair that already has a pool.
- **Already created on the current stable stack:** cUSDT/cUSDC `0x9e89bAe009adf128782E19e8341996c596ac40dC`, cUSDT/USDT `0x866Cb44b59303d8dc5f4F9E3E7A8e8b0bf238d66`, cUSDC/USDC `0xc39B7D0F40838cbFb54649d327f49a6DAC964062`; the script skips any pair that already has a pool.
### 1.2 Contracts and roles
| Contract | Address (Chain 138) | Role |
|----------|---------------------|------|
| DODOPMMIntegration | `0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d` | `createPool(base, quote, ...)`; `swapExactIn(pool, tokenIn, amountIn, minAmountOut)` for generic routing |
| DODOPMMProvider | `0x5CAe6Ce155b7f08D3a956F5Dc82fC9945f29B381` | `registerPool(tokenIn, tokenOut, pool)`; `executeSwap` uses `swapExactIn` for any registered pool |
| DODOPMMIntegration | `0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895` | `createPool(base, quote, ...)`; `swapExactIn(pool, tokenIn, amountIn, minAmountOut)` for generic routing on the canonical stable stack |
| DODOPMMProvider | `0x3f729632E9553EBacCdE2e9b4c8F2B285b014F2e` | `registerPool(tokenIn, tokenOut, pool)`; `executeSwap` uses `swapExactIn` for any registered pool on the canonical stable stack |
- Deployer (or the account that holds **POOL_MANAGER_ROLE** on the integration and **POOL_MANAGER_ROLE** on the provider) must run pool creation and registration.
- **Generic routing:** `DODOPMMIntegration.swapExactIn` allows any registered pool to be used for swaps; `DODOPMMProvider.executeSwap` routes through it when the pair is not one of the six legacy pairs.

16
docs/03-deployment/PMM_POOLS_FUNDING_PLAN.md
View File

@@ -1,10 +1,10 @@
# PMM Pools Funding Plan - Chain 138
> Historical note (2026-03-26): this funding plan documents an earlier three-pool PMM phase. The live canonical Chain 138 PMM stack is `DODOPMMIntegration=0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d` and `DODOPMMProvider=0x5CAe6Ce155b7f08D3a956F5Dc82fC9945f29B381`. Current public funded pool addresses are maintained in [LIQUIDITY_POOLS_MASTER_MAP.md](../11-references/LIQUIDITY_POOLS_MASTER_MAP.md).
> Historical note (2026-04-02): this funding plan documents an earlier three-pool PMM phase. The live canonical Chain 138 PMM stack is `DODOPMMIntegration=0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895` and `DODOPMMProvider=0x3f729632E9553EBacCdE2e9b4c8F2B285b014F2e`. Current public funded pool addresses are maintained in [LIQUIDITY_POOLS_MASTER_MAP.md](../11-references/LIQUIDITY_POOLS_MASTER_MAP.md).
**Purpose:** Step-by-step plan to fund the three DODO PMM liquidity pools on Chain 138.
**Deployer:** `0x4A666F96fC8764181194447A7dFdb7d471b301C8`
**Integration:** `DODOPMMIntegration` at `0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d`
**Integration:** `DODOPMMIntegration` at `0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895`
---
@@ -12,9 +12,9 @@
| Pool | Base token | Quote token | Pool address | Fund when |
|------|------------|-------------|--------------|-----------|
| **1. cUSDT/cUSDC** | cUSDT | cUSDC | `0xff8d3b8fDF7B112759F076B69f4271D4209C0849` | Deployer has cUSDT + cUSDC (mintable) |
| **2. cUSDT/USDT** | cUSDT | USDT (official) | `0x6fc60DEDc92a2047062294488539992710b99D71` | Deployer has cUSDT + official USDT |
| **3. cUSDC/USDC** | cUSDC | USDC (official) | `0x9f74Be42725f2Aa072a9E0CdCce0E7203C510263` | Deployer has cUSDC + official USDC |
| **1. cUSDT/cUSDC** | cUSDT | cUSDC | `0x9e89bAe009adf128782E19e8341996c596ac40dC` | Deployer has cUSDT + cUSDC (mintable) |
| **2. cUSDT/USDT** | cUSDT | USDT (official mirror) | `0x866Cb44b59303d8dc5f4F9E3E7A8e8b0bf238d66` | Deployer has cUSDT + official USDT mirror |
| **3. cUSDC/USDC** | cUSDC | USDC (official mirror) | `0xc39B7D0F40838cbFb54649d327f49a6DAC964062` | Deployer has cUSDC + official USDC mirror |
- **Pool 1** uses only c* tokens; you can mint both on Chain 138 and fund fully.
- **Pools 2 and 3** need "official" USDT/USDC on 138 (set in DODOPMMIntegration at deploy time). If those are deployer-owned mocks, mint them too; otherwise fund only from existing balance.
@@ -85,8 +85,8 @@ From repo root, with smom-dbis-138/.env sourced:
```bash
cd smom-dbis-138 && source .env
INT=0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d
POOL1=0xff8d3b8fDF7B112759F076B69f4271D4209C0849
INT=0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895
POOL1=0x9e89bAe009adf128782E19e8341996c596ac40dC
CUSDT=0x93E66202A11B1772E55407B32B44e5Cd8eda7f22
CUSDC=0xf22258f57794CC8E06237084b353Ab30fFfa640b
RPC="$RPC_URL_138"
@@ -106,7 +106,7 @@ cast send "$INT" "addLiquidity(address,uint256,uint256)" "$POOL1" "$BASE_AMOUNT"
```bash
cd smom-dbis-138 && source .env
export POOL_CUSDTCUSDC=0xff8d3b8fDF7B112759F076B69f4271D4209C0849
export POOL_CUSDTCUSDC=0x9e89bAe009adf128782E19e8341996c596ac40dC
export ADD_LIQUIDITY_BASE_AMOUNT=1000000000000
export ADD_LIQUIDITY_QUOTE_AMOUNT=1000000000000

22
docs/03-deployment/PRE_DEPLOYMENT_CHECKLIST.md
View File

@@ -1,6 +1,6 @@
# Pre-Deployment Checklist — DODO PMM, Pools, Provider, Router & APIs
**Last Updated:** 2026-03-26
**Last Updated:** 2026-04-02
**Purpose:** Single source of truth for component status and ordered steps required before deployment (Chain 138).
**See also:** [DEPLOYMENT_ORDER_OF_OPERATIONS.md](DEPLOYMENT_ORDER_OF_OPERATIONS.md) — full deployment order (Phase 0–6) and remaining recommendations.
@@ -18,11 +18,11 @@
| Component | Status | Address / Notes |
|-----------|--------|-----------------|
| **DODOPMMIntegration** | ✅ Deployed | Chain 138 canonical corrected stack: `0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d`. |
| **PMM pools** | ✅ Reconciled | 104 desired-state pools aligned; live funded public pools include cUSDT/cUSDC `0xff8d3b8fDF7B112759F076B69f4271D4209C0849`, cUSDT/USDT `0x6fc60DEDc92a2047062294488539992710b99D71`, cUSDC/USDC `0x9f74Be42725f2Aa072a9E0CdCce0E7203C510263`, cUSDT/cXAUC `0x94316511621430423a2cff0C036902BAB4aA70c2`, cUSDC/cXAUC `0x7867D58567948e5b9908F1057055Ee4440de0851`, cEURT/cXAUC `0x505403093826D494983A93b43Aa0B8601078A44e`. |
| **DODOPMMProvider** | ✅ Deployed | `0x5CAe6Ce155b7f08D3a956F5Dc82fC9945f29B381`; 104/104 desired-state routes aligned. |
| **EnhancedSwapRouter** | ❌ Not deployed | Mainnet-only script today; for Chain 138 deploy when Uniswap/Balancer pools exist; set quoter/poolId. |
| **Token-aggregation API** | ✅ Implemented, runnable | Single-hop quotes; can index DODO once pools exist (set `CHAIN_138_DODO_PMM_INTEGRATION`). |
| **DODOPMMIntegration** | ✅ Deployed | Chain 138 canonical official DODO V2 DVM-backed stack: `0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895`. |
| **PMM pools** | ✅ Reconciled | 104 desired-state pools aligned; live funded public pools include cUSDT/cUSDC `0x9e89bAe009adf128782E19e8341996c596ac40dC`, cUSDT/USDT `0x866Cb44b59303d8dc5f4F9E3E7A8e8b0bf238d66`, cUSDC/USDC `0xc39B7D0F40838cbFb54649d327f49a6DAC964062`, plus retained XAU public pools. |
| **DODOPMMProvider** | ✅ Deployed | `0x3f729632E9553EBacCdE2e9b4c8F2B285b014F2e`; canonical stable routes aligned. |
| **EnhancedSwapRouter** | ❌ Not deployed | Chain 138 deployment script exists, but live WETH-to-stable routes and non-DODO providers are still not configured. |
| **Token-aggregation API** | ✅ Implemented, runnable | Single-hop quotes; now persists the canonical Chain 138 DODO pool set on the live explorer deployment. |
| **Bridge quote (swap+bridge+swap)** | ✅ Implemented | `POST /api/bridge/quote`; on-chain coordinator optional. |
| **Cross-chain cW* mesh** | Design/tooling only | Edge pools and bots not deployed. |
@@ -42,7 +42,7 @@
- [ ] **Env set in `smom-dbis-138/.env` only**
Required: `PRIVATE_KEY`, `RPC_URL_138` (must be Core RPC, not Public).
For PMM: `DODO_PMM_INTEGRATION_ADDRESS=0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d`, `DODO_PMM_PROVIDER_ADDRESS=0x5CAe6Ce155b7f08D3a956F5Dc82fC9945f29B381`.
For PMM: `DODO_PMM_INTEGRATION_ADDRESS=0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895`, `DODO_PMM_PROVIDER_ADDRESS=0x3f729632E9553EBacCdE2e9b4c8F2B285b014F2e`.
Optional: `GAS_PRICE_138` or `GAS_PRICE` (default 1 gwei).
After TransactionMirror deploy: set `TRANSACTION_MIRROR_ADDRESS` from script output.
Verify: `cd smom-dbis-138 && ./scripts/deployment/check-env-required.sh`.
@@ -100,7 +100,7 @@ This deploys TransactionMirror then creates **only** the cUSDT/cUSDC pool. For m
```bash
cd smom-dbis-138
export DODO_PMM_INTEGRATION="${DODO_PMM_INTEGRATION_ADDRESS:-0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d}"
export DODO_PMM_INTEGRATION="${DODO_PMM_INTEGRATION_ADDRESS:-0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895}"
export RPC_URL_138="${RPC_URL_138:-http://192.168.11.211:8545}"
export GAS_PRICE="${GAS_PRICE_138:-${GAS_PRICE:-1000000000}}"
@@ -149,7 +149,7 @@ Current deploy script is mainnet-only (`block.chainid == 1`). For Chain 138:
### Step 6: Token-aggregation API (DODO indexing)
- Ensure `CHAIN_138_DODO_PMM_INTEGRATION=0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d` (or equivalent) is set where the token-aggregation service runs. Optional: `CHAIN_138_DODO_POOL_MANAGER`, `CHAIN_138_DODO_VENDING_MACHINE` (see token-aggregation `.env.example` and [dex-factories.ts](../../smom-dbis-138/services/token-aggregation/src/config/dex-factories.ts)).
- Ensure `CHAIN_138_DODO_PMM_INTEGRATION=0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895` (or equivalent) is set where the token-aggregation service runs. Optional: `CHAIN_138_DODO_POOL_MANAGER`, `CHAIN_138_DODO_VENDING_MACHINE` (see token-aggregation `.env.example` and [dex-factories.ts](../../smom-dbis-138/services/token-aggregation/src/config/dex-factories.ts)).
- Once pools exist, the service can index DODO pools from DODOPMMIntegration and expose single-hop quotes.
### Step 7: On-chain verification
@@ -160,7 +160,7 @@ After any new deployment:
./scripts/verify/check-contracts-on-chain-138.sh [RPC_URL]
```
Target: all expected addresses (e.g. **64/64** per check-contracts-on-chain-138.sh when TransactionMirror, DODO pools, vault/reserve, CompliantFiatTokens, and ISO20022Router are present). Update [REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md](REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md) and [CONTRACT_ADDRESSES_REFERENCE.md](../11-references/CONTRACT_ADDRESSES_REFERENCE.md) with new pool and provider addresses.
Target: all expected addresses (e.g. **67/67** per check-contracts-on-chain-138.sh when TransactionMirror, DODO pools, vault/reserve, CompliantFiatTokens, ISO20022Router, and the cross-chain flash trio are present). Update [REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md](REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md) and [CONTRACT_ADDRESSES_REFERENCE.md](../11-references/CONTRACT_ADDRESSES_REFERENCE.md) with new pool, provider, and flash-infrastructure addresses.
---
@@ -173,7 +173,7 @@ Target: all expected addresses (e.g. **64/64** per check-contracts-on-chain-138.
| `smom-dbis-138/script/dex/CreateCUSDTUSDTPool.s.sol` | Create cUSDT/USDT pool. |
| `smom-dbis-138/script/dex/CreateCUSDCUSDCPool.s.sol` | Create cUSDC/USDC pool. |
| `smom-dbis-138/script/liquidity/DeployDODOPMMProvider.s.sol` | Deploy DODOPMMProvider (then register pools). |
| `smom-dbis-138/script/bridge/trustless/DeployEnhancedSwapRouter.s.sol` | Deploy EnhancedSwapRouter (mainnet-only; Chain 138 needs env/config). |
| `smom-dbis-138/script/bridge/trustless/DeployEnhancedSwapRouter.s.sol` | Legacy router deployment path (mainnet-oriented). The live Chain 138 execution surface is `EnhancedSwapRouterV2` plus the funded pilot-compatible venue layer; verify with `scripts/verify/check-chain138-pilot-dex-venues.sh`. |
| `scripts/verify/check-contracts-on-chain-138.sh` | Verify expected contract addresses on Chain 138. |
---

224
docs/03-deployment/PROXMOX_CSTAR_TO_CW_BRIDGE_RUNBOOK.md Normal file
View File

@@ -0,0 +1,224 @@
# Proxmox Runbook: Bridge Any c* Asset to cW*
**Created:** 2026-04-06
**Purpose:** Single operator runbook for taking any canonical Chain 138 `c*` asset and bridging it to its public-chain `cW*` mirror using the dedicated GRU transport stack.
This consolidates the repo’s existing cW deployment and bridge material into one generic workflow for Proxmox operators. It is the shortest path from “we want `cEURC -> cWEURC` on Polygon” to exact wiring and exact send commands.
Related:
- [CW_DEPLOY_AND_WIRE_RUNBOOK.md](../07-ccip/CW_DEPLOY_AND_WIRE_RUNBOOK.md)
- [CW_BRIDGE_APPROACH.md](../07-ccip/CW_BRIDGE_APPROACH.md)
- [ROUTES_NO_PREFUNDED_BRIDGE_REQUIRED.md](../11-references/ROUTES_NO_PREFUNDED_BRIDGE_REQUIRED.md)
- [token-mapping-multichain.json](../../config/token-mapping-multichain.json)
## 1. Model
The generic outbound path is:
1. User approves the Chain 138 canonical token to `CWMultiTokenBridgeL1`.
2. User calls `CWMultiTokenBridgeL1.lockAndSend(canonicalToken, destinationSelector, recipient, amount)`.
3. Chain 138 locks the canonical `c*` balance in escrow.
4. The destination `CWMultiTokenBridgeL2` receives the CCIP message.
5. The destination bridge mints the configured `cW*` mirror to the recipient.
The generic return path is the reverse:
1. User approves the destination `cW*` token to `CWMultiTokenBridgeL2`.
2. User calls `CWMultiTokenBridgeL2.burnAndSend(mirroredToken, 138, recipient, amount)`.
3. The destination bridge burns `cW*`.
4. Chain 138 receives the return message.
5. `CWMultiTokenBridgeL1` releases the escrowed canonical `c*` back to the recipient.
## 2. Supported generic asset families
The repo already maps these generic canonical-to-mirror lanes in [token-mapping-multichain.json](../../config/token-mapping-multichain.json):
- `cUSDT -> cWUSDT`
- `cUSDC -> cWUSDC`
- `cAUSDT -> cWAUSDT`
- `cUSDW -> cWUSDW`
- `cEURC -> cWEURC`
- `cEURT -> cWEURT`
- `cGBPC -> cWGBPC`
- `cGBPT -> cWGBPT`
- `cAUDC -> cWAUDC`
- `cJPYC -> cWJPYC`
- `cCHFC -> cWCHFC`
- `cCADC -> cWCADC`
- `cXAUC -> cWXAUC`
- `cXAUT -> cWXAUT`
Important nuance:
- The generic wiring model is reusable for all of those symbols.
- The repo’s currently proven live end-to-end corridors are still narrower than the full design surface. Mainnet `cUSDT -> cWUSDT`, Mainnet `cUSDC -> cWUSDC`, and Avalanche `cUSDT -> cWUSDT` are the clearest proven references.
- Other generic lanes should be treated as operator-wirable and testable, but not automatically “production proven” until they have their own canary proof.
## 3. Prerequisites
Before bridging a new lane, make sure all of this is true:
- `smom-dbis-138/.env` has `PRIVATE_KEY`, `RPC_URL_138`, and the destination RPC URL.
- `smom-dbis-138/.env` has the destination selector, for example `ETH_MAINNET_SELECTOR`, `POLYGON_SELECTOR`, or `AVALANCHE_SELECTOR`.
- `smom-dbis-138/.env` has `CW_L1_BRIDGE_CHAIN138` or `CHAIN138_L1_BRIDGE`.
- `smom-dbis-138/.env` has `CW_BRIDGE_<CHAIN>` for the destination `CWMultiTokenBridgeL2`.
- The destination `cW*` token is already deployed and recorded in `.env` and [token-mapping-multichain.json](../../config/token-mapping-multichain.json).
- The destination bridge has `MINTER_ROLE` and `BURNER_ROLE` on that `cW*` token.
If the destination `cW*` suite is not deployed yet, use:
```bash
./scripts/deployment/run-cw-remaining-steps.sh --deploy
```
Then set the emitted `CW*_<CHAIN>` addresses in `smom-dbis-138/.env` and refresh the mapping:
```bash
./scripts/deployment/run-cw-remaining-steps.sh --update-mapping
./scripts/deployment/run-cw-remaining-steps.sh --verify
```
## 4. Generic wiring
Use the new generic helper from repo root:
```bash
./scripts/deployment/configure-cstar-cw-bridge-pair.sh --chain <CHAIN> --asset <c*>
```
Examples:
```bash
./scripts/deployment/configure-cstar-cw-bridge-pair.sh --chain MAINNET --asset cUSDT
./scripts/deployment/configure-cstar-cw-bridge-pair.sh --chain POLYGON --asset cEURC
./scripts/deployment/configure-cstar-cw-bridge-pair.sh --chain AVALANCHE --asset cUSDC --max-outstanding 1000000000000 --freeze
```
Broadcast the writes only after the dry-run looks right:
```bash
./scripts/deployment/configure-cstar-cw-bridge-pair.sh --chain POLYGON --asset cEURC --execute
./scripts/deployment/configure-cstar-cw-bridge-pair.sh --chain AVALANCHE --asset cUSDC --max-outstanding 1000000000000 --freeze --execute
```
What the script does:
1. Resolves the canonical `c*` address from [token-mapping-multichain.json](../../config/token-mapping-multichain.json).
2. Resolves the destination `cW*` token from `.env` and mapping.
3. Calls `CWMultiTokenBridgeL2.configureTokenPair(canonical, mirrored)`.
4. Calls `CWMultiTokenBridgeL1.configureDestination(canonical, selector, l2Bridge, true)`.
5. Calls `CWMultiTokenBridgeL2.configureDestination(138, l1Bridge, true)`.
6. Calls `CWMultiTokenBridgeL1.configureSupportedCanonicalToken(canonical, true)`.
7. Optionally calls `CWMultiTokenBridgeL1.setMaxOutstanding(...)`.
8. Optionally calls `CWMultiTokenBridgeL2.freezeTokenPair(...)` and `freezeDestination(138)`.
## 5. Generic outbound send
Use the new send helper from repo root:
```bash
./scripts/bridge/bridge-cstar-to-cw.sh --asset <c*> --chain <CHAIN> --amount <human> --recipient <address>
```
Examples:
```bash
./scripts/bridge/bridge-cstar-to-cw.sh --asset cUSDT --chain MAINNET --amount 1 --recipient 0x1234...
./scripts/bridge/bridge-cstar-to-cw.sh --asset cEURC --chain POLYGON --amount 250.5 --recipient 0x1234...
./scripts/bridge/bridge-cstar-to-cw.sh --asset cXAUC --chain AVALANCHE --raw-amount 1000000 --recipient 0x1234...
```
Dry-run output includes:
- canonical and mirrored token addresses
- source bridge address
- destination selector
- converted raw amount
- current source-token allowance
- bridge fee quote
- fee mode: native or ERC-20 fee token
- exact `cast send` commands that would be run
To let the helper auto-approve and then submit:
```bash
./scripts/bridge/bridge-cstar-to-cw.sh --asset cEURC --chain POLYGON --amount 250.5 --recipient 0x1234... --approve --execute
```
What the send helper does:
1. Resolves the canonical 138 token and destination `cW*` mirror from [token-mapping-multichain.json](../../config/token-mapping-multichain.json).
2. Reads `decimals()` from the canonical token and converts `--amount` to raw units.
3. Reads `feeToken()` and `calculateFee(...)` from `CWMultiTokenBridgeL1`.
4. Checks allowance on the canonical token.
5. If the bridge uses an ERC-20 fee token, checks that allowance too.
6. If `--approve` is set, submits the approvals needed.
7. Calls `lockAndSend(address,uint64,address,uint256)`.
## 6. Manual casts
If you want the raw contract calls without the helper:
Approve the canonical token:
```bash
cast send "$CUSDC_138" "approve(address,uint256)" "$CW_L1_BRIDGE_CHAIN138" 1000000 \
--rpc-url "$RPC_URL_138" --private-key "$PRIVATE_KEY" --legacy
```
Quote the fee:
```bash
cast call "$CW_L1_BRIDGE_CHAIN138" "calculateFee(address,uint64,address,uint256)(uint256)" \
"$CUSDC_138" "$POLYGON_SELECTOR" 0xRecipient 1000000 --rpc-url "$RPC_URL_138"
```
Send with native fee mode:
```bash
cast send "$CW_L1_BRIDGE_CHAIN138" "lockAndSend(address,uint64,address,uint256)" \
"$CUSDC_138" "$POLYGON_SELECTOR" 0xRecipient 1000000 \
--rpc-url "$RPC_URL_138" --private-key "$PRIVATE_KEY" --legacy --value "$FEE_WEI"
```
## 7. Verification
After wiring:
```bash
./scripts/deployment/run-cw-remaining-steps.sh --verify
```
Useful direct checks:
```bash
cast call "$CW_L1_BRIDGE_CHAIN138" "supportedCanonicalToken(address)(bool)" "$CUSDC_138" --rpc-url "$RPC_URL_138"
cast call "$CW_L1_BRIDGE_CHAIN138" "destinations(address,uint64)((address,bool))" "$CUSDC_138" "$POLYGON_SELECTOR" --rpc-url "$RPC_URL_138"
cast call "$CW_BRIDGE_POLYGON" "canonicalToMirrored(address)(address)" "$CUSDC_138" --rpc-url "$POLYGON_MAINNET_RPC"
cast call "$CWUSDC_POLYGON" "hasRole(bytes32,address)(bool)" "$(cast keccak 'MINTER_ROLE')" "$CW_BRIDGE_POLYGON" --rpc-url "$POLYGON_MAINNET_RPC"
```
After a send:
```bash
cast call "$CWUSDC_POLYGON" "balanceOf(address)(uint256)" 0xRecipient --rpc-url "$POLYGON_MAINNET_RPC"
```
## 8. Operational notes
- `CWMultiTokenBridgeL1` is the correct generic sender for canonical `c*`.
- `CWMultiTokenBridgeL2` is the correct generic receiver for mirrored `cW*`.
- `CCIPWETH9Bridge` and `CCIPWETH10Bridge` are not the generic `c* -> cW*` path.
- For strict hard-peg lanes, set `maxOutstanding`, attach the reserve verifier, and freeze the destination config after validation.
- For ALL Mainnet, keep using the dedicated adapter model rather than assuming a selector-driven public-chain CW bridge path.
## 9. Recommended operator sequence
1. Deploy missing destination `cW*` tokens if needed.
2. Refresh [token-mapping-multichain.json](../../config/token-mapping-multichain.json).
3. Run `configure-cstar-cw-bridge-pair.sh` in dry-run mode.
4. Run the same command with `--execute`.
5. Run `bridge-cstar-to-cw.sh` in dry-run mode with a canary amount.
6. Run the same send with `--approve --execute`.
7. Verify the destination mint and record the tx hash in the relevant lane runbook.

16
docs/03-deployment/PROXMOX_VE_OPERATIONAL_DEPLOYMENT_TEMPLATE.md
View File

@@ -1,6 +1,6 @@
# Proxmox VE — Operational deployment template
**Last Updated:** 2026-03-25
**Last Updated:** 2026-04-08
**Status:** Active — ties hypervisors, LAN/WAN, cluster peering, Chain 138 Besu tiers, NPMplus ingress, FQDNs, and deployment gates into one place.
**Machine-readable:** [`config/proxmox-operational-template.json`](../../config/proxmox-operational-template.json) (sync when you change VMIDs/IPs/FQDNs).
@@ -16,11 +16,15 @@
## 1. Proxmox VE hosts (management)
| Hostname | MGMT IP | Proxmox UI | Cluster | Role (target) |
|----------|---------|------------|---------|----------------|
| ml110 | 192.168.11.10 | https://192.168.11.10:8006 | h (legacy) | Planned WAN aggregator (OPNsense/pfSense); **migrate CT/VM off before repurpose** |
| r630-01 | 192.168.11.11 | https://192.168.11.11:8006 | h | Primary: Chain 138 RPC/CCIP-adjacent workloads, Sankofa Phoenix stack, much of DBIS |
| r630-02 | 192.168.11.12 | https://192.168.11.12:8006 | h | Firefly, MIM4U, Mifos LXC, extra NPMplus instances, supporting infra |
| Hostname | **Canonical FQDN** | MGMT IP | Proxmox UI | Cluster | Role (target) |
|----------|---------------------|---------|------------|---------|----------------|
| ml110 | **ml110.sankofa.nexus** | 192.168.11.10 | https://192.168.11.10:8006 | h (legacy) | Planned WAN aggregator (OPNsense/pfSense); **migrate CT/VM off before repurpose** |
| r630-01 | **r630-01.sankofa.nexus** | 192.168.11.11 | https://192.168.11.11:8006 | h | Primary: Chain 138 RPC/CCIP-adjacent workloads, Sankofa Phoenix stack, much of DBIS |
| r630-02 | **r630-02.sankofa.nexus** | 192.168.11.12 | https://192.168.11.12:8006 | h | Firefly, MIM4U, Mifos LXC, extra NPMplus instances, supporting infra |
| r630-03 | **r630-03.sankofa.nexus** | 192.168.11.13 | https://192.168.11.13:8006 | h | Spare + storage thin pools; Besu **2102**, validators **1003–1004**, sentries **1503–1508**, ThirdWeb **2400–2403**, **2301** when placed here (see `ALL_VMIDS_ENDPOINTS.md`) |
| r630-04 | **r630-04.sankofa.nexus** | 192.168.11.14 | https://192.168.11.14:8006 | h | Spare + Ceph OSDs |
**Read-only inventory diff:** `bash scripts/verify/audit-proxmox-operational-template.sh` — defaults to **five** management IPs from `config/ip-addresses.conf` (ML110 + r630-01..04). Hosts without SSH still **SKIP**; include **r630-03** so template VMIDs on that node are not false “missing.”
**LAN:** 192.168.11.0/24, gateway **192.168.11.1** (UDM Pro), VLAN 11. Extended node IP plan (r630-03 …): `config/ip-addresses.conf` comments.

2
docs/03-deployment/PUBLIC_SECTOR_LIVE_DEPLOYMENT_CHECKLIST.md
View File

@@ -40,7 +40,7 @@ This checklist tracks **proxmox-repo automation** and **sibling repos** (`../com
| RPC `192.168.11.221:8545` / `192.168.11.211:8545` | HTTP 201 |
| SSH `root@192.168.11.10` / `.11` | OK (BatchMode) |
| `./scripts/run-completable-tasks-from-anywhere.sh` | Exit 0 |
| `./scripts/verify/check-contracts-on-chain-138.sh` | **64/64** present |
| `./scripts/verify/check-contracts-on-chain-138.sh` | **67/67** present |
| `E2E_ACCEPT_502_INTERNAL=1 ./scripts/verify/verify-end-to-end-routing.sh` | 37 domains, 0 failed; report under `docs/04-configuration/verification-evidence/e2e-verification-20260325_165153/` |
| `https://phoenix.sankofa.nexus/`, `https://sankofa.nexus/` | HTTP 200 |
| `http://192.168.11.50:4000/health`, `:51:3000`, `:52:8080/health/ready` | No HTTP response from operator host (hosts ping; services may be down, firewalled, or not bound) — **re-check on Proxmox / in-container** |

12
docs/03-deployment/RECOMMENDATIONS_AND_FIXES_BEFORE_DEPLOY.md
View File

@@ -1,8 +1,8 @@
# Recommendations and Fixes Before Deploying Smart Contracts and PMM Pools
> Historical note (2026-03-26): this checklist spans earlier deployment phases and may reference superseded PMM workflows. The current canonical Chain 138 PMM stack is `DODOPMMIntegration=0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d` and `DODOPMMProvider=0x5CAe6Ce155b7f08D3a956F5Dc82fC9945f29B381`. Use [ADDRESS_MATRIX_AND_STATUS.md](../11-references/ADDRESS_MATRIX_AND_STATUS.md) for live operations.
> Historical note (2026-04-02): this checklist spans earlier deployment phases and may reference superseded PMM workflows. The current canonical Chain 138 PMM stack is `DODOPMMIntegration=0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895` and `DODOPMMProvider=0x3f729632E9553EBacCdE2e9b4c8F2B285b014F2e`. Use [ADDRESS_MATRIX_AND_STATUS.md](../11-references/ADDRESS_MATRIX_AND_STATUS.md) for live operations.
**Last Updated:** 2026-02-27
**Last Updated:** 2026-04-02
**Purpose:** Single checklist of all **recommendations** and **required fixes** to complete before deploying smart contracts and PMM pools on Chain 138 (and related chains). Use this with [DEPLOYMENT_ORDER_OF_OPERATIONS.md](DEPLOYMENT_ORDER_OF_OPERATIONS.md) and [PRE_DEPLOYMENT_CHECKLIST.md](PRE_DEPLOYMENT_CHECKLIST.md).
**Related:** [TODOS_CONSOLIDATED](../00-meta/TODOS_CONSOLIDATED.md) § First (0a–0c) | [CONTRACT_DEPLOYMENT_RUNBOOK.md](CONTRACT_DEPLOYMENT_RUNBOOK.md) | [RECOMMENDATIONS_OPERATOR_CHECKLIST](../00-meta/RECOMMENDATIONS_OPERATOR_CHECKLIST.md)
@@ -17,11 +17,11 @@ These must be satisfied before **any** Chain 138 deployment. Run preflight once;
| # | Item | Action / fix |
|---|------|--------------|
| **1.1** | **Run preflight** | From repo root: `./scripts/deployment/preflight-chain138-deploy.sh [--cost]`. Verifies: dotenv exists, required env keys, RPC returns chainId 0x8a (138), deployer nonce (warns if stuck). Use `--cost` for gas/cost estimate. |
| **1.1** | **Run preflight** | From repo root: `./scripts/deployment/preflight-chain138-deploy.sh [--cost]`. Verifies: dotenv exists, required env keys, RPC returns chainId 0x8a (138), deployer nonce (warns if stuck). Use `--cost` for gas/cost estimate. If Core RPC `192.168.11.211:8545` is still reopening RocksDB after tx-pool maintenance, you can temporarily run preflight against a healthy same-chain **public** RPC: on LAN `CHAIN138_PREFLIGHT_RPC_URL=http://192.168.11.221:8545`, or from anywhere **`CHAIN138_PREFLIGHT_RPC_URL=https://rpc-http-pub.d-bis.org`** (HTTPS FQDN only for public checks). |
| **1.2** | **Core RPC = IP:port, not FQDN** | In `smom-dbis-138/.env` set `RPC_URL_138=http://192.168.11.211:8545` (Core RPC, VMID 2101). Do **not** use `https://rpc-core.d-bis.org` for deployment (DNS/tunnel can fail). See [RPC_ENDPOINTS_MASTER](../04-configuration/RPC_ENDPOINTS_MASTER.md), [TODOS_CONSOLIDATED](../00-meta/TODOS_CONSOLIDATED.md) § 0b. |
| **1.3** | **Deployer gas (Chain 138)** | Ensure deployer has ≥ ~0.006 ETH (recommended 1–2 ETH). Check: `RPC_URL_138=http://192.168.11.211:8545 ./scripts/deployment/check-deployer-balance-chain138-and-funding-plan.sh` or `cd smom-dbis-138 && ./scripts/deployment/check-balances-gas-and-deploy.sh`. |
| **1.4** | **Env from smom-dbis-138/.env only** | All deploy secrets from **`smom-dbis-138/.env`** only. Required: `PRIVATE_KEY`, `RPC_URL_138`. For PMM: `DODO_PMM_INTEGRATION_ADDRESS=0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d`, `DODO_PMM_PROVIDER_ADDRESS=0x5CAe6Ce155b7f08D3a956F5Dc82fC9945f29B381`. Optional: `GAS_PRICE_138`, `GAS_PRICE` (default 1 gwei). For explorer/runtime inventories, prefer the checked-in JSON references under `explorer-monorepo/config/` instead of repopulating address-heavy `.env` files. Verify: `cd smom-dbis-138 && ./scripts/deployment/check-env-required.sh`. |
| **1.5** | **No stuck transactions** | If nonce has pending txs or you see "Replacement transaction underpriced": run `./scripts/clear-all-transaction-pools.sh` then wait **~60s** before deploying. Prefer scripts that check nonce (e.g. `deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh`). |
| **1.4** | **Env from smom-dbis-138/.env only** | All deploy secrets from **`smom-dbis-138/.env`** only. Required: `PRIVATE_KEY`, `RPC_URL_138`. For PMM: `DODO_PMM_INTEGRATION_ADDRESS=0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895`, `DODO_PMM_PROVIDER_ADDRESS=0x3f729632E9553EBacCdE2e9b4c8F2B285b014F2e`. Optional: `GAS_PRICE_138`, `GAS_PRICE` (default 1 gwei). For explorer/runtime inventories, prefer the checked-in JSON references under `explorer-monorepo/config/` instead of repopulating address-heavy `.env` files. Verify: `cd smom-dbis-138 && ./scripts/deployment/check-env-required.sh`. |
| **1.5** | **No stuck transactions** | If nonce has pending txs or you see "Replacement transaction underpriced": run `./scripts/clear-all-transaction-pools.sh` then wait **~60s** before deploying. Prefer scripts that check nonce (e.g. `deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh`). Note: Core RPC 2101 can take additional time to bind JSON-RPC while Besu reopens or compacts RocksDB; public RPC may recover first, but deployments should still return to Core once 2101 is healthy. |
| **1.6** | **RPC 2101 (Core) writable** | If Core was read-only: `./scripts/maintenance/make-rpc-vmids-writable-via-ssh.sh` then `./scripts/maintenance/health-check-rpc-2101.sh`. See [RPC_2101_READONLY_FIX.md](RPC_2101_READONLY_FIX.md). |
| **1.7** | **Test all contracts** | Run **before** any deploy: `./scripts/deployment/test-all-contracts-before-deploy.sh`. Use `--dry-run` to print commands; `--no-match "Fork|Mainnet|Integration|e2e"` for unit-only; `--alltra` to include alltra-lifi-settlement. See [DEPLOYMENT_ORDER_OF_OPERATIONS](DEPLOYMENT_ORDER_OF_OPERATIONS.md) § Phase 0.8. |
| **1.8** | **Gas / cost estimate** | Before deploying: `cd smom-dbis-138 && ./scripts/deployment/calculate-costs-consolidated.sh` (Chain 138 min gas 1 gwei). See [DEPLOYMENT_GAS_COSTS_REALTIME](../11-references/DEPLOYMENT_GAS_COSTS_REALTIME.md). |
@@ -73,7 +73,7 @@ If you plan to deploy **additional** tokens or vaults after core + PMM, ensure p
| # | Item | Action |
|---|------|--------|
| 5.1 | **DODOPMMIntegration** | Already deployed: `0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d`. Ensure `DODO_PMM_INTEGRATION_ADDRESS` set in .env. |
| 5.1 | **DODOPMMIntegration** | Already deployed: `0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895`. Ensure `DODO_PMM_INTEGRATION_ADDRESS` set in .env. |
| 5.2 | **PMM pools (all three)** | cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC must be **created** (CreateCUSDTCUSDCPool, CreateCUSDTUSDTPool, CreateCUSDCUSDCPool). Use Core RPC only. |
| 5.3 | **DODOPMMProvider** | Deploy via DeployDODOPMMProvider.s.sol; set `DODO_PMM_PROVIDER_ADDRESS` in .env. Register each pool: `provider.registerPool(tokenIn, tokenOut, poolAddress)`. |
| 5.4 | **Liquidity (optional)** | Per pool: approve base/quote to DODOPMMIntegration, then `addLiquidity(pool, baseAmount, quoteAmount)`. See [DODO_PMM_INTEGRATION](../../smom-dbis-138/docs/integration/DODO_PMM_INTEGRATION.md). |

28
docs/03-deployment/REMAINING_DEPLOYMENTS_FOR_FULL_NETWORK_COVERAGE.md
View File

@@ -1,9 +1,9 @@
# Remaining Deployments for Full Network Coverage
> Historical note (2026-03-26): this status tracker includes earlier PMM-address snapshots. The current canonical Chain 138 PMM stack is `DODOPMMIntegration=0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d` and `DODOPMMProvider=0x5CAe6Ce155b7f08D3a956F5Dc82fC9945f29B381`.
> Historical note (2026-04-02): this status tracker includes earlier PMM-address snapshots. The current canonical Chain 138 PMM stable stack is `DODOPMMIntegration=0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895` and `DODOPMMProvider=0x3f729632E9553EBacCdE2e9b4c8F2B285b014F2e`. Public XAU pools remain live on the older PMM phase until explicitly migrated.
**Last Updated:** 2026-03-04
**Purpose:** Ordered list of remaining deployments to achieve **maximum effective execution across all networks** (13-chain hub model: Chain 138 + 12 edge/alt). Use after [REQUIRED_FIXES_GAPS_AND_DEPLOYMENTS_LIST](../00-meta/REQUIRED_FIXES_GAPS_AND_DEPLOYMENTS_LIST.md) and [DEPLOYMENT_ORDER_OF_OPERATIONS](DEPLOYMENT_ORDER_OF_OPERATIONS.md).
**Last Updated:** 2026-04-03
**Purpose:** Ordered list of remaining deployments to achieve **maximum effective execution across all networks** (13-chain hub model: Chain 138 + 12 edge/alt). Use after [REQUIRED_FIXES_GAPS_AND_DEPLOYMENTS_LIST](../00-meta/REQUIRED_FIXES_GAPS_AND_DEPLOYMENTS_LIST.md) and [DEPLOYMENT_ORDER_OF_OPERATIONS](DEPLOYMENT_ORDER_OF_OPERATIONS.md). Desired non-EVM targets such as **Solana** are tracked separately from this EVM / ALT matrix until a dedicated wrapped-asset and relay program is opened.
**Routing context:** [routing-matrix-13x13.json](../../smom-dbis-138/real-robinhood/data/routing-matrix-13x13.json) — 138↔Celo (42220) **B/SBS** (CCIP bridges deployed 2026-03-04); 138↔Wemix (1111) **Tabled** (see below). Full coverage = all 13 chains with bridge + liquidity where designed.
@@ -22,7 +22,7 @@
| B | B.2b Wemix CCIP bridges | 📋 Tabled | No route to acquire WEMIX from ETH/BNB/POLY in-repo; tabled until route exists or manual acquisition. Fund ~0.4 WEMIX ([acquire-cro-and-wemix-gas.sh](../../scripts/deployment/acquire-cro-and-wemix-gas.sh)); then `deploy-bridges-config-ready-chains.sh wemix` + complete-config. See [WEMIX_ACQUISITION_TABLED.md](WEMIX_ACQUISITION_TABLED.md). |
| B | **Gnosis CCIP bridges** | ✅ Done (2026-03-04) | Deployed: WETH9 `0x4ab39b5BaB7b463435209A9039bd40Cf241F5a82`, WETH10 `0xC15ACdBAC59B3C7Cb4Ea4B3D58334A4b143B4b44`; .env updated. |
| B | B.3 Fund CCIP with LINK | ⏳ Blocked | `scripts/deployment/fund-ccip-bridges-with-link.sh` run (2026-03-04): many lanes failing with insufficient LINK or gas, Chain 138 Invalid params; top up LINK balances and gas on each chain before retry. |
| C | C.1–C.2 cW* + edge pools | 📋 Runbook | [PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK.md](PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK.md). |
| C | C.1 token mesh complete; C.2–C.3 edge pools / stabilization pending (EVM only) | ⚠️ Partial | [PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK.md](PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK.md). |
| D | D.1–D.4 Optional XAU/vaults/trustless | 📋 Checklist | [PHASE_D_OPTIONAL_CHECKLIST.md](PHASE_D_OPTIONAL_CHECKLIST.md). |
**Latest run (same session):** A.1 mint retry → timeout again (Chain 138 RPC). complete-config → Step A/B still fail (138 tx timeout or destination already set). Gnosis bridges deployed ✅. fund-ccip → failed (Chain 138 Invalid params; other chains: insufficient LINK or gas). Cronos deploy skipped (set CRONOS_RPC and CCIP_ROUTER_CRONOS in .env).
@@ -33,12 +33,12 @@
| Item | Status | Action |
|------|--------|--------|
| **Core RPC 2101** | ✅ Healthy (container, besu-rpc, port 8545, chain 138, DB writable) | None. Use `RPC_URL_138=http://192.168.11.211:8545`. |
| **Tx pool** | May repopulate after clear | Run `./scripts/clear-all-transaction-pools.sh`; if mint fails with “Replacement transaction underpriced”, use `GAS_PRICE_138=500000000000` (500 gwei) when running mint. |
| **Validators** | 1000–1004 active (1004 restarted 2026-03-04) | If 1004 fails again: `ssh root@192.168.11.10 'pct exec 1004 -- systemctl restart besu-validator'`. |
| **Block production** | Stalled (blocks not advancing) | **Blocker for confirmations.** Run `./scripts/monitoring/monitor-blockchain-health.sh`; when blocks advance, mint/add-liquidity txs will confirm. |
| **Core RPC 2101** | ✅ Healthy | Use `RPC_URL_138=http://192.168.11.211:8545` for deployment. Current verification on 2026-04-02 returned all sampled RPCs healthy with head spread `0`. |
| **Tx pool** | Healthy, but still operationally watchable | Only clear tx pools if you actually hit a stuck nonce or “Replacement transaction underpriced”. |
| **Validators** | Healthy in current verification window | Continue standard validator monitoring; no active block-production blocker is open in this review. |
| **Block production** | Healthy | Blocks are advancing. Mint/add-liquidity and deploy confirmations are no longer blocked by the March 2026 stall. |
**Next steps in order:** (1) Ensure blocks are advancing (all 5 validators active, wait for sync). (2) `cd smom-dbis-138 && ./scripts/mint-for-liquidity.sh` (optionally `GAS_PRICE_138=500000000000` if pool has a stuck tx). (3) After mint confirms, optionally `--add-liquidity`. See [CORE_RPC_2101_2102_TXPOOL_ADMIN_STATUS.md](../04-configuration/CORE_RPC_2101_2102_TXPOOL_ADMIN_STATUS.md) §7–8.
**Next steps in order:** (1) Treat canonical Chain 138 stable liquidity as complete and only rebalance when treasury or routing changes require it. (2) Focus remaining operator work on cross-chain coverage gaps such as LINK funding, Cronos/Wemix readiness, and public-chain cW* edge pools. (3) Reuse the mesh-first runbooks only when explicitly extending the pool set beyond the current live stable + retained XAU pools.
---
@@ -46,11 +46,11 @@
| Area | Status |
|------|--------|
| Chain 138 core + PMM | **64/64** contracts (check-contracts-on-chain-138.sh; includes ISO20022Router); DODOPMMIntegration + 3 pools (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC) created; DODOPMMProvider deployed. |
| Chain 138 liquidity | **Re-verify required** — prior run reported cUSDT/cUSDC liquidity add; this checklist previously showed zero liquidity. Treat liquidity state as unknown until reconfirmed on-chain. |
| Chain 138 core + PMM | **67/67** contracts verified; canonical stable stack is `DODOPMMIntegration=0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895`, `DODOPMMProvider=0x3f729632E9553EBacCdE2e9b4c8F2B285b014F2e`, with public stable pools `0x9e89...`, `0x866c...`, `0xc39b...` live, and the cross-chain flash trio now deployed and verified. |
| Chain 138 liquidity | **Verified live** — explorer token-aggregation now persists the canonical stable pools in its DB and public quote/report endpoints are healthy. Public XAU pools remain live on the older PMM phase. |
| CCIP 138 → 1, 56, 137, 10, 42161, 43114, 8453, 100, 25, **42220 (Celo)** | Configured (B/SBS). Celo CCIP bridges deployed 2026-03-04; Gnosis, Cronos config-ready; Wemix (1111) **Tabled** (no ETH/BNB/POLY→WEMIX route; see [WEMIX_ACQUISITION_TABLED.md](WEMIX_ACQUISITION_TABLED.md)). |
| Alltra 138 ↔ 651940 | ALT path live. |
| cW* on public chains | cW* token addresses and bridge availability are recorded in `deployment-status.json` on active chains; PMM pool arrays are still empty, so broader public-chain routing remains partial. |
| cW* on public chains | The tracked public EVM cW token mesh is now **12/12 on all 9 active public EVM chains**, and `deployment-status.json` records those token addresses plus bridge availability. PMM pool arrays are still empty, so broader public-chain routing remains partial. Desired non-EVM targets like Solana are not part of this EVM cW pool graph yet. |
| LINK for CCIP | Fund bridges per lane so cross-chain messages execute. |
---
@@ -86,11 +86,13 @@
## Phase C — Public-chain cW* and edge pools
This phase remains **EVM-only**. Non-EVM desired targets such as **Solana** require a separate relay / adapter track and a wrapped-asset program that does not yet exist in the EVM `pool-matrix` flow.
**Goal:** Enable swap-bridge-swap and arbitrage on **public chains** (cW* tokens + DODO/Uniswap edge pools per pool-matrix).
| Step | Action | Ref |
|------|--------|-----|
| C.1 | **Deploy or bridge cW* tokens** per chain (1, 56, 137, 10, 42161, 8453, 43114, 100, 25, 42220, 1111). Use cross-chain-pmm-lps token-map and deployment recipe; record addresses in deployment-status.json and .env. | [PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK](PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK.md), [TOKEN_CONTRACT_DEPLOYMENTS_REMAINING](../11-references/TOKEN_CONTRACT_DEPLOYMENTS_REMAINING.md) §3 |
| C.1 | **Currently loaded public EVM cW token mesh complete** for 1, 10, 25, 56, 100, 137, 42161, 42220, 43114, and 8453. Remaining token-side work is the final Wemix target plus dedicated receiver / transport promotion where needed. | [PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK](PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK.md), [TOKEN_CONTRACT_DEPLOYMENTS_REMAINING](../11-references/TOKEN_CONTRACT_DEPLOYMENTS_REMAINING.md) §3 |
| C.2 | **Create and fund PMM edge pools** (cW*/USDC, cW*/USDT, etc.) per [pool-matrix.json](../../cross-chain-pmm-lps/config/pool-matrix.json). Populate deployment-status.json with pool addresses. | [PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK](PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK.md), [LIQUIDITY_POOLS_MASTER_MAP](../11-references/LIQUIDITY_POOLS_MASTER_MAP.md) § Public-chain cW* |
| C.3 | **Stabilization bot / peg bands** (optional): Run bot and peg-band config from cross-chain-pmm-lps for cW* peg maintenance. | [cross-chain-pmm-lps/README.md](../../cross-chain-pmm-lps/README.md) |

29
docs/03-deployment/REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md
View File

@@ -1,15 +1,15 @@
# Required Fixes and Deployments — Status
> Historical note (2026-03-26): this tracker includes earlier PMM-address snapshots. The current canonical Chain 138 PMM stack is `DODOPMMIntegration=0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d` and `DODOPMMProvider=0x5CAe6Ce155b7f08D3a956F5Dc82fC9945f29B381`.
> Historical note (2026-04-02): this tracker includes earlier PMM-address snapshots. The current canonical Chain 138 PMM stable stack is `DODOPMMIntegration=0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895` and `DODOPMMProvider=0x3f729632E9553EBacCdE2e9b4c8F2B285b014F2e`. Public XAU pools remain live on the older PMM phase until migrated.
**Last Updated:** 2026-02-28
**Last Updated:** 2026-04-03
## Required fixes
### 1. RPC 2101 (Core) — read-only filesystem
- **Status:** Not fixed (host storage I/O errors).
- **Fix before deploying:** Run `./scripts/maintenance/make-rpc-vmids-writable-via-ssh.sh` then `./scripts/maintenance/health-check-rpc-2101.sh`. No Public RPC fallback for contract deployments.
- **Status:** Healthy in the current deployment window.
- **Fix before deploying:** If Core RPC regresses to read-only, run `./scripts/maintenance/make-rpc-vmids-writable-via-ssh.sh` then `./scripts/maintenance/health-check-rpc-2101.sh`. No Public RPC fallback for contract deployments.
- **Fix:** See [RPC_2101_READONLY_FIX.md](RPC_2101_READONLY_FIX.md).
### 2. Stuck transactions
@@ -20,8 +20,8 @@
## On-chain verification (Chain 138)
**Last run (2026-03-01):** `./scripts/verify/check-contracts-on-chain-138.sh` (use Core RPC URL or run from LAN).
**Result:** **64 present, 0 missing** (64 addresses per check-contracts-on-chain-138.sh; includes ISO20022Router; live verify 2026-03-30). TransactionMirror: `0x7131F887DBEEb2e44c1Ed267D2A68b5b83285afc`. Current canonical DODO cUSDT/cUSDC pool: `0xff8d3b8fDF7B112759F076B69f4271D4209C0849`. **DeployCompliantFiatTokens** was run 2026-02-27 (10 tokens: cEURC, cEURT, cGBPC, cGBPT, cAUDC, cJPYC, cCHFC, cCADC, cXAUC, cXAUT); see [CHAIN138_TOKEN_ADDRESSES](../11-references/CHAIN138_TOKEN_ADDRESSES.md). Evidence: [LIVE_VERIFICATION_LOG_2026-03-30.md](../00-meta/LIVE_VERIFICATION_LOG_2026-03-30.md).
**Last run (2026-04-03):** `./scripts/verify/check-contracts-on-chain-138.sh` (use Core RPC URL or run from LAN).
**Result:** **75 present, 0 missing** (75 addresses per `check-contracts-on-chain-138.sh`; includes ISO20022Router, the cross-chain flash trio, and the router-v2 execution stack). TransactionMirror: `0x7131F887DBEEb2e44c1Ed267D2A68b5b83285afc`. Canonical stable PMM pools: cUSDT/cUSDC `0x9e89bAe009adf128782E19e8341996c596ac40dC`, cUSDT/USDT `0x866Cb44b59303d8dc5f4F9E3E7A8e8b0bf238d66`, cUSDC/USDC `0xc39B7D0F40838cbFb54649d327f49a6DAC964062`. Cross-chain flash infra: adapter `0xBe9e0B2d4cF6A3b2994d6f2f0904D2B165eB8ffC`, repay receiver `0xD084b68cB4B1ef2cBA09CF99FB1B6552fd9b4859`, vault credit receiver `0x89F7a1fcbBe104BeE96Da4b4b6b7d3AF85f7E661`. Router-v2 execution stack: router `0xF1c93F54A5C2fc0d7766Ccb0Ad8f157DFB4C99Ce`, coordinator `0x7D0022B7e8360172fd9C0bB6778113b7Ea3674E7`, DODO v3 adapter `0x9Cb97adD29c52e3B81989BcA2E33D46074B530eF`. **DeployCompliantFiatTokens** was run 2026-02-27 (10 tokens: cEURC, cEURT, cGBPC, cGBPT, cAUDC, cJPYC, cCHFC, cCADC, cXAUC, cXAUT); see [CHAIN138_TOKEN_ADDRESSES](../11-references/CHAIN138_TOKEN_ADDRESSES.md).
---
@@ -30,7 +30,14 @@
| Item | Address | Status |
|------|---------|--------|
| TransactionMirror | `0x7131F887DBEEb2e44c1Ed267D2A68b5b83285afc` | Deployed 2026-02-27. Set `TRANSACTION_MIRROR_ADDRESS` in smom-dbis-138/.env. |
| DODO cUSDT/cUSDC pool | 0xff8d3b8fDF7B112759F076B69f4271D4209C0849 | Current canonical public pool on corrected stack. Add liquidity via [ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK](ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK.md). |
| DODOPMMIntegration | `0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895` | Current canonical official-DVM-backed stable integration. |
| DODOPMMProvider | `0x3f729632E9553EBacCdE2e9b4c8F2B285b014F2e` | Current canonical provider for the stable pool set. |
| DODO cUSDT/cUSDC pool | `0x9e89bAe009adf128782E19e8341996c596ac40dC` | Current canonical public stable pool. |
| DODO cUSDT/USDT pool | `0x866Cb44b59303d8dc5f4F9E3E7A8e8b0bf238d66` | Current canonical public stable pool. |
| DODO cUSDC/USDC pool | `0xc39B7D0F40838cbFb54649d327f49a6DAC964062` | Current canonical public stable pool. |
| UniversalCCIPFlashBridgeAdapter | `0xBe9e0B2d4cF6A3b2994d6f2f0904D2B165eB8ffC` | Deployed and Blockscout-verified 2026-04-03. |
| CrossChainFlashRepayReceiver | `0xD084b68cB4B1ef2cBA09CF99FB1B6552fd9b4859` | Deployed and Blockscout-verified 2026-04-03. |
| CrossChainFlashVaultCreditReceiver | `0x89F7a1fcbBe104BeE96Da4b4b6b7d3AF85f7E661` | Deployed and Blockscout-verified 2026-04-03. |
| Compliant Fiat (10 tokens) | See CHAIN138_TOKEN_ADDRESSES | Deployed via DeployCompliantFiatTokens 2026-02-27. |
---
@@ -38,7 +45,7 @@
## Completion (run from LAN)
0. **If Core RPC was read-only:** `./scripts/maintenance/make-rpc-vmids-writable-via-ssh.sh` then `./scripts/maintenance/health-check-rpc-2101.sh` (must pass). See [RPC_2101_READONLY_FIX.md](RPC_2101_READONLY_FIX.md).
1. Optional: `./scripts/clear-all-transaction-pools.sh` then wait 60s if nonce stuck.
2. `./scripts/deployment/deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh` (Core RPC only; checks nonce, RPC, gas; deploys mirror then pool).
3. Set `TRANSACTION_MIRROR_ADDRESS` in `smom-dbis-138/.env` to the logged address.
4. `./scripts/verify/check-contracts-on-chain-138.sh` (pass Core RPC URL or use RPC_URL_138) — target **61** present per current script list (run check-contracts-on-chain-138.sh).
1. Optional: `./scripts/clear-all-transaction-pools.sh` then wait 60s if nonce is stuck.
2. For stable-pool verification: `./scripts/verify/check-pmm-pool-balances-chain138.sh` and `pnpm run verify:token-aggregation-api`.
3. For redeploy / rebuild only: use `./scripts/deployment/deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh` or the mesh-first pool creation flow in [PRE_DEPLOYMENT_CHECKLIST.md](PRE_DEPLOYMENT_CHECKLIST.md).
4. `./scripts/verify/check-contracts-on-chain-138.sh` (pass Core RPC URL or use `RPC_URL_138`) — target **75/75** present.

12
docs/03-deployment/SANKOFA_IT_OPS_KEYCLOAK_PORTAL_NEXT_STEPS.md
View File

@@ -19,10 +19,12 @@ One command after `.env` has `NPM_PASSWORD`, Cloudflare vars (for DNS), and SSH
## 1. Keycloak
1. Create realm role **`sankofa-it-admin`** (idempotent): `bash scripts/deployment/keycloak-sankofa-ensure-it-admin-role.sh` (needs `KEYCLOAK_ADMIN_PASSWORD` in repo `.env`, SSH to Proxmox, CT 7802). Then assign the role to IT staff in the Keycloak Admin Console (or use a group + token mapper if you prefer group claims).
2. Map **only** platform IT staff; require **MFA** at realm or IdP policy.
3. **Do not** reuse client-admin groups used for `admin.sankofa.nexus` tenant administration unless policy explicitly allows.
4. Optional: client scope **it-ops** with claim `it_admin=true` for the IT BFF audience.
1. Create realm role **`sankofa-it-admin`** (idempotent): `bash scripts/deployment/keycloak-sankofa-ensure-it-admin-role.sh` (needs `KEYCLOAK_ADMIN_PASSWORD` in repo `.env`, SSH to Proxmox, CT 7802).
2. Create group **`sankofa-it-admin`** and map the realm role onto it: `bash scripts/deployment/keycloak-sankofa-ensure-it-admin-group.sh`. Add IT users under **Groups → sankofa-it-admin → Members** (or assign the role directly to users if you skip the group).
3. **MFA policy (required for IT):** In Keycloak Admin → **Authentication** → **Required actions**: ensure **Configure OTP** is available. For realm **master** (or your Sankofa realm if split): **Realm settings** → **Security defences** / **Authentication** flows: add **OTP** to the browser flow for IT accounts, or enforce MFA at the corporate IdP (Azure AD / Google) that federates into Keycloak. Minimum bar: IT staff must not use password-only access to `/it` or break-glass SSH; document exception process in your security policy.
4. Map **only** platform IT staff; do not grant `sankofa-it-admin` to tenant client admins by default.
5. **Do not** reuse client-admin groups used for `admin.sankofa.nexus` tenant administration unless policy explicitly allows.
6. Optional: client scope **it-ops** with claim `it_admin=true` for the IT BFF audience.
**Reference:** Keycloak CT / VMID in [ALL_VMIDS_ENDPOINTS.md](../04-configuration/ALL_VMIDS_ENDPOINTS.md); portal login runbook `scripts/deployment/enable-sankofa-portal-login-7801.sh`.
@@ -30,7 +32,7 @@ One command after `.env` has `NPM_PASSWORD`, Cloudflare vars (for DNS), and SSH
## 2. Sankofa portal (`Sankofa/portal` repo)
1. **Implemented:** protected route **`/it`** (`src/app/it/page.tsx`) gated by **`sankofa-it-admin`** / **`ADMIN`** (credentials bootstrap). API proxies: `GET /api/it/drift`, `GET /api/it/inventory`, `POST /api/it/refresh`.
1. **Implemented:** protected route **`/it`** (`src/app/it/page.tsx`) gated by **`sankofa-it-admin`** / **`ADMIN`** (credentials bootstrap). API proxies: `GET /api/it/drift`, `GET /api/it/inventory`, `GET /api/it/summary`, `GET /api/it/portmap`, `POST /api/it/refresh`.
2. **Configure on CT 7801:** **`IT_READ_API_URL`** (e.g. `http://192.168.11.<host>:8787`) and optional **`IT_READ_API_KEY`** (server-only; never `NEXT_PUBLIC_*`). Proxies to the read API on VLAN 11.
3. **Do not** expose `IT_READ_API_KEY` or Proxmox credentials to the browser bundle.
4. Display **`collected_at`** from JSON; show a stale warning if older than your SLO (e.g. 24h).

6
docs/03-deployment/SANKOFA_IT_OPS_LIVE_INVENTORY_SCRIPTS.md
View File

@@ -10,8 +10,12 @@
| `scripts/it-ops/lib/collect_inventory_remote.py` | Run on PVE via SSH stdin (`python3 -`) |
| `scripts/it-ops/compute_ipam_drift.py` | Local: merge live JSON + `config/ip-addresses.conf` + **`ALL_VMIDS_ENDPOINTS.md`** pipe tables (`--all-vmids-md`) |
| `scripts/it-ops/export-live-inventory-and-drift.sh` | Orchestrator: ping seed, SSH, write `reports/status/` |
| `services/sankofa-it-read-api/server.py` | Read-only HTTP: `/v1/inventory/live`, `/v1/inventory/drift` |
| `services/sankofa-it-read-api/server.py` | Read-only HTTP: `/v1/summary`, `/v1/collector-contract`, `/v1/portmap/joined`, `/v1/inventory/*` |
| `scripts/it-ops/persist-it-snapshot-sqlite.py` | Optional SQLite append when **`IT_BFF_SNAPSHOT_DB`** is set (export hook) |
| `.github/workflows/live-inventory-drift.yml` | `workflow_dispatch` + weekly (graceful skip without LAN) |
| `.gitea/workflows/live-inventory-hardware-weekly.yml` | Weekly hardware poll + export (Gitea Actions) |
On the **seed PVE**, set **`IT_COLLECT_IP_NEIGH=1`** when piping the collector to include an `ip_neigh_vmbr0_sample` block on nodes with `vmbr0`.
**Exit codes (`compute_ipam_drift.py`):** **2** = same LAN IP used by guests with **different** names (address conflict). **0** otherwise. Guests that share an IP but share the **same** hostname (e.g. clone pairs) are listed under **`same_name_duplicate_ip_guests`** only (informational). **`vmid_ip_mismatch_live_vs_all_vmids_doc`** is informational (docs often lag live CT config).

5
docs/03-deployment/SANKOFA_STUDIO_DEPLOYMENT.md
View File

@@ -1,6 +1,6 @@
# Sankofa Studio (FusionAI Creator) — Proxmox Deployment
**Last Updated:** 2026-02-28
**Last Updated:** 2026-04-05
**Status:** Active
**White-label URL:** [https://studio.sankofa.nexus](https://studio.sankofa.nexus)
@@ -24,6 +24,7 @@
- **Single LXC** runs Docker and the FusionAI Creator stack (orchestrator API, worker, Redis, audio/image/video/ue5_export services).
- **API** listens on `0.0.0.0:8000`; NPMplus proxies `studio.sankofa.nexus` → `http://192.168.11.72:8000`.
- **App-owned root redirect:** `https://studio.sankofa.nexus/` returns **302** to `/studio/` from the FusionAI app itself, so NPMplus can stay generic with no custom per-host redirect block.
- **Studio UI** at `https://studio.sankofa.nexus/studio/`; **Marketplace landing** at `https://studio.sankofa.nexus/marketplace/landing.html`.
For scaled-out deployment (separate VMs per service), see FusionAI Creator [service-topology](https://gitea.d-bis.org/d-bis/FusionAI-Creator/src/branch/main/docs/specs/service-topology.md) and optional runbook updates.
@@ -93,6 +94,7 @@ PROXMOX_HOST=192.168.11.11 REPO_URL=https://gitea.d-bis.org/d-bis/FusionAI-Creat
- **Forward hostname / IP:** `192.168.11.72`
- **Forward port:** `8000`
2. Request **SSL certificate** (Let's Encrypt or Cloudflare Origin) and enable **Force SSL**.
3. Leave `advanced_config` empty for this host. The app already owns the `/` → `/studio/` redirect and the edge does not need a Studio-specific override.
---
@@ -130,6 +132,7 @@ Or SSH into the container and run the same.
## Health and verification
- **Health:** `curl -s http://192.168.11.72:8000/health`
- **Root redirect:** `curl -I http://192.168.11.72:8000/`
- **Studio UI:** https://studio.sankofa.nexus/studio/
- **Marketplace landing:** https://studio.sankofa.nexus/marketplace/landing.html

7
docs/03-deployment/SANKOFA_STUDIO_E2E_FLOW.md
View File

@@ -1,6 +1,6 @@
# Sankofa Studio — E2E Flow (studio.sankofa.nexus → 192.168.11.72:8000)
**Last Updated:** 2026-02-28
**Last Updated:** 2026-04-05
**Purpose:** Execute the full E2E flow for Sankofa Studio (FusionAI Creator) at https://studio.sankofa.nexus.
---
@@ -57,6 +57,8 @@ cd /home/intlc/projects/proxmox
bash scripts/nginx-proxy-manager/add-studio-sankofa-npmplus-proxy.sh
```
If the host already exists, the helper now preserves its current certificate and `Force SSL` state while resetting Studio-specific `advanced_config` back to empty.
Then request SSL for the host (one of the hosts without a cert):
```bash
@@ -71,6 +73,7 @@ FIRST_ONLY=1 bash scripts/request-npmplus-certificates.sh
- **Scheme:** HTTP
- **Forward hostname / IP:** `192.168.11.72`
- **Forward port:** `8000`
- **Advanced config:** leave empty; the app itself redirects `/` to `/studio/`
2. **SSL:** Request certificate (Let's Encrypt or Cloudflare Origin), enable **Force SSL**.
---
@@ -105,6 +108,7 @@ This creates/updates **A** `studio.sankofa.nexus` → `76.53.10.36` (or `PUBLIC_
```bash
curl -s http://192.168.11.72:8000/health
curl -I http://192.168.11.72:8000/
curl -s http://192.168.11.72:8000/studio/ -o /dev/null -w "%{http_code}\n"
```
@@ -120,6 +124,7 @@ bash scripts/verify/verify-end-to-end-routing.sh --profile=public
**Browser:**
- Root redirect: https://studio.sankofa.nexus/ -> `/studio/`
- Studio UI: https://studio.sankofa.nexus/studio/
- Marketplace landing: https://studio.sankofa.nexus/marketplace/landing.html

21
docs/03-deployment/SINGLE_SIDED_LPS_PUBLIC_NETWORKS_RUNBOOK.md
View File

@@ -22,6 +22,21 @@ The source of truth is **cross-chain-pmm-lps/config/pool-matrix.json**:
- **chains[chainId].poolsFirst:** List of pools to deploy first (e.g. `cWUSDT/USDC`, `cWUSDC/USDC`, …).
- **chains[chainId].poolsOptional:** Optional extra quote stables (e.g. `cWUSDT/USDT`, `cWUSDT/DAI`).
The matrix now includes the full GRU Wave 1 wrapped set:
- `cWEURC`
- `cWEURT`
- `cWGBPC`
- `cWGBPT`
- `cWAUDC`
- `cWJPYC`
- `cWCHFC`
- `cWCADC`
- `cWXAUC`
- `cWXAUT`
This is a design / deployment queue update, not proof that those pools are live.
---
## 3. Prerequisites per chain
@@ -64,6 +79,12 @@ From repo root, run:
This script reads **cross-chain-pmm-lps/config/pool-matrix.json** and prints, per chain, the list of **cW* / HUB** pools to create (and optional pools). Use the output to drive deployment (manual or via a deploy script that calls the appropriate factory on each chain).
For the GRU-specific operator queue, use:
```bash
bash scripts/verify/check-gru-v2-deployment-queue.sh
```
---
## 6. Deployment status and MCP allowlist source

30
docs/03-deployment/UNDEPLOYED_CONTRACTS_PRE_DEPLOYMENT_TASKS.md
View File

@@ -1,17 +1,17 @@
# Undeployed Contracts — Pre-Deployment Tasks
> Historical note (2026-03-26): this pre-deployment checklist preserves an earlier PMM bring-up phase. The current canonical Chain 138 PMM stack is `DODOPMMIntegration=0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d` and `DODOPMMProvider=0x5CAe6Ce155b7f08D3a956F5Dc82fC9945f29B381`.
> Historical note (2026-04-02): this pre-deployment checklist preserves earlier PMM bring-up phases. The current canonical Chain 138 PMM stable stack is `DODOPMMIntegration=0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895` and `DODOPMMProvider=0x3f729632E9553EBacCdE2e9b4c8F2B285b014F2e`. Public XAU pools remain on the older PMM phase until explicitly migrated.
**Last Updated:** 2026-02-28
**Execution summary (2026-02-27):** On-chain verification **36/38**. Two missing: TransactionMirror (set `TRANSACTION_MIRROR_ADDRESS` in .env from script output) and DODO cUSDT/cUSDC pool (0x9fcB...). **Deploy uses Core RPC only.** Before deploy: if Core was read-only, run `./scripts/maintenance/make-rpc-vmids-writable-via-ssh.sh` then `./scripts/maintenance/health-check-rpc-2101.sh`. See [REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md](REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md), [RPC_2101_READONLY_FIX.md](RPC_2101_READONLY_FIX.md).
**Last Updated:** 2026-04-03
**Execution summary (2026-04-03):** On-chain verification is now **67/67 present, 0 missing** on Chain 138. The canonical stable PMM stack is live, the explorer token-aggregation deployment persists the three canonical stable pools in its database, the cross-chain flash trio is deployed and Blockscout-verified, and the `EnhancedSwapRouter` dry-run now succeeds when invoked through the standard project env loader. The remaining router blocker is functional, not deploy-script-related: `swapToStablecoin()` still needs at least one live WETH-to-stable route on Chain 138.
**Execution summary (2026-02-26):** **All runnable tasks executed.** Env check, unified deploy dry-run, PMM pool dry-run, on-chain verification (36/36), deploy-optional-future-all --dry-run, fund-ccip-bridges-with-link --dry-run, check-balances-gas-and-deploy.sh, get-multichain-gas-prices.sh all completed. Mainnet dry-run and TransactionMirror simulate started (mainnet compiles CCIP bridges; run to completion when mainnet RPC is responsive). Previous: 1.x wallet/gas, 2.x gas API and estimates, 3.1 unified deploy dry-run (RPC + init fixes in smom-dbis-138), 3.2 DeployDeterministicCore simulated, 3.3 PMM pool script dry-run, 3.4 TransactionMirror, 3.6 optional-future, 3.7 fund-ccip dry-run, 4.6 on-chain verification (36/36). Optional env vars added to `smom-dbis-138/.env` when missing: `DODO_PMM_INTEGRATION_ADDRESS` and `QUOTE_TOKEN_ADDRESS` (public addresses only). PMM and unified deploy dry-runs now work with the hardened env loader (no inline env). Remaining: 3.5 mainnet dry-run (run when mainnet RPC is reachable); 4.1–4.5 post-deploy validation when components are deployed.
**Historical execution summary (2026-02-26):** **All runnable tasks executed for that earlier phase.** Env check, unified deploy dry-run, PMM pool dry-run, on-chain verification (36/36 at that time), deploy-optional-future-all --dry-run, fund-ccip-bridges-with-link --dry-run, check-balances-gas-and-deploy.sh, get-multichain-gas-prices.sh all completed. Mainnet dry-run and TransactionMirror simulate started (mainnet compiles CCIP bridges; run to completion when mainnet RPC is responsive). Previous: 1.x wallet/gas, 2.x gas API and estimates, 3.1 unified deploy dry-run (RPC + init fixes in smom-dbis-138), 3.2 DeployDeterministicCore simulated, 3.3 PMM pool script dry-run, 3.4 TransactionMirror, 3.6 optional-future, 3.7 fund-ccip dry-run, 4.6 on-chain verification (36/36 at that time). Optional env vars added to `smom-dbis-138/.env` when missing: `DODO_PMM_INTEGRATION_ADDRESS` and `QUOTE_TOKEN_ADDRESS` (public addresses only). PMM and unified deploy dry-runs now work with the hardened env loader (no inline env). Remaining at that historical point: 3.5 mainnet dry-run (run when mainnet RPC is reachable); 4.1–4.5 post-deploy validation when components are deployed.
**Source:** [AI_AGENTS_57XX_MCP_CONTRACTS_AND_CHAINS.md](../02-architecture/AI_AGENTS_57XX_MCP_CONTRACTS_AND_CHAINS.md), [DEX_AND_CROSS_CHAIN_CONTRACTS_NEEDED.md](../11-references/DEX_AND_CROSS_CHAIN_CONTRACTS_NEEDED.md), [DEPLOYED_CONTRACTS_OVERVIEW](../../smom-dbis-138/docs/deployment/DEPLOYED_CONTRACTS_OVERVIEW.md), [deployment-status.json](../../cross-chain-pmm-lps/config/deployment-status.json)
This checklist covers: **testing** anything not yet deployed, **checking deployer wallet gas**, **using the gas API to estimate deployment costs**, and **dry-running deployments** before live execution.
**Optional env vars (add/set when needed):** In `smom-dbis-138/.env`, if missing, add (public addresses only): `DODO_PMM_INTEGRATION_ADDRESS=0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d`, `DODO_PMM_PROVIDER_ADDRESS=0x5CAe6Ce155b7f08D3a956F5Dc82fC9945f29B381`, `QUOTE_TOKEN_ADDRESS=0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` so PMM pool script and dry-runs work with the current env flow. Check: `./scripts/deployment/check-env-required.sh`.
**Optional env vars (add/set when needed):** In `smom-dbis-138/.env`, if missing, add (public addresses only): `DODO_PMM_INTEGRATION_ADDRESS=0x86ADA6Ef91A3B450F89f2b751e93B1b7A3218895`, `DODO_PMM_PROVIDER_ADDRESS=0x3f729632E9553EBacCdE2e9b4c8F2B285b014F2e`, `QUOTE_TOKEN_ADDRESS=0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` so PMM pool scripts and dry-runs follow the current env flow. Check: `./scripts/deployment/check-env-required.sh`.
---
@@ -82,16 +82,16 @@ This checklist covers: **testing** anything not yet deployed, **checking deploye
## 4. Test anything not deployed (validation / unit / script)
- [ ] **4.1** **PMM pools (Chain 138):** Create cUSDT/cUSDC pool with `forge script script/dex/CreateCUSDTCUSDCPool.s.sol:CreateCUSDTCUSDCPool --rpc-url $RPC_URL_138 --broadcast --private-key $PRIVATE_KEY --with-gas-price 1000000000` (script: `smom-dbis-138/script/dex/CreateCUSDTCUSDCPool.s.sol`). Requires POOL_MANAGER_ROLE on DODOPMMIntegration. If you see "Replacement transaction underpriced", a tx is pending at that nonce; wait for it to be mined or clear mempool, then retry with same or higher gas. After creation, test: `getMidPrice`, `getOraclePrice`, `getBaseReserve`, `getQuoteReserve` on pool address; confirm MCP `dodo.get_pool_state` and `dodo.identify_pool_interface` work with that address in allowlist.
- [ ] **4.2** **DODOPMMProvider:** Not deployed; implementation placeholder. When implemented, add unit tests and a script dry-run for deployment.
- [ ] **4.3** **TransactionMirror (Chain 138):** Deploy with `forge script script/DeployTransactionMirror.s.sol:DeployTransactionMirror --rpc-url $RPC_URL_138 --broadcast --private-key $PRIVATE_KEY --with-gas-price 1000000000`. If you see "Known transaction", the tx may be pending or already mined; check code at the logged address. Then test mirror receive path.
- [ ] **4.4** **EnhancedSwapRouter:** Not deployed. When Uniswap/Balancer pools exist on 138, run deploy script with `--dry-run` and test quote path.
- [x] **4.1** **PMM pools (Chain 138):** The canonical stable pools are already live on the current stack: cUSDT/cUSDC `0x9e89bAe009adf128782E19e8341996c596ac40dC`, cUSDT/USDT `0x866Cb44b59303d8dc5f4F9E3E7A8e8b0bf238d66`, cUSDC/USDC `0xc39B7D0F40838cbFb54649d327f49a6DAC964062`. Use `bash scripts/verify/check-pmm-pool-balances-chain138.sh` to verify reserves, or `./scripts/deployment/create-all-pmm-pools-chain138.sh` only if you are explicitly rebuilding the stable stack.
- [x] **4.2** **DODOPMMProvider:** Already deployed on the canonical stable stack at `0x3f729632E9553EBacCdE2e9b4c8F2B285b014F2e`. Use desired-state sync / registration scripts if the stable pool set changes.
- [x] **4.3** **TransactionMirror (Chain 138):** Already deployed at `0x7131F887DBEEb2e44c1Ed267D2A68b5b83285afc`. Keep `TRANSACTION_MIRROR_ADDRESS` in `.env` aligned and test the mirror receive path after any related contract changes.
- [ ] **4.4** **EnhancedSwapRouter:** Deployment dry-run is now healthy, but live `swapToStablecoin()` is still blocked because Chain 138 does not yet have a WETH-to-stable route on any enabled provider. Re-run `bash scripts/deployment/dry-run-enhanced-swap-router-chain138.sh --run` after any WETH route change.
- [ ] **4.5** **cW* tokens and PMM pools on public chains (1, 56, 137, etc.):** No addresses in deployment-status. No deployment from this repo yet. When you have a deployment path (bridge + factory or DODO), run gas estimate and dry-run per chain.
- [x] **4.6** **On-chain verification (64 addresses; check-contracts-on-chain-138.sh):** After any new deployment, run:
- [x] **4.6** **On-chain verification (67 addresses; check-contracts-on-chain-138.sh):** After any new deployment, run:
```bash
./scripts/verify/check-contracts-on-chain-138.sh [RPC_URL]
```
Includes TransactionMirror and DODO cUSDT/cUSDC pool in the list. Last run: 36 present, 2 missing; see [REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS](REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md).
Includes TransactionMirror, the canonical stable pools, ISO20022Router, and the cross-chain flash trio in the list. Last run: 67 present, 0 missing; see [REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS](REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md).
---
@@ -99,10 +99,10 @@ This checklist covers: **testing** anything not yet deployed, **checking deploye
| Chain | Item | Action for estimate / dry-run |
|-------|------|-------------------------------|
| **138** | PMM pools (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC) | Estimate: `createPool` / `createCUSDTCUSDCPool` gas. Dry-run: pool-creation script or `cast send --dry-run`. |
| **138** | TransactionMirror | `forge script` or `forge create` with `--dry-run` / `cast estimate`. |
| **138** | DODOPMMProvider | When implemented: script dry-run + unit tests. |
| **138** | EnhancedSwapRouter | When pools exist: script dry-run. |
| **138** | PMM pools (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC) | Already live on the canonical stable stack. Estimate or dry-run only when rebuilding or extending the current pool set. |
| **138** | TransactionMirror | Already deployed. Use dry-run or gas estimate only if redeploying. |
| **138** | DODOPMMProvider | Already deployed on the canonical stable stack. Desired-state sync only if pool mappings change. |
| **138** | EnhancedSwapRouter | Dry-run is healthy today; do not broadcast until at least one live WETH-to-stable route exists if `swapToStablecoin()` is required. |
| **1** | (Trustless stack deployed; no new DODO from repo) | Gas estimate only if adding contracts. |
| **56, 137, 10, 100, 25, 42161, 8453, 42220, 1111, 43114** | cW* tokens, PMM pools | When deployment path exists: per-chain gas estimate + deploy script dry-run. |

178
docs/03-deployment/USDW_PUBLIC_WRAP_VAULT_RUNBOOK.md Normal file
View File

@@ -0,0 +1,178 @@
# USDW Public Wrap Vault Runbook
**Purpose:** Deploy and configure the public-chain native `USDW` -> `cWUSDW` wrap vault so the same `cWUSDW` contract can serve both:
- native public-chain `USDW` wrapping / unwrapping, and
- GRU bridge mint / burn from Chain 138 `cUSDW`
**Current status:** repo-local contract, tests, and deploy scripts are ready; live BSC / Polygon deployment and role wiring remain operator work.
---
## 1. Scope and chain posture
| Chain | Native `USDW` source | `cWUSDW` status | Wrap vault status |
|-------|-----------------------|-----------------|------------------|
| 56 (BSC) | `dwinUsdWinPublic.chains.56.usdwCurrent` | Existing `cWUSDW` re-used | Ready to deploy |
| 137 (Polygon) | `dwinUsdWinPublic.chains.137.usdwCurrent` | Native `USDW` exists; must deploy `cWUSDW` first | Ready after `cWUSDW` exists |
| 43114 (Avalanche) | No native CMC-listed USD DWIN pinned in repo | Existing bridge-only `cWUSDW` | Do not deploy wrap vault unless issuer publishes native `USDW` on Avalanche |
---
## 2. Repo artifacts
- Contract: `smom-dbis-138/contracts/bridge/integration/USDWPublicWrapVault.sol`
- Deploy script: `smom-dbis-138/script/deploy/DeployUSDWPublicWrapVault.s.sol`
- Tests: `smom-dbis-138/test/bridge/USDWPublicWrapVault.t.sol`
- cW token deploy script: `smom-dbis-138/script/deploy/DeployCWTokens.s.sol`
- Checklist: `docs/03-deployment/USD_DWIN_CUSDW_CWUSDW_BRIDGE_CHECKLIST.md`
---
## 3. Design notes
- The vault locks native public-chain `USDW` and mints `cWUSDW` after decimal normalization.
- The same `cWUSDW` supply can also be minted by the GRU bridge on inbound transfers from Chain 138.
- The vault intentionally allows pooled convertibility: bridge-minted `cWUSDW` can unwrap if enough native `USDW` liquidity is present.
- The current conservative implementation does **not** let admins withdraw the underlying native `USDW` reserve. Only non-underlying stray tokens can be recovered.
That choice avoids creating an insolvency path before the repo has a fuller reserve-liability model for mixed vault and bridge issuance.
---
## 4. Deploy `cWUSDW`
### BSC
Reuse the existing `cWUSDW`:
- `0xC2FA05F12a75Ac84ea778AF9D6935cA807275E55`
Do **not** redeploy unless you intentionally want a separate token surface, which this repo does not recommend.
### Polygon
The native Polygon `USDW` leg already exists in repo config. The remaining missing token is the GRU mirror `cWUSDW`.
Deploy a new `cWUSDW`:
```bash
cd smom-dbis-138
DEPLOY_CWUSDT=0 \
DEPLOY_CWUSDC=0 \
DEPLOY_CWUSDW=1 \
CW_BRIDGE_ADDRESS=0xYourPolygonBridge \
forge script script/deploy/DeployCWTokens.s.sol \
--rpc-url "$POLYGON_RPC_URL" \
--broadcast
```
After deployment:
1. Record the `cWUSDW` address.
2. Update `config/token-mapping-multichain.json` `dwinUsdWinPublic.chains.137.cwUsdwBridgeMirror`.
3. Set `Compliant_USDW_cW.addressTo` for `138 -> 137`.
4. Align `cross-chain-pmm-lps/config/deployment-status.json`.
---
## 5. Deploy the wrap vault
### Required env
- `PRIVATE_KEY`
- `USDW_NATIVE_ADDRESS`
- `CWUSDW_ADDRESS`
### Optional env
- `USDW_WRAP_ADMIN`
- `USDW_WRAP_OPERATOR`
- `USDW_WRAP_EMERGENCY_ADMIN`
- `USDW_WRAP_GRANT_TOKEN_ROLES=1`
- `USDW_WRAP_STRICT_ADMIN=1`
### Example
```bash
cd smom-dbis-138
USDW_NATIVE_ADDRESS=0xed75ad08f416d4e53e4d45dd5140a4c8b84f39fb \
CWUSDW_ADDRESS=0xC2FA05F12a75Ac84ea778AF9D6935cA807275E55 \
USDW_WRAP_GRANT_TOKEN_ROLES=1 \
forge script script/deploy/DeployUSDWPublicWrapVault.s.sol \
--rpc-url "$BSC_RPC_URL" \
--broadcast
```
If the caller is not `DEFAULT_ADMIN_ROLE` on `cWUSDW`, leave `USDW_WRAP_GRANT_TOKEN_ROLES=0` and grant roles separately from the token admin.
---
## 6. Required role wiring
`cWUSDW` must grant both roles to:
- the GRU public-chain bridge
- the `USDWPublicWrapVault`
Required roles:
- `MINTER_ROLE`
- `BURNER_ROLE`
Recommended admin posture:
- keep operational roles unfrozen until both bridge and vault are confirmed
- freeze operational roles only after final role recipients are set and audited
---
## 7. Seed and verify liquidity
Seed native `USDW` into the vault before relying on pooled unwrap:
```bash
# approve native USDW to the vault, then seed from a reserve operator account
```
Minimum checks after deploy:
1. `previewWrap(1 native token)` returns `1` token worth of `cWUSDW` units after decimal normalization.
2. `wrap(...)` mints `cWUSDW`.
3. `unwrap(...)` burns `cWUSDW` and releases native `USDW`.
4. Bridge-minted `cWUSDW` can unwrap against seeded liquidity.
---
## 8. Activation gate
Do **not** activate `cUSDW` in `config/gru-transport-active.json` until all of the following are true:
1. Polygon `cWUSDW` is deployed and recorded.
2. Bridge and wrap-vault minter / burner roles are verified.
3. Public-chain native `USDW` decimals are confirmed on-chain and documented.
4. Reserve / outstanding-limit policy is decided for `cUSDW`.
5. `bash scripts/validation/validate-config-files.sh` passes after the config changes.
At that point:
1. add `cUSDW` to `enabledCanonicalTokens`
2. set Polygon `Compliant_USDW_cW.addressTo`
3. add transport pairs / max outstanding / optional reserve verifier entries
---
## 9. Verification
Local repo verification:
```bash
cd smom-dbis-138
forge test --match-path test/bridge/USDWPublicWrapVault.t.sol
```
Workspace validation:
```bash
bash scripts/validation/validate-config-files.sh
```

114
docs/03-deployment/USD_DWIN_CUSDW_CWUSDW_BRIDGE_CHECKLIST.md Normal file
View File

@@ -0,0 +1,114 @@
# USD DWIN (CMC) ↔ cUSDW / cWUSDW — Completed Practical Checklist
**Status:** Config, documentation, and repo-local contract scaffolding complete; live deployment of the wrap vault, Polygon `cWUSDW`, and GRU transport activation for `cUSDW` remain operator work.
**Listing reference:** [CoinMarketCap — USD DWIN](https://coinmarketcap.com/currencies/usd-dwin/)
**Issuer migration notes:** [usddwin.com migration (BNB Chain)](https://usddwin.com/migration-binance-chain/)
---
## 1. Pin post-swap public contract addresses (done in repo)
Verified from the CMC page (April 2026):
| Network | Chain ID | Role | Address |
|---------|----------|------|---------|
| BSC | 56 | **Current** USD DWIN (USDW) | `0xed75ad08f416d4e53e4d45dd5140a4c8b84f39fb` |
| BSC | 56 | Deprecated (1:1 swap source) | `0xabddb950f2ae8430c5a818f8bb4ec09e3ae41253` |
| Polygon | 137 | **Current** USD DWIN (USDW) | `0x3deb0c60f0be9d9b99da83a2b6b2ee790f5af37a` |
| Polygon | 137 | Deprecated | `0x60f7dd499956ec8fcea8ed80e9d7eade4ccdc417` |
**Single source in repo:** `config/token-mapping-multichain.json` → object **`dwinUsdWinPublic`**.
**Operator follow-up:** Call `decimals()` on each current contract and record the result next to `decimalsNote` in that JSON after verification. The wrap adapter must normalize to the same base unit as **cUSDW / cWUSDW (6)** on Chain 138 for bridge accounting.
---
## 2. Decision: use existing cWUSDW for BSC and Avalanche (done)
| Chain | cWUSDW (GRU mirror, repo) | Use for DWIN wrap + bridge? |
|-------|---------------------------|-----------------------------|
| BSC 56 | `0xC2FA05F12a75Ac84ea778AF9D6935cA807275E55` | **Yes** — same token should implement both (a) mint/burn from GRU CCIP receiver and (b) mint/burn from a DWIN lock vault, with one supply invariant. |
| Avalanche 43114 | `0xcfdCe5E660FC2C8052BDfa7aEa1865DD753411Ae` | **Bridge-only today** — CMC does not list a native USD DWIN ERC-20 on Avalanche in `dwinUsdWinPublic`. No public unwrap target until the issuer deploys or lists one. |
| Polygon 137 | Native public `USDW` already pinned in `dwinUsdWinPublic`; `cWUSDW` not yet deployed | **Deploy** a Polygon **cWUSDW**, align with `deployment-status.json` and `Compliant_USDW_cW` (currently `addressTo` zero placeholder). |
Do **not** redeploy BSC cWUSDW unless you are intentionally splitting “bridge cWUSDW” from “DWIN-wrapped cWUSDW” (not recommended).
---
## 3. Implement wrap / unwrap + GRU bridge wiring
**Repo scaffolding now present:**
- Contract: `smom-dbis-138/contracts/bridge/integration/USDWPublicWrapVault.sol`
- Deploy script: `smom-dbis-138/script/deploy/DeployUSDWPublicWrapVault.s.sol`
- cW deploy support: `smom-dbis-138/script/deploy/DeployCWTokens.s.sol` now supports `DEPLOY_CWUSDW=1`
- Detailed operator runbook: `docs/03-deployment/USDW_PUBLIC_WRAP_VAULT_RUNBOOK.md`
**Still required as operator work:**
1. **Wrap module (per chain with native DWIN USDW)**
- Lock `dwinUsdWinPublic.chains.<id>.usdwCurrent` in a vault.
- Mint **cWUSDW** to the user (same contract as `cwUsdwBridgeMirror`).
- **Unwrap:** burn cWUSDW, release locked USDW to the user.
- Enforce **MINTER_ROLE** / **BURNER_ROLE** only for this module and the existing GRU L2 bridge (see `docs/07-ccip/CW_BRIDGE_APPROACH.md`, `CWMultiTokenBridgeL2.sol`, `CompliantWrappedToken`).
2. **Inbound to Chain 138**
- After wrap, user or relayer uses the **GRU** path: burn/lock **cWUSDW** on public, mint/unlock **cUSDW** on 138 (`0xcA6BFa614935f1AB71c9aB106bAA6FBB6057095e`) per the chosen bridge stack.
3. **Outbound from Chain 138**
- Lock **cUSDW** on 138, mint **cWUSDW** on destination; user **unwraps** to native DWIN USDW where a public leg exists.
4. **Security**
- Single ledger: `circulating cWUSDW ≤ locked DWIN USDW + bridge liability from cUSDW` (adjust formula to your exact lock/mint ordering).
- Add **CWReserveVerifier** / outstanding limits when enabling transport for cUSDW in `config/gru-transport-active.json` (pattern matches cUSDT/cUSDC).
**Important current design choice:** the repo-local vault intentionally does **not** expose an admin withdrawal path for the underlying native USDW reserve. That stays conservative until a fuller liability model exists for pooled convertibility between vault-minted and bridge-minted `cWUSDW`.
---
## 4. Extend mapper config (done)
| Item | Location |
|------|-----------|
| Native DWIN USDW + migration metadata | `config/token-mapping-multichain.json` → **`dwinUsdWinPublic`** |
| cUSDW → cWUSDW per route | Same file → **`pairs`** with key **`Compliant_USDW_cW`** for **138→56** (live), **138→43114** (live), **138→137** (placeholder `addressTo` until Polygon cWUSDW exists) |
Symbol map **cUSDW → cWUSDW** was already in **`cToCwSymbolMapping`**.
Registry-style fields for institutional JSON (`wrappedFrom`, `originChainId`, `bridgeAdapter`) are described in `docs/04-configuration/naming-conventions/04_REGISTRY_AND_JSON_FIELDS.md` and `03_BRIDGES_CROSS_CHAIN_NAMING.md`.
---
## 5. Disambiguate tokens in canonical docs (done)
**Cronos ISO-4217W USDW** (script family, 2 decimals in fallbacks) remains distinct from **CMC USD DWIN** on BSC/Polygon. See **`docs/11-references/TOKEN_CATEGORIES_CANONICAL.md`** (section on public USD DWIN).
---
## Optional env (operator)
In **`.env.master.example`**:
- `USDW_DWIN_BSC` — optional override for tooling; canonical pin remains `token-mapping-multichain.json`.
- `USDW_DWIN_POLYGON` — same for Polygon.
Existing **`CWUSDW_ADDRESS_56`** / **`CWUSDW_ADDRESS_43114`** continue to identify the **cWUSDW** contracts for token-aggregation.
---
## Activation gate (not done)
**cUSDW** is not yet listed under **`enabledCanonicalTokens`** in `config/gru-transport-active.json`. When wrap + bridge are audited:
1. Add **cUSDW** with `mappingKey`: **`Compliant_USDW_cW`**, `mirroredSymbol`: **`cWUSDW`**, per-chain **transportPairs**, **maxOutstanding**, and optional **reserveVerifierKey**.
2. Set Polygon **`Compliant_USDW_cW.addressTo`** to the deployed **cWUSDW** and align **`cross-chain-pmm-lps/config/deployment-status.json`**.
3. Run `bash scripts/validation/validate-config-files.sh`.
---
## Related runbooks
- `docs/03-deployment/CUSDW_CUSDC_V2_HUB_POOL_RUNBOOK.md` — Chain 138 **cUSDW** hub liquidity.
- `docs/03-deployment/USDW_PUBLIC_WRAP_VAULT_RUNBOOK.md` — Native public-chain USDW → **cWUSDW** vault deployment and role wiring.
- `docs/07-ccip/CW_BRIDGE_APPROACH.md` — GRU **c\*** ↔ **cW\*** strategy.
- `docs/04-configuration/C_TO_CW_MAPPER_MAPPING.md` — Mapper table including **cUSDW**.

43
docs/03-deployment/VLAN_FLAT_11_TO_SEGMENTED_RUNBOOK.md Normal file
View File

@@ -0,0 +1,43 @@
# VLAN migration runbook — flat 11 → segmented
**Current:** Single broadcast domain `192.168.11.0/24` (VLAN 11).
**Target segments:** Documented in [NETWORK_CONFIGURATION_MASTER.md](../11-references/NETWORK_CONFIGURATION_MASTER.md) (e.g. 110–112, 120, 160, 200–203).
**Policy:** Enforce **IP uniqueness** and automated drift **before** cutover ([SANKOFA_IT_OPERATIONS_CONTROLLER_SPEC.md](../02-architecture/SANKOFA_IT_OPERATIONS_CONTROLLER_SPEC.md) section 4).
## Preconditions
1. `bash scripts/it-ops/export-live-inventory-and-drift.sh` exits **0** (no `duplicate_ips` for different guest names).
2. Backup UDM/UniFi and Proxmox network configs.
3. Maintenance window announced for default gateway moves.
## Ordered segments (do not reorder without risk review)
| Step | Segment | Intent |
|------|---------|--------|
| 1 | Out-of-band / IPMI (if any) | Isolate management before touching data plane |
| 2 | Tenant-facing VLANs (200+) | Reduce blast radius for external-facing workloads |
| 3 | Besu validators / RPC | High sensitivity; coordinate with Chain 138 ops |
| 4 | Sankofa app tier | Portal, Keycloak, NPM upstreams |
## Executable checklist
Run the shell helper (dry-run by default):
```bash
bash scripts/it-ops/vlan-segmentation-ordered-checklist.sh
bash scripts/it-ops/vlan-segmentation-ordered-checklist.sh --apply
```
`--apply` only records completion timestamps in a local state file under `reports/status/`; it does **not** configure switches. Use it as an operator log.
## Per-step tasks (manual)
1. Create VLANs on UDM/UniFi; assign subnets (no overlap with existing static leases).
2. Add tagged ports on switches; update Proxmox bridges / CT `net0` VLAN tags incrementally.
3. Re-run IPAM export after each wave; fix drift before the next wave.
4. Update [ALL_VMIDS_ENDPOINTS.md](../04-configuration/ALL_VMIDS_ENDPOINTS.md) and `config/ip-addresses.conf` **after** live matches intent.
## Rollback
- Keep previous UDM backup; revert trunk tagging if a segment loses gateway.
- Document actual vs planned in `reports/status/` for the IT controller audit log (Phase 3).

6
docs/03-deployment/WEMIX_ACQUISITION_TABLED.md
View File

@@ -1,15 +1,18 @@
# Wemix (1111) deployments — tabled
**Last Updated:** 2026-03-06
**Last Updated:** 2026-04-05
**Status:** All Wemix network deployments (CCIP bridges, config, LINK funding on 1111) are **tabled** until the deployer can acquire WEMIX for gas.
---
## Reason
- Current deployer: `0x4A666F96fC8764181194447A7dFdb7d471b301C8`.
- Current preflight status from `cd smom-dbis-138 && ./scripts/deployment/preflight-config-ready-chains.sh wemix`: RPC OK on chain `1111`, deployer balance `0 WEMIX`, required minimum `0.4 WEMIX`.
- Deployer needs **~0.4 WEMIX** (native gas) on chain 1111 to deploy and configure CCIP bridges.
- There is **no in-repo route** (aggregator/DEX integration or script) to swap **ETH**, **BNB**, or **Polygon (POL)** to WEMIX.
- [TOKENS_AND_NETWORKS_MINTABLE_TO_DEPLOYER](../11-references/TOKENS_AND_NETWORKS_MINTABLE_TO_DEPLOYER.md) lists Wemix as “Bridge/DEX” only — i.e. manual acquisition.
- Historical `DeployWETHBridges.s.sol` broadcast files exist for chain `1111`, but the recorded bridge addresses do not currently resolve to bytecode on-chain. Treat the Wemix bridge layer as undeployed until a fresh funded deployment succeeds.
---
@@ -35,3 +38,4 @@
- [REMAINING_DEPLOYMENTS_FOR_FULL_NETWORK_COVERAGE.md](REMAINING_DEPLOYMENTS_FOR_FULL_NETWORK_COVERAGE.md) — Phase B.2, routing context.
- [CONFIG_READY_CHAINS_COMPLETION_RUNBOOK](../07-ccip/CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md) — steps when Wemix is un-tabled.
- [WEMIX_TOKEN_VERIFICATION.md](../07-ccip/WEMIX_TOKEN_VERIFICATION.md) — token addresses on scan.wemix.com.
- [CONTRACT_ADDRESSES_REFERENCE.md](../11-references/CONTRACT_ADDRESSES_REFERENCE.md) — current gas-native rollout and Wemix bridge note.

117
docs/03-deployment/WORMHOLE_NTT_EXECUTOR_OPERATOR_RUNBOOK.md Normal file
View File

@@ -0,0 +1,117 @@
# Wormhole NTT + Executor — operator runbook
**Last updated:** 2026-04-01
**Purpose:** Prepare a Wormhole operator environment for **Native Token Transfers (NTT)** using the modern **Executor** relay path, while clearly separating repo-local preparation from the protocol support boundary for **Chain 138**.
## What this runbook completes
- installs the official `ntt` CLI
- bootstraps a local NTT project directory
- seeds environment templates and deployment placeholders
- records the current protocol boundary for Chain 138
## What this runbook does not complete automatically
- deploying Wormhole contracts to a chain that is not currently listed as Wormhole-supported
- registering Chain 138 as a Wormhole chain
- providing Guardian / protocol-level support for Chain 138
- filling secrets, RPC URLs, or signing keys
## Why Executor, not Standard Relayer
Wormhole’s own relayer docs now direct developers to the **Executor** framework and warn that the **Standard Relayer** is deprecated. New NTT integrations should be prepared with **Executor** in mind, not the legacy Standard Relayer path.
## Chain 138 boundary
Before attempting a real Wormhole deploy, confirm the chain is officially supported:
- Wormhole chain IDs reference: `https://wormhole.com/docs/products/reference/chain-ids/`
- supported networks reference: `https://wormhole.com/docs/products/reference/supported-networks/`
As of this repo update, **Chain 138 is not listed there**, so a full Wormhole NTT or messaging deployment for Chain 138 is still blocked on Wormhole-side chain support or a separate custom-chain onboarding process.
That means:
- **supported chains**: you can prepare and deploy NTT + Executor normally
- **Chain 138**: you can prepare operator tooling and configs, but you should not mark a live Wormhole deployment complete
## Repo-local preparation
### 1. Install the NTT CLI
```bash
bash scripts/wormhole/install-ntt-cli.sh
```
This follows Wormhole’s current guidance:
- install `ntt`
- ensure **Bun v1.2.23** is available in `PATH`
### 2. Bootstrap a project
```bash
WORMHOLE_NTT_PROJECT_DIR=~/wormhole-ntt-mainnet \
WORMHOLE_ENVIRONMENT=Mainnet \
bash scripts/wormhole/bootstrap-ntt-project.sh
```
This creates an NTT project, initializes `deployment.json`, and copies repo example files for local editing.
### 3. Fill local env
Use [config/wormhole/ntt-operator.example.env](/home/intlc/projects/proxmox/config/wormhole/ntt-operator.example.env) as the base for your local-only environment.
At minimum, fill:
- source RPC URL
- destination RPC URL
- deployer private key
- any Wormhole provider/API credentials you use internally
### 4. Check Executor support
Before a real transfer route, confirm the destination chain supports NTT with Executor:
```bash
curl -fsSL https://executor.labsapis.com/v0/capabilities | jq .
```
For testnet:
```bash
curl -fsSL https://executor-testnet.labsapis.com/v0/capabilities | jq .
```
Do not proceed with automated relaying unless the source/destination pair is supported there.
## Suggested operator placement
Use the OP Stack deployer CT as the Wormhole preparation box:
- `5751` `op-stack-deployer-1` at `192.168.11.69`
That CT already has:
- baseline build tools
- SSH access for `opuser`
- repo bootstrap content
## Artifact handling
Store non-secret outputs in:
- [config/wormhole/deployed/](/home/intlc/projects/proxmox/config/wormhole/deployed/)
Examples:
- `deployment.mainnet.json`
- `executor-capabilities.snapshot.json`
- `supported-chains.audit.md`
## Next real blockers
1. pick a Wormhole-supported source/destination pair if you want a live proof-of-path now
2. decide whether Chain 138 is waiting for official support or for a custom-chain onboarding effort
3. fill the local-only RPC + key material
4. run the actual `ntt` deployment flow from the bootstrapped project