# Deployments — Start Here

**Note: Nothing here is optional nor future — these are planned deployments (Chain 138 and multichain).**

**Last Updated:** 2026-04-03  
**Purpose:** Single entry point to run all deployments: AddressMapper (other chains), DODO PMM 138, Mainnet trustless, Paymaster. Run from repo root or `smom-dbis-138/` with `.env` and PRIVATE_KEY.

> Historical note: the completion table below preserves the 2026-02-16 optional-deployment snapshot. The current canonical Chain 138 contract baseline is **67/67** in `check-contracts-on-chain-138.sh`.

---

## Completion status (automated run)

| Step | Status | Notes |
|------|--------|------|
| **§1 Dry-run** | ✅ Done | `./scripts/run-optional-deployments.sh --dry-run` — all phases listed; phases 4, 6, 7, 8, 9 would run (1–3, 5 skipped when env set). |
| **§2A AddressMapper (Cronos)** | ✅ Deployed | Deployed at `0x6F521cd9FCF7884cD4E9486c7790e818638e09Dd` on Cronos (chain 25). `config/smart-contracts-master.json` → `chains["25"].mapper` updated. |
| **§2B DODO PMM 138** | ✅ Code | Phase 7 skips unless `DODO_VENDING_MACHINE_ADDRESS` is set; DeployDODOPMMIntegration.s.sol no-ops when required env unset. Set DODO_VENDING_MACHINE_ADDRESS + COMPLIANT_* to run. |
| **§2C Trustless (Lockbox138)** | ✅ Deployed | `0x9E51fAAE511024161b99838Af0dbA38Ff354F72c`. Stuck tx cleared; deploy succeeded. |
| **§2C Trustless (Mainnet)** | ✅ Unblocked | `ETHEREUM_MAINNET_RPC` set to https://ethereum.publicnode.com; DeployTrustlessBridge run (BondManager, InboxETH, LiquidityPoolETH, etc.). Addresses in smom-dbis-138/.env (`*_MAINNET`). Re-run deploy if broadcast was interrupted. |
| **Phase 4 Reserve Keeper** | ✅ Code | Script skips Phase 4 unless `ORACLE_PRICE_FEED` or `RESERVE_KEEPER` is set; DeployKeeper.s.sol no-ops with message when ORACLE_PRICE_FEED unset. Set env to run or skip. |
| **Phase 8 eMoney 138** | ✅ Deployed | ComplianceRegistry, DebtRegistry, PolicyManager, eMoney impl, TokenFactory138, BridgeVault138 deployed. |
| **§2D Paymaster** | ✅ Script run | Informational script ran; next steps: deploy EntryPoint/AccountFactory/Paymaster from ERC-4337 kit, set env. |
| **§4 Post-deployment check** | ✅ Done | Historical snapshot: `check-contracts-on-chain-138.sh`: 46 present, 0 missing (EOA and Mainnet-only excluded) on 2026-02-16. Current canonical baseline is **67/67**. |

**To finish deployments:** If Phase 6/8 failed with "Replacement transaction underpriced", run **Fix stuck transaction** (cancel-pending or flush-stuck-tx) first, then `./scripts/run-optional-deployments.sh --execute --phases 6,8`. Set DODO env vars for §2B to run Phase 7. Use a Mainnet RPC that accepts your key for §2C Mainnet.

---

## What else is needed (beyond PRIVATE_KEY in .env)

All steps read `PRIVATE_KEY` from `smom-dbis-138/.env`. In addition:

| Item | Required in .env | Notes |
|------|------------------|------------------|
| **§2A AddressMapper (other chain)** | None | Set `RPC_URL` or `CRONOS_RPC` for target chain (e.g. `CRONOS_RPC=https://evm.cronos.org`). Deployer needs native gas on that chain (e.g. CRO on Cronos). |
| **§2B DODO PMM 138** | `DODO_VENDING_MACHINE_ADDRESS`, `COMPLIANT_USDT_ADDRESS`, `COMPLIANT_USDC_ADDRESS` | `OFFICIAL_USDT_ADDRESS`, `OFFICIAL_USDC_ADDRESS`, `DODO_APPROVE_ADDRESS`. Get DODO Vending Machine from [DODO docs](https://docs.dodoex.io/) or Chain 138 DODO deployment. `.env.example` has COMPLIANT_*; add `DODO_VENDING_MACHINE_ADDRESS=0x...`. |
| **§2C Trustless (138)** | `RPC_URL_138` | Defaults to `http://192.168.11.211:8545` if unset. Deployer needs ETH on 138. |
| **§2C Trustless (Mainnet)** | `ETHEREUM_MAINNET_RPC` | Deployer needs ETH on Mainnet. Add `--broadcast --via-ir --verify` when running. |
| **§2D Paymaster** | `RPC_URL_138` | Script is informational. To deploy: use ERC-4337 / Smart Accounts kit, then set `ENTRY_POINT`, `SMART_ACCOUNT_FACTORY`, `PAYMASTER` in .env. |
| **§3 Run all** | `RPC_URL_138` | Same as above; Phase 7 (DODO) only runs if `DODO_VENDING_MACHINE_ADDRESS` (and compliant USDT/USDC) are set. |
| **Phase 4 (Reserve Keeper)** | `ORACLE_PRICE_FEED` or `RESERVE_KEEPER` | Set `ORACLE_PRICE_FEED` to deploy a new keeper; or set `RESERVE_KEEPER` to an existing PriceFeedKeeper address to skip (e.g. from `config/smart-contracts-master.json` chain 138 `Price_Feed_Keeper`). |

**Summary:** For **§2A, §2C (138), §3** you only need `PRIVATE_KEY` and `RPC_URL_138` (and gas on the chain). For **§2B** add the three DODO/compliant vars. For **§2C Mainnet** add `ETHEREUM_MAINNET_RPC` and Mainnet ETH.

**If you see "Replacement transaction underpriced":** A **stuck transaction** (same nonce as the next deploy) is in the node’s mempool. Raising gas on the deploy does not fix it. Do one of the following, then re-run the deploy:

1. **Replace the stuck tx (recommended):** From repo root, run  
   `./scripts/cancel-pending-transactions.sh`  
   (sources `smom-dbis-138/.env`, sends 0-value self-transfers at the stuck nonce(s) with high gas so they replace and clear). If the script reports "No pending" but deploy still fails, try  
   `./scripts/cancel-pending-transactions.sh --force`  
   to send one replacement at the current nonce (uses 500 gwei; set `GAS_PRICE_138` for higher). Then run `./scripts/run-optional-deployments.sh --execute --phases 6,8`.
2. **Clear the node mempool (Chain 138 RPC/validators):** From a host that can reach the RPC, run  
   `./scripts/flush-stuck-tx-rpc-and-validators.sh`  
   (tries `txpool_besuClear` on RPC, or full pool clear on validators). Then run the deploy again.
3. **If replacement still fails (e.g. "underpriced" even at 500 gwei):** The RPC node may have a stuck tx that Besu will not replace by gas price, or the pool clear did not affect that node. **Option A:** Run `flush-stuck-tx-rpc-and-validators.sh` from the **same host that serves the RPC** (e.g. the Chain 138 RPC VM), then run the deploy **from a machine on the same LAN** immediately after. **Option B:** Use a fresh deployer wallet so the next nonce is 0.
4. **After all else: verify RPC 2101 full approve and in sync with 5 validators.** Run  
   `./scripts/verify/verify-rpc-2101-approve-and-sync.sh`  
   to confirm the RPC on VMID 2101 has Chain 138, ADMIN API, ≥5 peers (including all 5 validator IPs 192.168.11.100–104), block production advancing, and optionally all 5 validators active (requires SSH from LAN). Ensures the RPC is permissioned and synced before or after deploy.

**Where the stuck transaction comes from:** The stuck tx is the **Lockbox138 deploy** (Phase 6) from a previous run. Forge sent it with nonce 13274 to the **RPC at VMID 2101** (192.168.11.211). The RPC accepted it into its **local transaction pool**, but the tx was never included in a block (e.g. block production stalled, or the tx was never propagated to validators). So it sits in the **RPC node’s mempool** at nonce 13274. Every new tx you send at 13274 is treated as a replacement; Besu rejects it as “underpriced” unless the new tx has higher gas than the one already in the pool (or the pool is cleared). The full flush (`clear-all-transaction-pools.sh`) runs over **SSH** on the Proxmox host (r630-01); if you ran it from a machine without SSH to 192.168.11.11, the RPC pool may not have been cleared. After a restart, validators can also re-gossip the same tx back to the RPC. See [STUCK_TX_ROOT_CAUSE_AND_GUARDRAILS](../08-monitoring/STUCK_TX_ROOT_CAUSE_AND_GUARDRAILS.md).

**Phase 4 and Phase 7 skip automatically** when required env is missing: Phase 4 is skipped unless `ORACLE_PRICE_FEED` or `RESERVE_KEEPER` is set; Phase 7 is skipped unless `DODO_VENDING_MACHINE_ADDRESS` is set (and the Forge script also no-ops if compliant USDT/USDC are unset).

---

## 1. Dry-run first (no broadcast)

From **proxmox repo root**:

```bash
./scripts/run-optional-deployments.sh --dry-run
```

Or from `smom-dbis-138/`:

```bash
cd smom-dbis-138
source .env
./scripts/deployment/deploy-optional-future-all.sh --dry-run
```

This prints every command that would run. Then run without `--dry-run` to execute.

---

## 2. Deployments (in order)

### A. AddressMapper on other chains (e.g. Cronos)

Deploys an empty AddressMapper (no Chain-138-specific mappings) so you can set `mapper` in config for that chain.

```bash
cd smom-dbis-138
source .env

# Cronos example
export RPC_URL="$CRONOS_RPC"   # or https://evm.cronos.org
forge script script/DeployAddressMapperOtherChain.s.sol:DeployAddressMapperOtherChain \
  --rpc-url "$RPC_URL" --broadcast --private-key "$PRIVATE_KEY" --legacy
```

**After deploy:** Set `config/smart-contracts-master.json` → `chains["25"].mapper` (Cronos) to the printed address (replace `"canonical"`).

**Ref:** [RECOMMENDED_COMPLETION_CHECKLIST](RECOMMENDED_COMPLETION_CHECKLIST.md) §5.

---

### B. DODO PMM on Chain 138

**Required env:** `DODO_VENDING_MACHINE_ADDRESS`, `COMPLIANT_USDT_ADDRESS`, `COMPLIANT_USDC_ADDRESS`. Additional: `OFFICIAL_USDT_ADDRESS`, `OFFICIAL_USDC_ADDRESS`, `DODO_APPROVE_ADDRESS`.

```bash
cd smom-dbis-138
source .env
forge script script/dex/DeployDODOPMMIntegration.s.sol \
  --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY" --with-gas-price "${GAS_PRICE_138:-2000000000}"
```

Then create pools (e.g. `createCUSDTUSDTPool`, `createCUSDCUSDCPool`) and set `CHAIN_138_DODO_POOL_MANAGER` / `CHAIN_138_DODO_VENDING_MACHINE` in env.  
**Ref:** [DODO_PMM_INTEGRATION](../../smom-dbis-138/docs/integration/DODO_PMM_INTEGRATION.md), [LIQUIDITY_POOL_CONTROLS_RUNBOOK](../03-deployment/LIQUIDITY_POOL_CONTROLS_RUNBOOK.md).

---

### C. Mainnet trustless stack (Lockbox138 + Mainnet)

**Chain 138 (Lockbox138):**

```bash
cd smom-dbis-138
source .env
forge script script/bridge/trustless/DeployTrustlessBridge.s.sol:DeployTrustlessBridge \
  --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY" --with-gas-price "${GAS_PRICE_138:-2000000000}"
```

**Mainnet (BondManager, ChallengeManager, LiquidityPoolETH, InboxETH):**

```bash
forge script script/bridge/trustless/DeployTrustlessBridge.s.sol:DeployTrustlessBridge \
  --rpc-url "$ETHEREUM_MAINNET_RPC" --broadcast --via-ir --verify
```

**Ref:** [OPTIONAL_FUTURE_DEPLOYMENTS_RUNBOOK](../03-deployment/OPTIONAL_FUTURE_DEPLOYMENTS_RUNBOOK.md) §1, [bridge/trustless/DEPLOYMENT_INSTRUCTIONS](../../smom-dbis-138/docs/bridge/trustless/DEPLOYMENT_INSTRUCTIONS.md).

---

### D. Paymaster / Smart accounts (Chain 138)

Deploy from ERC-4337 / MetaMask Smart Accounts Kit, then set `ENTRY_POINT`, `SMART_ACCOUNT_FACTORY`, `PAYMASTER` in .env.

```bash
cd smom-dbis-138
forge script script/smart-accounts/DeploySmartAccountsKit.s.sol \
  --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY" --with-gas-price "${GAS_PRICE_138:-2000000000}"
```

(Script may be informational only; deploy actual contracts from the kit.)  
**Ref:** [SMART_ACCOUNTS_DEPLOYMENT_NOTE](../../metamask-integration/docs/SMART_ACCOUNTS_DEPLOYMENT_NOTE.md).

---

## 3. Run all (Chain 138) in one go

From **proxmox repo root**:

```bash
./scripts/run-optional-deployments.sh --execute
```

Or with specific phases (e.g. DODO + Trustless Lockbox only):

```bash
./scripts/run-optional-deployments.sh --execute --phases 6,7
```

Phases: 1=Deterministic core, 2=Vault, 3=Reserve, 4=Keeper, 5a/5b=Channels, 6=Trustless Lockbox138, 7=DODO PMM, 8=eMoney, 9=Smart accounts (informational).

**Ref:** [deploy-optional-future-all.sh](../../smom-dbis-138/scripts/deployment/deploy-optional-future-all.sh), [OPTIONAL_FUTURE_DEPLOYMENTS_RUNBOOK](../03-deployment/OPTIONAL_FUTURE_DEPLOYMENTS_RUNBOOK.md).

---

## 4. After deployment

1. **Update env:** Add new addresses to `smom-dbis-138/.env` (and root `.env` if used). See script output for `export ...` lines.
2. **Update config:** In `config/smart-contracts-master.json` set `chains["<chainId>"].mapper` and `contracts.Address_Mapper` for other-chain mappers; add DODO/Trustless addresses when deployed.
3. **Verify:** Run `./scripts/verify/check-contracts-on-chain-138.sh`. From LAN with secrets: `./scripts/verify/run-contract-verification-with-proxy.sh` for Blockscout.
4. **Periodic checks:** Run `./scripts/run-completable-tasks-from-anywhere.sh` (config + on-chain + validation).

---

## 5. Next steps — complete in order

**From anywhere (no LAN):**

| # | Action | Command |
|---|--------|--------|
| 1 | Config + on-chain + validation | `./scripts/run-completable-tasks-from-anywhere.sh` |
| 1b | Mapper: validation + operator checklist | `./scripts/run-remaining-mapper-tasks.sh` (validates config, on-chain 138, prints Wemix/CCIP/LINK/DODO/Trustless steps) |
| 2 | Dry-run deployments | `./scripts/run-optional-deployments.sh --dry-run` |
| 3 | Deploy (Chain 138 phases 6, 8 when ready) | `./scripts/run-optional-deployments.sh --execute --phases 6,8` (set `GAS_PRICE_138` if needed) |
| 4 | Check contracts on 138 | `./scripts/verify/check-contracts-on-chain-138.sh` |
| 4b | **After all else:** RPC 2101 full approve and in sync | `./scripts/verify/verify-rpc-2101-approve-and-sync.sh` — full fix flow: [RPC_AND_VALIDATOR_TESTING_RUNBOOK](../08-monitoring/RPC_AND_VALIDATOR_TESTING_RUNBOOK.md). |

**From LAN with secrets (operator):**

| # | Action | Command / doc |
|---|--------|----------------|
| 5 | Wemix token verify | [scan.wemix.com/tokens](https://scan.wemix.com/tokens) → update JSON if needed → `bash scripts/validation/validate-config-files.sh` |
| 6 | Gnosis, Celo, Wemix CCIP bridges | [CONFIG_READY_CHAINS_COMPLETION_RUNBOOK](CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md) |
| 7 | LINK on Mainnet relay | [RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK](RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md) |
| 8 | Blockscout verification | `source smom-dbis-138/.env 2>/dev/null; ./scripts/verify/run-contract-verification-with-proxy.sh` |
| 9 | E2E 502 fix | `./scripts/maintenance/run-all-maintenance-via-proxmox-ssh.sh --e2e` or `address-all-remaining-502s.sh` |
| 10 | All operator tasks | `./scripts/run-all-operator-tasks-from-lan.sh [--deploy] [--create-vms]` — [STEPS_FROM_PROXMOX_OR_LAN_WITH_SECRETS](../00-meta/STEPS_FROM_PROXMOX_OR_LAN_WITH_SECRETS.md) |

**Full list:** [NEXT_STEPS_AND_REMAINING_TODOS](../00-meta/NEXT_STEPS_AND_REMAINING_TODOS.md).

**Master completion plan (all incomplete + missing items):** [COMPLETION_MASTER_PLAN](../00-meta/COMPLETION_MASTER_PLAN.md).

**Current operator steps:** [../00-meta/OPERATOR_READY_CHECKLIST.md](../00-meta/OPERATOR_READY_CHECKLIST.md), [../00-meta/NEXT_STEPS_OPERATOR.md](../00-meta/NEXT_STEPS_OPERATOR.md), [../04-configuration/FIXES_PREPARED.md](../04-configuration/FIXES_PREPARED.md).