# MazeXChain Proof-of-Understanding Kernel

## Project Control Documents

Before changing architecture, protocol, wallet, chain state, networking, storage, deployment, or public documentation, read:

```text
PROJECT_SCOPE.md
PROJECT_STATUS.md
PROJECT_CONTEXT.md
PROJECT_READING_RULES.md
```

`PROJECT_SCOPE.md` is the project constitution. It defines the active protocol line, hard boundaries, deprecated directions, security rules, wallet boundaries, and update discipline.

`PROJECT_STATUS.md` is the project status ledger. It records completed modules, partially implemented areas, missing main-chain engineering blocks, verification commands, and the recommended next work order.

`PROJECT_CONTEXT.md` is the persistent handoff memory. It records the active product decisions, safety boundaries, current implementation snapshot, user-facing style decisions, and next work order for future AI sessions.

`PROJECT_READING_RULES.md` is the mandatory reading dependency graph. It defines which documents and modules must be read before changing each task area.

`ROADMAP.md` is the current engineering sequence. It records the next structural milestones after each completed block.

MazeXChain is a local cognitive advancement protocol and Proof of Understanding chain implementation. It generates Step challenge behavior from chain-derived randomness, encrypted fragment commitments, operator units, static parameters, dynamic parameters, deterministic verification, and reward-funded state transitions.

```text
Challenge behavior = observation source
Verifier = consensus rule
Solve Block = state transition
```

## Run

```powershell
npm start
```

Open:

```text
http://localhost:3000
```

## Docker Local Node

```powershell
docker compose -f docker/docker-compose.yml up --build
```

The container serves the same HTTP interface on:

```text
http://localhost:3000
```

Runtime chain data is mounted from the host `data/` directory. Configuration and genesis files are mounted read-only from `config/` and `genesis/`.

## Verify

```powershell
npm run smoke
npm test
```

## CLI

```powershell
npm run cli -- help
npm run cli -- node start --port 3000
npm run cli -- node health --url http://localhost:3000
npm run cli -- chain status
npm run cli -- chain verify
npm run cli -- chain replay
npm run cli -- wallet create
npm run cli -- config show
npm run cli -- downloads package
```

The CLI calls the same protocol modules as the HTTP server. It is an operator surface for local nodes, chain checks, wallet creation, runtime config inspection, and download packaging.

## Engineering Control Surface

```text
docs/       stable architecture, module, data-flow, security, API, and deployment notes
docs/protocol-vocabulary.md canonical protocol terminology and legacy term mapping
config/     app, chain, network, consensus, wallet, security, and genesis runtime configuration
genesis/    genesis-state, initial-account, and initial-fragment templates
tests/      formal test suites and runner backed by tools/
CHANGELOG.md project change history
ROADMAP.md current engineering sequence
PROJECT_CONTEXT.md persistent handoff memory
PROJECT_READING_RULES.md mandatory reading routes
docker/ reproducible local-node container definition
```

The files above are the project-control layer for future conversations and future contributors. Core app, chain, wallet, network, security, and genesis defaults are loaded through the runtime config module.

## Core Flow

```text
Wallet and node state
  -> Synced current Layer / Step
  -> Latest-head preflight
  -> Chain-derived seed source
  -> Fragment registry root
  -> Deterministic fragment selection
  -> Fragment generation profile
  -> Fragment-bound seed source
  -> Base-value expression generation
  -> Challenge behavior commitment
  -> Behavior observation interface
  -> Candidate explanation
  -> Answer budget
  -> Deterministic verifier
  -> Network confirmation
  -> Solve Block
  -> Reward and fee settlement
  -> Next Step commitment
```

## Protocol Direction

mazexchain progresses by Layer and Step. A Step can advance only after a valid explanation is submitted, verified, recorded, and used to derive the next challenge seed.

The current algorithm starts from a minimal base value and increases difficulty through operator count, operator type, parameter count, parameter magnitude, dynamic parameters, grid size, behavior budget, and verification strength. Higher layers can reuse lower-layer operators and parameters while unlocking harder dynamic and nonlinear components.

The public runtime path is Base1 only. Older prototype challenge endpoints and snapshot-based adoption paths are not part of the active protocol.

## Main API

```text
GET  /api/health
GET  /api/base1/current
GET  /api/base1/current?sync=1
POST /api/base1/sample
POST /api/base1/sample-batch
POST /api/base1/submit
POST /api/base1/preflight
GET  /api/base1/leaderboard
GET  /api/base1/events
GET  /api/base1/reveals
GET  /api/base1/chain/summary
GET  /api/base1/chain/blocks
GET  /api/base1/chain/blocks-since
POST /api/base1/chain/blocks
GET  /api/base1/chain/verify
GET  /api/base1/chain/replay
GET  /api/base1/fragments
POST /api/base1/fragments/register
POST /api/base1/fragments/upgrade
POST /api/base1/fragments/quarantine
GET  /api/base1/node/head
POST /api/base1/node/head-query
POST /api/base1/node/solve-candidate
POST /api/base1/transfer-signing-payload
POST /api/base1/transfer
POST /api/base1/reset
```

## Project Structure

```text
src/server.js              HTTP API and static frontend server
src/lib/base1_algorithm.js Base-value algorithm
src/lib/budget.js          Answer budget and complexity checks
src/lib/base1_state.js     Local chain state machine, Solve Blocks, fragments, rewards, sync
src/lib/fragment_registry.js Encrypted fragment registration, activation, quarantine, download packages
src/lib/difficulty.js      Difficulty, grid growth, and verification strength engine
src/lib/expression_tree_verifier.js Candidate explanation verifier
src/lib/private_vault.js   Private Step material storage and public-state sanitization
src/lib/sharded_chain_storage.js Block/header/snapshot sharded storage
src/lib/p2p_network.js     TCP P2P head and block propagation
src/lib/mainnet_security.js API limits, request safety, and development-only guards
src/lib/config.js          Runtime configuration and genesis loaders
public/wallet_crypto.mjs   Browser-side native wallet generation, recovery, and Ed25519 signing
src/lib/wallet.js          Local wallet and transfer ledger
public/                    Public web interface and whitepaper
cli/                       Local operator CLI for node, chain, wallet, config, and packaging tasks
docker/                    Local node image and compose deployment
docs/                      Architecture and protocol-control documents
config/                    Runtime configuration templates
genesis/                   Genesis state and initial registry templates
tests/                     Formal test suites and manifest runner
tools/                     Generation, simulation, and stress-test tools
```

## Runtime State

Runtime state is stored under:

```text
data/
```

The storage layer uses sharded block files and snapshots so that long chains do not require rewriting a single large JSON file on every update.

## Verification Model

The verifier does not require the submitted explanation to match the internal challenge construction. It requires behavior equivalence under the active Step rules, context, verification domain, and answer budget.

```text
candidate(A, context) == challenge_behavior(A, context)
```

If an answer exceeds the budget, violates the expression-tree schema, depends on forbidden structures, fails any verification point, or targets an expired Step, it is rejected before it can become chain state.
