# 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](https://docs.sui.io/build/install) 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](https://docs.sui.io/guides/developer/getting-started/connect) for more information.

You then need to create a wallet and fund it with some testnet SUI. Please refer to the [Sui wallet guide](https://docs.sui.io/guides/developer/getting-started/get-address) 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](https://docs.sui.io/guides/developer/getting-started/get-coins).

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:

```bash
sui client faucet
```

You can then query your wallet balance through

```bash
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:**

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

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

```bash
./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:

```bash
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&#x20;
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).&#x20;

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:

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

The `TaskSmallId` is a wrapper around a `u64` number

```rust
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:\\

```bash
./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:

```bash
./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:

```bash
./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):

```bash
./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&#x20;

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:

```bash
./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:\\

```rust
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:

```bash
./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:

```bash
./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:

```bash
./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:

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