# Wrapped LP / Public Chain Program (Scaffold)

Solidity for **Option A** (lock → mint `wLP` → redeem) and **Option B** (ERC-4626 vault + NAV oracle). This is a **new vertical**: **not** an extension of `CWMultiTokenBridgeL1/L2` or catalog **cW*** CCIP paths.

---

## Documentation (exhaustive index)

| Doc | Description |
|-----|-------------|
| [WRAPPED_LP_PROGRAM_REFERENCE.md](../../../docs/04-configuration/WRAPPED_LP_PROGRAM_REFERENCE.md) | **Master index**, invariants, glossary, phase gates |
| [ADR_WRAPPED_LP_VAULT_PUBLIC_CHAIN.md](../../../docs/03-deployment/ADR_WRAPPED_LP_VAULT_PUBLIC_CHAIN.md) | Architecture decisions, alternatives |
| [WRAPPED_LP_MESSAGE_SCHEMA.md](../../../docs/04-configuration/WRAPPED_LP_MESSAGE_SCHEMA.md) | `lockRef`, payloads, CCIP, redemption |
| [WRAPPED_LP_ORACLE_STACK.md](../../../docs/04-configuration/WRAPPED_LP_ORACLE_STACK.md) | Two-price model, keepers, lending |
| [WRAPPED_LP_LENDING_GOVERNANCE.md](../../../docs/04-configuration/WRAPPED_LP_LENDING_GOVERNANCE.md) | Venues, listing, risk matrix |
| [WRAPPED_LP_OPERATIONS_RUNBOOK.md](../../../docs/03-deployment/WRAPPED_LP_OPERATIONS_RUNBOOK.md) | SLOs, RACI, incidents |
| [WRAPPED_LP_AUDIT_CHECKLIST.md](../../../docs/03-deployment/WRAPPED_LP_AUDIT_CHECKLIST.md) | Auditor scope, threats |

---

## Contracts

| File | Role |
|------|------|
| `Chain138LPLocker.sol` | Escrow LP on 138; `lockRef`; `releaseLock` / `releaseAmount` |
| `WLPReceiptToken.sol` | Public-chain `wLP` (MINTER/BURNER) |
| `PublicChainMintController.sol` | Idempotent `mintForLock`; `mintPaused` |
| `WLPRedemptionGateway.sol` | Burn + `RedemptionRequested` |
| `WrappedLPNAVVault.sol` | ERC-4626 + `depositCap` |
| `WLPNAVOracle.sol` | USD-style feed, heartbeat, breaker, `isStale()` |
| `interfaces/IWLPProgramEvents.sol` | Shared events |

---

## Build / test (scoped Forge)

Full-repo `forge test` may fail on legacy **0.5.x/0.6.x** vendor trees; always use **scope**:

```bash
cd smom-dbis-138
bash scripts/forge/scope.sh build wrapped-lp-public
bash scripts/forge/scope.sh test wrapped-lp-public --match-path 'test/wrapped-lp-public/*.t.sol'
```

---

## Deployment

| Script | Use |
|--------|-----|
| [DeployWrappedLPLockerChain138.s.sol](../../script/wrapped-lp-public/DeployWrappedLPLockerChain138.s.sol) | **Chain 138 only** — `Chain138LPLocker` |
| [DeployWrappedLPPublicChain.s.sol](../../script/wrapped-lp-public/DeployWrappedLPPublicChain.s.sol) | **Public chain** — wLP, mint controller, gateway, oracle, optional vault |
| [DeployWrappedLPProgram.s.sol](../../script/wrapped-lp-public/DeployWrappedLPProgram.s.sol) | **Single-chain / Anvil** — full stack on one RPC (not production two-chain) |

Production: two `forge script` runs (138 RPC then destination RPC). See [WRAPPED_LP_DEPLOYMENT_RUNBOOK.md](../../../docs/03-deployment/WRAPPED_LP_DEPLOYMENT_RUNBOOK.md).

### Post-deploy role wiring (required)

| Grant | To |
|-------|-----|
| `WLPReceiptToken.MINTER_ROLE` | `PublicChainMintController` |
| `WLPReceiptToken.BURNER_ROLE` | `WLPRedemptionGateway` |
| `PublicChainMintController.RELAYER_ROLE` | Relayer worker(s) |
| `Chain138LPLocker.BRIDGE_RELEASE_ROLE` | Relayer (138 release path) |
| `WLPNAVOracle.KEEPER_ROLE` | Price keeper |

Use **multisig** for `DEFAULT_ADMIN_ROLE` on production.

### Environment variables (deploy script)

| Variable | Purpose |
|----------|---------|
| `LP_TOKEN` | DODO LP ERC20 on 138 |
| `ADMIN` | Multisig / admin |
| `PRIVATE_KEY` | Broadcast key (lab only) |
| `USDC` | Optional; if set, deploys `WrappedLPNAVVault` |

---

## Limitations (read before mainnet)

1. **Relayer trust:** Mint path assumes **honest** relayer until ZK/attestation hardening.
2. **Fungible wLP:** Secondary trading breaks **simple** per-lock redemption; see message schema doc.
3. **Vault:** `totalAssets()` follows **ERC-20 balance**; off-chain strategy on 138 is **operational**.

---

## Repo context

- PMM pools: `docs/11-references/DEPLOYED_TOKENS_BRIDGES_LPS_AND_ROUTING_STATUS.md` §4.1  
- cW bridge **pattern only**: `docs/07-ccip/CW_BRIDGE_APPROACH.md`  
- GRU policy **orthogonality**: `docs/04-configuration/GRU_REFERENCE_PRIMACY_AND_MESH_EXECUTION_MODEL.md`