Config Reference — UNFED AI

How to use this page: Registry uses cluster_config.json. Daemon/Compute/MPC use node.run --config JSON files. Vision uses the compute schema with vision model settings.

# Registry
python -m network.registry_server --port 50050 --cluster-config cluster_config.json

# Node roles
python -m node.run --config daemon_config.json
python -m node.run --config compute_config.json
python -m node.run --config mpc_config.json

Registry (cluster_config.json)

Loaded by network.registry_server --cluster-config.

Field	Default	What it does
`cluster_id`	`""` (auto)	Cluster UUID. Auto-generated if omitted.
`name`	`""`	Human-readable cluster name shown to clients/operators.
`description`	`""`	Optional operator description of cluster purpose/region.
`operator`	`""`	Operator contact/name metadata.
`public_endpoint`	`""`	Public registry endpoint advertised to peers.
`default_min_stake`	`100.0`	Registry default stake policy. In on-chain mode, final admission checks use escrow `isEligible()`/`minStake()`.
`default_slash_fraction`	`0.5`	Default penalty share applied when slashing.
`default_reward_scheme`	`"proportional"`	Default reward distribution model.
`default_base_rate`	`0.001`	Base reward rate fallback.
`default_price_per_input_token`	`0.0001`	Client price per input token.
`default_price_per_output_token`	`0.001`	Client price per output token.
`default_pplns_window`	`1000`	PPLNS accounting window size.
`default_pps_rate`	`0.0`	PPS mode payout rate (if used).
`default_max_payout_multiplier`	`5.0`	Upper bound safety for payouts.
`default_fee_base`	`0.001`	EIP-1559 base fee starting value.
`default_fee_min`	`0.0001`	Minimum base fee floor.
`default_fee_max`	`0.1`	Maximum base fee cap.
`default_fee_adjustment_factor`	`0.125`	How aggressively fee changes per window.
`default_fee_target_utilization`	`0.7`	Target utilization for fee control loop.
`default_fee_window_blocks`	`10`	Utilization averaging window length.
`default_fee_target_capacity`	`40`	Shares/block expected at 100% utilization.
`chain_rpc_url`	`""`	RPC endpoint for on-chain escrow and staking.
`escrow_contract_address`	`""`	UnfedEscrow contract address.
`staking_token_address`	`""`	ERC-20 staking token contract address.
`operator_private_key`	`""`	Operator signing key used for on-chain actions.
`cooldown_seconds`	`3600`	Unbonding/cooldown delay.
`challenge_window_seconds`	`60`	Settlement challenge window duration.
`daemon_required_count`	`1`	Minimum healthy daemons required to serve.
`daemon_heartbeat_timeout_seconds`	`30`	Daemon considered stale after this timeout.
`daemon_fee_bps`	`200`	Daemon infra allocation in basis points.
`he_dispute_sampling_rate`	`0.05`	Fraction of HE outputs sampled for dispute checks.
`he_dispute_report_rate_limit_per_window`	`64`	Max HE dispute reports per time window.
`he_dispute_window_seconds`	`60`	Window size for HE dispute rate-limits.
`he_dispute_slash_fraction`	`0.5`	Slash fraction for confirmed HE fraud.
`he_dispute_rollout_stage`	`"shadow"`	Enforcement stage: `shadow\|soft\|enforced`.
`winner_bonus_per_report`	`0.25`	Share-weight bonus added per coordinator-signed race-winner receipt.
`winner_bonus_cap_ratio`	`0.5`	Caps winner bonus at this fraction of that node's base settlement shares.
`winner_receipt_store_path`	`"~/.unfed/registry_winner_receipts.jsonl"`	Lightweight persistent store for signed winner receipts (restart continuity + audit trail).
`winner_receipt_store_max_entries`	`200000`	Maximum retained winner receipts before compaction.
`created_at`, `updated_at`	`0.0`	Metadata timestamps (typically managed automatically).

Registry auth hardening: registration and control-plane RPCs now enforce timestamp + nonce replay guards with signed payload checks. Useful registry environment controls:

UNFED_AUTH_MAX_SKEW_MS (default 300000) — max accepted clock skew for signed control payloads.
UNFED_AUTH_NONCE_MAX_ENTRIES (default 200000) — hard cap for nonce replay caches (oldest entries evicted first).
UNFED_AUTH_RATE_LIMIT_PER_MINUTE (default 120) — per-peer/per-node rate limit for register/heartbeat/unregister auth RPCs.
UNFED_STAKE_REVALIDATE_TTL_SECONDS (default 30) — cache TTL before re-checking on-chain eligibility.

Shared Base Fields (daemon/compute/mpc)

Defined by BaseNodeConfig and inherited by node roles.

Field	Default	What it does
`role`	`"compute"`	Role selector: `compute`, `daemon`, or `mpc`.
`port`	`0`	Listen port. `0` means role default.
`host`	`"[::]"`	Bind host/interface.
`advertise`	`null`	Address advertised to registry (defaults to localhost:port).
`registry`	`null`	Registry endpoint used for registration/discovery.
`grpc_max_workers`	`0`	Worker pool size; `0` uses role defaults.
`grpc_max_message_mb`	`256`	Max gRPC message size in MB.
`heartbeat_interval_seconds`	`10`	Heartbeat interval to registry.
`connect_timeout`	`10.0`	Peer connect timeout.
`forward_timeout`	`60.0`	Forward RPC timeout.
`max_retries`	`3`	Retry count for resilient RPC calls.
`retry_backoff_base`	`1.0`	Base retry backoff (seconds).
`retry_backoff_max`	`10.0`	Max retry backoff (seconds).
`keepalive_time_ms`	`30000`	gRPC keepalive ping interval.
`keepalive_timeout_ms`	`10000`	Keepalive ping timeout.
`tls_cert`	`""`	TLS certificate file path (optional for local).
`tls_key`	`""`	TLS private key file path.
`require_tls_for_public`	`true`	Fail startup if public advertise lacks TLS.

Daemon Node (role=daemon)

Field	Default	What it does
`db_path`	`"~/.unfed/chain.db"`	SQLite path for sharechain persistence.
`chain_prune_keep`	`10000`	Keep last N blocks (0 disables pruning).
`block_interval_seconds`	`10.0`	Target block production interval.
`settlement_blocks`	`6`	Blocks per settlement window.
`collection_window_seconds`	`4.0`	Wait period before producing block.
`peer_refresh_interval_seconds`	`30.0`	How often daemon refreshes peer list.
`gossip_timeout_seconds`	`5.0`	Timeout for daemon gossip RPCs.
`sync_timeout_seconds`	`30.0`	Timeout for initial chain sync.
`fee_enabled`	`true`	Enable dynamic fee oracle.
`fee_base`	`0.001`	Initial base fee.
`fee_min`	`0.0001`	Base fee lower bound.
`fee_max`	`0.1`	Base fee upper bound.
`fee_adjustment_factor`	`0.125`	Per-window base fee adjustment magnitude.
`fee_target_utilization`	`0.7`	Target utilization for fee balancing.
`fee_window_blocks`	`10`	Rolling fee utilization window size.
`fee_target_capacity`	`40`	Expected shares per block at target utilization.

Daemon auth note: daemon now follows the same registry admission/control-plane hardening path: share-signing PoP at registration, EVM stake-auth signature in on-chain mode, and signed heartbeat/unregister with timestamp+nonce replay protection.

# Required in on-chain mode (prefer file-based secret loading)
export UNFED_STAKE_EVM_PRIVATE_KEY_FILE=~/.unfed/daemon_stake.key
python -m network.daemon_node --eth-address 0x<daemon staked wallet address> ...

Compute Node (role=compute)

Includes model/shard runtime, transfer policy, and HE/attestation controls.

Performance defaults are now always-on: compute nodes now run async daemon submission with batching/blob transport, output 2PC binary wire format with FP16 hidden-vector codec, and short-window same-hop micro-batching. These are no longer controlled by environment-variable toggles.

Model + Runtime

Field	Default	What it does
`shard_index`	`null`	Required shard index this node serves.
`model_name`	`"Qwen/Qwen2.5-0.5B"`	Model identifier metadata.
`model_type`	`"qwen2"`	Runtime type (`qwen2`, `qwen2_vl`, `smolvlm`).
`shards_dir`	`"shards"`	Directory containing split shard files.
`manifest_path`	`"shards/manifest.json"`	Manifest path used for layer metadata.
`max_memory_gb`	`null`	Optional memory budget hint.
`session_timeout_seconds`	`300`	KV session cleanup timeout.
`eos_token_id`	`151643`	EOS token override for model-specific termination.
`device`	`"cpu"`	Execution device (`cpu`, `cuda`, etc.).
`verification_sampling_rate`	`0.05`	Fraction of forwards sampled for verification logic.
`ticket_submit_interval_seconds`	`10`	Interval for verification ticket submission.

Transfer + Session Policy

Field	Default	What it does
`shard_transfer_timeout`	`600.0`	Timeout for shard transfer operations.
`shard_chunk_size`	`1048576`	Chunk size for shard streaming.
`serve_shards_enabled`	`true`	Whether this node serves shards to peers.
`max_upload_rate_mbps`	`0.0`	Upload throttle (0 = unlimited).
`max_concurrent_transfers`	`0`	Transfer concurrency cap (0 = unlimited).
`inference_priority`	`true`	Prioritize inference traffic over transfers.
`require_daemon`	`true`	Fail request if daemon is unavailable.
`allowed_prev_node_types`	`[]`	Optional upstream node type allowlist.

KV / Wire / Compression

Field	Default	What it does
`kv_quantize`	`"none"`	KV quantization mode (`none` or `int8`).
`kv_offload_enabled`	`false`	Enable KV offload under pressure.
`kv_offload_after_seconds`	`30.0`	Idle age before offload.
`max_kv_memory_gb`	`0.0`	KV memory cap (0 = unlimited).
`prefill_chunk_size`	`0`	Prefill chunking size (0 disables).
`wire_dtype`	`"float32"`	Activation wire precision.
`compress_activations`	`true`	Enable activation compression for wire hops.
`compress_threshold`	`16384`	Min payload bytes before compression.

Forward Attestation + HE Policy

Field	Default	What it does
`require_forward_attestation`	`true`	Require signed attestation from previous hop.
`require_forward_proof`	`false`	Require non-empty proof artifact in attestation.
`forward_proof_max_bytes`	`8192`	Max accepted attestation proof size.
`forward_proof_allowed_formats`	`["none"]`	Allowed proof format names.
`he_compute_mode`	`"off"`	Output mode: `off`, `decode_client_sample`, or `full_output_2pc` for output MPC A/B artifact handoff.
`he_compute_top_k`	`64`	Top-k for HE sampling path.
`he_compute_temperature`	`1.0`	Sampling temperature for HE path.
`he_compute_top_p`	`1.0`	Top-p for HE sampling path.
`he_full_vocab_sidecar_url`	`""`	Legacy field (retired path). Keep empty for current deployments.
`he_full_vocab_sidecar_timeout_ms`	`2000`	Legacy timeout for retired sidecar path.
`he_full_vocab_sidecar_required`	`false`	Legacy fail-closed toggle for retired sidecar path.
`he_sidecar_allowed_formats`	`["paillier_v1"]`	Legacy allowlist for retired sidecar disputes.
`he_sidecar_max_payload_bytes`	`2097152`	Legacy max payload size for retired sidecar disputes.
`he_dispute_sampling_rate`	`0.05`	HE dispute sampling fraction.
`he_dispute_report_rate_limit_per_window`	`64`	HE dispute report rate cap.
`he_dispute_window_seconds`	`60`	HE dispute rate-limit window.
`he_dispute_rollout_stage`	`"shadow"`	Rollout stage: `shadow\|soft\|enforced`.

On-chain registration requirement: in pools with on-chain escrow, compute/vision/MPC/daemon nodes must provide an EVM signature proving control of the stake identity used for admission.

# Required on compute/vision/MPC/daemon operators in on-chain mode
# (direct env still supported, file path is recommended)
export UNFED_STAKE_EVM_PRIVATE_KEY_FILE=~/.unfed/node_stake.key

Vision Node Profile

Vision nodes use the same compute schema. Main differences are operational values: set model_type to your vision pipeline, use the vision shard index/paths from your manifest, and run alongside text compute nodes.

For multimodal generation, output-token privacy controls still come from compute settings such as he_compute_mode (off, decode_client_sample, full_output_2pc).

{
  "role": "compute",
  "shard_index": 0,
  "model_type": "smolvlm_vision",
  "shards_dir": "shards_smolvlm",
  "manifest_path": "shards_smolvlm/manifest.json"
}

MPC Node (role=mpc)

MPC optimization defaults are also always-on: shard-0 runs async daemon submission with batching/blob transport, seed-based triple-set reuse, and persistent triple-cache prewarm at startup. Legacy compatibility toggles for these optimized paths are no longer exposed.

Field	Default	What it does
`mpc_role`	`"A"`	MPC role: entry node A or peer node B.
`peer_address`	`""`	Required address of the other MPC node.
`shard_index`	`0`	MPC always serves shard 0.
`mpc_dnc_mode`	`"off"`	DNC mode: off/manual/auto.
`mpc_dnc_depth`	`0`	Manual DNC recursion depth.
`mpc_dnc_split_dim`	`-1`	Manual split dimension for element-wise ops.
`mpc_dnc_matmul_split_dim`	`-3`	Manual split dimension for matmul paths.
`mpc_dnc_parallel_workers`	`1`	Worker count in manual DNC mode.
`mpc_dnc_auto_min_elems`	`65536`	Auto mode threshold for enabling DNC.
`mpc_dnc_auto_chunk_min_elems`	`16384`	Auto mode minimum chunk size.
`mpc_dnc_auto_max_depth`	`3`	Auto mode recursion cap.
`mpc_dnc_auto_max_workers`	`4`	Auto mode worker cap.

MPC inherits all compute + base fields too (timeouts, attestation, HE policy, TLS/public rules).

CLI Override Map

Common CLI flags that override JSON values in node.run:

--config --role --port --host --advertise --registry
--require-tls-for-public
--shard-index --model-type --shards-dir
--peer --db