Skip to main content

Module diff_adjust

psibase::services

Module diff_adjust 

Source
Expand description

§Description

Dynamic difficulty adjustment service for adaptive rate limiting

This service provides a self-adjusting rate limiting mechanism that dynamically modifies difficulty thresholds based on observed activity patterns. Each rate limiter is represented by an NFT, allowing ownership-based administration.

§Mechanics

The service operates on a time-windowed counter system:

  1. Activity Tracking: A consumer account increments a counter each time an action occurs. The counter accumulates activity within a configurable time window.

  2. Difficulty Adjustment:

    • Below Target: If the counter is below target_min when a window elapses, the difficulty decreases by a configured percentage (subject to a floor value).
    • Above Target: If the counter exceeds target_max at any point, the difficulty immediately increases by a configured percentage, the counter resets, and a new window begins. If one increment pushes the counter past target_max by one or more whole multiples of target_max, the difficulty is increased by the configured percentage once per multiple.

  3. Window-Based Decay: After each window period (window_seconds), if activity was below the minimum target, difficulty decays proportionally for each complete window that elapsed.

  4. Bounded Adjustments: Difficulty cannot fall below floor_difficulty, ensuring a minimum security threshold is maintained.

§Roles

  • Admin: The NFT owner can configure all parameters (targets, window, percentages, floor). The NFT is initially minted to the account that creates the rate limiter, but can be transferred to change administration.
  • Consumer: The account designated at creation time can increment the counter and query difficulty. The consumer is automatically set to the account that calls create() and cannot be changed after creation. Initially, the creator is both admin and consumer, but the admin role can be transferred via NFT ownership while the consumer remains fixed.

Re-exports§

pub use Service::SERVICE;
pub use Service::Actions;
pub use Service::Wrapper;
pub use Service::action_structs;

Modules§

Service