## Summary Deploy and wire the always-on, oracle-priced **UST1 ↔ vFDUSD** mint/redeem window on Terra Classic mainnet (`columbus-5`), including tokens, CL8Y bridge registration for vFDUSD, `ust1-oracle` + `ust1-window`, treasury allowance, and the off-chain oracle service. **Phase 0 decisions (approved):** - Window = primary always-on oracle mint/redeem (not time-boxed; no calendar close). Pause / oracle-staleness only. - DEX AMM is secondary (tracked in cl8y-dex Phase 4) — not a replacement for this window. - Skip `cmm-native-wrap` in this repo; native wrap uses **ustr-cmm treasury + wrap-mapper** (Phase 3). - UI lives at `https://dex.cl8y.com/ust1` (Phase 4). - **Phase 1 prerequisites confirmed** (bridge admin, treasury migrate/admin path, keys, RPCs). **Approved parameters (governance-updatable after deploy):** | Param | Value | Base units (6 decimals) | |-------|-------|-------------------------| | Window `fee_bps` | **100** (1%, `DEFAULT_FEE_BPS`) | — | | `per_tx_ust1_limit` | **1,000 UST1** | `"1000000000"` | | `rolling_24h_ust1_limit` | **10,000 UST1** | `"10000000000"` | --- ## Current codebase Mature CosmWasm monorepo (`v0.1.0` / oracle `0.1.1`) with contracts, oracle service, LocalTerra, and operator runbook — **not yet deployed to mainnet** (address registry blank except hardcoded CMM treasury). | Component | Path | Role | |-----------|------|------| | Shared math / oracle policy / fee split | `smartcontracts-terraclassic/packages/ust1-common/` | `RATE_SCALE`, `DEFAULT_FEE_BPS=100`, INV-ORACLE-*, INV-MATH-*, INV-SWAP-* | | CMM treasury constant | `smartcontracts-terraclassic/packages/ust1-cmm/` | `CMM_TREASURY_MAINNET` = `terra16j5u6ey7a84g40sr3gd94nzg5w5fm45046k9s2347qhfpwm5fr6sem3lr2` | | `ust1-oracle` | `smartcontracts-terraclassic/contracts/ust1-oracle/` | Operator `UpdateRate`; 4h throttle, +2%/UTC day, monotonic non-decreasing | | `ust1-window` | `smartcontracts-terraclassic/contracts/ust1-window/` | CW20 receive: vFDUSD→mint UST1 + forward to treasury; UST1→burn + `TransferFrom` vFDUSD | | Oracle service | `oracle-service/` | Polls BSC Venus `exchangeRateStored`, multi-RPC consensus, broadcasts `UpdateRate` | | Deploy runbook | `docs/DEPLOYMENT.md` | Full mainnet checklist (tokens → bridge → stack → oracle host) | | Integration tests | `smartcontracts-terraclassic/tests/src/integration_tests.rs` | Deposit/withdraw, fees, oracle throttle, `EffectiveSwap` | | Optional native wrap | `smartcontracts-terraclassic/contracts/cmm-native-wrap/` | **Out of scope** for this launch (self-custody; superseded by ustr-cmm wrap-mapper) | **No frontend** in this repo. Integrators use CW20 `Send` + `{"effective_swap":{}}`. --- ## Why this is needed `dex.cl8y.com` is live (CW20 soft launch) but has no UST1 mint/redeem venue. UST1 must be issued/redeemed against bridged Venus **vFDUSD** at an oracle rate that tracks BSC Venus exchange rate, with inventory held in the CMM treasury — not via an AMM pool. Without Phase 2, Phase 4 UI and secondary DEX pairs have no economic base asset. --- ## Constraints / guardrails 1. **Do not deploy `cmm-native-wrap`** for LUNC/USTC; that is Phase 3 (`ustr-cmm`). 2. **Do not** reintroduce or depend on the historical USTC→USTR swap window. 3. Window must remain **always-on** (no start/end timestamps). Only governance pause or oracle-staleness may block swaps. 4. Oracle rate policy must stay aligned on-chain and in `oracle-service` (INV-ORACLE-THROTTLE/DAILY/MONO). 5. vFDUSD Terra/BSC **decimals must match** bridge registration or amounts brick. 6. vFDUSD CW20 minter = **CL8Y Terra bridge**; UST1 minter path = governance then **`add_minter(ust1-window)`**. 7. Instantiation limits must use approved caps: `per_tx_ust1_limit="1000000000"`, `rolling_24h_ust1_limit="10000000000"`, `fee_bps=100` (not the older DEPLOYMENT.md example of 500 / 2,500). 8. Update `docs/DEPLOYMENT.md` example instantiate JSON + fill the address registry after deploy. 9. Never commit mnemonics / private keys; oracle operator mnemonic only in host secrets. 10. Treasury vFDUSD `increase_allowance` for the window is required before withdraws work. --- ## Relevant files - `docs/DEPLOYMENT.md` - `README.md` - `Makefile` / `scripts/optimize.sh` / `scripts/verify_oracle_operator_env.sh` - `smartcontracts-terraclassic/contracts/ust1-oracle/**` - `smartcontracts-terraclassic/contracts/ust1-window/**` - `smartcontracts-terraclassic/packages/ust1-common/**` - `smartcontracts-terraclassic/packages/ust1-cmm/**` - `oracle-service/src/**` (esp. `config.rs`, `bsc.rs`, `evm_rpc.rs`, `terra_tx.rs`) - `smartcontracts-terraclassic/tests/src/integration_tests.rs` - External: CL8Y bridge `docs/deployment-guide.md` §5–6; cw20-mintable code ID **10184** on columbus-5 --- ## Recommended direction 1. `make build-optimized` → store `ust1_oracle.wasm` + `ust1_window.wasm`. 2. Instantiate **vFDUSD** (bridge minter) + **UST1** (governance minter) via cw20-mintable **10184**. 3. Complete CL8Y bridge symmetric registration for vFDUSD (BSC ↔ Terra). 4. Instantiate oracle + window with approved fee/limits; `cmm_treasury: null` (default mainnet treasury) unless ops specify otherwise. 5. Post-deploy wiring: UST1 `add_minter(window)` → treasury `increase_allowance(vFDUSD, window)` → first `UpdateRate` → start oracle-service (`make verify-oracle-env` first). 6. Record all addresses/code IDs in `DEPLOYMENT.md` registry; hand governance to multisig per ops policy. 7. Smoke on mainnet with small amounts; hand addresses to Phase 4 / Phase 5. --- ## Acceptance criteria - [ ] Optimized wasm built and stored; code IDs recorded. - [ ] Mainnet **vFDUSD** and **UST1** CW20 addresses live; decimals = 6; minters correct. - [ ] CL8Y bridge can mint vFDUSD on Terra for a verified BSC→Terra transfer (or documented equivalent smoke). - [ ] `ust1-oracle` + `ust1-window` instantiated with `fee_bps=100`, per-tx **1000**, 24h **10000** UST1. - [ ] Window points at CMM treasury `terra16j5u6…` (or explicitly documented override). - [ ] Window is UST1 minter; treasury has sufficient vFDUSD allowance for window. - [ ] First rate committed; `EffectiveSwap` query returns non-stale oracle state. - [ ] Oracle service running in prod with ≥2 BSC RPCs; `verify_oracle_operator_env` passes against prod env. - [ ] Deposit vFDUSD→UST1 and withdraw UST1→vFDUSD succeed within limits. - [ ] Over per-tx / rolling-24h limits reject as designed. - [ ] `docs/DEPLOYMENT.md` address registry filled; example instantiate JSON updated to approved limits. - [ ] No `cmm-native-wrap` deployed as part of this issue. --- ## Test plan (happy / functional paths) 1. **Unit / multitest (CI):** `make test-contracts` — oracle policy, window deposit/withdraw, fee split, pause, limits. 2. **LocalTerra dry-run:** deploy stack with approved limits; deposit/withdraw round-trip; `EffectiveSwap` parity. 3. **Bridge path:** register vFDUSD; bridge small amount BSC→Terra; confirm Terra CW20 balance. 4. **Mainnet smoke (small):** - Deposit under per-tx limit → UST1 minted; vFDUSD lands in treasury. - Withdraw under limit → UST1 burned; vFDUSD returned (net of fee). - Query rolling volume after txs. 5. **Oracle service:** force/wait poll; confirm `UpdateRate` when rate differs and policy allows; silence alert config present. 6. **Governance path (testnet or controlled):** `SetFee` / limit updates / pause ↔ unpause. --- ## Test plan (attack / hack / abuse vectors) | Vector | Expected | |--------|----------| | Stale oracle (`last_update` older than `max_oracle_age_sec`) | Swaps fail `OracleStale` | | Non-operator `UpdateRate` | Rejected | | Rate decrease / >2% daily jump / update inside 4h throttle | Rejected by policy (on-chain + service) | | Exceed per-tx or rolling 24h UST1 limit | Rejected | | Withdraw with zero/insufficient treasury vFDUSD or allowance | `InsufficientVfdusd` / `InsufficientTreasuryAllowance` | | Pause window or oracle (governance) | Swaps blocked; unauthorized pause rejected | | Spoofed CW20 / wrong token send to window | Rejected (token allowlist / receive hook) | | Compromised single BSC RPC feeding bad rate | Multi-RPC consensus (≥2, agreement threshold) prevents update | | Reentrancy / double-mint via crafted receive | Covered by existing integration + multitest; no second mint without deposit | | Governance takeover without timelock/multisig process | Ops: deployer → multisig handoff documented; no single-EOA residual admin if policy forbids | --- ## Verification criteria - [ ] Address registry complete in `docs/DEPLOYMENT.md`. - [ ] On-chain queries: oracle `state`, window `effective_swap` match expected fee/limits/rate freshness. - [ ] End-to-end deposit + withdraw tx hashes recorded (mainnet smoke). - [ ] Oracle service health: successful poll/broadcast within first policy window; silence alert wired. - [ ] Phase 4 unblocked with published token + contract addresses. - [ ] Cross-link this issue from Phase 3 / 4 / 5 issues once opened. ### Related - Phase 3: ustr-cmm treasury migrate + wrap-mapper (cLUNC / cUSTC) - Phase 4: cl8y-dex `/ust1` UI + wrap wiring + secondary AMM pairs - Phase 5: ops hardening (oracle liveness, treasury inventory, registries)