# MazeXChain API Design

## 1. API Principles

```text
1. APIs expose public protocol state, not private generator material.
2. Invalid local answers must not enter network or chain state.
3. Signed operations must be verified server-side.
4. Development-only endpoints must be guarded before public deployment.
5. Network endpoints propagate data; protocol modules decide validity.
```

## 2. Health and Current State

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/api/health` | Runtime health check. |
| `GET` | `/api/base1/current` | Current Layer, Step, commitments, score, grid, wallet-visible state. |
| `GET` | `/api/base1/current?sync=1` | Current state after sync attempt. |

## 3. Sampling

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/api/base1/sample` | Return one challenge-behavior output `B(u,v)` for input `A(x,y)`. |
| `POST` | `/api/base1/sample-batch` | Return multiple samples for a bounded batch request. |

Sampling is free and does not alter chain state.

## 4. Solve Submission

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/api/base1/preflight` | Check latest head and Step freshness before submission. |
| `POST` | `/api/base1/submit` | Verify a signed candidate explanation and create a Solve Block if valid. |

Submission must enforce answer budget, Layer/Step freshness, wallet signature, deterministic verification, reward settlement, and next Step derivation.

## 5. Chain Data

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/api/base1/chain/summary` | Chain summary and current head. |
| `GET` | `/api/base1/chain/blocks` | Block list or range. |
| `GET` | `/api/base1/chain/blocks-since` | Incremental block sync. |
| `POST` | `/api/base1/chain/blocks` | Receive peer blocks and validate before adoption. |
| `GET` | `/api/base1/chain/verify` | Verify current local chain state. |
| `GET` | `/api/base1/chain/replay` | Replay or validate state reconstruction path. |

## 6. Fragment Registry

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/api/base1/fragments` | List public fragment registry state. |
| `POST` | `/api/base1/fragments/register` | Register a candidate fragment under protocol checks. |
| `POST` | `/api/base1/fragments/upgrade` | Record fragment version or rule upgrade. |
| `POST` | `/api/base1/fragments/quarantine` | Quarantine invalid or deprecated fragment entries. |

## 7. Node and Network

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/api/base1/node/head` | Return local node head. |
| `POST` | `/api/base1/node/head-query` | Query or compare peer heads. |
| `POST` | `/api/base1/node/solve-candidate` | Propagate a solve candidate through the network path. |

## 8. Wallet and Transfer

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/api/base1/transfer-signing-payload` | Build canonical transfer signing payload. |
| `POST` | `/api/base1/transfer` | Verify signature, apply transfer fee, and commit transfer. |

## 9. Development and Reset

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/api/base1/reset` | Reset local development chain state. |

Reset endpoints must be disabled or strongly gated in public deployment.
