Skip to main content

Scenario Handling & End-to-End Deposit Flows

1. Scenario: All Pools Balanced, New LP Deposit​

Condition: Active at target, Reserve at max, Yield at capacity.

Class A LP deposits: Reserve is full → entire deposit enters Pending Queue. Admin is notified. Resolution: admin raises Reserve Max (if protocol growth justifies it), or LP cancels deposit. Capital is never redirected to Yield.

Class B LP deposits: Reserve portion overflows to Yield (tagged as overflow). If Yield is also full, excess enters Pending Queue. Admin notified.

2. Scenario: Stablecoin Issuer LP (IDRX)​

Condition: IDRX issuer deposits 2M IDRX. Earns fiat yield already. Zero DeFi yield interest.

Handling: Issuer is onboarded as Class A. Admin configures their custom fee tier (e.g., 0.3× of standard LP rate — because the issuer's value is strategic liquidity provision, not yield-seeking). Deposit routes 100% to Reserve Pool. Issuer receives kIDR-fx tokens. They earn from FX swap volume proportional to their TVL contribution at their configured rate, with zero yield exposure.

Commercial Note

The custom fee tier for issuers is a powerful commercial lever. Ratio can negotiate different rates with different issuers based on the strategic value of their liquidity (depth, stability, exclusivity agreements). This is more flexible than a one-size-fits-all fee model.

3. Scenario: Partner Opt-In/Opt-Out for Yield​

Condition: New partner onboarding. Partner chooses not to participate in yield.

Handling: Partner onboarding flow includes a yield participation selection. If they opt out, they are classified as Class A with a configured fee tier. If they opt in, they are Class B with standard fee rates. This flag is set per partner and applies to all their deposits by default, though a partner can make individual deposits under either class (as separate deposit transactions).

4. Scenario: Mixed Intent from Same LP​

Condition: LP wants $300K FX-only and $200K with yield.

Handling: LP makes two separate deposits: $300K as Class A (receives kXXX-fx) and $200K as Class B (receives kXXX-full). Each deposit has its own cooldown timer, its own deposit ledger entry, and its own routing path. The LP holds both token variants in their wallet.

5. Scenario: Class Migration​

Condition: Class A LP wants to switch to Class B (or vice versa).

Handling: Class migration is treated as a withdrawal followed by a new deposit. The LP initiates withdrawal from their current class (subject to LP Withdrawal cooldown and queue rules). Once withdrawn, they make a new deposit under the target class. A fresh cooldown period starts. This prevents gaming where an LP avoids yield risk during volatile periods and opts in only during safe periods to capture profits.

6. Scenario: Imbalanced Class Composition​

Condition: 90% of IDRX pool is Class A (issuers), only 10% Class B. Yield Pool for IDRX is very thin.

Implications: Yield generation for IDRX is limited by thin Yield Pool. Smart Rebalancing recall has very little to pull back if Reserve enters deficit. System must rely more heavily on external sourcing (RFQ, minting with issuers) for deficit recovery.

Mitigation: The Smart Rebalancing escalation logic should be aware of Yield Pool depth per currency. For issuer-heavy pools, the escalation path should skip "Recall from Yield" and go directly to "Mint with issuer" or "RFQ external" since the issuers providing the liquidity are also the entities who can mint more. This creates a natural feedback loop: the same issuers who fill the Reserve can mint replacement capital on demand.

7. Scenario: Yield Pool Losses​

Condition: Yield strategy loses 5% of deployed capital.

Handling:

  • kXXX-full Liquidity Index decreases proportionally. Class B holders absorb the loss.
  • kXXX-fx Liquidity Index is unaffected. Class A holders see no change.
  • Reserve Pool balance calculation is firewalled: Yield Pool losses do not reduce Reserve Pool's reported health.
  • If Smart Rebalancing triggers a Yield recall, only net-positive positions are recalled. Underwater positions are written down within Yield Pool.
  • Class B LPs can still withdraw, but their kXXX-full redemption value reflects the loss (fewer underlying stablecoins per kToken).

8. End-to-End Deposit Flow: Class A (Happy Path)​

Example: IDRX issuer deposits 1,000,000 IDRX as Class A.

  1. Issuer calls deposit(IDRX_pool, 1000000, CLASS_A) on the Vault Contract.
  2. Vault Contract accepts 1,000,000 IDRX into Deposit Pool (staging).
  3. Off-chain Routing Engine reads: intentClass=A, Reserve IDRX balance=800K, Reserve IDRX max=2M.
  4. Routing Engine determines: Reserve has 1.2M capacity remaining. Full deposit fits.
  5. Routing Engine instructs on-chain: transfer 1,000,000 IDRX from Deposit Pool → Reserve Pool.
  6. Vault Contract mints 1,000,000 kIDR-fx tokens to issuer's wallet.
  7. Deposit ledger records: {timestamp, amount: 1M, class: A, pool: Reserve, partner: IDRX_issuer}.
  8. Smart Rebalancing detects Active Pool needs rebalancing → transfers IDRX from Reserve to Active per threshold logic.

9. End-to-End Deposit Flow: Class B (Overflow Path)​

Example: Retail LP deposits 500,000 USDT as Class B. Reserve USDT is at 4.8M (max 5M). Yield has capacity.

  1. LP calls deposit(USDT_pool, 500000, CLASS_B).
  2. Vault Contract accepts 500,000 USDT into Deposit Pool.
  3. Routing Engine calculates: Reserve portion = 250K (50%), Yield portion = 250K (50%).
  4. Reserve capacity check: 5M − 4.8M = 200K available. Only 200K of the 250K Reserve portion fits.
  5. Routing Engine routes: 200K → Reserve Pool, 50K overflow + 250K Yield portion = 300K → Yield Pool.
  6. The 50K is tagged as "overflow" in the off-chain ledger for priority recall.
  7. Vault Contract mints 500,000 kUSD-full tokens to LP's wallet.
  8. Deposit ledger records: {timestamp, amount: 500K, class: B, pools: {Reserve: 200K, Yield: 300K (50K overflow)}}.