# 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

```bash
npm install ethers
```

#### Configuration

```javascript
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`

<pre class="language-solidity"><code class="lang-solidity">function create(
  string memory name,
  string memory metadata,
  address variableAddress,
  uint256 minNumOfNodes,
  uint256 maxNumOfNodes,
  uint256 redundant,
  uint256 numOfValidatorNodes,
  uint256 mode,
  bool reserveEphemeralNodes,
<strong>  uint256 sla,
</strong>  uint256 modelIdentifier,
  uint256 reservePeriod,
  uint256 maxTaskExecutionCount
) external;
</code></pre>

Creates a new session.

```js
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`

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

Returns all sessions owned by a user address.

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

***

#### `getSession`

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

Returns details for a session by ID.

```js
const session = await sessionContract.getSession(0);
```

***

#### `getSessionMiners`

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

Returns ephemeral miners assigned to a session.

```js
const miners = await sessionContract.getEphemeralNodes(0);
```

***

#### `updateSession`

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

Updates session configuration.

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

***

### Task Management

#### `submit`

```solidity
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.

```js
await sessionContract.submit(
  0,
  0,
  JSON.stringify({ type: "chat", message: "Hello" }),
  0,
  "",
  [1024, 1, 1, 1, 0, 0],
  "my-client-side-reference"
);
```

***

#### `getTasksBySessionId`

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

Returns all tasks for a session.

```js
const tasks = await queueContract.getTasksBySessionId(0);
```

***

#### `getTaskResults`

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

Returns the results submitted by miners for a specific task.

```js
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

```js
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

```js
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