# Viridial operator playbook

## 1 — Route by intent

Use BNB Smart Chain 56. Plant at `0x9a17A906E58c9DdAc8E8559b183fE3c69c87aEe1` (ViridialPass; NFT Viridial Pass / VRDL), harvest at `0x009FC052895E276d8Eded526E486509F4137A4b9` (ViridialHarvest), receive `0xf15fE9535A90c5fA4e44300a37f5F48861cE8661` (ViridialCoin; Viridial Grain / VRDLG). Harvest deploys Pass and Coin itself: resolve `Harvest.CARDS()` / `Harvest.COIN()`, then require `Pass.HARVEST()` / `Coin.HARVEST()` to point back. Read `Pass.ID_REGISTRY()` from the chain. Do not interchange targets.

The final source offers no admin, pause, upgrade or withdrawal route. owner() is zero, FEE_SINK() immutable; ordinary calls retain no BNB because charged fees forward and unused value refunds atomically. Coin.SUPPLY_CAP() is fixed and only Coin.HARVEST() mints. Pass.MAX_SUPPLY() equals uint256 maximum. Source links: https://bscscan.com/address/0x9a17A906E58c9DdAc8E8559b183fE3c69c87aEe1#code ; https://bscscan.com/address/0x009FC052895E276d8Eded526E486509F4137A4b9#code ; https://bscscan.com/address/0xf15fE9535A90c5fA4e44300a37f5F48861cE8661#code . These require verified deployment addresses before use.

## 2 — Plant during an open phase

`2026-11-21 10:02:43 (UTC+8)` denotes the deployment reference, not a hardcoded sale date. Check `plantOpen()`, `PLANT_UNTIL()`, `PHASE()`, `currentPhase()`, `nextPhaseAt()` and `canMint(holder)` (ok, reason, nextAt; reasons 0 eligible / 1 closed / 2 missing identity / 3 quota used). One pass per caller-owned Agent ID per six-hour UTC phase while open. Preferred entry is Pass.freeMint(), value 0, gas limit 300000.

| Signature | Selector |
|---|---|
| `mint()` | `0x1249c58b` |
| `freeMint()` | `0x5b70ea9f` |
| `claim()` | `0x4e71d92d` |
| `mint(uint256)` | `0xa0712d68` |
| `publicMint()` | `0x26092b83` |
| `freeMint(uint256)` | `0x7c928fe9` |
| `mintFree()` | `0x8ab53447` |
| `claimFree()` | `0xf366afc9` |
| `agentMint()` | `0x1be3587a` |
| `mint(address)` | `0x6a627842` |
| `mint(address,uint256)` | `0x40c10f19` |
| `mint(uint256,address)` | `0x94bf804d` |
| `mintFree(uint256)` | `0xa4146733` |

Every free alias consumes the same caller-owned Agent ID quota. A positive quantity still gives one NFT; zero quantity reverts, except `mintFree(uint256)` ignores its argument including zero. `mint(address)` and `mint(address,uint256)` deliver to that recipient. `mint(uint256,address)` ignores its second argument. Prefer value 0; attached BNB is returned atomically. Network gas is separate.


## 3 — Tend the phase seed

`phaseOf(id)` or `info(id)` identifies the planting phase. `Harvest.matureAt(id)`, `maturePhaseOf(id)` and `nextRipeAt()` describe maturity: the next phase boundary, not six elapsed hours. An expired planting window does not prevent harvesting old passes.

Send `Pass.pushSeed(uint32)` for a finished phase, value 0, gas limit 300000. First registration sets revealAt to current block +5. `Pass.seedView(uint32)` returns (state, seed), **not** the height; use `Pass.revealAt(uint32)` for that. `Pass.phaseSeed(uint32)` is the saved seed. State 0 needs registration, 1 needs waiting strictly beyond the height, 2 can be frozen or harvested, 3 is frozen, 4 is permanently grade-0 Grain. `Pass.touch()` (value 0, gas limit 300000) progresses the last two finished phases with passes; planting and harvesting do that too. Explicit pushSeed can reach an older phase.

The reveal hash uses BLOCKHASH through 256 blocks and EIP-2935 through 8191 blocks, around one hour on BSC. If nobody freezes a seed inside that span, every pass in the phase settles as Grain, `grainFor(0)`. No re-roll and no caller choice; an already saved seed remains fixed. The validator producing the assigned reveal block can influence its hash. Current quotes from unsaved seeds must be rechecked.

## 4 — Assemble a paid harvest

Only these Harvest selectors open passes; `claim(uint256[])` is absent:

| Signature | Selector |
|---|---|
| `claim(uint256)` | `0x379607f5` |
| `claimMany(uint256[])` | `0x925489a8` |
| `claimBatch(uint256[])` | `0x62abebce` |
| `claimReward(uint256[])` | `0xc94c7ff4` |

Let F = `harvestFee()` wei. Quote `feeForCount(n)` / `affordable(value)` / `BATCH_LIMIT()` at the same block as the other reads.

照付款金額成交。批次能開幾張就依付款處理前幾張，零頭及未使用費用同筆退回；連一份費用都不足則回退。單張最多開一張，多付款同筆退回；未登記期的單張只登記並全額退款。

For a batch, examined count n = min(floor(value/F), ids.length, live batch limit). Only the first n IDs are examined. For owned, mature, unopened, seed-ready cards with sufficient rewards:

| IDs | Sent | Opened | Refunded |
|---|---|---|---|
| five | 3F + 1 wei | 3 | 1 wei |
| five | 6F | 5 | F |
| five | 3F - 1 wei | 2 | F - 1 wei |
| two | 5F | 2 | 3F |
| one | F + 1 wei | 1 | 1 wei |
| one | 2F | 1 | F |
| one, seed ready | F - 1 wei | revert | value never charged |

A single call is explicitly limited to its one ID even with extra payment. A batch skips unregistered/waiting seeds and full rewards exceeding the remaining token supply; skipped cards cost zero. Unregistered periods are registered. Never replace a skipped ID with an unpaid trailing ID. Refund = value - F * actuallyOpened. Invalid ownership, an already opened ID, or an immature card in the examined prefix reverts the whole call; duplicates that would open twice also revert. Single pool-short calls revert. Base rewards are never clipped. Bare BNB transfers and unknown selectors revert; payee/refund failure reverts atomically.


`gradeOf(id)` is 255 while UNRIPE, 0..3 when known; `payoutOf(id)` and `harvestable(id)` quote current availability. Read `harvested(id)` to distinguish historical payouts. Grain is a project token, not BNB.

## 5 — Price a set

Batch aliases alone add a bonus. Read bonusBps(2)=500, bonusBps(3)=1500, bonusBps(4)=4000 (5%, 15%, 40%). Count the distinct grades of actually opened passes, **including ordinary Grain for expired phases**. Sum full base amounts from grainFor(); add min(floor(base*BPS/10000), remaining after base). Only the bonus may be clipped.

`quoteMany(ids)` returns counted, cost, baseCoins, distinct, bonus. It omits unready passes but does not enforce ownership, duplicates, payment-limited prefix or BATCH_LIMIT. Pass only a separately validated ordered paid prefix to the quote, then simulate the exact original transaction. A seed registration changes chain state even if zero passes open.

## 6 — Encode and sign once

Read minted IDs from receipt events; the following IDs are examples, not existing NFTs. Replace IDs and all placeholders, ABI-encode with the published ABI, then simulate the exact from/to/data/value. Single opening calldata for ID 1 is `0x379607f50000000000000000000000000000000000000000000000000000000000000001`. Batch [1,2,3,4,5] calldata is:

```text
0x925489a80000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000500000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000300000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000005
```

Free transaction template:
```json
{"from":"<Agent ID holder>","to":"0x9a17A906E58c9DdAc8E8559b183fE3c69c87aEe1","data":"0x5b70ea9f","value":"0x0","gas":"0x493e0"}
```

For a ready single ID send value F, or F+1 to verify a 1 wei refund; for the example batch send 3F+1 to inspect three IDs and refund 1 wei. Compute F in integer wei from the getter, never floating point. With an UNREGISTERED mature period, sending the single call with F succeeds, records a future reveal height, opens zero cards and returns ALL F. Gas is still paid. Check the new reveal height, wait strictly past it and repeat preview before paying to open. While already registered but waiting, single calls revert SeedNotReady; batches instead skip without fee.


Harvest single gas limit is 300000; batch is 150000+100000*n, n including skipped IDs. Read price, maturity, grade and token room at a common block. Require the three address relationships, chain 56, correct account and current ownership. eth_call exact from/to/calldata/value; compare eth_estimateGas to the cap. Present the cost, refund, token amount and target; after approval recheck the quote and send once. Confirm receipt status and PassOpened/BatchDone/SetBonus events. Unknown or pending receipts need investigation, not automatic retries. No approval, typed data or message signature is needed.

## Compiled getter directory

| Contract | Getter | Selector |
|---|---|---|
| ViridialPass | `HARVEST()` | `0x4f3c9862` |
| ViridialPass | `ID_REGISTRY()` | `0xa8f301e8` |
| ViridialPass | `MAX_SUPPLY()` | `0x32cb6b0c` |
| ViridialPass | `PHASE()` | `0xb8eb8e61` |
| ViridialPass | `PLANT_UNTIL()` | `0x5cdd264b` |
| ViridialPass | `balanceOf(address)` | `0x70a08231` |
| ViridialPass | `canMint(address)` | `0xc2ba4744` |
| ViridialPass | `currentPhase()` | `0x055ad42e` |
| ViridialPass | `getApproved(uint256)` | `0x081812fc` |
| ViridialPass | `identityOf(address)` | `0xc6345626` |
| ViridialPass | `info(uint256)` | `0x2e340599` |
| ViridialPass | `isApprovedForAll(address,address)` | `0xe985e9c5` |
| ViridialPass | `name()` | `0x06fdde03` |
| ViridialPass | `nextPhaseAt()` | `0xa1f4ea9f` |
| ViridialPass | `owner()` | `0x8da5cb5b` |
| ViridialPass | `ownerOf(uint256)` | `0x6352211e` |
| ViridialPass | `phaseOf(uint256)` | `0x9a243ebf` |
| ViridialPass | `phaseSeed(uint32)` | `0xefdff798` |
| ViridialPass | `plantOpen()` | `0xd3ab0e4a` |
| ViridialPass | `plantedIn(uint32)` | `0xa55cc45d` |
| ViridialPass | `revealAt(uint32)` | `0xb65eb7f4` |
| ViridialPass | `seedView(uint32)` | `0x960064ea` |
| ViridialPass | `supportsInterface(bytes4)` | `0x01ffc9a7` |
| ViridialPass | `symbol()` | `0x95d89b41` |
| ViridialPass | `tokenURI(uint256)` | `0xc87b56dd` |
| ViridialPass | `totalSupply()` | `0x18160ddd` |
| ViridialHarvest | `BATCH_LIMIT()` | `0x9559c0bd` |
| ViridialHarvest | `CARDS()` | `0x85698fed` |
| ViridialHarvest | `COIN()` | `0xa54a72b7` |
| ViridialHarvest | `FEE_SINK()` | `0x12bb5fd4` |
| ViridialHarvest | `UNRIPE()` | `0x74954eb7` |
| ViridialHarvest | `affordable(uint256)` | `0xdc86e25f` |
| ViridialHarvest | `bonusBps(uint256)` | `0x300adb21` |
| ViridialHarvest | `coinsLeft()` | `0xefd0f59b` |
| ViridialHarvest | `currentPhase()` | `0x055ad42e` |
| ViridialHarvest | `feeForCount(uint256)` | `0x06ab396f` |
| ViridialHarvest | `gradeForRoll(uint256)` | `0xe47fde84` |
| ViridialHarvest | `gradeOf(uint256)` | `0x1ac9a7d2` |
| ViridialHarvest | `grainFor(uint8)` | `0x1e4b888c` |
| ViridialHarvest | `harvestFee()` | `0xb5962917` |
| ViridialHarvest | `harvestable(uint256)` | `0x0fe71094` |
| ViridialHarvest | `harvested(uint256)` | `0x17ab5b9a` |
| ViridialHarvest | `matureAt(uint256)` | `0xf05b893f` |
| ViridialHarvest | `maturePhaseOf(uint256)` | `0xfba73978` |
| ViridialHarvest | `nextRipeAt()` | `0x60885322` |
| ViridialHarvest | `owner()` | `0x8da5cb5b` |
| ViridialHarvest | `payoutOf(uint256)` | `0xdd14fde2` |
| ViridialHarvest | `quoteMany(uint256[])` | `0xef27f647` |
| ViridialCoin | `HARVEST()` | `0x4f3c9862` |
| ViridialCoin | `SUPPLY_CAP()` | `0x0cfccc83` |
| ViridialCoin | `allowance(address,address)` | `0xdd62ed3e` |
| ViridialCoin | `balanceOf(address)` | `0x70a08231` |
| ViridialCoin | `decimals()` | `0x313ce567` |
| ViridialCoin | `name()` | `0x06fdde03` |
| ViridialCoin | `owner()` | `0x8da5cb5b` |
| ViridialCoin | `symbol()` | `0x95d89b41` |
| ViridialCoin | `totalSupply()` | `0x18160ddd` |

Explicit seed action: `pushSeed(uint32)` at `0x9a17A906E58c9DdAc8E8559b183fE3c69c87aEe1`, selector `0x29f766a6`, value 0, gas limit 300000.
Pass progression: `touch()` selector `0xa55526db`, target `0x9a17A906E58c9DdAc8E8559b183fE3c69c87aEe1`, value 0, gas limit 300000.
