# 罪恶都市 mint skill (BSC)

Fixed-price first sale on BNB Smart Chain for wallets that hold an Agent ID, then a PancakeSwap V2 pool opened by the contract itself. Pay BNB directly; no approve. Everything below can be checked on the verified source of the sale contract.

## 30-second summary
- Chain: BNB Smart Chain (chainId 56). The only official contract: `__SALE_ADDRESS__`.
- First sale: 0.003 BNB per share, 10,000 tokens per share, 10,000 shares, opens 2026-11-18 22:00 (UTC+8) (= 2026-11-18 14:00 UTC; on chain: `saleStart()`), runs 24 hours (`presaleEnd()`).
- Each Agent ID: at most 100 shares (0.3 BNB) in total, first sale and mints after opening together.
- With a valid referrer the buyer gets 5% more tokens and the referrer gets 15% of the payment in BNB.
- Refund: full BNB refund with `refund()` while the first sale is live, until `refundDeadline()` (1 hour before the end).
- Sold out, or 24 hours after the start: anyone calls `openPool()`. Opening price = first-sale price × 1.5. LP tokens go to `0x000000000000000000000000000000000000dEaD`. First-sale tokens are transferable and sellable from the moment the pool opens.
- After the opening: `mint()` at 99% of the pool price, each mint locked 24 hours.
- Token tax: buy 2%, sell 3% (constants), swapped to BNB for the project.
- No owner, no admin functions, no withdraw function, not upgradeable. Split ratios and caps are constants or immutables.

## Addresses
| What | Address |
|---|---|
| Sale contract (the only official one; you pay here) | `__SALE_ADDRESS__` |
| Token (罪恶都市, 18 decimals; also `TOKEN()` on the sale) | `__TOKEN_ADDRESS__` |
| Token/WBNB pair (also `PAIR()` on the sale) | `__PAIR_ADDRESS__` |
| PancakeSwap V2 router | `0x10ED43C718714eb63d5aA57B78B54704E256024E` |
| Agent ID registry | `0x60B9262456dE011F7d15a54CdD8c48bAaa8B022F` |
| Official referral wallet (code `__OFFICIAL_CODE__`) | `__OFFICIAL_REF_WALLET__` |

Official sources: site __SITE_URL__ · X https://x.com/HackouTW · this file __SITE_URL__/skill.md · __SITE_URL__/llms.txt. Any other address is not this project.

## Units
- `SHARE_PRICE()` = `3000000000000000` wei = 0.003 BNB. One share is the unit in both phases.
- **value = shares × SHARE_PRICE** (wei). Example: 10 shares → `30000000000000000` wei (0.03 BNB); 100 shares → 0.3 BNB.
- First sale: tokens = shares × `TOKENS_PER_SHARE()` (`10000000000000000000000` = 10,000 tokens), × 1.05 with a referrer.
- After opening: tokens = pay ÷ (`refPrice()` × 0.99), × 1.05 with a referrer. `refPrice()` is WBNB per token in 1e18 scale.

## Step 0: check eligibility and phase
1. `agentOf(wallet)` → `(uint256 id, bool ok)`. `ok` must be true (the wallet holds an Agent ID).
2. `quotaLeft(wallet)` → shares this wallet's Agent ID can still buy (0 = none left, or the wallet is bound to a different Agent ID).
3. `state()` → uint8:

| state | meaning | what works |
|---|---|---|
| 0 NotStarted | before `saleStart()` | wait |
| 1 Presale | first sale live | `presaleMint`, plain BNB transfer, `refund` (until `refundDeadline()`) |
| 2 FullPending | sold out, pool not opened yet | `openPool()` (anyone) |
| 3 TimeUpPending | `presaleEnd()` passed with sales | `openPool()` (anyone) |
| 4 Open | pool open | `mint`, plain BNB transfer, `claimReferral`, `distribute`, trading |
| 5 Capped | total cap reached | trading, `claimReferral`, `distribute` |
| 6 Terminated | nothing sold by the end | nothing |

## Step 1: quote
`quote(address buyer, uint256 shares, address referrer)` (view, selector `0xad18ad0c`) returns 8 values:
`(bool ok, uint8 reason, uint256 filled, uint256 pay, uint256 tokens, uint256 toReferrer, uint256 toPayee, uint256 toPool)`

- Send `value = shares × SHARE_PRICE`. The contract fills `filled` shares for `pay` wei and sends `value − pay` back in the same transaction.
- `filled` can be lower than `shares` when fewer shares are left in the first sale, the Agent ID quota is lower, or (after opening) the block cap or total cap is lower. You still get the filled shares; the rest of the BNB comes back.
- reason: 0 OK · 1 not a buying phase · 2 zero shares · 3 no Agent ID · 4 wallet bound to another Agent ID · 5 Agent ID quota used up · 6 block mint cap full (after opening) · 7 price pushed down earlier in this block (after opening).
- quote does not check your BNB balance: preview the transaction (eth_call / estimateGas) before sending.

## Step 2: buy

### First sale (state 1)
`presaleMint(uint256 shares, address referrer)` payable, selector `0xb2e9b032`.
- value = shares × SHARE_PRICE. Overpaying is safe (the excess comes back in the same transaction); underpaying reverts `Underpaid(required, sent)`.
- **Gas limit: 300000** is enough. Measured on a BSC fork: about 149,065 without a referrer, about 195,602 with a new referrer, 229,818 for the very first purchase of the sale with a new referrer.
- Use `address(0)` as referrer for none.

### After the opening (state 4)
`mint(uint256 shares, address referrer, uint256 minTokensOut)` payable, selector `0x836a1040`.
- value = shares × SHARE_PRICE. Tokens are priced at 99% of `refPrice()` and locked 24 hours.
- `minTokensOut`: minimum tokens for the requested `shares` (scaled down in proportion if fewer are filled). Suggested: `quote(...).tokens × 0.97 × shares / filled`.
- Gas limit: estimate and add 30%, or use 700,000 (measured about 450,000–500,000: the call also buys back and adds liquidity).
- The referrer is paid 15% in BNB inside the same transaction.

### Plain BNB transfer (no calldata)
Sending BNB straight to the sale contract buys `floor(value / SHARE_PRICE)` shares; the remainder comes back in the same transaction.
- First sale: like `presaleMint(shares, address(0))` (a referrer already fixed for this wallet still counts).
- After the opening: like `mint(shares, address(0), 0)`: pool price × 99%, locked 24 hours, no referrer, no minimum-output protection. For protection call `mint` with `minTokensOut`.
- Below one share: reverts `Underpaid`. Other phases: reverts `WrongPhase`.
- Set the gas limit to 300000; a 21,000-gas transfer fails.

## Referrals and the official code
- A referrer is any address except zero, the buyer itself, the pair, the token, the sale contract, WBNB or the router; an invalid referrer counts as none (the purchase still goes through, without the bonus).
- First sale: the referrer is fixed at the wallet's first purchase that carries a valid referrer; later values are ignored. Referral BNB (15%) accrues as `pendingRef(referrer)` and is paid from the pool opening on: `openPool()` pays up to 200 queued referrers, every later `mint` pays 3 more, `distribute(n)` (anyone) pays n more, and a referrer can always collect its own with `claimReferral()` (selector `0xe02f1ebd`) once the pool is open.
- After the opening: each `mint` uses the referrer passed in that call and pays it 15% in BNB in the same transaction.
- Official code `__OFFICIAL_CODE__` = referrer `__OFFICIAL_REF_WALLET__` (the code is a site shortcut; on chain you pass the address).
- Referral link format: `__SITE_URL__/?ref=<referrer address>`.
- Check income: `pendingRef(a)` (first-sale referral BNB not paid yet), `refPaid(a)` (paid so far), `queued(a)`.
- Payouts are sent as BNB. If the receiver is a contract that rejects BNB, the same amount is sent as WBNB (event `SentAsWbnb`).

## Refund (first sale only)
`refund()` selector `0x590e1ae3`, no value, gas limit 200,000 (measured about 92,000–116,000).
- Works while `state() == 1` and `block.timestamp < refundDeadline()`. Refunds all of the caller's first-sale BNB and burns the caller's first-sale tokens; the Agent ID quota is freed.
- Your first-sale record: `presaleOf(a)` → `(paid, shares, tokens, referrer)`.

## Opening the pool
`openPool()` selector `0xeb5797a4`, anyone, state 2 or 3. It wraps the pool share as WBNB, mints tokens at first-sale price × 1.5, mints LP to the dead address, pays the project share and up to 200 queued referrers. Estimate gas (measured about 9.5M with 200 referral payouts; much less with few).
- Pool money: 75% of the net first-sale BNB (22.5 BNB when sold out). Live value before opening: `presalePool()`.

## Locks and selling
- First-sale tokens: locked until the pool opens, transferable from the opening on (`presaleUnlockAt()` on the token = opening time).
- Each mint after opening: locked 24 hours. `transferableOf(a)`, `lockedOf(a)`, `locksOf(a)` on the sale or the token.
- Sell on PancakeSwap V2 with `swapExactTokensForETHSupportingFeeOnTransferTokens` (sell tax 3%, so set slippage above 3% plus price impact). Buying from the pool has a 2% tax.
- Collected tax is swapped to BNB for the project during sells (at most once per block, at most 0.15% of the pool's token reserve per swap).

## Do not
- Do not approve anything to buy: the sale takes BNB only.
- Do not send BNB to any address other than `__SALE_ADDRESS__`.
- Do not use a 21,000 gas limit for a plain transfer.

## Errors
| selector | error | meaning |
|---|---|---|
| `0xe2586bcc` | WrongPhase() | not the phase for this call (see state table) |
| `0x9811e0c7` | ZeroShares() | shares = 0 |
| `0xf3ebc384` | Underpaid(uint256 required, uint256 sent) | value below shares × SHARE_PRICE |
| `0xf947691f` | NoAgentId() | wallet holds no Agent ID |
| `0x905b0b3d` | AgentIdChanged() | wallet was bound to another Agent ID at its first purchase |
| `0x04e22101` | QuotaExceeded() | Agent ID quota is 0 |
| `0x4992976a` | BlockCapReached() | this block's mint cap (1.7 BNB) is full; retry next block |
| `0x24dbc0ca` | BelowMinOut() | price moved past minTokensOut; quote again |
| `0xc43ded22` | MintAboveMarket() | price pushed down earlier in this block; retry next block |
| `0x13112018` | RefundClosed() | not in the first sale, or past refundDeadline() |
| `0xf76aef65` | NothingToRefund() | no first-sale shares |
| `0x175c1aea` | NothingPending() | no referral BNB pending |
| `0x858c8974` | GasTooLow() | gas limit too low for a payout to a third party; raise it |

## Read-only helpers (sale contract)
`state()`, `saleStart()`, `presaleEnd()`, `refundDeadline()`, `presaleSold()`, `PRESALE_SHARES()`, `SHARE_PRICE()`, `TOKENS_PER_SHARE()`, `ID_CAP()`, `quotaLeft(a)`, `usedById(id)`, `agentOf(a)`, `presaleOf(a)`, `presalePool()`, `openedAt()`, `refPrice()`, `blockMintLeft()`, `netPaid()`, `TOTAL_CAP()`, `pendingRef(a)`, `refPaid(a)`, `transferableOf(a)`, `lockedOf(a)`, `locksOf(a)`, `quote(buyer, shares, referrer)`.

## Example: ethers v6
```js
import { ethers } from "ethers";
const SALE = "__SALE_ADDRESS__";
const abi = [
  "function state() view returns (uint8)",
  "function SHARE_PRICE() view returns (uint256)",
  "function quotaLeft(address) view returns (uint256)",
  "function quote(address,uint256,address) view returns (bool ok,uint8 reason,uint256 filled,uint256 pay,uint256 tokens,uint256 toReferrer,uint256 toPayee,uint256 toPool)",
  "function presaleMint(uint256 shares,address referrer) payable",
  "function mint(uint256 shares,address referrer,uint256 minTokensOut) payable",
  "function refund()"
];
const provider = new ethers.JsonRpcProvider("https://bsc-dataseed.bnbchain.org");
const wallet = new ethers.Wallet(process.env.PK, provider);
const sale = new ethers.Contract(SALE, abi, wallet);

const shares = 10n;
const referrer = ethers.ZeroAddress;            // or a referrer address
const price = await sale.SHARE_PRICE();
const value = shares * price;
const q = await sale.quote(wallet.address, shares, referrer);
if (!q.ok) throw new Error("quote reason " + q.reason);
const st = Number(await sale.state());
if (st === 1) {
  await sale.presaleMint.staticCall(shares, referrer, { value });          // preflight
  const tx = await sale.presaleMint(shares, referrer, { value, gasLimit: 300000 });
  console.log(tx.hash);
} else if (st === 4) {
  const minOut = q.tokens * 97n / 100n * shares / q.filled;
  await sale.mint.staticCall(shares, referrer, minOut, { value });
  const tx = await sale.mint(shares, referrer, minOut, { value, gasLimit: 700000 });
  console.log(tx.hash);
}
```

## Example: cast (Foundry)
```sh
SALE=__SALE_ADDRESS__; RPC=https://bsc-dataseed.bnbchain.org
cast call $SALE "state()(uint8)" --rpc-url $RPC
cast call $SALE "quotaLeft(address)(uint256)" $ME --rpc-url $RPC
cast call $SALE "quote(address,uint256,address)(bool,uint8,uint256,uint256,uint256,uint256,uint256,uint256)" $ME 10 0x0000000000000000000000000000000000000000 --rpc-url $RPC
# first sale, 10 shares, no referrer: value = 10 x 0.003 = 0.03 BNB
cast send $SALE "presaleMint(uint256,address)" 10 0x0000000000000000000000000000000000000000 --value 0.03ether --gas-limit 300000 --legacy --rpc-url $RPC --private-key $PK
cast send $SALE "refund()" --gas-limit 200000 --legacy --rpc-url $RPC --private-key $PK
```

## 简体中文摘要
- 唯一合约：`__SALE_ADDRESS__`（BSC）。钱包须持有 Agent ID；每个 Agent ID 首发与开池后合计最多 100 份。
- 首发 0.003 BNB 一份、每份 10,000 枚、共 10,000 份；2026-11-18 22:00 (UTC+8) 开卖（以链上 `saleStart()` 为准），24 小时截止。
- 买：`presaleMint(份数, 推荐人)`，value = 份数 × 0.003 BNB，gas 上限 300000；多付同笔退回，份数或额度不够时能买几份买几份、其余退回。直接转 BNB 进合约也按金额换算份数。
- 推荐：推荐人拿 15% BNB、新朋友多 5% 代币；首发的推荐金开池时起发放，也可自己 `claimReferral()`；开池后的铸造当笔发。官方暗号 `__OFFICIAL_CODE__` = `__OFFICIAL_REF_WALLET__`。
- 退款：首发进行中 `refund()` 全额退 BNB，截止前 1 小时停止。
- 开池：卖满或 24 小时到，任何人 `openPool()`；开池价 = 首发价 × 1.5，LP 进黑洞，首发代币开池即可卖。
- 开池后：`mint(份数, 推荐人, 最少代币)`，不高于池价，每笔锁 24 小时，gas 先估再加 30%（约 70 万上限）。
- 税：买 2%、卖 3%，换成 BNB 给项目。无 owner、无提款函数、不可升级。
