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


---

# 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/modular-architecture-and-smart-contract-interactions/session-payment.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.