[FEAT] Automated Liquidity Reserve Rebalancing & Cross-Asset Yield Aggregation Vault

[jotel-dev]

telegram link : t.me/nullifiersystem

---

1. Summary & Core Promise

Idle provider collateral in contracts/escrow/src/lib.rs generates zero yield. This feature implements an Automated Liquidity Reserve Rebalancing & Yield Aggregation Subsystem. Unallocated escrow funds are deposited into Soroban yield vaults (contracts/escrow/src/yield_vault.rs) to earn 4-8% APY while maintaining a dynamic 20% liquid reserve buffer for instant cash trade match settlements.

---

2. Background & Architectural Risks

• Capital Inefficiency: Idle escrow reserves discourage institutional providers from locking large balances.
• Liquidity Lockup Risk: High trade volume spiking above liquid buffers must instantly recall funds from yield strategies without trade settlement delays.

---

3. Database Layer Specifications

Migration SQL (026_add_yield_aggregation_vaults.sql)

CREATE TABLE yield_vault_configs (
    vault_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    asset_address VARCHAR(56) NOT NULL,
    liquid_buffer_ratio NUMERIC(3,2) NOT NULL DEFAULT 0.20,
    current_tvl_stroops BIGINT NOT NULL DEFAULT 0
);

CREATE TABLE provider_vault_shares (
    provider_id VARCHAR(64) NOT NULL,
    vault_id UUID NOT NULL REFERENCES yield_vault_configs(vault_id),
    share_balance BIGINT NOT NULL DEFAULT 0,
    PRIMARY KEY (provider_id, vault_id)
);

---

4. Backend Route & Service Layer Specifications

Route: POST /api/v1/yield/harvest

1. Harvests accumulated protocol yield from external Soroban strategies.
2. Updates share-token exchange rates in provider_vault_shares.

---

5. Background Processors / Workers

Yield Rebalance Worker (apps/api/src/lib/workers/yieldRebalanceWorker.ts)

• Drives periodic yield compounding and dynamic 20% liquidity buffer optimization.

---

6. Frontend / UI Component Specifications

Component: mobile/frontend/src/pages/ProviderYieldPortal.tsx

• React dashboard displaying APY charts, yield harvest buttons, and buffer ratio slider controls.

---

7. Rigor & Test Plan

1. Share Math Test (yield_vault_tests.rs): Verifies share exchange rate math during deposits and harvests.
2. Instant Withdrawal Stress Test (yield_withdrawal_stress.test.ts).

---

8. Relevant Files Inventory (19 Files)

• contracts/escrow/src/yield_vault.rs
• contracts/escrow/src/yield_vault_tests.rs
• apps/api/src/lib/yield/buffer-optimizer.ts
• apps/api/src/lib/yield/strategy-adapter.ts
• apps/api/src/lib/workers/yieldRebalanceWorker.ts
• apps/api/src/db/migrations/026_add_yield_aggregation_vaults.sql
• apps/api/src/routes/yield-vaults.ts
• apps/api/src/lib/liquidity-netting.ts
• apps/api/src/lib/store.ts
• apps/api/src/lib/stellar.ts
• apps/api/src/app.ts
• contracts/escrow/src/lib.rs
• mobile/frontend/src/pages/ProviderYieldPortal.tsx
• mobile/frontend/src/components/YieldApyChart.tsx
• mobile/frontend/src/components/BufferRatioSlider.tsx
• packages/shared/src/types/yield.ts
• packages/shared/src/index.ts
• apps/api/src/lib/yield/__tests__/buffer-optimizer.test.ts
• tests/concurrency/yield_withdrawal_stress.test.ts

---

9. Acceptance Criteria

• Idle escrow collateral automatically earns APY yield.
• Trade matching instantly draws from 20% liquid buffer without latency.

---

10. Contributor Notes

• ⚠️ Invariant Rule: Share token exchange rate must NEVER decrease during yield harvesting.

[Peculiarr7]

Hi! I came across this issue and would love to work on it. I have experience with similar tasks and I'm confident I can investigate, implement a clean solution, and thoroughly test it before submitting a PR. If the issue is still open, I would appreciate it if you could assign it to me. I’ll prioritize this immediately and ensure a reliable solution is delivered as soon as possible. Thank you!

[angelraph]

hey maintaner

This feature sits at the intersection of Soroban contract accounting, liquidity management, and yield strategy execution, so I’d approach it as a financial state-transition problem rather than treating the listed files as independent implementation tasks.

I’d first trace the existing escrow lifecycle and establish the exact relationship between provider collateral, liquid reserves, vault positions, and trade settlement. From there I’d implement the vault accounting around explicit invariants for shares, underlying assets, and exchange rates.

The critical invariant I’d protect is that harvesting can increase provider value through yield without ever reducing the share exchange rate due to accounting, rounding, or synchronization errors. I’d cover this with deposit → harvest → rebalance → withdrawal lifecycle tests, including multiple providers and repeated harvest cycles.

For liquidity management, I’d separate immediately available settlement capital from strategy capital and make the rebalance worker operate around the required liquidity floor rather than relying on a fixed transfer schedule. Strategy failures and insufficient liquid reserves would have explicit failure paths so trade settlement isn't silently exposed to yield-strategy state.

I’d also treat the withdrawal stress test as a core acceptance test. Concurrent withdrawals, reserve exhaustion, strategy withdrawal latency, rounding, repeated harvesting, and boundary conditions should all be exercised before considering the subsystem complete.

On the implementation side, I can work across the Soroban/Rust contracts, TypeScript services and workers, database layer, shared types, and React provider portal. I’d use Claude Code to accelerate repository analysis, implementation, test generation, and iteration while keeping the financial invariants and state-transition design under deliberate review.

My goal would be a complete, test-backed subsystem that can safely move idle provider collateral into yield while preserving the liquidity required for actual trade settlement. let me handle this

[gelluisaac]

Hi! I’d like to take this issue. I’ll go through the existing implementation, identify the root cause, and work on a clean solution before submitting a PR for review.

[grantfox-oss]

🦊 GrantFox — @gelluisaac has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #408)
2. Your PR will be reviewed by the Nullifier-Systems maintainers

Good luck! Track your progress on GrantFox.