### Basic Genesis Node Setup

Source: https://github.com/gonka-ai/gonka/blob/main/local-test-net/README.md

Starts a basic genesis node using the core services and genesis configuration.

```bash
docker-compose -f docker-compose-base.yml -f docker-compose.genesis.yml up
```

--------------------------------

### Install Dependencies and Create Environment File

Source: https://github.com/gonka-ai/gonka/blob/main/proposals/ethereum-bridge-contact/SETUP.md

Installs project dependencies using npm and copies the example environment file to .env. Ensure Node.js v16+ and npm/yarn are installed.

```bash
npm install

cp .env.example .env
```

--------------------------------

### Setup Development Environment

Source: https://github.com/gonka-ai/gonka/blob/main/mlnode/README.md

Sets up a development virtual environment with all dependencies installed. Activate it using 'source .venv/bin/activate'.

```bash
make setup-dev-env
```

--------------------------------

### MLNodeBackgroundManager Initialization

Source: https://github.com/gonka-ai/gonka/blob/main/proposals/mlnode-autodownload/README.md

Example of initializing the MLNodeBackgroundManager with necessary dependencies, including the broker, and starting its background process.

```go
mlnodeBackgroundManager := modelmanager.NewMLNodeBackgroundManager(
    config,
    chainPhaseTracker,
    nodeBroker,  // Added broker
    &mlnodeclient.HttpClientFactory{},
    30*time.Minute,
)
go mlnodeBackgroundManager.Start(ctx)
```

--------------------------------

### Initial Server Setup via SSH

Source: https://github.com/gonka-ai/gonka/blob/main/mlnode/packages/benchmarks/scripts/README.md

Sets up a remote server by disabling auto-tmux, linking CUDA libraries, and starting the MLNode API with Uvicorn. Ensure the LD_LIBRARY_PATH is set before starting the server to avoid CUDA errors.

```bash
ssh -i <key> -p <ssh_port> root@<host>
touch ~/.no_auto_tmux
ln -sf /lib/x86_64-linux-gnu/libcuda.so.1 /lib/x86_64-linux-gnu/libcuda.so
export LD_LIBRARY_PATH=/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH
. /app/packages/api/.venv/bin/activate && \
  cd /app/packages && \
  python -m uvicorn api.app:app --host 0.0.0.0 --port 8080
```

--------------------------------

### Install and Initialize LXD

Source: https://github.com/gonka-ai/gonka/blob/main/testermint/parallel-local.md

Set up LXD on your system. This includes installation, automatic initialization, and adding the current user to the lxd group.

```bash
sudo snap install lxd
sudo lxd init --auto
sudo usermod -aG lxd $USER
newgrp lxd
```

--------------------------------

### w8a16 Quantization on Same Machine (L40S)

Source: https://github.com/gonka-ai/gonka/blob/main/mlnode/docs/inference-validation.md

This example shows the setup for validating w8a16 quantization on the same NVIDIA L40S GPU for both generation and validation. Consistent results are expected.

```bash
Generate: NVIDIA L40S: RedHatAI/Qwen2.5-7B-quantized.w8a16
Validate: NVIDIA L40S: RedHatAI/Qwen2.5-7B-quantized.w8a16
```

--------------------------------

### Install and Verify inferenced CLI

Source: https://github.com/gonka-ai/gonka/blob/main/docs/consumer_setup.md

Download the inferenced binary, make it executable, move it to a system-wide location, and verify the installation.

```bash
chmod +x inferenced
sudo mv inferenced /usr/local/bin/
inferenced version
```

--------------------------------

### Install kubectl using Homebrew

Source: https://github.com/gonka-ai/gonka/blob/main/test-net-cloud/TESTING.md

Installs the kubectl command-line tool. Verify the installation by checking the client version.

```bash
brew install kubectl
# Verify installation
kubectl version --client
```

--------------------------------

### Quick Start: Run devshardctl and Make a Request

Source: https://github.com/gonka-ai/gonka/blob/main/devshard/docs/proxy.md

Start the devshardctl proxy with essential configuration and then send a chat completion request to it.

```bash
devshardctl \
  --private-key "deadbeef..." \
  --escrow-id 42 \
  --chain-rest "http://localhost:1317"

# In another terminal:
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"Qwen/Qwen3-235B-A22B-Instruct-2507-FP8","messages":[{"role":"user","content":"Hello"}],"max_tokens":100}'
```

```bash
export DEVSHARD_PRIVATE_KEY="deadbeef..."
export DEVSHARD_ESCROW_ID="42"
export DEVSHARD_CHAIN_REST="http://localhost:1317"

devshardctl
```

--------------------------------

### Check Account Balances Example

Source: https://github.com/gonka-ai/gonka/blob/main/docs/specs/genesistransfer/genesistransfer-cli-guide.md

Example for checking account balances using the bank module query command.

```bash
inferenced query bank balances gonka1genesis...
inferenced query bank balances gonka1recipient...
```

--------------------------------

### w8a8 Quantization on Same Machine (L40S)

Source: https://github.com/gonka-ai/gonka/blob/main/mlnode/docs/inference-validation.md

This example shows the setup for validating w8a8 quantization on the same NVIDIA L40S GPU for both generation and validation. Potential issues with repetition are noted.

```bash
Generate: NVIDIA L40S: RedHatAI/Qwen2.5-7B-quantized.w8a8
Validate: NVIDIA L40S: RedHatAI/Qwen2.5-7B-quantized.w8a8
```

--------------------------------

### Environment Variables for Setup

Source: https://github.com/gonka-ai/gonka/blob/main/local-test-net/README.md

Specifies required environment variables for the local test network setup.

```bash
# Required
KEY_NAME=your-key-name
NODE_CONFIG=node-config.json
```

--------------------------------

### FP8 Quantization on the Same Machine

Source: https://github.com/gonka-ai/gonka/blob/main/mlnode/docs/inference-validation.md

This example demonstrates using FP8 quantization on the same NVIDIA RTX 3090 GPU for both generation and validation. This setup is expected to yield consistent results.

```bash
Generate: NVIDIA RTX 3090: --quantization fp8
Validate: NVIDIA RTX 3090: --quantization fp8
```

--------------------------------

### Mock Server v2 PoC Response Setup

Source: https://github.com/gonka-ai/gonka/blob/main/proposals/poc/dev/switch-impl.md

Sets up mock responses for v2 PoC generation and validation scenarios in the mock server. Logs the setup details.

```kotlin
override fun setPocV2Response(weight: Long, hostName: String?, scenarioName: String) {
    // Log for v2 PoC generation mock setup
}

override fun setPocV2ValidationResponse(weight: Long, scenarioName: String) {
    // Log for v2 PoC validation mock setup
}
```

--------------------------------

### MLNodeBackgroundManager Start Method with GPU Update Call

Source: https://github.com/gonka-ai/gonka/blob/main/proposals/mlnode-autodownload/README.md

Updated Start method to include a call to checkAndUpdateGPUs alongside the existing checkAndDownloadModels.

```go
func (m *MLNodeBackgroundManager) Start(ctx context.Context) {
    ticker := time.NewTicker(m.checkInterval)
    defer ticker.Stop()

    for {
        select {
        case <-ticker.C:
            m.checkAndDownloadModels(ctx)  // Existing
            m.checkAndUpdateGPUs(ctx)       // New
        case <-ctx.Done():
            return
        }
    }
}
```

--------------------------------

### Complete Transfer Workflow Example

Source: https://github.com/gonka-ai/gonka/blob/main/docs/specs/genesistransfer/genesistransfer-cli-guide.md

Example demonstrating a complete transfer workflow, including checking eligibility, performing the ownership transfer, and then checking the status.

```bash
inferenced query genesistransfer transfer-eligibility gonka1genesis...
inferenced tx genesistransfer transfer-ownership gonka1genesis... gonka1recipient... \
  --from genesis-key --gas 2000000 --yes
inferenced query genesistransfer transfer-status gonka1genesis...
```

--------------------------------

### Starting the MLNode API Server

Source: https://github.com/gonka-ai/gonka/blob/main/mlnode/packages/benchmarks/scripts/README.md

Activate the virtual environment and start the MLNode API server using uvicorn. This command should be run on the target machine where the API will be hosted.

```bash
. /app/packages/api/.venv/bin/activate
cd /app/packages
python -m uvicorn api.app:app --host 0.0.0.0 --port 8080
```

--------------------------------

### Initial Inference Request Example

Source: https://github.com/gonka-ai/gonka/blob/main/proposals/inference/README.md

This example shows the first request in a sequence, sent to host h1, with initial diffs and state hash.

```json
{
  "...": "...",
  "diffs": [
    {"nonce": 1, "txs": ["MsgStartInference(1)"], "state_sigs": []}
  ],
  "state_hash": "<SHA256>"
}
```

--------------------------------

### Minimum Inference Charge Calibration Example

Source: https://github.com/gonka-ai/gonka/blob/main/proposals/transaction-fees/README.md

Provides an example of calibrating the minimum charge based on current pricing, showing the calculation for a specific token count and price.

```go
min_charge = (1000 + 500) × 100 = 150,000 ngonka ≈ 0.00015 GNK
```

--------------------------------

### MLNodeBackgroundManager Start Method

Source: https://github.com/gonka-ai/gonka/blob/main/proposals/mlnode-autodownload/README.md

The Start method of MLNodeBackgroundManager uses a ticker to periodically check and download models and update GPU information. It runs indefinitely until the context is done.

```go
func (m *MLNodeBackgroundManager) Start(ctx context.Context) {
    ticker := time.NewTicker(m.checkInterval) // 30 minutes
    for {
        select {
        case <-ticker.C:
            m.checkAndDownloadModels(ctx)  // Existing
            m.checkAndUpdateGPUs(ctx)       // New
        case <-ctx.Done():
            return
        }
    }
}
```

--------------------------------

### Start Development Environment with Docker Compose

Source: https://github.com/gonka-ai/gonka/blob/main/mlnode/packages/pow/README.md

Builds and starts the development environment using Docker Compose. Access Jupyter Lab at http://localhost:8080.

```bash
docker compose up --build
```

--------------------------------

### Setup and Imports for PoW Client

Source: https://github.com/gonka-ai/gonka/blob/main/mlnode/packages/pow/notebooks/rest-usage.ipynb

Imports necessary libraries and defines constants for PoW operations. Includes setup for unique identifiers and batch size.

```python
# Setup and Imports
import time
import datetime
import requests
import hashlib
from pow.app.client_v1 import ClientV1
from pow.compute.stats import estimate_R_from_experiment
from pow.compute.compute import ProofBatch
from pow.data import ValidatedBatch
from pow.models.utils import Params

# Generate unique identifiers for this session
date_str = datetime.datetime.now().strftime('%Y-%m-%d_%H-%M-%S')
BLOCK_HASH = hashlib.sha256(date_str.encode()).hexdigest()
PUBLIC_KEY = f"pub_key_1_{date_str}"
BATCH_SIZE = 5000
```

--------------------------------

### Execute Start PoC Node Command V1

Source: https://github.com/gonka-ai/gonka/blob/main/proposals/poc/dev/migration.md

Executes the V1 command to start a PoC node by checking the state, stopping if necessary, and then initiating generation via InitGenerateV1.

```go
package broker

type StartPoCNodeCommandV1 struct {
    BlockHeight int64
    BlockHash   string
    PubKey      string
    CallbackUrl string
    TotalNodes  int
    ModelParams *types.PoCModelParams
}

func (c StartPoCNodeCommandV1) Execute(ctx context.Context, worker *NodeWorker) NodeResult {
    // V1: Check state, Stop() if needed, then InitGenerateV1()
}
```

--------------------------------

### GET /v1/poc/artifacts/state Response Example

Source: https://github.com/gonka-ai/gonka/blob/main/proposals/poc/dev/offchain-phase2.md

Example JSON response for the GET /v1/poc/artifacts/state endpoint. It includes the PoC stage start block height, the total count of artifacts, and the root hash of the Merkle Mountain Range (MMR).

```json
{
  "poc_stage_start_block_height": 100,
  "count": 50000,
  "root_hash": "<base64>"
}
```

--------------------------------

### GET /v1/poc/artifacts/state Request Example

Source: https://github.com/gonka-ai/gonka/blob/main/proposals/poc/dev/offchain-phase2.md

Example of a GET request to query the artifact store state for a specific PoC stage. This is used by validators and tests to retrieve the current artifact count and root hash.

```http
GET /v1/poc/artifacts/state?height=100
```

--------------------------------

### In-Process Unit Test Setup

Source: https://github.com/gonka-ai/gonka/blob/main/proposals/inference/design.md

Demonstrates setting up a devshard session for in-process unit testing. This approach uses in-memory storage, a no-op gossip client, and a fake mainnet bridge for deterministic, network-free testing.

```go
bridge := &FakeBridge{escrows: map[string]EscrowInfo{...}}
store  := storage.NewMemory()
signer := signing.NewSecp256k1(privateKey)
gossip := &NoOpGossip{}

node := devshard.New(bridge, store, signer, gossip)
// now drive the full protocol with real data
```

--------------------------------

### Original Architecture Diagram

Source: https://github.com/gonka-ai/gonka/blob/main/mlnode/packages/api/src/api/inference/vllm/proxy.md

Illustrates the initial setup with separate ports for management and vLLM inference APIs.

```text
Port 8000: /api/* → Management APIs
Port 5000: /v1/* → vLLM Inference APIs (separate service)
```

--------------------------------

### Start Inference Node

Source: https://github.com/gonka-ai/gonka/blob/main/inference-chain/readme.md

Starts a full node for the Inference blockchain after initialization.

```shell
./build/inferenced start
```

--------------------------------

### Setup Environment Variables

Source: https://github.com/gonka-ai/gonka/blob/main/mlnode/README.md

Run this command to create template environment files for the project. You will need to fill these with actual values.

```bash
make setup-envs
```

--------------------------------

### Summary Table Example

Source: https://github.com/gonka-ai/gonka/blob/main/mlnode/packages/benchmarks/scripts/README.md

An example of a summary table used to present benchmark results.

```markdown
| Metric                  | Value         |
|-------------------------|---------------|
| PoC nonces/min          | 55,423        |
| Inference tokens/sec    | 2,686         |
| Validation mean dist    | 0.0073        |
| Validation max dist     | 0.0124        |
```

--------------------------------

### Initialize Node

Source: https://github.com/gonka-ai/gonka/blob/main/genesis/README.md

Run this command to initialize your node. This is a necessary step before proceeding with other server configurations.

```bash
docker compose run --rm node
```

--------------------------------

### Quick Start with Docker Compose

Source: https://github.com/gonka-ai/gonka/blob/main/proxy-ssl/README.md

Enables SSL profile and restarts proxy services using docker-compose. Ensure config.env is sourced.

```bash
source config.env && \
docker compose pull proxy proxy-ssl && \
docker compose --profile "ssl" \
  -f docker-compose.mlnode.yml \
  -f docker-compose.yml \
  up -d proxy proxy-ssl
```

--------------------------------

### Install stern for Log Browsing

Source: https://github.com/gonka-ai/gonka/blob/main/test-net-cloud/TESTING.md

Installs the stern tool, which is used for browsing logs from Kubernetes pods.

```bash
brew install stern
```

--------------------------------

### List Account Keys

Source: https://github.com/gonka-ai/gonka/blob/main/genesis/README.md

Use this command to view the information of your existing Account Cold Key, which was generated during the quickstart process.

```bash
./inferenced keys list --keyring-backend file
```

--------------------------------

### Initialize Local Environment

Source: https://github.com/gonka-ai/gonka/blob/main/inference-chain/readme.md

Sets up environment variables and basic configuration for a local single-node run.

```shell
./srcipts/init-local.sh
```

--------------------------------

### Example: Execute Emergency Transfer

Source: https://github.com/gonka-ai/gonka/blob/main/docs/specs/restrictions/restrictions-cli-guide.md

Provides a concrete example of executing an emergency transfer with specific parameters.

```bash
inferenced tx restrictions execute-emergency-transfer \
  emergency-001 gonka1from... gonka1to... 1000 ugonka \
  --from from-key --gas 300000 --yes
```

--------------------------------

### Example Genesis Time Log Message

Source: https://github.com/gonka-ai/gonka/blob/main/genesis/README.md

This is an example log message indicating the node is waiting for the genesis time.

```text
INF Genesis time is in the future. Sleeping until then... genTime=2025-08-14T09:13:39Z module=server
```

--------------------------------

### Dual-Write Mode Usage Example

Source: https://github.com/gonka-ai/gonka/blob/main/proposals/poc/dev/offchain-phase1.md

Demonstrates how to configure the ArtifactStore and integrate it with the MLNode server for dual-write functionality.

```go
// Usage
store, _ := pocartifacts.Open("/path/to/artifacts")
server := mlnode.NewServer(recorder, broker, mlnode.WithArtifactStore(store))
```

--------------------------------

### Example: Check Restriction Status and Output

Source: https://github.com/gonka-ai/gonka/blob/main/docs/specs/restrictions/restrictions-cli-guide.md

Demonstrates how to check if restrictions are active and provides an example of the expected JSON output.

```bash
# Check if restrictions are active
inferenced query restrictions transfer-restriction-status

# Example output:
# {
#   "is_active": true,
#   "restriction_end_block": "1555000",
#   "current_block_height": "125000",
#   "remaining_blocks": "1430000"
# }
```

--------------------------------

### Install Gonka OpenAI SDK

Source: https://github.com/gonka-ai/gonka/blob/main/docs/consumer_setup.md

Install the Gonka-specific OpenAI SDK using pip. This library is required for sending inference requests.

```bash
pip install gonka-openai
```

--------------------------------

### Docker Compose Example for Versiond

Source: https://github.com/gonka-ai/gonka/blob/main/proposals/versioned/README.md

Example Docker Compose configuration for deploying versiond. Includes setting the oracle URL and optional overrides for local testing or forcing specific versions.

```yaml
versiond:
  image: ghcr.io/gonka-ai/versiond:latest
  environment:
    VERSIOND_ORACLE_URL: http://api:9100/versions
    # Optional: override a version for local testing
    # VERSIOND_OVERRIDE_v0_2_11: /opt/local/devshard-dev
    # Optional: force versions not yet in governance
    # VERSIOND_FORCE: v0.2.13-rc1
  ports:
    - "8080:8080"
```

--------------------------------

### Import Libraries and Setup Environment

Source: https://github.com/gonka-ai/gonka/blob/main/mlnode/packages/pow/notebooks/reproduce_operations.ipynb

Imports necessary libraries and sets up environment variables and autoreload for the POW library. Ensure the 'src' directory is in the Python path.

```python
import os
os.environ["CUBLAS_WORKSPACE_CONFIG"] = ":4096:8"
%load_ext autoreload
%autoreload 2
import numpy as np
import hashlib
import time
import torch
from tqdm.notebook import tqdm
import sys
sys.path.append('../src')
from pow.compute.pipeline import Pipeline
from pow.compute.compute import AttentionModel, Compute
```

--------------------------------

### Install Stress Testing Tool

Source: https://github.com/gonka-ai/gonka/blob/main/CONTRIBUTING.md

Install the compressa-perf tool, a fork used for stress testing, via pip from its GitHub repository.

```bash
pip install git+https://github.com/product-science/compressa-perf.git
```

--------------------------------

### Python Environment Setup

Source: https://github.com/gonka-ai/gonka/blob/main/mlnode/packages/benchmarks/scripts/README.md

Set up the Python environment for running benchmark scripts. This command configures the PYTHONPATH.

```bash
cd gonka/mlnode/packages/benchmarks
PYTHONPATH="src:../common/src:$PYTHONPATH" python scripts/<script>.py <args>
```

--------------------------------

### Full Release Process

Source: https://github.com/gonka-ai/gonka/blob/main/mlnode/README.md

Runs all tests, builds and pushes the Docker image, and creates a new Git tag for the release.

```bash
VERSION=<version> make release
```

--------------------------------

### Start Bridge Container

Source: https://github.com/gonka-ai/gonka/blob/main/proposals/governance-artifacts/update-v0.2.5/README.md

Start the bridge container using Docker Compose after pulling the latest changes. Ensure the config.env file is sourced.

```bash
source config.env && docker compose up bridge -d
```

--------------------------------

### Start vLLM Inference with Management API

Source: https://github.com/gonka-ai/gonka/blob/main/mlnode/packages/api/src/api/inference/vllm/proxy.md

Use this command to start a vLLM inference service. Specify the model and data type for the inference.

```bash
# Start vLLM inference
curl -X POST http://localhost:8000/api/v1/inference/up \
  -H "Content-Type: application/json" \
  -d '{"model": "microsoft/DialoGPT-medium", "dtype": "auto"}'
```

--------------------------------

### FP8 Quantization on Different Machines

Source: https://github.com/gonka-ai/gonka/blob/main/mlnode/docs/inference-validation.md

This example shows the command-line arguments for generating and validating a model using FP8 quantization on different NVIDIA GPUs (RTX 3090 and L40S). It highlights potential discrepancies in inference results due to hardware support for FP8.

```bash
Generate: NVIDIA RTX 3090: --quantization fp8
Validate: NVIDIA L40S: --quantization fp8
```

--------------------------------

### Example Output of Gentx Generation

Source: https://github.com/gonka-ai/gonka/blob/main/genesis/README.md

This is an example of the output produced after successfully generating gentx and genparticipant files, showing the file paths and prompts.

```bash
./inferenced genesis gentx \
    --home ./702121 \
    --keyring-backend file \
    702121 1nicoin \
    --pubkey eNrjtkSXzfE18jq3lqvpu/i1iIog9SN+kqR2Wsa6fSM= \
    --ml-operational-address gonka13xplq68fws3uvs8m7ej2ed5ack9hzpc68fwvex \
    --url http://36.189.234.237:19238 \
    --moniker "mynode-702121" --chain-id gonka-mainnet \
    --node-id 149d25924b9a6676448aea716864c31775645459
Enter keyring passphrase (attempt 1/3):
Classic genesis transaction written to "702121/config/gentx/gentx-149d25924b9a6676448aea716864c31775645459.json"
Genparticipant transaction written to "702121/config/genparticipant/genparticipant-149d25924b9a6676448aea716864c31775645459.json"
```

--------------------------------

### Module Wiring and Dependency Injection

Source: https://github.com/gonka-ai/gonka/blob/main/inference-chain/x/genesistransfer/README.md

Demonstrates how the module automatically registers with the app wiring and handles dependency injection for essential keepers like AccountKeeper and BankKeeper.

```go
// Module automatically registers with app wiring
func ProvideModule(in ModuleInputs) ModuleOutputs {
    // Automatic dependency injection for AccountKeeper, BankKeeper, etc.
}
```

--------------------------------

### Run Mock Server with Gradle

Source: https://github.com/gonka-ai/gonka/blob/main/testermint/mock_server/README.md

Execute this command in the terminal to start the mock server using Gradle. The server defaults to port 8080.

```bash
./gradlew :mock_server:run
```