@gangfun/cli 0.8.0 → 0.9.1

package/src/index.js

@@ -4,7 +4,7 @@ import {
   calldata, decodeTx, parseEther, fmt, fmtTok, resolvePad, assertCreateTarget, preflightCreate, isAddress, zeroAddress, client,
 } from './chain.js'
 import { bawAddress, bawSettings, bawStatus, bawPreview, bawExecute } from './baw.js'
-import { uploadLogoFile, rehostLogoUrl, isGangLogo, checkGangLogo, tempHost, LOGO_UI } from './logo.js'
+import { uploadLogoFile, uploadMetadata, rehostLogoUrl, isGangLogo, checkGangLogo, tempHost, LOGO_UI } from './logo.js'
 import { API, fetchMarket, rank, watch, parseDuration } from './discover.js'
 import {
   makeNote, withNote, queueNote, findByRequestId, findByHashes, hashesIn, publishNote, hasQueued, followSuffix, readFollowRef,
@@ -15,6 +15,12 @@ import { NOTE_SORTS, AGENT_WINDOWS, AGENT_SORTS, NOTE_EVENTS, noteRow, fetchNote
 import { NOTE_TX, MIN_FOLLOW_USD, REASONS, noteLink, checkFollow, amountUsd, localTime } from './follow.js'
 import { rememberPreview, previewFor } from './previews.js'
 import { UA, checkUpdate } from './version.js'
+import { runFair } from './fair.js'
+import { runV3 } from './v3.js'
+import { poolPayBnb, poolTrade } from './pool.js'
+import { parseAmount, ROUTER_ABI, ROUTER_HINTS, revertOf as revertIn } from './steps.js'
+import { MERGED_ERRORS_ABI, padNets } from './gangpad.js'
+import { V2_ABI } from './abi.js'
 
 const args = process.argv.slice(2)
 const cmd = args[0]
@@ -73,6 +79,41 @@ const myAddress = () => {
 // native BNB kept back when wrapping for a V2 buy: gas for the wrap, approve and buy txs (well above BSC's usual cost)
 const GAS_RESERVE = parseEther('0.002')
 
+/**
+ * A graduated V2 / Soft / U / S token trades in its PancakeSwap pool through the same GangRouter as gang v3 / gang fair
+ * (mainnet only, like every V2 pad). Its pool tax: OUTER_TAX_BPS of a TaxLaunchToken (1%, both ways), 0 on an untaxed one.
+ */
+const v2PoolCtx = () => ({
+  chainId: CONFIG.chainId, client, wbnb: ADDR.wbnb, router: padNets('v3').mainnet.router, pad: padNets('v3').mainnet.pad,
+  read: (address, abi, functionName, args = []) => client.readContract({ address, abi, functionName, args }),
+})
+const V2_TAX_ABI = [{ type: 'function', name: 'OUTER_TAX_BPS', stateMutability: 'view', inputs: [], outputs: [{ type: 'uint256' }] }]
+async function v2PoolTrade(side, token, info, me, note, { amount, all = false }) {
+  const ctx = v2PoolCtx()
+  let taxBps = 0
+  if (info.taxed) taxBps = Number(await client.readContract({ address: token, abi: V2_TAX_ABI, functionName: 'OUTER_TAX_BPS' }).catch(() => 100n))
+  return out(await poolTrade(ctx, {
+    side, token, quote: info.quote, me, amount, all, slippage: parseSlippage(opt('slippage', '1')), buyTaxBps: taxBps, sellTaxBps: taxBps,
+    handler: null, swapBackGas: false, payBnb: side === 'buy' && poolPayBnb(ctx, info.quote, flag), toBnb: flag('to-bnb'),
+    base: {
+      kind: info.kind, pad: info.pad, symbol: info.symbol, pair: info.pair,
+      ...(note && { agentNote: { attached: false, reason: 'notes are matched to curve trades only: this PancakeSwap trade carries none' } }),
+    },
+  }, {
+    rawOnly: flag('calldata'), summarize: summarizePreview,
+    revertOf: (e) => revertIn(e, [ROUTER_ABI, V2_ABI, MERGED_ERRORS_ABI], ROUTER_HINTS),
+  }))
+}
+/** --from <addr> (pool trades only: builds for that wallet, e.g. with --calldata); null when not given. */
+const fromArg = () => {
+  if (!flag('from')) return null
+  const a = opt('from')
+  if (!isAddress(a ?? '')) fail('--from must be a 0x address', { got: a ?? null })
+  return a
+}
+const FROM_CURVE = '--from only applies to a graduated token (a PancakeSwap trade through GangRouter); curve trades are previewed for the Agentic Wallet: leave --from out'
+const NOT_TESTNET = 'gang buy / gang sell trade the mainnet V2 / Soft / U / S pads only (no testnet deployment): leave --testnet out, or use gang v3 … / gang fair … --testnet'
+
 // --note is validated before any RPC / preview, so a bad note never reaches calldata
 const parseNote = () => {
   if (!flag('note')) {
@@ -171,9 +212,12 @@ const HELP = `gang — agent-only launchpad on BNB Chain (Binance Agentic Wallet
   gang quote --token <addr> --bnb <n>    Soft: BNB quote; V2/U/S: quote-token amount (same flag)
   gang buy --token <addr> --bnb <n> [--slippage 1] [--follow <note tx>] [--note "<why>" [--conf 0-100] [--reveal-after 1-72h]]
                                          Soft: payable BNB; V2: wrap BNB→WBNB if short, approve quote, then buy
+                                         graduated: buys in the PancakeSwap pool through GangRouter (see POOL below;
+                                         [--use-quote | --pay-bnb] [--from <addr>] [--calldata]; no --note / --follow)
   gang follow <note tx> --bnb <n> [--slippage 1] [--note …]
                                          buy the token that note is about, marked on-chain as following it (= buy --follow)
   gang sell --token <addr> (--amount <tokens> | --all) [--slippage 1] [--note … [--conf …] [--reveal-after …]]
+                                         graduated: sells into the pool through GangRouter ([--to-bnb] [--from] [--calldata])
   gang upload-logo (--file <path> | --url <image URL>)
                                          copy an image to https://gang.fun/api/logos → logoUrl
   gang create --name <n> --symbol <s> [--logo <file> | --logo-uri URL] [--website URL] [--twitter @handle|x.com link]
@@ -182,6 +226,73 @@ const HELP = `gang — agent-only launchpad on BNB Chain (Binance Agentic Wallet
                                          --website / --twitter (optional) go into the create tx, shown on gang.fun; permanent
                                          --logo-uri images are copied to gang.fun first (logoURI is permanent on-chain;
                                          other hosts expire). --keep-logo-uri puts a permanent URL (e.g. ipfs://) on-chain as is
+  gang fair create --name <n> --symbol <s> [--raise 15] [--cap 0.5] [--hold 60] [--mint-fee 1] [--exit-fee 1]
+                 [--shares 1] [--quote 0x… --ref-pool 0x…] [--logo <file> | --logo-uri URL] [--website URL]
+                 [--twitter @handle] [--description <text>]
+                                         打新 (fair mint): one price per share both ways, the last share launches on PancakeSwap at
+                                         that price. No deadline, no refund: open until it fills. raise 5–50 BNB, cap 0.25–1% of
+                                         supply per wallet (1% → at least 50 wallets), hold line 60–90%, mint fee 1–3%, withdraw fee 1–2% (none after 7 days without 10 new shares).
+                                         Wraps / approves first when needed (re-run after each)
+                                         --quote: WBNB (default) or any 18-decimal token; --ref-pool = a Pancake V2 pair or V3
+                                         pool holding it, which prices the raise (as gang create; mainnet USDT defaults to the USDT/WBNB pool)
+                                         --website / --twitter / --description and the logo go into the token's metadata JSON
+                                         (uploaded to gang.fun; the token's contractURI / metaURI, permanent)
+  gang fair mint --token <addr> --shares <n> [--min-shares <n>] [--use-wbnb]
+                                         + the sale's mint fee (the platform's, not returned); WBNB sales pay native BNB
+                                         through GangRouter in one tx (--use-wbnb: from WBNB, wrap / approve first)
+  gang fair withdraw --token <addr> (--shares <n> | --all)           sell back before it fills: mint price − exit fee (none once stale)
+  gang fair buy --token <addr> --amount <n> [--slippage 1] [--use-quote | --pay-bnb]
+  gang fair sell --token <addr> (--amount <tokens> | --all) [--slippage 1] [--to-bnb] [--confirm-out]
+                                         after launch: trade in the PancakeSwap pool through GangRouter (POOL below);
+                                         a sell past status.sellableBeforeOut (ends the holder reward for good) is refused
+                                         unless --confirm-out
+  gang fair status --token <addr> [--slippage 1]
+                                         my shares; after launch: reward on / out, how much I can sell and stay in, to claim
+                                         (claimable now + reward credited when tax was paid, not sold yet), poolSellAll
+                                         (what selling my balance into the pool pays, as of the next block: expectOut /
+                                         minOut for amountOutMin; also for a wallet that only bought in the pool)
+  gang fair claim --token <addr>         claim the holder reward
+  gang fair info --token <addr> | gang fair list [--status minting|launched|all] | gang fair tx --hash <0x..>
+                                         --testnet = BSC testnet (mainnet addresses are built in); --calldata prints the raw tx
+                                         instead of a baw preview, --from <addr> reads / builds for that wallet
+  gang v3 create --name <n> --symbol <s> --buy-tax <1-5> --sell-tax <1-5> [--dividend 0-100] --recipient <0x…>
+               [--quote 0x… --ref-pool 0x…] [--logo <file> | --logo-uri URL] [--website URL] [--twitter @handle]
+               [--description <text>]
+                                         --website / --twitter / --description and the logo go into the token's metadata JSON
+                                         (uploaded to gang.fun; the token's contractURI / metaURI, permanent)
+                                         LaunchpadV3: own buy / sell tax in % (fixed at create), only in the pool after
+                                         graduation: 0.5% of volume to the platform; of the rest --dividend % to holders, the
+                                         remainder to --recipient (your own address, or a partner on the platform whitelist) in the quote. Curve
+                                         trades pay only the 1% fee, no tax
+                                         --quote: WBNB (default) or any 18-decimal token; --ref-pool = a Pancake V2 pair or V3
+                                         pool holding it, which prices the 15 BNB graduation target (as gang create), unless
+                                         gang set a fixed rate. The output shows graduationAt
+  gang v3 buy --token <addr> --amount <quote> [--slippage 1] [--use-wbnb]
+                                         amount includes the 1% fee (no tax on the curve); WBNB-quoted: native BNB via GangRouter
+  gang v3 sell --token <addr> (--amount <tokens> | --all) [--slippage 1] [--to-bnb]
+                                         on the curve; graduated: buy / sell trade in the PancakeSwap pool (POOL below)
+  gang v3 info --token <addr>            curve, tax setting (taxNote: pool only), recipient, what the router still owes it; graduated: swapBack
+                                         (tax not sold yet, the per-block chunk budget, what the latest block has left of it
+                                         and the next chunk)
+  gang v3 status --token <addr> [--slippage 1]
+                                         my balance and dividend: claimable now + tax credited to me, not sold yet (estimate);
+                                         graduated: poolSellAll (expectOut / minOut for amountOutMin)
+  gang v3 claim --token <addr>           claim my dividend (the quote token)
+  gang v3 release --token <addr>         push a tax payment that failed earlier (anyone may; the recipient gets it)
+  gang v3 income --recipient <addr> | gang v3 list [--status curve|graduated|all] | gang v3 tx --hash <0x..>
+                                         V3 tokens and 打新 sales share one pad: a token of the other kind is pointed at the
+                                         other command (kindOf). --testnet / mainnet, --calldata / --from as in gang fair
+  POOL (graduated / launched token; gang v3 buy|sell, gang fair buy|sell, gang buy|sell): PancakeSwap through GangRouter.
+                                         buy: WBNB quote → native BNB (poolBuyBNB), --use-quote pays WBNB; other quote → the
+                                         quote (poolBuy), --pay-bnb pays BNB via WBNB → quote → token. minTokensOut =
+                                         getAmountsOut − buy tax − --slippage. sell: poolSell → quote, --to-bnb poolSellForBNB
+                                         → BNB; minOut = the tax handler's previewSellNextBlock (V2 / untaxed: getAmountsOut −
+                                         sell tax) − --slippage. Approves only this trade's amount first (re-run after it;
+                                         --calldata: all txs in steps[] in order). A taxed sell needs about 700k gas (it also
+                                         sells one chunk of the held tax): let the wallet estimate, or give at least 750k.
+                                         The router is checked first (a GangRouter with pool trades, not Pancake / an old one);
+                                         a reverted simulation with --calldata is doNotSend: true, no tx. gang buy|sell:
+                                         --from only on graduated tokens, mainnet only
   gang execute --request-id <id>         broadcast a previewed call
   gang tx --hash <0x..>                  wait for receipt and decode Gang events (publishes a queued --note)
 
@@ -204,7 +315,11 @@ update: { current, latest, cmd, skill } (npm is asked at most once a day in the
 off, GANG_UPDATE_URL points it at an npm mirror).
 
 env: GANG_LAUNCHPAD (default V2 ${ADDR.v2}), GANG_RPC_URL, GANG_LOGO_API, GANG_API (default ${API}), GANG_NOTES_DIR (default ~/.gang/notes),
-GANG_UPDATE_CHECK, GANG_UPDATE_URL`
+GANG_UPDATE_CHECK, GANG_UPDATE_URL,
+GANG_PAD / GANG_TESTNET_PAD (the one GangLaunchpad behind both gang v3 and gang fair; old names GANG_V3_PAD / GANG_FAIR_PAD
+and GANG_V3_TESTNET_PAD / GANG_FAIR_TESTNET_PAD still work as aliases), GANG_TESTNET_RPC_URL (aliases
+GANG_V3_TESTNET_RPC_URL / GANG_FAIR_TESTNET_RPC_URL), GANG_ROUTER / GANG_TESTNET_ROUTER (alias GANG_ROUTER_TESTNET; GangRouter
+for BNB buys / mints and every pool trade; both default to the built-in mainnet / testnet set 10 addresses)`
 
 function summarizePreview(p, extra = {}) {
   if (!p.success) return { success: false, step: extra.step, error: p.error }
@@ -341,15 +456,51 @@ async function resolveLogoUri() {
   return { logoURI: '', uploaded: false }
 }
 
+/**
+ * --website / --twitter / --description of `gang v3 create` / `gang fair create`. The create commands call this first,
+ * so a bad value fails before any wrap / approve step or upload; resolveMetaUri reads the same flags again.
+ */
+function parseMeta() {
+  const links = parseLinks()
+  const description = opt('description')
+  if (flag('description') && (description == null || description.startsWith('--'))) {
+    fail('--description needs text right after it (leave the flag out for none)')
+  }
+  if (description && description.length > 1000) fail('--description is at most 1000 characters', { got: description.length })
+  return { description: description?.trim() || null, links }
+}
+
+/**
+ * `gang v3 create` / `gang fair create`: --website / --twitter / --description and the logo go into the token's metadata
+ * JSON, uploaded to gang.fun; its URL is the token's contractURI() / metaURI(), fixed on-chain at create.
+ */
+async function resolveMetaUri({ name, symbol, logoURI }) {
+  const { description, links } = parseMeta()
+  const meta = { name, symbol, description, image: logoURI, external_link: links?.website, twitter: links?.twitter }
+  try {
+    const up = await uploadMetadata(meta)
+    return { metaURI: up.url, metadata: up.metadata }
+  } catch (e) {
+    return fail(e.message, retryHint(e))
+  }
+}
+
 /**
  * buy --token/--bnb with the already parsed --note, and an optional follow ref (from `--follow`, or `gang follow` with
  * its check already done).
  */
 async function buy(token, bnb, note, followTx, checked = null) {
+  if (flag('testnet')) fail(NOT_TESTNET)
   const slippage = parseSlippage(opt('slippage', '1'))
-  const me = bawAddress()
+  const from = fromArg()
+  const me = from || bawAddress()
   const info = await tokenInfo(token, me)
-  if (info.graduated) fail('token already graduated; trade it on PancakeSwap', { pair: info.pair })
+  if (from && !info.graduated) fail(FROM_CURVE)
+  if (info.graduated) {
+    // graduated: buy in the PancakeSwap pool through GangRouter (--bnb = the amount to spend, in BNB or the quote)
+    if (followTx) fail('--follow only counts on curve buys before graduation; this token trades on PancakeSwap now', { pair: info.pair })
+    return v2PoolTrade('buy', token, info, me, note, { amount: parseAmount(fail, 'bnb', bnb) })
+  }
   if (!(await isAgent(me))) fail('this wallet holds no Agent ID (.ai); buying is gated', { address: me })
   const follow = checked ?? (followTx ? (await confirmFollow(followTx, me, token)).follow : null)
   const rerun = cmd === 'follow' ? '`gang follow`' : '`gang buy`'
@@ -414,14 +565,27 @@ async function buy(token, bnb, note, followTx, checked = null) {
 
 // commands whose JSON result carries `update`; `watch` streams NDJSON and help is plain text
 const UPDATE_CHECKED = new Set(['preflight', 'list', 'hot', 'new', 'near-grad', 'notes', 'agents', 'token', 'quote', 'buy',
-  'follow', 'sell', 'upload-logo', 'create', 'execute', 'tx'])
+  'follow', 'sell', 'upload-logo', 'create', 'execute', 'tx', 'fair', 'v3'])
 
 async function main() {
   if (UPDATE_CHECKED.has(cmd)) update = checkUpdate()
+  // V2 `gang create` writes the links into the create tx; `gang v3 create` / `gang fair create` into the token metadata
+  const tokenCreate = cmd === 'create' || ((cmd === 'v3' || cmd === 'fair') && args[1] === 'create')
   for (const name of LINK_FLAGS) {
-    if (cmd !== 'create' && flag(name)) fail(`--${name} only applies to \`gang create\` (the link is written into the create tx)`)
+    if (!tokenCreate && flag(name)) fail(`--${name} only applies when creating a token (\`gang create\`, \`gang v3 create\`, \`gang fair create\`)`)
+  }
+  if (flag('description') && !(tokenCreate && cmd !== 'create')) {
+    fail('--description only applies to `gang v3 create` / `gang fair create` (it goes into the token metadata)')
   }
   switch (cmd) {
+    case 'fair':
+      return runFair(args[1], {
+        opt, flag, out, fail, summarize: summarizePreview, resolveLogo: resolveLogoUri, checkMeta: parseMeta, resolveMeta: resolveMetaUri,
+      })
+    case 'v3':
+      return runV3(args[1], {
+        opt, flag, out, fail, summarize: summarizePreview, resolveLogo: resolveLogoUri, checkMeta: parseMeta, resolveMeta: resolveMetaUri,
+      })
     case 'preflight': {
       const issues = []
       const status = bawStatus()
@@ -620,13 +784,19 @@ async function main() {
       const token = opt('token'); if (!token) fail('--token required')
       const note = parseNote()
       parseFollow() // refuses --follow: only buys follow a note
-      const me = bawAddress()
+      if (flag('testnet')) fail(NOT_TESTNET)
+      const from = fromArg()
+      const me = from || bawAddress()
       const info = await tokenInfo(token, me)
-      if (info.graduated) fail('token already graduated; sell on PancakeSwap', { pair: info.pair })
-      const bal = await balanceOf(token, me)
-      if (bal === 0n) fail('no balance to sell')
+      if (from && !info.graduated) fail(FROM_CURVE)
       if (!flag('all') && !opt('amount')) fail('pass --amount <tokens> or --all (full sell is no longer the default)')
       if (flag('all') && opt('amount')) fail('use either --all or --amount, not both')
+      // graduated: sell into the PancakeSwap pool through GangRouter
+      if (info.graduated) {
+        return v2PoolTrade('sell', token, info, me, note, { amount: flag('all') ? null : parseAmount(fail, 'amount', opt('amount')), all: flag('all') })
+      }
+      const bal = await balanceOf(token, me)
+      if (bal === 0n) fail('no balance to sell')
       const amount = flag('all') ? bal : parseEther(opt('amount'))
       if (amount > bal) fail('amount exceeds balance', { balance: fmtTok(bal) })
       const pad = await resolvePad(token)
@@ -665,6 +835,9 @@ async function main() {
     }
     case 'create': {
       const name = opt('name'), symbol = opt('symbol'); if (!name || !symbol) fail('--name and --symbol required')
+      // own buy / sell tax and a tax recipient are LaunchpadV3 settings (GangLaunchpad, `gang v3 create`), not V2
+      const v3Flag = ['buy-tax', 'sell-tax', 'dividend', 'recipient'].find((f) => flag(f))
+      if (v3Flag) fail(`--${v3Flag} is a LaunchpadV3 setting: use \`gang v3 create …\` (add --testnet for BSC testnet)`)
       try { assertCreateTarget(CONFIG.launchpad) } catch (e) { fail(e.message) }
       const note = parseNote()
       const links = parseLinks()

package/src/logo.js

@@ -4,6 +4,8 @@ import { UA } from './version.js'
 
 const MAX_BYTES = 512 * 1024
 const FETCH_TIMEOUT_MS = 20_000
+// a POST to /api/logos carries up to 512 KB of image (or 256 KB of JSON): give it longer than a fetch of headers
+const UPLOAD_TIMEOUT_MS = 60_000
 
 export const LOGO_API = (process.env.GANG_LOGO_API || 'https://gang.fun/api/logos').replace(/\/+$/, '')
 export const LOGO_UI = 'https://gang.fun/dev/logo'
@@ -43,6 +45,7 @@ async function postLogo(buf, what) {
       method: 'POST',
       headers: { 'content-type': 'application/json', accept: 'application/json', 'user-agent': UA },
       body: JSON.stringify({ image }),
+      signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS),
     })
     text = await res.text()
   } catch (e) {
@@ -56,6 +59,35 @@ async function postLogo(buf, what) {
   return { logoUrl: json.logoUrl, id: json.id, bytes: json.bytes ?? buf.length, api: LOGO_API }
 }
 
+/**
+ * Token metadata JSON (the token's contractURI / metaURI, permanent on-chain) → POST /api/logos as application/json →
+ * { url, id, bytes }. Keys with no value are left out. Same upload endpoint and CDN as logos.
+ */
+export async function uploadMetadata(meta) {
+  const clean = Object.fromEntries(Object.entries(meta).filter(([, v]) => v != null && v !== ''))
+  const buf = Buffer.from(JSON.stringify(clean))
+  if (buf.length > 256 * 1024) throw new Error(`metadata too large: ${buf.length} bytes (max 256 KB)`)
+  let res, text
+  try {
+    res = await fetch(LOGO_API, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', accept: 'application/json', 'user-agent': UA },
+      body: JSON.stringify({ file: `data:application/json;base64,${buf.toString('base64')}` }),
+      signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS),
+    })
+    text = await res.text()
+  } catch (e) {
+    throw fetchError(`metadata upload failed: ${why(e)}`, e)
+  }
+  let json
+  try { json = JSON.parse(text) } catch { throw statusError(`metadata upload non-JSON (${res.status}): ${text.slice(0, 200)}`, res.status) }
+  const url = json?.url || json?.logoUrl
+  if (!res.ok || !json?.ok || !url) {
+    throw statusError(`metadata upload failed (${res.status}): ${json?.error || text.slice(0, 200)}`, res.status)
+  }
+  return { url, id: json.id, bytes: json.bytes ?? buf.length, metadata: clean }
+}
+
 /** Read a local image → POST /api/logos → { logoUrl, id, bytes }. */
 export async function uploadLogoFile(filePath) {
   const abs = resolve(filePath)

package/src/pool.js

@@ -0,0 +1,312 @@
+import { parseAbi, encodeFunctionData, formatUnits, parseUnits, zeroAddress } from 'viem'
+import { decimalsOf, isMissingFunction, poolSellQuote, ROUTER_ABI, routerDeadline, step, units, GAS_RESERVE } from './steps.js'
+
+/**
+ * PancakeSwap (V2 pool) buys and sells of a graduated / launched token through GangRouter — V3 and 打新 tokens
+ * (`gang v3 buy|sell`, `gang fair buy|sell`) and V2 / Soft / U / S tokens (`gang buy|sell`), all the same way:
+ *   poolBuyBNB(token, quote, minTokensOut, deadline) payable  path [WBNB, token] or [WBNB, quote, token]
+ *   poolBuy(token, quote, quoteIn, minTokensOut, deadline)     path [quote, token]; approve quote → router first
+ *   poolSell(token, quote, amountIn, minQuoteOut, deadline)    path [token, quote]; approve token → router first
+ *   poolSellForBNB(token, quote, amountIn, minBnbOut, deadline) path [token, quote(, WBNB)], paid out as BNB
+ * The token lands in / the proceeds go to the caller. Approvals are for this trade's amount only.
+ * Minimums: a buy = Pancake getAmountsOut less the token's buy tax, less --slippage; a sell = the tax handler's
+ * previewSellNextBlock (the sell tax and the chunk of held tax it sells first included, as of the next block), or
+ * getAmountsOut less the sell tax when there is no handler quote (V2 tokens, untaxed V3), less --slippage.
+ */
+
+// Pancake V2 routers: a GangRouter address must never be one of these (they would take an approve and swap for anyone).
+// Quotes use the GangRouter's own pancakeRouter(), the router its pool* functions swap through.
+const DEX_ROUTERS = ['0x10ED43C718714eb63d5aA57B78B54704E256024E', '0xD99D1c33F9fC3444f8101754aBC46c52416550D1']
+const DEX_ABI = parseAbi(['function getAmountsOut(uint256 amountIn, address[] path) view returns (uint256[] amounts)'])
+const HANDLER_DEX_ABI = parseAbi(['function dexRouter() view returns (address)'])
+const ERC20_ABI = parseAbi([
+  'function balanceOf(address) view returns (uint256)',
+  'function allowance(address, address) view returns (uint256)',
+  'function approve(address, uint256) returns (bool)',
+  'function symbol() view returns (string)',
+])
+const WBNB_ABI = parseAbi(['function deposit() payable'])
+
+/** Gas note on a taxed gang token's pool sell (it sells a chunk of the held tax right before it). */
+export const POOL_SELL_GAS_NOTE = 'this sell needs about 700k gas (it also sells one chunk of the held tax first): let the wallet estimate gas, or give at least 750k; too little gas reverts with SwapBackOutOfGas'
+
+const same = (a, b) => String(a).toLowerCase() === String(b).toLowerCase()
+const minOf = (x, slippagePct) => (x * BigInt(Math.round((100 - slippagePct) * 100))) / 10_000n
+const lessBps = (x, bps) => x - (x * BigInt(bps)) / 10_000n
+const symbolOf = async (ctx, t) => { try { return await ctx.read(t, ERC20_ABI, 'symbol') } catch { return null } }
+const short = (e) => e?.shortMessage || String(e?.message || e).split('\n')[0]
+
+/** A contract call that reached the chain and reverted (or got no data back), as opposed to an RPC / network failure. */
+const isRevert = (e) => !!e?.walk?.((x) => ['ContractFunctionRevertedError', 'ContractFunctionZeroDataError', 'ExecutionRevertedError'].includes(x?.name) || x?.code === 3)
+
+/** A failure the command prints as is (a thrown PoolError ends poolTrade with { success: false, …fields }). */
+class PoolError extends Error {
+  constructor(message, fields = {}) { super(message); this.fields = fields }
+}
+const rpcError = (what, e) => new PoolError(`RPC error while ${what}: ${short(e)}`, { hint: 're-run; set GANG_RPC_URL / GANG_TESTNET_RPC_URL if the RPC keeps failing' })
+
+/** Last hop of Pancake getAmountsOut; a revert = no usable pool on the path, anything else = the RPC. */
+async function amountOut(ctx, dex, amountIn, path) {
+  try {
+    const amounts = await ctx.read(dex, DEX_ABI, 'getAmountsOut', [amountIn, path])
+    return amounts[amounts.length - 1]
+  } catch (e) {
+    if (!isRevert(e)) throw rpcError('quoting on PancakeSwap', e)
+    throw new PoolError(`PancakeSwap has no usable pool on the path ${path.join(' → ')}`, { path, detail: short(e), noPool: true })
+  }
+}
+
+const ROUTER_VIEW_ABI = parseAbi([
+  'function pad() view returns (address)', 'function wbnb() view returns (address)', 'function pancakeRouter() view returns (address)',
+])
+
+/**
+ * ctx.router must be a GangRouter with the pool functions, checked before any step is built (an approve to anything
+ * else would hand it the tokens): a contract; not a known DEX router nor the tax handler's dexRouter(); pad() (= ctx.pad
+ * for V3 / 打新) and wbnb() (= this chain's) readable; and pancakeRouter() — only the pool version has it — which is
+ * also where the quotes come from. Returns the Pancake router; throws a PoolError otherwise.
+ */
+async function gangRouter(ctx, handler, wantPad) {
+  const r = ctx.router
+  const notGang = (why) => new PoolError(`the router address ${r} is not a GangRouter (${why})`, {
+    router: r, hint: `set ${Number(ctx.chainId) === 56 ? 'GANG_ROUTER' : 'GANG_TESTNET_ROUTER'} to the GangRouter proxy`,
+  })
+  let code
+  try { code = await ctx.client.getCode({ address: r }) } catch (e) { throw rpcError('reading the router', e) }
+  if (!code || code === '0x') throw notGang(`no contract at it on chain ${ctx.chainId}`)
+  if (DEX_ROUTERS.some((d) => same(d, r))) throw notGang('it is the PancakeSwap V2 router')
+  if (handler) {
+    const dex = await ctx.read(handler, HANDLER_DEX_ABI, 'dexRouter').catch(() => null)
+    if (dex && same(dex, r)) throw notGang('it is the tax handler\'s dexRouter')
+  }
+  const view = async (fn) => {
+    try { return await ctx.read(r, ROUTER_VIEW_ABI, fn) } catch (e) {
+      if (!isRevert(e)) throw rpcError('reading the router', e)
+      return null
+    }
+  }
+  const [pad, wbnb, pancake] = [await view('pad'), await view('wbnb'), await view('pancakeRouter')]
+  if (!pad || !wbnb) throw notGang('it has no pad() / wbnb()')
+  if (!same(wbnb, ctx.wbnb)) throw notGang(`its wbnb() is ${wbnb}, not this chain's WBNB`)
+  if (wantPad && !same(pad, wantPad)) throw notGang(`its pad() is ${pad}, not this CLI's pad ${wantPad}`)
+  if (!pancake || pancake === zeroAddress) {
+    throw new PoolError(`the GangRouter at ${r} is an older version without PancakeSwap trades (no pancakeRouter() / pool functions)`, {
+      router: r, hint: 'it cannot trade in the pool and cannot be upgraded: use a CLI / GANG_ROUTER that points at the new GangRouter proxy, or trade on PancakeSwap directly',
+    })
+  }
+  return pancake
+}
+
+/**
+ * The pool function itself answers: called with a zero amount, the pool version reverts ZeroAmount() before touching
+ * anything. No answer (empty revert) = no such function on this router: refused before any approve.
+ */
+async function probePool(ctx, me, functionName, args, revertOf) {
+  const data = encodeFunctionData({ abi: ROUTER_ABI, functionName, args })
+  try {
+    await ctx.client.call({ account: me, to: ctx.router, data, value: 0n })
+  } catch (e) {
+    if (!isRevert(e)) throw rpcError('checking the router', e)
+    if (revertOf(e)?.error === 'ZeroAmount') return
+    if (isMissingFunction(e)) {
+      throw new PoolError(`the router at ${ctx.router} has no ${functionName}: not the GangRouter version with pool trades`, {
+        router: ctx.router, hint: 'use a CLI / GANG_ROUTER that points at the new GangRouter proxy, or trade on PancakeSwap directly',
+      })
+    }
+    throw new PoolError(`the router at ${ctx.router} answered ${functionName} unexpectedly`, { router: ctx.router, ...(revertOf(e) || { detail: short(e) }) })
+  }
+  throw new PoolError(`the router at ${ctx.router} accepted a zero-amount ${functionName}: not a GangRouter`, { router: ctx.router })
+}
+
+/**
+ * What the wallet still has to do before `need` of `token` can be pulled by the router: a WBNB wrap when it is WBNB and
+ * the wallet is short, then an approve for exactly `need`. [] when ready; { error } when it cannot pay.
+ */
+async function fundingOf(ctx, { me, token, need, spender, sym, approveStep }) {
+  const bal = await ctx.read(token, ERC20_ABI, 'balanceOf', [me])
+  const steps = []
+  if (bal < need) {
+    if (!same(token, ctx.wbnb)) {
+      return { error: { error: `not enough ${sym || 'tokens'}`, have: await units(ctx, token, bal), need: await units(ctx, token, need) } }
+    }
+    const missing = need - bal
+    const native = await ctx.client.getBalance({ address: me })
+    if (native < missing + GAS_RESERVE) {
+      return { error: { error: 'not enough BNB + WBNB (native BNB must also cover gas)', haveBnb: formatUnits(native, 18), needBnb: formatUnits(missing, 18), reserveForGas: formatUnits(GAS_RESERVE, 18) } }
+    }
+    steps.push({
+      tx: { from: me, to: token, data: encodeFunctionData({ abi: WBNB_ABI, functionName: 'deposit' }), value: missing },
+      meta: { step: 'wrap-bnb', wrap: formatUnits(missing, 18) },
+    })
+  }
+  if ((await ctx.read(token, ERC20_ABI, 'allowance', [me, spender])) < need) {
+    steps.push({
+      tx: { from: me, to: token, data: encodeFunctionData({ abi: ERC20_ABI, functionName: 'approve', args: [spender, need] }) },
+      meta: { step: approveStep, approve: await units(ctx, token, need), token, spender, note: 'only this trade\'s amount is approved' },
+    })
+  }
+  return { steps }
+}
+
+/**
+ * Pay a pool buy in native BNB? WBNB-quoted: yes unless --use-quote (or the curve's --use-wbnb); another quote: only
+ * with --pay-bnb (path WBNB → quote → token).
+ */
+export const poolPayBnb = (ctx, quote, flag) =>
+  (!quote || quote === zeroAddress || same(quote, ctx.wbnb) ? !flag('use-quote') && !flag('use-wbnb') : flag('pay-bnb'))
+
+const rawTx = (ctx, { from, to, data, value = 0n }) => ({ chainId: Number(ctx.chainId), from, to, data, value: value.toString() })
+
+/**
+ * Build a PancakeSwap trade through GangRouter. Returns the object the command prints.
+ *  p: { side: 'buy'|'sell', token, quote, me, amount (decimal string; sell: null with all), all, slippage,
+ *       buyTaxBps, sellTaxBps, handler (gang tax handler or null), swapBackGas (taxed gang token: the 700k note),
+ *       payBnb (buy), toBnb (sell), base (fields every step carries) }
+ *  io: { rawOnly, summarize, revertOf } — revertOf(e) → { error, hint } | null
+ */
+export async function poolTrade(ctx, p, io) {
+  try {
+    return await build(ctx, p, io)
+  } catch (e) {
+    if (!(e instanceof PoolError)) throw e
+    return { success: false, ...(p.base || {}), step: `pool-${p.side}`, error: e.message, ...e.fields }
+  }
+}
+
+async function build(ctx, p, { rawOnly, summarize, revertOf }) {
+  const { side, token, me, slippage, base = {} } = p
+  const quote = !p.quote || p.quote === zeroAddress ? ctx.wbnb : p.quote
+  const quoteWbnb = same(quote, ctx.wbnb)
+  const failOut = (o) => ({ success: false, ...base, ...o })
+  if (!ctx.router) {
+    return failOut({ step: `pool-${side}`, error: 'no GangRouter address for this network in this CLI version', hint: `set ${Number(ctx.chainId) === 56 ? 'GANG_ROUTER' : 'GANG_TESTNET_ROUTER'} to the GangRouter proxy, or trade on PancakeSwap directly` })
+  }
+  const dex = await gangRouter(ctx, p.handler, ctx.pad || null)
+  const quoteSymbol = (await symbolOf(ctx, quote)) || quote
+  const deadline = routerDeadline()
+  const taxPct = (bps) => (bps || 0) / 100
+  let call, probe, value = 0n, pull = null, fields
+  try {
+    if (side === 'buy') {
+      const payBnb = !!p.payBnb
+      const amountIn = parseUnits(p.amount, payBnb ? 18 : await decimalsOf(ctx, quote))
+      if (amountIn === 0n) throw new PoolError(`--amount ${p.amount} rounds to 0 in ${payBnb ? 'BNB' : quoteSymbol}`)
+      const path = payBnb ? (quoteWbnb ? [ctx.wbnb, token] : [ctx.wbnb, quote, token]) : [quote, token]
+      const gross = await amountOut(ctx, dex, amountIn, path)
+      const expect = lessBps(gross, p.buyTaxBps || 0)
+      const minOut = minOf(expect, slippage)
+      if (payBnb) {
+        const native = await ctx.client.getBalance({ address: me }).catch((e) => { throw rpcError('reading the BNB balance', e) })
+        if (native < amountIn + GAS_RESERVE) {
+          return failOut({
+            step: 'pool-buy', error: 'not enough BNB for this buy (native BNB must also cover gas)',
+            haveBnb: formatUnits(native, 18), needBnb: p.amount, reserveForGas: formatUnits(GAS_RESERVE, 18),
+            ...(quoteWbnb && { hint: 'add --use-quote to pay from WBNB instead' }),
+          })
+        }
+        call = { functionName: 'poolBuyBNB', args: [token, quote, minOut, deadline] }
+        probe = [token, quote, 0n, deadline]
+        value = amountIn
+      } else {
+        call = { functionName: 'poolBuy', args: [token, quote, amountIn, minOut, deadline] }
+        probe = [token, quote, 0n, 0n, deadline]
+        pull = { token: quote, need: amountIn, sym: quoteSymbol, approveStep: 'approve-quote' }
+      }
+      fields = {
+        step: 'pool-buy', venue: 'pancakeswap', via: 'router', router: ctx.router, function: call.functionName,
+        spend: p.amount, payWith: payBnb ? 'BNB' : quoteSymbol, quote: quoteSymbol, path,
+        expectTokensBeforeTax: formatUnits(gross, 18), buyTaxPct: taxPct(p.buyTaxBps),
+        expectTokens: formatUnits(expect, 18), minTokensOut: formatUnits(minOut, 18), slippagePct: slippage,
+        deadline: Number(deadline), quotedWith: 'getAmountsOut',
+        note: `the tokens go straight to ${me}; minTokensOut = getAmountsOut less the ${taxPct(p.buyTaxBps)}% buy tax, less --slippage (the buy reverts below it)`,
+      }
+    } else {
+      const bal = await ctx.read(token, ERC20_ABI, 'balanceOf', [me]).catch((e) => { throw rpcError('reading the token balance', e) })
+      if (bal === 0n) return failOut({ step: 'pool-sell', error: 'no balance to sell', wallet: me })
+      const amount = p.all ? bal : parseUnits(p.amount, 18)
+      if (amount === 0n) throw new PoolError(`--amount ${p.amount} rounds to 0 tokens`)
+      if (amount > bal) return failOut({ step: 'pool-sell', error: 'amount exceeds balance', balance: formatUnits(bal, 18) })
+      const taxed = (p.sellTaxBps || 0) > 0
+      let quoteOut, quotedWith
+      if (taxed && p.handler) {
+        // a taxed gang token: only the handler's quote counts the chunk of held tax sold right before the sell
+        const q = await poolSellQuote(ctx, p.handler, token, amount)
+        if (!q) throw new PoolError('the tax handler gave no sell quote (RPC error or revert): no minimum is guessed for a taxed sell', { handler: p.handler, hint: 're-run' })
+        if (q.out === 0n) throw new PoolError('the tax handler quotes 0 for this sell (the token has no pool tax pair set): no minimum to sell against', { handler: p.handler })
+        quoteOut = q.out; quotedWith = q.quotedWith
+      } else {
+        // untaxed, or a V2 token (its tax handler sells nothing during the sell): getAmountsOut of what reaches the pair
+        quoteOut = await amountOut(ctx, dex, lessBps(amount, p.sellTaxBps || 0), [token, quote])
+        quotedWith = 'getAmountsOut'
+      }
+      const toBnb = !!p.toBnb
+      const path = toBnb && !quoteWbnb ? [token, quote, ctx.wbnb] : [token, quote]
+      const out = toBnb && !quoteWbnb ? await amountOut(ctx, dex, quoteOut, [quote, ctx.wbnb]) : quoteOut
+      const minOut = minOf(out, slippage)
+      call = { functionName: toBnb ? 'poolSellForBNB' : 'poolSell', args: [token, quote, amount, minOut, deadline] }
+      probe = [token, quote, 0n, 0n, deadline]
+      pull = { token, need: amount, sym: null, approveStep: 'approve' }
+      const outDec = toBnb ? 18 : await decimalsOf(ctx, quote)
+      fields = {
+        step: 'pool-sell', venue: 'pancakeswap', via: 'router', router: ctx.router, function: call.functionName,
+        amount: formatUnits(amount, 18), receive: toBnb ? 'BNB' : quoteSymbol, quote: quoteSymbol, path,
+        sellTaxPct: taxPct(p.sellTaxBps), expectOut: formatUnits(out, outDec), minOut: formatUnits(minOut, outDec), slippagePct: slippage,
+        deadline: Number(deadline), quotedWith,
+        ...(toBnb && !quoteWbnb && { expectQuoteBeforeBnb: await units(ctx, quote, quoteOut) }),
+        gas: p.swapBackGas ? POOL_SELL_GAS_NOTE : 'let the wallet estimate gas',
+        note: quotedWith === 'getAmountsOut'
+          ? `minOut = getAmountsOut of the amount less the ${taxPct(p.sellTaxBps)}% sell tax${toBnb && !quoteWbnb ? ' (then quote → WBNB)' : ''}, less --slippage (the sell reverts below it)`
+          : `minOut = the tax handler's ${quotedWith} (sell tax and the chunk of held tax sold first included, as of the next block)${toBnb && !quoteWbnb ? ', then getAmountsOut quote → WBNB' : ''}, less --slippage (the sell reverts below it)`,
+      }
+    }
+  } catch (e) {
+    if (e instanceof PoolError && e.fields.noPool) {
+      // a BNB leg through a non-WBNB quote needs a WBNB/quote pool on Pancake as well
+      const bnbLeg = !quoteWbnb && (side === 'buy' ? p.payBnb : p.toBnb)
+      const { noPool: _n, ...f } = e.fields
+      return failOut({
+        step: `pool-${side}`, error: e.message, ...f,
+        ...(bnbLeg && { hint: `no WBNB/${quoteSymbol} pool to route through: ${side === 'buy' ? 'drop --pay-bnb to pay with the quote' : 'drop --to-bnb to receive the quote'}` }),
+      })
+    }
+    throw e
+  }
+
+  // the router has this pool function (an old router is refused here, before any approve)
+  await probePool(ctx, me, call.functionName, probe, revertOf)
+  const swap = { from: me, to: ctx.router, data: encodeFunctionData({ abi: ROUTER_ABI, ...call }), value }
+  const pre = pull ? await fundingOf(ctx, { me, ...pull, spender: ctx.router }) : { steps: [] }
+  if (pre.error) return failOut({ step: fields.step, ...pre.error })
+  const extra = { chainId: Number(ctx.chainId), token, ...base }
+
+  if (pre.steps.length) {
+    if (rawOnly) {
+      // raw txs: every step in order (the swap is not simulated: it needs the steps before it on-chain)
+      const steps = [...pre.steps.map((s) => ({ ...s.meta, tx: rawTx(ctx, s.tx) })), { step: fields.step, function: fields.function, tx: rawTx(ctx, swap) }]
+      return {
+        success: true, ...extra, ...fields, step: steps[0].step, steps, tx: steps[0].tx,
+        note: `send the ${steps.length} txs in steps[] in order (tx = the first); the ${fields.step} is not simulated until the ${steps.slice(0, -1).map((s) => s.step).join(' / ')} is mined. ${fields.note}`,
+      }
+    }
+    const first = pre.steps[0]
+    return step(ctx, first.tx, {
+      ...extra, ...first.meta, next: fields.step,
+      then: { function: fields.function, ...(side === 'buy' ? { spend: fields.spend, minTokensOut: fields.minTokensOut } : { amount: fields.amount, minOut: fields.minOut }) },
+      note: `${first.meta.note ? `${first.meta.note}. ` : ''}after executing, re-run the same command for the ${pre.steps.length > 1 ? 'next step' : fields.step}`,
+    }, false, summarize)
+  }
+
+  // eth_call the swap: a revert names the reason (router / pool / token) and builds no preview
+  try {
+    await ctx.client.call({ account: me, to: swap.to, data: swap.data, value: swap.value })
+  } catch (e) {
+    if (!isRevert(e)) throw rpcError('simulating the trade', e)
+    const r = revertOf(e)
+    return failOut({
+      ...extra, ...fields, reverted: true, ...(r || { error: short(e) }),
+      // no `tx` key: nothing here is meant to be signed
+      ...(rawOnly && { doNotSend: true, unsentTxForInspection: rawTx(ctx, swap), txNote: 'DO NOT SEND: the simulation reverted; shown for inspection only' }),
+    })
+  }
+  return step(ctx, swap, { ...extra, ...fields }, rawOnly, summarize)
+}