# MazeXChain Module Responsibilities

## 1. Module Map

| Module | Main Files | Inputs | Outputs | Depends On |
| --- | --- | --- | --- | --- |
| HTTP server | `src/server.js` | HTTP requests, static assets, runtime config | API responses, static pages | `src/lib/*` |
| Runtime config | `src/lib/config.js`, `config/*.json`, `genesis/*.json` | Project config files, genesis files, environment overrides | Normalized config snapshots and runtime defaults | filesystem |
| Base1 generator | `src/lib/base1_algorithm.js` | Layer, Step, chain seed, difficulty, fragments | Challenge behavior, commitments, metadata | difficulty, RNG, parameters |
| Difficulty engine | `src/lib/difficulty.js` | Layer, Step, protocol knobs | Grid size, score, operator/parameter targets | config constants |
| Static parameters | `src/lib/parameter_extractors.js`, `src/lib/parameter_selectors.js`, `src/lib/parameter_injector.js` | Difficulty, RNG | Bound static numeric parameters | RNG, operator rules |
| Dynamic parameters | `src/lib/dynamic_context.js`, `src/lib/dynamic_parameter_extractors.js`, `src/lib/dynamic_parameter_injector.js` | Context, click count, time bucket, state references | Dynamic terms and context bindings | RNG, context model |
| Operator selection | `src/lib/formula_selectors.js`, `src/lib/combiner_selectors.js` | Difficulty, RNG, parameter pool | Operator units and composition plan | parameter modules |
| Output pipeline | `src/lib/output_pipeline.js`, `src/lib/blackbox.js` legacy alias | Generated expressions, input point, context | Challenge behavior output point `B(u,v)` | Base1 generator |
| Behavior commitment | `src/lib/behavior_commitment.js` | Behavior table or deterministic behavior leaves | Behavior root and commitment fields | hash utilities |
| Answer budget | `src/lib/budget.js` | Candidate explanation JSON | Budget acceptance or rejection | verifier |
| Expression verifier | `src/lib/expression_tree_verifier.js` | Candidate tree, current challenge, context | Pass/fail result and reason | budget, challenge behavior evaluator |
| Fragment registry | `src/lib/fragment_registry.js` | Fragment proposals, activation/quarantine actions | Registry state, roots, downloadable package | hash utilities, storage |
| Private Vault | `src/lib/private_vault.js` | Private generated material | Internal storage, public-state sanitization | filesystem, hash utilities |
| Chain state | `src/lib/base1_state.js`, `src/lib/chain.js` | Valid solve, transfer, fragment action, block input | New state, block, events, balances | verifier, storage, wallet |
| Storage | `src/lib/sharded_chain_storage.js` | Blocks, headers, snapshots, indexes | Persisted chain data | filesystem, hash utilities |
| Wallet core | `src/lib/wallet.js`, `public/wallet_crypto.mjs` | Key material, signing payloads, transfer data | Address, signatures, balance operations | Ed25519, BIP-39 |
| Wallet extension | `extension/` | User password, mnemonic/private key, site requests | Encrypted vault, approvals, signatures | browser extension APIs |
| Network | `src/lib/p2p_network.js` | Peer heads, blocks, candidates | Propagated messages and sync state | chain state, security |
| Security guards | `src/lib/mainnet_security.js` | Requests, messages, payload sizes, peer activity | Allow/deny/cooldown decisions | config constants |
| CLI | `cli/mazex.js` | Local operator commands | Node start, health, chain checks, wallet creation, config display, packaging | server, chain state, wallet, config |
| Tools | `tools/` | Local scripts and fixtures | Samples, stress reports, packages | project modules |

## 2. Dependency Rule

Core protocol logic must live under `src/lib/`. UI files may call APIs and render state, but must not contain chain validity rules.

```text
UI -> HTTP API -> protocol modules -> storage
Wallet extension -> site bridge -> signed payload -> HTTP API
Network -> received data -> protocol validation -> chain state
```

## 3. Refactor Rule

`src/lib/base1_state.js` is currently the largest state module. Future refactors should split it only after tests and status documents are updated. No refactor may change state transition semantics without a migration note.
