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
Atoma's package id (on Sui's testnet):
0xc05bae323433740c969d8cf938c48d7559490be5f8dde158792e7a0623787013
Atoma's DB object id:
0x7b8f40e38698deb650519a51f9c1a725bf8cfdc074d1552a4dc85976c2b414be
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:
Clone the Atoma contract repository:
git clone https://github.com/atoma-network/atoma-contracts
cd atoma-contracts/sui/
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:
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, 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
:
No security - 0 (meaning no additional security requirements like verifiability or privacy are required)
Sampling Consensus - 1 (meaning that the each workload on Atoma for this task is under the
Sampling Consensus
protocol, for verifiable AI)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 Stack
s 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
Last updated