Gitea repo: http://54.38.205.168:3000/tiamak/Peya
Preferred CLI for remote inspection: tea
tea is especially useful for:
- checking branch state on Gitea
- inspecting Actions runs
- reading Actions job logs

Reference Material

/mnt/duzy/sal11v4/townforge — merge-mining design reference
/mnt/duzy/sal11v4/ninacatcoin — reward events and EDA reference
/mnt/duzy/sal11v4/monero/monero-x86_64-linux-gnu-v0.18.4.6 — Monero binaries for parent-chain tests
/mnt/duzy/sal11v4/sal — Salvium binaries for parent-chain compatibility tests
/mnt/duzy/sal11v4/zeph/zephyr-cli-linux-v2.3.0 — Zephyr binaries for parent-chain compatibility tests
/mnt/duzy/sal11v4/sal/salvium — Salvium source tree
/mnt/duzy/sal11v4/zeph/zephyr — Zephyr source tree
/mnt/duzy/sal11v4/cryptonote-nodejs-pool — stabilized solo-pool baseline fork
/mnt/duzy/sal11v4/peya-nodejs-pool — active Peya-centric pool repo for the next product layer
/mnt/duzy/sal11v4/node-cryptoforknote-util-salvium — shared Salvium/Peya util backend for pool-side blob/template work
/mnt/duzy/sal11v4/xmrig — local XMRig fork/source used for miner-side integration tests

Additional Gitea Repositories

http://54.38.205.168:3000/tiamak/cryptonote-nodejs-pool
http://54.38.205.168:3000/tiamak/peya-nodejs-pool
http://54.38.205.168:3000/tiamak/node-cryptoforknote-util-salvium
http://54.38.205.168:3000/tiamak/node-cryptoforknote-util-mo
http://54.38.205.168:3000/tiamak/xmrig

Peya Branch Model

main — stable promoted branch
develop — current integration branch for deeper feature work
upstreams — selective Monero cherry-pick staging branch
safe-basecode — preserved snapshot of earlier stable state

Core Peya Subsystems

Consensus And Block Logic

src/cryptonote_basic
- block structures
- hashing blobs
- reward logic
- merge-mining helpers
src/cryptonote_core
- block validation
- miner tx validation
- chain difficulty integration
- tx pool integration

RPC Layer

src/rpc
- daemon RPC definitions
- block template RPC
- aux-pow submit RPC

Wallet Layer

src/wallet
- wallet refresh, outputs, stake/yield handling

Proxy Layer

src/merge_mining_proxy
- Monero-parent merge-mining proxy
- signer-key handling
- key-generation helper

Peya Hardfork Model

HF_VERSION_CARROT = 10
HF_VERSION_ENABLE_TOKENS = 11
merge mining activates later:
- HF_VERSION_MERGE_MINING = 13
- HF_VERSION_RESTRICTED_MERGE_MINING = 14

Hardfork heights are intentionally early because Peya does not need historical compatibility with a long-lived production chain yet.

Reward Architecture

Base Reward

base emission still comes from the standard reward path in cryptonote_basic_impl.cpp

Reward Events

deterministic events keyed from the previous block hash
current model:
- x2
- x20
they apply to full block subsidy before any miner/staker split
stacking was intentionally disabled

Staking Split

no active stakes -> 100% miner reward
active stakes -> 80/20 split

Treasury

treasury payouts use precomputed carrot payout tuples in cryptonote_config.h
treasury is independent of merge mining and has already been verified to survive merge-mined blocks

Difficulty Architecture

Base Algorithm

LWMA remains the main difficulty algorithm

EDA Layer

bounded EDA is an overlay, not a replacement
it is intended to accelerate recovery after abrupt hashrate departure
current implementation applies the cap after normal LWMA calculation

Trend Correction Layer

Peya now also applies a deterministic short-vs-baseline trend correction after LWMA + bounded EDA
purpose:
- prevent a large emergency downward cap from immediately snapping back toward the untouched LWMA trajectory
current shape:
- recent window: 5 solve times
- older baseline window: 15 solve times
- smoothing: 3/10
- per-block clamp: +-5%
this remains a bounded overlay on top of the base LWMA path rather than a replacement algorithm

Merge Mining Architecture In Peya

High-Level Model

Peya supports two valid mining modes:
- normal solo mining
- merge-mined aux-chain blocks
merge mining is optional

Current Parent-Chain Assumption

Peya no longer lives in a purely Monero-only parent world
explicit Zephyr and Salvium parent representations were added where needed for merge-mining-critical serialization and hashing
current mainnet runtime status is:
- Monero -> Peya works
- Salvium -> Peya works
- Zephyr -> Peya works
the remaining engineering risk is operational churn and pool/proxy robustness, not a fundamental inability to accept Zephyr or Salvium parents

Zephyr-Specific Finding

Zephyr coinbase outputs use txout_zephyr_tagged_key
that type carries Zephyr-specific fields such as asset_type
this differs from the Monero-style parent output model and is exactly why Zephyr support had to become an explicit adapter path
Zephyr compatibility is therefore a consensus-aware parent integration, not a trivial endpoint swap

Intended Parent-Adapter Architecture

Peya should move from a single hardcoded Monero parent model to explicit parent adapters
the likely shape is:
- parent_chain_type
- parent-specific header representation
- parent-specific coinbase representation
- parent-specific parse/hash/tag helpers
proxy should switch parent chain at runtime via a CLI flag
Peya consensus must switch parent validation based on the parent type stored in the block aux header
practical implication:
- Monero and Zephyr can coexist as supported parent chains
- Salvium can coexist as a supported parent chain as well
- adding a new parent later still requires a Peya update because the adapter affects consensus validation

Pool Runtime Note

peya-nodejs-pool needed an additional template-binding fix for live merge-mining operation
the important rule is:
- miner jobs cannot be keyed only by height
- they must stay attached to the exact originating template when templates churn on the same height
this is especially visible on active mainnet merge-mining runs and with rented hashrate
upstream parent-chain releases do not always force a Peya fork
a Peya adapter update is only required if the upstream chain changes merge-mining-relevant inputs, especially:
- template blob encoding
- parent block layout
- coinbase layout
- merge-mining commitment placement
- seed-hash or PoW semantics
first implemented groundwork on develop:
- explicit parent_chain field in aux_header
- parent coinbase stored as serialized blob instead of always as typed Monero coinbase object
- consensus-side parent coinbase parsing switched by parent chain
- proxy runtime flag to select parent chain (monero, zephyr)

Block Model

Peya block can optionally carry an aux header
aux header contains the parent-chain proof and merge-mining metadata
restricted merge mining extends the aux header with authorization data
testnet currently has a development signer pubkey hardcoded for iterative MM testing; the matching secret key lives outside repo at /mnt/duzy/sal11v4/peya-mm-testnet-auth.key and must not be committed
the current in-progress generalization direction is:
- store parent chain type explicitly
- avoid forcing every parent coinbase into monero_coinbase_transaction_t
- move toward parent-specific parsing plus parent-agnostic hashed blobs where possible

Authorization Model

merge-mined block contains:
- authorized signer pubkey
- signature over deterministic aux-pow authorization hash
daemon verifies:
- pubkey is whitelisted
- signature is valid
secret key is held only by the proxy

Proxy Model

proxy talks to:
- Monero parent daemon
- Peya aux daemon
proxy obtains parent and aux templates
proxy embeds aux commitment into parent
proxy signs merged block if MM auth is configured
proxy submits:
- parent block to parent chain
- aux block to Peya

Why Townforge Matters

Townforge demonstrates the correct architectural split for merge mining:
- parent-specific block model
- aux-header validation inside consensus
- proxy as orchestration layer
game and PoS layers in Townforge are not relevant and should be ignored

Why Ninacatcoin Matters

Ninacatcoin is useful as a source of isolated ideas:
- deterministic reward multiplier events
- emergency difficulty adjustment
its codebase is not a good cherry-pick source; use it as a design quarry

Current Architectural Gap

parent-chain compatibility is still Monero-specific
to support Zephyr, Salvium, or others, Peya likely needs a parent adapter layer with at least:
- parent blocktemplate parsing
- parent block serialization
- parent coinbase interpretation
- parent seed hash / PoW semantics

Pool Layer Status

Current Direction

the next integration layer is cryptonote-nodejs-pool
the pool is being adapted first for solo mining, not merge mining
the util backend is now being treated as an adapter host, not as a single-coin fork

Shared Util Direction

node-cryptoforknote-util-salvium is now the active util for both:
- current Salvium
- current Peya
it now also has an explicit monero-family adapter for blobType 0
the intended shape is:
- shared adapter host
- explicit family branches where needed
first concrete Peya-specific adapter need already confirmed:
- Peya block parsing after HF_VERSION_MERGE_MINING
- current Peya blocktemplate carries the has_aux_header tail even for solo blocks
- Salvium util had to learn that block suffix to parse current Peya templates
current verified coverage of this shared util:
- monero-family
- salvium-family
- zephyr-family
- Peya as a small block-format branch on top of the Salvium-family side
current shape of this shared util:
- monero-family
- salvium-family
- zephyr-family
Zephyr support was added as an explicit adapter, not as a Monero tweak:
- Zephyr-specific block header with raw pricing_record blob
- Zephyr-specific coinbase/output typing
- Zephyr-specific block wrapper

Solo Pool Validation

the pool layer has now been validated with daemon + pool + xmrig in four modes:
- local Salvium -> pool -> xmrig
- public Salvium testnet -> pool -> xmrig
- local Peya -> pool -> xmrig
- local Monero regtest -> pool -> xmrig
- local fastfork Zephyr testnet -> pool -> xmrig
concrete runtime result:
- local Salvium mined blocks successfully through the pool
- public Salvium testnet accepted shares cleanly through the pool on current Carrot-era templates
- local Peya accepted shares and mined blocks successfully through the pool after the util gained the Peya block adapter
- local Monero regtest accepted shares and mined blocks successfully through the pool after the util gained the monero-family adapter
- local fastfork Zephyr testnet accepted shares and mined blocks successfully through the pool after the util gained the zephyr-family adapter

Pool Compatibility Scope

for the current solo-mining milestone, the minimum compatibility set is:
- current carrot-only address validation for Salvium
- current carrot-only address validation for Peya
- current asset-aware transfer fields for Salvium/Peya payout code
- blocktemplate parsing for:
  - current Monero
  - current Salvium
  - current Peya
  - current Zephyr
legacy/carrot transition logic from earlier Salvium experiments is no longer considered part of the target architecture