[FEAT] Dynamic Geo-Spatial Liquidity Provider Rebalancing & Hotspot Incentive Engine

[jotel-dev]

telegram link : t.me/nullifiersystem

---

1. Summary & Core Promise

Velo's spatial indexing in apps/api/src/lib/h3-spatial-index.ts and order allocation in apps/api/src/lib/order-allocator.ts match cash requests to nearby providers using flat distance metrics. In high-demand zones (e.g. transit hubs or event venues), provider liquidity quickly exhausts while adjacent cells remain over-capitalized.

This feature implements a Dynamic Geo-Spatial Liquidity Provider Rebalancing & Hotspot Incentive Engine. It calculates spatial demand density across Uber H3 hex cells (resolution = 7), dynamically boosts provider fee share multipliers (1.1x to 2.0x) in high-demand "hotspots", and updates provider allocation weights in PostgreSQL (SELECT FOR UPDATE).

---

2. Background & Architectural Risks

• Spatial Liquidity Desert: Popular geographic cells run out of active cash providers while nearby cells have idle liquidity.
• Dynamic Fee Manipulation: Malicious providers spoofing locations to artificially trigger hotspot fee multipliers without fulfilling local trades.

---

3. Database Layer Specifications

Migration SQL (031_add_spatial_hotspot_incentives.sql)

CREATE TABLE spatial_h3_cell_metrics (
    h3_index VARCHAR(15) PRIMARY KEY,
    active_requests_count INT NOT NULL DEFAULT 0,
    available_providers_count INT NOT NULL DEFAULT 0,
    demand_ratio NUMERIC(5,2) NOT NULL DEFAULT 1.00,
    fee_multiplier NUMERIC(3,2) NOT NULL DEFAULT 1.00,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_h3_demand ON spatial_h3_cell_metrics(demand_ratio DESC);

Data Locking (SELECT FOR UPDATE)

BEGIN;
SELECT h3_index, demand_ratio, fee_multiplier 
FROM spatial_h3_cell_metrics 
WHERE h3_index = $1 
FOR UPDATE;
-- Recalculate demand ratio and fee multiplier...
COMMIT;

---

4. Backend Route & Service Layer Specifications

Route: GET /api/v1/spatial/hotspots

1. Queries high-demand H3 cells where demand_ratio > 2.0.
2. Computes dynamic fee multiplier min(1.0 + (demand_ratio * 0.1), 2.0).
3. Returns geoJSON spatial hotspot overlay layer for mobile clients.

---

5. Background Processors / Workers

H3 Spatial Metrics Recalculator Worker (apps/api/src/lib/workers/spatialMetricsWorker.ts)

• Runs every 30 seconds. Aggregates active cash requests per H3 cell and updates fee_multiplier scores.

---

6. Frontend / UI Component Specifications

Component: mobile/frontend/src/components/SpatialHotspotMapOverlay.tsx

• Renders interactive H3 spatial hex map overlay showing high-yield hotspot zones (color-coded green -> orange -> red) to guide providers where to relocate for higher fee earnings.

---

7. Rigor & Test Plan

1. Unit Tests (h3-spatial-index.ts): Verify H3 cell aggregation and demand ratio calculation.
2. Concurrency Stress Test (tests/concurrency/spatial_hotspot_stress.test.ts): Simulate 100 simultaneous cash requests in a single H3 cell; assert fee multiplier caps at 2.0x cleanly.

---

8. Relevant Files Inventory

New Files to Create

• apps/api/src/db/migrations/031_add_spatial_hotspot_incentives.sql
• apps/api/src/routes/spatial-hotspots.ts
• apps/api/src/lib/workers/spatialMetricsWorker.ts
• tests/concurrency/spatial_hotspot_stress.test.ts
• mobile/frontend/src/components/SpatialHotspotMapOverlay.tsx

Existing Files to Modify

• apps/api/src/lib/h3-spatial-index.ts
• apps/api/src/lib/order-allocator.ts
• apps/api/src/routes/provider.ts
• apps/api/src/app.ts
• mobile/frontend/src/pages/Home.tsx

---

9. Acceptance Criteria

• H3 cell metrics worker updates demand ratios every 30 seconds.
• Hotspot fee multipliers scale dynamically from 1.0x up to a maximum 2.0x.
• Provider allocation algorithm prioritizes high-demand spatial cells.

---

10. Contributor Notes

• ⚠️ Geofence Verification: ALWAYS verify provider GPS coordinates against H3 cell boundaries before granting hotspot fee multipliers.

[ryzen-xp]

Hi maintainers 👋
I’m a blockchain developer with strong expertise in Stellar, Rust,TS and Stellar SDK integrations. I’ve worked on multiple Stellar-based smart contract and backend systems.

I understand the scope of this issue and can deliver a reliable, production-quality solution with proper tests and documentation.
Plz assign me !!

ETA: 44 hours

[DevSolex]

Hi Maintainer,

I’m a smart contract and full-stack developer and would love to contribute to this issue. I’m an experienced contributor with hands-on expertise in Rust, Soroban, Cairo, and TypeScript.

I’m passionate about building secure, scalable blockchain solutions, with a strong emphasis on writing clean and maintainable code. Based on the scope of this issue, I’m confident I can deliver a complete solution within 24 hours of assignment.

I’d greatly appreciate the opportunity to contribute and help move this forward.

[bamiebot-maker]

Hi team! 🦊 I'm ready to tackle this task. My technical background aligns well with this issue, and I can have a clean, tested Pull Request ready for review within your expected timeframe. Please let me assign me so I can begin

[grantfox-oss]

🦊 GrantFox — @bamiebot-maker 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 #421)
2. Your PR will be reviewed by the Nullifier-Systems maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!

@bamiebot-maker's PR #423 was approved and merged by @jotel-dev.

🏆 @bamiebot-maker: You earned 40 FoxPoints for this contribution! Your current tier: Builder (1,188 total points). Track your full progress on GrantFox.

👏 Great work, @bamiebot-maker! Keep contributing to Nullifier-Systems.