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.