@gangfun/cli 0.12.0 → 0.13.0

package/src/buyback.js

@@ -0,0 +1,183 @@
+import { createPublicClient, http, parseAbi, encodeFunctionData, formatUnits, hexToString, isAddress, zeroAddress } from 'viem'
+import { padNets, NOT_ON_MAINNET } from './gangpad.js'
+import { walletFor } from './fair.js'
+import { parseNum, revertOf as revertIn, step } from './steps.js'
+
+/**
+ * `gang buyback …` and `gang create … --buyback <pct>` — GangBuybackSplitter (dev 税按比例回购销毁): a V3 token's tax
+ * recipient that splits each payment between a buy-back in the token's PancakeSwap pool, sent to 0xdead, and the dev.
+ * GangBuybackSplitterFactory clones one per token for the dev (`create(bps, salt)`, at `predict(dev, salt)`) and has
+ * GangHandlerAdmin list it, so the dev names it as the recipient at create (launch.js does the three steps: clone →
+ * create → bind). A dev who doesn't
+ * want it leaves --buyback out: the tax goes to their own address as before.
+ * The ratio: a raise applies at once, a cut 3 days after it is asked for (then anyone applies it within 7 days, or it
+ * lapses). The keeper buys back in chunks (≤ 0.5% of the pool's quote side, never > 2% above the 10-minute average).
+ * Env: GANG_SPLITTER_FACTORY / GANG_TESTNET_SPLITTER_FACTORY override the built-in factory addresses.
+ */
+
+// BSC 56, 2026-10-28 (docs/MAINNET-BUYBACK-SPLITTER-2026-10-28.md); lists clones once the Safe ran its batch
+export const MAINNET_SPLITTER_FACTORY = '0x6bcd79206da85Aa0643Db2164Ab887b468618546'
+export const TESTNET_SPLITTER_FACTORY = '0x0Ff5C8801BdeaDac374fC14fEd6e7B31977c9DA1'
+export const BUYBACK_TYPE = 'buyback-burn-v1'
+
+export const FACTORY_ABI = parseAbi([
+  'function create(uint16 buybackBps, bytes32 salt) returns (address splitter)',
+  'function predict(address dev, bytes32 salt) view returns (address)',
+  'function pad() view returns (address)',
+  'error NotAgent()',
+  'error NotFactory()',
+  'error BadBps()',
+])
+
+export const SPLITTER_ABI = parseAbi([
+  'function moduleType() view returns (bytes32)',
+  'function dev() view returns (address)',
+  'function token() view returns (address)',
+  'function quote() view returns (address)',
+  'function buybackBps() view returns (uint16)',
+  'function pendingCut() view returns (bool live, uint16 bps, uint64 at)',
+  'function buybackLeft() view returns (uint256)',
+  'function unsplit() view returns (uint256)',
+  'function devOwed() view returns (uint256)',
+  'function previewBurn() view returns (bool ready, uint256 quoteIn, uint256 tokensOut)',
+  'function bind(address token)',
+  'function setBuybackBps(uint16 newBps)',
+  'function applyBuybackBps()',
+  'function releaseDev() returns (uint256)',
+  'error NotDev()',
+  'error BadBps()',
+  'error AlreadyBound()',
+  'error NotCurve()',
+  'error NotCreator()',
+  'error NotRecipient()',
+  'error NoProposal()',
+  'error NotDue()',
+  'error CutLapsed()',
+  'error NothingOwed()',
+])
+
+const PAD_ABI = parseAbi([
+  'function taxConfigOf(address token) view returns (uint16 buyTaxBps, uint16 sellTaxBps, uint16 dividendBps, address recipient)',
+])
+
+const HINTS = {
+  NotAgent: 'only an Agent can create a V3 token, so only an Agent gets a buy-back splitter',
+  NotFactory: 'this factory is not allowed on the platform\'s GangHandlerAdmin (any more): it cannot list a splitter',
+  NotDev: 'only the dev this splitter was made for can change its ratio',
+  NotCreator: 'the token was not created by this splitter\'s dev',
+  NotRecipient: 'the token does not pay its tax to this splitter',
+  AlreadyBound: 'the splitter is bound to a token already',
+  NotDue: 'the 3-day notice of this cut has not run yet',
+  CutLapsed: 'the cut was not applied within 7 days after its notice and has lapsed: ask for it again',
+  NoProposal: 'no cut asked for',
+  NothingOwed: 'nothing is owed to the dev',
+}
+const revertOf = (e) => revertIn(e, [SPLITTER_ABI, FACTORY_ABI], HINTS)
+
+export function splitterFactoryAddress(testnet) {
+  return (testnet ? process.env.GANG_TESTNET_SPLITTER_FACTORY || TESTNET_SPLITTER_FACTORY
+    : process.env.GANG_SPLITTER_FACTORY || MAINNET_SPLITTER_FACTORY) || null
+}
+
+export const notDeployed = (testnet) =>
+  `GangBuybackSplitterFactory is not deployed on ${testnet ? 'the BSC testnet' : 'BSC mainnet'} in this CLI version: set ${testnet ? 'GANG_TESTNET_SPLITTER_FACTORY' : 'GANG_SPLITTER_FACTORY'} to its address`
+
+/** --buyback <pct> (0–100, the share of the recipient's part bought back) in bps. */
+export const buybackBpsOf = (fail, raw) => Math.round(parseNum(fail, 'buyback', raw, 0, 100) * 100)
+
+const pct = (bps) => Number(bps) / 100
+const iso = (s) => new Date(Number(s) * 1000).toISOString()
+
+/** The splitter's state when `addr` is a GangBuybackSplitter; null when it is not (an EOA, a partner, another module). */
+export async function splitterOf(read, addr) {
+  if (!addr || addr === zeroAddress) return null
+  let type
+  try { type = await read(addr, SPLITTER_ABI, 'moduleType') } catch { return null }
+  if (hexToString(type, { size: 32 }) !== BUYBACK_TYPE) return null
+  const [dev, token, bps, cut, left, unsplit, owed, burn] = await Promise.all(
+    ['dev', 'token', 'buybackBps', 'pendingCut', 'buybackLeft', 'unsplit', 'devOwed', 'previewBurn'].map((f) => read(addr, SPLITTER_ABI, f)))
+  // the pad takes 18-decimal quotes only
+  const q = (x) => formatUnits(x, 18)
+  return {
+    splitter: addr, moduleType: BUYBACK_TYPE, dev, token: token === zeroAddress ? null : token, buybackPct: pct(bps), buybackBps: Number(bps),
+    pendingCut: cut[0] ? { toPct: pct(cut[1]), appliesFrom: iso(cut[2]), lapsesAfter: iso(Number(cut[2]) + 7 * 86400) } : null,
+    buybackLeft: q(left), unsplit: q(unsplit), devOwed: q(owed),
+    nextChunk: burn[0] ? { quoteIn: q(burn[1]), tokensBurned: formatUnits(burn[2], 18) } : null,
+    note: `${pct(bps)}% of each tax payment to this recipient is bought back in the pool and burned (0xdead), the rest goes to the dev; a raise applies at once, a cut only 3 days after it is asked for`,
+  }
+}
+
+function buybackCtx(testnet) {
+  const net = padNets('v3')[testnet ? 'testnet' : 'mainnet']
+  if (!net.pad) throw new Error(NOT_ON_MAINNET)
+  const client = createPublicClient({ chain: net.chain, transport: http(net.rpc) })
+  return { ...net, client, read: (address, abi, functionName, args = []) => client.readContract({ address, abi, functionName, args }) }
+}
+
+/** Dry-run a call; { failed } with the revert when it would not pass. */
+export async function simulateCall(client, from, address, abi, functionName, args = []) {
+  try {
+    const { result } = await client.simulateContract({ account: from, address, abi, functionName, args })
+    return { result }
+  } catch (e) {
+    const r = revertOf(e)
+    return { failed: r ? { reverted: true, ...r } : { reverted: false, error: e.shortMessage || e.message.split('\n')[0] } }
+  }
+}
+
+const SUBS = ['status', 'set', 'apply', 'bind', 'release']
+const USAGE = 'usage: gang buyback <status|set|apply|bind|release> --token <addr> [--pct <0-100>] [--testnet] — see gang help'
+
+/** `gang buyback <sub>`: the splitter of a V3 token (its tax recipient), found from --token. */
+export async function runBuyback(sub, { opt, flag, out, fail, summarize }) {
+  if (!SUBS.includes(sub)) return fail(USAGE, { got: sub ?? null })
+  const testnet = flag('testnet')
+  const rawOnly = flag('calldata')
+  let ctx
+  try { ctx = buybackCtx(testnet) } catch (e) { return fail(e.message) }
+  const token = opt('token')
+  if (!isAddress(token ?? '')) fail('--token must be a V3 token address (0x…)', { got: token ?? null })
+  let recipient
+  try { recipient = (await ctx.read(ctx.pad, PAD_ABI, 'taxConfigOf', [token]))[3] } catch {
+    return fail('not a V3 token on this pad', { token, chainId: Number(ctx.chainId) })
+  }
+  const s = await splitterOf(ctx.read, recipient)
+  if (!s) return fail('this token\'s tax recipient is not a buy-back splitter', { token, recipient: recipient === zeroAddress ? null : recipient })
+  const chainId = Number(ctx.chainId)
+  const me = () => walletFor(ctx, opt('from'))
+  const send = async (functionName, args, extra) => {
+    const sim = await simulateCall(ctx.client, me(), s.splitter, SPLITTER_ABI, functionName, args)
+    if (sim.failed) return out({ success: false, step: functionName, ...sim.failed })
+    const data = encodeFunctionData({ abi: SPLITTER_ABI, functionName, args })
+    return out(step(ctx, { from: me(), to: s.splitter, data }, { chainId, token, splitter: s.splitter, ...extra }, rawOnly, summarize))
+  }
+
+  if (sub === 'status') return out({ success: true, chainId, ...s, ...(s.token === null && { bound: false }) })
+
+  if (sub === 'bind') {
+    if (s.token) return fail('already bound', { boundTo: s.token })
+    return send('bind', [token], { step: 'bind', note: 'anyone may bind; the token must be the dev\'s and pay its tax to this splitter' })
+  }
+
+  if (sub === 'set') {
+    if (me().toLowerCase() !== s.dev.toLowerCase()) return fail(HINTS.NotDev, { wallet: me(), dev: s.dev })
+    if (!flag('pct')) fail('--pct <0-100> required: the new buy-back share')
+    const bps = Math.round(parseNum(fail, 'pct', opt('pct'), 0, 100) * 100)
+    return send('setBuybackBps', [bps], bps >= s.buybackBps
+      ? { step: 'set-buyback', fromPct: s.buybackPct, toPct: bps / 100, note: `applies at once${s.pendingCut ? ' and cancels the pending cut' : ''}` }
+      : {
+          step: 'ask-cut', fromPct: s.buybackPct, toPct: bps / 100, appliesFromAbout: new Date(Date.now() + 3 * 86400_000).toISOString(),
+          note: `a cut waits 3 days (holders see it coming), then anyone runs gang buyback apply --token ${token}${testnet ? ' --testnet' : ''} within 7 days or it lapses${s.pendingCut ? '; this replaces the cut already asked for' : ''}`,
+        })
+  }
+
+  if (sub === 'apply') {
+    if (!s.pendingCut) return fail(HINTS.NoProposal, { buybackPct: s.buybackPct })
+    if (Date.parse(s.pendingCut.appliesFrom) > Date.now()) return fail(HINTS.NotDue, { appliesFrom: s.pendingCut.appliesFrom })
+    return send('applyBuybackBps', [], { step: 'apply-cut', fromPct: s.buybackPct, toPct: s.pendingCut.toPct, note: 'anyone may apply a cut once its notice ran' })
+  }
+
+  // release
+  if (!(Number(s.devOwed) > 0)) return fail(HINTS.NothingOwed)
+  return send('releaseDev', [], { step: 'release', amount: s.devOwed, note: 'anyone may; the dev gets what a failed push left owed' })
+}

package/src/fair.js

@@ -5,6 +5,7 @@ import { API } from './discover.js'
 import { UA } from './version.js'
 import { MERGED_ERRORS_ABI, MERGED_HINTS, NOT_ON_MAINNET, notThisKind, padNets } from './gangpad.js'
 import { poolPayBnb, poolTrade } from './pool.js'
+import { bondAddress, bondGuard } from './bond.js'
 
 /**
  * `gang fair …` — 打新 (fair mint): one fixed price per share both ways (mint buys at it, withdraw sells back at it);
@@ -393,6 +394,11 @@ export async function runFair(sub, { opt, flag, out, fail, summarize, resolveLog
     const held = await ctx.read(ctx.pad, PAD_ABI, 'positions', [token, me])
     if (!held) return fail('this wallet has no shares in this sale')
     const shares = flag('all') ? Number(held) : parseIntIn(fail, 'shares', opt('shares'), 1, Number(held))
+    // a bond posted during the sale already binds: selling shares back takes their tokens out of the creator's wallet
+    const guard = bondAddress(testnet) && await bondGuard(ctx, {
+      token, me, amount: BigInt(shares) * (await ctx.read(ctx.pad, PAD_ABI, 'TOKENS_PER_SHARE')), testnet, breakBond: flag('break-bond'), settleFirst: flag('settle-first'),
+    }, rawOnly, summarize)
+    if (guard?.refuse) return out({ success: false, step: 'withdraw', wallet: me, ...guard.refuse })
     const [payout, fee] = await ctx.read(ctx.pad, PAD_ABI, 'previewWithdraw', [token, me, BigInt(shares)])
     // the price is fixed, so only the exit fee can move the payout: a mint landing first can restart the 7-day clock
     // and bring a 1–2% fee back. 0.1% below the preview refuses that and nothing else.
@@ -404,7 +410,7 @@ export async function runFair(sub, { opt, flag, out, fail, summarize, resolveLog
       step: 'withdraw', chainId: Number(ctx.chainId), token, shares,
       receive: await units(ctx, sale.quote, payout), minReceive: await units(ctx, sale.quote, minPayout),
       exitFee: await units(ctx, sale.quote, fee), quote: sale.quoteSymbol,
-      exitFeePct: sale.exitFeeNowPct,
+      exitFeePct: sale.exitFeeNowPct, ...guard?.info,
       note: sale.stale
         ? `no progress for 7 days: no exit fee, the full mint price back; the ${sale.mintFeePct}% paid at mint is not returned`
         : `mint price − ${sale.exitFeeNowPct}% exit fee (none after 7 days without 10 new shares); the ${sale.mintFeePct}% paid at mint is not returned`,
@@ -462,6 +468,7 @@ export async function runFair(sub, { opt, flag, out, fail, summarize, resolveLog
       amount: sub === 'sell' && flag('all') ? null : parseAmount(fail, 'amount', opt('amount')), all: sub === 'sell' && flag('all'),
       swapBackGas: Number(sellTaxBps) > 0, payBnb: sub === 'buy' && poolPayBnb(ctx, sale.quote, flag), toBnb: flag('to-bnb'),
       base: { kind: 'fair', pair: sale.pair, ...notes.pool, ...(outWarning && { ...outWarning, confirmedOut: true }) },
+      ...(sub === 'sell' && { bond: { testnet, breakBond: flag('break-bond'), settleFirst: flag('settle-first') } }),
     }, { rawOnly, summarize, revertOf }))
   }
 

package/src/index.js

@@ -17,6 +17,9 @@ import { rememberPreview, previewFor } from './previews.js'
 import { UA, checkUpdate } from './version.js'
 import { runFair, FAIR_EVENT_ABIS } from './fair.js'
 import { runV3, v3Ctx, V3_EVENT_ABIS } from './v3.js'
+import { runBond } from './bond.js'
+import { runBuyback } from './buyback.js'
+import { FAIR_DEV_BUY, isLaunch, LAUNCH_FLAGS, runLaunch } from './launch.js'
 import { poolPayBnb, poolTrade } from './pool.js'
 import { parseAmount, ROUTER_ABI, ROUTER_HINTS, revertOf as revertIn, step as writeStep } from './steps.js'
 import { MERGED_ERRORS_ABI, kindOf, padNets } from './gangpad.js'
@@ -277,6 +280,21 @@ graduated tokens only).
                                          gang.fun; the token's contractURI / metaURI, permanent). --logo-uri images are copied
                                          to gang.fun first (other hosts expire); --keep-logo-uri puts a permanent URL (e.g.
                                          ipfs://) on-chain as is; gang.fun files always go on as ipfs://<cid>
+  LAUNCH in one command (one tx per run: execute it, then run the very same command again until launch.stage = done):
+  gang create … --dev-buy <quote> [--bond <quote> [--bond-hold <tokens|N%|all>] --bond-days <7-90>]
+                                         V3: create → the dev buys on the curve (--dev-buy, as gang buy) → bonds what it
+                                         holds (--bond-hold, default all; gang bond post). Wrap / approve steps come in between
+  gang create … --buy-tax <1-5> --sell-tax <1-5> --buyback <0-100> [--dev-buy … [--bond …]]
+                                         V3, taxed: the recipient's part of the tax is split, --buyback % bought back in the
+                                         pool and burned (0xdead), the rest to you. Steps: clone your buy-back splitter
+                                         (GangBuybackSplitterFactory; listed as a recipient in the same tx) → create with it as
+                                         the recipient → bind → the rest of the launch. Without --buyback the tax goes to you
+  gang create --fair … [--shares <n>] --bond <quote> [--bond-hold …] --bond-days <7-90>
+                                         打新: create (the dev's --shares are bought in it) → bond. Progress is read from the
+                                         chain (a token this wallet created with this symbol since the plan); a run that finds
+                                         none never creates again by itself (the first may still be landing): --restart does.
+                                         Done stays done: running it again only reports. --note goes on the create only;
+                                         --bond needs GangBond on the network (testnet only for now), checked before the create
   NOTES: gang create / buy / sell, and gang mint / withdraw on a 打新 sale, take [--note "<why>" [--conf 0-100]
                                          [--reveal-after 1-72h]] (a create's note is its launch manifesto); gang buy also
                                          --follow <note tx>. Mainnet only; pool trades (graduated / launched) carry no note
@@ -295,6 +313,47 @@ graduated tokens only).
                                          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. V2 / Soft / U / S:
                                          --from only on graduated tokens, mainnet only
+                                         A creator selling below its bonded X (gang bond) is refused unless --break-bond;
+                                         past the deadline, --settle-first settles the bond before the sell.
+
+BOND (押金承诺, GangBond; any GangLaunchpad token, from create on; GANG_BOND / GANG_TESTNET_BOND = its address):
+  gang bond post --token <addr> --hold <tokens|N%> --days <7-90> (--amount <quote> | --cover <coverage %>) [--use-wbnb]
+                                         creator only, any time after create (V3: buy on the curve first): bond in the token's
+                                         quote (WBNB: paid in BNB, --use-wbnb pays WBNB; also on topup) promising the creator
+                                         keeps at least --hold tokens (N% = of the 1B supply) from now on. The --days clock
+                                         starts when the token graduates / launches (at once if it already has). --cover 100 =
+                                         exactly what dumping X fetches now (only once on the pair). No early withdrawal;
+                                         below X anyone reports it, on the curve too
+  gang bond topup --token <addr> (--amount <quote> | --cover <target %>) | gang bond raise-hold --token <addr> --hold <tokens|N%>
+  gang bond extend --token <addr> --days <n>
+                                         creator only: the bond only grows, X only rises, the commitment only gets longer (90
+                                         days in all before the pair; a deadline ≤ 90 days from now after it)
+  gang bond status --token <addr>        state, phase (pending: waiting for the pair / running), X and the creator's balance /
+                                         headroom, coverage + tier once on the pair (≥100% full cover, 50–100% bond, <50% no
+                                         badge), toFullCover, time left, buy-back progress, the creator's record
+  gang bond start --token <addr>         anyone, once the token graduated / launched: start the clock (deadline = now + days)
+  gang bond report --token <addr>        anyone, when the creator holds less than X: 1% of the bond to you, the rest buys
+                                         back and burns the token (simulated first; nothing is sent when not violated)
+  gang bond settle --token <addr>        anyone, after the deadline while X is held: the bond goes back to the creator
+  gang bond refund --token <addr>        creator, posted before the pair and still no pair 30 days later: run it once to ask
+                                         (a 3-day notice: X still binds, graduation / launch voids it), again after it to
+                                         get the bond back
+  gang bond burn --token <addr> [--slippage 1]
+                                         anyone: one buy-back chunk of a slashed bond (≤ 0.5% of the pair's quote side; waits
+                                         for a 10-minute average and skips when the price is > 2% above it). Slashed before the
+                                         pair: waits for it; none 30 days after the post → the rest goes to 0xdead as quote
+  gang bond tx --hash <0x..>             decode GangBond events. --testnet, --calldata, --from as in gang v3. A bonded
+                                         creator's gang v3 sell (curve or pool), gang fair sell and gang fair withdraw are
+                                         checked against X (--break-bond / --settle-first)
+BUYBACK (a V3 token whose recipient is a buy-back splitter; GANG_SPLITTER_FACTORY / GANG_TESTNET_SPLITTER_FACTORY):
+  gang buyback status --token <addr>     ratio, a cut asked for (applies from / lapses after), quote waiting to be bought
+                                         back, owed to the dev, the next chunk (the keeper buys it back every few minutes)
+  gang buyback set --token <addr> --pct <0-100>
+                                         dev only: a higher share applies at once; a lower one after a 3-day notice
+  gang buyback apply --token <addr>      anyone: apply a cut whose notice ran (within 7 days, or it lapses)
+  gang buyback bind --token <addr> | gang buyback release --token <addr>
+                                         anyone: bind the splitter to its token (the launch does it) / push the dev what a
+                                         failed payment left owed. --testnet, --calldata, --from as in gang v3
   gang execute --request-id <id>         broadcast a previewed call
   gang tx --hash <0x..> [--testnet]      wait for receipt and decode Gang events: V2 / Soft / U / S, GangLaunchpad (V3 /
                                          打新, tax router, vaults) (publishes a queued --note; mainnet). GangLaunchpad events
@@ -662,6 +721,8 @@ const createGateAgent = (me) =>
 
 // what `gang v3` / `gang fair` (and `gang create`) get from here; each call adds its `notes` (padNotes)
 const PAD_IO = { opt, flag, out, fail, summarize: summarizePreview, resolveLogo: resolveLogoUri, checkMeta: parseMeta, resolveMeta: resolveMetaUri }
+/** `gang create … --dev-buy … [--bond …]` / `gang fair create … --bond …`: one command, one tx per run (launch.js). */
+const LAUNCH_DEPS = { io: PAD_IO, runV3, runFair, runBond, padNotes: (kind, sub, pre) => padNotes(kind, sub, pre) }
 
 // ---------------------------------------------------------------- one command per action, whatever the pad
 // gang buy|sell|info|status|claim|mint|withdraw|release --token <addr> ask GangLaunchpad's kindOf what the token is and
@@ -780,16 +841,19 @@ function create() {
   if (flag('fair')) {
     const wrong = V3_CREATE_FLAGS.find(flag)
     if (wrong) fail(`--${wrong} is a V3 tax setting; a 打新 sale's pool tax is fixed (1%): leave it out, or drop --fair for a V3 token`)
+    if (isLaunch('fair', flag)) return runLaunch('fair', LAUNCH_DEPS)
     return runFair('create', { ...PAD_IO, notes: padNotes('fair', 'create') })
   }
   const wrong = FAIR_CREATE_FLAGS.find(flag)
   if (wrong) fail(`--${wrong} is a 打新 (fair-mint) setting: add --fair to create a sale (gang create --fair …)`)
+  if (isLaunch('v3', flag)) return runLaunch('v3', LAUNCH_DEPS)
   return runV3('create', { ...PAD_IO, notes: padNotes('v3', 'create') })
 }
 
 // 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', 'info', 'status', 'quote',
-  'buy', 'follow', 'sell', 'claim', 'mint', 'withdraw', 'release', 'upload-logo', 'create', 'execute', 'tx', 'fair', 'v3'])
+  'buy', 'follow', 'sell', 'claim', 'mint', 'withdraw', 'release', 'upload-logo', 'create', 'execute', 'tx', 'fair', 'v3', 'bond',
+  'buyback'])
 // gang tx decodes these beside the V2 / Soft / U / S pads' events (GangLaunchpad: both kinds; the tax router; the vaults)
 const GANG_EVENT_ABIS = [...V3_EVENT_ABIS, ...FAIR_EVENT_ABIS]
 
@@ -803,11 +867,26 @@ async function main() {
   if (flag('description') && !tokenCreate) {
     fail('--description only applies when creating a token (`gang create`, `gang create --fair`; it goes into the token metadata)')
   }
+  // --bond-hold / --bond-days / --restart only mean something in a chained launch (--dev-buy / --bond); never drop them silently
+  // gang fair create and gang create --fair are 打新 creates; the rest V3
+  const launchKind = cmd === 'fair' || (cmd === 'create' && flag('fair')) ? 'fair' : 'v3'
+  if (tokenCreate && !isLaunch(launchKind, flag)) {
+    // a 打新 dev buys with --shares in the create itself: say so here, not "add --bond" (which would only lead to that)
+    if (launchKind === 'fair' && flag('dev-buy')) fail(FAIR_DEV_BUY)
+    const lone = LAUNCH_FLAGS.find((f) => flag(f))
+    if (lone) fail(`--${lone} only applies to a launch in one command: add --bond <quote>${launchKind === 'fair' ? '' : ' (or --dev-buy <quote> / --buyback <pct>)'}`)
+  }
   switch (cmd) {
     case 'fair':
+      if (args[1] === 'create' && isLaunch('fair', flag)) return runLaunch('fair', LAUNCH_DEPS)
       return runFair(args[1], alias('fair', args[1]))
     case 'v3':
+      if (args[1] === 'create' && isLaunch('v3', flag)) return runLaunch('v3', LAUNCH_DEPS)
       return runV3(args[1], alias('v3', args[1]))
+    case 'bond':
+      return runBond(args[1], { opt, flag, out, fail, summarize: summarizePreview })
+    case 'buyback':
+      return runBuyback(args[1], { opt, flag, out, fail, summarize: summarizePreview })
     case 'preflight': {
       const issues = []
       const status = bawStatus()

package/src/launch.js

@@ -0,0 +1,284 @@
+import { createHash, randomBytes } from 'node:crypto'
+import { mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { createPublicClient, http, parseAbi, formatUnits, encodeFunctionData, zeroAddress } from 'viem'
+import { DIR } from './notes.js'
+import { padNets, NOT_ON_MAINNET } from './gangpad.js'
+import { bondAddress, BOND_ABI } from './bond.js'
+import { walletFor } from './fair.js'
+import { parseAmount, parseIntIn, step } from './steps.js'
+import { buybackBpsOf, FACTORY_ABI, notDeployed, simulateCall, SPLITTER_ABI, splitterFactoryAddress, splitterOf } from './buyback.js'
+
+/**
+ * One command for a launch: `gang create … [--buyback <pct>] [--dev-buy <quote> [--bond <quote> [--bond-hold <tokens|N%|all>]
+ * --bond-days <7-90>]]` (V3) and `gang fair create … [--shares <n>] --bond <quote> [--bond-hold …] --bond-days <7-90>` (打新: the dev buys its
+ * shares in the create itself). Each run builds the next tx, as every other multi-step command does (wrap / approve
+ * steps in between): run it, execute, run the same command again.
+ *
+ * Progress comes from the chain, not from what was executed: a plan file keeps the wallet, the name / symbol and the
+ * pad's token count before the create, and each run looks for a token this wallet created with that symbol since then
+ * (none yet → the create; found and the dev holds none → the V3 dev buy; holds some and no bond → the bond; else done).
+ * The plan is written only once the create preview succeeds, and a run that finds no token never builds a second
+ * create on its own (the first may still be landing): `--restart` does. The plan keeps the token once found (no rescan
+ * on later runs) and is marked done at the end: a done launch only reports, even if the dev's balance or the bond
+ * changed since (no second buy, bond or create) — for 7 days, then the plan expires.
+ * --buyback (V3, taxed): before the create, GangBuybackSplitterFactory clones the dev's splitter at
+ * predict(dev, salt), with a fresh salt per plan kept in it (so the address is known before the clone and never another
+ * launch's), the create names it as the recipient, and a bind step follows the create. A launch keeps the mode it began
+ * with: adding --buyback after the create (or dropping it before) is refused rather than starting over.
+ */
+
+const LAUNCH_DIR = process.env.GANG_LAUNCH_DIR || join(dirname(DIR), 'launch')
+const TTL_MS = 7 * 24 * 3600_000
+const PAD_ABI = parseAbi([
+  'function tokenCount() view returns (uint256)',
+  'function allTokens(uint256) view returns (address)',
+  'function kindOf(address token) view returns (uint8)',
+  'function curves(address token) view returns (address creator, address quote, uint128 realQuote, uint128 sold, uint128 gradAmt, uint128 virtualQuote, bool graduated, uint16 buyTaxBps, uint16 sellTaxBps, uint16 dividendBps, address pair, address refPair)',
+  'function sales(address token) view returns (address creator, uint64 progressAt, uint16 capShares, uint16 holdBps, address quote, uint16 sold, bool launched, uint16 mintFeeBps, uint16 exitFeeBps, address gate, uint128 sharePrice, address pair, address refPool, uint16 markSold)',
+])
+const ERC20_ABI = parseAbi(['function balanceOf(address) view returns (uint256)', 'function symbol() view returns (string)'])
+/** Flags only the chain reads; everything else goes to the step's own command. */
+export const LAUNCH_FLAGS = ['dev-buy', 'bond', 'bond-hold', 'bond-days', 'buyback', 'restart']
+const NOTE_FLAGS = ['note', 'conf', 'reveal-after']
+/** `gang fair create --dev-buy`, with or without --bond (index.js stops the lone flag, runLaunch the chained one). */
+export const FAIR_DEV_BUY = 'a 打新 dev buys its shares in the create itself: use --shares <n> (not --dev-buy)'
+
+/** The run asks for a chained launch (`kind` 'v3' | 'fair'). */
+export const isLaunch = (kind, flag) => flag('bond') || flag('buyback') || (kind === 'v3' && flag('dev-buy'))
+
+const planPath = (key) => join(LAUNCH_DIR, `${createHash('sha256').update(key).digest('hex').slice(0, 32)}.json`)
+
+function readPlan(key) {
+  try {
+    const p = JSON.parse(readFileSync(planPath(key), 'utf8'))
+    return p.createdAt > Date.now() - TTL_MS ? p : null
+  } catch { return null }
+}
+
+function writePlan(key, plan) {
+  mkdirSync(LAUNCH_DIR, { recursive: true, mode: 0o700 })
+  for (const name of readdirSync(LAUNCH_DIR)) {
+    const f = join(LAUNCH_DIR, name)
+    try { if (Date.now() - statSync(f).mtimeMs > TTL_MS) unlinkSync(f) } catch { /* gone */ }
+  }
+  const p = planPath(key)
+  writeFileSync(`${p}.${process.pid}.tmp`, JSON.stringify({ ...plan, createdAt: Date.now() }), { mode: 0o600 })
+  renameSync(`${p}.${process.pid}.tmp`, p)
+}
+
+/** An argv reader over `base` (the real one) with `over` replacing / adding flags; a value of undefined drops one. */
+function argsWith(base, over, drop = []) {
+  const has = (n) => (n in over ? over[n] !== undefined : !drop.includes(n) && base.flag(n))
+  return {
+    flag: has,
+    opt: (n, def) => (n in over ? (over[n] === undefined ? def : String(over[n])) : drop.includes(n) ? def : base.opt(n, def)),
+  }
+}
+
+/**
+ * Entry. `kind` 'v3' | 'fair'. deps: { io (index.js PAD_IO: opt, flag, out, fail, …), runV3, runFair, runBond, padNotes }.
+ */
+export async function runLaunch(kind, { io, runV3, runFair, runBond, padNotes }) {
+  const { opt, flag, out, fail } = io
+  const testnet = flag('testnet')
+  const net = padNets(kind)[testnet ? 'testnet' : 'mainnet']
+  if (!net.pad) return fail(NOT_ON_MAINNET)
+  const name = opt('name'), symbol = opt('symbol')
+  if (!name || !symbol) fail('--name and --symbol are required')
+  if (flag('follow')) fail('--follow does not apply to a launch')
+  if (kind === 'fair' && flag('dev-buy')) fail(FAIR_DEV_BUY)
+  if (kind === 'fair' && flag('buyback')) fail('--buyback is for V3 tokens: it makes the tax recipient a buy-back splitter, and a 打新 token has no recipient')
+
+  // everything checked before the create, so a launch never stops half way on a bad flag
+  const devBuy = kind === 'v3' && flag('dev-buy') ? parseAmount(fail, 'dev-buy', opt('dev-buy')) : null
+  const bonding = flag('bond')
+  if (!bonding && (flag('bond-hold') || flag('bond-days'))) fail('--bond-hold / --bond-days go with --bond <quote>')
+  let bond = null
+  if (bonding) {
+    if (flag('cover')) fail('--cover needs the PancakeSwap pair: a launch bonds before it, so give --bond <quote>')
+    if (kind === 'v3' && !devBuy) fail('a V3 launch with --bond needs --dev-buy <quote>: the creator holds nothing until it buys on the curve')
+    if (!bondAddress(testnet)) fail(`GangBond is not deployed on ${testnet ? 'the BSC testnet' : 'BSC mainnet'} in this CLI version: drop --bond (and --bond-hold / --bond-days), or add --testnet`)
+    const hold = String(opt('bond-hold', 'all')).trim()
+    if (!(hold === 'all' || /^(\d+(\.\d*)?|\.\d+)%?$/.test(hold)) || /^0*(\.0*)?%?$/.test(hold)) {
+      fail('--bond-hold must be all (everything the dev holds), a token amount, or N% of the supply', { got: opt('bond-hold') })
+    }
+    bond = { amount: parseAmount(fail, 'bond', opt('bond')), hold, days: parseIntIn(fail, 'bond-days', opt('bond-days'), 7, 90) }
+  }
+
+  // --buyback: a taxed V3 token whose recipient (the part left after holders) is the dev's splitter
+  let buyback = null
+  if (flag('buyback')) {
+    const zero = (f) => /^0+(\.0+)?$/.test(opt(f) ?? '')
+    if (!flag('buy-tax') || !flag('sell-tax') || (zero('buy-tax') && zero('sell-tax'))) {
+      fail('--buyback needs a taxed token: add --buy-tax and --sell-tax (each 1–5, in %); the buy-back is paid from the tax')
+    }
+    if (flag('recipient')) fail('--buyback makes the recipient your buy-back splitter: leave --recipient out')
+    if (/^0*100(\.0+)?$/.test(opt('dividend', '0'))) fail('--dividend 100 leaves nothing for the recipient, so nothing to buy back: lower it or drop --buyback')
+    const factory = splitterFactoryAddress(testnet)
+    if (!factory) fail(notDeployed(testnet))
+    buyback = { bps: buybackBpsOf(fail, opt('buyback')), factory }
+  }
+
+  const client = createPublicClient({ chain: net.chain, transport: http(net.rpc) })
+  const read = (address, abi, functionName, args = []) => client.readContract({ address, abi, functionName, args })
+  const me = walletFor({ chainId: net.chainId }, opt('from'))
+  const key = [net.chainId, net.pad, me.toLowerCase(), kind, name, symbol].join('|')
+  const steps = [...(buyback ? ['buyback-splitter'] : []), kind === 'v3' ? 'create' : 'create (dev shares included)', ...(buyback ? ['bind'] : []),
+    ...(devBuy ? ['dev-buy'] : []), ...(bond ? ['bond'] : [])]
+  const rerun = 're-run this same command after executing it'
+  const tag = (stage, extra = {}) => ({ launch: { stage, steps, ...extra } })
+  const withTag = (stage, extra) => (o) => out({ ...o, ...tag(stage, extra) })
+
+  let plan = flag('restart') ? null : readPlan(key)
+  const base = { kind, name, symbol, me, chainId: net.chainId, pad: net.pad }
+
+  // ---- a launch keeps the mode it began with (the create, once built, is never redone by a changed flag)
+  const created = plan?.startCount !== undefined
+  if (buyback && created && !plan.splitter) {
+    return fail('this launch was created without --buyback (its recipient is fixed): run it again without --buyback, or add --restart for a new token')
+  }
+  if (!buyback && !created && plan?.salt) {
+    return fail('this launch began with --buyback (its splitter is cloned or on the way): run it again with --buyback, or add --restart without it')
+  }
+
+  // ---- buy-back splitter: cloned for the dev before the create, at predict(dev, plan.salt)
+  if (buyback && !created) {
+    if (!plan?.salt) {
+      const salt = `0x${randomBytes(32).toString('hex')}`
+      const at = await read(buyback.factory, FACTORY_ABI, 'predict', [me, salt])
+      const sim = await simulateCall(client, me, buyback.factory, FACTORY_ABI, 'create', [buyback.bps, salt])
+      if (sim.failed) return out({ success: false, step: 'buyback-splitter', ...tag('buyback-splitter'), ...sim.failed })
+      writePlan(key, { ...base, salt, splitter: at, factory: buyback.factory })
+      const data = encodeFunctionData({ abi: FACTORY_ABI, functionName: 'create', args: [buyback.bps, salt] })
+      return out({
+        ...step({ chainId: net.chainId }, { from: me, to: buyback.factory, data }, {
+          step: 'buyback-splitter', chainId: Number(net.chainId), factory: buyback.factory, buybackPct: buyback.bps / 100,
+          splitter: at,
+          note: `clones your buy-back splitter (listed as a tax recipient in the same tx): ${buyback.bps / 100}% of the recipient's part is bought back and burned, the rest goes to you. A raise applies at once later, a cut only after a 3-day notice`,
+        }, flag('calldata'), io.summarize),
+        ...tag('buyback-splitter', { splitter: at, next: `${rerun}: it then builds the create with the splitter as the recipient` }),
+      })
+    }
+    if ((await client.getCode({ address: plan.splitter }) ?? '0x') === '0x') {
+      return out({
+        success: false, ...tag('buyback-splitter', { splitter: plan.splitter }), error: 'the buy-back splitter is not on chain yet',
+        hint: `if the clone was executed, wait for it to land and ${rerun.replace(' after executing it', '')}; if it was not, add --restart to build it again`,
+      })
+    }
+    const s = await splitterOf(read, plan.splitter)
+    if (!s || s.dev.toLowerCase() !== me.toLowerCase() || s.token) {
+      return fail('the splitter at this launch\'s address is not an unbound buy-back splitter of this wallet: add --restart', { splitter: plan.splitter })
+    }
+    if (s.buybackBps !== buyback.bps) {
+      return fail(`this launch's splitter buys back ${s.buybackPct}%, not ${buyback.bps / 100}%: run it again with --buyback ${s.buybackPct}, or add --restart for a new splitter (gang buyback set changes it after the create)`, { splitter: plan.splitter })
+    }
+  }
+
+  // ---- create
+  if (!created) {
+    const startCount = (await read(net.pad, PAD_ABI, 'tokenCount')).toString()
+    const createIo = {
+      ...io,
+      ...argsWith(io, plan?.splitter ? { recipient: plan.splitter } : {}, LAUNCH_FLAGS),
+      out: (o) => {
+        // the plan starts with the create tx itself: a wrap / approve step before it (or a failed preview) leaves none,
+        // so the next run builds the create again
+        const built = o.success && o.step === 'create'
+        if (built) writePlan(key, { ...base, ...(plan?.splitter && { salt: plan.salt, splitter: plan.splitter, factory: plan.factory }), startCount })
+        const after = steps[steps.indexOf(kind === 'v3' ? 'create' : 'create (dev shares included)') + 1]
+        return out({
+          ...o,
+          ...tag('create', built ? { next: `${rerun}: it finds the new token and continues with ${after ?? 'nothing'}` } : o.success ? { next: `${rerun}: it then builds the create` } : {}),
+        })
+      },
+    }
+    if (kind === 'v3') return runV3('create', { ...createIo, notes: padNotes('v3', 'create') })
+    return runFair('create', { ...createIo, notes: padNotes('fair', 'create') })
+  }
+
+  // ---- the token this plan created: kept in the plan once found, else looked up from the pad's list since the plan
+  let token = plan.token ?? null
+  if (!token) {
+    const count = Number(await read(net.pad, PAD_ABI, 'tokenCount'))
+    for (let i = Number(plan.startCount); i < count && !token; i++) {
+      const t = await read(net.pad, PAD_ABI, 'allTokens', [BigInt(i)])
+      const k = Number(await read(net.pad, PAD_ABI, 'kindOf', [t]))
+      const creator = k === 1 ? (await read(net.pad, PAD_ABI, 'curves', [t]))[0] : k === 2 ? (await read(net.pad, PAD_ABI, 'sales', [t]))[0] : zeroAddress
+      if (creator.toLowerCase() !== me.toLowerCase()) continue
+      if ((await read(t, ERC20_ABI, 'symbol')) === symbol) token = t
+    }
+    if (token) {
+      plan = { ...plan, token }
+      writePlan(key, plan)
+    }
+  }
+  if (!token) {
+    return out({
+      success: false, ...tag('create'), error: 'no token from this launch yet',
+      hint: `if the create was executed, wait for it to land and ${rerun.replace(' after executing it', '')}; if it was not (or its preview failed), add --restart to build the create again`,
+    })
+  }
+
+  // later steps carry no note (it went on the create) and take the token from the plan
+  const stepIo = (over) => ({ ...io, ...argsWith(io, { ...over, token }, [...LAUNCH_FLAGS, ...NOTE_FLAGS, 'name', 'symbol']) })
+  const bal = await read(token, ERC20_ABI, 'balanceOf', [me])
+  const buybackState = () => (plan.splitter ? splitterOf(read, plan.splitter) : null)
+
+  // ---- done: the report only, whatever happened to the balance or the bond since
+  const report = async () => {
+    const done = {
+      success: true, ...tag('done', { token, again: 'this launch is done; running the command again only reports it. Another token with the same name / symbol: add --restart' }),
+      token, name, symbol, devBalance: formatUnits(bal, 18), chainId: Number(net.chainId),
+    }
+    const bb = await buybackState()
+    if (bb) done.buyback = bb
+    if (!bond) return out({ ...done, note: `launched: gang ${kind} info --token ${token}${testnet ? ' --testnet' : ''}` })
+    return runBond('status', { ...stepIo({}), out: (o) => out({ ...done, bondStatus: o, note: `launched and bonded: gang bond status --token ${token}${testnet ? ' --testnet' : ''}` }) })
+  }
+  if (plan.done) return report()
+
+  // ---- bind the splitter to the token (anyone may; the launch does it right after the create)
+  if (plan.splitter) {
+    const bound = await read(plan.splitter, SPLITTER_ABI, 'token')
+    if (bound === zeroAddress) {
+      const sim = await simulateCall(client, me, plan.splitter, SPLITTER_ABI, 'bind', [token])
+      if (sim.failed) return out({ success: false, step: 'bind', ...tag('bind', { token }), ...sim.failed })
+      const data = encodeFunctionData({ abi: SPLITTER_ABI, functionName: 'bind', args: [token] })
+      return out({
+        ...step({ chainId: net.chainId }, { from: me, to: plan.splitter, data }, {
+          step: 'bind', chainId: Number(net.chainId), token, splitter: plan.splitter,
+          note: 'ties the splitter to this token for good (what it buys back and burns)',
+        }, flag('calldata'), io.summarize),
+        ...tag('bind', { token, next: `${rerun}${devBuy ? ': it continues with the dev buy' : bond ? ': it continues with the bond' : ': the launch is then done'}` }),
+      })
+    }
+    if (bound.toLowerCase() !== token.toLowerCase()) {
+      return out({ success: false, ...tag('bind', { token }), error: 'the splitter is bound to another token', splitter: plan.splitter, boundTo: bound })
+    }
+  }
+
+  // ---- V3 dev buy (a 打新 dev already holds its shares' tokens)
+  if (devBuy && bal === 0n) {
+    return runV3('buy', {
+      ...stepIo({ amount: devBuy }), out: withTag('dev-buy', { token, next: `${rerun}${bond ? ': it continues with the bond' : ': the launch is then done'}` }),
+      notes: padNotes('v3', 'buy', { note: null }),
+    })
+  }
+
+  // ---- bond
+  if (bond) {
+    const b = await read(bondAddress(testnet), BOND_ABI, 'bondOf', [token])
+    if (Number(b.round) === 0) {
+      const hold = bond.hold === 'all' ? formatUnits(bal, 18) : bond.hold
+      return runBond('post', {
+        ...stepIo({ amount: bond.amount, hold, days: bond.days, cover: undefined }),
+        out: withTag('bond', { token, next: `${rerun}: it reports the launch` }),
+      })
+    }
+  }
+
+  // ---- every step done: mark the plan, so later runs only report (never a second buy, bond or create)
+  writePlan(key, { ...plan, done: true })
+  return report()
+}