Interact with the Atoma smart contract

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

The first step is to install locally the Sui client software. This can be done as follows:

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.

Once you have the Sui client installed, locally, you need to 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.

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

Once you finish 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)).

You can request Sui testnet funds by running the command:

sui client faucet

You can then query your wallet balance through

sui client balance

Atoma testnet parameters

  1. Atoma's package id (on Sui's testnet): 0xc05bae323433740c969d8cf938c48d7559490be5f8dde158792e7a0623787013

  2. Atoma's DB object id: 0x7b8f40e38698deb650519a51f9c1a725bf8cfdc074d1552a4dc85976c2b414be

  3. Atoma's TOMA faucet token package id (testnet):

    0xa1b2ce1a52abc52c5d21be9da0f752dbd587018bc666c5298f778f42de26df1d

Set up Atoma's custom cli

In order to interact with the Atoma contract, through our custom cli, one must follow the steps:

  1. Clone the Atoma contract repository:

git clone https://github.com/atoma-network/atoma-contracts
cd atoma-contracts/sui/

  1. Request faucet TOMA tokens to your (local) active Sui wallet (it mints 100 tokens, as the token is programmed to have 9 decimal places):

./dev/cli toma faucet \
  --toma-package "0xa1b2ce1a52abc52c5d21be9da0f752dbd587018bc666c5298f778f42de26df1d"\
  --amount 100000000000 # feel free to adjust the amount, it has 9 decimal places

Once the transaction is submitted, you should be able to query the value amount of faucet TOMA tokens you currently hold on your wallet:

sui client balance

Create a Task on Atoma

In order to create a Task on Atoma, it is important to understand how these are used to specify compute jobs on the network. Each Task is assigned a role. Roles can be one of those values:

  1. Chat completions - 0

  2. Embeddings - 1

  3. Vision - 2

  4. Image generation - 3

  5. Text to speech - 4

  6. Speech to Text - 5

  7. Fine tuning - 6

  8. Training - 7

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

model-name: meta-llama/Llama-3.1-8B-Instruct

It is also possible to specify an optional Security level for the Task:

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

  2. Sampling Consensus - 1 (meaning that the each workload on Atoma for this task is under the Sampling Consensus protocol, for verifiable AI)

  3. Confidential compute - 2 (meaning that each workload on Atoma for this task requires trusted hardware to be executed, allowing for both verifiability and privacy).

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

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

./dev/cli db create-task-entry \
  --package "0xc05bae323433740c969d8cf938c48d7559490be5f8dde158792e7a0623787013" \
  --role 0 \ # chat completions
  --model-name "meta-llama/Llama-3.1-8B-Instruct" \ # (optional)
  --security-level 1 \ # (optional) Sampling Consensus verifiability
  --minimum-reputation-score 50 # (optional) Only nodes with 50 reputation score can participate in task related workloads

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 "0xc05bae323433740c969d8cf938c48d7559490be5f8dde158792e7a0623787013" \
  --task-badge TASK_BADGE_ID

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 "0xc05bae323433740c969d8cf938c48d7559490be5f8dde158792e7a0623787013" \
  --task-badge TASK_BADGE_ID

Register a node

In order to register a node on Atoma, one must run:

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

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 "0xc05bae323433740c969d8cf938c48d7559490be5f8dde158792e7a0623787013" \
  --task-small-id 1 \ # The Task small id, referring to a specific task on Atoma
  --price-per-compute-unit 100 \ # the price to which the node is willing to be paid for its compute
  --max-num-compute-units 10000000 # the maximum number of compute units that a node is willing to sell per Stack, the higher the better

Unsubscribe 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 "0xc05bae323433740c969d8cf938c48d7559490be5f8dde158792e7a0623787013" \
  --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 "0xc05bae323433740c969d8cf938c48d7559490be5f8dde158792e7a0623787013" \
  --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 100 # The price per compute unit to which the user is willing to pay for

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 "0xc05bae323433740c969d8cf938c48d7559490be5f8dde158792e7a0623787013" \
  --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 for our Sampling Consensus protocol. If no security or confidential compute security are required, 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 "0xc05bae323433740c969d8cf938c48d7559490be5f8dde158792e7a0623787013" \
  --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 "0xc05bae323433740c969d8cf938c48d7559490be5f8dde158792e7a0623787013" \
  --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 "0xc05bae323433740c969d8cf938c48d7559490be5f8dde158792e7a0623787013" \
  --settled-ticket-ids 1,2,3,4 \ # The Stack small id to which this transaction refers to

PreviousAtoma architectureNextCurrent available tasks on Atoma

Last updated