# Woodlandz: Agent Skill

Read this file and https://woodlandz.xyz/llms.txt before acting. All addresses are on BNB Smart Chain, chainId 56 (0x38). Amounts of $WOOD are in wei (18 decimals). Rates are $WOOD per hour, in wei.

## Project

Woodlandz is a chop-to-earn game on BNB Smart Chain. Players mint Logger NFTs. A revealed Logger auto-mines $WOOD at its tier rate, hour after hour, even while the holder is offline. Mining comes only from holding Logger NFTs. The Lumber Hall (Townhall) is the Market where Loggers are bought and sold in USDT. The other 6 buildings (Sawmill, Log Camp, Workshop, Cabin, Tool Shed, Storage Yard) give boosts and capacity. In-game $WOOD = token $WOOD 1:1: claiming in the game claims the token on-chain. The website is https://woodlandz.xyz, the game is https://play.woodlandz.xyz, and the X account is https://x.com/woodlandz_xyz.

## Contracts

The live deployment below is the TEST deployment: the Punch In contracts stand in for the Woodlandz contracts, by the project's own direction, with the same functions. The real $WOOD contracts will replace these addresses with the same function names. Until then, use these addresses exactly.

- Logger NFT (MineCard contract standing in for the Logger NFT): 0xF8A72C4538Cd9d570B2C771f01A0d561a90A64Eb
- Woodlandz Mining (PunchInMining standing in for the game contract): 0x6ed42b9a51fbe6648E42B1a4643168321e22d0aA
- $WOOD (PUNCHIN BEP-20 standing in for $WOOD): 0x3Bbd25AA231F0f2e0bF3dCEba8Af45B5a4A46144
- Townhall Market (MineCardMarket): 0x0510670186c9424de18501a81dD2a4E74b6eaA2E
- USDT (BEP-20, for Market buys): 0x55d398326f99059fF775485246999027B3197955
- Agent ID registry (Binance Agent ID): 0x60B9262456dE011F7d15a54CdD8c48bAaa8B022F
- Payout wallet (receives all mint BNB, immutable): 0x828551d3baa692058d7b6a33ad980609da4166a3
- Owner: 0xD87546aff805399BDaC04f4a8D99fD3e942D5A74

The contracts are Sourcify verified. The full ABIs are embedded in the test game at https://woodlandz-test.pages.dev (assets/woodlandz-real.js) and in the deploy page at https://punch-in-mine-deploy.pages.dev.

Giving an agent the Logger NFT contract address alone is enough to start: from it, this skill lists the Mining contract, the token, the Market, and the registry. The agent needs nothing else except the user's wallet.

## Real $WOOD contracts (spec locked 2026-11-21)

The live deployment above is the test deployment. The real $WOOD contracts will use this locked spec, with the same function names:

- Payout wallet: 0xd40d76b961d82d2d9b4b00bb7454c3c7b17175d4. Mint BNB forwards to this wallet in the same mint tx (SAGENT pattern, set once in the constructor, immutable, contract balance stays 0).
- Royalty 1% fixed, collected by the owner.
- Agent ID gate on mint.
- Treasury: 5 Logger NFTs.
- Reveal: sealed, revealBlock = mint block + 1 (1-block reveal).
- Bug Report 5% (50,000,000 $WOOD) goes to wallet 0x55965bdfcd97f5ae7f02e62aeced2db4cf7d6087; the owner distributes to bug reporters from that wallet.
- Liquidity 40% (400,000,000 $WOOD) goes to the payout wallet 0xd40d76b961d82d2d9b4b00bb7454c3c7b17175d4; the owner holds it and adds LP manually.
- Townhall Market = Punch In style (PXIO model: fixed USDT prices per tier, FIFO, USDT only). Locked tier prices: T1 1 / T2 2 / T3 4 / T4 6 / T5 8 USDT. The owner collects the 1% royalty on sales. Sell/cancel fee stays as before (PXIO-style 0.0002-0.0003 BNB).
- Still open: Game 55% (550,000,000 $WOOD) goes to the WoodlandzMining contract, funded at deploy.
- Deploy page: https://woodlandz-deploy.pages.dev/ (contracts written and tested, 46/46 hardhat tests pass).
- REAL contracts, DEPLOYED and verified on-chain 2026-11-21 (owner 0x4E0030A298e7cd8C2031A9E23DBE65115516ec3d): $WOOD Token 0xDE31a73D486C7418aE943822b4f1B59FC7Ec4b66, Logger NFT 0xcC3eB3055F011bB01C211Ae8B4452164B7e31850, LoggerMarket 0xcd7C5D4D80766a073209014Ae3Ca17a0d63675eF (prices 1/2/4/6/8 USDT), WoodlandzMining 0x4355e2e9dE65A209A45456081dEb1aAE5036cd91 (funded 550,000,000 $WOOD). Treasury 5/5 minted. Mint is NOT open yet (mintOpen false); baseURI not set (metadata/IPFS pending).

## Connecting

The agent connects with a Binance Agentic Wallet. The website generates a pairing QR and a short pairing code; the user scans it with the Binance App (Agentic Wallet, Developer Mode ON) and confirms in the app. The wallet must hold a Binance Agent ID to mint. The game at https://play.woodlandz.xyz (live game) and https://woodlandz-test.pages.dev (test game) both have this connect flow. Never ask for or use the user's private key.

## Who can mint

- Only wallets holding a Binance Agent ID (registry balanceOf > 0), including the owner's.
- Max 20 Logger NFTs per wallet, counted across all mints.
- Supply on the live test contract is 8,888. The real Logger NFT supply is 9,999. Read totalMinted() live before minting.

## Price per Logger (by the wallet's own running count)

The price ladder is PER WALLET, not global. Every wallet follows the same ladder on its own mint count. Always read costForQty live: it is the only exact quote. Never send more than the quote.

Planned Woodlandz ladder (real contracts): 1st Logger FREE, 2nd-10th 0.0005 BNB each, 11th-20th 0.0009 BNB each. 20 Loggers total 0.0135 BNB.

Live test contract ladder (MineCard): 1st FREE, 2nd-5th 0.0005 BNB, 6th-10th 0.001 BNB, 11th-15th 0.002 BNB, 16th-20th 0.004 BNB. 20 cards total 0.037 BNB. A multi-card mint prices each card by its position on the caller's ladder.

## Mint procedure

1. Read hasAgentId(wallet) (0x4eab3ef2). It must be true.
2. Read mintedBy(wallet) (0x3cef28d2) and totalMinted() (0xa2309ff8) and mintOpen() (0x24bbd049). The mint must be open and the wallet cap and supply must not be exceeded.
3. Read costForQty(wallet, qty) (0x3d7f7e00). This is the exact BNB value to send. You can also read priceForWallet(wallet) (0x8bef67c3) for the next single Logger price.
4. Call mintCard(uint256 qty) (0x60b47a50) with value = costForQty, chainId 56. The mint returns the first tokenId. Each minted Logger gets revealBlock = block.number + 3.

## Reveal procedure

The tier is RANDOM (gacha), drawn from the hash of the block 3 blocks after the mint.

1. Read revealBlock(tokenId) (0x53a06804). Wait until the current block number is past it (about 9 seconds).
2. Call reveal(tokenId) (0xc2ca0ac5) or revealBatch(uint256[] tokenIds) (0x75ef961f) to reveal many at once. Anyone can call it. Value 0.
3. If the reveal block is more than 256 blocks old, the draw falls back to the latest blockhash mixed with the tokenId, so a late reveal still works.
4. Read tierOf(tokenId) (0x53f96df2): 0 = still sealed, 1-5 = tier. Read tierName(tier) (0xc1959a6b) and tierRate(tier) (0xaa3b9225) for the name and rate. The on-chain tier names are the test contract's names; the Woodlandz display names for the same tiers 1-5 are T1 Apprentice, T2 Lumberjack, T3 Master Logger, T4 Forest Legend, T5 Timber Titan.
5. A sealed Logger mines nothing. Accrual starts at the Logger's reveal time (revealedAt(tokenId), 0xe7e2de69).

Tier odds: T1 Apprentice 40%, T2 Lumberjack 30%, T3 Master Logger 18%, T4 Forest Legend 9%, T5 Timber Titan 3%.

## Mining $WOOD (fully on-chain, Mining contract)

- Mining needs at least one revealed Logger in the wallet. Everything is computed by the contract.
- Holding a revealed Logger is enough. Accrual starts at reveal time.
- Rates per Logger: T1 Apprentice 5, T2 Lumberjack 10, T3 Master Logger 20, T4 Forest Legend 40, T5 Timber Titan 80 $WOOD per hour. Loggers stack: the wallet rate is the sum of every revealed Logger held.
- Read rateOf(wallet) (0xcbf09802) for the wallet's total rate and pendingOf(wallet) (0xf44136a1) for the pending $WOOD right now. pendingOf returns settled pending plus live accrual from every revealed Logger, capped at the wallet's storage capacity.
- When storage is full, mining pauses until the holder claims. Accrual lost to a full storage is gone.
- Mining runs continuously, hour after hour.

## Claim

- Read pendingOf(wallet) first and tell the user the amount and the storage cap.
- Call claim() (0x4e71d92d), value 0. It pays the caller's exact pending $WOOD. Claim anytime, with only gas to pay.
- $WOOD arrives in the wallet in the same transaction (event Claimed(holder, amount)).
- If the fund holds less than the full pending amount, the claim pays what the fund holds and the remainder stays pending for a later claim after the owner tops the fund up. Read fundBalance() (0x3c067945) to check the fund first.
- A claim with nothing pending reverts with "Nothing to claim". A claim when the fund is empty reverts with "Mining fund empty".
- Read totalClaimed() (0xd54ad2a1) for the lifetime claimed total.

## Storage upgrades (optional)

- Read storageCapacity(wallet) (0x80dd13f2): level 0 holds 100 $WOOD. Each level adds 100.
- Read upgradeCost(wallet) (0x76d3673e): level L to L+1 costs 50 x (L+1) $WOOD (L0 to L1 = 50, L1 to L2 = 100, and so on). Max level 100 (capacity 10,100 $WOOD).
- Upgrade one level at a time: approve the Mining contract on the $WOOD token for the cost, then call upgradeStorage() (0x85035a85). The payment stays in the Mining contract and joins the mining fund. Preview both transactions and wait for confirmation.
- The pending amount is settled at the OLD cap before the cap rises.
- Suggest claiming before pending reaches the cap, because a full storage stops mining. Suggest upgrading storage only when the wallet's rate fills the cap faster than the holder claims.

## Gameplay (the game at play.woodlandz.xyz)

- The game is the visual front end for the same on-chain state: mint from HIRE, claim from CLAIM, reveal from the mint sheet.
- Loggers work in the village and keep earning while the holder is offline. Work stops only when Storage is full.
- The 6 non-Townhall buildings (Sawmill, Log Camp, Workshop, Cabin, Tool Shed, Storage Yard) give boosts and capacity in the game. The on-chain mining rate is the Logger tier rate; building boosts are the in-game layer on top of it.
- In-game $WOOD = token $WOOD 1:1. Claiming in the game calls the same on-chain claim().

## Townhall Market (buy and sell Loggers)

- The Market is the ONLY way Loggers change hands. Direct wallet-to-wallet transfers revert.
- Prices are fixed per tier in USDT, first in first out. Never hardcode a price: read prices() (uint256[5]) and availableAll() (uint256[5]) live before every buy.
- Read priceOf(tier) for one tier, available(tier) for how many are listed, queue(tier, start, count) for the listing order, isListed(tokenId) to check one Logger, activeListingsOf(address) for a wallet's listings, feeOf(address) for the fee.
- Buy: call buy(uint8 tier, uint256 qty). It takes the oldest listings of that tier. Pay in USDT: approve the Market on USDT first, then buy.
- Sell: call sell(uint256 tokenId) to list a Logger at its tier price. Cancel: call cancel(uint256 tokenId) to remove a listing.
- Sale split (live TEST market contract only): 80% of the sale goes to the seller, 20% is swapped to $WOOD. The 20% swap needs pool liquidity: it can revert on its slippage guard until real BNB liquidity is added to the $WOOD pool. If a buy or sell reverts, check the pool liquidity before retrying. The REAL Townhall Market pays 99% to the seller and 1% royalty to the owner (see "Real $WOOD contracts" above).
- The royalty is 1% fixed (ERC2981, 100 bps) to the payout wallet. It applies to market sales.

## Transfers

- Logger NFTs move ONLY to or from the Townhall Market contract. Direct wallet-to-wallet transfers revert.
- On every transfer the NFT notifies the Mining contract BEFORE ownership changes, so the sender's accrued $WOOD settles to the sender and the buyer starts fresh from the transfer time.

## Funding

- The mining fund is the Mining contract's $WOOD balance. It was funded with 1,999,993.13 at funding time.
- Claims pay out of this balance only. The supply is fixed at 1B.
- Funds leave only via claims.
- The owner can top the fund up later with fundMiningPool(amount) (0x748bfd52, owner only) or a plain token transfer.

## Live state (read it, do not trust this file)

- Mint OPEN, totalMinted 1,516 on the live test contract at the last check (2026-11-21 ~02:47 Yangon, direct chain read).
- totalClaimed was 151,626.39 $WOOD at the last check (2026-11-21 ~01:20 Yangon).
- Always read totalMinted(), mintOpen(), fundBalance(), pendingOf(wallet) and rateOf(wallet) live before every action.

## Rules for agents

- Never ask for or use the user's private key. Preview every transaction and wait for confirmation.
- Never send more than the quote from costForQty. The addresses in this file are the only valid ones.
- Never claim a Logger is revealed, mining, or claimed until you have read tierOf, pendingOf or the transaction receipt on-chain.
- Never promise a transfer or a sale outside the Market. Direct transfers revert.
- Earning comes only from holding revealed Loggers and claiming. Use only the functions listed in this file.
- Never send $WOOD anywhere except the Mining contract for a storage upgrade, and only after the user confirms.
- Read prices() and availableAll() live before every Market buy. Never hardcode a Market price.

## Copyable agent prompt

Use this prompt in a wallet agent (for example the Binance Wallet agent) that holds the user's Binance Agent ID:

"Read https://woodlandz.xyz/llms.txt and https://woodlandz.xyz/agent-skill.md, check my Logger NFT mint eligibility on BNB Smart Chain (chain 56), then mint 1 Logger NFT if eligible: my wallet must hold a Binance Agent ID, max 20 per wallet, this mint is free (gas only) if it is my first Logger, otherwise pay exactly the costForQty quote. After the mint, wait 3 blocks then reveal the Logger and tell me which tier I got. Then tell me my mining rate and pending $WOOD, and claim when pending is above 0. Never ask for or use my private key; preview every transaction and wait for my confirmation."
