cyberia 3.2.5 → 3.2.9

package/src/client/public/cyberia-docs/ENTITY-PROFILE.md

@@ -0,0 +1,241 @@
+# Entity Profile
+
+**Module:** `src/api/cyberia-entity` · `src/api/cyberia-instance-conf`
+
+---
+
+## Overview
+
+An **Entity** is any object in the Cyberia Online game world — players, bots, NPCs, resource nodes, terrain tiles, portals, and skill-spawned projectiles. Every entity is represented as an ordered stack of **Object Layer** item IDs, a position on the grid, a type discriminator, and a runtime state.
+
+---
+
+## CyberiaEntity Schema (MongoDB)
+
+```
+CyberiaEntity {
+  entityType:         String  // see Entity Type Registry below
+  initCellX:          Number  // initial grid column
+  initCellY:          Number  // initial grid row
+  dimX:               Number  // width in cells (default: 1)
+  dimY:               Number  // height in cells (default: 1)
+  color:              String  // RGBA fallback color (no active OL texture)
+  objectLayerItemIds: [String] // ordered list of ObjectLayer item IDs
+
+  // Bot-specific (ignored for non-bot entities)
+  spawnRadius:  Number  // max wander / respawn radius in cells
+  aggroRange:   Number  // attack range in cells (0 = passive)
+  maxLife:      Number  // maximum HP (0 = immortal)
+  lifeRegen:    Number  // HP regeneration per tick
+}
+```
+
+---
+
+## Entity Type Registry
+
+| `entityType`   | Behavior              | Map-placed | Description                                           |
+| -------------- | --------------------- | ---------- | ----------------------------------------------------- |
+| `player`       | interactive           | no         | Local (self) player                                   |
+| `other_player` | interactive           | no         | Remote players in AOI                                 |
+| `bot`          | `hostile` / `passive` | yes        | AI-controlled bot                                     |
+| `skill`        | `skill`               | no         | Runtime-spawned projectile (created by skill system)  |
+| `coin`         | `coin`                | no         | Runtime-spawned collectible (dropped on entity death) |
+| `floor`        | static                | yes        | Terrain tile (walkable)                               |
+| `obstacle`     | static                | yes        | Collision tile (blocks movement)                      |
+| `portal`       | static                | yes        | Zone transition trigger                               |
+| `foreground`   | static                | yes        | Foreground decoration layer                           |
+| `resource`     | extractable           | yes        | Exploitable world object (drops items on extraction)  |
+
+---
+
+## Runtime PlayerState (Go)
+
+```go
+type PlayerState struct {
+    ID                string             // Go server player UUID
+    MapCode           string             // current map
+    Pos               Point              // world position (float64 X, Y)
+    Dims              Dimensions         // entity size
+    Color             ColorRGBA          // fallback solid color
+    Direction         Direction          // UP, UP_RIGHT, RIGHT, DOWN_RIGHT, DOWN, DOWN_LEFT, LEFT, UP_LEFT, NONE
+    Mode              ObjectLayerMode    // IDLE, WALKING, TELEPORTING
+    ObjectLayers      []ObjectLayerState // active OL stack: { ItemID, Active, Quantity }
+    MaxLife           float64
+    Life              float64
+    LifeRegen         float64
+    Coins             uint32             // flat coin balance (single source of truth)
+    Frozen            bool               // FrozenInteractionState active
+    FreezeReason      string             // "dialogue" | "inventory" | ...
+    Path              []PointI           // A* path (for smooth movement)
+    AOI               Rectangle          // current area-of-interest bounds
+    SumStatsLimit     int                // max aggregate stat sum (equipment rules)
+}
+```
+
+---
+
+## ObjectLayer State
+
+Each entity carries an ordered stack of `ObjectLayerState` entries:
+
+```go
+type ObjectLayerState struct {
+    ItemID   string  // references ObjectLayer.data.item.id
+    Active   bool    // equipped/activated (only activable types can be true)
+    Quantity int     // inventory quantity (for stackable items)
+}
+```
+
+The **active layers** determine the entity's rendered appearance and mechanical stats. The `Active` field is managed by the equipment rules.
+
+---
+
+## Equipment Rules
+
+Equipment rules govern which item types may be simultaneously active on a character:
+
+```javascript
+EQUIPMENT_RULES_DEFAULTS = {
+  activeItemTypes: ['skin', 'breastplate', 'weapon'], // only these types may be activated
+  onePerType: true, // at most one active item per type
+  requireSkin: true, // player must always have an active skin if they own any
+};
+```
+
+**Validation on `item_activation` request:**
+
+1. Reject if `item.type` not in `activeItemTypes`.
+2. If `onePerType`, deactivate any currently active item of the same type before activating the new one.
+3. If `requireSkin`, ensure a skin remains active after the change.
+
+---
+
+## Z-Order Rendering
+
+The C client composites layers bottom-to-top by `item.type`:
+
+```
+z-order  type
+──────   ───────────────────
+  0      floor / obstacle / portal / foreground
+  1      skin  (base character body)
+  2      breastplate (armor overlay)
+  3      weapon (weapon overlay)
+```
+
+`get_priority_for_type()` in `entity_render.c` maps item type → z-order integer. Multiple layers of the same type are rendered in declared order within that z-level.
+
+---
+
+## Stat Aggregation
+
+Stats are aggregated across all **active** Object Layers on an entity. The server enforces a `sumStatsLimit` — the maximum sum of all stat values allowed for the player. Attempting to equip items that would exceed this limit is rejected.
+
+**Active stats sum:**
+
+$$\text{activeStatsSum} = \sum_{\text{active layers}} (\text{effect} + \text{resistance} + \text{agility} + \text{range} + \text{intelligence} + \text{utility})$$
+
+The `sumStatsLimit` and `activeStatsSum` are sent to the client on each AOI update so the inventory UI can show remaining equip budget.
+
+---
+
+## Entity Status Indicator (ESI)
+
+The Go server computes a status `u8` per entity each AOI tick. The C client renders the corresponding icon above the entity nameplate.
+
+```go
+// Status constants (entity_status.go) — MUST stay in sync with JS STATUS_ICONS array
+StatusNone              = 0  // skill/coin bots, world objects
+StatusPassive           = 1  // passive bot
+StatusHostile           = 2  // hostile bot
+StatusFrozen            = 3  // player in FrozenInteractionState
+StatusPlayer            = 4  // normal alive player
+StatusDead              = 5  // dead / respawning entity
+StatusResource          = 6  // static exploitable resource
+StatusResourceExtracted = 7  // depleted resource (respawning)
+StatusActionProvider    = 8  // NPC with available actions (bouncing chat icon)
+```
+
+---
+
+## Per-EntityType Defaults
+
+Instance configuration (`CyberiaInstanceConf`) defines canonical defaults per entity type:
+
+| Field         | Description                                                                       |
+| ------------- | --------------------------------------------------------------------------------- |
+| `liveItemIds` | ObjectLayer item IDs applied when entity is alive with no explicit items assigned |
+| `deadItemIds` | ObjectLayer item IDs for dead/ghost/respawning state                              |
+| `dropItemIds` | Items granted to the extractor when a resource entity is depleted                 |
+| `colorKey`    | Named palette color used as solid fallback when no active OL texture is available |
+
+---
+
+## Bot Entity Profile
+
+Bot entities extend the base schema with runtime AI state:
+
+```go
+type BotState struct {
+    // Inherits all PlayerState fields
+    Behavior      string     // "hostile" | "passive" | "skill" | "coin"
+    SpawnRadius   int        // wander / respawn radius
+    AggroRange    int        // attack range (0 = passive)
+    SpawnPoint    PointI     // original spawn cell
+    RespawnTimer  time.Time  // next respawn timestamp
+}
+```
+
+**Bot behaviors:**
+
+| Behavior  | AI Actions                              | Description              |
+| --------- | --------------------------------------- | ------------------------ |
+| `hostile` | pathfind to player, attack              | Aggressive enemy bot     |
+| `passive` | random wander                           | Non-aggressive world NPC |
+| `skill`   | move in direction, despawn on collision | Projectile entity        |
+| `coin`    | static, collectible                     | Coin drop entity         |
+
+---
+
+## Resource Entity Profile
+
+Resource entities have a specific lifecycle:
+
+```
+Alive (StatusResource)
+  → Player extracts (tap interaction)
+    → dropItemIds granted to player inventory
+    → Entity transitions to StatusResourceExtracted
+      → Respawn timer starts
+        → Entity returns to StatusResource
+```
+
+---
+
+## Entity Lifecycle Diagram
+
+```mermaid
+stateDiagram-v2
+    [*] --> Alive : Spawned by instance_loader
+    Alive --> Dead : Life reaches 0 (combat/skill)
+    Alive --> ResourceExtracted : Player extracts (resource type)
+    Dead --> Alive : Respawn timer elapsed
+    ResourceExtracted --> Alive : Respawn timer elapsed
+    Alive --> Frozen : Player opens modal (FrozenInteractionState)
+    Frozen --> Alive : Player closes modal
+    Alive --> [*] : Entity removed from AOI
+```
+
+---
+
+## Coin Balance Architecture
+
+Coins use a **flat + display split** design to avoid O(N) inventory traversal:
+
+| Field                         | Type               | Purpose                                                                                            |
+| ----------------------------- | ------------------ | -------------------------------------------------------------------------------------------------- |
+| `entity.Coins`                | `uint32`           | **Single source of truth** — all economy operations read/write this field O(1)                     |
+| `coinItemId ObjectLayer slot` | `ObjectLayerState` | **Display only** — `Active: false`, `Quantity = Coins`, synced by `syncCoinOL()` on every mutation |
+
+The `coin` item type is never activable. The inventory UI automatically renders it with a lock indicator.

package/src/client/public/cyberia-docs/HARDHAT-MODULE.md

@@ -0,0 +1,300 @@
+# Hardhat Module
+
+**Path:** `hardhat/`
+
+---
+
+## Overview
+
+The Hardhat module is the smart contract development, testing, and deployment environment for the **ObjectLayerToken** ERC-1155 contract — the on-chain economic reality layer of the Object Layer Protocol. It targets Hyperledger Besu private networks (IBFT2/QBFT) running on Kubernetes.
+
+---
+
+## Directory Structure
+
+```
+hardhat/
+  hardhat.config.js       Main Hardhat configuration
+  package.json
+  contracts/
+    ObjectLayerToken.sol  ERC-1155 multi-token contract
+  scripts/
+    deployObjectLayerToken.js  Deployment script
+  test/                   Contract tests (Mocha + ethers v6)
+  deployments/            Deployment artifacts (auto-generated)
+  ignition/               Hardhat Ignition modules (optional)
+  networks/               Network-specific genesis configs
+```
+
+---
+
+## ObjectLayerToken Contract
+
+### Inheritance Chain
+
+```
+ObjectLayerToken
+  └─ ERC1155         (OpenZeppelin 5.x — core multi-token standard)
+  └─ ERC1155Burnable (holders can burn their tokens)
+  └─ ERC1155Pausable (owner can freeze all transfers)
+  └─ ERC1155Supply   (on-chain total supply per token ID)
+  └─ Ownable         (mint, register, pause restricted to owner)
+```
+
+### Token ID Semantics
+
+| Token ID         | Semantic                                         | Supply                               | Managed By     |
+| ---------------- | ------------------------------------------------ | ------------------------------------ | -------------- |
+| `0` (CRYPTOKOYN) | Fungible in-game currency (CKY)                  | 10,000,000 × 10^18                   | cryptokoyn.net |
+| `≥ 1`            | Object Layer item (weapon, skin, resource, etc.) | 1 = non-fungible; >1 = semi-fungible | itemledger.com |
+
+### Token ID Derivation
+
+Token IDs ≥ 1 use a deterministic namespace-scoped derivation:
+
+```solidity
+// computeTokenId(itemId) = uint256(keccak256(abi.encodePacked(namespace, itemId)))
+// namespace = "cyberia.object-layer:"
+uint256 tokenId = uint256(keccak256(abi.encodePacked("cyberia.object-layer:", itemId)));
+```
+
+This guarantees:
+
+- The same `itemId` always produces the same `tokenId`.
+- Token IDs are collision-resistant across different item namespaces.
+- Any party can independently verify a `tokenId` from an `itemId`.
+
+### Key State Variables
+
+```solidity
+uint256 public constant CRYPTOKOYN = 0;
+uint256 public constant INITIAL_CRYPTOKOYN_SUPPLY = 10_000_000 * 1e18;
+
+mapping(uint256 => string) private _tokenCIDs;      // tokenId → canonical IPFS CID
+mapping(uint256 => string) private _itemIds;         // tokenId → itemId string
+mapping(bytes32 => uint256) private _itemIdToTokenId; // keccak256(itemId) → tokenId
+```
+
+### Events
+
+| Event                                                                | Description                       |
+| -------------------------------------------------------------------- | --------------------------------- |
+| `ObjectLayerRegistered(tokenId, itemId, metadataCid, initialSupply)` | New item type registered on-chain |
+| `MetadataUpdated(tokenId, metadataCid)`                              | Item metadata CID updated         |
+| `TransferSingle(operator, from, to, id, value)`                      | Single token transfer             |
+| `TransferBatch(operator, from, to, ids, values)`                     | Batch token transfer              |
+| `Paused(account)`                                                    | All transfers frozen              |
+| `Unpaused(account)`                                                  | Transfers resumed                 |
+
+### Key Functions
+
+| Function                                                     | Access      | Description                               |
+| ------------------------------------------------------------ | ----------- | ----------------------------------------- |
+| `registerObjectLayer(to, itemId, metadataCid, supply, data)` | `onlyOwner` | Register a new item + mint initial supply |
+| `batchRegisterObjectLayers(to, items[])`                     | `onlyOwner` | Batch registration + mint                 |
+| `mint(to, tokenId, amount, data)`                            | `onlyOwner` | Mint additional supply for existing token |
+| `mintBatch(to, ids[], amounts[], data)`                      | `onlyOwner` | Batch mint                                |
+| `burn(from, tokenId, amount)`                                | holder      | Burn tokens                               |
+| `burnBatch(from, ids[], amounts[])`                          | holder      | Batch burn                                |
+| `setTokenMetadataCID(tokenId, metadataCid)`                  | `onlyOwner` | Update IPFS metadata CID                  |
+| `pause()` / `unpause()`                                      | `onlyOwner` | Emergency transfer freeze                 |
+| `computeTokenId(itemId)`                                     | pure        | Deterministic token ID computation        |
+| `getItemId(tokenId)`                                         | view        | Reverse lookup tokenId → itemId           |
+| `getTokenCID(tokenId)`                                       | view        | Get canonical IPFS CID for token          |
+
+### URI Resolution
+
+```solidity
+// uri(tokenId) returns: {baseTokenURI}{_tokenCIDs[tokenId]}
+// e.g.: "ipfs://bafkrei...json"
+// The returned URI resolves to the full ObjectLayer data JSON (AtomicPrefab)
+```
+
+---
+
+## Networks
+
+### Network Configuration (`hardhat.config.js`)
+
+| Network      | URL                                             | Chain ID | Use Case              |
+| ------------ | ----------------------------------------------- | -------- | --------------------- |
+| `hardhat`    | in-process                                      | -        | Local testing         |
+| `besu-ibft2` | `BESU_IBFT2_RPC_URL` or `http://127.0.0.1:8545` | 777771   | Direct Besu IBFT2 RPC |
+| `besu-qbft`  | `BESU_QBFT_RPC_URL` or `http://127.0.0.1:8545`  | 777771   | Direct Besu QBFT RPC  |
+| `besu-k8s`   | `BESU_K8S_RPC_URL` or `http://127.0.0.1:30545`  | 777771   | Kubernetes NodePort   |
+
+All Besu networks: `gasPrice: 0` (permissioned network, gasless model).
+
+### Coinbase Key Management
+
+The deployment uses a coinbase private key read from `engine-private/eth-networks/besu/coinbase`:
+
+```javascript
+const coinbaseKey = readPrivateKey('../engine-private/eth-networks/besu/coinbase');
+```
+
+If the key file does not exist, the config falls back to a dummy key (safe for compilation-only workflows).
+
+---
+
+## Deployment
+
+### Prerequisites
+
+```bash
+cd hardhat
+npm install
+```
+
+### Compile Contracts
+
+```bash
+npx hardhat compile
+# Artifacts written to hardhat/artifacts/
+```
+
+### Deploy to Besu
+
+```bash
+# Deploy to IBFT2 network
+npx hardhat run scripts/deployObjectLayerToken.js --network besu-ibft2
+
+# Deploy to QBFT network
+npx hardhat run scripts/deployObjectLayerToken.js --network besu-qbft
+
+# Deploy to Kubernetes cluster (via NodePort :30545)
+npx hardhat run scripts/deployObjectLayerToken.js --network besu-k8s
+```
+
+**Deployment script actions:**
+
+1. Connect to Besu RPC using the coinbase secp256k1 key.
+2. Deploy `ObjectLayerToken` contract.
+3. Mint `INITIAL_CRYPTOKOYN_SUPPLY` (10M CKY) to the deployer address.
+4. Verify initial state: total supply, deployer balance.
+5. Write deployment artifact to `hardhat/deployments/{network}/ObjectLayerToken.json`.
+
+**Deployment artifact structure:**
+
+```json
+{
+  "address": "0x...",
+  "abi": [...],
+  "txHash": "0x...",
+  "blockNumber": 42,
+  "deployer": "0x...",
+  "network": "besu-ibft2",
+  "chainId": 777771,
+  "timestamp": "2026-01-01T00:00:00.000Z"
+}
+```
+
+The artifact is consumed by:
+
+- `bin/cyberia.js` CLI (`cyberia chain` subcommands).
+- Engine gRPC server for contract address resolution.
+- itemledger.com and cryptokoyn.net API servers.
+
+---
+
+## Running Tests
+
+```bash
+cd hardhat
+npx hardhat test
+
+# With gas report
+REPORT_GAS=true npx hardhat test
+```
+
+Tests use **Mocha + ethers v6** via `@nomicfoundation/hardhat-toolbox-mocha-ethers`. The `hardhat` in-process network simulates Besu behavior.
+
+---
+
+## Cyberia CLI Integration
+
+The Cyberia CLI (`bin/cyberia.js`) exposes the full Besu chain and contract lifecycle:
+
+### Key Management
+
+```bash
+# Generate new Ethereum secp256k1 key pair
+cyberia chain key-gen
+# Save key pair to default paths
+cyberia chain key-gen --save
+
+# Set the coinbase deployer key from hex
+cyberia chain set-coinbase --private-key 0xYOUR_PRIVATE_KEY_HEX
+# Set from saved key file
+cyberia chain set-coinbase --from-file ./engine-private/eth-networks/besu/<address>.key.json
+```
+
+### Network Lifecycle
+
+```bash
+# Deploy Besu network to Kubernetes
+cyberia chain deploy
+cyberia chain deploy --consensus qbft
+
+# Remove Besu network
+cyberia chain remove
+```
+
+### Contract Lifecycle
+
+```bash
+# Compile contracts
+cyberia chain compile
+
+# Deploy ObjectLayerToken (mints 10M CKY to deployer)
+cyberia chain deploy-contract --network besu-ibft2
+
+# Run contract tests
+cyberia chain test
+```
+
+### Token Operations
+
+```bash
+# Register a non-fungible unique item (uses canonical CID from MongoDB)
+cyberia chain register --item-id legendary-hatchet --from-db --supply 1
+
+# Register semi-fungible stackable resource
+cyberia chain register --item-id gold-ore --from-db --supply 1000000
+
+# Manual CID override
+cyberia chain register --item-id legendary-hatchet --metadata-cid bafkrei... --supply 1
+
+# Batch-register multiple items
+cyberia chain batch-register --from-db --items '[{"itemId":"wood","supply":500000},{"itemId":"stone","supply":500000}]'
+
+# Mint additional CKY
+cyberia chain mint --token-id 0 --to 0xABCD...1234 --amount 1000000000000000000000
+
+# Query balance
+cyberia chain balance --address 0xABCD...1234 --token-id 0
+
+# Transfer
+cyberia chain transfer --from 0x... --to 0x... --token-id 0 --amount 1000
+
+# Burn
+cyberia chain burn --token-id 0 --amount 500 --address 0x...
+
+# Status and governance
+cyberia chain status
+cyberia chain pause
+cyberia chain unpause
+```
+
+---
+
+## Environment Variables
+
+| Variable              | Default                  | Description                         |
+| --------------------- | ------------------------ | ----------------------------------- |
+| `BESU_IBFT2_RPC_URL`  | `http://127.0.0.1:8545`  | Besu IBFT2 JSON-RPC URL             |
+| `BESU_QBFT_RPC_URL`   | `http://127.0.0.1:8545`  | Besu QBFT JSON-RPC URL              |
+| `BESU_K8S_RPC_URL`    | `http://127.0.0.1:30545` | Kubernetes NodePort RPC URL         |
+| `BESU_IBFT2_CHAIN_ID` | `777771`                 | Chain ID override for IBFT2         |
+| `REPORT_GAS`          | `false`                  | Enable gas usage reporting in tests |
+| `GAS_REPORT_FILE`     | _(stdout)_               | Path for gas report output file     |