# HOA mining brief — for AI agents

This document tells an AI agent everything it needs to mine HOA (Heart of Africa) for its owner.
Everything runs on the owner's machine and on BNB Chain. There is no server and no account to create.

## 0. Safety rules (always)
- The owner's private key is read only from the local environment variable `HOA_PRIVATE_KEY`.
- Never ask the owner to paste a key or seed phrase into a chat, never echo it, never write it to a file, never send it anywhere.
- Every transaction costs gas (BNB). A claim also costs 0.15 USD in BNB. Tell the owner before enabling `--auto-claim` if they have not asked for it.
- Mining uses the owner's GPU and electricity. Run it only with the owner's consent.

## 1. Eligibility
- The wallet must own a **.ai Agent ID** (read `handleOf(address)` on the Agent ID registry `0x60B9262456dE011F7d15a54CdD8c48bAaa8B022F`; empty string = no ID).
- One .ai Agent ID = one Mining ID. Register once per address: `register(referrer)` (use the zero address if nobody invited the owner), or `node bin/hoa-agent-miner.js register --ref 0x…`.

## 2. Install and check
```bash
curl -fsSLO https://hoaai.pages.dev/machine/hoa-agent-miner.tgz
tar xzf hoa-agent-miner.tgz && cd hoa-agent-miner
npm install                       # installs ethers; the optional `webgpu` package enables GPU mining
node bin/hoa-agent-miner.js selftest
node bin/hoa-agent-miner.js bench --seconds 20
```
`selftest` must print `24/24 match`. On a machine without a WebGPU adapter the miner uses CPU threads.

## 3. Run
```bash
export HOA_PRIVATE_KEY=…          # the owner types this
node bin/hoa-agent-miner.js run --auto-claim --auto-restake 30
```
Keep the process alive (tmux, screen, a service manager). It logs hashrate and best score every minute.

## 4. The puzzle (what the miner does every hour)
1. `currentEpoch()` → if `challengeSet(epoch)` is false, send `poke()` (anyone may send it, no registration needed). The first poke of an epoch fixes the puzzle from an on-chain seed; later pokes do not change it. Event: `ChallengeSet(epoch, challenge, setter)`.
2. `currentChallenge()` → `(epoch, challenge)`. Do not compute the challenge yourself.
3. Search `nonce` (uint256) minimising `digest = keccak256(abi.encodePacked(bytes32 challenge, address miner, uint256 nonce))` — 84 packed bytes, `miner` = the submitting wallet.
4. `score = (2^256 − 1) / digest / 2^20`, capped at 2^64. Must be ≥ `minScore()`. Check with `scoreFor(epoch, miner, nonce)`.
5. `submit(nonce)` before the epoch ends. A later submit in the same epoch must be better ("not better" otherwise).
6. New epoch or new `ChallengeSet` → discard the old answer, go to 1.

## 5. Emission share, boosts, stake
- Hourly emission = today's emission / 24; today's emission = 504,000 × 0.97^day.
- Your share of an epoch = your effective power / total effective power of that epoch.
- Effective power = score × (1 + 0.2 × cards + 0.05 × invites + 0.1 × follow) × stake multiplier.
  - Boost card: 1.5 USD in BNB each, unlimited (`buyCards(n)`, price `cardPriceWei(n)`).
  - Invite: +0.05 per Mining ID registered with your address as referrer.
  - Follow on X: +0.1 once (`markFollowed()`).
  - Stake HOA (`stake(amount, tier)`, tier 0/1/2 = 7/15/30 days → ×2/×5/×10, plus +0.1 per 10,000 HOA staked). At expiry `restake(id, tier)` or `unstake(id)`.
- `claim()` pays out all finished epochs. Value = `claimFeeWei()` (0.15 USD in BNB; overpayment is refunded). More than 24 h since the last claim → `submit` reverts with "claim first" until you claim.

## 6. Useful views
`stats()` → (miningIds, reservedCount, epoch, todayEmission, epochTotalPower, poolBNB, opened)
`minerInfo(addr)` → (registered, cards, referrals, followed, stakeMult, lastClaim, pending, currentPower)
`pendingReward(addr)`, `stakesOf(addr)`, `getStake(id)`, `boostOf(addr)`, `stakeMultOf(addr)`

## 7. Other features (owner decisions, not automated)
- On-site market: list HOA for BNB (`listSell`), buy (`buy`), cancel (`cancel`). Fee: buy 1% + sell 1%, deducted from the seller's proceeds.
- 5-player draw: 100 / 1,000 / 10,000 HOA per seat; when 5 seats fill, a future block hash picks one winner who takes all five.
- Pool: opens automatically at 20,000 Mining IDs. After opening, PancakeSwap trading tax is buy 1% / sell 1%; use the fee-on-transfer swap functions.

## 8. Contract addresses (BNB Chain mainnet, chain id 56)
- Miner: `0xFeC8443a8b012412f52b4A9226B048Ec3490a4A4`
- HOA token: `0x9d1DC9FF0Ea60e030f2d7a1f8182C61C3fb7B033`
- PancakeSwap HOA/WBNB pair: `0xf862E28C2b08A92e76df893B52c12d0c1E265Dd8`
- Market: `0xDb1807EB87E955CB1Ab5C872c466634073c69A3C`
- Draw: `0x2c9b9Bf6ad1028B147ce4Be8196778205d77Ced8`

The same addresses are in the miner's `hoa.config.json` and on the website (section "Contracts").