chore: sync submodule state (parent ref update)

Made-with: Cursor
2026-03-02 12:14:09 -08:00
parent 50ab378da9
commit 5efe36b1e0
1100 changed files with 155024 additions and 8674 deletions
--- a/docs/integration/DODO_PMM_INTEGRATION.md
+++ b/docs/integration/DODO_PMM_INTEGRATION.md
@@ -29,11 +29,24 @@ DODO PMM Integration enables liquidity pools between CompliantUSDT (cUSDT)/Compl
 - Manage liquidity provision

 **Key Features**:
- Pool creation (cUSDT/USDT, cUSDC/USDC)
+- Pool creation (cUSDT/USDT, cUSDC/USDC, cUSDT/cUSDC, and generic pairs)
 - Liquidity management
 - Swap execution
 - Price discovery via PMM algorithm

+### Public Pool Pairs (VAULT_SYSTEM_MASTER_TECHNICAL_PLAN §4)
+
+The Master Plan specifies four **public** liquidity pool types for user routing and price discovery (not primary stabilization):
+
+| Pair | Creation method | Notes |
+|------|-----------------|--------|
+| **cUSDT / cUSDC** | `createCUSDTCUSDCPool(lpFeeRate, initialPrice, k, isOpenTWAP)` | Dedicated function; swap via `swapCUSDTForUSDC` / `swapUSDCForCUSDT`. Register in DODOPMMProvider for getQuote/executeSwap. |
+| **cUSDT / XAU** | `createPool(cUSDT, xauTokenAddress, ...)` | Requires XAU token address on Chain 138. Use generic `createPool`. |
+| **cUSDC / XAU** | `createPool(cUSDC, xauTokenAddress, ...)` | Same as above. |
+| **cEURT / XAU** | `createPool(cEURTAddress, xauTokenAddress, ...)` | Requires cEURT and XAU token addresses on Chain 138. |
+
+For cUSDT/XAU, cUSDC/XAU, and cEURT/XAU: deploy or obtain token addresses on Chain 138, then call `createPool(baseToken, quoteToken, lpFeeRate, initialPrice, k, isOpenTWAP)` with `POOL_MANAGER_ROLE`. Public pools serve user routing, price discovery, and flash loan access; they do not serve as the primary stabilization engine (see Master Plan private mesh).
+
 ---

 ## DODO PMM Overview
@@ -261,11 +274,53 @@ cast send $DODO_PMM_INTEGRATION_ADDRESS \

 ---

+## Oracle and Reporting
+
+### Optional ReserveSystem (oracle-backed mid price)
+
+PMM pool price can be driven by the **ReserveSystem** when base/quote tokens are registered there. This gives reporting and off-chain services an oracle-backed price when available.
+
+1. **Set ReserveSystem** (admin only):
+   ```bash
+   cast send $DODO_PMM_INTEGRATION_ADDRESS \
+     "setReserveSystem(address)" \
+     $RESERVE_SYSTEM_ADDRESS \
+     --rpc-url $RPC_URL --private-key $PRIVATE_KEY
+   ```
+   Use `address(0)` to disable and fall back to pool `getMidPrice()` only.
+
+2. **getPoolPriceOrOracle(pool)** returns: oracle price (via `reserveSystem.getConversionPrice(baseToken, quoteToken)`) if ReserveSystem is set and returns a valid price; otherwise pool `getMidPrice()`.
+
+3. **DODOPMMProvider** uses `getPoolPriceOrOracle` for quotes, so liquidity provider quotes prefer the oracle when configured.
+
+### Reporting API and pool indexer
+
+The **token-aggregation** service indexes PMM pools for `/report/all`, `/report/coingecko`, and `/report/cross-chain` when **CHAIN_138_DODO_PMM_INTEGRATION** is set.
+
+- Set in token-aggregation `.env`: `CHAIN_138_DODO_PMM_INTEGRATION=<DODOPMMIntegration address>`.
+- The pool indexer calls `getAllPools()`, then for each pool `getPoolConfig`, `getPoolReserves`, and `getPoolPriceOrOracle` to compute TVL and persist pools to the DB.
+- Ensure the indexer runs for Chain 138 (cron or on-demand) so report endpoints include PMM pools.
+
+See also: [PRICE_FEED_SETUP.md](PRICE_FEED_SETUP.md) for ReserveSystem/OraclePriceFeed setup; [ORACLE_AND_KEEPER_CHAIN138.md](ORACLE_AND_KEEPER_CHAIN138.md) for ORACLE_AGGREGATOR/ORACLE_PROXY and keeper flows on Chain 138.
+
+### PMM price for vault / reporting
+
+**PMMPriceProvider** (`contracts/vault/adapters/PMMPriceProvider.sol`) exposes `getPrice(asset, quoteToken)` using DODOPMMIntegration’s `getPoolPriceOrOracle`. Use it for vault collateral valuation (e.g. cUSDT/cUSDC in USD terms) or off-chain reporting when the asset is a PMM pair token. Deploy with the DODOPMMIntegration address; see [Vault IMPLEMENTATION_SUMMARY](../vault/IMPLEMENTATION_SUMMARY.md#gru-smart-vault-and-pmm-integration).
+
+---
+
 ## Query Functions

-### Get Pool Price
+### Get Pool Price (oracle if configured)

 ```bash
+# Prefer oracle when ReserveSystem is set
+cast call $DODO_PMM_INTEGRATION_ADDRESS \
+  "getPoolPriceOrOracle(address)" \
+  $POOL_ADDRESS \
+  --rpc-url $RPC_URL
+
+# Pool mid only (no oracle)
 cast call $DODO_PMM_INTEGRATION_ADDRESS \
  "getPoolPrice(address)" \
  $POOL_ADDRESS \
--- a/docs/integration/ORACLE_AND_KEEPER_CHAIN138.md
+++ b/docs/integration/ORACLE_AND_KEEPER_CHAIN138.md
@@ -0,0 +1,49 @@
+# Chain 138 Oracle and Keeper Reference
+
+**Purpose**: ORACLE_AGGREGATOR / ORACLE_PROXY for Chain 138 and keeper/price-update flows so PMM and reporting stay aligned with oracle data.
+
+---
+
+## Environment Variables (Chain 138)
+
+Set in project `.env` (and in token-aggregation or relay when they consume oracle):
+
+| Variable | Description |
+|----------|-------------|
+| `ORACLE_AGGREGATOR_ADDRESS` | Oracle aggregator contract on Chain 138 (e.g. from deployment). Used by CCIP and other consumers. |
+| `ORACLE_PROXY_ADDRESS` | Oracle proxy contract on Chain 138 when applicable. |
+| `RESERVE_SYSTEM` | ReserveSystem address (Chain 138). Required for DODOPMMIntegration oracle-backed mid price. |
+| `RPC_URL_138` / `RPC_URL` | RPC endpoint for Chain 138 (keeper and scripts). |
+
+References: [DEPLOYMENT_COMPLETE_GUIDE.md](../deployment/DEPLOYMENT_COMPLETE_GUIDE.md), [DEPLOYMENT_CHECKLIST.md](../DEPLOYMENT_CHECKLIST.md), [PARALLEL_COMPLETION_TASK_LIST.md](../PARALLEL_COMPLETION_TASK_LIST.md).
+
+---
+
+## Keeper and Price Feed Updates
+
+1. **OraclePriceFeed → ReserveSystem**  
+   ReserveSystem receives prices from OraclePriceFeed. Ensure assets used by PMM pairs (e.g. cUSDT, cUSDC, USDT, USDC) have aggregators set in OraclePriceFeed and are updated on schedule.  
+   See: [PRICE_FEED_SETUP.md](PRICE_FEED_SETUP.md).
+
+2. **Keeper (on-chain / off-chain)**  
+   - **PriceFeedKeeper** and scripts: `script/reserve/DeployKeeper.s.sol`, `scripts/reserve/keeper-service.js`, `scripts/reserve/keeper-service.sh`.  
+   - **Check/perform upkeep**: `PerformUpkeep.s.sol`, `CheckUpkeep.s.sol`.  
+   See: [KEEPER_COMPLETE.md](KEEPER_COMPLETE.md), [KEEPER_SETUP.md](KEEPER_SETUP.md) (if present).
+
+3. **Oracle publisher (off-chain)**  
+   Service that pushes external prices (e.g. CoinGecko) into the system:  
+   - `services/oracle-publisher/` (e.g. `oracle_publisher.py`, `oracle_publisher_optimized.py`).  
+   Use for assets that do not have a Chainlink-style aggregator on Chain 138.
+
+4. **Update oracle price script**  
+   One-off or cron-driven update of oracle/oracle proxy with current price:  
+   - `scripts/update-oracle-price.sh` — usage: `[rpc-url] [oracle-address] [private-key]`; uses `AGGREGATOR_ADDRESS` and fetches ETH/USD from CoinGecko.  
+   Schedule this (or the keeper service) so PMM oracle-backed prices and reporting stay fresh.
+
+---
+
+## PMM and Reporting
+
+- **DODOPMMIntegration**: Optional `setReserveSystem(ReserveSystem)`; then `getPoolPriceOrOracle(pool)` uses ReserveSystem when base/quote are registered.  
+- **Token-aggregation**: Set `CHAIN_138_DODO_PMM_INTEGRATION` so the pool indexer ingests PMM pools; report API then includes them in `/report/all`, `/report/coingecko`, `/report/cross-chain`.  
+See: [DODO_PMM_INTEGRATION.md](DODO_PMM_INTEGRATION.md#oracle-and-reporting).