Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
284 lines (204 loc) · 9.86 KB

GETTING_STARTED.md

File metadata and controls

284 lines (204 loc) · 9.86 KB
Raw

ILC Getting Started

Epoch 0 — Public RC. Production mainnet, ECU minting, and ILC settlement are not yet active. See docs/phases/STATUS.md for current activation state. This guide covers operator setup from public RC onward.

This guide bridges the root README.md and the protocol spec/architecture docs. It is intentionally practical and focused on what you can run today.

1. Installation

Prerequisites

  • Python 3.10+
  • Rust toolchain (rustup recommended): curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  • Git

From source

git clone https://github.com/jamison/ilc.git
cd ilc
python3 --version   # must be Python 3.10+
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
ilc version

The python -m pip install -e . path installs the ilc binary and all Python protocol modules in editable mode. Verify the install immediately with ilc version.

Build the Rust consensus layer

The Rust consensus layer (ilc_consensus/) provides BLS12-381 quorum compression, the post-quantum signing tool (pq_sign), and the low-level DAG consensus substrate. It is not required for Python-only local graph operations, but is required for consensus participation and Genesis signing.

cd ilc_consensus
cargo build --release
cd ..

Binaries are placed in ilc_consensus/target/release/. The main binary is ilc_consensus/target/release/ilc_consensus. The post-quantum signing tool is ilc_consensus/target/release/pq_sign.

Verify installation

ilc version          # confirms Python layer
ilc doctor           # full local health check — JSON output
ilc-canon-cluster-a-replay-proof ci-gate --profile release-v0.1 --pretty
bash tools/check_cluster_a_replay_proof_release_gate.sh

ilc doctor reports: Python version, ilc_core importability, local identity state, balance state, CCSS identity, and any missing components. Expected output on a fresh install with no identity yet:

{
  "ok": false,
  "checks": {
    "ilc_core_importable": true,
    "identity_initialized": false,
    "balance_state_present": false,
    "ccss_identity_present": false
  },
  "verdict": "not_initialized",
  "next_action": "ilc identity init"
}

2. Identity Initialization

Every ILC participant — human operator or AI agent — has a local identity rooted in an ML-DSA-65 keypair (NIST FIPS 204). The identity is content-addressed (CIDv1) and cannot be recovered if the seed material is lost.

Development / local install (no invite required)

ilc identity init \
  --lineage-id lineage-local \
  --key-ref key-local-0

This creates a local identity suitable for development and local graph operations. No invite token is required.

Invite-gated install (production bootstrap)

For production participation, an invite token from an existing network member is required. The invite encodes a one-time nullifier preventing replay.

ilc identity init \
  --invite path/to/invite_batch.json \
  --enable-invites \
  --identity-seed-hex <64-char-hex-seed> \
  --redeemer-pubkey-cid <cid>

Warning: The identity seed is the cryptographic root of your network identity. Write it to durable offline storage before the init call returns. There is no recovery path if it is lost.

Verify identity

ilc identity show

Expected output includes lineage_id, status: "active", and key_ref. The agent_id (CIDv1) is derived from your public key at initialization time.

3) First local run (quick path)

Boot genesis (verify local config)

python3 tools/genesis_boot.py

Reads config/genesis.json, prints the genesis hash and signer summary, and exits. This is a local read-only verification step — it does not submit anything to the network.

Run the local node

python3 run_node.py

Starts the local ILC node API on http://127.0.0.1:8000/. Endpoints:

Route Purpose
GET / Node health and summary
GET /v1/protocol/schema Protocol schema
POST /v1/protocol/claim Submit a claim
POST /v1/protocol/task_outcome Submit a task outcome record
POST /v1/protocol/refute Submit a refutation
GET /node/{node_id} Fetch a graph node by ID
GET /docs OpenAPI interactive docs

Run the demo walkthrough

In a second terminal:

python3 tools/demo_walkthrough.py

The demo submits a sample claim, refutation, and revision through the local node API and prints the resulting graph state. Useful for confirming end-to-end local operation.

4. ILC CLI Reference (key commands)

ilc --help                    # Full command reference
ilc doctor                    # Local health check
ilc version                   # Version info
ilc identity init             # Initialize local identity
ilc identity show             # Show current identity state
ilc identity rotate           # Rotate operational key
ilc submit                    # Submit a truth primitive to local graph
ilc query node <id>           # Query a graph node
ilc verify claim <id>         # Verify a claim record
ilc balance                   # Show local ECU/ILC balance state
ilc sidecar list              # List installed sidecars
ilc sidecar recipe list       # List available recipes
ilc sidecar recipe apply <name>  # Apply a sidecar recipe
ilc ccss apply-recipe         # Configure CCSS (confidential messaging)
ilc ccss send genesis "msg"   # Send a message to Genesis Agent
ilc ccss inbox                # Check incoming messages
ilc atlas status              # Genesis Atlas LMDB status

Truth primitives (the 7 canonical operations):

ilc submit --primitive assert.truth     # Assert a new claim
ilc submit --primitive validate.claim   # Validate an existing claim
ilc submit --primitive contradict.assert # Contradict an assertion
ilc submit --primitive refute.claim     # Refute with evidence
ilc submit --primitive revise.assert    # Issue a revision
ilc submit --primitive link.claim       # Link two claims
# commit.epoch is consensus-layer only — not agent-issuable

5. CCSS — Confidential Coordination

CCSS (Confidential Coordination Sidecar Suite) provides private, sealed-sender messaging using fixed-size 4156-byte encrypted envelopes. It is the primary contact surface for reaching Genesis Agent and for private operator coordination.

# Apply the full CCSS recipe (first-time setup)
ilc ccss apply-recipe

# Check configured contacts
ilc ccss contacts

# Send a message
ilc ccss send genesis "Hello Genesis"

# Check your inbox
ilc ccss inbox
ilc ccss read --latest

Transport ladder:

  1. Direct transport — host:port for peers on the same network
  2. Tor transport — .onion hidden service for anonymized delivery
  3. D2d transport — planned ILC-native routing by agent_id (requires live D2d peer network)

See sidecars.md for the full CCSS bootstrap flow.

6. OpenClaw Integration (optional)

OpenClaw is an optional multi-agent orchestration layer that ILC can use as a host. The ilc-openclaw-local-capture skill provides local capture, consent-gated ECU estimation, and invite-gated bootstrap for ILC graph contribution via OpenClaw sessions.

Install the canonical ILC ClawHub entry:

clawhub install ilc

OpenClaw local capture is routed through the canonical ilc listing.

The skill adds the following vocabulary to OpenClaw sessions:

Skill command Purpose
capture Capture session output to local ILC graph
estimate Non-binding private ECU estimate
verify-invite Verify an invite token
status Show local queue and policy state
mine-idle Run idle-capacity maintenance tasks

These are OpenClaw skill vocabulary, not top-level ilc binary commands. See skills/ilc-openclaw-local-capture/SKILL.md.

7. Running Tests

# Quick focused tests
pytest tests/test_phase_1575b_fix2i_cli_minimal_polish.py -q

# Full Python test suite
pytest -q

# Rust test suite
cd ilc_consensus && cargo test --workspace && cd ..

The full Python suite is deliberately slower than the quick path. Run it when a phase or release gate requires it, not on every edit.

8. Configuration Reference

Path Purpose
config/genesis.json Genesis configuration — do not edit without an explicit CDL
config/README.md Full configuration policy
~/.ilc/ Local runtime state (identity, balance, CCSS, graph state)

See config/README.md for full configuration policy.

9. Architecture Orientation

Document What it covers
README.md Project overview, feature table, TOON block
HUMANS.md Full introduction, letter to agents, ECU/PoIL explanation
QUICKSTART.md Two-audience quickstart (digital agents + human operators)
economics.md ECU mechanics, decay, conversion, anti-hoarding
sidecars.md Sidecar platform, available recipes
methodology.md Development methodology, CDL governance, coding standards
SECURITY.md Responsible disclosure, PQ identity, spectral integrity model
Glossary.md Canonical term definitions
docs/ILC_Technical_Paper_Draft_v0.2.md Protocol architecture, PoIL, consensus design
docs/ILC_Economic_Paper_Draft_v0.3.md Economic design, ECU model, agentic labor costs
docs/phases/STATUS.md Live protocol activation state
docs/architecture/ilc_canonical_glossary_and_concepts_v0.2.md Canonical term authority