Crate nvana_rev_epoch 

nvana_rev_epoch

A high-precision revenue distribution library implementing time-decay bonus epochs.

Overview

nvana_rev_epoch provides a flexible, trait-based system for distributing revenue to participants with time-decay bonuses that reward early participation. Originally designed for Solana programs, the library is suitable for any environment requiring precise, overflow-safe revenue distribution.

Core Concepts

Epochs

An epoch is a fixed time window during which:

1. Users add shares to participate
2. Revenue accumulates in a pot
3. Early participants receive bonus multipliers
4. At epoch end, revenue is distributed proportionally

Time-Decay Bonuses

The bonus system uses linear decay from maximum at epoch start to zero at epoch end:

progress = (time - epoch_start) / epoch_duration
bonus = max_bonus_bps * (1 - progress)
effective_shares = base_shares * (1 + bonus)

For example, with a 100% maximum bonus:

• Shares added at epoch start: 2x multiplier (100% bonus)
• Shares added at epoch midpoint: 1.5x multiplier (50% bonus)
• Shares added at epoch end: 1x multiplier (0% bonus)

WAD Scaling

The library uses WAD scaling (10^18) for high-precision fixed-point arithmetic:

• Shares are stored as u128 values scaled by 10^18
• Revenue-per-share calculations maintain 18 decimal places
• Final revenue amounts are floored to u64 (native token amounts)

Architecture

The system uses a trait-based design that separates business logic from storage:

• RevEpochConfig - Global configuration singleton
• RevEpochDistributor - Per-epoch accounting ledger
• RevEpochUserGlobalAccount - Per-user revenue accumulator
• RevEpochUserLocalAccount - Per-user per-epoch participation

This design allows flexible storage backends (Solana accounts, databases, memory) while maintaining consistent, tested business logic.

Usage Example

use nvana_rev_epoch::*;

// Define your storage types

// 1. Create a new epoch
let epoch_start = 1000;
create_new_epoch(&mut config, epoch_start)?;

// 2. User adds shares (early = high bonus)
let shares = 1000;
let timestamp = epoch_start + 100; // Early in epoch
add_shares(&config, &mut distributor, &mut user_local, shares, timestamp)?;

// 3. Add revenue to the pot
distributor.increase_pot_by(50_000)?;

// 4. Settle epoch after duration passes
let epoch_end = epoch_start + config.get_epoch_duration();
settle_epoch(&config, &mut distributor, epoch_end)?;

// 5. User claims their reward
let revenue = settle_epoch_for_user(
    &distributor,
    &mut user_local,
    &mut user_global
)?;

// 6. User withdraws
let amount = user_collect_rev(&mut user_global);

Safety Guarantees

The library prioritizes safety for mission-critical financial applications:

• No Unsafe Code: #![deny(unsafe_code)] enforced at compile time
• Overflow Protection: All arithmetic uses checked operations
• Solana Compatible: Handles u64::MAX token amounts correctly
• Precision Preservation: WAD scaling minimizes rounding errors

Solana Considerations

The library is designed for Solana programs:

• Token amounts use u64 (native Solana type)
• Timestamps use u64 seconds (Unix time)
• All overflow scenarios tested with u64::MAX values

Error Handling

All operations return Result<T> with descriptive RevEpochError variants. Errors are cheap to clone and compare (Copy + PartialEq), suitable for performance-critical contexts.

Feature Highlights

• ✅ Time-decay bonus system with linear decay
• ✅ WAD-scaled precision (18 decimals)
• ✅ Overflow protection throughout
• ✅ Zero-cost trait abstractions
• ✅ Flexible storage backends
• ✅ Comprehensive test coverage
• ✅ Mission-critical code quality

Re-exports

pub use error::Result;

pub use error::RevEpochError;

pub use program::add_shares;

pub use program::create_new_epoch;

pub use program::settle_epoch;

pub use program::settle_epoch_for_user;

pub use program::user_collect_rev;

pub use traits::RevEpochConfig;

pub use traits::RevEpochDistributor;

pub use traits::RevEpochUserGlobalAccount;

pub use traits::RevEpochUserLocalAccount;

pub use types::constants;

pub use types::Mbps;

pub use types::Seconds;

Modules

error

Error types for the RevEpoch system.

program

Core program logic for revenue distribution epochs.

traits

Trait definitions for the RevEpoch system.

types

Type definitions and constants for the RevEpoch system.