cyberia 3.2.5 → 3.2.12

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     |

package/src/client/public/cyberia-docs/OFF-CHAIN-ECONOMY.md

@@ -0,0 +1,279 @@
+# Off-Chain Economy: Fountain & Sink Architecture
+
+**Module:** `cyberia-server/src/economy.go` · `src/api/cyberia-instance-conf`
+
+> **Status:** Alpha (sinks disabled by default; all values reset on reconnect).
+> **On-chain bridge:** CKY ERC-1155 token (ID 0) on Hyperledger Besu.
+> The bridge protocol stays aligned with the project's CKY tokenomics model.
+
+---
+
+## 1. Model Overview
+
+Cyberia Online uses the **Fountain & Sink** economy — the industry standard for sustainable in-game economies, pioneered by _Ultima Online_ and refined in _EVE Online_ and _World of Warcraft_.
+
+```
+                ┌─────────────────────────────┐
+                │         FOUNTAINS           │
+                │  (inject coins into economy) │
+                │                             │
+                │  botSpawnCoins  ──► Bot      │
+                │  playerSpawnCoins ► Player   │
+                └──────────────┬──────────────┘
+                               │ new coins
+                               ▼
+                ┌──────────────────────────────┐
+                │      CIRCULATING SUPPLY      │
+                │   (player & bot wallets)     │
+                └──────┬───────────────────────┘
+                       │
+          ┌────────────┴────────────┐
+          │   KILL TRANSFER         │  zero-sum redistribution
+          │   loser → winner        │
+          │                         │
+          │  PvE: coinKillPercentVsBot    │
+          │  PvP: coinKillPercentVsPlayer │
+          │  floor: coinKillMinAmount     │
+          └────────────┬────────────┘
+                       │
+                ┌──────▼──────────────────────┐
+                │           SINKS             │
+                │   (destroy coins — alpha=0) │
+                │                             │
+                │  respawnCostPercent         │
+                │  portalFee                  │
+                │  craftingFeePercent         │
+                └─────────────────────────────┘
+```
+
+### Core Rules
+
+| Rule                          | Description                                                                                     |
+| ----------------------------- | ----------------------------------------------------------------------------------------------- |
+| **Bots are infinite mint**    | Every bot respawn resets wallet to `botSpawnCoins`. Supply bounded by player kill rate.         |
+| **Players are zero-sum**      | Killing a player transfers coins but creates no new ones. PvP is redistribution only.           |
+| **Kill floor**                | `coinKillMinAmount` guarantees every successful kill pays out even against a near-empty wallet. |
+| **Sinks scale with activity** | Fees burn a fraction — more activity = more burn, preventing indefinite inflation.              |
+
+---
+
+## 2. Configuration Structure
+
+Economy parameters live in `CyberiaInstanceConf.economyRules`. A document without an `economyRules` sub-document receives canonical defaults automatically.
+
+### 2.1 JavaScript Defaults (`cyberia-server-defaults.js`)
+
+```javascript
+economyRules: {
+  // ── Fountains ──────────────────────────────────────────
+  botSpawnCoins:    50,   // coins on bot spawn/respawn (infinite mint)
+  playerSpawnCoins: 50,   // guest starting wallet (resets on reconnect)
+
+  // ── Kill Transfer ───────────────────────────────────────
+  coinKillPercentVsBot:    0.40, // 40% of bot wallet → killer on PvE kill
+  coinKillPercentVsPlayer: 0.15, // 15% of player wallet → killer on PvP kill
+  coinKillMinAmount:       10,   // minimum coins per kill (hard floor)
+
+  // ── Sinks (alpha: all 0 = disabled) ────────────────────
+  respawnCostPercent:  0.0,  // fraction burned on player death
+  portalFee:           0,    // flat coins burned per portal use
+  craftingFeePercent:  0.0,  // fraction burned per crafting action
+}
+```
+
+### 2.2 Protobuf Message (`proto/cyberia.proto`)
+
+```proto
+message EconomyRules {
+  int32  bot_spawn_coins             = 1;
+  int32  player_spawn_coins          = 2;
+  double coin_kill_percent_vs_bot    = 3;
+  double coin_kill_percent_vs_player = 4;
+  int32  coin_kill_min_amount        = 5;
+  double respawn_cost_percent        = 6;
+  int32  portal_fee                  = 7;
+  double crafting_fee_percent        = 8;
+}
+```
+
+### 2.3 Go Server (`server.go → ApplyInstanceConfig`)
+
+```go
+er := cfg.GetEconomyRules()
+if er == nil { er = &pb.EconomyRules{} }
+
+s.botSpawnCoins           = int(er.GetBotSpawnCoins())
+s.playerSpawnCoins        = int(er.GetPlayerSpawnCoins())
+s.coinKillPercentVsBot    = er.GetCoinKillPercentVsBot()
+s.coinKillPercentVsPlayer = er.GetCoinKillPercentVsPlayer()
+s.coinKillMinAmount       = int(er.GetCoinKillMinAmount())
+s.respawnCostPercent      = er.GetRespawnCostPercent()
+s.portalFee               = int(er.GetPortalFee())
+s.craftingFeePercent      = er.GetCraftingFeePercent()
+```
+
+---
+
+## 3. Runtime Economy API (`economy.go`)
+
+All economy logic is encapsulated in a single file enforcing the single-source principle. Callers (`handlers.go`, `collision.go`, `skill.go`) call named methods and never manipulate coin wallets directly.
+
+### Method Reference
+
+| Method                                | Caller                             | Description                                          |
+| ------------------------------------- | ---------------------------------- | ---------------------------------------------------- |
+| `FountainInitPlayer(player)`          | `handlers.go` on WebSocket connect | Credits `playerSpawnCoins` to new player             |
+| `FountainInitBot(bot)`                | `collision.go` on bot respawn      | Resets bot wallet to `botSpawnCoins` (infinite mint) |
+| `ExecuteKillTransfer(caster, victim)` | `skill.go HandleOnKillSkills`      | Transfers coins based on kill scenario               |
+| `SinkRespawnCost(player)`             | `collision.go handlePlayerDeath`   | Burns `respawnCostPercent`% of player coins          |
+| `SinkPortalFee(player)`               | Portal handler                     | Burns flat `portalFee` coins on portal use           |
+| `SinkCraftingFee(player, item)`       | Craft handler                      | Burns `craftingFeePercent`% on crafting              |
+
+### Kill Transfer Logic
+
+```
+ExecuteKillTransfer(caster, victim):
+
+  if caster=Player, victim=Bot    → rate = coinKillPercentVsBot     (PvE farming)
+  if caster=Player, victim=Player → rate = coinKillPercentVsPlayer  (PvP)
+  if caster=Bot,    victim=Player → rate = coinKillPercentVsPlayer  (bot kills player)
+  if caster=Bot,    victim=Bot    → rate = coinKillPercentVsBot     (bot-on-bot)
+
+  transfer = max(floor(victim.coins × rate), coinKillMinAmount)
+  transfer = min(transfer, victim.coins)    // can't take more than available
+
+  victim.coins  -= transfer
+  caster.coins  += transfer                 // bots ignore received coins
+  → sendFCT(caster, FCTTypeCoinGain, worldX, worldY, transfer)
+  → sendFCT(victim, FCTTypeCoinLoss,  worldX, worldY, transfer)
+```
+
+---
+
+## 4. Coin Balance Architecture
+
+Coins use a **flat + display split** design:
+
+| Field                         | Type                                                  | Role                                                              |
+| ----------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------- |
+| `entity.Coins`                | `uint32`                                              | **Single source of truth** — O(1) read/write for all economy math |
+| `coinItemId` ObjectLayer slot | `ObjectLayerState { Active: false, Quantity: Coins }` | **Display only** — synced by `syncCoinOL()` on every mutation     |
+
+**Why split:**
+
+- Economy math uses `Coins` directly (O(1)); no OL iteration.
+- Coin slot is always `Active: false` — the inventory UI automatically renders it with a lock indicator (non-activable).
+- No risk of coin OL being activated by the `item_activation` handler.
+
+---
+
+## 5. Floating Combat Text (FCT) Wire Protocol
+
+Economy events trigger client-side visual feedback via the binary AOI protocol.
+
+**Coin FCT (14 bytes, fixed):**
+
+```
+MsgTypeFCT = 0x04
+
+Offset  Size  Field
+──────  ────  ─────────────────────────────
+  0      u8   message type (0x04)
+  1      u8   fct_type (see table)
+  2      f32  world_x (entity position)
+  6      f32  world_y
+ 10      u32  value (always positive; sign implied by type)
+```
+
+**Item FCT (variable length):**
+
+```
+MsgTypeItemFCT = 0x05
+
+Offset  Size  Field
+──────  ────  ─────────────────────────────
+  0      u8   message type (0x05)
+  1      u8   fct_type (FCTTypeItemGain or FCTTypeItemLoss)
+  2      f32  world_x
+  6      f32  world_y
+ 10      u32  quantity
+ 14      u8   itemId length
+ 15      str  itemId bytes
+```
+
+| `fct_type` | Constant          | Color  | Display        |
+| ---------- | ----------------- | ------ | -------------- |
+| `0x00`     | `FCTTypeDamage`   | Red    | `-N` HP lost   |
+| `0x01`     | `FCTTypeRegen`    | Green  | `+N` HP gained |
+| `0x02`     | `FCTTypeCoinGain` | Yellow | `+N` coins     |
+| `0x03`     | `FCTTypeCoinLoss` | Yellow | `-N` coins     |
+| `0x04`     | `FCTTypeItemGain` | Cyan   | `+N ItemID`    |
+| `0x05`     | `FCTTypeItemLoss` | Purple | `-N ItemID`    |
+
+---
+
+## 6. MongoDB Document Example
+
+```json
+{
+  "instanceCode": "alpha-01",
+  "economyRules": {
+    "botSpawnCoins": 50,
+    "playerSpawnCoins": 50,
+    "coinKillPercentVsBot": 0.4,
+    "coinKillPercentVsPlayer": 0.15,
+    "coinKillMinAmount": 10,
+    "respawnCostPercent": 0.0,
+    "portalFee": 0,
+    "craftingFeePercent": 0.0
+  }
+}
+```
+
+---
+
+## 7. gRPC Config Builder
+
+The `toInstanceConfig()` function in `grpc-server.js` resolves `economyRules` with a two-tier fallback:
+
+```
+priority:  gc.economyRules.field    (instance document in MongoDB)
+         → fb.economyRules.field    (CYBERIA_INSTANCE_CONF_DEFAULTS — always set)
+```
+
+---
+
+## 8. On-Chain Bridge
+
+The off-chain `coin` balance maps to the on-chain **CKY token (ERC-1155 Token ID 0)** on Hyperledger Besu:
+
+```
+Off-chain Coins (uint32)
+    ↕  conversion (via cryptokoyn.net withdrawal protocol)
+On-chain CKY (ERC-1155, Token ID 0, 18-decimal precision)
+```
+
+**Bridge mechanics:**
+
+- **Withdrawal:** Player requests conversion of off-chain coins to on-chain CKY via cryptokoyn.net.
+- **Deposit:** Player deposits on-chain CKY to top up off-chain balance.
+- **CKY Minting Fee:** Converting off-chain items to ERC-1155 tokens requires a CKY fee — the primary on-chain sink mechanism.
+
+---
+
+## 9. Enabling Sinks (Alpha → Beta)
+
+To activate economy pressure:
+
+```javascript
+// Update CyberiaInstanceConf in MongoDB for the target instance
+{
+  "economyRules": {
+    "respawnCostPercent":  0.05,  // 5% burned on death
+    "portalFee":           5,     // 5 coins burned per portal use
+    "craftingFeePercent":  0.03   // 3% burned on each crafting action
+  }
+}
+```
+
+The Go server picks up updated config via gRPC hot-reload (`GetFullInstance` polling at `ENGINE_GRPC_RELOAD_INTERVAL_SEC`).