feat: Updated design doc to describe flexible alerting for spending l… (

#2917) * feat: Updated design doc to describe flexible alerting for spending limits. Signed-off-by: ebadiere <[email protected]> * feat: Added a couple of lines addressing the technical alert mechanism. Signed-off-by: ebadiere <[email protected]> feat: Expanded on the tier 3 value determination Signed-off-by: ebadiere <[email protected]> * fix: Removed Average HBar Spent per User per Day Signed-off-by: ebadiere <[email protected]> --------- Signed-off-by: ebadiere <[email protected]>
hashgraph · Sep 13, 2024 · f8e9e89 · f8e9e89
1 parent 01a6013
commit f8e9e89
Showing 1 changed file with 56 additions and 0 deletions.
diff --git a/docs/design/hbar-limiter.md b/docs/design/hbar-limiter.md
@@ -9,9 +9,16 @@
  - [Requirements](#requirements)
  - [Spending Tracking](#spending-tracking)
  - [Spending Limits](#spending-limits)
+ - [Early Detection and Prevention (Preemptive Rate Limit)](#early-detection-and-prevention-preemptive-rate-limit)
  - [Architecture](#architecture)
  - [High-Level Design](#high-level-design)
  - [Class Diagram](#class-diagram)
+ - [Service Layer](#service-layer)
+ - [Database Layer:](#database-layer)
+ - [Support flexible alerting mechanisms for spending thresholds](#support-flexible-alerting-mechanisms-for-spending-thresholds)
+ - [HBar Allocation Strategy](#hbar-allocation-strategy)
+ - [Metrics to Track](#metrics-to-track)
+ - [Allocation Algorithm](#allocation-algorithm)
  - [Additional Considerations](#additional-considerations)
  - [Performance](#performance)
  - [Monitoring and logging](#monitoring-and-logging)
@@ -198,6 +205,55 @@ classDiagram
  EthAddressHbarSpendingPlanRepository --> CacheService : uses
  IpAddressHbarSpendingPlanRepository --> CacheService : uses
 ```
+### Support flexible alerting mechanisms for spending thresholds
+The existing technical infrastructure, prometheus and grafana will be used to trigger alerts. At the time of this writing 10K HBar is the maximum the relay operator can spend in one day, on HashIO.
+
+The rest of this section describes addtional metrics that will be added, with alerts later, to track critical balances, and how new values for those tiers in HashIO will
+be determined.
+
+The initial spending threshold of the Tier 3 General users will be a rough
+estimate based on the current daily spending of the Relay Operator. In order
+to refine this over time a prometheus metric called the `basicSpendingPlanCounter`
+will be used to track the number of unique spending plans. 
+
+The metrics listed below will be added to help determine the best Tier 3 General users over time:
+
+1. Daily Unique Users Counter
+2. Average Daily Users
+3. Dynamic Per-User Limit - Daily budget for the Relay Operator (10K) divided by the average number of users
+4. Time-based Allocation - Allocating the Relay Operator's budget throughout the day to prevent early users from consuming all resources
+5. User History - Track individual user usage over time to identify and manage heavy users
+6. Flexible Limits - Implement a system that can adjust limits based on current usage and time of day
+
+#### HBar Allocation Strategy
+##### Metrics to Track
+1. Daily Unique Users
+2. Total HBar Spent per Day
+3. Rolling Average of Daily Unique Users (e.g., over 7 or 30 days)
+4. Individual User Daily and Monthly Usage
+
+##### Allocation Algorithm
+1. Base Allocation:
+ - Daily Budget / Rolling Average of Daily Unique Users = Base User Limit
+
+2. Time-Based Adjustment:
+ - Divide the day into time slots (e.g., 6 4-hour slots)
+ - Allocate a portion of the daily budget to each slot
+ - Adjust user limits based on remaining budget in the current slot
+
+3. Dynamic User Limit:
+ - Start with the Base User Limit
+ - Adjust based on:
+a. User's historical usage (lower limit for consistently heavy users)
+b. Time of day (higher limits when usage is typically lower)
+c. Current day's usage (increase limits if overall usage is low)
+
+4. Flexible Ceiling:
+ - Implement a hard cap (e.g., 2x Base User Limit) to prevent single user from consuming too much
+
+5. Reserve Pool:
+ - Keep a small portion of the daily budget (e.g., 10%) as a reserve
+ - Use this to accommodate unexpected spikes or high-priority users
 
 ## Additional Considerations