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
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
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.
Last updated