`ogpu.types`¶

Pure data types shared across the whole SDK — enums, exceptions, Receipt, metadata and snapshot dataclasses. This package is a leaf in the dependency graph: nothing here imports from ogpu.protocol, ogpu.client, ogpu.chain, or any other higher layer. Every type is a plain Python data container with no network I/O, no chain access, and no hidden side effects.

What you'll find here:

Enums — typed versions of the uint8 fields returned by the contracts (TaskStatus, SourceStatus, ResponseStatus, Environment, DeliveryMethod, Role).
Errors — the full OGPUError hierarchy, 30 concrete classes grouped into seven abstract domains. See error handling for usage patterns.
Receipt — frozen dataclass returned by every write operation.
Metadata dataclasses — SourceInfo, TaskInfo, TaskInput, SourceMetadata, ImageEnvironments, plus on-chain struct mirrors (SourceParams, TaskParams, ResponseParams) and snapshot types (SourceSnapshot, TaskSnapshot, etc.).

Enums¶

TaskStatus¶

ogpu.types.enums.TaskStatus ¶

Lifecycle state of a Task contract.

Tasks progress through these states as providers attempt, respond, and the client confirms. The protocol transitions happen on the Nexus contract — this enum mirrors the Solidity TaskStatus enum 1:1.

Members

NEW: Task was just published, no attempts yet. ATTEMPTED: At least one provider has called attempt. RESPONDED: At least one provider has submitted a response. CANCELED: Client called cancel_task before any attempts. EXPIRED: Task's expiryTime passed before finalization; set on the next Nexus.attempt call. FINALIZED: A response was confirmed (via confirm_response for MANUAL_CONFIRMATION, or automatically on first submit for FIRST_RESPONSE). Task is done.

Example

task = Task.load("0x...")
task.get_status()
# <TaskStatus.NEW: 0>

task.get_status() == TaskStatus.FINALIZED
# False

SourceStatus¶

ogpu.types.enums.SourceStatus ¶

Lifecycle state of a Source contract.

Sources are either accepting new tasks (ACTIVE) or permanently closed to new tasks (INACTIVE). Inactivation is one-way — once a source is inactivated, it cannot be reactivated. Existing tasks continue to their natural lifecycle but no new tasks can be published against the source.

Members

ACTIVE: Source accepts new tasks. INACTIVE: Source is closed to new tasks. Publishing reverts with SourceInactiveError.

ResponseStatus¶

ogpu.types.enums.ResponseStatus ¶

Lifecycle state of a Response contract.

Responses are either waiting for confirmation (SUBMITTED) or have been confirmed by the client (CONFIRMED). Confirmation releases payment from the vault and finalizes the parent task.

Members

SUBMITTED: Provider submitted a response, awaiting client decision (MANUAL_CONFIRMATION) or automatic confirmation (FIRST_RESPONSE — flips immediately to CONFIRMED). CONFIRMED: Client (or the protocol, for first-response delivery) has confirmed this response as the winner.

Environment¶

ogpu.types.enums.Environment ¶

Docker-compose execution environments supported by a source.

An IntFlag — combine with bitwise OR to indicate that a source provides images for multiple hardware targets. The on-chain imageEnvironments field is a uint8 bitmask using the same values.

Members

CPU: Generic x86_64 CPU-only image (value = 1). NVIDIA: NVIDIA GPU image using CUDA (value = 2). AMD: AMD GPU image using ROCm (value = 4).

Example

Environment.CPU | Environment.NVIDIA
# <Environment.NVIDIA|CPU: 3>

combine_environments(Environment.CPU, Environment.AMD)
# 5

DeliveryMethod¶

ogpu.types.enums.DeliveryMethod ¶

How a Task's winning response is selected.

Set on a source via SourceInfo.deliveryMethod at publish time and inherited by every task published to that source.

Members

MANUAL_CONFIRMATION: Multiple providers can attempt and submit. Client reviews the responses and explicitly calls confirm_response on the one they accept. Slower but higher-quality. FIRST_RESPONSE: The first submitted response is automatically confirmed on-chain. Fast and cheap — no manual client action required. Good for public-result tasks.

Example

from ogpu.client import SourceInfo, DeliveryMethod
info = SourceInfo(..., deliveryMethod=DeliveryMethod.FIRST_RESPONSE)

Role¶

ogpu.types.enums.Role ¶

Identifies which role a signer is acting as.

resolve_signer uses this to pick the right *_PRIVATE_KEY environment variable when no explicit signer is passed:

Role.CLIENT → reads CLIENT_PRIVATE_KEY
Role.PROVIDER → reads PROVIDER_PRIVATE_KEY
Role.MASTER → reads MASTER_PRIVATE_KEY
Role.AGENT → reads AGENT_PRIVATE_KEY

You rarely touch this directly — every high-level wrapper (client.publish_task, agent.register_to, etc.) already knows which role it's acting as and passes it to resolve_signer internally. You only see it in error messages (MissingSignerError(role=...)) or when calling resolve_signer by hand for custom protocol flows.

Note

Agents are not principals in the agent-delegation model — an agent is an address authorized to sign on behalf of a master or client. The role exists purely so the SDK can look up the agent's own env var when it signs. See PRD N1 for the full rationale.

Receipt¶

ogpu.types.receipt.Receipt `dataclass` ¶

Receipt(tx_hash: str, block_number: int, gas_used: int, status: int, logs: list[Any] = list(), timestamp: int = 0)

Result of a successful on-chain transaction.

Every state-changing operation in the SDK returns a Receipt instance — TxExecutor builds it from the raw web3 TxReceipt after the transaction is mined. This gives you a consistent, immutable, typed object to log and inspect without having to touch web3's AttributeDict.

Frozen — create a new instance instead of mutating.

Attributes:

Name	Type	Description
`tx_hash`	`str`	Transaction hash as a 0x-prefixed hex string.
`block_number`	`int`	Block the transaction was included in.
`gas_used`	`int`	Gas actually consumed by the transaction.
`status`	`int`	Transaction status (1 = success, 0 = reverted). The SDK raises `TxRevertError` on status 0, so in practice every `Receipt` you see has `status == 1`.
`logs`	`list[Any]`	Raw event log list from the receipt, useful for custom event decoding.
`timestamp`	`int`	Unix timestamp of the block when available, else 0.

Example

from ogpu.protocol import controller
receipt = controller.cancel_task("0x...", signer=KEY)
print(receipt.tx_hash)
# '0xabc...'
print(receipt.block_number, receipt.gas_used)
# 12345678 21000

tx_hash `instance-attribute` ¶

tx_hash: str

block_number `instance-attribute` ¶

block_number: int

gas_used `instance-attribute` ¶

gas_used: int

status `instance-attribute` ¶

status: int

logs `class-attribute` `instance-attribute` ¶

logs: list[Any] = field(default_factory=list)

timestamp `class-attribute` `instance-attribute` ¶

timestamp: int = 0

from_web3_receipt `classmethod` ¶

from_web3_receipt(receipt: Any, timestamp: int = 0) -> Receipt

Build a Receipt from a raw web3 TxReceipt dict.

Used internally by TxExecutor to wrap the result of web3.eth.wait_for_transaction_receipt. Handles the transaction hash coming in as bytes, HexBytes, or string.

Parameters:

Name	Type	Description	Default
`receipt`	`Any`	The `TxReceipt` dict returned by web3.	required
`timestamp`	`int`	Optional block timestamp, defaults to 0.	`0`

Returns:

Type	Description
`Receipt`	A new `Receipt` instance.

Metadata¶

SourceInfo¶

ogpu.types.metadata.SourceInfo `dataclass` ¶

SourceInfo(name: str, description: str, logoUrl: str, imageEnvs: ImageEnvironments, minPayment: int, minAvailableLockup: int, maxExpiryDuration: int, deliveryMethod: DeliveryMethod = MANUAL_CONFIRMATION)

User-facing source builder.

Construct one of these, then pass it to client.publish_source. The client wrapper handles uploading the metadata to IPFS and building the final SourceParams tuple — this dataclass is a pure data container with no side effects.

Attributes:

Name	Type	Description
`name`	`str`	Human-readable source name.
`description`	`str`	Short description of what the source does.
`logoUrl`	`str`	URL to a logo image (any HTTP-fetchable location).
`imageEnvs`	`ImageEnvironments`	Docker-compose URLs per hardware environment.
`minPayment`	`int`	Minimum wei a task must offer to be publishable against this source.
`minAvailableLockup`	`int`	Minimum vault lockup a provider must hold to register to this source.
`maxExpiryDuration`	`int`	Maximum seconds a task against this source can live before expiring.
`deliveryMethod`	`DeliveryMethod`	How winning responses get confirmed — either `MANUAL_CONFIRMATION` (client explicitly confirms) or `FIRST_RESPONSE` (automatic on first submit).

Example

from web3 import Web3
from ogpu.client import SourceInfo, ImageEnvironments, DeliveryMethod
info = SourceInfo(
    name="sentiment-analyzer",
    description="DistilBERT classifier",
    logoUrl="https://example.com/logo.png",
    imageEnvs=ImageEnvironments(cpu="https://.../compose.yml"),
    minPayment=Web3.to_wei(0.01, "ether"),
    minAvailableLockup=Web3.to_wei(0.5, "ether"),
    maxExpiryDuration=86400,
    deliveryMethod=DeliveryMethod.FIRST_RESPONSE,
)

TaskInfo¶

ogpu.types.metadata.TaskInfo `dataclass` ¶

TaskInfo(source: str, config: TaskInput, expiryTime: int, payment: int)

User-facing task builder.

Construct one of these, then pass it to client.publish_task. The client wrapper uploads config to IPFS and builds the final TaskParams tuple — this dataclass is pure data.

Attributes:

Name	Type	Description
`source`	`str`	Source contract address the task targets.
`config`	`TaskInput`	`TaskInput` holding the function name + data + extras.
`expiryTime`	`int`	Unix timestamp after which the task expires and cannot be attempted. Must be less than `now + source.maxExpiryDuration`.
`payment`	`int`	Amount in wei to pay the winning provider. Must be at least `source.minPayment`.

Example

import time
from web3 import Web3
from ogpu.client import TaskInfo, TaskInput
info = TaskInfo(
    source="0xSOURCE",
    config=TaskInput(function_name="predict", data={"text": "hi"}),
    expiryTime=int(time.time()) + 3600,
    payment=Web3.to_wei(0.01, "ether"),
)

TaskInput¶

ogpu.types.metadata.TaskInput `dataclass` ¶

TaskInput(function_name: str, data: BaseModel | dict[str, Any], **kwargs: Any)

Operational input for a task — function name + data + extras.

The client puts this into TaskInfo.config. The client wrapper uploads it to IPFS before publishing, so the on-chain TaskParams.config field ends up as an IPFS URL. Providers download it, decode the JSON, and call the matching @expose'd handler on their running source.

The function_name field is mandatory — it's how the source framework routes the call to the right handler. Everything else (data, plus any extra kwargs) is passed through unchanged.

Attributes:

Name	Type	Description
`function_name`	`str`	Name of the handler to invoke on the source. Must match an `@ogpu.service.expose()`'d function.
`data`	`BaseModel \| dict[str, Any]`	The actual input payload. Accepts a Pydantic model or a plain dict. Pydantic models are dumped via `model_dump()` before serialization.

Extras

Any additional keyword arguments passed to __init__ become top-level fields in the serialized config alongside function_name and data. Useful for attaching metadata the source handler inspects (priority, sensitivity, campus, ...).

Example

# Plain dict
TaskInput(function_name="predict", data={"text": "hello"})

# Pydantic model
from pydantic import BaseModel
class Req(BaseModel):
    text: str
    top_k: int = 1
TaskInput(function_name="predict", data=Req(text="hi", top_k=5))

# Extras
TaskInput(
    function_name="predict",
    data={"text": "hi"},
    priority="high",
    sensitivity="low",
).to_dict()
# {'function_name': 'predict', 'data': {'text': 'hi'},
#  'priority': 'high', 'sensitivity': 'low'}

to_dict ¶

to_dict() -> dict[str, Any]

Return the JSON-ready dict representation.

data is dumped via model_dump() if it's a Pydantic model, otherwise passed through as-is. Extra kwargs are merged at the top level.

SourceMetadata¶

ogpu.types.metadata.SourceMetadata `dataclass` ¶

SourceMetadata(cpu: str, nvidia: str, amd: str, name: str, description: str, logoUrl: str)

Off-chain metadata package for a source.

This is what gets uploaded to IPFS before Nexus.publishSource is called — the resulting URL goes into SourceParams.imageMetadataUrl. Contains both the docker-compose URLs (one per environment) and the display fields shown in dashboards (name, description, logo).

Formerly named ImageMetadata — the name was misleading because it sounded like just-the-docker-image metadata, when it actually contains the full off-chain source descriptor.

Attributes:

Name	Type	Description
`cpu`	`str`	Docker-compose URL for CPU execution.
`nvidia`	`str`	Docker-compose URL for NVIDIA GPU execution.
`amd`	`str`	Docker-compose URL for AMD GPU execution.
`name`	`str`	Human-readable source name.
`description`	`str`	Short description of what the source does.
`logoUrl`	`str`	URL to a logo image for display.

Example

meta = SourceMetadata(
    cpu="https://.../compose.yml",
    nvidia="",
    amd="",
    name="sentiment-analyzer",
    description="DistilBERT classifier",
    logoUrl="https://example.com/logo.png",
)
meta.to_dict()
# {'cpu': 'https://.../compose.yml', 'nvidia': '', 'amd': '', ...}

ImageEnvironments¶

ogpu.types.metadata.ImageEnvironments `dataclass` ¶

ImageEnvironments(cpu: str = '', nvidia: str = '', amd: str = '')

Docker-compose URLs for each hardware environment a source supports.

A source may provide one, two, or three compose files — one per target hardware. Empty strings mean the source does not support that environment. The client layer translates the non-empty fields into an imageEnvironments bitmask when building SourceParams.

Attributes:

Name	Type	Description
`cpu`	`str`	URL to a docker-compose file for generic CPU execution.
`nvidia`	`str`	URL to a docker-compose file for NVIDIA GPU execution.
`amd`	`str`	URL to a docker-compose file for AMD GPU execution.

Example

ImageEnvironments(cpu="https://raw.githubusercontent.com/.../compose.yml")
ImageEnvironments(
    cpu="https://.../compose.cpu.yml",
    nvidia="https://.../compose.gpu.yml",
)

SourceParams¶

ogpu.types.metadata.SourceParams ¶

Typed mirror of the Solidity Nexus.publishSource input tuple.

You rarely construct this by hand — the client wrapper builds it from a SourceInfo before calling the contract. You do see it coming back from Source.get_params(), and it appears inside SourceSnapshot.

The to_tuple method produces the raw tuple that web3 expects when encoding the transaction data.

Attributes:

Name	Type	Description
`client`	`str`	Address that owns the source (the one who published it).
`imageMetadataUrl`	`str`	IPFS URL pointing at a `SourceMetadata` JSON.
`imageEnvironments`	`int`	Bitmask of `Environment` flags.
`minPayment`	`int`	Minimum wei a task must pay to be publishable.
`minAvailableLockup`	`int`	Minimum vault lockup a provider must hold to register to this source.
`maxExpiryDuration`	`int`	Maximum seconds a task against this source can live before expiring.
`privacyEnabled`	`bool`	Reserved for future use — currently always False.
`optionalParamsUrl`	`str`	Reserved for future use — currently empty.
`deliveryMethod`	`int`	Integer value of the `DeliveryMethod` enum (0 = MANUAL_CONFIRMATION, 1 = FIRST_RESPONSE).
`lastUpdateTime`	`int`	Unix timestamp of the last update to this source.

TaskParams¶

ogpu.types.metadata.TaskParams ¶

Typed mirror of the Solidity Controller.publishTask input tuple.

Built by the client wrapper from a TaskInfo. You see it coming back from Task.get_params(), and it appears inside TaskSnapshot.

Attributes:

Name	Type	Description
`source`	`str`	Source contract address the task targets.
`config`	`str`	IPFS URL pointing at a JSON-encoded `TaskInput`.
`expiryTime`	`int`	Unix timestamp after which the task is considered expired.
`payment`	`int`	Amount in wei the client is willing to pay per completion.

ResponseParams¶

ogpu.types.metadata.ResponseParams `dataclass` ¶

ResponseParams(task: str, provider: str, data: str, payment: int)

Typed mirror of what Response.getResponseParams() returns on-chain.

Also used as the input when a provider calls Nexus.submitResponse — frozen because once constructed, the values are what gets encoded and sent.

Attributes:

Name	Type	Description
`task`	`str`	Task contract address this response is for.
`provider`	`str`	Provider address that produced the response.
`data`	`str`	Off-chain payload URL (typically IPFS).
`payment`	`int`	Wei the provider is claiming for this response.

Example

from ogpu.types import ResponseParams
params = ResponseParams(
    task="0xTASK",
    provider="0xPROV",
    data="https://cipfs.../Qm123",
    payment=10**16,
)

Snapshot dataclasses¶

ogpu.types.metadata.SourceSnapshot `dataclass` ¶

SourceSnapshot(address: str, client: str, status: SourceStatus, params: SourceParams, task_count: int, registrant_count: int)

Frozen batch capture of a source's on-chain state.

Returned by Source.snapshot(). Each field is fetched via one RPC call during the snapshot; after that, reading fields on the snapshot costs nothing — it's just a dataclass.

Does not include paginated fields (tasks, registrants) or IPFS-fetching fields (metadata). Call those methods on the Source instance directly when you need them.

Attributes:

Name	Type	Description
`address`	`str`	Source contract address.
`client`	`str`	Owner of the source.
`status`	`SourceStatus`	Current `SourceStatus`.
`params`	`SourceParams`	Full `SourceParams` tuple from the contract.
`task_count`	`int`	Total number of tasks ever published against this source.
`registrant_count`	`int`	Total number of registered providers.

ogpu.types.metadata.TaskSnapshot `dataclass` ¶

TaskSnapshot(address: str, source: str, status: TaskStatus, params: TaskParams, payment: int, expiry_time: int, delivery_method: DeliveryMethod, attempt_count: int, winning_provider: str | None)

Frozen batch capture of a task's on-chain state.

Returned by Task.snapshot(). See SourceSnapshot for the general pattern — pagination-heavy fields like attempters and responses are omitted.

Attributes:

Name	Type	Description
`address`	`str`	Task contract address.
`source`	`str`	Source contract address this task was published to.
`status`	`TaskStatus`	Current `TaskStatus`.
`params`	`TaskParams`	Full `TaskParams` tuple from the contract.
`payment`	`int`	Payment in wei.
`expiry_time`	`int`	Unix timestamp after which the task expires.
`delivery_method`	`DeliveryMethod`	`DeliveryMethod` for response confirmation.
`attempt_count`	`int`	Number of attempts submitted so far.
`winning_provider`	`str \| None`	Address of the provider whose response was confirmed, or None if not yet finalized.

ogpu.types.metadata.ResponseSnapshot `dataclass` ¶

ResponseSnapshot(address: str, task: str, params: ResponseParams, data: str, status: ResponseStatus, timestamp: int, confirmed: bool)

Frozen batch capture of a response's on-chain state.

Returned by Response.snapshot().

Attributes:

Name	Type	Description
`address`	`str`	Response contract address.
`task`	`str`	Task contract address this response is for.
`params`	`ResponseParams`	Full `ResponseParams` tuple.
`data`	`str`	Raw data URL from the params.
`status`	`ResponseStatus`	Current `ResponseStatus`.
`timestamp`	`int`	Unix timestamp when the response was submitted.
`confirmed`	`bool`	Whether this response has been confirmed.

ogpu.types.metadata.ProviderSnapshot `dataclass` ¶

ProviderSnapshot(address: str, master: str, base_data: str, live_data: str, is_provider: bool, default_agent_disabled: bool, balance: int, lockup: int, unbonding: int, unbonding_timestamp: int, total_earnings: int, frozen_payment: int, sanction: int, is_eligible: bool, is_whitelisted: bool)

Frozen batch capture of a provider's state across Terminal + Vault.

Returned by Provider.snapshot(). Composes reads from the Terminal (pairing, base/live data) and Vault (balance, lockup, earnings, eligibility).

Does not include get_registered_sources() — that's a paginated Nexus read; call it explicitly.

Attributes:

Name	Type	Description
`address`	`str`	Provider address.
`master`	`str`	Address of the master this provider is paired with.
`base_data`	`str`	Long-lived provider metadata URL (base data).
`live_data`	`str`	Short-lived provider status URL (live data).
`is_provider`	`bool`	Whether the address is registered as a provider.
`default_agent_disabled`	`bool`	Whether the default agent delegation is disabled for this provider.
`balance`	`int`	Available vault balance in wei.
`lockup`	`int`	Locked (staked) amount in wei.
`unbonding`	`int`	Amount currently in the unbonding phase.
`unbonding_timestamp`	`int`	When the unbonding matures.
`total_earnings`	`int`	Cumulative earnings across all completed tasks.
`frozen_payment`	`int`	Amount escrowed against pending attempts.
`sanction`	`int`	Sanction amount if any.
`is_eligible`	`bool`	Whether the provider is eligible for new tasks.
`is_whitelisted`	`bool`	Whether the provider is on the vault whitelist.

ogpu.types.metadata.MasterSnapshot `dataclass` ¶

MasterSnapshot(address: str, provider: str, is_master: bool, balance: int, lockup: int, unbonding: int, total_earnings: int, frozen_payment: int, is_eligible: bool, is_whitelisted: bool)

Frozen batch capture of a master's state across Terminal + Vault.

Returned by Master.snapshot(). Lighter than ProviderSnapshot because masters have a smaller surface — no base/live data, no sanction/unbonding timestamps tracked.

Attributes:

Name	Type	Description
`address`	`str`	Master address.
`provider`	`str`	Address of the provider this master is paired with.
`is_master`	`bool`	Whether the address is registered as a master.
`balance`	`int`	Available vault balance in wei.
`lockup`	`int`	Locked amount in wei.
`unbonding`	`int`	Amount currently in the unbonding phase.
`total_earnings`	`int`	Cumulative earnings.
`frozen_payment`	`int`	Amount escrowed against pending task work.
`is_eligible`	`bool`	Whether the master is eligible to manage providers.
`is_whitelisted`	`bool`	Whether the master is on the vault whitelist.

Errors¶

Every SDK exception inherits from OGPUError. See error handling for the full hierarchy and usage.

Base¶

ogpu.types.errors.OGPUError ¶

Root of all SDK exceptions.

Catch this when you want to handle any SDK-originated failure without distinguishing the specific cause — useful for top-level error boundaries, logging, retry loops.

Abstract domain bases¶

ogpu.types.errors.NotFoundError ¶

Abstract: an on-chain entity could not be resolved at the given address.

Raised by the .load() eager constructors of instance classes (Source.load, Task.load, etc.) when the given address doesn't respond to a cheap view call.

ogpu.types.errors.StateError ¶

Abstract: operation is not valid in the current on-chain state.

The entity exists, the caller is authorized, but the state machine disallows the operation — e.g. cancelling a task that's already finalized, confirming a response that's already confirmed.

ogpu.types.errors.PermissionError ¶

Abstract: caller does not have permission for this operation.

Raised when the signer of a transaction is not authorized to perform the requested action — wrong role, wrong owner, not a registered provider, etc.

ogpu.types.errors.VaultError ¶

Abstract: Vault-specific failure.

Raised by ogpu.protocol.vault operations when the vault state does not allow the requested action (insufficient balance, lockup too low, unbonding period not elapsed, etc.).

ogpu.types.errors.TxError ¶

Abstract: transaction-layer failure.

Catches revert, nonce, gas, and RPC issues. These are distinct from StateError in that the problem is at the transaction layer (signing, broadcasting, inclusion) rather than the contract's business logic — though in practice contract reverts are mapped into TxRevertError for consistency.

ogpu.types.errors.ConfigError ¶

Abstract: SDK configuration is missing or invalid.

Raised when the SDK cannot proceed because required configuration (signer, chain, RPC) is missing or malformed.

ogpu.types.errors.IPFSError ¶

Abstract: IPFS publish or fetch failure.

Raised by ogpu.ipfs helpers and by any method that internally uploads or downloads off-chain content (get_metadata, fetch_data).

Concrete errors¶

Exception hierarchy for the OGPU SDK.

Every SDK exception inherits from OGPUError. Seven abstract intermediate classes group concrete errors by failure domain so callers can write precise except clauses without catching unrelated failures.

OGPUError
├── NotFoundError   — entity missing at the given address
├── StateError      — operation not valid in current on-chain state
├── PermissionError — caller is not authorized
├── VaultError      — vault-specific failures
├── TxError         — transaction-layer failures
├── ConfigError     — SDK configuration issues
└── IPFSError       — IPFS publish or fetch failures

Every concrete error carries the data it was raised with (addresses, amounts, reasons) as typed attributes, so you can use them for structured logging without having to parse the message string.

Example

from ogpu.types import InsufficientBalanceError, VaultError, OGPUError

try:
    vault.lock(10**20, signer=KEY)
except InsufficientBalanceError as e:
    print(f"need {e.required}, have {e.available}")
except VaultError:
    print("other vault failure")
except OGPUError:
    print("other SDK failure")

TaskNotFoundError ¶

TaskNotFoundError(address: str)

No Task contract exists at the given address.

Raised by Task.load(address) when the cheap getStatus() probe reverts. Usually means the address is wrong, was never a task, or belongs to a different chain.

SourceNotFoundError ¶

SourceNotFoundError(address: str)

No Source contract exists at the given address.

Raised by Source.load(address) when the cheap getStatus() probe reverts.

ResponseNotFoundError ¶

ResponseNotFoundError(address: str)

No Response contract exists at the given address.

Raised by Response.load(address) when the cheap getStatus() probe reverts.

ProviderNotFoundError ¶

ProviderNotFoundError(address: str)

The given address is not registered as a provider.

Raised by Provider.load(address) when Terminal.isProvider returns False.

MasterNotFoundError ¶

MasterNotFoundError(address: str)

The given address is not registered as a master.

Raised by Master.load(address) when Terminal.isMaster returns False.

TaskExpiredError ¶

TaskExpiredError(task: str, expiry: int)

Task's expiryTime has passed — no more attempts can be submitted.

Attributes:

Name	Type	Description
`task`		Task contract address.
`expiry`		Unix timestamp when the task expired.

TaskAlreadyFinalizedError ¶

TaskAlreadyFinalizedError(task: str)

Task is in FINALIZED state and cannot be modified.

Raised when attempting to cancel or re-finalize a task that has already reached terminal state.

Attributes:

Name	Type	Description
`task`		Task contract address.

ResponseAlreadyConfirmedError ¶

ResponseAlreadyConfirmedError(response: str)

Response is already confirmed — calling confirm again reverts.

Attributes:

Name	Type	Description
`response`		Response contract address.

SourceInactiveError ¶

SourceInactiveError(source: str)

Source is in INACTIVE state and cannot accept new tasks.

Raised by publish_task when the target source has been inactivated via inactivate_source.

Attributes:

Name	Type	Description
`source`		Source contract address.

NotTaskOwnerError ¶

NotTaskOwnerError(task: str, caller: str)

Caller is not the client that owns the target task.

Raised on operations like cancel_task or confirm_response when the signer is not the address that originally published the task.

Attributes:

Name	Type	Description
`task`		Task contract address.
`caller`		Address that tried to call the protected operation.

NotSourceOwnerError ¶

NotSourceOwnerError(source: str, caller: str)

Caller is not the client that owns the target source.

Raised on operations like update_source or inactivate_source when the signer is not the original publisher of the source.

Attributes:

Name	Type	Description
`source`		Source contract address.
`caller`		Address that tried to call the protected operation.

NotMasterError ¶

NotMasterError(account: str)

Account is not registered as a master.

Raised on master-role operations (announce_provider, remove_provider, etc.) when the signer is not a master.

Attributes:

Name	Type	Description
`account`		Address that tried to call the master-role operation.

NotProviderError ¶

NotProviderError(account: str)

Account is not registered as a provider.

Raised on provider-role operations (announce_master, attempt) when the signer is not a provider.

Attributes:

Name	Type	Description
`account`		Address that tried to call the provider-role operation.

InsufficientBalanceError ¶

InsufficientBalanceError(account: str, required: int, available: int)

Vault balance is too low for the requested operation.

Raised by withdraw, lock, or any operation that moves funds when the caller's available balance is less than what they asked for.

Attributes:

Name	Type	Description
`account`		Address whose balance is insufficient.
`required`		Amount the operation needed, in wei.
`available`		Amount actually available, in wei.

InsufficientLockupError ¶

InsufficientLockupError(account: str, required: int, available: int)

Locked (staked) amount is too low for the requested operation.

Raised by unbond when the amount requested exceeds the currently locked balance, or by registration flows that require a minimum lockup per source.

Attributes:

Name	Type	Description
`account`		Address whose lockup is insufficient.
`required`		Amount the operation needed, in wei.
`available`		Amount actually locked, in wei.

UnbondingPeriodNotElapsedError ¶

UnbondingPeriodNotElapsedError(account: str, remaining_seconds: int)

Cannot claim yet — the unbonding cooldown hasn't elapsed.

Attributes:

Name	Type	Description
`account`		Address attempting to claim.
`remaining_seconds`		Seconds left before the unbonding period matures and the claim will succeed.

NotEligibleError ¶

NotEligibleError(account: str)

Account is not eligible for this vault operation.

Raised when Vault.isEligible returns False — typically because the account is not whitelisted or is below some protocol-level eligibility threshold.

Attributes:

Name	Type	Description
`account`		Address that failed the eligibility check.

TxRevertError ¶

TxRevertError(reason: str)

Transaction reverted for a reason the SDK could not map to a typed error.

The SDK maintains a REVERT_PATTERN_MAP that translates known revert strings into specific PermissionError / StateError / VaultError subclasses. Any revert that doesn't match a known pattern ends up here as a fallback.

Attributes:

Name	Type	Description
`reason`		The raw revert reason string extracted from the underlying `ContractLogicError`.

NonceError ¶

NonceError(address: str, tried: int, suggested: int)

Nonce collision that TxExecutor could not auto-recover from.

TxExecutor automatically retries on nonce too low / already known / replacement transaction underpriced — this error is only raised when retries are exhausted. Use ogpu.fix_nonce to manually clear stuck pending transactions.

Attributes:

Name	Type	Description
`address`		Address whose nonce collided.
`tried`		Nonce the SDK attempted to use.
`suggested`		Nonce the SDK suggests using next (or -1 if unknown).

GasError ¶

GasError(reason: str)

Gas-related transaction failure.

Raised when the SDK cannot recover from an underpriced transaction after retry with backoff, or when gas estimation fails.

Attributes:

Name	Type	Description
`reason`		Human-readable description of the failure.

InvalidRpcUrlError ¶

InvalidRpcUrlError(url: str)

RPC URL is not reachable or failed the connectivity probe.

Raised by ChainConfig.set_rpc when Web3.is_connected() returns False against the given URL.

Attributes:

Name	Type	Description
`url`		The RPC URL that failed the probe.

MissingSignerError ¶

MissingSignerError(role: Role | None = None)

No signer provided and no env-var fallback resolved.

For role-based calls this means the relevant *_PRIVATE_KEY env var is not set. For vault calls (where env-var fallback is disabled by design), this means no signer= kwarg was passed.

Attributes:

Name	Type	Description
`role`		The `Role` the operation expected, or `None` for vault calls that require an explicit signer.

InvalidSignerError ¶

InvalidSignerError(reason: str)

Signer value was not a valid key or address.

Raised by resolve_signer when the given value is neither a hex key nor a LocalAccount, or by write operations given malformed address arguments.

Attributes:

Name	Type	Description
`reason`		Human-readable description of why the value was rejected.

ChainNotSupportedError ¶

ChainNotSupportedError(chain_id: object)

Chain identifier does not correspond to a supported OGPU chain.

Raised by ChainConfig.set_chain / set_rpc / get_rpc when the given ChainId is not in CHAIN_CONTRACTS.

Attributes:

Name	Type	Description
`chain_id`		The chain identifier that failed the check.

IPFSFetchError ¶

IPFSFetchError(url: str, reason: str)

Network or JSON-parse failure while fetching from IPFS.

Raised when the HTTP GET fails, the response body is not valid JSON, or the request times out.

Attributes:

Name	Type	Description
`url`		The URL that was being fetched.
`reason`		Human-readable description of the failure.

IPFSGatewayError ¶

IPFSGatewayError(gateway: str, status_code: int)

IPFS gateway returned a non-success HTTP status.

Raised when the gateway responded but with a 4xx or 5xx status, or when the response body is structurally unexpected (missing link field on a publish response, etc.).

Attributes:

Name	Type	Description
`gateway`		The gateway URL that returned the bad status.
`status_code`		The HTTP status code received.

ogpu.types¶

Enums¶

TaskStatus¶

ogpu.types.enums.TaskStatus ¶

SourceStatus¶

ogpu.types.enums.SourceStatus ¶

ResponseStatus¶

ogpu.types.enums.ResponseStatus ¶

Environment¶

ogpu.types.enums.Environment ¶

DeliveryMethod¶

ogpu.types.enums.DeliveryMethod ¶

Role¶

ogpu.types.enums.Role ¶

Receipt¶

ogpu.types.receipt.Receipt dataclass ¶

tx_hash instance-attribute ¶

block_number instance-attribute ¶

gas_used instance-attribute ¶

status instance-attribute ¶

logs class-attribute instance-attribute ¶

timestamp class-attribute instance-attribute ¶

from_web3_receipt classmethod ¶

Metadata¶

SourceInfo¶

ogpu.types.metadata.SourceInfo dataclass ¶

TaskInfo¶

ogpu.types.metadata.TaskInfo dataclass ¶

TaskInput¶

ogpu.types.metadata.TaskInput dataclass ¶

to_dict ¶

SourceMetadata¶

ogpu.types.metadata.SourceMetadata dataclass ¶

ImageEnvironments¶

ogpu.types.metadata.ImageEnvironments dataclass ¶

SourceParams¶

ogpu.types.metadata.SourceParams ¶

TaskParams¶

ogpu.types.metadata.TaskParams ¶

ResponseParams¶

ogpu.types.metadata.ResponseParams dataclass ¶

Snapshot dataclasses¶

ogpu.types.metadata.SourceSnapshot dataclass ¶

ogpu.types.metadata.TaskSnapshot dataclass ¶

ogpu.types.metadata.ResponseSnapshot dataclass ¶

ogpu.types.metadata.ProviderSnapshot dataclass ¶

ogpu.types.metadata.MasterSnapshot dataclass ¶

Errors¶

Base¶

ogpu.types.errors.OGPUError ¶

Abstract domain bases¶

ogpu.types.errors.NotFoundError ¶

ogpu.types.errors.StateError ¶

ogpu.types.errors.PermissionError ¶

ogpu.types.errors.VaultError ¶

ogpu.types.errors.TxError ¶

ogpu.types.errors.ConfigError ¶

ogpu.types.errors.IPFSError ¶

Concrete errors¶

TaskNotFoundError ¶

SourceNotFoundError ¶

ResponseNotFoundError ¶

ProviderNotFoundError ¶

MasterNotFoundError ¶

TaskExpiredError ¶

TaskAlreadyFinalizedError ¶

ResponseAlreadyConfirmedError ¶

SourceInactiveError ¶

NotTaskOwnerError ¶

NotSourceOwnerError ¶

NotMasterError ¶

NotProviderError ¶

InsufficientBalanceError ¶

InsufficientLockupError ¶

UnbondingPeriodNotElapsedError ¶

NotEligibleError ¶

TxRevertError ¶

NonceError ¶

GasError ¶

InvalidRpcUrlError ¶

`ogpu.types`¶

ogpu.types.receipt.Receipt `dataclass` ¶

tx_hash `instance-attribute` ¶

block_number `instance-attribute` ¶

gas_used `instance-attribute` ¶

status `instance-attribute` ¶

logs `class-attribute` `instance-attribute` ¶

timestamp `class-attribute` `instance-attribute` ¶

from_web3_receipt `classmethod` ¶

ogpu.types.metadata.SourceInfo `dataclass` ¶

ogpu.types.metadata.TaskInfo `dataclass` ¶

ogpu.types.metadata.TaskInput `dataclass` ¶

ogpu.types.metadata.SourceMetadata `dataclass` ¶

ogpu.types.metadata.ImageEnvironments `dataclass` ¶

ogpu.types.metadata.ResponseParams `dataclass` ¶

ogpu.types.metadata.SourceSnapshot `dataclass` ¶

ogpu.types.metadata.TaskSnapshot `dataclass` ¶

ogpu.types.metadata.ResponseSnapshot `dataclass` ¶

ogpu.types.metadata.ProviderSnapshot `dataclass` ¶

ogpu.types.metadata.MasterSnapshot `dataclass` ¶