Web3 SDK Reference

Status: WIP — Early Draft

This document provides a comprehensive reference for interacting with Cortensor smart contracts using the ethers.js library. It covers session and task management, along with contract event listening for dApp integrations.

---

Setup

Dependencies

npm install ethers

Configuration

const SESSION_V2_ADDRESS = "0x...";        // SessionV2 contract address
const SESSION_QUEUE_V2_ADDRESS = "0x...";  // SessionQueueV2 contract address
const PUBLIC_RPC_URL = "https://...";      // Public RPC endpoint

ABIs Required

• SessionV2.json

• SessionQueueV2.json

---

Session Management

Create Session

const sessionContract = new ethers.Contract(SESSION_V2_ADDRESS, SessionV2ABI, signer);
const tx = await sessionContract.create(
  "My Session",
  "Metadata",
  await signer.getAddress(),
  1, 3, 1, 0, 0,
  false
);
await tx.wait();

List Sessions by Address

const sessions = await sessionContract.getSessions("0xYourAddress");

Get Session Details

const session = await sessionContract.getSession(0);
const miners = await sessionContract.getSessionMiners(0);

Update Session

await sessionContract.updateSession(
  0,
  "Updated Name",
  "Updated Metadata",
  2, 4, 2
);

---

Task Management

Submit Task

const queueContract = new ethers.Contract(SESSION_QUEUE_V2_ADDRESS, SessionQueueV2ABI, signer);
const tx = await queueContract.submitTask(0, JSON.stringify({ type: "chat", message: "Hello" }));
await tx.wait();

Get Tasks by Session

const tasks = await queueContract.getTasksBySessionId(0);
const [miners, results] = await queueContract.getTaskResults(0, 0);

---

Events

SessionV2 Contract Events

Event	Description	Parameters
SessionCreated	New session created	uint256 sessionId, bytes32 sid, address owner, address[] miners
SessionUpdated	Session updated	uint256 indexed sessionId, address indexed updater, uint256 minNumOfNodes, uint256 maxNumOfNodes, uint256 redundant
SessionDeactivated	Session deactivated	uint256 indexed sessionId, address indexed deactivator
TaskSubmitted	Task submitted	uint256 sessionId, string taskData
TaskAssigned	Task assigned to nodes	uint256 sessionId, uint256 taskId, bytes32[] nodeIds
NodeReleased	Node released from session	bytes32 nodeId, uint256 sessionId
RouterAdded	Router added	address routerAddress, string routerInfo
RouterUpdated	Router updated	address routerAddress, string routerInfo
RouterRemoved	Router removed	address routerAddress
AllRoutersRemoved	All routers removed from a session	uint256 indexed sessionId
DedicatedNodeAdded	Dedicated node added	address indexed nodeAddress
DedicatedNodeRemoved	Dedicated node removed	address indexed nodeAddress
DepositToSession	Funds deposited	uint256 indexed sessionId, address indexed from, uint256 amount
WithdrawFromSession	Funds withdrawn	uint256 indexed sessionId, address indexed to, uint256 amount

SessionQueueV2 Contract Events

Event	Description	Parameters
TaskQueued	Task queued	uint256 sessionId, uint256 taskId, uint256 globalId, string taskData
TaskAssigned	Task assigned to miners	uint256 sessionId, uint256 taskId, address[] miners
TaskAcked	Miner acknowledged task	uint256 sessionId, uint256 taskId, address miner
TaskPrecommitted	Miner precommitted	uint256 sessionId, uint256 taskId, address miner
TaskAllPrecommitted	All miners precommitted	uint256 sessionId, uint256 taskId, address[] miners
TaskPrecommitEnded	Precommit phase ended	uint256 sessionId, uint256 taskId
TaskCommitted	Miner committed	uint256 sessionId, uint256 taskId, address miner
TaskAllCommitted	All miners committed	uint256 sessionId, uint256 taskId, address[] miners
TaskCommitEnded	Commit phase ended	uint256 sessionId, uint256 taskId
TaskEnded	Task completed	uint256 sessionId, uint256 taskId, address[] miners

---

Listening to Events

const provider = new ethers.WebSocketProvider(PUBLIC_RPC_URL.replace('https', 'wss'));
const queueContract = new ethers.Contract(SESSION_QUEUE_V2_ADDRESS, SessionQueueV2ABI, provider);

queueContract.on("TaskEnded", (sessionId, taskId, miners, event) => {
  console.log(`Task ${taskId} in session ${sessionId} completed`);
});

---

Session Modes

Mode	Description
0	Ephemeral session
1	Hybrid session
2	Dedicated session

---

Production Notes

• Use secure RPC providers

• Wrap all calls in try/catch

• Monitor gas costs and transaction status

• Use hardware wallets for critical ops

---

Error Handling

Use robust logging and retry mechanisms:

try {
  const tx = await contract.fn();
  await tx.wait();
} catch (error) {
  console.error("Contract call failed:", error);
}

---

This SDK complements the Web2 REST API by enabling full smart contract integration for decentralized apps using Cortensor.