# 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**

```solidity
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**

```solidity
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**

```solidity
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**

```solidity
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**

```solidity
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**

```solidity
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**

```solidity
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**

```solidity
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**

```solidity
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**

```solidity
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**

```solidity
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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cortensor.network/technical-architecture/designs-wip/sessionpaymentstaking.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.