# Session Payment

The `SessionPayment` smart contract forms the **financial backbone** of the Cortensor session system. It manages **deposits, payments, and withdrawals** between users (sessions) and service providers (nodes/miners), ensuring a secure and transparent accounting process for AI inference services across the decentralized network.

***

### Purpose

* Allow users to deposit ETH or ERC20 tokens for session-based inference requests.
* Track session ownership and network contribution per session.
* Facilitate and allocate payments to nodes based on actual usage.
* Enable nodes to claim their earned payments securely.

***

### Inheritance

* **`AccessControl`**: Provides role-based permissions for contract functions.
* **`ReentrancyGuard`**: Prevents reentrant calls during fund transfers.

***

### Roles

| Role                    | Description                                                                         |
| ----------------------- | ----------------------------------------------------------------------------------- |
| `ADMIN_ROLE`            | Full administrative control for emergency actions or token recovery                 |
| `SESSION_CONTRACT_ROLE` | Authorized to call payment-related session functions (usually the Session contract) |

***

### Key Data Structures

* **`Account`**: Tracks session data like ID, owner, payment amount, and timestamps.
* **`sessionBalances`**: ETH/token balance associated with each session.
* **`nodeLastUsedTimestamps`**: Timestamp logs for node activity.
* **`sessions`**: Maps session IDs to owner addresses.
* **`sessionNetworkUsage`**: Records cumulative session payments made to the network.
* **`totalNetworkBalance`**: Tracks available funds for node payments.
* **`nodePendingPayments`**: Accumulated payments owed to nodes before withdrawal.

***

### Core Payment Flow

#### 1. Session Deposits

Users deposit ETH (or tokens) via `depositToSession`. Funds are held in the session’s internal balance.

#### 2. Network Contribution

Session-based tasks pay into the network treasury using `payFromSessionToNetwork`, recording usage via `sessionNetworkUsage`.

#### 3. Node Allocation

Payments are distributed to eligible nodes through `allocateNodePayments`, using tracked usage and performance metrics.

#### 4. Node Withdrawals

Nodes can withdraw earned funds via `withdrawNodePayment` once they’re allocated.

***

### Key Functions

#### Session Management

* `registerSession(sessionId, owner)`: Registers a new session.
* `getSessionBalance(sessionId)`: Returns balance of the session.
* `depositToSession(sessionId)`: Allows ETH deposits to a session.
* `withdrawFromSession(sessionId)`: Allows ETH withdrawal by session owner.

#### Network Treasury

* `payFromSessionToNetwork(sessionId, amount)`: Transfers balance from session to network.
* `getSessionNetworkUsage(sessionId)`: Returns total contribution of a session to the network.

#### Node Payments

* `allocateNodePayments(address[] nodes, uint256 amountPerNode)`: Allocates payments to active nodes.
* `withdrawNodePayment(address node)`: Allows nodes to withdraw their funds.
* `updateNodeLastUsedTimestamp(address node)`: Updates node's last usage.
* `deleteNodeLastUsedTimestamp(address node)`: Removes node usage entry.

#### Admin & Emergency

* `adminWithdrawToken(tokenAddress)`: Allows recovery of mistakenly sent tokens.
* Emergency ETH withdrawal for recovery and debugging.

***

### Security Features

* **Role-Based Access**: Only authorized contracts and admins can perform sensitive actions.
* **ReentrancyGuard**: Protects ETH withdrawal functions.
* **Balance & Session Validations**: Prevent overdrafts or unauthorized access.
* **Per-Session Tracking**: Clear accounting for funds paid into the network.

***

### Events

| Event                                    | Trigger                          |
| ---------------------------------------- | -------------------------------- |
| `DepositToSession(sessionId, amount)`    | When user deposits ETH           |
| `WithdrawFromSession(sessionId, amount)` | When session owner withdraws ETH |
| `SessionRegistered(sessionId, owner)`    | New session registration         |
| `NodeTimestampUpdated(node)`             | Node activity timestamp update   |
| `PaymentToNetwork(sessionId, amount)`    | Session pays into the network    |
| `NodePaymentAllocated(node, amount)`     | Payment allocated to node        |
| `NodePaymentWithdrawn(node, amount)`     | Node claims their earned payment |

***

### Summary

The `SessionPayment` contract plays a **crucial role in managing payments** between users and the network. It ensures:

* Transparent and secure session-level accounting.
* Accurate tracking of network contributions.
* Fair and reliable reward distribution to nodes.
* Protection against common security vulnerabilities.

This module is essential for sustaining Cortensor's decentralized economic model while maintaining operational accountability and trust across participants.