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

Required 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://...";      // RPC URL for the network

Required ABIs

• SessionV2.json - ABI for the Session V2 contract

• SessionQueueV2.json - ABI for the Session Queue V2 contract

---

Session Management

create

function create(
  string memory name,
  string memory metadata,
  address variableAddress,
  uint256 minNumOfNodes,
  uint256 maxNumOfNodes,
  uint256 redundant,
  uint256 numOfValidatorNodes,
  uint256 mode,
  bool reserveEphemeralNodes
) external;

Creates a new session.

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

---

getSessions

function getSessionsByAddress(address userAddr) external view returns (Session[] memory);

Returns all sessions owned by a user address.

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

---

getSession

function getSession(uint256 sessionId) external view returns (Session memory);

Returns details for a session by ID.

const session = await sessionContract.getSession(0);

---

getSessionMiners

function getEphemeralNodes(uint256 sessionId) external view returns (address[] memory);

Returns ephemeral miners assigned to a session.

const miners = await sessionContract.getEphemeralNodes(0);

---

updateSession

function update(
  string memory name,
  string memory metadata,
  uint256 sessionId,
  uint256 minNumOfNodes,
  uint256 maxNumOfNodes,
  uint256 redundant,
  uint256 numOfValidatorNodes,
  uint256 mode
) public;

Updates session configuration.

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

---

Task Management

submit

function submit(
  uint256 sessionId,
  uint256 nodeType,
  string calldata taskData,
  uint256 promptType,
  string calldata promptTemplate,
  uint256[] calldata llmParams
) external;

Submits a task to the session.

await sessionContract.submit(
  0,
  0,
  JSON.stringify({ type: "chat", message: "Hello" }),
  0,
  "",
  [1024, 1, 1, 1, 0, 0]
);

---

getTasksBySessionId

function getTasksBySessionId(uint256 sessionId) public view returns (Task[] memory);

Returns all tasks for a session.

const tasks = await queueContract.getTasksBySessionId(0);

---

getTaskResults

function getTaskResults(uint256 sessionId, uint256 taskId) public view returns (address[] memory, string[] memory);

Returns the results submitted by miners for a specific task.

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

---

Events

SessionV2 Contract Events

• SessionCreated(uint256 sessionId, bytes32 sid, address owner, address[] miners)

• SessionUpdated(uint256 indexed sessionId, address indexed updater, uint256 minNumOfNodes, uint256 maxNumOfNodes, uint256 redundant)

• SessionDeactivated(uint256 indexed sessionId, address indexed deactivator)

---

SessionQueueV2 Contract Events

• TaskQueued(uint256 sessionId, uint256 taskId, uint256 globalId, string taskData)

• TaskAssigned(uint256 sessionId, uint256 taskId, address[] miners)

• TaskEnded(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`);
});

---

Notes

• Use a secure provider (e.g. Alchemy, Infura)

• Wrap contract calls in try/catch

• Monitor for transaction failures

• For production, use hardware wallets for signing

---

Error Handling

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

---

Session Modes

• 0: Ephemeral — shared miner pool

• 1: Hybrid — dedicated + ephemeral

• 2: Dedicated — exclusively dedicated miners