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 contractSessionQueueV2.json
- ABI for the Session Queue V2 contract
Session Management
create
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
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
getSession
function getSession(uint256 sessionId) external view returns (Session memory);
Returns details for a session by ID.
const session = await sessionContract.getSession(0);
getSessionMiners
getSessionMiners
function getEphemeralNodes(uint256 sessionId) external view returns (address[] memory);
Returns ephemeral miners assigned to a session.
const miners = await sessionContract.getEphemeralNodes(0);
updateSession
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
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
getTasksBySessionId
function getTasksBySessionId(uint256 sessionId) public view returns (Task[] memory);
Returns all tasks for a session.
const tasks = await queueContract.getTasksBySessionId(0);
getTaskResults
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 pool1
: Hybrid — dedicated + ephemeral2
: Dedicated — exclusively dedicated miners
Last updated