@gangfun/cli 0.13.0 → 0.15.0

package/README.md

@@ -87,8 +87,8 @@ gang bond burn --token <addr> | gang bond tx --hash <0x..>       # push one buy-
 #   A creator's gang sell (curve or pool) / gang withdraw below X is refused unless --break-bond (past T: --settle-first)
 # Launch in one command: one tx per run — execute it, 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 → dev buy → bond
-gang create … --buy-tax 3 --sell-tax 3 --buyback 50 [--dev-buy …]  # V3: the recipient's part of the tax 50% bought back + burned, the rest to you
-gang buyback status|set|apply --token 0x… [--pct 0-100]           # the buy-back splitter: ratio (raise now, cut after 3 days), what waits
+gang create … --buy-tax 3 --sell-tax 3 --buyback 50 [--buyback-to 0x…] [--dev-buy …]  # V3: the recipient's part of the tax 50% bought back + burned, the rest to you (or --buyback-to)
+gang buyback status|set|set-payee|apply --token 0x… [--pct 0-100] [--to 0x…]  # the buy-back splitter: ratio (raise now, cut after 3 days), payee (at once), what waits
 gang create --fair … [--shares <n>] --bond <quote> [--bond-hold …] --bond-days <7-90>                 # 打新: create (dev shares) → bond
 gang execute --request-id <id>
 gang tx --hash <0x..> [--testnet]            # V2 / Soft and GangLaunchpad events (GangLaunchpad: units "raw", amounts in wei)
@@ -227,4 +227,4 @@ gang agents --window 30d --sort follow
 
 ## Version
 
-`0.13.0` · repo [gangfun/cli](https://github.com/gangfun/cli) · published to [npm](https://www.npmjs.com/package/@gangfun/cli) on push to `main`
+`0.15.0` · repo [gangfun/cli](https://github.com/gangfun/cli) · published to [npm](https://www.npmjs.com/package/@gangfun/cli) on push to `main`

package/README.zh-CN.md

@@ -77,8 +77,8 @@ gang bond burn --token <addr> | gang bond tx --hash <0x..>       # 推进一块
 #   创建者用 gang sell（内盘或外盘）/ gang withdraw 卖到低于 X 会被拒，除非加 --break-bond（过了 T：--settle-first 先取回）
 # 一条命令发射：每次运行产出一笔交易，执行后再运行同一条命令，直到 launch.stage = done
 gang create … --dev-buy <报价币数量> [--bond <数量> [--bond-hold <枚数|N%|all>] --bond-days <7-90>]  # V3：发币 → dev 内盘买入 → 押金
-gang create … --buy-tax 3 --sell-tax 3 --buyback 50 [--dev-buy …]  # V3：接收地址那份税 50% 回购销毁，其余给你
-gang buyback status|set|apply --token 0x… [--pct 0-100]           # 回购合约：比例（提高立即生效，下调 3 天后）、待回购金额
+gang create … --buy-tax 3 --sell-tax 3 --buyback 50 [--buyback-to 0x…] [--dev-buy …]  # V3：接收地址那份税 50% 回购销毁，其余给你（或 --buyback-to 指定的地址）
+gang buyback status|set|set-payee|apply --token 0x… [--pct 0-100] [--to 0x…]  # 回购合约：比例（提高立即生效，下调 3 天后）、收款地址（立即生效）、待回购金额
 gang create --fair … [--shares <n>] --bond <数量> [--bond-hold …] --bond-days <7-90>                    # 打新：发币（含 dev 份额）→ 押金
 gang execute --request-id <id>
 gang tx --hash <0x..> [--testnet]            # 解析 V2 / Soft 和 GangLaunchpad 的事件（GangLaunchpad 的带 units "raw"，金额是 wei）
@@ -200,4 +200,4 @@ gang agents --window 30d --sort follow
 
 ## 版本
 
-`0.13.0` · [gangfun/cli](https://github.com/gangfun/cli) · push 到 `main` 自动发布到 [npm](https://www.npmjs.com/package/@gangfun/cli)
+`0.15.0` · [gangfun/cli](https://github.com/gangfun/cli) · push 到 `main` 自动发布到 [npm](https://www.npmjs.com/package/@gangfun/cli)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gangfun/cli",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Gang launchpad CLI for Binance Agentic Wallet agents: create on GangLaunchpad (untaxed or tax tokens), 打新 fair mint, PancakeSwap pool trades, LaunchpadV2 and legacy Soft/U/S trade.",
   "type": "module",
   "bin": {

package/src/bond.js

@@ -15,11 +15,12 @@ import { bawAddress } from './baw.js'
  * Env: GANG_BOND (mainnet), GANG_TESTNET_BOND (testnet) override the addresses below.
  */
 
-// script/DeployGangBond.s.sol. Testnet: 2026-10-28, block 139374309, over the set-10 pad — bonds from create on, refunds
-// asked for by the creator with a 3-day notice (earlier testnet versions: 0x587f…5d7E after the pair only, 0x5a99…d716
-// without the notice; docs/TESTNET-GANG-BOND-2026-10-28.md). Mainnet: not deployed yet (GANG_BOND overrides either)
+// script/DeployGangBond.s.sol. Testnet: 2026-10-29, block 139463214, over the set-10 pad — the audited version (two-step
+// settle, one buy-back chunk per 4 minutes; earlier testnet versions: 0x587f…5d7E after the pair only, 0x5a99…d716
+// without the refund notice, 0xB034…EBE3 before the audit; docs/TESTNET-GANG-BOND-2026-10-28.md). Mainnet: not deployed
+// yet (GANG_BOND overrides either)
 export const MAINNET_BOND = null
-export const TESTNET_BOND = '0xB034cFeb81Cbd29EE3d0CD6a0885766B6F10EBE3'
+export const TESTNET_BOND = '0xd6a8dd5d1E6641a34A255f25Db2B3ED397CB1086'
 
 export const BOND_ABI = parseAbi([
   'function post(address token, uint256 amount, uint256 holdAmount, uint64 duration) payable',
@@ -28,11 +29,12 @@ export const BOND_ABI = parseAbi([
   'function extend(address token, uint64 by)',
   'function start(address token)',
   'function report(address token)',
+  'function requestSettle(address token)',
   'function settle(address token)',
   'function requestRefund(address token)',
   'function refund(address token)',
   'function burnChunk(address token, uint256 minTokensOut) returns (uint256 quoteIn, uint256 burned)',
-  'function bondOf(address token) view returns ((address creator, uint64 postedAt, uint32 round, address quote, uint8 state, uint64 deadline, uint64 duration, uint64 refundAt, uint128 amount, uint128 holdAmount, uint128 burnLeft))',
+  'function bondOf(address token) view returns ((address creator, uint64 postedAt, uint32 round, address quote, uint8 state, uint64 deadline, uint64 duration, uint64 requestAt, uint128 amount, uint128 holdAmount, uint128 burnLeft))',
   'function isViolated(address token) view returns (bool)',
   'function isLive(address token) view returns (bool)',
   'function dumpValue(address token) view returns (uint256)',
@@ -42,12 +44,14 @@ export const BOND_ABI = parseAbi([
   'function previewBurn(address token) view returns (bool ready, uint256 quoteIn, uint256 tokensOut)',
   'function MIN_DURATION() view returns (uint64)', 'function MAX_DURATION() view returns (uint64)',
   'function REPORTER_BPS() view returns (uint256)', 'function MAX_WAIT() view returns (uint64)', 'function REFUND_NOTICE() view returns (uint64)',
+  'function SETTLE_DELAY() view returns (uint64)', 'function CHUNK_GAP() view returns (uint64)',
   'event BondPosted(address indexed token, address indexed creator, uint32 round, address quote, uint256 amount, uint256 holdAmount, uint64 duration, uint64 deadline)',
   'event BondStarted(address indexed token, uint32 round, uint64 deadline)',
   'event BondToppedUp(address indexed token, uint32 round, uint256 added, uint256 amount)',
   'event HoldRaised(address indexed token, uint32 round, uint256 holdAmount)',
   'event BondExtended(address indexed token, uint32 round, uint64 duration, uint64 deadline)',
   'event BondReported(address indexed token, uint32 round, address indexed reporter, uint256 balance, uint256 reward, uint256 burnLeft)',
+  'event SettleRequested(address indexed token, uint32 round, uint64 settleAt)',
   'event BondSettled(address indexed token, uint32 round, address indexed creator, uint256 amount)',
   'event RefundRequested(address indexed token, uint32 round, uint64 refundAt)',
   'event BondRefunded(address indexed token, uint32 round, address indexed creator, uint256 amount)',
@@ -55,7 +59,8 @@ export const BOND_ABI = parseAbi([
   'error ZeroAddress()', 'error UnknownToken()', 'error NotTradable()', 'error NotCreator()', 'error BondLive()',
   'error NotActive()', 'error ZeroAmount()', 'error BadDuration()', 'error BadHold()', 'error BadValue()',
   'error FeeOnTransferQuote()', 'error NotViolated()', 'error Violated()', 'error NotDue()', 'error NothingToBurn()',
-  'error BurnedThisBlock()', 'error Slippage()', 'error FlashSwapActive()', 'error AlreadyLive()', 'error AlreadyRequested()', 'error NoRefundRequest()',
+  'error BurnTooSoon()', 'error Slippage()', 'error FlashSwapActive()', 'error AlreadyLive()', 'error AlreadyRequested()', 'error NoRefundRequest()',
+  'error NoSettleRequest()',
   'error SafeCastOverflowedUintDowncast(uint8 bits, uint256 value)', 'error SafeERC20FailedOperation(address token)',
 ])
 
@@ -78,19 +83,21 @@ const HINTS = {
   FeeOnTransferQuote: 'the quote takes a fee on transfer: it cannot be used for a bond',
   NotViolated: 'the creator still holds at least X: nothing to report',
   Violated: 'the creator holds less than X: the bond cannot be settled or refunded, only reported',
+  NoSettleRequest: 'ask to settle first (gang bond settle asks; it runs 1 hour later)',
   AlreadyLive: 'the token reached its pair: the bond runs (gang bond start) instead of being refunded',
-  AlreadyRequested: 'a refund is already requested: it can run once its 3-day notice is over',
+  AlreadyRequested: 'already requested: a refund runs once its 3-day notice is over, a settle 1 hour after its request',
   NoRefundRequest: 'request the refund first (gang bond refund asks for it; it runs 3 days later)',
-  NotDue: 'the deadline has not passed yet',
+  NotDue: 'not due yet: the deadline, the refund notice or the 1-hour settle wait has not passed',
   NothingToBurn: 'no slashed bond with buy-back left on this token',
-  BurnedThisBlock: 'a chunk was already bought for this token in this block: try the next block',
+  BurnTooSoon: 'a chunk was bought for this token less than 4 minutes ago: one chunk per 4 minutes',
   Slippage: 'the buy-back would burn fewer tokens than the minimum: the price moved, re-run',
-  FlashSwapActive: 'the token\'s pair is mid flash swap: settle cannot count tokens borrowed from it; send settle in its own tx',
+  FlashSwapActive: 'the token\'s pair is mid flash swap: settle cannot count tokens borrowed from it; send it in its own tx',
 }
 
 const STATES = ['none', 'active', 'slashed', 'settled', 'refunded']
 const MAX_WAIT = 30 * 86_400 // GangBond.MAX_WAIT
 const REFUND_NOTICE = 3 * 86_400 // GangBond.REFUND_NOTICE
+const SETTLE_DELAY = 3_600 // GangBond.SETTLE_DELAY
 const BPS = 10_000n
 const TOTAL_SUPPLY = 1_000_000_000n * 10n ** 18n
 const DAY = 86_400
@@ -194,12 +201,12 @@ async function bondView(ctx, token, m) {
         ...(m.live
           ? { note: `the token is on its pair: anyone can start the clock (gang bond start --token ${token}); any other bond write starts it too` }
           : { refundRequestFrom: new Date(refundAt * 1000).toISOString(), coverageNote: 'no coverage before the pair: shown once it trades on PancakeSwap' }),
-        ...(b.refundAt !== 0n && !m.live && {
-          refundRequested: true, refundRunsAt: new Date(Number(b.refundAt) * 1000).toISOString(),
+        ...(b.requestAt !== 0n && !m.live && {
+          refundRequested: true, refundRunsAt: new Date(Number(b.requestAt) * 1000).toISOString(),
           refundNote: 'the creator asked for the bond back: it can be withdrawn from refundRunsAt if the token still has no pair; the promise binds until then, and graduation / launch cancels the request',
         }),
         ...violatedNote,
-        ...(!violated && !m.live && raw.now >= refundAt && b.refundAt === 0n && { note: `no pair within 30 days of the post and X is held: the creator can ask for the bond back (gang bond refund --token ${token}); it runs 3 days later` }),
+        ...(!violated && !m.live && raw.now >= refundAt && b.requestAt === 0n && { note: `no pair within 30 days of the post and X is held: the creator can ask for the bond back (gang bond refund --token ${token}); it runs 3 days later` }),
       })
       return { ...v, _raw: raw }
     }
@@ -208,12 +215,20 @@ async function bondView(ctx, token, m) {
       ctx.read(ctx.bond, BOND_ABI, 'coverageBps', [token]),
     ])
     const left = Number(b.deadline) - now
+    const settleAt = Number(b.requestAt)
     Object.assign(v, {
       phase: 'running', violated, dumpValue: q(dump), coveragePct: cov === MAX_UINT ? null : pctOfBps(cov), tier: tierOf(cov), tierNote: TIER_NOTE[tierOf(cov)],
       toFullCover: dump > b.amount ? q(dump - b.amount) : '0',
       ...(left > 0 ? { secondsLeft: left, daysLeft: Math.round((left / DAY) * 10) / 10 } : { pastDeadline: true }),
       ...violatedNote,
-      ...(!violated && left <= 0 && { note: `past the deadline and X is held: anyone can settle it (gang bond settle --token ${token}); the bond goes back to the creator. Until then it can still be reported if the balance drops below X` }),
+      ...(settleAt !== 0 && { settleRequested: true, settleRunsAt: new Date(settleAt * 1000).toISOString() }),
+      ...(!violated && left <= 0 && {
+        note: settleAt === 0
+          ? `past the deadline and X is held: anyone can settle it in two steps (gang bond settle --token ${token} asks; run it again 1 hour later and the bond goes back to the creator). X must still be held then; until then it can be reported if the balance drops below X`
+          : now < settleAt
+            ? `settle asked for: it runs from settleRunsAt if X is still held then; until then it can be reported if the balance drops below X`
+            : `settle is due: gang bond settle --token ${token} returns the bond to the creator (X must still be held)`,
+      }),
     })
     Object.assign(raw, { dump, cov })
   }
@@ -227,7 +242,7 @@ async function bondView(ctx, token, m) {
           ? 'slashed before the pair and still no pair 30 days after the post: gang bond burn --token … sends the rest to 0xdead as quote'
           : `slashed before the pair: the buy-back starts once the token ${m.kind === 'v3' ? 'graduates' : 'launches'}; if it has not by ${new Date((Number(b.postedAt) + MAX_WAIT) * 1000).toISOString()}, the rest goes to 0xdead as quote`,
       }),
-      ...(b.burnLeft > 0n && m.live && { nextChunk: ready ? { quoteIn: q(quoteIn), tokensOut: tokens(tokensOut) } : null, nextChunkNote: ready ? 'gang bond burn --token … buys this chunk now' : 'not ready: the first call after a slash records a price observation, then the buy-back waits 10 minutes and skips while the price is more than 2% above its average (after 20 minutes without a call it starts over)' }),
+      ...(b.burnLeft > 0n && m.live && { nextChunk: ready ? { quoteIn: q(quoteIn), tokensOut: tokens(tokensOut) } : null, nextChunkNote: ready ? 'gang bond burn --token … buys this chunk now' : 'not ready: the first call after a slash records a price observation, then the buy-back waits 10 minutes and skips while the price is more than 2% above its average (after 20 minutes without a call it starts over); at most one chunk per 4 minutes' }),
     })
   }
   return { ...v, _raw: raw }
@@ -350,7 +365,7 @@ export async function runBond(sub, { opt, flag, out, fail, summarize }) {
     if (!same(me(), b.creator)) return fail('only the creator can ask for its bond back', { wallet: me(), creator: b.creator })
     if (!raw.pending || m.live) return fail(HINTS.AlreadyLive, { deadline: view.deadline })
     if (view.violated) return fail(HINTS.Violated, { creatorBalance: view.creatorBalance, holdTokens: view.holdTokens })
-    if (b.refundAt === 0n) {
+    if (b.requestAt === 0n) {
       const requestAt = Number(b.postedAt) + MAX_WAIT
       if (raw.now < requestAt) return fail('a refund can be asked for only 30 days after the post without a pair', { refundRequestFrom: view.refundRequestFrom, secondsLeft: requestAt - raw.now })
       const sim = await simulate(ctx, me(), 'requestRefund', [token])
@@ -360,7 +375,7 @@ export async function runBond(sub, { opt, flag, out, fail, summarize }) {
         note: 'step 1 of 2: starts a 3-day notice (shown on gang.fun). Keep holding X: a breach can still be reported, and if the token graduates / launches meanwhile the request is void and the clock starts. Then run gang bond refund again',
       }))
     }
-    if (raw.now < Number(b.refundAt)) return fail('the refund notice is not over yet', { refundRunsAt: view.refundRunsAt, secondsLeft: Number(b.refundAt) - raw.now })
+    if (raw.now < Number(b.requestAt)) return fail('the refund notice is not over yet', { refundRunsAt: view.refundRunsAt, secondsLeft: Number(b.requestAt) - raw.now })
     const sim = await simulate(ctx, me(), 'refund', [token])
     if (sim.failed) return out({ success: false, step: 'refund', ...sim.failed })
     return out(send('refund', [token], { step: 'refund', refund: view.bond, quote: view.quote, note: 'step 2 of 2: no pair after the notice, X held: the bond comes back to you (not counted as honored)' }))
@@ -375,9 +390,19 @@ export async function runBond(sub, { opt, flag, out, fail, summarize }) {
     }
     if (raw.now < Number(b.deadline)) return fail(HINTS.NotDue, { deadline: view.deadline, secondsLeft: Number(b.deadline) - raw.now })
     if (view.violated) return fail(HINTS.Violated, { creatorBalance: view.creatorBalance, holdTokens: view.holdTokens, hint: `gang bond report --token ${token}${net}` })
+    // two steps, anyone: ask (X held now), then settle 1 hour later (X held again) — so X can't be met for one tx only
+    if (b.requestAt === 0n) {
+      const sim = await simulate(ctx, me(), 'requestSettle', [token])
+      if (sim.failed) return out({ success: false, step: 'request-settle', ...sim.failed })
+      return out(send('requestSettle', [token], {
+        step: 'request-settle', creator: b.creator, bond: view.bond, quote: view.quote, settleRunsAbout: new Date((raw.now + SETTLE_DELAY) * 1000).toISOString(),
+        note: 'step 1 of 2: the bond can be settled 1 hour after this lands, if the creator still holds X then; until then a drop below X can be reported. Then run gang bond settle again',
+      }))
+    }
+    if (raw.now < Number(b.requestAt)) return fail('the settle wait is not over yet', { settleRunsAt: view.settleRunsAt, secondsLeft: Number(b.requestAt) - raw.now })
     const sim = await simulate(ctx, me(), 'settle', [token])
     if (sim.failed) return out({ success: false, step: 'settle', ...sim.failed })
-    return out(send('settle', [token], { step: 'settle', creator: b.creator, refund: view.bond, quote: view.quote, note: 'the bond goes back to the creator, whoever sends this' }))
+    return out(send('settle', [token], { step: 'settle', creator: b.creator, refund: view.bond, quote: view.quote, note: 'step 2 of 2: the bond goes back to the creator, whoever sends this' }))
   }
 
   if (sub === 'burn') {
@@ -394,7 +419,7 @@ export async function runBond(sub, { opt, flag, out, fail, summarize }) {
       step: 'burn', burnLeft: view.burnLeft, quote: view.quote,
       ...(toDead ? { quoteToDead: qf(quoteIn), note: 'slashed before the pair and still no pair 30 days after the post: the rest goes to 0xdead as quote' }
         : ready ? { chunkQuoteIn: qf(quoteIn), expectBurnTokens: tokens(tokensOut), minBurnTokens: tokens(minOut), slippagePct: slippage }
-        : { note: 'no chunk this time: the call records the price observation (first call after a slash) or waits for the 10-minute average / a price no more than 2% above it. It is cheap; the platform keeper also calls it every 10 minutes. If a chunk becomes buyable before it lands, it reverts (Slippage) rather than buy without a minimum: re-run then' }),
+        : { note: 'no chunk this time: the call records the price observation (first call after a slash) or waits for the 10-minute average / a price no more than 2% above it. It is cheap; the platform keeper also calls it every 5 minutes (one chunk per 4 minutes at most). If a chunk becomes buyable before it lands, it reverts (Slippage) rather than buy without a minimum: re-run then' }),
     }))
   }
 
@@ -515,7 +540,8 @@ export async function runBond(sub, { opt, flag, out, fail, summarize }) {
  * bond, not the creator), else one of:
  * - { refuse: {…} } — the sell would leave less than X before the deadline (no --break-bond), or after the deadline
  *   before settle (no --settle-first): print it as the failure;
- * - { settleStep: {…} } — --settle-first after the deadline: send this settle first, then re-run the sell;
+ * - { settleStep: {…} } — --settle-first after the deadline: send this step first (ask to settle, or settle once the
+ *   1-hour wait is over), then re-run the sell;
  * - { info: {…} } — go on, with these fields added to the preview (headroom after the sell, or the --break-bond warning).
  */
 export async function bondGuard(ctx, p, rawOnly, summarize) {
@@ -549,10 +575,18 @@ export async function bondGuard(ctx, p, rawOnly, summarize) {
   const net = p.testnet ? ' --testnet' : ''
   if (pastDeadline && bal >= b.holdAmount) {
     if (!p.settleFirst) {
-      return { refuse: { error: `the bond is past its deadline but not settled: this sell leaves ${tokens(after)} tokens, below X (${tokens(b.holdAmount)}), and anyone could report it before you settle`, ...base, hint: `run gang bond settle --token ${p.token}${net} first, or add --settle-first to this sell` } }
+      return { refuse: { error: `the bond is past its deadline but not settled: this sell leaves ${tokens(after)} tokens, below X (${tokens(b.holdAmount)}), and anyone could report it before you settle`, ...base, hint: `run gang bond settle --token ${p.token}${net} first (two steps, 1 hour apart), or add --settle-first to this sell` } }
+    }
+    const now = Number(block.timestamp)
+    if (b.requestAt !== 0n && now < Number(b.requestAt)) {
+      return { refuse: { error: 'settle is asked for but its 1-hour wait is not over: keep X until it runs, then settle and sell', ...base, settleRunsAt: new Date(Number(b.requestAt) * 1000).toISOString(), secondsLeft: Number(b.requestAt) - now } }
     }
-    const data = encodeFunctionData({ abi: BOND_ABI, functionName: 'settle', args: [p.token] })
-    return { settleStep: step(ctx, { from: p.me, to: addr, data }, { step: 'settle', chainId: Number(ctx.chainId), token: p.token, refund: base.bond, ...base, note: 'settle first (the bond comes back to you); after executing, re-run the same sell' }, rawOnly, summarize) }
+    const fn = b.requestAt === 0n ? 'requestSettle' : 'settle'
+    const data = encodeFunctionData({ abi: BOND_ABI, functionName: fn, args: [p.token] })
+    const note = fn === 'requestSettle'
+      ? 'ask to settle first (step 1 of 2): 1 hour after it lands, settle (the bond comes back to you) and then sell; keep X until then'
+      : 'settle first (the bond comes back to you); after executing, re-run the same sell'
+    return { settleStep: step(ctx, { from: p.me, to: addr, data }, { step: fn === 'requestSettle' ? 'request-settle' : 'settle', chainId: Number(ctx.chainId), token: p.token, refund: base.bond, ...base, note }, rawOnly, summarize) }
   }
   const lost = formatUnits(b.amount, dec)
   const consequence = `anyone can report it, the reporter takes 1% and the rest of the ${lost} bond buys back and burns the token`

package/src/buyback.js

@@ -4,9 +4,10 @@ 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
+ * `gang buyback …` and `gang create … --buyback <pct> [--buyback-to <addr>]` — 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's payee (the dev unless it names another address; v2 splitters only, `gang buyback set-payee`).
+ * GangBuybackSplitterFactory clones one per token for the dev (`create(bps, salt, payee)`, 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.
@@ -15,13 +16,15 @@ import { parseNum, revertOf as revertIn, step } from './steps.js'
  * 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'
+// BSC 56, factory v2 (payee; docs/MAINNET-BUYBACK-SPLITTER-2026-10-28.md). v1 was 0x6bcd…8546 (2-argument create)
+export const MAINNET_SPLITTER_FACTORY = '0x93467Cb38B9Cb7f6EF3b67d2226Eb8b77ca58F2f'
+export const TESTNET_SPLITTER_FACTORY = '0x08b9E2Cf5F666b55F262239b19e25de25b8ba87D'
+/** The factory's clones; v1 (mainnet's first factory, 0x6bcd…8546) pays the dev, v2 its payee. */
+export const BUYBACK_TYPE = 'buyback-burn-v2'
+const BUYBACK_TYPES = ['buyback-burn-v1', BUYBACK_TYPE]
 
 export const FACTORY_ABI = parseAbi([
-  'function create(uint16 buybackBps, bytes32 salt) returns (address splitter)',
+  'function create(uint16 buybackBps, bytes32 salt, address payee) returns (address splitter)',
   'function predict(address dev, bytes32 salt) view returns (address)',
   'function pad() view returns (address)',
   'error NotAgent()',
@@ -44,6 +47,8 @@ export const SPLITTER_ABI = parseAbi([
   'function setBuybackBps(uint16 newBps)',
   'function applyBuybackBps()',
   'function releaseDev() returns (uint256)',
+  'function payee() view returns (address)',
+  'function setPayee(address newPayee)',
   'error NotDev()',
   'error BadBps()',
   'error AlreadyBound()',
@@ -93,17 +98,22 @@ 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 moduleType = hexToString(type, { size: 32 }).replace(/\0+$/, '')
+  if (!BUYBACK_TYPES.includes(moduleType)) 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)))
+  // v1 has no payee: it pays the dev
+  const hasPayee = moduleType !== 'buyback-burn-v1'
+  const payee = hasPayee ? await read(addr, SPLITTER_ABI, 'payee') : dev
+  const toDev = payee.toLowerCase() === dev.toLowerCase()
   // 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),
+    splitter: addr, moduleType, dev, payee, payeeChangeable: hasPayee, 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`,
+    note: `${pct(bps)}% of each tax payment to this recipient is bought back in the pool and burned (0xdead), the rest goes to ${toDev ? 'the dev' : `the payee ${payee}`}; a raise applies at once, a cut only 3 days after it is asked for${hasPayee ? '; the dev can change the payee at once (gang buyback set-payee)' : ''}`,
   }
 }
 
@@ -125,8 +135,8 @@ export async function simulateCall(client, from, address, abi, functionName, arg
   }
 }
 
-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'
+const SUBS = ['status', 'set', 'set-payee', 'apply', 'bind', 'release']
+const USAGE = 'usage: gang buyback <status|set|set-payee|apply|bind|release> --token <addr> [--pct <0-100>] [--to <addr>] [--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 }) {
@@ -171,6 +181,18 @@ export async function runBuyback(sub, { opt, flag, out, fail, summarize }) {
         })
   }
 
+  if (sub === 'set-payee') {
+    if (!s.payeeChangeable) return fail('this splitter (buyback-burn-v1) has no payee: it pays the dev; only splitters from the current factory (v2) can name another address')
+    if (me().toLowerCase() !== s.dev.toLowerCase()) return fail('only the dev this splitter was made for can change its payee', { wallet: me(), dev: s.dev })
+    const to = opt('to')
+    if (!isAddress(to ?? '') || to === zeroAddress) fail('--to <0x…> required (checksummed or all lowercase): the address the dev\'s part goes to from now on', { got: to ?? null })
+    if (to.toLowerCase() === s.payee.toLowerCase()) return fail('that is the payee already', { payee: s.payee })
+    return send('setPayee', [to], {
+      step: 'set-payee', fromPayee: s.payee, toPayee: to,
+      note: 'applies at once (the dev\'s own share; holders are not affected). Quote that arrived before is split to the current payee first; what is owed goes to the new one',
+    })
+  }
+
   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 })
@@ -179,5 +201,5 @@ export async function runBuyback(sub, { opt, flag, out, fail, summarize }) {
 
   // 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' })
+  return send('releaseDev', [], { step: 'release', amount: s.devOwed, payee: s.payee, note: 'anyone may; the payee gets what a failed push left owed' })
 }

package/src/index.js

@@ -284,9 +284,10 @@ graduated tokens only).
   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 …]]
+  gang create … --buy-tax <1-5> --sell-tax <1-5> --buyback <0-100> [--buyback-to <addr>] [--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
+                                         pool and burned (0xdead), the rest to you (or --buyback-to <addr>; changeable later
+                                         with gang buyback set-payee). 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>
@@ -314,7 +315,8 @@ graduated tokens only).
                                          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.
+                                         past the deadline, --settle-first settles the bond before the sell (asks first;
+                                         settles 1 hour later).
 
 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]
@@ -334,25 +336,31 @@ BOND (押金承诺, GangBond; any GangLaunchpad token, from create on; GANG_BOND
   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 settle --token <addr>        anyone, after the deadline while X is held, two steps: run it once to ask, again
+                                         1 hour later (X still held) and 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
+                                         anyone: one buy-back chunk of a slashed bond (≤ 0.5% of the pair's quote side, one
+                                         per 4 minutes; 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)
+                                         back, the payee and what is owed to it, 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 set-payee --token <addr> --to <addr>
+                                         dev only: the part not bought back goes to --to from now on (at once; splitters
+                                         from the current factory; the first mainnet ones, buyback-burn-v1, pay the dev)
   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
+                                         anyone: bind the splitter to its token (the launch does it) / push the payee 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 /

package/src/launch.js

@@ -1,7 +1,7 @@
 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 { createPublicClient, http, parseAbi, formatUnits, encodeFunctionData, isAddress, zeroAddress } from 'viem'
 import { DIR } from './notes.js'
 import { padNets, NOT_ON_MAINNET } from './gangpad.js'
 import { bondAddress, BOND_ABI } from './bond.js'
@@ -26,6 +26,7 @@ import { buybackBpsOf, FACTORY_ABI, notDeployed, simulateCall, SPLITTER_ABI, spl
  * 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.
+ * --buyback-to <addr> names where the dev's part goes (default: the dev); the dev can change it later at once.
  */
 
 const LAUNCH_DIR = process.env.GANG_LAUNCH_DIR || join(dirname(DIR), 'launch')
@@ -39,7 +40,7 @@ const PAD_ABI = parseAbi([
 ])
 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']
+export const LAUNCH_FLAGS = ['dev-buy', 'bond', 'bond-hold', 'bond-days', 'buyback', 'buyback-to', '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)'
@@ -108,6 +109,7 @@ export async function runLaunch(kind, { io, runV3, runFair, runBond, padNotes })
 
   // --buyback: a taxed V3 token whose recipient (the part left after holders) is the dev's splitter
   let buyback = null
+  if (flag('buyback-to') && !flag('buyback')) fail('--buyback-to <addr> goes with --buyback <pct>: it names where the part not bought back goes')
   if (flag('buyback')) {
     const zero = (f) => /^0+(\.0+)?$/.test(opt(f) ?? '')
     if (!flag('buy-tax') || !flag('sell-tax') || (zero('buy-tax') && zero('sell-tax'))) {
@@ -117,7 +119,12 @@ export async function runLaunch(kind, { io, runV3, runFair, runBond, padNotes })
     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 }
+    let payee = null
+    if (flag('buyback-to')) {
+      payee = opt('buyback-to')
+      if (!isAddress(payee ?? '') || payee === zeroAddress) fail('--buyback-to must be a 0x address, checksummed or all lowercase (where the part not bought back goes; leave it out for your own wallet)', { got: payee ?? null })
+    }
+    buyback = { bps: buybackBpsOf(fail, opt('buyback')), factory, payee }
   }
 
   const client = createPublicClient({ chain: net.chain, transport: http(net.rpc) })
@@ -147,15 +154,16 @@ export async function runLaunch(kind, { io, runV3, runFair, runBond, padNotes })
     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])
+      const args = [buyback.bps, salt, buyback.payee ?? zeroAddress]
+      const sim = await simulateCall(client, me, buyback.factory, FACTORY_ABI, 'create', args)
       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] })
+      const data = encodeFunctionData({ abi: FACTORY_ABI, functionName: 'create', args })
       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`,
+          splitter: at, payee: buyback.payee ?? me,
+          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 ${buyback.payee ? `${buyback.payee} (--buyback-to)` : 'you'}. Later a raise applies at once, a cut only after a 3-day notice; the payee can be changed at once (gang buyback set-payee)`,
         }, flag('calldata'), io.summarize),
         ...tag('buyback-splitter', { splitter: at, next: `${rerun}: it then builds the create with the splitter as the recipient` }),
       })
@@ -173,6 +181,11 @@ export async function runLaunch(kind, { io, runV3, runFair, runBond, padNotes })
     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 })
     }
+    const wantPayee = (buyback.payee ?? me).toLowerCase()
+    if (s.payee.toLowerCase() !== wantPayee) {
+      const was = s.payee.toLowerCase() === me.toLowerCase() ? 'leave --buyback-to out' : `--buyback-to ${s.payee}`
+      return fail(`this launch's splitter pays ${s.payee}, not ${buyback.payee ?? me}: run it again with ${was}, or add --restart for a new splitter (gang buyback set-payee changes it after the create)`, { splitter: plan.splitter })
+    }
   }
 
   // ---- create