# MazeXChain Project Status

Last updated: 2026-05-11

Baseline Git commit at creation: `ade91b4`

## 1. Status Labels

```text
Not Started    no implementation or only rough discussion
Designed       documented design exists
Implemented    code exists
Tested         automated or scripted test exists
Packaged       distributable artifact exists
Blocked        known unresolved blocker
```

## 2. Current Project Snapshot

MazeXChain currently has a working local Base1 challenge-behavior chain kernel, browser UI, native wallet extension, deterministic verification path, local chain state, sharded storage, fragment registry, P2P prototypes, security guards, packaging scripts, whitepaper pages, and stress/smoke tools.

The project is not yet a fully released public mainnet. It still needs stronger project organization, formal tests, block explorer, independent wallet distribution, hardened public deployment, and longer multi-node operation.

## 3. Module Status Table

| Area | Status | Main Files | Notes |
| --- | --- | --- | --- |
| Project constitution | Implemented | `PROJECT_SCOPE.md`, `PROJECT_STATUS.md` | Control layer for future work. |
| Persistent project context | Implemented | `PROJECT_CONTEXT.md` | Handoff memory for future AI sessions and context compression recovery. |
| Reading dependency rules | Implemented | `PROJECT_READING_RULES.md` | Mandatory reading routes before editing project areas. |
| Protocol vocabulary | Implemented | `docs/protocol-vocabulary.md` | Canonical terminology for cognitive advancement, challenge behavior, Solve Blocks, cognitive state, MAZEX resources, and legacy term mapping. |
| Website information architecture | Implemented | `docs/website-information-architecture.md`, `public/index.html`, `public/console.html`, `public/*.html` | Homepage is now a protocol entry page with sticky grouped Mega Menu navigation, Console is the operational solving workspace, and child pages have page-specific visual explainers. |
| README entry | Implemented | `README.md` | Needs periodic updates when status changes. |
| Architecture docs | Implemented | `docs/architecture.md`, `docs/modules.md`, `docs/data-flow.md`, `docs/security.md`, `docs/api-design.md`, `docs/deployment.md` | Stable English engineering summaries now exist. |
| Whitepaper | Implemented | `public/whitepaper.html`, `public/whitepaper.zh.html`, PDFs | Content exists; may still need final publication polish. |
| Web UI | Implemented / Needs visual iteration | `public/index.html`, `public/console.html`, `public/app.js`, `public/styles.css`, `public/*.html` | Public homepage, Console, Protocol, Downloads, Wallet, Node, Explorer, and Docs pages are separated; the public header now uses sticky grouped Mega Menu navigation; child pages now include reference-mapped visual objects instead of repeated text-only cards; the public shell now has unified neutral surfaces, transparent-by-default hover cards, stronger visual rhythm, and light motion rules. Future work can refine custom illustration assets, live data widgets, and explorer depth. |
| Base1 algorithm | Implemented / Tested | `src/lib/base1_algorithm.js`, `tools/sample_base1_algorithm.js` | Active challenge generation line. |
| Difficulty system | Implemented / Sample-tested | `src/lib/difficulty.js`, difficulty docs | Scoring and grid growth exist; ongoing tuning expected. |
| Static parameters | Implemented | `src/lib/parameter_extractors.js`, `src/lib/parameter_selectors.js`, `src/lib/parameter_injector.js` | Used by Base1. |
| Dynamic parameters | Implemented | `src/lib/dynamic_context.js`, `src/lib/dynamic_parameter_extractors.js`, `src/lib/dynamic_parameter_injector.js` | Needs more long-range adversarial testing later. |
| Operator / combiner selection | Implemented | `src/lib/formula_selectors.js`, `src/lib/combiner_selectors.js` | Active in generation flow. |
| Behavior commitment | Implemented | `src/lib/behavior_commitment.js` | Behavior root commitment exists. |
| Answer budget | Implemented | `src/lib/budget.js` | Prevents unbounded answer payloads. |
| Expression verifier | Implemented / Tested | `src/lib/expression_tree_verifier.js`, sample scripts | Current verification path. |
| Fragment registry | Implemented | `src/lib/fragment_registry.js` | Registration, activation, quarantine concepts exist. |
| Fragment protocol docs | Designed | `MazeX_全网加密碎片协议设计.md`, `MazeX_碎片注册账本协议.md` | Needs future deeper formalization if public fragment governance expands. |
| Private Vault / secrecy | Implemented / Sample-tested | `src/lib/private_vault.js`, `MazeX_保密清洗与私密Vault设计.md` | Public-state cleaning exists. |
| Local chain state machine | Implemented / Smoke-tested | `src/lib/base1_state.js`, `src/lib/chain.js` | Large file; future refactor into modules recommended. |
| Solve Blocks | Implemented | `src/lib/base1_state.js` | Correct answer triggers state progression. |
| Reward and fee settlement | Implemented / Smoke-tested | `src/lib/base1_state.js`, `MazeX_奖励与动态提交费曲线设计.md` | Submit fee deducted from reward and burned. |
| Account balances and transfers | Implemented / Sample-tested | `src/lib/wallet.js`, `tools/sample_base1_transfer.js` | Native transfer path exists. |
| Wallet extension | Implemented / Packaged | `extension/`, `public/downloads/mazexchain-wallet-extension.zip` | Register, phrase verification, login, signing approval exist. |
| Signature confirmation | Implemented | `extension/confirm.*`, `extension/background.mjs` | Every site-requested signing requires approval. |
| Website wallet bridge | Implemented | `public/app.js`, `extension/content_script.js`, `extension/inpage.js` | Connects web page to extension. |
| Latest-head preflight | Implemented / Sample-tested | `tools/sample_submit_preflight.js`, `src/lib/base1_state.js` | Must remain required before submission. |
| UTC time ordering | Designed / Partly implemented | `MazeX_UTC时间校准与提交排序设计.md`, related state code | Needs future multi-node validation. |
| P2P network | Implemented prototype / Tested locally | `src/lib/p2p_network.js`, `tools/sample_p2p_network.js`, `tools/stress_two_copies_p2p.js` | Not yet a mature public gossip network. |
| Priority relay | Designed / Sample-tested | `tools/sample_priority_relay.js`, docs | Propagation optimization, not validity source. |
| Network safety | Implemented prototype / Sample-tested | `src/lib/mainnet_security.js`, `tools/sample_network_safety.js` | Needs mainnet-grade hardening. |
| API security | Implemented prototype / Sample-tested | `src/lib/mainnet_security.js`, `tools/sample_api_security.js` | Continue hardening before public exposure. |
| Sharded storage | Implemented / Sample-tested | `src/lib/sharded_chain_storage.js`, `tools/sample_sharded_storage.js` | Reduces large JSON rewrite risk. |
| Crash-safe storage | Sample-tested | `tools/sample_crash_safe_storage.js` | Needs production integration review. |
| State replay | Implemented / Sample-tested | `tools/sample_state_replay.js` | Full replay / snapshot-assisted path exists conceptually. |
| Public deployment record | Designed / Recorded | `MazeX_公网部署记录.md` | Public server work exists but should be gated. |
| Download packages | Implemented / Packaged | `public/downloads/`, `tools/package_downloads.ps1` | Wallet, node program, chain data, and whitepaper PDF packages exist. |
| Block explorer | Not Started | planned | User previously deferred. |
| Independent wallet app | Not Started | planned | Browser extension exists; standalone app not built. |
| CLI tools | Implemented / Tested | `cli/mazex.js`, `cli/README.md` | Node start, health, chain status, verification, replay, wallet creation, balance, config, and packaging commands exist. |
| Docker deployment | Implemented | `docker/Dockerfile`, `docker/docker-compose.yml`, `docker/README.md` | Reproducible local node deployment exists; production image hardening remains future work. |
| Formal test tree | Implemented | `tests/`, `tests/manifest.json`, `tests/run.js` | Existing `tools/` checks are classified into formal suites. |
| Config directory | Implemented / Tested | `config/*.json`, `src/lib/config.js`, `tools/sample_runtime_config.js` | Core app, chain, wallet, network, security, and genesis defaults load through runtime config. |
| Genesis directory | Implemented / Tested | `genesis/*.json`, `genesis/README.md`, `src/lib/config.js` | Genesis state, initial accounts, and initial fragments are loadable by runtime config; placeholder public commitments remain launch-time values. |
| Roadmap | Implemented | `ROADMAP.md` | Current engineering sequence is now recorded outside chat context. |
| Ops runbooks | Not Started | planned `ops/` | Monitoring, backup, upgrade, incident response missing. |
| Changelog | Implemented | `CHANGELOG.md` | Must be updated after meaningful changes. |

## 4. Immediate Structural Gaps

These are the highest-priority project-organization gaps:

```text
1. Create ops/ runbooks for backup, upgrade, monitoring, and incident response.
2. Add block explorer after core project skeleton is organized.
3. Harden public deployment and P2P networking after local operations are documented.
```

## 5. Next Recommended Work Order

```text
1. Add ops/ monitoring, backup, upgrade, and incident-response runbooks.
2. Refactor oversized state machine modules only after status and tests are stable.
3. Build block explorer after core project skeleton is organized.
4. Harden public deployment and P2P network after local structure is complete.
```

## 6. Do-Not-Forget Notes

```text
Sampling is free.
Submit fee is deducted only after successful solve reward.
Invalid local answers must not broadcast.
Layer / Step must advance sequentially.
Current Step is generated only from current chain state and chained randomness.
Future Step material must not be pre-generated and exposed.
The active wallet direction is native MazeXChain extension wallet.
MetaMask is external identity only until an explicit EVM-compatible bridge exists.
The public UI can be Chinese locally, but production-facing server pages and code comments should be English unless explicitly changed.
Server upload requires explicit user approval.
```

## 7. Verification Commands

Use these before committing meaningful changes:

```powershell
node --check src/server.js
npm run smoke
npm test
npm run package:downloads
```

For project-control file 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
```

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 broader protocol checks:

```powershell
npm run stress:base1
npm run stress:brutal
npm run stress:attack-sim
```
