> For the complete documentation index, see [llms.txt](https://opengpu-network.gitbook.io/opengpu-network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://opengpu-network.gitbook.io/opengpu-network/ecosystem/protocol.md).

# Protocol

Smart contracts governing the compute marketplace.

## Contracts

| Contract       | Address                                      | Purpose                                     |
| -------------- | -------------------------------------------- | ------------------------------------------- |
| **Nexus**      | `0x2b0cC6058313801D5feb184a539e3a0C5A87a6a1` | Source/task registry, provider registration |
| **Controller** | `0x8661F4B9c30e07A04d795A192478dfD905625a1D` | Task publishing and confirmation            |
| **Terminal**   | `0xaEBC7b712D38Fc4d841f0732c21B8774339869D3` | Provider-master wallet pairing              |
| **Vault**      | `0xa5c582254AA313528898311362bc698b041580cC` | Staking, payments, escrow                   |

## How They Work Together

```
Client publishes Source → Nexus
Provider registers → Nexus + Terminal
Client publishes Task → Nexus (payment → Vault)
Provider responds → Nexus
Task finalized → Vault releases payment
```

## Contract Reference

ABIs: [Nexus](https://gist.githubusercontent.com/can-ogpu/1ced6257c49a8c0e77ddb3f70f6f6697/raw/Nexus.json) | [Controller](https://gist.githubusercontent.com/can-ogpu/1ced6257c49a8c0e77ddb3f70f6f6697/raw/Controller.json) | [Terminal](https://gist.githubusercontent.com/can-ogpu/1ced6257c49a8c0e77ddb3f70f6f6697/raw/Terminal.json) | [Vault](https://gist.githubusercontent.com/can-ogpu/1ced6257c49a8c0e77ddb3f70f6f6697/raw/Vault.json)

### Data Structures

**SourceParams**

| Field              | Type    | Description                  |
| ------------------ | ------- | ---------------------------- |
| client             | address | Owner address                |
| imageMetadataUrl   | string  | Docker config URL            |
| imageEnvironments  | uint8   | Supported hardware (bitmask) |
| minPayment         | uint256 | Min OGPU per task            |
| minAvailableLockup | uint256 | Required provider stake      |
| maxExpiryDuration  | uint256 | Max task duration            |
| privacyEnabled     | bool    | Encrypt task data            |
| deliveryMethod     | uint8   | 0=FirstResponse, 1=Manual    |

**TaskParams**

| Field      | Type    | Description        |
| ---------- | ------- | ------------------ |
| source     | address | Source contract    |
| config     | string  | Task config JSON   |
| expiryTime | uint256 | Deadline timestamp |
| payment    | uint256 | OGPU payment       |

**ResponseParams**

| Field    | Type    | Description      |
| -------- | ------- | ---------------- |
| task     | address | Task contract    |
| provider | address | Provider address |
| data     | string  | Result data      |
| payment  | uint256 | Claimed payment  |

### Source Lifecycle

| Contract | Function                             | Description                   |
| -------- | ------------------------------------ | ----------------------------- |
| Nexus    | `publishSource(SourceParams)`        | Deploy source                 |
| Nexus    | `updateSource(source, SourceParams)` | Update source config          |
| Nexus    | `register(source, provider, env)`    | Provider registers for source |
| Nexus    | `unregister(source, provider)`       | Provider unregisters          |

### Task Lifecycle

| Contract   | Function                                    | Description                       |
| ---------- | ------------------------------------------- | --------------------------------- |
| Controller | `publishTask(TaskParams)`                   | Submit task with payment          |
| Nexus      | `attempt(task, provider, suggestedPayment)` | Provider signals intent           |
| Nexus      | `submitResponse(ResponseParams)`            | Provider submits result           |
| Controller | `confirmResponse(response)`                 | Required if deliveryMethod=Manual |
| Controller | `cancelTask(task)`                          | Cancel pending task               |

### Wallet Pairing

| Contract | Function                             | Description                       |
| -------- | ------------------------------------ | --------------------------------- |
| Terminal | `announceProvider(provider, amount)` | Master announces provider address |
| Terminal | `announceMaster(master)`             | Provider announces master address |

Both must announce each other. Once matched, master can manage vault on provider's behalf.

### Vault Operations

| Contract | Function           | Description      |
| -------- | ------------------ | ---------------- |
| Vault    | `deposit(account)` | Deposit OGPU     |
| Vault    | `lock(amount)`     | Lock stake       |
| Vault    | `unbond(amount)`   | Start unbonding  |
| Vault    | `withdraw(amount)` | Withdraw balance |
| Vault    | `claim()`          | Claim rewards    |

## Interacting with the Protocol

| Method          | Use Case                                   |
| --------------- | ------------------------------------------ |
| Client App      | Source and task publishing over UI         |
| Provider Suite  | Task execution                             |
| Management dApp | Registration, monitoring, vault management |
| SDK             | Programmatic source and task publishing    |
| Direct RPC      | Full control via contract calls            |

All contracts are deployed on the OpenGPU Blockchain and can be interacted with using standard EVM tooling.

> See [How It Works](/opengpu-network/ecosystem/how-it-works.md) for the task lifecycle.