Environment
All services read their settings from environment variables; the repository's .env.example lists them with comments. Defaults below are what the code uses when a variable is unset.
Several protocol values (gas budget, stake, rewards, slashing, AI thresholds) are governance parameters stored on chain. Where an environment variable exists for one, it overrides the on-chain value on that node at start-up — meant for test networks; on a shared network every validator must use the same value. See Governance → Parameters.
Node
Network and identity
| Variable | Default | Meaning |
|---|---|---|
CHAIN_ENV | mainnet | mainnet: strict signatures, faucet off, RPC on localhost. testnet: warn-only signatures, faucet on |
NEUROCHAIN_NETWORK | neurochain-mainnet-1 | Network / chain id |
NEUROCHAIN_DATA_DIR | ./data | Data directory (state, WAL, key) |
NEUROCHAIN_MODELS_DIR | ./models | AI model weights |
NEUROCHAIN_RPC_PORT | 9933 | HTTP RPC port |
NEUROCHAIN_RPC_HOST | localhost (mainnet) / 0.0.0.0 (testnet) | RPC bind address |
NEUROCHAIN_P2P_PORT | 30333 | P2P port (also carries consensus) |
NEUROCHAIN_P2P_PORT_MIN / _MAX | 1024 / 65534 | Accepted peer port range |
NEUROCHAIN_NODE_ADDR | localhost:<p2p port> | Address peers use to reach this node; must not be 0.0.0.0. Matches the node to its genesis validator entry |
NEUROCHAIN_BOOTSTRAP | — | Comma-separated peers to join on start |
NEUROCHAIN_PEER_DISCOVERY_SECS | 30 | Peer discovery interval |
NEUROCHAIN_P2P_CONN_RATE_LIMIT | 20 | Inbound P2P connections per second per IP |
NEUROCHAIN_TLS_CERT, NEUROCHAIN_TLS_KEY | — | Serve the RPC over HTTPS |
Genesis
| Variable | Default | Meaning |
|---|---|---|
NEUROCHAIN_GENESIS_VALIDATORS | this node only | `neuro:name.node |
NEUROCHAIN_GENESIS_ACCOUNTS | — | `neuro:addr.human |
NEUROCHAIN_FAUCET_BALANCE | 1 000 000 000 NRO | Balance of the faucet vault at genesis |
NEUROCHAIN_INITIAL_BALANCE | 0 | uNRO credited to a never-seen account on first read (test networks only) |
NEUROCHAIN_GAS_SPONSOR | neuro:faucet.vault | Onboarding gas sponsor |
NEUROCHAIN_GAS_SPONSOR_FUND | 1 000 000 NRO | Its gas pool at genesis |
NEUROCHAIN_CHECKPOINT_URL | — | Start an empty node from this node's state snapshot |
Consensus and sharding
| Variable | Default | Meaning |
|---|---|---|
NEUROCHAIN_MIN_VALIDATORS | 7 | Below this, the node warns about reduced fault tolerance |
NEUROCHAIN_BLOCK_MS | 200 | Minimum wait before proposing a block with transactions |
NEUROCHAIN_EMPTY_BLOCK_MS | 2000 | Minimum wait before proposing an empty block |
NEUROCHAIN_SYNC_HISTORY_BLOCKS | 10000 | Decided blocks kept to serve catching-up peers |
NEUROCHAIN_JAIL_BLOCKS | 10000 | Jail length after a slash (governance jail_blocks) |
NEUROCHAIN_SLASH_FRACTION_DOUBLE_SIGN_BPS | 500 | Double-sign slash, basis points of min_stake |
NEUROCHAIN_SLASH_REWARD_FRACTION_BPS | 100 | Reporter's share of a slash |
NEUROCHAIN_SLASH_EVIDENCE_WINDOW | 10000 | Oldest offence (in blocks) that evidence may prove |
NEUROCHAIN_SHARD_ID | — | Shard this node serves; unset = single shard |
NEUROCHAIN_SHARDS | 4 with a shard id, else 1 | Number of shards |
NEUROCHAIN_SHARD_DIR_PREFIX | shard | Sub-directory name per shard |
Economics and mempool
| Variable | Default | Meaning |
|---|---|---|
NEUROCHAIN_UNBONDING_BLOCKS | governance (1 512 000) | Staking lock |
NEUROCHAIN_REWARD_INTERVAL_BLOCKS | governance (216 000) | Blocks between reward payouts |
NEUROCHAIN_FUEL_PER_GAS_UNIT | 20000 | Contract fuel per gas unit |
NEUROCHAIN_MAX_SPONSORED_FEE | 100000 uNRO | Largest fee a gas pool pays per transaction |
NEUROCHAIN_MAX_MEMPOOL | 10000 | Pending transactions held |
NEUROCHAIN_MAX_PENDING_PER_ACCOUNT | 64 | Pending transactions per sender |
NEUROCHAIN_RBF_MIN_BUMP_PCT | 10 | Gas price increase needed to replace a pending transaction |
NEUROCHAIN_MIN_FEE_PER_GAS | 0 | Extra mempool price floor |
NEUROCHAIN_FAUCET_MAX_NRO | 100 | Largest faucet request (test networks) |
NEUROCHAIN_FAUCET_COOLDOWN_SECS | 86400 | Faucet cooldown per address; 0 = none |
AI
| Variable | Default | Meaning |
|---|---|---|
MONITOR_INTERVAL_SECS | 20 | Re-audit of deployed contracts |
MONITOR_SCORE_THRESHOLD | 10 | Score change that triggers a certificate update |
NEUROCHAIN_SENTINEL_POLICY_ENABLED | governance (0) | Sentinel policy layer on/off |
NEUROCHAIN_SENTINEL_HOLD_THRESHOLD | governance (60) | Score × 100 from which transfers are held |
NEUROCHAIN_SENTINEL_STEPUP_THRESHOLD | governance (70) | Score × 100 from which the owner must confirm |
NEUROCHAIN_SENTINEL_HOLD_BLOCKS | governance (50) | Automatic release delay |
NEUROCHAIN_SENTINEL_CONFIRM_EXPIRY_BLOCKS | governance (1000) | Wait for confirmation before refund |
NEUROCHAIN_SENTINEL_AGENT_CONFIRM_THRESHOLD | governance (60) | Threshold for session-key transfers |
NEUROCHAIN_TRUST_ACTIVATION_BLOCKS | governance (300) | Delay before a trusted recipient counts |
AI_EXPORT_MAX_LIMIT | 5000 | Rows per AI data export request |
IBC v2
See IBC v2 & sharding → Configuration: NEUROCHAIN_IBC_OPERATOR_PUBKEYS, NEUROCHAIN_IBC_TRUSTED_PUBKEYS, NEUROCHAIN_IBC_REQUIRE_HEADER, NEUROCHAIN_IBC_REQUIRE_PACKET_COMMITMENT, NEUROCHAIN_IBC_TIMEOUT_BLOCKS, NEUROCHAIN_IBC_MAX_PACKET_UNRO, NEUROCHAIN_IBC_MAX_CHANNEL_ESCROW_UNRO, NEUROCHAIN_IBC_NATIVE_DENOM.
Native assets
| Variable | Default | Meaning |
|---|---|---|
NEUROCHAIN_ASSET_ISSUERS | — | Addresses given the verified issuer tier at genesis |
NEUROCHAIN_RESERVED_SYMBOLS | — | Tickers reserved at genesis |
Both are read once, at genesis; afterwards the registries change only through governance.
Access and limits
| Variable | Default | Meaning |
|---|---|---|
NEUROCHAIN_RPC_RATE_LIMIT | 100 | RPC requests per second per IP |
CORS_ALLOWED_ORIGINS | * | Allowed browser origins |
NEUROCHAIN_INTERNAL_TOKEN | — | Required X-Internal-Token for internal endpoints |
NEUROCHAIN_SNAPSHOT_TOKEN | — | Required bearer token for /api/v1/state/snapshot |
NEUROCHAIN_ALLOW_SERVER_DERIVE | false | Allow POST /api/v1/wallet/derive-address (receives a recovery phrase) on test networks; always off on mainnet |
RUST_LOG | neurochain=info,warn | Log level |
Gateway
Listed with explanations on the Gateway page: PORT, NODE_RPC_URL, NEUROCHAIN_SHARD_NODES, SHARD_NODE_URLS, NETWORK_ID, CORS_ALLOWED_ORIGINS, TLS_CERT, TLS_KEY, rate limits (GLOBAL_RL_MAX_RPS, AI_RL_MAX_RPM, WS_*), chain watching (POLL_NODE_INTERVAL_MS, SENTINEL_*, ALERT_COOLDOWN_MS), faucet (FAUCET_AMOUNT, FAUCET_COOLDOWN_SECS, REDIS_URL) and AI tools (ANTHROPIC_API_KEY, SMARTFORGE_*, AI_EXPORT_TOKEN, ASSISTANT_*).
Web app
| Variable | Default | Meaning |
|---|---|---|
WEB_PORT | 8080 | Dev server port |
WEB_HOST | localhost | Dev server bind; 0.0.0.0 to expose on the network |
GATEWAY_URL | http://localhost:3000 | Gateway the dev server proxies /api and /ws to |
VUE_APP_NEUROCHAIN_RPC | — (same origin) | Force a fixed API base URL into the build |
VUE_APP_SITE_URL, VUE_APP_SITE_NAME, VUE_APP_SITE_OG_IMAGE | — | Metadata of the deployed app |
VUE_APP_DOCS_URL | — | Link to this documentation |
Docs site
| Variable | Default | Meaning |
|---|---|---|
DOCS_SITE_URL | https://docs.nro.world | Canonical URLs, sitemap, hreflang, llms.txt |
DOCS_OG_IMAGE | /og-image.png | Social preview image |
DOCS_GOOGLE_SITE_VERIFICATION, DOCS_BING_SITE_VERIFICATION | — | Search-console ownership tokens |
DOCS_HOST, DOCS_PORT | localhost, 5173 | Dev server |
DOCS_BASE | / | Base path |
MCP server
| Variable | Default | Meaning |
|---|---|---|
NEUROCHAIN_MCP_CONFIG | — | Path to the JSON config — see AI agents (MCP) |