# MESO PROTOCOL

> On-chain specimen protocol on BNB Smart Chain. Fixed supply 3000 NFTs, five on-chain stages,
> 5% ERC-2981 royalty shared with ascended holders. Rules live in the contract; no off-chain promises.

## MCP (one-line agent onboarding)
mcp add meso https://hongwu.cloud/meso/mcp

Tools (read-only, no keys needed):
- meso_overview        contracts, supply, fees, floor prices
- meso_specimen        one specimen: stage, rarity, xp, owner, listing, offer
- meso_specimens       recent specimens from the on-chain index
- meso_reserve         reserve buckets + public allocation
- meso_excavation_rules  fixed-amount table, open state, expected value
- meso_verify          recompute one excavation (message + digest + weight table)
- meso_contracts       addresses + function signatures for local signing
- meso_docs            protocol summary and links

Writes are never done for you: get addresses/signatures from meso_contracts and sign locally.

## Contracts (BNB Smart Chain, chainId 56)
- NFT (ERC-721): 0x054237fe97dad04FB51526dB15aA386075054710
- Marketplace (list / buy / offers): 0xc88244FbCEdF927D7BBBc05B8f3090979d903281
- Floor fund (ascended buyback): 0x297F97be9f16bec1f85c1A8d37b0eca9C9B68dF3
- Source verification: https://sourcify.dev/#/lookup/0x054237fe97dad04FB51526dB15aA386075054710

## Machine-readable
- Live stats JSON: https://hongwu.cloud/meso/api/stats
- Agent manifest: https://hongwu.cloud/meso/agents.json
- Agent guide: https://hongwu.cloud/meso/agents.md
- ABI: https://hongwu.cloud/meso/meta/abi.json
- Traits + rarity table: https://hongwu.cloud/meso/meta/traits.json

## What it is
1. Mint an egg (stage 0). Rarity is hidden until hatch.
2. Hatch after the hatch delay (1h at time of writing; read the live value of hatchDelay()): rarity becomes public (common 55% / rare 30% / epic 12% / legendary 3%).
3. Feed on a cooldown (1h at time of writing; read live value from /api/stats) to gain XP; higher rarity earns more XP per feed.
4. Evolve at XP thresholds: hatchling (1) -> juvenile (2) -> adult (3) -> ascended (4).
5. Ascended supply is capped (300). Royalty revenue is split with ascended holders.

## Parameters (read live values from /api/stats)
- maxSupply 3000, ascended cap 300, max 3 per wallet
- public mint 0.002 BNB per specimen, hard cap 3 per wallet; no free-mint coupons are issued
- hatch fee 0.0002 BNB
- feed fees 0.00005 / 0.0001 / 0.00015 BNB by stage (hatchling / juvenile / adult)
- market fee 2%; royalty 5%

## How to interact (programmatic)
- Read: plain JSON-RPC eth_call against https://hongwu.cloud/meso/rpc or any BSC node.
- Write: standard signed transactions to the NFT or marketplace contract.
- Machine quickstart: GET https://hongwu.cloud/meso/quickstart.json (contracts, prices, steps, risks in one JSON),
- Zero-cost trial: GET https://hongwu.cloud/api/meso/simulate — all-in cost per rarity, feeds needed, hours to ascend. Read-only, nothing signed, no wallet needed.
- Build the tx for me: GET https://hongwu.cloud/api/meso/action?address=<wallet>&step=mint|hatch|feed|evolve&tokenId=<id>
  returns {chain_id, to, data, value_wei} ready to sign; the server eth_calls it first and reports the real revert
  (cooldown / not owner / too early / not enough xp) instead of guessing.
- What can I do now: GET https://hongwu.cloud/api/meso/actions?address=<wallet> — every specimen you own with its next step.

## Honest limitations
- Rarity derives from block hash, not a verifiable randomness beacon.
- Metadata and images are served from this domain, not IPFS.
- No floor price is promised. The floor fund only buys ascended tokens, and only while funded.
- Market data is only what the chain shows; zero trades means zero volume.

## Verification checklist for agents
1. GET /api/stats -> compare contract addresses and minted count.
2. eth_call maxSupply(), ascendedCap(), hatchFee(), feedCooldown() -> must match docs.
3. Check listings via marketplace listings(tokenId).