# MazeXChain Persistent Project Context

Last updated: 2026-05-09

This file is the persistent handoff context for future AI sessions. It exists because chat context can be summarized or compressed, while repository files and Git history remain durable.

## 1. How Future Sessions Should Start

Before making project-level changes, read these files in order:

```text
PROJECT_CONTEXT.md
PROJECT_SCOPE.md
PROJECT_READING_RULES.md
PROJECT_STATUS.md
README.md
CHANGELOG.md
ROADMAP.md
```

Then read `docs/protocol-vocabulary.md`, and follow `PROJECT_READING_RULES.md` to read the task-specific documents and module files needed for the requested task.

## 2. One-Sentence Definition

MazeXChain is a cognitive advancement protocol for verifiable structural intelligence: solvers observe challenge behavior, submit bounded candidate models, pass deterministic behavior verification, and advance Layer / Step cognitive state through Solve Blocks.

## 3. Active Protocol Line

The active protocol line is `Base1`.

```text
base value
  -> operator units
  -> static numeric parameters
  -> dynamic context parameters
  -> deterministic challenge behavior
  -> behavior commitment
  -> bounded candidate explanation
  -> behavior-equivalence verification
  -> Solve Block
  -> reward and fee settlement
  -> next Step commitment
```

Do not reintroduce older formula-library allocation, narrative theme puzzles, or direct formula-family selection as active runtime behavior unless an explicit migration document is created.

## 4. Product and Protocol Decisions

```text
Sampling is free.
Successful submit fees are deducted from solve rewards and burned.
Invalid local answers must not broadcast.
Layer / Step advances strictly in sequence.
The current Step exists only after the previous Step is solved and committed.
Future Step material must not be pre-generated into public state.
Solvers are judged by behavior equivalence, not by matching hidden internal construction text.
The native MazeXChain wallet extension is the production wallet direction.
MetaMask is external identity only until explicit EVM compatibility exists.
Server uploads require explicit user approval.
Every meaningful change must be committed to Git.
```

## 5. Current Implementation Snapshot

Implemented locally:

```text
Base1 challenge-behavior chain kernel
current web UI
native wallet extension
phrase verification wallet registration
password / phrase / private-key login paths
site-requested signature approval popup
deterministic verifier
answer budget
local chain state machine
Solve Blocks
reward and fee settlement
native account balance and transfer path
fragment registry
private vault public-state cleaning
sharded chain storage
prototype P2P/network path
CLI wrappers for node, chain, wallet, config, and download packaging
download packaging
whitepaper pages
smoke and stress scripts
project-control docs
config and genesis templates
formal tests tree and manifest runner
runtime config loader for app, chain, wallet, network, security, and genesis defaults
Docker local-node deployment
```

Not yet final public-mainnet complete:

```text
ops runbooks
block explorer
standalone wallet app
long-running public multi-node validation
mainnet-grade network hardening
deeper runtime wiring for future config-only protocol migration
```

## 6. Core Files

```text
src/server.js
src/lib/base1_algorithm.js
src/lib/base1_state.js
src/lib/expression_tree_verifier.js
src/lib/budget.js
src/lib/difficulty.js
src/lib/fragment_registry.js
src/lib/private_vault.js
src/lib/sharded_chain_storage.js
src/lib/p2p_network.js
src/lib/mainnet_security.js
src/lib/wallet.js
public/app.js
public/index.html
public/styles.css
public/wallet_crypto.mjs
extension/
docs/
config/
genesis/
docker/
ROADMAP.md
tools/
```

## 7. Safety Boundaries

Public data may include commitments, roots, hashes, public addresses, signatures, block records, state roots, and challenge metadata.

Private data must not be exposed in public APIs, public static files, or logs:

```text
wallet private keys
mnemonic phrases
internal generated expressions
private seed material
fragment selection paths
private vault contents
uncommitted future challenge material
server-only generator internals
```

## 8. User-Facing Style Decisions

```text
Local conversation with the user is Chinese.
Production-facing server pages, code, and comments should be English unless explicitly changed.
The main UI visual direction is clean black and white.
Top header should be minimal and use MAZEX branding.
Wallet UX should resemble a real wallet: landing, register, login, dashboard, settings, connected sites, backup, lock/logout.
Downloaded extension packages must reflect the latest extension build before being shared.
```

## 9. Standard Verification Commands

For normal project changes:

```powershell
node --check src/server.js
npm run smoke
git diff --check
```

For wallet extension changes:

```powershell
node --check extension\popup.mjs
node --check extension\background.mjs
node --check extension\confirm.mjs
npm run package:downloads
```

For config/genesis/template changes:

```powershell
node -e "for (const f of ['config/app.config.json','config/chain.config.json','config/network.config.json','config/consensus.config.json','config/genesis.config.json','config/wallet.config.json','config/security.config.json','genesis/genesis.json','genesis/initial-accounts.json','genesis/initial-fragments.json']) JSON.parse(require('fs').readFileSync(f,'utf8')); console.log('json ok')"
git diff --check
```

## 10. Recommended Next Work Order

```text
1. Keep PROJECT_CONTEXT.md, PROJECT_SCOPE.md, PROJECT_STATUS.md, README.md, and CHANGELOG.md current.
2. Add ops/ monitoring, backup, upgrade, and incident-response runbooks.
3. Build block explorer after the core project skeleton is stable.
4. Harden public deployment and P2P network after local structure is complete.
```

## 11. Context Rule

If a future assistant is unsure whether a requested change belongs to the active protocol, it must prefer the files above over compressed chat memory. If files conflict, use the newest project-control file and update the older file in the same change.
