# AISFOR Global Chain Plan

AISFOR-CHAIN should grow in layers. The first global-ready layer is not a coin. It is authenticated proof anchoring.

The living whitepaper is maintained at `docs/WHITEPAPER.md`.
When a protocol feature changes, the whitepaper should be updated in the same work cycle.

## Layer 1: Trusted Proof Gateway

- AISFOR remains the identity master.
- AISFOR-CHAIN accepts proofs only from registered services.
- Registered services are `AISFOR`, `AISTALK`, `AISGROUP`, and `AISMALL`.
- Service requests use `X-AISFOR-SERVICE` plus either `X-AISFOR-API-KEY` or `X-AISFOR-SIGNATURE`.
- HMAC v2 signed requests add `X-AISFOR-TIMESTAMP` and `X-AISFOR-NONCE` to reduce replay risk during service integration.
- AISFOR, AISTALK, AISGROUP, and AISMALL clients now generate HMAC v2 headers when service keys are configured.
- AISFOR-CHAIN is now running with `AISFOR_CHAIN_AUTH_REQUIRED=1`; unsigned proof writes are rejected.

## Layer 2: AISFOR Bundle Anchor

AISFOR already builds internal proof chains and `BlockchainProofBundle` rows. The first real integration should send those bundles to AISFOR-CHAIN as `BLOCKCHAIN_PROOF_BUNDLE`.

Status: initial client hook is implemented in AISFOR.

- `E:\aisfor\services\aisforChainClient.js`
- `POST /admin/blockchain/bundles/:id/submit-chain`
- target AISFOR-CHAIN endpoint: `POST /api/proof`

## Layer 3: Service Activity Proofs

After AISFOR bundle anchoring is stable:

- AISTALK sends message/activity proofs. Initial `MESSAGE_CREATED` hook is implemented.
- AISGROUP sends group/collaboration proofs. Initial `GROUP_ACTIVITY` event-record hook is implemented.
- AISMALL sends commerce/order/review proofs. Initial `MALL_ACTIVITY` order-created hook is implemented.

## Layer 4: Persistent Ledger

Status: file-backed persistence is live, and MongoDB migration staging is verified.

- Ledger file: `D:\aisfor-chain\data\ledger.json`
- Stored rows: proofs, mock chain transactions, point entries
- PM2 restarts preserve the mock ledger
- Every proof remains idempotent by `sourceService + idempotencyKey`
- MongoDB staging backfill has matched 212 / 212 JSON ledger documents with 0 failed collections
- MongoDB observation dual-write is enabled for observation collections and currently matches 212 / 212 with 0 failed collections; the short window runner reached 6 consecutive OK samples

Next persistence step: run a longer observation window across real service writes, then require manual approval before any live DB read switch.

## Layer 5: Mock Block Chain

Status: initial block sealing is implemented.

- Blocks contain `height`, `previousHash`, `merkleRoot`, and `blockHash`
- Pending proofs can be mined with `POST /api/block/mine`
- Auto-mining seals a block when pending proofs reach `AISFOR_CHAIN_AUTO_MINE_SIZE`
- Chain verification is available at `GET /api/block/verify`
- Node economy transactions are sealed into blocks as standalone mock chain transactions

## Layer 6: Node Economy And Mock Finality

Status: initial node economy and validator finality are implemented.

- Node participants can lock pledge points, receive rewards, and receive slashes
- Each economy event creates a node economy ledger row and mock chain transaction
- Eligible validators are active or warning nodes with enough locked pledge
- Blocks can be assigned validators, receive approve/reject votes, and become `FINALIZED_MOCK`
- Approving validators receive a mock validator reward

Useful endpoints:

- `GET /api/node/economy/stats`
- `GET /api/block/validators/eligible`
- `POST /api/block/:blockId/assign-validators`
- `POST /api/block/:blockId/vote`
- `POST /api/block/:blockId/mock-finalize`

## Layer 7: Chain Confirmation Callbacks

Status: initial callback ledger is implemented.

- `FINALIZED_MOCK` blocks create callback events for included proofs
- Services can configure callback URLs with `AISFOR_CHAIN_CALLBACK_*`
- If no callback URL is configured, the event is stored as `MOCK_DELIVERED`
- Callback events are visible in `/admin` and available at `GET /api/callback`

Callback receiver status:

- AISFOR: initial `BlockchainProofBundle` confirmation receiver is implemented at `/internal/aisfor-chain/callback`
- AISTALK: initial `ChatMessage` confirmation receiver is implemented at `/internal/aisfor-chain/callback`
- AISGROUP: initial `EventRecord` confirmation receiver is implemented at `/internal/aisfor-chain/callback`
- AISMALL: initial `Order` confirmation receiver is implemented at `/internal/aisfor-chain/callback`

End-to-end callback status: passed across AISFOR, AISTALK, AISGROUP, and AISMALL with newly created test records.

Service-side admin chain status views are now available for callback/proof visibility: AISTALK `/admin/chain-status`, AISGROUP `/master/chain-status`, and AISMALL `/admin/chain-status`.

## Layer 8: Real Mainnet Preparation

Only after proof contracts, auth, persistence, bundle anchoring, and service integrations are stable should a real mainnet or token layer be designed.

No real coin issuance is included in the current stage.












