Skip to content

getting-started.md

Latest commit

 

History

History
657 lines (433 loc) · 18.4 KB

getting-started.md

File metadata and controls

657 lines (433 loc) · 18.4 KB
Raw

Model_0 — InfiniteZero Network Protocol

Tip

Hit an error or get stuck anywhere in this guide? Post it in the DevNet 2.0 pre-launch discussion.

Welcome to the onboarding guide for Model_0 on the InfiniteZero Network.

Planning a different model or dataset? Read What can I train on DIN? to understand the tested reference, custom-service path, and practical limits.

InfiniteZero Network devnet has been launched as sepolia_op_devnet.

Model_0 is the first active model registered on the InfiniteZero Network and serves as the pioneer deployment of InfiniteZero's model-specific smart contracts.

The InfiniteZero Network coordinates decentralized AI training, auditing, aggregation, and validation through Ethereum smart contracts, off-chain distributed compute, and decentralized storage.

🧭 Protocol Overview

Model_0 operates through recurring Global Iterations (GI).

Each Global Iteration represents a complete decentralized training cycle coordinated by Ethereum smart contracts.

A typical iteration includes:

  1. Clients train local models on their own datasets
  2. Local model updates are submitted to IPFS and referenced on-chain
  3. Auditors independently evaluate the submitted local models and approve (or reject) them.
  4. Approved local models are batched and assigned to aggregators for aggregation.
  5. Aggregators aggregate assigned T1 and subsequently T2 aggregation batches.
  6. The resulting global model is finalized and published
  7. The next iteration begins using the updated global model

This process enables decentralized, verifiable, and scalable collaborative AI training without centralizing participant data.

🌐 What is sepolia_op_devnet?

To simplify onboarding, we refer to our devnet as:

sepolia_op_devnet = Optimism Sepolia testnet + DIN deployed contracts

So when you see:

SEPOLIA_OP_DEVNET_RPC_URL=<your_rpc_url>

It means:

  • You are connecting to Optimism Sepolia
  • And interacting specifically with DIN protocol contracts deployed there

Current Status

Note

This guide documents Model_0's protocol flow as implemented on the develop branch, which can be ahead of what is actually deployed on the live sepolia_op_devnet network — including which Global Iteration is open and whether aggregator/auditor steps use the commit-then-reveal flow described below (added after the initial devnet deployment). Always confirm the live state yourself before acting:

dincli task gi show-state 0

🔐 Security Model

The InfiniteZero Network is secured by Ethereum smart contracts deployed on Sepolia OP Devnet.

Ethereum acts as the source of truth for:

  • Participant registration
  • State transitions
  • Submission coordination
  • Staking logic
  • Validation rules
  • Protocol enforcement

On-chain responsibilities

Layer Responsibility
Ethereum (on-chain) Coordination, state, validation, enforcement
IPFS/Filebase Model artifacts and decentralized storage
Off-chain compute Training, aggregation, auditing
Participants Execute computation and submit results

Core guarantee

The system is verifiable end-to-end:

  • Ethereum enforces correctness, coordination, and finality
  • IPFS ensures reproducible and distributed data availability
  • Off-chain compute enables scalable ML execution

💡 Trust is shifted from participants to cryptographic enforcement on-chain. Staking exists to add economic enforcement on top of that, but the reward/slashing economics are still under active development — see "Current Devnet Scope" further down this guide — so treat "economic enforcement" as a protocol goal, not yet a fully live guarantee.

📦 Data Availability Layer (IPFS via Filebase)

The protocol uses IPFS (commonly through Filebase) as a decentralized storage layer for protocol artifacts.

This includes:

  • Local model uploads
  • Aggregated/global model artifacts
  • Manifest or scripts artifacts
  • Aggregation outputs

🎭 Participation Model

Participants may operate as one or more of the following roles simultaneously:

  1. Aggregators
    • Aggregate Tier 1 and Tier 2 batches of models
  2. Auditors
    • Independently evaluate the submitted local models and approve (or reject) them.
  3. Clients
    • Train local models on local datasets
    • Submit local model updates to the network

💡 A single participant may act as Client, Auditor, and Aggregator simultaneously using multiple accounts.

🧠 Validator Model (No Mining)

This system does not use mining or Proof-of-Work.

Instead, it uses a role-based validation model coordinated through Ethereum smart contracts on sepolia_op_devnet.

  • Clients train and submit local model updates
  • Auditors independently evaluate the submitted local models and approve (or reject) them.
  • Approved model updates are batched and assigned to aggregators
  • Aggregators aggregate assigned T1 and subsequently T2 aggregation batches.
  • Ethereum finalizes accepted protocol state transitions

💡 Aggregators and Auditors collectively function as validators.

💻 System Requirements

Participating in Model_0 on the InfiniteZero Network is lightweight and does not require specialized hardware.

Minimum Requirements

  • RAM: 4 GB
  • Disk: ~30 GB
  • CPU: Standard CPU (GPU not required)
  • Python 3 + virtual environment

Dependencies

  • dincli
  • Python ML/runtime dependencies (~5 GB virtual environment)

💡 Typical setup time is around 10–15 minutes for users familiar with Python environments.

⚠️ Current Devnet Scope

The current devnet primarily focuses on:

  • Decentralized coordination
  • Distributed training
  • Aggregation workflows
  • Validation workflows
  • Ethereum-enforced protocol state transitions

Staking, slashing and rewards are part of every Global Iteration: validators stake DIN to register, misbehaving or absent validators are slashed, and each GI pays clients, auditors and aggregators from a reward pool the model owner funds before starting it. After a GI ends, claim your share with dincli rewards claim <model_id> --gi <gi> and dincli rewards withdraw <model_id>. Reward splits, bond sizes and other economic parameters are not final and may change between devnet phases.

🌐 Community Channels

Telegram

  • Announcements
  • Coordination
  • Community support

https://t.me/+h46VS3AnO384ZGI8

Signal

  • Technical discussions
  • Coordination
  • Protocol updates

https://signal.group/#CjQKICVqJ0Ri3KGCZOsf8A3dhmg8GC_vc1MBmBrq0JV7lIr6EhBCOwElVHvE0swjO8kSk7ky

⚠️ Global Iteration updates and onboarding assistance are shared regularly.

Faucet Access (Sepolia Optimism)

To participate in the InfiniteZero Network devnet, you will need Sepolia Optimism ETH for transaction fees.

You can request testnet tokens from the following official faucets:

If you are unable to obtain funds through the faucets above, you may also request Sepolia Optimism ETH through the InfiniteZero Foundation Telegram and Signal community groups.

🩺 Environment Preflight Check

For contributors working from a clone of this repo. Participants who installed dincli from the wheel (per setup.md) can skip this section — forge and anvil are not required for network participation.

Before starting development, verify your environment with:

python3 scripts/preflight.py

The script checks each of the following and prints [OK], [WARN], or [MISSING] with a fix hint:

Check Pass condition
Python version ≥ 3.12
forge on PATH Foundry installed
anvil on PATH Foundry installed
foundry/node_modules cd foundry && npm ci has been run
eth-account, py-multibase, web3 importable after pip install -e .
torch importable after pip install -e .[test] (optional — tests skip without it)

Exits 0 when all required checks pass; exits 1 if Python is below 3.12, forge or anvil is missing, foundry/node_modules is absent, or a core package (eth-account, py-multibase, web3) cannot be imported. Missing optional torch only warns and does not fail preflight.

To also verify the configured RPC endpoint (read from os.environ or .env, the same lookup dincli uses) and the IPFS config:

python3 scripts/preflight.py --network sepolia_op_devnet
# or: python3 scripts/preflight.py --network local

Network checks run only with --network. When requested, missing RPC configuration, an unreachable endpoint or invalid RPC response, and unresolved or incomplete IPFS configuration also cause exit 1. A reachable RPC reporting an unexpected chain ID remains a warning.

⚙️ DIN CLI Installation and Setup

Before participating, ensure dincli is correctly installed and configured.

Please read:

https://github.com/InfiniteZeroFoundation/DevNet/blob/develop/Documentation/public/setup.md

Initialize DIN CLI

dincli system init

Environment Configuration

Set RPC URL in .env:

SEPOLIA_OP_DEVNET_RPC_URL=<your_rpc_url>

Add Ethereum private keys:

⚠️ Local development only. The ETH_PRIVATE_KEY_<n> pattern stores raw private keys in plaintext. Production validators: use the encrypted keystore instead — see wallet-setup.md.

ETH_PRIVATE_KEY_0=...
ETH_PRIVATE_KEY_1=...

dincli system init (above) defaults demo mode off, so register-wallet --account <n> below reads straight from these .env keys. If you'd rather use a well-known local Hardhat dev key instead of your own, use dincli system connect-demo-wallet --account <n> (requires dincli system configure-demo --mode yes) in place of register-wallet in the steps below.

Recommended

  • Use Filebase as your IPFS provider

🧩 Aggregators

Step 1: Explore Model

dincli task explore 0

Step 2: Check Global Iteration State

dincli task gi show-state 0

Step 3: Register (if state = DINaggregatorsRegistrationStarted)

# Register wallet (example: account index 0; saved as 'default', the active fallback)
dincli system register-wallet --account 0

# Check ETH balance
dincli system --eth-balance

# Buy DIN tokens
dincli aggregator dintoken buy 0.00001

# Stake tokens
dincli aggregator dintoken stake 10

# Verify stake
dincli aggregator dintoken read-stake

# Register as aggregator
dincli aggregator register 0

Step 4: Check Global Iteration State

dincli task gi show-state 0

Step 5: Check your Aggregation Batch (if state = T1nT2Bcreated)

If the state is still LMSevaluationClosed, lock the batch-assignment seed first (this moves it to AggSeedLocked; the model owner then creates the batches):

dincli aggregator lock-seed 0
# Check T1 batch assigned to you
dincli aggregator show-t1-batches 0 --detailed

# Check T2 batch assigned to you
dincli aggregator show-t2-batches 0 --detailed

Step 6: Check Global Iteration State

dincli task gi show-state 0

Step 7: Aggregate your T1 Batch (commit if state = T1AggregationStarted, reveal if T1AggregationRevealStarted)

# show the aggregator its assigned t1 batches if assigned
dincli aggregator show-t1-batches 0 --detailed

# aggregate the assigned t1 batches and commit a hidden hash of the result
dincli aggregator aggregate-t1 0 --submit

# once the model owner opens the T1 reveal window: reveal your commit
dincli aggregator reveal-t1 0

Step 8: Aggregate your T2 Batch (commit if state = T2AggregationStarted, reveal if T2AggregationRevealStarted)

# show the aggregator its assigned t2 batches if assigned
dincli aggregator show-t2-batches 0 --detailed

# aggregate the assigned t2 batches and commit a hidden hash of the result
dincli aggregator aggregate-t2 0 --submit

# once the model owner opens the T2 reveal window: reveal your commit
dincli aggregator reveal-t2 0

⚠️ Aggregation is commit-then-reveal: a commit that is never revealed is slashed like a missed submission. Reveal from the same machine you committed from; the salt is cached locally.

Step 9: Claim your reward (once state = GIended)

# credit your share of GI <gi> (the GI you took part in), then withdraw it
dincli rewards claim 0 --gi <gi>
dincli rewards withdraw 0

💡 T1 and T2 batch assignments depend on the current Global Iteration state and protocol allocation logic. A registered aggregator may not receive a batch in every iteration.

🛡️ Auditors

Step 1: Explore Model

dincli task explore 0

Step 2: Check Global Iteration State

dincli task gi show-state 0

Step 3: Register (if state = DINauditorsRegistrationStarted)

# Register wallet (saved as 'default', the active fallback)
dincli system register-wallet --account 0

# Check ETH balance
dincli system --eth-balance

# Buy DIN tokens
dincli auditor dintoken buy 0.00001

# Stake tokens
dincli auditor dintoken stake 10

# Verify stake
dincli auditor dintoken read-stake

# Register as auditor
dincli auditor register 0

# Once per wallet: register the encryption key your batch's test data is encrypted to
dincli auditor register-encryption-key

Step 4: Check Global Iteration State

dincli task gi show-state 0

Step 5: Check your Auditor Batch (if state = AuditorsBatchesCreated or AuditTestDataAssigned)

If the state is still LMSclosed, lock the batch-assignment seed first (this moves it to AuditSeedLocked; the model owner then creates the batches):

dincli auditor lock-seed 0
dincli auditor lms-evaluation show-batch 0

If a batch is shown, you will soon be required to audit it. The model owner then assigns each batch its test data (AuditTestDataAssigned) and opens evaluation.

Step 6: Check Global Iteration State

dincli task gi show-state 0

Step 7: Audit your assigned batch (commit if state = LMSevaluationStarted, reveal if LMSevaluationRevealStarted)

# check your assigned batch
dincli auditor lms-evaluation show-batch 0

# audit your batch (scripts run automatically) and commit a hidden hash of each score
dincli auditor lms-evaluation evaluate 0 --submit

# once the model owner opens the reveal window: reveal your scores
dincli auditor lms-evaluation reveal 0

⚠️ Scoring is commit-then-reveal: a commit that is never revealed is slashed as a missed vote. Reveal from the same machine you committed from; the salt is cached locally.

Step 8: Claim your reward (once state = GIended)

# credit your share of GI <gi> (the GI you took part in), then withdraw it
dincli rewards claim 0 --gi <gi>
dincli rewards withdraw 0

💡 Auditor batch assignments depend on the current Global Iteration state and protocol allocation logic. A registered auditor may not receive a batch in every iteration.

🤖 Clients

  • Train local models using their dataset partition
  • Submit model updates to the network

📊 MNIST Dataset Distribution

Model_0 uses the MNIST dataset, which is integrated into dincli for ease of use for clients. If you have your own MNIST dataset please proceed to Dataset Requirements subsection. Otherwise you can distribute the dataset as follows:

📦 Distribute Dataset

dincli system dataset distribute-mnist \
  --seed <seed> \
  --model-id <model-id> \
  --test-train \
  --clients \
  --num-clients <num-clients> \
  --start-client-index <start-client-index>

where:

Argument Description
--seed Random seed for shuffling
--model-id Creates model directory
--test-train Creates dataset directory
--clients Enables client dataset distribution
--num-clients Number of participating clients
--start-client-index Starting wallet index

Example:

dincli system dataset distribute-mnist \
  --seed 42 \
  --model-id 0 \
  --test-train \
  --clients \
  --num-clients 9 \
  --start-client-index 0

Account Indexing Requirement

Ensure sufficient private keys in .env.

Formal Requirement

MAX_INDEX ≥ start-client-index + num-clients - 1

Interpretation

  • Clients are assigned sequentially and inclusively
  • Total keys required = num-clients

Example

If:

  • start-client-index = 2
  • num-clients = 9

Then:

ETH_PRIVATE_KEY_2 → ETH_PRIVATE_KEY_10

📂 Dataset Requirements

Ensure your dataset is located at:

<CACHE_DIR>/sepolia_op_devnet/model_0/dataset/clients/<account_address>/data.pt

Find your cache directory:

dincli system get-cache-dir

Training Process

Step 1: Explore Model

dincli task explore 0

Step 2: Check Global Iteration State

dincli task gi show-state 0

Step 3: Submit Local Model (if state = LMSstarted)

# Register wallet (saved as 'default', the active fallback)
dincli system register-wallet --account 0

# Check ETH balance
dincli system --eth-balance

# Train a local model (nothing is sent on-chain)
dincli client train-lms 0

# Upload the trained model and submit it
dincli client submit-lm 0

# Show submitted models
dincli client lms show-models 0

Step 4: Claim your reward (once state = GIended)

# credit your share of GI <gi> (the GI you took part in), then withdraw it
dincli rewards claim 0 --gi <gi>
dincli rewards withdraw 0

🧠 Final Notes

  • Always verify the Global Iteration State before taking action
  • Use multiple accounts strategically if desired
  • Stay active in community channels for protocol updates and troubleshooting assistance

🚀 You are now ready to participate in Model_0 and contribute to decentralized AI on the InfiniteZero Network.