Atoma smart contract

Description of Atoma's smart contract role for orchestrating compute resources

IMPORTANT:

The Atoma smart contract is currently deployed on Sui's testnet.
Atoma's contract package id (on testnet) is:
Atoma's Atoma DB object ID is:
The Atoma's testnet faucet TOMA contract package id is:

Atoma Smart Contract Documentation

Overview

The Atoma smart contract manages compute resources on the Atoma Network and serves as the payment platform for accessing AI compute. This document outlines the key components of the smart contract logic.

Tasks in the Atoma Network

Tasks are fundamental units of computation in the Atoma network, representing various AI-related operations that can be performed. They are defined by the Task struct and play a crucial role in orchestrating the network's computational resources.

Task Structure

A Task in Atoma includes the following key components:1. owner: The optional address of the user who created the task.

role: The specific purpose of the task (e.g., inference, embedding, fine-tuning).
model_name: An optional identifier for the AI model associated with the task.
is_deprecated: Indicates whether the task is still active or deprecated.
deprecated_at_epoch: The epoch when the task was deprecated, if applicable.
security_level: The security requirements for the task execution.
subscribed_nodes: List of nodes that have subscribed to perform this task.
minimum_reputation_level: The minimum reputation value that nodes must have to support the task.

Task Roles

Tasks are categorized into different roles:

Chat completions
Embeddings
Fine-tuning
Training
Vision
Text to speech
Speech to text
Etc

Optimizations

In the future, tasks can specify optimizations to enhance performance, these include:

Flash Attention
Prompt Caching
Quantization
Pruning
Speculative Decoding

Security Levels

Tasks can have different security requirements:

No Security (default)
Sampling Consensus: Relies on Atoma's Sampling Consensus algorithm to ensure that nodes do not tamper their generated responses.
Confidential compute (through TEEs): Relies on hardware based TEEs to ensure that privacy is maintained for both input and outputs of each task execution. It further provides high verifiability assurances (that is, nodes did not tampered the output in any form).

Task Lifecycle

1. Creation: Tasks are created with specific parameters defining their requirements and constraints.

Subscription: Nodes can subscribe to tasks they are capable of performing.
Execution: When requested, subscribed nodes execute the task according to its specifications.
Deprecation: Tasks can be deprecated, preventing new executions while maintaining historical data.

Tasks in the Atoma network provide a flexible and comprehensive way to define, manage, and execute various AI computations, ensuring efficient resource allocation and diverse computational capabilities across the network.

Implementation:

Tasks can specify required efficiency metrics during creation
Nodes can advertise if these are able to handle such efficiency requirements
The sampling mechanism considers these efficiency metrics when selecting nodes for task execution

Optimization types allow for more efficient resource allocation and task execution, tailoring the network's performance to specific use cases.

Stacks in the Atoma Network

Stacks are a fundamental concept in the Atoma network, representing a collection of compute units purchased by users for specific tasks. They serve as the primary mechanism for executing computational tasks and managing the associated payments and settlements.

Stack Structure A Stack in Atoma includes the following key components:

owner: Address of the user who created the stack
price: Price per compute unit in TOMA tokens
num_compute_units: Number of compute units remaining in the stack
selected_node_id: StackSmallId of the node selected to process the requests in the stack
task_small_id: The associated task TaskSmallId

Purpose of Stacks Stacks serve several crucial purposes in the Atoma network:

Resource Allocation: They allow users to pre-allocate compute resources for specific tasks.
Payment Management: Stacks facilitate the payment process between users and nodes.
Execution Tracking: They provide a way to track the execution of computational tasks.
Settlement Mechanism: Stacks enable a robust settlement process, ensuring fair compensation for nodes and refunds for unused resources.

Stack Creation and Node Selection When a user creates a Stack:

The user specifies the task, number of compute units, and price per unit.
The system selects an appropriate node based on the task requirements and node availability.
The selection process considers factors such as node reputation, price, and capability to perform the task.
A StackCreatedEvent is emitted, containing details about the new Stack.

Stack Execution and Settlement The settlement process varies based on the security level of the associated task:

No Security (Default Case):
- The selected node executes the task and submits the results.
- The node claims the payment for the used compute units.
- Any unused compute units are refunded to the user.
- A StackSettlementTicketClaimedEvent is emitted.
Sampling Consensus:
- The selected node executes the task and submits the results along with a commitment (committed_stack_proof).
- The system may randomly select additional nodes for attestation (cross-validation).
- Attestation nodes verify the execution and submit their own commitments.
- If all commitments match, the settlement proceeds.
- In case of a mismatch, a dispute resolution process is initiated.
- A StackSettlementTicketEvent is emitted upon successful settlement.
Trusted Execution Environment (TEE):
- The selected node (running in a TEE) executes the task and provides a proof of correct execution.
- The proof is verified on-chain.
- Upon successful verification, the settlement proceeds.

Attestation Process (for Sampling Consensus)

The system selects attestation nodes based on the cross_validation_probability_permille and cross_validation_extra_nodes_count parameters.
Attestation nodes re-execute the task and generate their own commitments.
These commitments are compared with the original node's commitment.
If all commitments match, the settlement is considered valid.
In case of mismatches, a StackAttestationDisputeEvent is emitted, and the dispute resolution process begins.

Fee Calculation Fees are calculated based on the following factors:

Base fee: price * num_claimed_compute_units
Sampling Consensus fee: An additional fee (sampling_consensus_charge_permille) is applied for tasks using Sampling Consensus.
Attestation fee: For cross-validated executions, an extra fee (cross_validation_extra_nodes_charge_permille) is applied for each attestation node.

The total fee is deducted from the Stack's allocated funds. Any unused funds are refunded to the user upon settlement.

Dispute Resolution In case of disputes:

The system initiates a dispute resolution process.
Trusted oracle nodes may be called upon to determine the correct result.
Nodes providing incorrect results may be slashed (have their collateral penalized).
Honest nodes (including the oracle) receive a portion of the slashed tokens as a reward.

Stack Lifecycle

Creation: User creates a Stack, allocating funds and compute units.
Execution: Selected node performs the computational task.
Settlement Attempt: Node attempts to settle the Stack (StackTrySettleEvent).
Attestation (if applicable): Additional nodes verify the execution.
Settlement: Successful settlement results in payment distribution and refunds.
Dispute Resolution (if necessary): Resolves conflicts in task execution or attestation.

Stacks play a crucial role in the Atoma network, providing a structured way to manage computational resources, ensure fair compensation, and maintain the integrity of task execution across various security levels.

Atoma Db

The AtomaDb is the central data structure that manages the global state of the Atoma network. It's implemented as a shared object on the Sui blockchain.

Key components of AtomaDb:

tickets: UID for settlement tickets associated with the database
next_node_small_id: Tracks total registered nodes for generating sequential SmallIds
next_task_small_id: Tracks registered tasks for generating sequential SmallIds
nodes: Table storing information about each node
models: ObjectTable storing information about each model and its supporting nodes
tasks: ObjectTable storing information about registered tasks
fee_treasury: Balance of collected fees
communal_treasury: Balance of slashed collateral
cross_validation_probability_permille: Probability of cross-validation
cross_validation_extra_nodes_count: Number of extra nodes sampled for cross-validation
Other configuration parameters (e.g., registration collateral, slashing percentages)

Model Management

Models on Atoma represent the AI models that can be executed on the network. Each model is associated with one or more echelons and can be enabled or disabled.

Key aspects of model management:

Models are stored in the models ObjectTable of AtomaDb
Each model has a unique name, modality, and a vector of supported echelons
Models can be added, removed, enabled, or disabled by the contract admin
Nodes can subscribe to serve specific models within their echelon

Functions for model management:

add_model: Adds a new model to the system
remove_model: Removes a model from the system
disable_model / enable_model: Toggles the availability of a model

Echelon System

Echelons represent performance tiers within the Atoma network. They allow for differentiation of node capabilities and pricing.

Key aspects of the echelon system:

Each model supports one or more echelons
Echelons are identified by EchelonId
Echelons define fees, performance expectations, and settlement timeouts
Nodes subscribe to models within specific echelons

Echelon properties:

input_fee_per_token / output_fee_per_token: Fees charged by nodes in this echelon
relative_performance: Influences the likelihood of echelon selection
settlement_timeout_ms: Maximum time for settling a prompt
oracles: Set of trusted nodes that can settle disputes
nodes: TableVec of nodes supporting this echelon

Slashing Mechanism

Slashing is a penalty mechanism to discourage malicious behavior or poor performance from nodes.

Key aspects of the slashing mechanism:

Nodes provide collateral upon registration, which can be slashed
Slashing occurs for timeout or incorrect results
Slashed tokens are moved to the communal treasury

Slashing parameters:

permille_to_slash_node_on_timeout: Percentage of collateral slashed for timeouts
permille_for_oracle_on_dispute: Percentage of slashed tokens given to the settling oracle
permille_for_honest_nodes_on_dispute: Percentage of slashed tokens distributed to honest nodes

Slashing functions:

slash_node_on_timeout: Slashes a node's collateral for not responding in time
slash_node_on_dispute: Slashes a node's entire collateral for providing incorrect results

The slashing mechanism helps maintain the integrity and reliability of the Atoma network by providing economic incentives for good behavior and penalties for poor performance or malicious actions.

Constants

The contract defines several important constants:

InitialCollateralRequiredForRegistration: The initial amount of collateral required for node registration. Collateral submitted by a node is subject to slashing, if the becomes unresponsive (Liveness failure) or the node provides tampered outputs (malicous behavior).
InitialSettlementTimeoutMs: The initial maximum time nodes have to settle a prompt.
InitialPermilleToSlashNodeOnTimeout: The initial percentage (in permille) of collateral slashed if a node doesn't respond within the timeout.
Various task roles, compute unit types, modality types, optimization types, security levels, and performance units are defined as constants.

Events

Atoma's protocol relies heavily on events emitted on the Sui blockchain to orchestrate off-chain actions to be performed by users, nodes and verifiers. Here's a comprehensive list of the available events and their roles:

PublishedEvent: Emitted once upon publishing the contract. Contains:

db: The object ID of the Atoma DB (manages Atoma's global state)
manager_badge: The manager object ID (contract's published object ID)

NodeRegisteredEvent: Emitted when a new node is registered in the Atoma network. Contains:

badge_id: The ID of the NodeBadge object assigned to the newly registered node
node_small_id: A unique NodeSmallId assigned to the node for efficient referencing

NodeSubscribedToModelEvent: Emitted when a node subscribes to serve a specific AI model. Contains:

node_small_id: NodeSmallId of the subscribing node
model_name: Name of the AI model the node subscribed to
echelon_id: ID of the echelon for this model subscription

NodeSubscribedToTaskEvent: Emitted when a node subscribes to a task. Contains:

task_small_id: TaskSmallId of the task
node_small_id: NodeSmallId of the subscribing node
price_per_compute_unit: Price per compute unit set by the node for this task
max_num_compute_units: The maximum number of compute units a node is willing to sell to buyers (holders of Stacks).

NodeUpdateSubscriptionEvent: Emitted when a node updates its subscription to a task. Contains:

task_small_id: TasksmallId of the task
node_small_id: NodeSmallId of the subscribing node
price_per_compute_unit: The updated price per compute unit set by the node for this task
max_num_compute_units: The new maximum number of compute units a node is willing to sell to buyers (holders of Stacks).

NodeUnsubscribedFromTaskEvent: Emitted when a node removes its subscription from a task:

task_small_id: TaskSmallId of the task.
node_small_id: NodeSmallId of the the subscribed node.

TaskRegisteredEvent: Emitted when a new task is registered in the system. Contains:

task_id: The object ID of the newly registered Task
task_small_id: SmallId of the newly registered task

TaskDeprecationEvent: Emitted when a task is deprecated. Contains:

task_id: The object ID of the deprecated Task
task_small_id: SmallId of the deprecated task
epoch: The epoch in which the task was deprecated

TaskRemoveEvent: Emitted when a task is removed from the task table. Contains:

task_id: The object ID of the removed Task
task_small_id: SmallId of the removed task
removed_at_epoch: The epoch in which the task was removed

StackCreatedEvent: Emitted when a new stack is created in the system. Contains:

stack_id: The object ID of the newly created Stack
small_id: Unique identifier for the stack within the Atoma network
selected_node: The SmallId of the node selected to process this stack's requests
num_compute_units: The number of compute units allocated to this stack
price: The price per compute unit in TOMA tokens

StackTrySettleEvent: Emitted when a node attempts to settle a stack. Contains:

stack_small_id: The SmallId of the stack being settled
selected_node_id: The SmallId of the node selected to process the requests in the stack
requested_attestation_nodes: Vector of SmallIds of nodes selected for attestation (if any)
committed_stack_proof: The Merkle root of the stack's execution proof
stack_merkle_leaf: The root of the Merkle tree for the first execution
num_claimed_compute_units: Number of compute units claimed by the user

StackSettlementTicketEvent: Emitted when a stack settlement ticket is successfully created and verified. Contains:

stack_small_id: StackmallId of the settled stack
selected_node_id: NodeSmallId of the node that processed the stack
num_claimed_compute_units: Number of claimed computed units
requested_attestation_nodes: Vector of NodeSmallIds of nodes selected for attestation (if any)
dispute_settled_at_epoch: The epoch at which the stack attestation is completely settled
committed_stack_proof: The committed stack proof

StackSettlementTicketClaimedEvent: Emitted when a stack settlement ticket is claimed and funds are distributed. Contains:

stack_small_id: The StackSmallId of the settled stack
selected_node_id: The NodeSmallId of the node that processed the stack
attestation_nodes: Vector of NodeSmallIds of nodes that attested to the settlement
num_claimed_compute_units: Number of compute units actually used and claimed
user_refund_amount: Amount of funds refunded to the user for unused compute units

StackAttestationDisputeEvent: Emitted when there's a dispute in the attestation of a stack settlement. Contains:

stack_small_id: StackSmallId of the disputed stack
attestation_commitment: The disputed attestation commitment
attestation_node_id: The NodeSmallId of the attesting node
original_node_id: The NodeSmallId of the original processing node
original_commitment: The original commitment

These events provide a comprehensive tracking system for major actions and state changes within the Atoma network, enabling efficient off-chain processing and synchronization.

Error Codes

Error codes are defined with a base of 312012_000 for easy identification in logs. Some key error codes include:

ENodeRegDisabled: Node registration is disabled.
EModelDisabled: The requested model is disabled.
ENodeAlreadySubscribedToTask: The node is already subscribed to the task.
ETaskNotFound: The specified task does not exist.
Other error codes can be found in the contract logic.

Structs

Core Structs

AtomaManagerBadge: Represents authority over the package. It corresponds to the object id of the wallet that first published the contract.
NodeBadge: Proof of registration for a node.
NodeSmallId: A u64 ID assigned to a node for efficient referencing.
TaskSmallId: A u64 ID assigned to a task for efficient referencing.
StackSmallId: A u64 ID assigned to a stack for efficient referencing.
Task: Represents a computational task on the Atoma network.
TaskRole, Modality, ComputeUnit, Optimization, SecurityLevel, PerformanceUnit: Various structs to define task properties.
ReputationScore: Represents the reputation score of a node. Upon registration, a node has a reputation score of 100, at each epoch the reputation score can either increase (up to a maximum of 1000) or decrease up to a minimum of `0`.

Key Functions

The contract includes functions for:

Registering nodes
Create, deprecate and remove tasks.
Adding nodes to models (Deprecated)
Subscribing nodes to tasks
Managing task lifecycles
Handling node reputation and slashing

These functions are crucial for maintaining the Atoma network's integrity and managing computational resources effectively.

Admin functions

Currently, some functionality is dedicated to the administrator of the Atoma smart contract. This is intended to change in the near future, once we introduce robust community governance mechanisms, in the protocol.

Admin functions in Atoma provide privileged operations for managing the network. These functions require the AtomaManagerBadge for authorization.

Key admin functions:

Model Management:
- add_model: Adds a new model to the system
- remove_model: Removes an existing model
- disable_model / enable_model: Toggles model availability
Echelon Management:
- add_model_echelon: Adds a new echelon to a model
- remove_model_echelon: Removes an echelon from a model
- update_model_echelon: Updates echelon parameters
Oracle Management:
- add_model_echelon_oracle_node: Adds an oracle node to a model echelon
- remove_model_echelon_oracle_node: Removes an oracle node
Network Parameter Updates:
- set_required_registration_toma_collateral: Changes the required collateral for node registration
- set_permille_to_slash_node_on_timeout: Updates the global settlement timeout
- `set_permille_to_slash_node_on_timeout: Modifies the slashing percentage for timeouts
- set_cross_validation_probability_permille: Adjusts the probability of cross-validation
- set_cross_validation_probability_permille: Changes the number of extra nodes for cross-validation
- Node Management:
  - permanently_disable_node: Disables a node, preventing it from participating in the network
  These admin functions allow for flexible management and adjustment of the Atoma network, ensuring it can adapt to changing requirements and maintain optimal performance.

Sampling Mechanism

The sampling mechanism in Atoma is responsible for selecting appropriate nodes to execute tasks. It's a crucial component that ensures fair task distribution and system security.

Key aspects of the sampling mechanism:

Node Pool Management:

Maintains a pool of nodes in a TableVec data structure
Automatically removes slashed or disabled nodes during sampling
Validates node eligibility based on collateral and active status

Random Selection:

Uses Sui's random number generator for unbiased node selection
Implements uniform random selection within node pools
No weighting system - all eligible nodes have equal chance of selection

Cross-validation Sampling:

Controlled by cross_validation_probability_permille (default: 1‰)
When triggered, samples cross_validation_extra_nodes_count (default: 1) additional nodes
Additional charge of cross_validation_extra_nodes_charge_permille (default: 1.2‰) per extra node

Performance Optimization:

Uses TableVec for O(1) access and efficient removal operations
Implements swap-remove pattern to maintain vector density
Includes early exit conditions when no eligible nodes are available

Key functions involved in sampling:

sample_node: Samples a single random node from a pool, removing any slashed/disabled nodes encountered
sample_unique_nodes: Samples multiple unique nodes using chunk-based sampling to ensure fair distribution
get_node_id_if_unslashed_or_swap_remove: Helper function to validate node eligibility and maintain pool cleanliness

Error Handling:

Returns None when no eligible nodes are available
Includes maximum iteration safeguards to prevent infinite loops
Handles pathological cases where many nodes are slashed

The sampling mechanism ensures:

Fair and random distribution of tasks
Automatic cleanup of invalid nodes
Support for cross-validation sampling
Efficient operation even with large node pools

Key aspects of the sampling mechanism:

Node Pool Creation:
- Filters nodes based on task requirements (model, echelon, optimizations)
- Considers node reputation scores and subscription status
Stack node sampling:
- sample_node_for_stack is the primary method for selecting nodes for new stacks
- Eligibility criteria for nodes:
  - Must be subscribed to the task
  - Price per compute unit must be below specified price cap
  - Maximum compute units must meet required amount
  - Must have positive collateral balance
  - Must not be disabled
- Aborts if:
  - No nodes are subscribed to the task (ENoNodesSubscribedToTask)
  - No nodes meet eligibility criteria (ENoNodesEligibleForTask)
- Returns a randomly selected eligible node from the filtered pool
Random Selection:
- Uses Sui's random number generator for unbiased node selection
- Implements uniform random selection within node pools
- No weighting system - all eligible nodes have equal chance of selection
Cross-validation Sampling:
- Controlled by cross_validation_probability_permille (default: 10‰)
- When triggered, samples cross_validation_extra_nodes_count (default: 1) additional nodes
- Additional charge of cross_validation_extra_nodes_charge_permille (default: 12‰) per extra node
The sampling mechanism ensures:
- Fair and random distribution of tasks
- Economic viability through price cap enforcement
- Automatic cleanup of invalid nodes
- Support for cross-validation sampling
- Efficient operation even with large node pools
Performance Optimizations:
- Uses TableVec for O(1) access and efficient removal operations
- Implements swap-remove pattern to maintain vector density
- Includes early exit conditions when no eligible nodes are available

PreviousAtoma architecture overview NextAtoma architecture

Last updated 1 month ago