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,
  uint256 sla,
  uint256 modelIdentifier,
  uint256 reservePeriod,
  uint256 maxTaskExecutionCount
) external;

Creates a new session.

const tx = await sessionContract.create(
  "My Session",
  "Metadata",
  await signer.getAddress(),
  1, 3, 1, 0, 0,
  false,
  0,
  0,
  300,
  5
);
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,
  string calldata clientReference
) 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],
  "my-client-side-reference"
);

---

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