# PLAI Tokenomics v0.1

## Status

This document defines the first internal tokenomics model for AISFOR-CHAIN. AISFOR-CHAIN remains the development name; PLAI Chain is the public display brand candidate. It is a design and simulation document, not a public coin issuance document.

## Naming

- Chain development name: AISFOR Chain
- Service brand: PLAI
- PLAI meaning: Platform Life AI
- Public display chain name: PLAI Chain
- Initial reward unit: PLAI Point
- Public display coin name: PLAI Coin
- Public display symbol: PLAI
- Final coin name: to be reviewed before public mainnet

Token and coin names must not be hardcoded in business logic. They must be read from configuration so the final public name can be changed before mainnet.

## Supply

- Candidate maximum supply: 10,000,000,000 PLAI
- Internal point supply: simulation only
- Testnet token supply: resettable and has no monetary value
- Mainnet supply: must be confirmed after technical, legal, security, and operational review

## Operating Sequence

1. Internal point
2. Testnet token
3. Mainnet coin

## Reward Model

AISFOR-CHAIN uses PoSS: Proof of Service & Storage.

PoSS rewards useful ecosystem contribution instead of wasteful computation.

## Reward Categories

- Service usage
- Content creation and content feature usage
- Storage capacity opened by users or nodes
- Actual data stored and retained
- Node uptime
- File custody verification
- Shopping purchase and sale activity
- AISTALK emoticon pack creation and sale
- Ecosystem participation

## Initial Reward Score Formula

The first simulation formula is:

```text
rewardScore =
  serviceScore
  + contentScore
  + storageScore
  + uptimeScore
  + verificationScore
  + commerceScore
  + emoticonScore
  + ecosystemScore
```

The reward engine must start in simulation mode. Simulation entries do not represent public coin issuance.

## Abuse Controls

- Daily reward cap
- Per-user reward cap
- Per-category reward cap
- Self-trading detection
- Refund and cancellation exclusion
- Repeated same-party commerce limits
- Emoticon fake sale detection
- Storage proof challenge verification
- Suspicious activity flagging
- Delayed reward settlement

## v0.1 Implementation Scope

- Add tokenomics configuration.
- Add reward simulation ledger.
- Add admin summary for reward simulation.
- Keep all rewards as simulation entries until testnet token policy is approved.

## 2026-07-01 Supply Alignment

- Existing mock wallet coin configuration used 1,000,000,000 AIS under the development display.
- Tokenomics v0.1 target maximum supply is 10,000,000,000 PLAI under the public display.
- `coinConfig` now reads supply, symbol, decimals, and display name from tokenomics configuration.
- The foundation treasury was adjusted with a `SUPPLY_POLICY_ADJUSTMENT` mock ledger transaction.
- Current wallet accounting target:
  - Total supply: 10,000,000,000 PLAI
  - Circulating supply: 166 PLAI
  - Foundation treasury: 9,999,999,834 PLAI
  - Total wallet balance: 10,000,000,000 PLAI

## 2026-07-01 Reward Policy Admin

- Added reward policy definitions for service, content, storage, uptime, verification, commerce, emoticon, and ecosystem categories.
- Added `/admin/rewards` as the dedicated PoSS reward simulation management page.
- `/admin/rewards` shows tokenomics status, category policies, category totals, top actors, and latest reward ledger entries.
- The page can create policy-based simulation entries without issuing public coins.
- `/admin` now links to `/admin/rewards` from the top navigation.

## 2026-07-01 AISFOR Point Mirror

- AISFOR already has an internal `PointLedger` for app activity and distributed storage contribution.
- AISFOR-CHAIN now exposes authenticated `/api/reward` for PoSS reward ledger writes.
- New AISFOR point events are mirrored into AISFOR-CHAIN reward ledger entries with an idempotency key.
- The mirror does not create an extra AISFOR point. It only records the same point event as a chain-side simulated reward proof.
- Existing bundle proof anchoring remains separate and can continue to submit batched point proof ranges.

## 2026-07-01 Reward Source Readiness

- Added chain-side source readiness definitions for AISFOR, AISTALK, AISMALL, AISGROUP, and AISFOR_CHAIN.
- `/api/reward/sources` exposes the allowed service categories, event types, endpoint, and idempotency key pattern.
- `/admin/rewards` now shows which services are connected and which services are ready for client-side integration.
- AISFOR is connected through PointLedger mirroring. AISTALK, AISMALL, and AISGROUP remain ready-for-integration until their own service code explicitly submits events.

## 2026-07-01 Testnet Policy

- Added `docs/TESTNET_POLICY.md` as the controlled PLAI Chain testnet policy.
- The policy confirms that PLAI Point, PLAI testnet token rehearsal, and PLAI Coin mainnet review are separate phases.
- Testnet balances are resettable, non-monetary, and not public issuance, withdrawal, exchange, or investment value.
- `/admin/rewards` now includes a Testnet Policy Readiness panel using the chain-side testnet status service.
- The panel surfaces network id, chain display name, symbol, issuance guardrail, validator count, genesis preview hash, and readiness checks.

## 2026-07-01 Mainnet Policy Draft

- Added `docs/MAINNET_POLICY_DRAFT.md` as the first PLAI mainnet decision draft.
- The draft locks public mainnet issuance, exchange listing, external withdrawal, and point conversion until separate approval.
- It defines candidate supply, conversion language, reward abuse controls, validator requirements, wallet requirements, commerce requirements, and launch gates.
- Testnet operation, PLAI Point, and testnet PLAI remain evidence and rehearsal only, not guaranteed future allocation.

## 2026-07-01 Reward Source Validation

- `/api/reward` now validates submitted source service, category, action type, and idempotency key prefix against the source readiness policy.
- Unknown sources, disallowed categories, and idempotency prefix mismatches are recorded as Reward Ledger flags.
- Unlisted event types and ready-but-not-connected sources are recorded as review warnings while rewards remain in simulation mode.
- Validation details are stored in reward entry metadata and shown on `/admin/rewards`.

## 2026-07-01 Explorer Reward Visibility

- `/explorer` now includes a Recent Reward Ledger section.
- `/explorer/reward/:rewardId` shows reward amount, source service, action type, validation status, references, and score breakdown.
- Explorer search can resolve reward id, `refId`, idempotency key, external event key, and external proof hash.
- This gives PoSS reward events the same traceability path as wallet transactions, chain transactions, blocks, and proofs.

## 2026-07-01 Reward Block Anchoring

- Reward Ledger entries can now be included in mock chain blocks alongside proofs and transactions.
- `ChainBlock` supports `rewardIds` and `rewardHashes` without changing historical block hashes.
- Mining assigns `blockId`, `blockHeight`, `blockHash`, and `minedAt` to reward entries.
- `/explorer/reward/:rewardId` links to the containing block, and block detail pages list reward entries in the block.
- The first anchored reward was included in block #41 during the simulation phase.

## 2026-07-01 Reward API Audit

- `/api/reward` now records an audit log for accepted reward submissions.
- Each audit row stores source service, category, action type, actor, idempotency key, request hash, validation result, service identity, and linked reward id.
- `/api/reward/audit` exposes the audit log for operational inspection.
- `/admin/rewards` now shows audit log count and recent audit entries.
- Existing Reward Ledger history was backfilled with an audit row so operators can verify the view immediately.
- Explorer can now search and open reward audit rows by audit id, request hash, idempotency key, ref id, or linked reward id.
- `/explorer/reward-audit/:auditId` shows request hash, validation, service identity, reward link, and simulated reward result.

## 2026-07-01 Reward Cap Gate

- Reward calculation now applies daily user and category caps from tokenomics configuration.
- When a reward would exceed the configured cap, only the remaining allowed amount is recorded.
- Cap decisions are stored in reward metadata as `capReview`.
- Cap application adds `DAILY_USER_CAP_APPLIED` or `DAILY_CATEGORY_CAP_APPLIED` flags for review.
- `/admin/rewards` and reward detail pages show requested vs applied reward amounts.

## 2026-07-01 Reward Review Queue

- Reward entries with flags, failed source validation, or cap-applied amounts are collected into a review queue.
- `/api/reward/review` exposes the current queue for operational checks.
- `/admin/rewards` now shows review count, cap-applied count, and the latest review entries.
- Review entries include source service, action type, actor, category, flags, validation result, and cap review.

## 2026-07-01 Reward Review Decisions

- Operators can record review decisions for reward entries as `APPROVE`, `WATCH`, or `REJECT`.
- Review decisions are stored separately in `rewardReviewDecisions` while the original reward ledger entry remains auditable.
- `/api/reward/review-decisions` exposes decision history.
- `/admin/rewards` shows decision count and recent review decisions.
- Explorer exposes review decisions through `/explorer/reward-review/:decisionId` and links them from reward and audit detail pages.
- Review decision records include reward id, decision, reviewer, note, prior reward amount, and the reward flags at review time.
- `APPROVE` and `REJECT` resolve a reward review and remove it from the pending review queue; `WATCH` keeps it visible for continued monitoring.
- Each new review decision writes a `REWARD_REVIEW_DECISION` chain transaction so the operator decision can be traced by tx hash and later ledger block references.
- The review-decision transaction is auto-mined with reason `reward-review-decision`, giving new decisions an immediate ledger block anchor when block mining succeeds.
- Transaction detail pages now detect `REWARD_REVIEW_DECISION` metadata and link back to the review decision, reward ledger, audit log, and ledger block anchor.
- Block detail pages show reward-review traces for `REWARD_REVIEW_DECISION` transactions, including direct review, reward, and audit links.
- Reward review stats now include chain tx count, ledger anchored count, pending anchor count, and missing review tx count for operator monitoring.
- Operators can run review anchor repair from `/admin/rewards` or `POST /api/reward/review-decisions/repair-anchors` to recreate missing review tx records and retry ledger anchoring.
- `/api/reward/readiness` and `/admin/rewards` now expose reward operations readiness across source policy, ledger, audit, review queue, review anchors, and block engine checks.

## 2026-07-01 Reward Integration Manifest

- `/api/reward/manifest` exposes the service integration contract for PoSS reward submissions.
- The manifest includes required fields, recommended fields, source service policies, idempotency key formats, guardrails, and sample payloads.
- `/admin/rewards` now shows the same manifest so operators can verify how AISFOR, AISTALK, AISMALL, AISGROUP, and AISFOR_CHAIN should submit reward events.
- This keeps actual service wiring separate from chain policy while making the expected request shape auditable before public testnet work.

## 2026-07-01 Reward Integration Manifest Check

- `scripts/reward-integration-manifest-check.js` validates every sample payload published by the reward integration manifest.
- `/api/reward/readiness` and `/admin/rewards` now include a manifest sample check so integration contract drift is visible before external services submit events.
- The check fails only on policy-breaking flags; warnings remain visible for ready-but-not-yet-connected services during simulation.

## 2026-07-01 Reward Service Auth Readiness

- `scripts/reward-service-auth-check.js` reports which reward source services have configured chain API credentials.
- Reward readiness now includes `service_auth_configuration`, showing whether AISFOR, AISTALK, AISMALL, and AISGROUP keys are prepared.
- `/admin/rewards` displays each source service auth env key and whether that key is currently configured.
- This keeps credential readiness visible before external services are allowed to submit PoSS reward events.

## 2026-07-01 Reward Dry-run Submission

- Authenticated services can call `POST /api/reward/dry-run` to validate and score a reward payload without writing to the Reward Ledger.
- Dry-run responses include policy validation, duplicate detection, score breakdown, cap review, final simulated reward amount, and whether the event would need review.
- `scripts/reward-dry-run-manifest-check.js` runs dry-run scoring against all manifest sample payloads.
- Reward readiness and `/admin/rewards` now include dry-run sample checks before external services submit live reward events.

## 2026-07-01 Reward Client Helper

- `lib/rewardIntegrationClient.js` provides HMAC v2 header creation and reward payload submission helpers for service integrations.
- `scripts/reward-client-dry-run-example.js` calls the dry-run or live simulation endpoint with a manifest sample payload and configured service credential.
- `docs/REWARD_SERVICE_INTEGRATION.md` documents the service integration path, required fields, authentication headers, dry-run flow, and guardrails.
- `/api/reward/manifest` and `/admin/rewards` now surface the auth mode and helper path so service teams can wire events consistently.

## 2026-07-01 Reward HTTP Dry-run Smoke

- `scripts/reward-http-dry-run-smoke.js` runs authenticated HTTP dry-run checks for every configured external reward source service.
- The smoke result is written to `data/reward-http-dry-run-smoke.json`.
- Reward readiness and `/admin/rewards` now show the latest HTTP dry-run smoke result so operators can verify that service credentials, signatures, routing, and dry-run scoring all work together.

## 2026-07-01 Reward Service Rollout Status

- Reward readiness now derives a per-service rollout plan from source policy, auth readiness, and the latest HTTP dry-run smoke result.
- `/admin/rewards` shows each external service as `CONNECTED`, `READY_FOR_LIVE_SIMULATION`, or `WAITING_FOR_SERVICE_WIRING`.
- `scripts/reward-rollout-status.js` prints the same rollout plan for operators before wiring real service events.
- This keeps AISTALK, AISMALL, and AISGROUP integration steps visible without changing their application code in the chain repository.

## 2026-07-01 Reward Live Canary Gate

- `scripts/reward-live-canary.js` rehearses a service reward write through dry-run by default.
- The same script performs an actual live simulation write only when `--confirm=LIVE_SIMULATION_WRITE` is supplied.
- Canary results are written to `data/reward-live-canary.json` and shown on `/admin/rewards`.
- This creates an explicit operator gate between HTTP dry-run readiness and Reward Ledger writes.
- `scripts/reward-live-canary-preflight.js` checks readiness, HTTP dry-run smoke, dry-run canary, and rollout availability before operators run the live simulation canary.
- `scripts/reward-live-canary-postcheck.js` verifies that dry-run canaries did not write reward/audit rows and that future live canaries create linked reward and audit rows.
- `scripts/reward-live-canary-permit.js` converts readiness, preflight, post-check, and rollout target state into an explicit execution permit. It reports `PERMITTED` only when a single controlled live simulation canary can be run after operator approval.
- `/admin/rewards` can record or revoke operator approval for the permitted live canary. The approval stores the permit id, service name, and command, but it does not execute the live simulation write.
- `scripts/reward-live-canary-approved-run.js` is the final execution wrapper. It refuses to run unless approval is recorded, the approval still matches the current permit, and `--confirm=LIVE_SIMULATION_WRITE` is supplied. It runs post-check immediately after the canary.

## 2026-07-01 Service Reward Wiring

- AISTALK now submits reward events from real chat and sticker store activity paths.
- AISGROUP now submits reward events from group event-record creation and comment activity paths.
- AISMALL now submits reward events from order creation and seller payment-confirmation paths.
- External service reward clients default to dry-run submission and require service credentials; per-service live simulation flags can enable controlled writes later.
- Chain source rollout status marks AISTALK, AISGROUP, and AISMALL as connected while settlement remains simulation-only.

## Safety Statement

PLAI is currently an internal point and testnet-token design candidate. It must not be promoted as a public cryptocurrency, investment product, guaranteed reward, or exchange-tradable asset at this stage.
