# Pyrevow: operator guide

Chain: BNB Smart Chain (56). Contract **Pyrevow Relics** (PYRV, ERC-721): `0xA46c0048dE23BFEBEbb55e2adCe9AcD51c88652a`. Coin **Pyrevow Ash** (PYRVA, ERC-20): `0x4f66ae82b046e02a5ee417406a929bb6a43e436a`. Both are verified on BscScan:
- https://bscscan.com/address/0xA46c0048dE23BFEBEbb55e2adCe9AcD51c88652a#code
- https://bscscan.com/address/0x4f66ae82b046e02a5ee417406a929bb6a43e436a#code

Before you spend, confirm on chain: `PyrevowRelics.ASH()` equals the Ash address, `PyrevowAsh.RELIC_HOUSE()` equals the Relics address, and `owner()` is the zero address on both. There is no owner, admin, pause, upgrade or withdraw function. Every fee is forwarded to the immutable `COLLECTOR()` in the same transaction, anything over the price is returned in the same transaction, and the contract keeps no BNB. Ash has a fixed cap of 1,200,000,000 (`ASH_CAP()`), and only the Relics contract can issue it. Ash is described by quantity only: nothing here promises a price, a listing or a return.

## What it is

A relic is taken, then settled exactly once, one of two ways.

- **Keep**: `claim(uint256 id)`. Pay `keepFee()` = 0.00025 BNB, receive 3,000 Ash. The relic stays with you, marked Held, and can be transferred.
- **Burn**: `claimBurn(uint256 id)`. Pay `burnFee()` = 0.0005 BNB, receive 12,000 Ash. The relic is destroyed for good and cannot be restored.
- **Keep, then burn later**: a Held relic can still be burned once for 0.0005 BNB and receives the 9,000 Ash difference. In all that is 0.00075 BNB for 12,000 Ash.
- **Paying more never switches the route**: a keep with extra payment is still a keep, and the extra comes back. A burn with less than `burnFee()` reverts; it never falls back to a keep.

**Taking relics**
- Gift: a wallet that holds an Agent ID takes one relic per UTC day for no fee but gas, while the day's `GIFT_SLOTS_PER_DAY()` = 2,000 gifts last (shared by everyone; first come, first served).
- Bought: any wallet, Agent ID or not, pays `relicPrice()` = 0.0003 BNB per relic: at most `BOUGHT_PER_WALLET_DAY()` = 30 per wallet per UTC day and `BUY_LIMIT_PER_TX()` = 30 per call.
- At most `RELIC_CEILING()` = 100,000 relics are ever issued, gifts and bought together. 100,000 x 12,000 equals the Ash cap, so every relic issued can always be settled, whichever way its holder chooses.
- Windows (read live): relics can be taken from `doorsOpen()` to `doorsClose()`: 2026-11-21 13:38:25 (UTC+8) to 2026-12-21 13:38:25 (UTC+8). Settling is open until `settleUntil()` (7 days after the doors close): 2026-12-28 13:38:25 (UTC+8).

Read every number from the getters; the values above are the deployment values.

## 1. Take a relic (entry call)

All of these do the same thing: `mint()` `0x1249c58b`, `mint(uint256)` `0xa0712d68`, `mint(address)` `0x6a627842`, `mint(uint256,address)` `0x94bf804d`, `mintFree()` `0x8ab53447`, `mintFree(uint256)` `0xa4146733`, `freeMint()` `0x5b70ea9f`, `freeMint(uint256)` `0x7c928fe9`, `claim()` `0x4e71d92d`, `claimFree()` `0xf366afc9`, `publicMint()` `0x26092b83`, `agentMint()` `0x1be3587a`, and plain BNB with no calldata. Prefer `mint()`.

Arguments never change the result: relics always go to the caller, an address is not a recipient, a number is not a quantity. `claim()` with no argument takes a relic; `claim(uint256 id)` keeps one (section 2).

**The contract settles by the amount you send** (照付款金额成交):

1. If the caller holds an Agent ID (checked live against the registry), has not taken today's gift, today's gifts are not used up and relics remain, it gets one relic with no fee. Value 0 is enough.
2. The rest of the payment buys `min(floor(value / relicPrice()), 30 per call, 30 minus what this wallet bought today, relics left under the ceiling)` relics.
3. Everything not used is returned in the same transaction, including any amount over the limits.
4. If the gift was given and the rest is under one relic, the gift is issued and the whole payment is returned.
5. If neither a gift nor a bought relic can be issued, the call reverts and takes nothing: `GiftNeedsAgentId(price)` (value 0, no Agent ID), `GiftAlreadyToday(nextAt, price)`, `GiftsGoneToday(nextAt, price)`, `RelicPriceUnmet(price, sent)` (some value, under one relic), `DailyBuyCap(bought, cap)`, `AllRelicsIssued(ceiling)`, `DoorsShut(opens, closes)`.

A gift and bought relics can come in the same call.

**Quote first**: `relicsFor(address who, uint256 value)` `0x0edd89c3` returns `(bool gift, uint256 bought, uint256 spent, uint256 refund, bool ok)`; `ok` false means the real call reverts. Also `giftReady(address)`, `buyRoomToday(address)`, `giftsLeftToday()`, `relicsLeft()`.

Examples (price 300000000000000 wei; wallet with room and no gift): value 0 -> reverts without an Agent ID; 299999999999999 -> reverts (`RelicPriceUnmet`) without an Agent ID; 300000000000000 -> 1 bought, 0 returned; 300000000000001 -> 1 bought, 1 wei returned; 900000000000000 -> 3 bought; 10000000000000000 (33.3 prices) -> 30 bought (per-call limit), 1000000000000000 returned. With an eligible Agent ID, add the free relic to each.

**gasLimit** (BSC fork measurements, with margin): free relic 170,000; first buy of 1 relic 200,000; gift plus 3 bought 280,000; buying n relics 200,000 + 30,000 x n (30 relics 1,100,000); plain BNB `max(400,000, 200,000 + 30,000 x n)`, never 2,300, plus 50,000 more if the transaction may cross UTC midnight. Prefer `eth_estimateGas` from the exact sender and value, plus 30%.

## 2. Settle

Only the holder can settle. A relic is settled in the window from `doorsOpen()` to `settleUntil()`.

- `claim(uint256 id)` `0x379607f5`, value >= `keepFee()`. Keeps this one relic; extra payment is returned and never turns it into a burn. Reverts `HoldFeeUnmet(fee, sent)`, `NotRelicHolder(id)`, `RelicAlreadySettled(id, state)`.
- `claimBurn(uint256 id)` `0xcb0c0be1`, value >= `burnFee()`. Burns this one relic. Receives 12,000 Ash (9,000 if it was already Held). Reverts `BurnFeeUnmet(burnFee, keepFee, sent)`, `NotRelicHolder`, `RelicAlreadySettled`. Irreversible: do not send it without the holder's explicit choice.
- `claim(uint256[] ids)` `0x6ba4c138` and `claimBurn(uint256[] ids)` `0xd2129091`: settle in list order `floor(value / fee)` relics (at most the list, list of 1 to `SETTLE_LIST_MAX()` = 40 ids, else `ListSize(40)`), return the rest. A bad id inside the paid prefix (not yours, already settled, duplicate) reverts the whole call; ids beyond the paid prefix are not checked.

**Preview**: `outcomeOf(uint256 id, bool burn)` `0xd8ef4676` returns `(fee, ashOut, destroys, holder, ok, reason)`. `reason` is one of `NO_SUCH_RELIC`, `ALREADY_BURNED`, `ALREADY_HELD`, `NOT_OPEN_YET`, `SETTLING_ENDED`, `ASH_CAP_REACHED`, or empty. `ok` does not check the caller: compare `holder` with your own address. `relicState(id)` is 0 open, 1 held, 2 burned, 3 none. `settleCost(n, burn)` quotes n relics.

**gasLimit**: `claim(id)` 180,000; `claimBurn(id)` 180,000; `claim(ids)` 120,000 + 40,000 x n; `claimBurn(ids)` 120,000 + 35,000 x n. Prefer `eth_estimateGas` plus 30%.

## 3. Safe operating procedure

1. Check chain id 56, both addresses, `owner()` zero, `ASH()` and `RELIC_HOUSE()` matching.
2. Read the window (`doorsOpen`, `doorsClose`, `settleUntil`), the three prices, and the quote (`relicsFor` or `outcomeOf`).
3. Simulate the exact call with `eth_call` (same from, to, data, value). Stop on any revert.
4. Estimate gas and add 30%. Show the user the target, value, Ash or relics expected, and whether the relic is destroyed.
5. Send once. No approval and no message signature are needed. A transaction hash is not a result: check the receipt, then `RelicsIssued`, `RelicHeld`, `RelicAshed` events and `balanceOf` on the Ash contract.

## Getters

`relicPrice` `keepFee` `burnFee` `doorsOpen` `doorsClose` `settleUntil` `COLLECTOR` `ASH` `HANDLE_REGISTRY` (Agent ID registry `0x60B9262456dE011F7d15a54CdD8c48bAaa8B022F`) `RELIC_CEILING` `GIFT_SLOTS_PER_DAY` `BOUGHT_PER_WALLET_DAY` `BUY_LIMIT_PER_TX` `SETTLE_LIST_MAX` `HOLD_YIELD` `BURN_YIELD` `REBURN_YIELD` `SETTLE_GRACE` `relicsMinted` `relicsLeft` `heldCount` `burnedCount` `reburnedCount` `totalSupply` `giftsLeftToday` `giftReady(address)` `buyRoomToday(address)` `handleKeyOf(address)` `currentDay` `nextDayAt` `ashLeft` `ashOwedAtMost`, plus the standard ERC-721 functions. Ash: standard ERC-20 plus `ASH_CAP`, `RELIC_HOUSE`, `unissued`, `owner`.

Unknown selectors revert `PyrevowNoSuchCall(bytes4)`, with or without BNB.
