# Truth Network — bridge integration and execution plan

**Last updated:** 2026-03-30  
**Purpose:** Replace the previously missing spec referenced from `scripts/truth-network/README.md`. Describes what exists on Chain 138, what is **not** implemented yet, and ordered work for WETH liquidity on Truth, optional cW* extension, and peg/stability.

---

## 1. Scope and facts

- **Truth Network** (Substrate) ↔ **Ethereum** is the primary public bridge summarized in [GALATIC_SUMMARY.md](../GALATIC_SUMMARY.md) (section 5.1: TRUU lift/burn; Ethereum Truth Bridge).
- **Chain 138** today exposes only a **registry adapter**, not a CCIP lane to Truth:

| Component | Role | Status |
|-----------|------|--------|
| `TruthNetworkAdapter` | Holds Ethereum Truth Bridge address for `ChainRegistry` | Deployed (see [CONTRACT_ADDRESSES_REFERENCE](../11-references/CONTRACT_ADDRESSES_REFERENCE.md) / [ADDRESS_MATRIX_AND_STATUS](../11-references/ADDRESS_MATRIX_AND_STATUS.md)) |
| `ChainRegistry` | EVM + non-EVM chain metadata | Deployed |
| Scripts | Deploy adapter, register Truth | `scripts/truth-network/*.sh` |

The adapter contract is intentionally minimal (immutable Ethereum bridge pointer only):

`smom-dbis-138/contracts/registry/TruthNetworkAdapter.sol`

---

## 2. What this spec does **not** claim

- There is **no** documented or scripted **Chain 138 WETH9 → Truth** CCIP path in this repo (CCIP docs cover EVM destinations; see [CCIP_138_DESTINATION_RECEIVER_BY_CHAIN_AND_TOKEN](../11-references/CCIP_138_DESTINATION_RECEIVER_BY_CHAIN_AND_TOKEN.md)).
- **`cross-chain-pmm-lps`** has **no** Truth chain entries today; Phase C pool-matrix work is EVM-scoped.

---

## 3. Execution plan (ordered)

### Phase A — Registry and Ethereum bridge truth (done / maintain)

1. Keep `TruthNetworkAdapter` constructor arg aligned with the **live** Ethereum Truth Bridge address.
2. Re-run registration only if registry or bridge address changes:  
   `./scripts/truth-network/deploy-and-register-truth-on-chain138.sh --register-only`

### Phase B — WETH representation and route to Truth (design + ops)

Pick and document **one** primary path (engineering decision):

| Option | Idea | Repo touchpoints |
|--------|------|------------------|
| B1 | User/assets: **Ethereum WETH** ↔ Truth via native Truth↔Ethereum bridge; Chain 138 is metadata/registry only | Adapter + off-chain docs |
| B2 | **138 WETH9** → Ethereum (existing CCIP / relay / hub patterns) → Truth via Ethereum bridge | [CCIP_BRIDGE_MAINNET_CONNECTION.md](CCIP_BRIDGE_MAINNET_CONNECTION.md), [DEPLOYER_TO_PUBLIC_STABLECOIN_ROUTES](../11-references/DEPLOYER_TO_PUBLIC_STABLECOIN_ROUTES.md) |
| B3 | Future **direct** 138↔Truth mechanism (custom bridge, wrapped asset on Truth, etc.) | Not designed in repo; requires new contracts + security review |

**Deliverables:** sequence diagram, responsible bridge contracts per hop, fee asset (LINK, ETH, TRUU), and Blockscout / Truth explorer links for each leg.

### Phase C — “Stable WETH9 price” on Truth (after route exists)

Treat as **operational**, not automatic:

1. **Reference price:** ETH/USD (or WETH/USD) from agreed oracles on Truth + Ethereum.
2. **Liquidity:** AMM or PMM pools that trade wrapped WETH vs a USD stable on Truth (if EVM-compatible substrate or via gateway).
3. **Monitoring:** deviation alerts vs reference; optional bot (same idea as [PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK.md](../03-deployment/PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK.md) section C.3 peg bands).

### Phase D — cW* on Truth + PMM / edge pools (extension)

If Truth exposes **EVM-compatible** assets (or a clear wrapped-token standard):

1. Mirror the **Phase C** pattern: [PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK.md](../03-deployment/PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK.md), `cross-chain-pmm-lps/config/pool-matrix.json`, `deployment-status.json`.
2. Add a **Truth chain id** (or sibling “network” row) to config; record cW* addresses and pool addresses when deployed.
3. Extend indexer / MCP allowlist generation per [SINGLE_SIDED_LPS_PUBLIC_NETWORKS_RUNBOOK.md](../03-deployment/SINGLE_SIDED_LPS_PUBLIC_NETWORKS_RUNBOOK.md) once pools exist.

If Truth remains **non-EVM** only, Phase D becomes “bridge cW* to Ethereum (or 138) only” — same as public EVM Phase C, not on-chain on Substrate.

---

## 4. E2E verification checklist (when implemented)

- [ ] Single documented path from **source** (138 WETH9 and/or Ethereum WETH) to **Truth** asset, with tx examples on both explorers.
- [ ] Price / peg: documented oracle(s) and pool addresses; alert thresholds.
- [ ] Optional: cW* addresses on target network + funded pools in `deployment-status.json`.
- [ ] Market data: update [CW_STAR_CMC_COINGECKO_LISTING_STATUS](../11-references/CW_STAR_CMC_COINGECKO_LISTING_STATUS.md) if tokens or pools become listable.

---

## 5. References

- `scripts/truth-network/README.md`
- [GALATIC_SUMMARY.md](../GALATIC_SUMMARY.md) section 5.1 bridges table
- [CW_BRIDGE_APPROACH.md](CW_BRIDGE_APPROACH.md)
- [REMAINING_DEPLOYMENTS_FOR_FULL_NETWORK_COVERAGE.md](../03-deployment/REMAINING_DEPLOYMENTS_FOR_FULL_NETWORK_COVERAGE.md) (Phases A–D)