SessionPaymentStaking

Status: Design Module: Payment Layer Integration: SessionV2, SessionPayment, NodePayment, Validator Purpose: Implements stake-based payment velocity and network-funded sessions.

The SessionPaymentStaking contract introduces a Stake-to-Use payment model that allows developers to access Cortensor’s inference services based on their staking commitment, rather than requiring upfront per-task deposits.

It preserves full backward compatibility with the existing SessionPayment pipeline while adding rate limiting, stake-based velocity control, and network-funded session allocation.

Core Problem Solved

Traditional Challenge

  • Users must prepay for each session or task.

  • Costs are unpredictable — difficult to plan and budget.

  • High friction discourages frequent or small task submissions.

  • Stake size does not affect access speed or task velocity.

Stake-to-Use Solution

  • Network admin deposits $COR into a shared funding pool.

  • Users stake tokens to unlock usage velocity credits.

  • Sessions are automatically funded from the pool, not user wallets.

  • Rate limiting enforces fairness and prevents abuse.

  • Creates predictable usage and smooth cash flow for developers.

Architecture Components

1. Network Deposit Pool

uint256 public totalNetworkAdminDeposits;
uint256 public totalNetworkDepositPoolBalance;

Purpose: Central funding source for all staking-based sessions.

Management: Admin-controlled, tracks lifetime deposits and current balances.

Funding: Supports both ERC20 $COR and native tokens.

2. Session Payment Type Tracking

mapping(uint256 => bool) public isSessionStakingPayment;

Purpose: Indicates which sessions use the staking model versus direct payment.

Integration: Referenced by SessionV2 for routing logic.

Effect: Enables dual payment coexistence (direct pay & stake-to-use).

3. Rate Limiting System

mapping(address => uint256) public userWindowStart;
mapping(address => uint256) public userWindowConsumed;
mapping(address => uint256) public userWindowLimit;
mapping(address => uint256) public userLastUpdate;

uint256 public windowDuration = 86400; // 24 hours

Purpose: Prevents abuse and smooths access velocity.

Algorithm: Sliding window with auto-reset.

Configuration: Admin can adjust limits, durations, and ratios.

4. Staking Integration

mapping(address => uint256) public userStakingBalance;
mapping(address => uint256) public userStakingExpirationDate;

uint256 public stakingToLimitRatio = 1000;
uint256 public minimumWindowLimit = 10;

Purpose: Converts staking amount into daily velocity limits.

Formula:

windowLimit = max((stakingAmount * stakingToLimitRatio) / 1e18, minimumWindowLimit)

Safeguards: Minimum limits guarantee basic access even with small stakes.

Payment Flow Integration

Traditional Payment Flow (Unchanged)

  1. User → depositToSession() → Session balance.

  2. Session → payFromSessionToNetwork() → Network credit.

  3. Network → allocateNodePayments() → Node distribution.

  4. Nodes → withdrawNodePayment() → Final token transfer.

New Stake-to-Use Flow

  1. Admin → depositToNetworkDeposit() → Shared pool.

  2. SessionV2 → checkAndUpdateRateLimit() → Validate stake velocity.

  3. SessionV2 → depositToSessionFromNetworkDeposit() → Fund session.

  4. Normal settlement continues via existing flow.

Dual Model Coexistence

Type

Funding Source

Mechanism

Direct Pay

User deposits

Per-session payments

Stake-to-Use

Network deposit pool

Rate-limited staking credits

Both models share identical accounting and payout logic for seamless transition.

Key Functional Components

Network Pool Management

function depositToNetworkDeposit(uint256 amount) public;
function depositToNetworkDepositNative() public payable;

Purpose: Funds the shared network deposit pool.

Access: Public (typically admin).

Events: DepositToNetworkDeposit(sender, amount, tokenType)

Session Funding

function depositToSessionFromNetworkDeposit(uint256 sessionId, uint256 amount)
    public onlyAdmin sessionExists(sessionId)

Purpose: Transfers credits from the network pool to a session.

Validation: Checks existence and amount constraints.

Event: DepositToSessionFromNetworkDeposit(sessionId, amount, poolBalance, totalSessionBalances)

Staking Management

function setStakingInfo(address _user, uint256 _amount, uint256 _expirationDate) external onlyAdmin;

Purpose: Defines user stake amount, expiry, and derived velocity.

Automation: Auto-calculates userWindowLimit.

Event: UserWindowLimitUpdated(user, newLimit)

Rate Limiting

function checkAndUpdateRateLimit(address _user, uint256 _amount) public returns (bool allowed);
function canConsumeAmount(address _user, uint256 _amount) public view returns (bool allowed, uint256 remaining);

Purpose: Enforces stake-based access velocity.

Integration: Used by SessionV2 before session funding.

Events: RateLimitConsumed, RateLimitExceeded, RateLimitWindowReset.

Rate Limiting Algorithm

Window Lifecycle

  • Initialization: New window created upon first session request.

  • Auto-reset: Resets after windowDuration (default 24h).

  • Tracking: Records each session consumption.

  • Overflow: Rejects over-limit requests.

Limit Formula

windowLimit = max(
    (stakingAmount * stakingToLimitRatio) / 1e18,
    minimumWindowLimit
)

Example: 5 COR × 1000 = 5000 tasks/day. Minimum: 10 tasks/day baseline.

Event Triggers

  • RateLimitWindowReset — new window started.

  • RateLimitConsumed — task consumption recorded.

  • RateLimitExceeded — rate cap breach detected.

  • UserWindowLimitUpdated — new limit after stake update.

Integration with SessionV2

Session Creation Flow

if (paymentType == PaymentType.StakeToUse) {
    (bool allowed, ) = stakingContract.canConsumeAmount(user, estimatedCost);
    require(allowed, "Rate limit exceeded");

    stakingContract.depositToSessionFromNetworkDeposit(sessionId, estimatedCost);
    stakingContract.checkAndUpdateRateLimit(user, estimatedCost);

    stakingContract.isSessionStakingPayment[sessionId] = true;
}

Task Submission Flow

if (isSessionStakingPayment[sessionId]) {
    // Already funded by staking pool
    // Proceed with normal settlement
} else {
    // Direct payment required
}

Administrative Controls

Pool Management

  • Funding: depositToNetworkDeposit()

  • Monitoring: via totalNetworkDepositPoolBalance

  • Emergency Withdrawals: Admin-only fail-safes

Rate Limit Configurations

  • setStakingToLimitRatio() — adjust stake-to-velocity rate.

  • setMinimumWindowLimit() — ensure minimum access.

  • setWindowDuration() — modify time window.

  • setUserWindowLimit() — override specific user access.

Staking Updates

  • setStakingInfo() — batch updates, cron-compatible.

  • Auto-expiration: expired stakes revert to minimum access.

Event System & Monitoring

Category

Event

Purpose

Financial

DepositToNetworkDeposit

Pool funding tracking

Financial

DepositToSessionFromNetworkDeposit

Session allocation

Rate Limit

RateLimitConsumed

Track per-user velocity usage

Rate Limit

RateLimitExceeded

Detect overuse or abuse

Rate Limit

RateLimitWindowReset

Window lifecycle tracking

Staking

UserWindowLimitUpdated

Stake-based velocity updates

Dashboard Integration: All events are indexable for:

  • User velocity visualization

  • Pool health monitoring

  • Session funding history

Security & Audit Features

Access Control

  • Role-based permissions (Admin, Session, User)

  • Function-specific modifiers

  • Emergency administrative overrides

Double-Entry Accounting

  • Tracks total pool balance vs. session allocations.

  • Maintains historical auditing via totalNetworkAdminDeposits.

Rate Limiting Security

  • Sliding window prevents burst usage.

  • Minimum limits ensure fair baseline.

  • Expiry automatically handled.

  • Full event logging for auditing.

Benefits & Advantages

Audience

Benefit

Developers

Predictable cost model, no per-task payments, velocity scales with stake

Network

Sustainable liquidity, reduced abuse, predictable inflows

Infrastructure

Zero disruption to existing payments, fully backward compatible

Summary

SessionPaymentStaking extends Cortensor’s payment layer into a stake-powered usage model, replacing frictional prepayments with predictable, rate-limited access. It integrates directly with SessionV2 and existing payment flows while remaining modular, auditable, and upgrade-safe, enabling the next evolution of staking-as-utility within the Cortensor network.

PreviousDesigns - WIPNextCommunity & Ecosystem

Last updated