On-Chain Implementation & Monitoring
1. On-Chain vs. Off-Chain Split
| Component | Location | Rationale |
|---|---|---|
| Cooldown Enforcement | On-chain (Smart Contract) | Lock period enforced at contract level; LP cannot call withdraw before cooldown expiry |
| Deposit Ledger | On-chain (Smart Contract) | Per-deposit timestamps and amounts; immutable record for cooldown tracking |
| Withdrawal Intent (Large/Whale) | On-chain (Smart Contract) | Notice period enforced at contract level; executeWithdrawal reverts if notice not expired |
| Withdrawal Queue | Off-chain (Backend) | Queue management, FIFO ordering, gate checks, tranche scheduling |
| Reserve Pool Health Check | Off-chain (reads on-chain balance) | Gate decision logic runs off-chain; executes on-chain transfer if approved |
| Yield Pool Recall | Off-chain (Yield Engine) | Recall from external strategies is off-chain; settlement on-chain |
| Queue State Management | Off-chain (Backend) | NORMAL/SLOW/PAUSED state machine; reads State Engine and VaR from chain |
| OTC Coordination | Off-chain (Manual/Ops) | Negotiated process; settlement recorded on-chain |
2. Smart Contract Functions
| Function | Parameters | Description |
|---|---|---|
deposit() | pool, amount | Deposits stablecoin; mints kTokens; records deposit timestamp in ledger. Cooldown starts. |
getCooldownStatus() | pool, lpAddress | Returns per-deposit cooldown status: locked amount, unlocked amount, earliest withdrawable timestamp. |
submitWithdrawalIntent() | pool, amount | Submits withdrawal intent for Large/Whale withdrawals. Records intent timestamp. Notice period starts. |
cancelWithdrawalIntent() | pool, intentId | Cancels a pending withdrawal intent. LP decides to stay. |
executeWithdrawal() | pool, amount, source (RESERVE|YIELD) | Executes withdrawal after cooldown + notice (if applicable). Burns kTokens. Transfers stablecoins from specified source. |
updateWithdrawalConfig() | pool, cooldownPeriod, standardCap, whaleCap, noticePeriod, trancheSize, earlyFeeRate | Admin-only; updates withdrawal parameters. Emits WithdrawalConfigUpdated event. |
3. On-Chain Events
| Event | Data Captured | Purpose |
|---|---|---|
DepositRecorded | pool, lpAddress, amount, cooldownExpiry, kTokensMinted | Tracks every deposit; cooldown start record |
WithdrawalIntentSubmitted | pool, lpAddress, amount, tier (STANDARD|LARGE|WHALE), noticeExpiry | Tracks Large/Whale intent submissions; notice period start |
WithdrawalExecuted | pool, lpAddress, amount, source (RESERVE|YIELD), kTokensBurned, queueWaitTime | Full audit trail per withdrawal execution |
WithdrawalQueued | pool, lpAddress, amount, queuePosition, estimatedWaitTime | Tracks queue entry; LP notification |
QueueStateChanged | pool, oldState, newState, triggerReason | Tracks NORMAL/SLOW/PAUSED transitions; monitors queue health |
WithdrawalConfigUpdated | pool, old/new parameters, updatedBy | Governance audit trail for parameter changes |
4. Monitoring & Analytics
4.1 Key Metrics
| Metric | Calculation | Target / Alert Threshold |
|---|---|---|
| Avg Queue Wait Time | Average time from withdrawal request to execution, per pool | Target < 1h USDT, < 2h tnSGD, < 4h IDRX/MYRC |
| Queue Pause Frequency | Pause events per pool per week | Target < 2/week; high frequency = pool undercapitalised |
| Large/Whale Withdrawal Frequency | Whale-tier withdrawals per pool per month | Track; increasing trend may indicate LP confidence issues |
| LP Retention Rate | % of LP capital remaining 30 days after cooldown expiry | Target > 80%; low = cooldown too long or yields too low |
| Withdrawal-to-Deposit Ratio | Weekly withdrawals / weekly deposits per pool | Alert if > 0.8 sustained for 2+ weeks (net outflow) |
| Reserve Pool Health at Withdrawal | Reserve Pool % of target when withdrawal executes | Healthy: > 60%; Alert if frequently < 40% |
| Yield Pool Recall Time | Average time from recall request to funds available | Track per strategy type; alert if > 24h for liquid strategies |
| Pending Queue Volume | Total USD equivalent waiting in queue per pool | Alert if > 20% of pool TVL |
4.2 Alerting Tiers
| Alert Level | Condition | Action | Channel |
|---|---|---|---|
| INFO | Large withdrawal intent submitted | Log; Ops awareness; pre-position liquidity | Dashboard + Slack |
| INFO | Queue enters SLOW state | Monitor Reserve Pool recovery; consider pausing yield deployments | Dashboard |
| WARNING | Queue PAUSED for > 4 hours | Active Ops intervention; evaluate Yield Pool recall; consider external sourcing | Slack + Dashboard |
| WARNING | Whale withdrawal intent > 10% of pool TVL | Risk Committee notification; prepare OTC coordination option | Slack + Dashboard |
| CRITICAL | Queue PAUSED for > 24 hours | Risk Committee escalation; emergency liquidity plan; consider emergency minting | PagerDuty + Slack |
| CRITICAL | Withdrawal-to-Deposit ratio > 1.0 for 7 days | Net outflow trend; Risk Committee to review LP incentives and pool health | PagerDuty + Slack |
5. Parameter Governance & Review Cadence
5.1 Review Schedule
| Parameter | Review Cadence | Review Criteria |
|---|---|---|
| Cooldown Period | Quarterly | Is the cooldown deterring LPs? Compare LP Retention Rate and deposit inflow against competitors. Shorten if retention is low and pools are healthy. |
| Reserve Health Gates | Monthly | Are the 60%/30% thresholds correctly calibrated? Review Queue Pause Frequency and Reserve Pool Health at Withdrawal. |
| Standard/Large/Whale Thresholds | Quarterly | Are size tiers correctly set for current pool TVL? A $50K threshold may be too low if pool TVL grows to $10M+. |
| Tranche Size & Schedule | Quarterly | Are tranches too small (unnecessarily slow) or too large (pool impact)? Review Avg Queue Wait Time for Large/Whale tiers. |
| Early Withdrawal Fee | Post-launch only | If enabled: is the fee rate attracting usage? Is the fee revenue meaningful? Is it deterring normal LPs? |
| Slow Queue Hourly Cap | Monthly | Is $10K/hour appropriate? Review against actual withdrawal patterns and Reserve Pool recovery rate. |
5.2 Change Authority
All parameter changes follow the standard governance process:
- Written justification referencing specific metrics or incidents.
- Approval from Risk Committee + Engineering.
- Execution via
updateWithdrawalConfig(), emittingWithdrawalConfigUpdatedevent. - Post-change monitoring for 7 days (longer than other priorities because LP behaviour changes slowly).
- Automated rollback if Queue Pause Frequency exceeds 5/week or LP Retention Rate drops below 60% within the monitoring period.
6. Interaction with Other Subsystems
6.1 FX Engine & Active Pool
The Active Pool is completely isolated from LP withdrawals. User swap execution, Phase 1 settlement, and all FX Engine operations are unaffected by withdrawal activity. The State Engine does not receive signals from the withdrawal queue. This is the most critical architectural constraint in this document.
6.2 Reserve Pool VaR
The withdrawal queue pauses when Reserve Pool VaR exceeds 80%. This ensures that during VaR stress, liquidity is preserved for the Emergency RFQ process rather than being released to LP withdrawals. VaR-based queue pauses take priority over all other queue states.
Additionally, the Reserve Pool health gates indirectly protect VaR by preventing Reserve Pool drain. A Reserve Pool that maintains > 60% of target has sufficient capacity for both Phase 1 settlement and LP withdrawals, keeping VaR utilisation lower.
6.3 Inventory Skew
Because the Active Pool is isolated from withdrawals, the Inventory Skew system is completely unaffected. LP withdrawals cannot introduce false inventory signals. The skew system continues to operate based solely on user swap flow, as designed.
6.4 Smart Rebalancing
Smart Rebalancing handles Reserve Pool deviations in both directions, with cause-specific responses. Surplus (above target from Phase 1 settlement) is handled by Phase 2 external clearance — unaffected by LP withdrawals. Swap-driven deficit is handled by Phase 2 buy-back — this does NOT interact with the LP withdrawal queue. LP withdrawal-driven deficit triggers Yield Pool recall, which directly controls the LP withdrawal queue states defined in this document. The two systems work together: LP Withdrawals slows or pauses outflows while Smart Rebalancing accelerates inflows via Yield Pool recall, converging back to healthy Reserve Pool levels.