Describes the main steps how to interact with the Atoma Smart Contract

In order to interact with the Atoma contract, we provide a set of tools which include a custom cli module for Atoma, that allows anyone to submit transactions into Atoma. Furthermore, node operators can leverage a custom daemon that automatizes many of the processes related to operating a node (we will provide a more extensive description of the daemon functionalities in a later section).

​
Install Sui cli

​
1. Install the Sui Client Locally:

The first step in setting up an Atoma node is installing the Sui client locally. Please refer to the Sui installation guide for more information.

After installing the Sui client, connect to a Sui RPC node to be able to interact with the Sui blockchain and therefore the Atoma smart contract. Please refer to the Connect to a Sui Network guide for more information.

Next, create a wallet and fund it with some testnet SUI. Please refer to the Sui wallet guide for more information. If you plan to run the Atoma node on Sui’s testnet, you can request testnet SUI tokens by following the docs.

After completing the steps above, you should have the following files created locally:

  • ~/.sui/sui_config/client.yaml - the Sui client configuration file.

  • ~/.sui/sui_config/sui.keystore - The Sui keystore file (contains your private key(s)).

Request Sui testnet funds by running the command:

sui client faucet

You can query your wallet balance through

sui client balance

​
Atoma Testnet Parameters

  1. Atoma’s package id (on Sui’s testnet): 0xfa971724b5fb14c2ffc9a959b81cce4d85d457da27e29f793e12428ed71bb922

  2. Atoma’s DB object id: 0xe0b1d6458f349d4bc71ef119694866f1d6ee6915b43f8cc05a5d44a49e3e1f0f

  3. USDC faucet token package id (testnet):

    0xa1ec7fc00a6f40db9693ad1415d0c193ad3906494428cf252621037bd7117e29

​
Set up Atoma’s Custom cli

To interact with the Atoma contract through our custom cli, follow these steps:

  1. Clone the Atoma contract repository:
git clone https://github.com/atoma-network/atoma-contracts
cd atoma-contracts/sui/

The current Atoma contract relies on USDC for payments. In order to start interacting with the Atoma contract, you need to request USDC tokens to your (local) active Sui wallet. In order to do so, you can request Sui testnet USDC tokens to your (local) active Sui wallet, via the url:

https://faucet.circle.com/

Once you have requested the tokens, you should be able to query the value amount of USDC tokens you currently hold on your wallet:

sui client balance

Notice that the USDC uses 6 decimal places, which means that to 1 USDCis represented logically on the Sui blockchain through an amount of 1000000.

​
Tasks on Atoma

Tasks on Atoma specify compute jobs on the network. Each Task is assigned a role. Roles can be one of the following values:

  • Chat completions - 0

  • Embeddings - 1

  • Vision - 2

  • Image generation - 3

  • Text to speech - 4

  • Speech to Text - 5

  • Fine tuning - 6

  • Training - 7

To spawn a new Task on Atoma, specify a model (following HuggingFace name convention), for example:

model-name: meta-llama/Llama-3.3-70B-Instruct

You can specify an optional Security level for the Task:

  • No security - 0 (meaning no additional security requirements like verifiability or privacy are required)

  • Confidential compute - 1 (meaning that the each workload on Atoma for this task is performed within proper TEEs, for both verifiable and private AI)

  • Sampling Consensus - 2 (meaning that each workload on Atoma for this task requires Sampling Consensus to be executed, allowing for verifiable AI through crypto-economics guarantees).

The Task creator can also specify a minimum node reputation score (minimum 0 and maximum 100).

In the current testnet version, Tasks can only be spawned by the administrator of the Atoma contract. In the future, tasks will be part of Atoma’s governance protocol. Moreover, tasks can either be public or private. Public tasks can be subscribed by any node on the network (more below), whereas private tasks can only be subscribed by nodes that have been granted access by the administrator, that is, that have been whitelisted by the administrator.

In order to submit to create a Task, using Atoma’s cli, one simply needs to run:

./dev/cli db create-task-entry \
  --package "0xfa971724b5fb14c2ffc9a959b81cce4d85d457da27e29f793e12428ed71bb922" \
  --role 0 \ # chat completions
  --model-name "meta-llama/Llama-3.3-70B-Instruct" \ # (optional)
  --security-level 1 \ # (optional) Confidential compute integrity
  --minimum-reputation-score 50 # (optional) Only nodes with 50 reputation score can participate in task related workloads
  --is-public true # (optional) Whether the task is public or not

When a transaction for creating a new Task is submitted, the involved wallet receives a new Sui Move object, of the form:

public struct TaskBadge has key, store {
  id: UID,
  small_id: TaskSmallId,
}

The TaskSmallId is a wrapper around a u64 number

public struct TaskSmallId has store, copy, drop {
  inner: u64,
}

This number is important to refer to the task in future transactions such as subscribing nodes to tasks, deprecated or remove tasks, buy Stacks on behalf of a user, etc.

​
Deprecating Tasks

It is possible to deprecate tasks that are active, and were created by the current wallet by running:

./dev/cli db deprecate-task \
  --package "0xfa971724b5fb14c2ffc9a959b81cce4d85d457da27e29f793e12428ed71bb922" \

The TASK_BADGE_ID value is the id within TaskBadge that can be accessed by querying the wallet owned objects.

​
Removing Tasks

To remove a task that was already deprecated, one can run the command:

./dev/cli db remove-deprecated-task \
  --package "0xfa971724b5fb14c2ffc9a959b81cce4d85d457da27e29f793e12428ed71bb922" \

​
Register a Node

The easiest way to register a node on the Atoma contract is through the Atoma node daemon. However, it is also possible to register a node manually through the Atoma cli. In order to register a node on Atoma,

./dev/cli db register-node \
  --package "0xfa971724b5fb14c2ffc9a959b81cce4d85d457da27e29f793e12428ed71bb922"

Once the node is registered, the node will receive a NodeBadge object of the form:

public struct NodeBadge has key, store {
  id: UID,
  small_id: NodeSmallId,
}

the NodeSmallId is a wrapper around a u64 number

public struct NodeSmallId has store, copy, drop {
  inner: u64,
}

which is a unique identifier that allows the Atoma contract to select different nodes for different tasks workloads.

​
Subscribe a Node to a Task

In order for Atoma nodes to participate in the protocol, these must subscribe to specific tasks:

./dev/cli db subscribe-node-to-task \
  --package "0xfa971724b5fb14c2ffc9a959b81cce4d85d457da27e29f793e12428ed71bb922" \
  --task-small-id 1 \ # The Task small id, referring to a specific task on Atoma
  --price-per-one-million-compute-units 1000000 \ # the price to which the node is willing to be paid for 1 million compute units

The price-per-one-million-compute-units is the price to which the node is willing to be paid for 1 million compute units. More concretely, in the example above, if task-small-id 1 is a Chat completions task, say for meta-llama/Llama-3.3-70B-Instruct, then the subscribed node is charging a price of 1 USDC for 1 million (LLM) tokens for the model meta-llama/Llama-3.3-70B-Instruct.

​
Unsubscribe a Node from a Task

Nodes on Atoma can unsubscribe from Tasks that these have subscribed to (even though nodes must claim each active Stacks):

./dev/cli db unsubscribe-node-from-task \ 
  --package "0xfa971724b5fb14c2ffc9a959b81cce4d85d457da27e29f793e12428ed71bb922" \
  --task-small-id 1 # the Task small id, referring to a specific task that the node did subscribe to

​
Buy Stacks

Users on Atoma can access nodes, by first buying Stacks associated to a specific Task. In order to buy a Stack, one just needs to run the command:

./dev/cli db acquire-new-stack-entry \
  --package "0xfa971724b5fb14c2ffc9a959b81cce4d85d457da27e29f793e12428ed71bb922" \
  --task-small-id 1 \ # the Task small id to which the current Stack refers to 
  --num-compute-units 1000000 # How many compute units are being bought, compute units correspond to either LLM tokens, pixels, or other metrics of compute
  --price 1000000 # The price per compute unit to which the user is willing to pay for

The price is the price per one million compute units to which the user is willing to pay for. In the example above, assuming that task-small-id 1 refers to a Chat completions task, under the meta-llama/Llama-3.3-70B-Instruct model, then the user is willing to pay 1 USDC for 1 million compute units (that is, 1 million LLM tokens, roughly words). Once the Stack is acquired by the wallet, the wallet will hold a StackBadge object of the form:

public struct StackBadge has key, store {
  id: UID,
  small_id: StackSmallId,
}

This object grants permissions to the wallet to manage the Stack. The StackSmallId is a wrapper around a u64, which can be used to refer to the Stack later, as we shall see.

​
Settling Stacks

Once nodes have processed a large number of compute units for a given Stack, the nodes can try to settle the Stack and claim the funds for having provided the compute to the holder of the Stack.

The first step to settle a Stack is by trying to settle the stack:

./dev/cli db try-settle-stack \
  --package "0xfa971724b5fb14c2ffc9a959b81cce4d85d457da27e29f793e12428ed71bb922" \
  --stack-small-id 1 \ # The Stack small id to which this transaction refers to 
  --num-claimed-compute-units 1000000 \ # This value should be inferior to the number of compute units bought in the Stack, the higher the better though
  --committed-stack-proof MERKLE_TREE_ROOT_BYTE_LEN32_ARRAY \ # Byte array of length 32 containing a proof commitment to the whole Stack history of requests and responses
  --stack-merkle-leaf MERKLE_TREE_LEAF_BYTE_LEN32_ARRAY \ # Byte array of length 32 containing a Merkle tree leaf for opening on the committed stack proof above

The values of committed-stack-proof and stack-merkle-leaf can be computed as the Merkle tree root and leaf index corresponding to the whole Stack history. In practice, node operators do not need to compute these values themselves, as this is completed addressed within the Atoma node daemon logic.

Once the transaction goes through, a dispute challenge window for the Stack execution starts, which lasts for two epochs. Within those epochs anyone can dispute the Stack settlement, including user holding the original Stack. Additionally, the Atoma contract can select one or more nodes to attest to the right execution from the original selected node for the Stack This is relevant, and only required, for our Sampling Consensus protocol. If no security or confidential compute security are associated to the Stack, then the contract skips this step.

If a node is selected to attest a Stack execution, it needs to fetch the Stack’s input data, and redo the whole history of execution (that is, running AI inference on the whole stack requests). Once that is done, the node can attest the execution by submitting an on-chain transaction as:

./dev/cli db submit-stack-settlement-attestation \
  --package "0xfa971724b5fb14c2ffc9a959b81cce4d85d457da27e29f793e12428ed71bb922" \
  --stack-small-id 1 \ # The Stack small id to which this transaction refers to 
  --committed-stack-proof MERKLE_TREE_ROOT_BYTE_LEN32_ARRAY \ # Byte array of length 32 containing a proof commitment to the whole Stack history of requests and responses
  --stack-merkle-leaf MERKLE_TREE_LEAF_BYTE_LEN32_ARRAY \ # Byte array of length 32 containing a Merkle tree leaf for opening on the committed stack proof above

On the other hand, any participant on the network can start a dispute mechanism as:

./dev/cli db start-attestation-dispute \
  --package "0xfa971724b5fb14c2ffc9a959b81cce4d85d457da27e29f793e12428ed71bb922" \
  --stack-small-id 1 \ # The Stack small id to which this transaction refers to 
  --attestation-commitment MERKLE_TREE_ROOT_BYTE_LEN32_ARRAY \ # Byte array of length 32 containing a proof commitment to the whole Stack history of requests and responses

In this case, a dispute resolution mechanism is put forth by the contract to resolve the dispute. The dishonest part involved in the dispute resolution mechanism will be at risk of slashed collateral.

​
Claim Funds

Once the dispute challenge period has finished for a Stack, the node can finally claim its funds by running the command:

./dev/cli db claim-funds \
  --package "0xfa971724b5fb14c2ffc9a959b81cce4d85d457da27e29f793e12428ed71bb922" \
  --settled-ticket-ids 1,2,3,4 \ # The Stack small id to which this transaction refers to
Tasks