# MazeXChain Architecture

## 1. Purpose

MazeXChain is a native cognitive advancement protocol and Proof-of-Understanding chain. Its state advances when a solver submits a bounded candidate model that reproduces the current challenge behavior under deterministic protocol rules.

The active architecture is the Base1 protocol line:

```text
chain head
  -> current Layer / Step
  -> chained randomness
  -> fragment registry commitment
  -> operator and parameter generation
  -> behavior commitment
  -> observation interface
  -> bounded candidate explanation
  -> deterministic verification
  -> Solve Block
  -> reward and fee settlement
  -> next Step commitment
```

## 2. Architectural Layers

| Layer | Responsibility | Public Surface |
| --- | --- | --- |
| Web interface | Shows the current challenge, sampling grid, wallet connection, commitments, submissions, downloads, and whitepaper pages. | `public/` |
| Wallet interface | Creates/imports native MazeXChain accounts, encrypts local vaults, approves signatures, and exposes a site bridge. | `extension/`, `public/wallet_crypto.mjs` |
| HTTP API | Serves current state, sampling, submission, chain sync, fragment registry, transfer, and node endpoints. | `src/server.js` |
| Runtime configuration | Loads app, chain, wallet, network, security, and genesis defaults with environment overrides. | `src/lib/config.js`, `config/`, `genesis/` |
| Challenge behavior kernel | Generates current Step behavior from chain-derived material, operators, static parameters, dynamic parameters, and fragment commitments. | `src/lib/base1_algorithm.js` |
| Verification kernel | Checks candidate explanations against budget, schema, context, and behavior equivalence. | `src/lib/expression_tree_verifier.js`, `src/lib/budget.js` |
| Chain state | Applies valid solves, emits Solve Blocks, settles rewards and fees, and derives the next Step. | `src/lib/base1_state.js`, `src/lib/chain.js` |
| Storage | Persists blocks, headers, indexes, snapshots, and runtime state without rewriting one large chain file. | `src/lib/sharded_chain_storage.js`, `data/` |
| Network | Propagates heads, blocks, and candidates. Network propagation never replaces protocol verification. | `src/lib/p2p_network.js` |
| Security boundary | Limits public exposure, cleans private material, and applies API/network safety guards. | `src/lib/private_vault.js`, `src/lib/mainnet_security.js` |

## 3. Core Invariants

```text
1. Layer and Step advance sequentially.
2. A Step is solved only by a valid, bounded, wallet-signed candidate explanation.
3. Sampling is free and does not advance chain state.
4. Failed local answers do not broadcast and do not enter chain state.
5. Successful submit fees are deducted from the solve reward and burned.
6. Future Step material is not pre-generated into public state.
7. Public commitments may expose hashes and roots, not private generator material.
8. Wallet private keys and mnemonic phrases stay client-side.
9. Network messages are propagation data, not validity authority.
10. The chain remains replayable from blocks and verifiable snapshots.
```

## 4. Active Runtime Boundary

The active runtime path is `Base1`.

Historical formula-library experiments, narrative challenge prototypes, and early allocation demos are retained as research material. They must not be treated as the active protocol unless a migration document explicitly promotes them.

## 5. Future Main-Chain Boundary

The current project has a working local chain kernel and prototype P2P path. A mature public chain still needs formal test structure, reproducible node deployment, long-running multi-node validation, block explorer, public wallet distribution, and operations runbooks.
