# 金蟬交易手册

用于核对与准备 JINCHAN 的交易。本文是公开操作数据，不授予签名权限。

## 核对部署

- 链：BNB Chain，56。唯一销售合约 `0x721e9C1d2d5535Db079f6A0841fbE677621258F5`，开卖时间 2026-11-21 15:59:47（UTC+8，`startTime()` = 1795247987）；以 `startTime()` / `endTime()` 为准。
- 阅读 `contract-source.sol`、`token-source.sol`，核验 BscScan 已验证代码及 ABI。读取 `siteUrl()`，核对其指向的官方页面与唯一地址一致。
- `owner()` 为零；销售与代币不可升级，无管理员可修改销售参数。上限由不可变参数决定。`LP_SINK()` 为 `0x000000000000000000000000000000000000dEaD`；开池后查真实 pair 的 LP 余额。
- `ID_REGISTRY()` 应为 `0x60B9262456dE011F7d15a54CdD8c48bAaa8B022F`；`DEX()` 为 `0x10ED43C718714eb63d5aA57B78B54704E256024E`。代币与交易对只从 `token()` / `pair()` 取得。
- 部署参数（链上已读回）：`unitPrice()` 0.005 BNB；`tokensPerUnit()` 80,000×10^18；`supplyUnits()` 10,000；`perAgentLimit()` 30。所有计算以 getter 实际值为准。

## 先选推荐，再取报价

`idOf(wallet)` 返回 `(agentId,valid)`；有效 ID 要同时满足 registry 的 handle 与 owner。`buyableBy(wallet)` 读这个 ID 还可买多少份（不代表目前已开卖）；`limitFor(wallet)` 读总上限。多个钱包持有同一 ID 时共用已购额度，推荐不加额度。

`bindReferrer(referrer)` 开卖前可调用，绑定后不能更改；不许自己、零地址或无有效 ID 的推荐人。绑定是独立交易，先确认买家授权。也可用 `mint(uint256,address)` 或 `mintWithReferrer(uint256,address)` 在购买时尝试绑定；已有绑定沿用，传入不合格推荐会被忽略且不给代币加成。尚未绑定时 `estimate()` 不会计入准备在购买中才绑定的推荐，因此建议先独立绑定、再报价。

有效绑定后：推荐人同笔获成交金额的 `inviterBps()/10000` BNB，买家另获基础代币的 `inviteeBonusBps()/10000`。部署参数均为 5%。`firstFillTerms()` 返回 `(units,toInviter,toInvitee,cap,remainingCap)`，部署参数为 `(15,0.00125 BNB,0.00125 BNB,1 BNB,剩余)`。只在绑定后那笔把被推荐 ID 的本合约累计份额从低于门槛推进到门槛或以上时触发；每 ID 一次；绑定前已经到门槛不会补发，预算不足时不发。首成交奖从收款份额支出，不动池子。

推荐金与双方首次成交奖使用同笔限 gas 推送。收不到时计入 `bnbOwed(wallet)`，余额保留在合约，用 `withdrawOwedBnb()` 领取；调用方必须能接收 BNB。

## 两种报价与付款规则

`estimate(wallet,units)` 返回 `(buys,price,tokens,available,ok,extraTokens,ffInviter,ffInvitee)`；`tokens` 是基础代币，总代币为 `tokens+extraTokens`。`estimateValue(wallet,valueWei)` 返回 `(units,spend,back,ok)`；`back` 是找零，不包含另外推送的首次成交奖。

照付款金额成交，数量参数只是报价。实际份数为 `min(value / unitPrice, buyableBy(wallet), unitsRemaining())`，零头同一笔退回。付款不足一份会 `Underpaid(unitPrice,sent)`；无 ID、非销售时间、额度用完等也会 revert。收不了 BNB 的合约钱包应付刚好成交金额，找零接收失败会使整笔回滚。付款最终，不退本金。

在单价 0.005 BNB、剩余额度充足的条件下，调用 `mint(15)`：

| 实付 | 成交 | 找零 |
|---|---:|---:|
| 0.075 BNB | 15 份 | 0 |
| 0.075 BNB + 1 wei | 15 份 | 1 wei |
| 0.15 BNB | 30 份 | 0 |
| 0.075 BNB − 1 wei | 14 份 | 0.005 BNB − 1 wei |
| 0.005 BNB − 1 wei | 回滚，买不起一份 | 整笔回滚 |

入口还有 `mint()`、`mintMany(uint256)`、`mint(uint256,address)`、`mintWithReferrer(uint256,address)` 及直接转 BNB；均按实付金额成交。不向代币合约转 BNB。以下 ethers 6 例子只准备和模拟，不发送：

```js
import { JsonRpcProvider, Contract, Interface, isAddress, ZeroAddress } from 'ethers';
import fs from 'node:fs';
const address = '0x721e9C1d2d5535Db079f6A0841fbE677621258F5';
if (!isAddress(address) || address === ZeroAddress) throw Error('Deployment address needed');
const provider = new JsonRpcProvider('https://bsc-rpc.publicnode.com', 56);
if ((await provider.getNetwork()).chainId !== 56n) throw Error('Wrong chain');
const abi = JSON.parse(fs.readFileSync('./abi.json', 'utf8'));
const sale = new Contract(address, abi.sale, provider);
const buyer = '0x...'; // replace with the authorized buyer; never insert a private key
const desired = 15n;
const identity = await sale.idOf(buyer);
if (!identity.valid || !(await sale.saleActive())) throw Error('Not eligible or not open');
const q = await sale.estimate(buyer, desired);
const paid = await sale.estimateValue(buyer, q.price);
if (!q.ok || !paid.ok) throw Error('No purchasable units');
console.log({units: q.buys, value: q.price, tokens: q.tokens + q.extraTokens,
  change: paid.back, firstFillToBuyer: q.ffInvitee, firstFillToReferrer: q.ffInviter});
const tx = {from: buyer, to: address,
  data: new Interface(abi.sale).encodeFunctionData('mint(uint256)', [q.buys]), value: q.price};
await provider.call(tx);
const estimated = await provider.estimateGas(tx);
tx.gasLimit = estimated * 125n / 100n > 700000n ? estimated * 125n / 100n : 700000n;
// Review chain, from, to, data, value, gas and expected tokens/BNB with the buyer.
// Immediately before any authorized send: reread estimate/estimateValue, compare all
// expected fields, recheck wallet and chain, then simulate again. Changes need a new review.
console.log(tx); // NOT sent; gas fee is separate from value
await provider.destroy();
```

绑定／领取／开池同样先模拟：

```js
// Using an ethers Contract connected to a read-only provider:
await sale.bindReferrer.staticCall(referrer, {from: buyer});
await sale.bindReferrer.estimateGas(referrer, {from: buyer});
// Preview owed BNB before preparing withdrawal:
const owed = await sale.bnbOwed(buyer);
if (owed > 0n) await sale.withdrawOwedBnb.staticCall({from: buyer});
// Seeding is possible only when seedable() is true:
if (await sale.seedable()) await sale.seedPool.staticCall({from: buyer});
```

每个写入都使用独立的买家授权、目标合约与 `eth_call`／`estimateGas`；末笔开池 gas 至少 700,000 或按估算加余量，取较高者。广播后保存 hash；状态未知时不盲目重发，查真实 receipt，失败回滚才可重报价。

## 开池与交易

末份成交同笔自动开池。到 `endTime()` 且已有成交后任何人可 `seedPool()`；零份成交不开池。`revenueSplit()` 给出 75% 进池、带推荐时推荐 5%／收款 20%、无推荐收款 25%的目标分配；首次成交奖从收款份额扣除。`poolPlan(unitsSold())` 给计划池额；已有 pair WBNB 计入池子，所以开池 BNB 不少于已售总额 75%，开盘价不低于预售价，LP 发往 `LP_SINK()`。

`seedPrice()` 开池前是按当前状态开池的估算，可能变化；开池后是历史开盘价。它不是未来市场价格或卖出回报。开池后代币无锁仓；官方 pair 买税 3%／卖税 2%，读代币 `BUY_LEVY_BPS()` / `SELL_LEVY_BPS()`。卖出采用税后可接收数预检，不能把未扣税的 `getAmountsOut` 当保底。

```js
// buyer signer only after explicit authorization; token/pair/router read from the sale.
const tokenAddress = await sale.token();
const token = new Contract(tokenAddress, abi.token, signer);
const routerAddress = await sale.DEX();
const router = new Contract(routerAddress, [
 'function WETH() view returns(address)',
 'function getAmountsOut(uint256,address[]) view returns(uint256[])',
 'function swapExactTokensForETHSupportingFeeOnTransferTokens(uint256,uint256,address[],address,uint256)',
 'function swapExactETHForTokensSupportingFeeOnTransferTokens(uint256,address[],address,uint256) payable'
], signer);
const amount = /* exact authorized token amount in 18-decimal units */ 1n;
const path = [tokenAddress, await router.WETH()];
const levy = await token.levyOf(buyer, await sale.pair(), amount);
const out = await router.getAmountsOut(amount - levy, path);
const minBnb = out[1] * 99n / 100n; // example 1% tolerance; buyer must approve it
const latest = await provider.getBlock('latest');
const deadline = BigInt(latest.timestamp + 300);
// Review exact allowance. Simulate approve before sending it; wait for its receipt.
await token.approve.staticCall(routerAddress, amount);
// Only after buyer authorization: token.approve(routerAddress, amount), then wait.
// With allowance in place, simulate the tax-supporting swap:
await router.swapExactTokensForETHSupportingFeeOnTransferTokens.staticCall(
 amount, minBnb, path, buyer, deadline);
// Estimate gas, review and request a separate signature; never send with minBnb=0.
// For buying, use swapExactETHForTokensSupportingFeeOnTransferTokens with
// [WETH,tokenAddress], a buyer-approved minimum AFTER buy levy, and a short deadline.
```

核对 swap 回执、真实代币与扣除 gas 后的 BNB 变化。示例变量 `signer`／`buyer`／`provider`／`abi` 由调用方在同一会话提供；此段不会自动授权或广播。
