PLAI Chain

# 한국어 백서

영문 백서 보기 Chain Home PLAIFOR Home
Mongo Read 운영 단계
이 문서는 영문 백서와 같은 섹션 구성을 가진 한국어판이다. 원문 백서의 내용을 요약하지 않고 운영자가 읽기 쉽게 한국어로 풀어 정리했다.

## 목적

AISFOR-CHAIN은 AISFOR 네트워크를 위한 내부 proof, wallet, settlement ledger 계층이다. 현재 역할은 공개 코인 발행이 아니다. 인증된 서비스 proof, mock chain transaction, wallet transfer, block reference, node-economy event, callback confirmation을 기록하여 AISFOR 서비스들이 공개 mainnet 결정을 내리기 전에 chain-like ledger를 통해 감사될 수 있게 한다.

## 네트워크 서비스

초기 신뢰 서비스는 다음과 같다.

- AISFOR
- AISTALK
- AISGROUP
- AISMALL
- AISFOR_CHAIN

AISFOR는 표준 identity source로 유지된다. AISFOR 사용자 `_id`는 사용자 지갑 매핑을 위한 안정적인 네트워크 계정 식별자로 취급된다.

## 인증 Proof Gateway

AISFOR-CHAIN은 auth-required mode가 활성화되어 있을 때 등록된 서비스에서 온 proof write만 수락한다. 서비스 클라이언트는 API-key auth 또는 HMAC v2 signature를 사용할 수 있다.

HMAC v2 서명 요청은 다음 header를 포함한다.

- `X-AISFOR-SERVICE`
- `X-AISFOR-API-KEY`
- `X-AISFOR-SIGNATURE`
- `X-AISFOR-TIMESTAMP`
- `X-AISFOR-NONCE`

서명 대상에는 service name, timestamp, nonce, HTTP method, path, request body가 포함된다. timestamp skew와 nonce replay check는 서비스 연동 중 우발적 또는 악의적 replay를 줄인다. AISFOR, AISTALK, AISGROUP, AISMALL client는 service key가 설정되어 있을 때 HMAC v2 header를 생성한다. 현재 auth-required deployment에서는 서명되지 않은 proof write가 거부된다.

## Proof Ledger

Proof ledger는 `sourceService + idempotencyKey` 기준의 idempotency로 서비스에서 발생한 event를 기록한다. 초기 proof source에는 AISFOR blockchain proof bundle, AISTALK chat activity, AISGROUP group activity, AISMALL order activity가 포함된다.

수락된 각 proof는 다음과 연결될 수 있다.

- proof ledger row
- mock chain transaction
- sealed block
- service callback confirmation
- address, transaction, block traceability를 위한 explorer view

## 지갑 계층

지갑 계층은 mock ledger 내부의 user wallet과 service wallet을 지원한다. User wallet은 AISFOR user id에서 idempotent하게 생성될 수 있다. Service wallet은 AISFOR, AISTALK, AISGROUP, AISMALL, AISFOR_CHAIN에 예약되어 있다.

현재 지갑 제어 기능은 다음을 포함한다.

- 수신 QR
- 송금 form
- PIN 보호
- 복구 문구 setup, confirmation, restore flow
- 민감한 API response redaction
- wallet transaction to chain transaction anchoring
- wallet transaction ledger block hydration

지갑 transfer는 mining 이후 내부 wallet transaction hash, 연결된 AISFOR-CHAIN transaction hash, ledger block reference를 생성한다.

## Explorer

Explorer는 내부 ledger의 chain-style view를 제공한다.

- `/explorer`
- `/explorer/address/:address`
- `/explorer/tx/:txHash`
- `/explorer/block/:height`
- address, transaction hash, block id 검색
- 연결된 chain transaction을 포함한 wallet transaction detail
- ledger block reference를 포함한 chain transaction detail
- wallet과 transaction history를 포함한 address detail

Explorer는 아직 public-chain explorer가 아니다. Mock chain ledger를 위한 내부 audit surface다.

## 블록과 Mock Finality

Block은 height, previous hash, merkle root, block hash, included ledger reference를 포함한다. Pending proof와 transaction은 mock block으로 seal될 수 있다. Validator assignment, voting, `FINALIZED_MOCK` finality는 public settlement를 주장하지 않으면서 향후 testnet behavior를 시뮬레이션한다.

## Node Economy

Node participant는 pledge point를 lock하고, reward를 받고, slash를 받을 수 있다. Node economy event는 ledger row와 mock chain transaction을 만든다. 이것은 향후 node와 validator 설계를 위한 simulation layer다.

## Chain Confirmation Callback

Finalized mock block은 포함된 proof에 대해 callback event를 생성한다. AISFOR, AISTALK, AISGROUP, AISMALL은 초기 callback receiver를 가진다. 서비스 측 chain status admin view는 proof/callback visibility를 제공한다.

- AISTALK: `/admin/chain-status`
- AISGROUP: `/master/chain-status`
- AISMALL: `/admin/chain-status`

## Ledger Database Migration Readiness

초기 단계에서 live ledger는 `data/ledger.json`을 읽고 썼다. MongoDB는 migration staging과 observation-only dual-write에 사용되었다. 당시 live read는 JSON을 사용했다.

DB migration path는 다음을 포함했다.

- JSON array에서 DB-shaped document로 dry-run mapping
- 결정론적 `_migrationId`와 `_sourceHash`
- rollback snapshot check
- shadow consistency check
- MongoDB connectivity probe
- `migration_staging_*` collection으로 staging-only backfill
- collection count와 source-hash sequence 기준 staging compare
- `/admin/ledger-migration`에서 admin visibility 제공

최신 staging 및 observation run 기준, 212개 ledger document가 0개 failed collection으로 성공적으로 비교되었다. MongoDB observation dual-write는 `observation_*` collection에 대해 활성화되었고, short observation window runner는 6 consecutive OK sample에 도달했다. Technical read-switch preflight는 준비되었지만, live DB read는 manual approval과 실제 service write를 포함한 더 긴 observation window가 완료될 때까지 잠겨 있었다.

## 현재 구현 상태

구현 완료:

- Node.js 및 Express AISFOR-CHAIN server
- proof ledger API
- mock chain transaction API
- file-backed ledger persistence
- mock block sealing
- node participant registry
- node pledge/reward/slash ledger
- point reward simulation
- validator assignment and voting
- mock finality
- chain confirmation callback ledger
- AISFOR, AISTALK, AISGROUP, AISMALL용 HMAC v2 service proof client
- unsigned write rejection을 포함한 auth-required proof submission mode
- AISFOR, AISTALK, AISGROUP, AISMALL용 service callback receiver
- AISFOR, AISTALK, AISGROUP, AISMALL 전체 end-to-end callback test
- admin dashboard
- AISTALK, AISGROUP, AISMALL의 service-side chain status admin view
- receive QR, send form, PIN protection, recovery vault control을 포함한 wallet UI
- 민감 field를 위한 wallet API response redaction
- wallet transfer PIN enforcement
- wallet transaction to chain transaction anchoring
- wallet transaction ledger block hydration
- explorer wallet, address, transaction, block traceability
- ledger migration을 위한 MongoDB staging backfill 및 compare verification
- MongoDB observation dual-write, compare verification, window runner, read-switch preflight gate
- PM2 process registration

진행 중:

- database-backed ledger live writer and read switch
- production-grade replay protection을 위한 persistent nonce store
- real callback delivery를 위한 retry queue

향후:

- testnet deployment
- external node protocol
- production validator rules
- real mainnet adapter
- 기술 및 compliance review 이후에만 token/legal/economic design 진행

## Mainnet 경로

AISFOR-CHAIN은 단계적으로 진화해야 한다.

1. Mock mainnet prototype
2. Internal testnet
3. Service-integrated testnet
4. External validator testnet
5. Mainnet candidate
6. Security, legal, operational readiness 이후에만 Public mainnet

현재 server는 core prototype이다. Mainnet candidate codebase로 계속 성장할 수 있지만, deployment environment는 분리되어 유지되어야 한다.

## 안전성 고지

AISFOR-CHAIN은 현재 mock ledger event와 simulated point reward를 기록한다. 이를 출시된 public blockchain, 발행된 cryptocurrency, 투자 상품으로 표현해서는 안 된다.

향후 coin, token, public mainnet 설계는 technical audit, legal review, security review, operational control을 포함한 별도 milestone으로 다뤄야 한다.

## 최신 Ledger DB Migration Milestone

2026-06-30, MongoDB read backend candidate는 adapter-only readiness에서 live collection parity 단계로 진전되었다.

- `scripts/ledger-mongo-live-backfill.js --confirm-live-backfill`로 confirmed live Mongo backfill이 실행되었다.
- 212개 ledger document가 `_ledgerLiveKind = ledger-json-live-backfill` marker와 함께 live Mongo read candidate collection에 기록되었다.
- `scripts/ledger-mongo-read-compare.js`가 JSON vs live Mongo parity를 검증했다. 결과는 212 / 212 match, failed collection 0개였다.
- MongoDB read adapter는 explicit read-backend request와 manual read-switch approval로 gate된다.
- 당시 live service read는 read switch가 명시적으로 승인 및 요청될 때까지 `data/ledger.json`에 남아 있었다.

이 milestone은 MongoDB가 현재 ledger의 read-equivalent copy를 보관할 수 있음을 증명하면서, JSON을 active live backend 및 rollback source로 보존했다.

## Controlled Read Gate Test

2026-06-30, running PM2 service environment를 바꾸지 않고 process-local MongoDB read gate test를 완료했다.

- 임시 manual read approval을 기록했다.
- 별도 Node process가 `AISFOR_CHAIN_LEDGER_READ_BACKEND=mongodb`를 요청했다.
- Mongo read adapter가 gate를 통과하고 MongoDB에서 212개 document를 읽었다.
- 검증 직후 임시 approval은 즉시 revoke되었다.
- Live AISFOR-CHAIN service read는 JSON에 남아 있었다.

## Mongo Read Snapshot Path

2026-06-30, AISFOR-CHAIN은 현재 Node.js service 구조를 위한 synchronous read-switch bridge를 확보했다.

- 검증된 Mongo read snapshot은 live Mongo read candidate collection에서 materialize될 수 있다.
- `persistentStore.readState()`는 Mongo read request와 manual approval이 모두 있을 때만 해당 snapshot을 읽을 수 있다.
- Process-local switch test는 store가 Mongo-derived snapshot에서 212 row를 읽는 것을 확인했다.
- 테스트 후 temporary approval은 revoke되었고 running service는 JSON read에 남아 있었다.

이 방식은 현재 service startup에서 ledger state를 synchronously load하는 module에 asynchronous Mongo read를 직접 도입하지 않도록 한다.

## PM2 Mongo Read Switch Rehearsal

2026-06-30, 임시 PM2-level Mongo read switch rehearsal이 완료되었다.

- 212 / 212 compare success 이후 Mongo read snapshot을 refresh했다.
- Manual approval과 `AISFOR_CHAIN_LEDGER_READ_BACKEND=mongodb`를 임시 적용했다.
- 실행 중인 `aisfor-chain` process를 재시작했고, admin, explorer, transaction detail, address detail page가 `mongodb-read-enabled` 상태에서 성공적으로 제공되었다.
- 검증 직후 environment는 JSON read로 rollback되었고 approval은 revoke되었다.
- 당시 live service mode는 `json-read-active`로 유지되었다.

## Read Backend 운영 제어

2026-06-30, AISFOR-CHAIN은 명시적 read backend request 및 rollback control을 추가했다.

- `Mongo Read 요청`은 manual approval을 기록하고 read backend request를 MongoDB로 설정한다.
- `JSON Read 롤백`은 read backend request를 JSON으로 복원하고 approval을 revoke한다.
- 모든 `.env` 변경은 timestamped backup과 switch-history record를 만든다.
- PM2 restart는 별도 operational step으로 남아 있어 operator가 적용 전에 request를 검토할 수 있다.
- 당시 live read backend는 JSON이었다.

## Mongo Live Writer And Snapshot Refresh

2026-07-01, AISFOR-CHAIN은 향후 Mongo read switch 이후 필요한 consistency layer를 추가했다.

- Gated Mongo live writer는 현재 ledger state에서 live read candidate collection을 refresh할 수 있다.
- `persistentStore.writeState()`는 Mongo read가 enabled일 때 Mongo read snapshot을 refresh한다.
- `persistentStore.writeState()`는 live write가 명시적으로 enabled이거나 Mongo read가 active일 때 live Mongo synchronization을 trigger할 수 있다.
- Manual live sync 검증 결과: 212 document synced, JSON vs Mongo compare 212 / 212 유지, read snapshot 212 document로 refresh.
- 당시 production mode는 Mongo live writer standby와 함께 JSON read에 남아 있었다.

## Mongo Read Monitor Gate

2026-07-01, AISFOR-CHAIN은 production Mongo read promotion 전에 반복 read monitor gate를 추가했다.

- 각 monitor sample은 active backend를 전환하지 않고 live Mongo read collection과 JSON ledger를 비교한다.
- Admin migration page는 latest sample, expected/actual rows, failed collections, sample window, consecutive OK count를 보여준다.
- 운영 promotion rule은 보수적이다. Mongo read를 ready로 취급하기 전에 최소 6 consecutive OK sample이 필요하다.
- 이 방식은 live service read가 JSON에 남아 있는 동안에도 switch decision을 evidence-based로 만든다.

## Mongo Post Switch Guard

AISFOR-CHAIN은 controlled promotion window를 위한 post-switch guard도 포함한다. Guard는 JSON과 Mongo ledger read를 비교한 뒤 admin, explorer, ledger migration status라는 key service endpoint를 검증한다.

Guard는 기본적으로 health만 기록하고 active backend를 변경하지 않는다. CLI operator가 rollback-on-failure와 confirmation을 명시적으로 요청한 경우에만 rollback을 수행한다. 이 방식은 normal admin-page health check에서 실수로 backend가 바뀌지 않게 하면서 production promotion을 reversible하게 유지한다.

## Controlled Mongo Read Promotion

2026-07-01, AISFOR-CHAIN은 controlled Mongo read promotion을 완료했다. Final preflight가 통과했고 read monitor는 12 consecutive OK sample에 도달했으며 JSON-vs-Mongo parity는 212 / 212로 유지되었다.

Promotion은 manual approval을 기록하고 read backend request를 MongoDB로 설정했으며, updated environment로 PM2 service를 재시작하고 runtime mode가 `mongodb-read-enabled`임을 확인했다. Post-switch guard는 admin, explorer, ledger migration endpoint가 200 response를 반환함을 검증했다. JSON은 rollback source로 유지되며 guarded rollback control을 통해 복원할 수 있다.

## Ledger Migration Completion

AISFOR-CHAIN은 JSON-primary operation에서 MongoDB-primary read로 ledger read migration을 완료했다. Final completion checkpoint는 `mongodb-read-enabled`, 12 / 12 successful read monitor sample, 212 / 212 document parity, healthy admin/explorer endpoint를 확인했다.

Legacy JSON ledger는 rollback source로 유지되지만 더 이상 active read backend는 아니다. 앞으로의 작업은 migration engineering이 아니라 routine operational monitoring과 더 넓은 chain feature expansion으로 이동한다.

## PoSS Tokenomics v0.1

AISFOR-CHAIN은 개발명으로 유지되며, PLAI Chain은 public display 후보이다. 이 모델은 simulation 및 testnet 준비용이며, public coin issuance statement가 아니다.

- 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
- Candidate maximum supply: 10,000,000,000 PLAI
- Operating sequence: internal point -> testnet token -> mainnet coin
- Reward model: PoSS, Proof of Service & Storage
- Token 및 coin name은 hardcoding하지 않고 configuration에서 읽어야 한다.

PoSS는 AISFOR ecosystem 안에서 실제로 유용한 contribution을 reward한다. Reward category는 service usage, content creation, storage capacity, actual data retention, node uptime, file custody verification, shopping activity, emoticon pack creation and sale, ecosystem participation을 포함한다.

첫 번째 reward engine은 simulation mode로 동작한다. Simulation reward는 reward ledger에 기록되지만 public cryptocurrency issuance, guaranteed value, exchange-tradable asset을 의미하지 않는다.

초기 score model은 다음과 같다.

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

Abuse control에는 daily reward cap, per-user cap, per-category cap, refund exclusion, self-trading review, fake commerce detection, storage proof challenge, suspicious activity flag, delayed settlement가 포함되어야 한다.

기존 mock wallet supply는 1,000,000,000 AIS였고, Tokenomics v0.1 후보 최대 공급량은 10,000,000,000 AIS다. 이 차이는 foundation treasury에 대한 mock `SUPPLY_POLICY_ADJUSTMENT` ledger transaction으로 기록되었다.

AISFOR-CHAIN은 전용 reward policy administration page인 `/admin/rewards`를 포함한다. 이 화면은 PoSS category, tokenomics status, category total, top simulated actor, latest reward entry, policy-based simulation control을 보여준다. 이를 통해 content, storage, commerce, emoticon event와 연동하기 전까지 reward를 simulation mode로 안전하게 유지한다.

AISFOR 본체에는 이미 app activity와 distributed storage contribution을 기록하는 내부 AISFOR Point ledger가 있다. AISFOR-CHAIN은 이제 authenticated `/api/reward` write를 받아 새 AISFOR point event를 chain-side PoSS Reward Ledger로 mirror한다. 이 mirror는 point를 중복 지급하지 않고, 동일한 event를 chain visibility를 위한 simulated reward proof로 기록한다. 기존 batched point proof anchoring은 별도로 유지되어 range-based audit evidence를 제공할 수 있다.