@gangfun/cli 0.20.0 → 0.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/index.js CHANGED
@@ -22,6 +22,7 @@ import { runBond } from './bond.js'
22
22
  import { runBuyback } from './buyback.js'
23
23
  import { runSplit, SPLIT_EVENT_ABIS } from './split.js'
24
24
  import { runLp, LP_EVENT_ABIS } from './lp.js'
25
+ import { runCombo, COMBO_EVENT_ABIS } from './combo.js'
25
26
  import { runFly, flyCtx, isFlyToken, FLY_EVENT_ABIS, FLY_CREATE_FLAGS } from './fly.js'
26
27
  import { FAIR_DEV_BUY, isLaunch, LAUNCH_FLAGS, runLaunch } from './launch.js'
27
28
  import { poolPayBnb, poolTrade } from './pool.js'
@@ -303,7 +304,8 @@ U / S pads) and run that kind's trade. Results of V3 / 打新 / 铸币飞轮 tok
303
304
  [--max-per-tx 1-10] [--hold 60-90] [--mint-fee 1-3] [--exit-fee 1-2] [--dev-cut 0-10] [--buy-pct 0-50]
304
305
  [--sell-tax 1-2] [--launch-delay 0-300] [--window 300-1800] [--cap-mul 1-2] [--post-mint | --no-post-mint]
305
306
  [--tier flat|standard|linear [--step-pct 0-10 --step-shares 100-100000 --max-mul 1-10]] [--supply-cap 10-500]
306
- [--dev-shares <n>] [--quote 0x… --ref-pool 0x…] [--logo …] [--website URL] [--twitter @handle] [--description …]
307
+ [--guard off|15|20|30] [--twap-window 15|30] [--dev-shares <n>] [--quote 0x… --ref-pool 0x…] [--logo …]
308
+ [--website URL] [--twitter @handle] [--description …]
307
309
  a 铸币飞轮 (Mint Flywheel, GangFlywheelPad) sale (mainnet; --testnet = BSC testnet
308
310
  set 2). 10,000 shares at raise / 10,000 each; a quota per wallet
309
311
  (--quota + --invite-bonus per wallet it invites), --max-per-tx per mint, Agent ID
@@ -351,9 +353,10 @@ U / S pads) and run that kind's trade. Results of V3 / 打新 / 铸币飞轮 tok
351
353
  nobody (not you, not the platform) can change the payees or shares later; a payee can
352
354
  only move its own slot (gang split set-payee). Steps: clone your split module
353
355
  (GangSplitModuleFactory; listed as a recipient in the same tx) → create with it as the
354
- recipient → bind → the rest of the launch. --split, --buyback, --lp and --recipient
355
- are exclusive. Quote: WBNB (default), GANG or one listed in the pad's QuoteRegistry
356
- only (the quotes the keeper splits; others are refused before the clone)
356
+ recipient → bind → the rest of the launch. Not with --recipient; with --buyback / --lp
357
+ it makes a combined recipient (below). Quote: WBNB (default), GANG or one listed in the
358
+ pad's QuoteRegistry only (the quotes the keeper splits; others are refused before the
359
+ clone)
357
360
  gang create … --buy-tax <1-5> --sell-tax <1-5> --lp <0-100> [--lp-to <addr>] [--dev-buy … [--bond …]]
358
361
  V3, taxed, auto-liquidity: --lp % of the recipient's part of the tax is added to the
359
362
  token's PancakeSwap pair as liquidity whose LP goes to 0xdead (locked for good), the
@@ -361,8 +364,23 @@ U / S pads) and run that kind's trade. Results of V3 / 打新 / 铸币飞轮 tok
361
364
  graduation the keeper adds it in chunks (half buys the token, all of it goes back in
362
365
  with the matching quote). Steps: clone your LP splitter (GangLiquiditySplitterFactory;
363
366
  listed as a recipient in the same tx) → create with it as the recipient → bind → the
364
- rest of the launch. Not with --buyback, --split or --recipient. Quote: WBNB
365
- (default), GANG or one listed in the pad's QuoteRegistry only
367
+ rest of the launch. Not with --recipient; with --buyback / --split it makes a combined
368
+ recipient (below). Quote: WBNB (default), GANG or one listed in the pad's QuoteRegistry
369
+ only
370
+ gang create … --buy-tax <1-5> --sell-tax <1-5> --buyback <0-100> --lp <0-100> [--split <addr>:<pct>[,…]] [--dev-buy …]
371
+ V3, taxed, combined recipient (GangComboSplitter, combo-v1): two or three of --buyback,
372
+ --lp, --split together. --buyback % of the recipient's part is bought back and burned,
373
+ --lp % added to the pair as liquidity (LP to 0xdead), the rest (100 − both) pushed to
374
+ the --split payees, whose shares are of that rest and add up to 100 (e.g. --buyback 30
375
+ --lp 30 --split self:70,0xKol…:30: 28% / 12% of the recipient's part); without --split
376
+ the rest goes to you. --buyback + --lp = 100 takes no --split; above 100 is refused.
377
+ --buyback-to / --lp-to don't apply (name payees with --split). PERMANENT: the ratios,
378
+ payees and shares can never change (unlike a lone --buyback / --lp, whose ratio the
379
+ dev can change); a payee can only move its own slot (gang combo set-payee). Any other
380
+ asset sent to it: its buy-back + LP share goes to 0xdead, the rest to the payees.
381
+ Steps: clone your combined recipient (GangComboSplitterFactory; listed in the same tx)
382
+ → create → bind → the rest of the launch. Quote: WBNB (default), GANG or one listed
383
+ in the pad's QuoteRegistry only
366
384
  gang create --fair … [--shares <n>] --bond <quote> [--bond-hold …] --bond-days <7-90>
367
385
  打新: create (the dev's --shares are bought in it) → bond. Progress is read from the
368
386
  chain (a token this wallet created with this symbol since the plan); a run that finds
@@ -474,12 +492,39 @@ LP (a V3 token whose recipient is an LP splitter, lp-burn-v1; GANG_LP_FACTORY /
474
492
  > 2% above it): minimum tokens = previewAdd less --slippage. Not ready: a call that
475
493
  only records the price. Gas: a chunk takes ~0.53–0.75M; the CLI never sets a gas
476
494
  limit, let the wallet estimate it. --testnet, --calldata, --from as in gang v3
495
+ COMBO (a V3 token whose recipient is a combined recipient, combo-v1; GANG_COMBO_FACTORY / GANG_TESTNET_COMBO_FACTORY):
496
+ gang combo status --token <addr> [--asset <addr>]
497
+ buy-back / LP / payees % (fixed for good), payees and shares, set aside for buy-back
498
+ (buybackLeft) and liquidity (lpLeft), not split yet (unsplit), what each slot is owed
499
+ (bound quote, WBNB, GANG, the token's quote, --asset), the next chunk (kind, ready or what it
500
+ waits for), the keeper (serves the quote or manual; due, and the planned action
501
+ decoded from previewWork: buy-back / liquidity / observe / split), next commands, and
502
+ a warning when the module is bound to another token than the one paying it
503
+ gang combo distribute --token <addr> [--asset <addr>|wbnb]
504
+ anyone, once bound: the bound quote (default) is split as the tax is; another asset's
505
+ buy-back + LP share goes to 0xdead, the rest to the payees
506
+ gang combo release --token <addr> [--asset <addr>] [--index <i>] [--max <amount>]
507
+ anyone: push a slot what a failed push left owed (--index = the contract's 0-based
508
+ slot, default your own slot or the only one owed)
509
+ gang combo set-payee --token <addr> --to <addr> [--index <i>]
510
+ only the slot's current payee (--index default: your wallet's slot): moves the slot
511
+ to --to at once, the share stays. Distributes other known assets waiting first (one
512
+ tx each, then re-run)
513
+ gang combo bind --token <addr> anyone: bind the module to its token (the launch does it)
514
+ gang combo chunk --token <addr> [--slippage 1]
515
+ anyone: one chunk now, as the keeper does (graduated tokens; one per 4 minutes for both
516
+ kinds; always the larger set-aside part): minimum tokens = previewChunk less --slippage
517
+ (default 1%). Not ready: a call that only records the price.
518
+ --module <addr> instead of --token names a module directly (not for bind). Gas: the
519
+ CLI never sets a gas limit; let the wallet estimate it (a chunk ~0.55–0.75M; each
520
+ payee push needs ~365k left before it, up to 10: a lower limit reverts PushStarved).
521
+ --testnet, --calldata, --from as in gang v3
477
522
  gang execute --request-id <id> broadcast a previewed call
478
523
  gang tx --pending a trade that waited for Binance App approval (execute: pendingConfirmation): find its tx
479
524
  in the wallet's history by the exact call previewed, then as gang tx --hash below
480
525
  gang tx --hash <0x..> [--testnet] wait for receipt and decode Gang events: V2 / Soft / U / S, GangLaunchpad (V3 /
481
- 打新, tax router, vaults), GangFlywheelPad (铸币飞轮 pad and tax handler), split modules
482
- and LP splitters (publishes a queued --note; mainnet). GangLaunchpad events
526
+ 打新, tax router, vaults), GangFlywheelPad (铸币飞轮 pad and tax handler), split modules,
527
+ LP splitters and combined recipients (publishes a queued --note; mainnet). GangLaunchpad events
483
528
  carry units: "raw" (amounts in wei, 18 decimals; bps / shares as is)
484
529
 
485
530
  --note is PUBLIC: shown on gang.fun next to the trade. Its hash goes into the tx calldata, so it is provably written
@@ -506,7 +551,10 @@ GANG_PAD / GANG_TESTNET_PAD (the one GangLaunchpad behind both gang v3 and gang
506
551
  and GANG_V3_TESTNET_PAD / GANG_FAIR_TESTNET_PAD still work as aliases), GANG_TESTNET_RPC_URL (aliases
507
552
  GANG_V3_TESTNET_RPC_URL / GANG_FAIR_TESTNET_RPC_URL), GANG_ROUTER / GANG_TESTNET_ROUTER (alias GANG_ROUTER_TESTNET; GangRouter
508
553
  for BNB buys / mints and every pool trade; both default to the built-in mainnet / testnet set 10 addresses),
509
- GANG_FLY_PAD / GANG_TESTNET_FLY_PAD (GangFlywheelPad; default: the built-in mainnet / testnet set 2 addresses)
554
+ GANG_FLY_PAD / GANG_TESTNET_FLY_PAD (GangFlywheelPad V1; default: the built-in mainnet / testnet set 2 addresses),
555
+ GANG_FLY_PAD_V2 / GANG_TESTNET_FLY_PAD_V2 (V2, where new tokens go; default: the built-in mainnet / testnet V2). --guard / --twap-window
556
+ (V2 only): the guard is off by default (post-launch minting does not pause on a price drop; the quota cap of 10 per
557
+ wallet bounds it); --guard 15|20|30 pauses mints while the pool is that % below its average over --twap-window (30)
510
558
 
511
559
  Private RPC: this CLI never broadcasts itself. Trades go out through the Agentic Wallet (gang execute), which picks its
512
560
  own RPC; a --calldata tx is sent by whatever signs it. To keep a large pool buy out of the public mempool (front-running),
@@ -1013,7 +1061,7 @@ const V3_CREATE_FLAGS = ['buy-tax', 'sell-tax', 'dividend', 'recipient']
1013
1061
  const FAIR_CREATE_FLAGS = ['raise', 'cap', 'hold', 'mint-fee', 'exit-fee', 'shares']
1014
1062
  // 铸币飞轮 settings beyond those it shares with 打新 (--raise / --hold / --mint-fee / --exit-fee) and V3 (--sell-tax)
1015
1063
  const FLY_ONLY_FLAGS = FLY_CREATE_FLAGS.filter((f) => !['raise', 'hold', 'mint-fee', 'exit-fee', 'sell-tax'].includes(f))
1016
- const FLY_NO_BOND = '铸币飞轮 tokens take no GangBond, buy-back splitter, split module, LP splitter or --dev-buy (phase 1): the creator mints its shares in the create with --dev-shares <n>'
1064
+ const FLY_NO_BOND = '铸币飞轮 tokens take no GangBond, buy-back splitter, split module, LP splitter, combined recipient or --dev-buy (phase 1): the creator mints its shares in the create with --dev-shares <n>'
1017
1065
  /** The flags a 铸币飞轮 create refuses (gang create --fly and gang fly create alike). */
1018
1066
  function checkFlyCreate() {
1019
1067
  if (flag('fair')) fail('give --fly (铸币飞轮) or --fair (打新), not both')
@@ -1047,11 +1095,11 @@ function create() {
1047
1095
  // commands whose JSON result carries `update`; `watch` streams NDJSON and help is plain text
1048
1096
  const UPDATE_CHECKED = new Set(['version', '--version', '-v', 'preflight', 'list', 'hot', 'new', 'near-grad', 'notes', 'agents', 'token', 'info', 'status', 'portfolio', 'quote',
1049
1097
  'buy', 'follow', 'sell', 'claim', 'mint', 'withdraw', 'release', 'upload-logo', 'create', 'execute', 'tx', 'fair', 'v3', 'bond',
1050
- 'buyback', 'split', 'lp', 'fly'])
1098
+ 'buyback', 'split', 'lp', 'combo', 'fly'])
1051
1099
  // gang tx decodes these beside the V2 / Soft / U / S pads' events (GangLaunchpad: both kinds; the tax router; the vaults)
1052
- const GANG_EVENT_ABIS = [...V3_EVENT_ABIS, ...FAIR_EVENT_ABIS, ...FLY_EVENT_ABIS, ...SPLIT_EVENT_ABIS, ...LP_EVENT_ABIS]
1100
+ const GANG_EVENT_ABIS = [...V3_EVENT_ABIS, ...FAIR_EVENT_ABIS, ...FLY_EVENT_ABIS, ...SPLIT_EVENT_ABIS, ...LP_EVENT_ABIS, ...COMBO_EVENT_ABIS]
1053
1101
 
1054
- /** gang bond / gang buyback / gang split / gang lp on a 铸币飞轮 token: those contracts refuse it, so say why before any step. */
1102
+ /** gang bond / gang buyback / gang split / gang lp / gang combo on a 铸币飞轮 token: those contracts refuse it, so say why before any step. */
1055
1103
  async function refuseFly(what) {
1056
1104
  const token = opt('token')
1057
1105
  if (!isAddress(token ?? '')) return
@@ -1168,6 +1216,9 @@ async function main() {
1168
1216
  case 'lp':
1169
1217
  await refuseFly('an LP splitter')
1170
1218
  return runLp(args[1], { opt, flag, out, fail, summarize: summarizePreview })
1219
+ case 'combo':
1220
+ await refuseFly('a combined recipient')
1221
+ return runCombo(args[1], { opt, flag, out, fail, summarize: summarizePreview })
1171
1222
  case 'version':
1172
1223
  case '--version':
1173
1224
  case '-v':
package/src/launch.js CHANGED
@@ -10,6 +10,7 @@ import { parseAmount, parseIntIn, step } from './steps.js'
10
10
  import { buybackBpsOf, FACTORY_ABI, notDeployed, simulateCall, SPLITTER_ABI, splitterFactoryAddress, splitterOf } from './buyback.js'
11
11
  import { parseSplitSpec, simulateSplit, SPLIT_ABI, SPLIT_FACTORY_ABI, splitFactoryAddress, splitLine, splitNotDeployed, splitOf } from './split.js'
12
12
  import { LP_ABI, LP_FACTORY_ABI, lpBpsOf, lpFactoryAddress, lpNotDeployed, lpOf, simulateLp } from './lp.js'
13
+ import { COMBO_ABI, COMBO_FACTORY_ABI, comboFactoryAddress, comboLine, comboNotDeployed, comboOf, comboParts, parseComboSpec, PERMANENT_NOTE, simulateCombo } from './combo.js'
13
14
 
14
15
  /**
15
16
  * One command for a launch: `gang create … [--buyback <pct>] [--dev-buy <quote> [--bond <quote> [--bond-hold <tokens|N%|all>]
@@ -36,7 +37,12 @@ import { LP_ABI, LP_FACTORY_ABI, lpBpsOf, lpFactoryAddress, lpNotDeployed, lpOf,
36
37
  * --lp <pct> [--lp-to <addr>] (V3, taxed): the same three steps with GangLiquiditySplitterFactory — the dev's LP splitter
37
38
  * (lp-burn-v1: --lp % of the recipient's part added to the pair as liquidity, the LP to 0xdead) is cloned at
38
39
  * predict(dev, salt), named as the recipient, then bound (`module: 'lp'` in the plan). A launch keeps the ratio and payee
39
- * it began with. --buyback, --split, --lp and --recipient are exclusive (each sets the recipient).
40
+ * it began with. --recipient goes with none of them (each sets the recipient).
41
+ * More than one of --buyback, --lp, --split (taxed V3): the same three steps with GangComboSplitterFactory — the dev's
42
+ * combined recipient (combo-v1: --buyback % of the recipient's part bought back and burned, --lp % added as liquidity, the
43
+ * rest pushed to the --split payees, or to the dev alone without --split) is cloned at predict(dev, salt), named as the
44
+ * recipient, then bound (`module: 'combo'`). Everything in it is fixed for good, so a re-run with other ratios or payees
45
+ * is refused rather than starting over. --buyback-to / --lp-to don't apply (the payees are --split's).
40
46
  */
41
47
 
42
48
  const LAUNCH_DIR = process.env.GANG_LAUNCH_DIR || join(dirname(DIR), 'launch')
@@ -61,7 +67,7 @@ const REGISTRY_ABI = parseAbi(['function quoteRegistry() view returns (address)'
61
67
  * --split takes the same quotes: a quote that calls the receiver back on transfer would let one payee make every split
62
68
  * run out of gas, and the keeper splits only these quotes anyway (split spec §2.4).
63
69
  * --lp takes the same quotes: the keeper adds liquidity only over these, and an unlisted quote may tax or block the
64
- * transfers into the pair every chunk makes.
70
+ * transfers into the pair every chunk makes. A combined recipient (several of them) takes the same quotes for all reasons.
65
71
  * null when trusted; otherwise the failure to report.
66
72
  */
67
73
  const UNTRUSTED = {
@@ -77,6 +83,10 @@ const UNTRUSTED = {
77
83
  why: '--lp needs WBNB, GANG or a quote listed in the pad\'s QuoteRegistry: the keeper adds liquidity only over those quotes, and an unlisted quote may tax or block the transfers into the pair every chunk makes',
78
84
  hint: 'drop --quote (WBNB), use a listed quote, or launch without --lp',
79
85
  },
86
+ combo: {
87
+ why: 'a combined recipient (more than one of --buyback / --lp / --split) needs WBNB, GANG or a quote listed in the pad\'s QuoteRegistry: its buy-backs and liquidity adds price on what the pair receives (a quote that taxes transfers into the pair fails every chunk), the keeper serves only those quotes, and an unlisted quote may call a payee back on transfer',
88
+ hint: 'drop --quote (WBNB), use a listed quote, or launch without --buyback / --lp / --split',
89
+ },
80
90
  }
81
91
  export async function untrustedBuybackQuote(read, net, quote, mode = 'buyback') {
82
92
  if (!isAddress(quote ?? '')) return { error: '--quote must be a 0x address', got: quote ?? null }
@@ -102,8 +112,10 @@ export const FAIR_DEV_BUY = 'a 打新 dev buys its shares in the create itself:
102
112
 
103
113
  /** The run asks for a chained launch (`kind` 'v3' | 'fair'). */
104
114
  export const isLaunch = (kind, flag) => flag('bond') || flag('buyback') || flag('split') || flag('lp') || (kind === 'v3' && flag('dev-buy'))
105
- /** The recipient modules a launch can clone (their flags), at most one per launch. */
115
+ /** The recipient modules a launch can clone (their flags): one alone clones its own module, several a combined one. */
106
116
  const MODULE_FLAGS = ['buyback', 'split', 'lp']
117
+ /** How a module's flags read in a message. */
118
+ const MOD_FLAG = { buyback: '--buyback', split: '--split', lp: '--lp', combo: 'more than one of --buyback / --lp / --split' }
107
119
 
108
120
  const planPath = (key) => join(LAUNCH_DIR, `${createHash('sha256').update(key).digest('hex').slice(0, 32)}.json`)
109
121
 
@@ -149,9 +161,9 @@ export async function runLaunch(kind, { io, runV3, runFair, runBond, padNotes })
149
161
  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')
150
162
  if (kind === 'fair' && flag('split')) fail('--split is for V3 tokens: it makes the tax recipient a split module, and a 打新 token has no recipient')
151
163
  if (kind === 'fair' && flag('lp')) fail('--lp is for V3 tokens: it makes the tax recipient an LP splitter, and a 打新 token has no recipient')
152
- if (flag('split') && flag('buyback')) fail('give --split or --buyback, not both: each makes the tax recipient its own module (a split with a buy-back is not supported)')
153
164
  const mods = MODULE_FLAGS.filter((f) => flag(f))
154
- if (mods.length > 1) fail(`give one of --${mods.join(' / --')}, not several: each makes the tax recipient its own module`)
165
+ // more than one: one combined recipient (GangComboSplitter) does them all
166
+ const combo = mods.length > 1
155
167
 
156
168
  // everything checked before the create, so a launch never stops half way on a bad flag
157
169
  const devBuy = kind === 'v3' && flag('dev-buy') ? parseAmount(fail, 'dev-buy', opt('dev-buy')) : null
@@ -169,10 +181,27 @@ export async function runLaunch(kind, { io, runV3, runFair, runBond, padNotes })
169
181
  bond = { amount: parseAmount(fail, 'bond', opt('bond')), hold, days: parseIntIn(fail, 'bond-days', opt('bond-days'), 7, 90) }
170
182
  }
171
183
 
184
+ // several of --buyback / --lp / --split: a taxed V3 token whose recipient is the dev's combined recipient
185
+ let comboFactory = null
186
+ if (combo) {
187
+ const names = mods.map((f) => `--${f}`).join(' + ')
188
+ comboFactory = comboFactoryAddress(testnet)
189
+ if (!comboFactory) fail(comboNotDeployed(testnet), { flags: mods.map((f) => `--${f}`) })
190
+ for (const to of ['buyback-to', 'lp-to']) {
191
+ if (flag(to)) fail(`--${to} does not apply to a combined recipient (${names}): the part not bought back or added goes to the payees — name them with --split self:<pct>,<addr>:<pct>,… (shares of that rest; without --split it all goes to you)`)
192
+ }
193
+ const zero = (f) => /^0+(\.0+)?$/.test(opt(f) ?? '')
194
+ if (!flag('buy-tax') || !flag('sell-tax') || (zero('buy-tax') && zero('sell-tax'))) {
195
+ fail(`${names} needs a taxed token: add --buy-tax and --sell-tax (each 1–5, in %); the combined recipient is paid from the tax`)
196
+ }
197
+ if (flag('recipient')) fail(`${names} makes the recipient your combined recipient: leave --recipient out`)
198
+ if (/^0*100(\.0+)?$/.test(opt('dividend', '0'))) fail(`--dividend 100 leaves nothing for the recipient: lower it or drop ${names}`)
199
+ }
200
+
172
201
  // --buyback: a taxed V3 token whose recipient (the part left after holders) is the dev's splitter
173
202
  let buyback = null
174
203
  if (flag('buyback-to') && !flag('buyback')) fail('--buyback-to <addr> goes with --buyback <pct>: it names where the part not bought back goes')
175
- if (flag('buyback')) {
204
+ if (flag('buyback') && !combo) {
176
205
  const zero = (f) => /^0+(\.0+)?$/.test(opt(f) ?? '')
177
206
  if (!flag('buy-tax') || !flag('sell-tax') || (zero('buy-tax') && zero('sell-tax'))) {
178
207
  fail('--buyback needs a taxed token: add --buy-tax and --sell-tax (each 1–5, in %); the buy-back is paid from the tax')
@@ -191,9 +220,24 @@ export async function runLaunch(kind, { io, runV3, runFair, runBond, padNotes })
191
220
 
192
221
  const me = walletFor({ chainId: net.chainId }, opt('from'))
193
222
 
223
+ // the combined recipient's ratios and payees (shares of the rest), checked as its initialize checks them
224
+ let comboSpec = null
225
+ if (combo) {
226
+ const spec = parseComboSpec({
227
+ buybackBps: flag('buyback') ? buybackBpsOf(fail, opt('buyback')) : 0,
228
+ lpBps: flag('lp') ? lpBpsOf(fail, opt('lp')) : 0,
229
+ split: flag('split') ? (opt('split') ?? '') : undefined,
230
+ }, me)
231
+ if (spec.error) {
232
+ const { error, ...extra } = spec
233
+ fail(error, extra)
234
+ }
235
+ comboSpec = { ...spec, factory: comboFactory }
236
+ }
237
+
194
238
  // --split: a taxed V3 token whose recipient is the dev's split module (fixed payees and shares)
195
239
  let split = null
196
- if (flag('split')) {
240
+ if (flag('split') && !combo) {
197
241
  const zero = (f) => /^0+(\.0+)?$/.test(opt(f) ?? '')
198
242
  if (!flag('buy-tax') || !flag('sell-tax') || (zero('buy-tax') && zero('sell-tax'))) {
199
243
  fail('--split needs a taxed token: add --buy-tax and --sell-tax (each 1–5, in %); the split is paid from the tax')
@@ -213,7 +257,7 @@ export async function runLaunch(kind, { io, runV3, runFair, runBond, padNotes })
213
257
  // --lp: a taxed V3 token whose recipient is the dev's LP splitter (auto-liquidity, the LP to 0xdead)
214
258
  let lp = null
215
259
  if (flag('lp-to') && !flag('lp')) fail('--lp-to <addr> goes with --lp <pct>: it names where the part not added to the pool goes')
216
- if (flag('lp')) {
260
+ if (flag('lp') && !combo) {
217
261
  const zero = (f) => /^0+(\.0+)?$/.test(opt(f) ?? '')
218
262
  if (!flag('buy-tax') || !flag('sell-tax') || (zero('buy-tax') && zero('sell-tax'))) {
219
263
  fail('--lp needs a taxed token: add --buy-tax and --sell-tax (each 1–5, in %); the liquidity is paid from the tax')
@@ -229,12 +273,12 @@ export async function runLaunch(kind, { io, runV3, runFair, runBond, padNotes })
229
273
  }
230
274
  lp = { bps: lpBpsOf(fail, opt('lp')), factory, payee }
231
275
  }
232
- const mod = buyback ? 'buyback' : split ? 'split' : lp ? 'lp' : null
276
+ const mod = comboSpec ? 'combo' : buyback ? 'buyback' : split ? 'split' : lp ? 'lp' : null
233
277
 
234
278
  const client = createPublicClient({ chain: net.chain, transport: rpcTransport(net.rpcs) })
235
279
  const read = (address, abi, functionName, args = []) => client.readContract({ address, abi, functionName, args })
236
280
  const key = [net.chainId, net.pad, me.toLowerCase(), kind, name, symbol].join('|')
237
- const cloneStep = buyback ? 'buyback-splitter' : split ? 'split-module' : 'lp-splitter'
281
+ const cloneStep = { buyback: 'buyback-splitter', split: 'split-module', lp: 'lp-splitter', combo: 'combo-module' }[mod]
238
282
  const steps = [...(mod ? [cloneStep] : []), kind === 'v3' ? 'create' : 'create (dev shares included)', ...(mod ? ['bind'] : []),
239
283
  ...(devBuy ? ['dev-buy'] : []), ...(bond ? ['bond'] : [])]
240
284
  const rerun = 're-run this same command after executing it'
@@ -246,14 +290,15 @@ export async function runLaunch(kind, { io, runV3, runFair, runBond, padNotes })
246
290
 
247
291
  // ---- a launch keeps the mode it began with (the create, once built, is never redone by a changed flag)
248
292
  const created = plan?.startCount !== undefined
249
- // the module this plan cloned: 'split' / 'lp' when it says so, else a --buyback splitter (plans from before --split)
250
- const planMod = plan?.salt ? (plan.module === 'split' || plan.module === 'lp' ? plan.module : 'buyback') : null
251
- const modNoun = { buyback: 'splitter', split: 'split module', lp: 'LP splitter' }
293
+ // the module this plan cloned: 'split' / 'lp' / 'combo' when it says so, else a --buyback splitter (plans from before --split)
294
+ const planMod = plan?.salt ? (['split', 'lp', 'combo'].includes(plan.module) ? plan.module : 'buyback') : null
295
+ const modNoun = { buyback: 'splitter', split: 'split module', lp: 'LP splitter', combo: 'combined recipient' }
252
296
  if (mod && created && !plan.splitter) {
253
- return fail(`this launch was created without --${mod} (its recipient is fixed): run it again without --${mod}, or add --restart for a new token`)
297
+ return fail(`this launch was created without ${MOD_FLAG[mod]} (its recipient is fixed): run it again without ${mod === 'combo' ? '--buyback / --lp / --split' : MOD_FLAG[mod]}, or add --restart for a new token`)
254
298
  }
255
299
  if (planMod && mod !== planMod && (!created || mod)) {
256
- return fail(`this launch began with --${planMod} (its ${modNoun[planMod]} is cloned or on the way): run it again with --${planMod}${mod ? ` instead of --${mod}` : ''}, or add --restart${mod ? '' : ` without it`}`)
300
+ const again = planMod === 'combo' ? 'the same --buyback / --lp / --split as before' : MOD_FLAG[planMod]
301
+ return fail(`this launch began with ${MOD_FLAG[planMod]} (its ${modNoun[planMod]} is cloned or on the way): run it again with ${again}${mod ? ` instead of ${MOD_FLAG[mod]}` : ''}, or add --restart${mod ? '' : ' without it'}`)
257
302
  }
258
303
 
259
304
  // ---- buy-back splitter: cloned for the dev before the create, at predict(dev, plan.salt)
@@ -389,6 +434,54 @@ export async function runLaunch(kind, { io, runV3, runFair, runBond, padNotes })
389
434
  }
390
435
  }
391
436
 
437
+ // ---- combined recipient: cloned for the dev before the create, at predict(dev, plan.salt)
438
+ if (comboSpec && !created) {
439
+ if (!plan?.salt) {
440
+ const refused = await untrustedBuybackQuote(read, net, flag('quote') ? opt('quote') : net.wbnb, 'combo')
441
+ if (refused) {
442
+ const { error, ...extra } = refused
443
+ return fail(error, extra)
444
+ }
445
+ if ((await client.getCode({ address: comboSpec.factory }) ?? '0x') === '0x') {
446
+ const env = testnet ? 'GANG_TESTNET_COMBO_FACTORY' : 'GANG_COMBO_FACTORY'
447
+ return fail(`GangComboSplitterFactory has no code at ${comboSpec.factory} on ${testnet ? 'the BSC testnet' : 'BSC mainnet'}: give one of --buyback / --lp / --split alone for now${process.env[env] ? ` (or fix ${env})` : ''}`, { factory: comboSpec.factory })
448
+ }
449
+ const salt = `0x${randomBytes(32).toString('hex')}`
450
+ const at = await read(comboSpec.factory, COMBO_FACTORY_ABI, 'predict', [me, salt])
451
+ if (comboSpec.payees.some((p) => p.toLowerCase() === at.toLowerCase())) return fail('--split: a payee cannot be the combined recipient itself', { module: at })
452
+ const args = [comboSpec.buybackBps, comboSpec.lpBps, comboSpec.payees, comboSpec.shares, salt]
453
+ const sim = await simulateCombo(client, me, comboSpec.factory, COMBO_FACTORY_ABI, 'create', args)
454
+ if (sim.failed) return out({ success: false, step: 'combo-module', factory: comboSpec.factory, ...tag('combo-module'), ...sim.failed })
455
+ writePlan(key, { ...base, salt, splitter: at, factory: comboSpec.factory, module: 'combo' })
456
+ const data = encodeFunctionData({ abi: COMBO_FACTORY_ABI, functionName: 'create', args })
457
+ const parts = comboParts(comboSpec.buybackBps, comboSpec.lpBps, comboSpec.payees.length)
458
+ return out({
459
+ ...step({ chainId: net.chainId }, { from: me, to: comboSpec.factory, data }, {
460
+ step: 'combo-module', chainId: Number(net.chainId), factory: comboSpec.factory, module: at,
461
+ buybackPct: comboSpec.buybackBps / 100, lpPct: comboSpec.lpBps / 100, payeesPct: (10_000 - comboSpec.buybackBps - comboSpec.lpBps) / 100,
462
+ payees: comboSpec.list, permanent: true, parts,
463
+ note: `clones your combined recipient (combo-v1, listed as a tax recipient in the same tx). Of the recipient's part of the tax: ${comboLine(comboSpec.buybackBps, comboSpec.lpBps, comboSpec.payees, comboSpec.shares)}. ${PERMANENT_NOTE}. ${parts.otherAssets[0].toUpperCase()}${parts.otherAssets.slice(1)}`,
464
+ }, flag('calldata'), io.summarize),
465
+ ...tag('combo-module', { module: at, next: `${rerun}: it then builds the create with the combined recipient as the recipient` }),
466
+ })
467
+ }
468
+ if ((await client.getCode({ address: plan.splitter }) ?? '0x') === '0x') {
469
+ return out({
470
+ success: false, ...tag('combo-module', { module: plan.splitter }), error: 'the combined recipient is not on chain yet',
471
+ 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`,
472
+ })
473
+ }
474
+ const s = await comboOf(read, plan.splitter, { wbnb: net.wbnb })
475
+ if (!s || s.dev.toLowerCase() !== me.toLowerCase() || s.token) {
476
+ return fail('the module at this launch\'s address is not an unbound combined recipient of this wallet: add --restart', { module: plan.splitter })
477
+ }
478
+ const same = s.buybackBps === comboSpec.buybackBps && s.lpBps === comboSpec.lpBps && s.payees.length === comboSpec.payees.length
479
+ && s.payees.every((p, i) => p.payee.toLowerCase() === comboSpec.payees[i].toLowerCase() && p.bps === comboSpec.shares[i])
480
+ if (!same) {
481
+ return fail(`this launch's combined recipient is ${comboLine(s.buybackBps, s.lpBps, s.payees.map((p) => p.payee), s.payees.map((p) => p.bps))}, not what --buyback / --lp / --split say: run it again with those, or add --restart for a new one (nothing in it can change after the clone)`, { module: plan.splitter })
482
+ }
483
+ }
484
+
392
485
  // ---- create
393
486
  if (!created) {
394
487
  const startCount = (await read(net.pad, PAD_ABI, 'tokenCount')).toString()
@@ -439,7 +532,9 @@ export async function runLaunch(kind, { io, runV3, runFair, runBond, padNotes })
439
532
  const bal = await read(token, ERC20_ABI, 'balanceOf', [me])
440
533
  const isSplit = plan.module === 'split'
441
534
  const isLp = plan.module === 'lp'
442
- const buybackState = () => (plan.splitter && !isSplit && !isLp ? splitterOf(read, plan.splitter) : null)
535
+ const isCombo = plan.module === 'combo'
536
+ const buybackState = () => (plan.splitter && !isSplit && !isLp && !isCombo ? splitterOf(read, plan.splitter) : null)
537
+ const comboState = () => (plan.splitter && isCombo ? comboOf(read, plan.splitter, { wbnb: net.wbnb, pad: net.pad, ref: `--token ${token}${testnet ? ' --testnet' : ''}` }) : null)
443
538
  const lpState = () => (plan.splitter && isLp ? lpOf(read, plan.splitter, { pad: net.pad }) : null)
444
539
  const splitState = () => (plan.splitter && isSplit ? splitOf(read, plan.splitter, { wbnb: net.wbnb, ref: `--token ${token}${testnet ? ' --testnet' : ''}` }) : null)
445
540
 
@@ -455,23 +550,27 @@ export async function runLaunch(kind, { io, runV3, runFair, runBond, padNotes })
455
550
  if (sp) done.split = sp
456
551
  const lps = await lpState()
457
552
  if (lps) done.lp = lps
553
+ const cs = await comboState()
554
+ if (cs) done.combo = cs
458
555
  if (!bond) return out({ ...done, note: `launched: gang ${kind} info --token ${token}${testnet ? ' --testnet' : ''}` })
459
556
  return runBond('status', { ...stepIo({}), out: (o) => out({ ...done, bondStatus: o, note: `launched and bonded: gang bond status --token ${token}${testnet ? ' --testnet' : ''}` }) })
460
557
  }
461
558
  if (plan.done) return report()
462
559
 
463
- // ---- bind the splitter / split module / LP splitter to the token (anyone may; the launch does it right after the create)
560
+ // ---- bind the splitter / split module / LP splitter / combined recipient to the token (anyone may; the launch does it right after the create)
464
561
  if (plan.splitter) {
465
- const abi = isSplit ? SPLIT_ABI : isLp ? LP_ABI : SPLITTER_ABI
562
+ const abi = isCombo ? COMBO_ABI : isSplit ? SPLIT_ABI : isLp ? LP_ABI : SPLITTER_ABI
466
563
  const bound = await read(plan.splitter, abi, 'token')
467
564
  if (bound === zeroAddress) {
468
- const sim = await (isSplit ? simulateSplit : isLp ? simulateLp : simulateCall)(client, me, plan.splitter, abi, 'bind', [token])
565
+ const sim = await (isCombo ? simulateCombo : isSplit ? simulateSplit : isLp ? simulateLp : simulateCall)(client, me, plan.splitter, abi, 'bind', [token])
469
566
  if (sim.failed) return out({ success: false, step: 'bind', ...tag('bind', { token }), ...sim.failed })
470
567
  const data = encodeFunctionData({ abi, functionName: 'bind', args: [token] })
471
568
  return out({
472
569
  ...step({ chainId: net.chainId }, { from: me, to: plan.splitter, data }, {
473
- step: 'bind', chainId: Number(net.chainId), token, ...(isSplit ? { module: plan.splitter } : { splitter: plan.splitter }),
474
- note: isSplit
570
+ step: 'bind', chainId: Number(net.chainId), token, ...(isSplit || isCombo ? { module: plan.splitter } : { splitter: plan.splitter }),
571
+ note: isCombo
572
+ ? 'ties the combined recipient to this token for good: its quote is what gets split, and its pair is where the buy-backs and liquidity go (from graduation on). Nothing is split before this'
573
+ : isSplit
475
574
  ? 'ties the split module to this token for good: the keeper then splits its quote among the payees'
476
575
  : isLp
477
576
  ? 'ties the LP splitter to this token for good: its pair is where the liquidity goes (from graduation on)'
@@ -481,7 +580,7 @@ export async function runLaunch(kind, { io, runV3, runFair, runBond, padNotes })
481
580
  })
482
581
  }
483
582
  if (bound.toLowerCase() !== token.toLowerCase()) {
484
- return out({ success: false, ...tag('bind', { token }), error: `the ${isSplit ? 'split module' : isLp ? 'LP splitter' : 'splitter'} is bound to another token`, [isSplit ? 'module' : 'splitter']: plan.splitter, boundTo: bound })
583
+ return out({ success: false, ...tag('bind', { token }), error: `the ${isCombo ? 'combined recipient' : isSplit ? 'split module' : isLp ? 'LP splitter' : 'splitter'} is bound to another token`, [isSplit || isCombo ? 'module' : 'splitter']: plan.splitter, boundTo: bound })
485
584
  }
486
585
  }
487
586
 
package/src/mcp.js CHANGED
@@ -24,7 +24,7 @@ const WATCH_MAX_SEC = 30 * 60
24
24
 
25
25
  // what the host shows the agent up front; some hosts cut server instructions near 2,000 characters, so the long form is in
26
26
  // RULES (gang_help). Keep both in step with skill/SKILL.md "Hard rules"
27
- const INSTRUCTIONS = `Gang (gang.fun): agent-only token launchpad on BNB Chain. Curve trades need a Binance Agentic Wallet with a .ai Agent ID: call gang_preflight first, relay each issues[].fix. Call gang_help for all flags and the full rules before any create, launch, bond, buyback, split, lp, mint or withdraw.
27
+ const INSTRUCTIONS = `Gang (gang.fun): agent-only token launchpad on BNB Chain. Curve trades need a Binance Agentic Wallet with a .ai Agent ID: call gang_preflight first, relay each issues[].fix. Call gang_help for all flags and the full rules before any create, launch, bond, buyback, split, lp, combo, mint or withdraw.
28
28
  Hard rules:
29
29
  - Preview -> show the user -> wait for a yes -> gang_execute. gang_buy / gang_sell / gang_follow and writes via gang_cli only preview; never gang_execute without the user's OK on that preview, unless they said to skip confirmation.
30
30
  - step wrap-bnb | approve | approve-quote = setup: execute it, check gang_tx, run the same tool again. A launch in one command is re-run until launch.stage is done.
@@ -42,7 +42,7 @@ Hard rules:
42
42
  export const RULES = [
43
43
  'Start: gang_preflight; relay each issues[].fix. A result carrying update: { cmd, skill } means this CLI is older than the rules: tell the user to run cmd, and do not trade on it.',
44
44
  'Preview -> show -> confirm -> execute. Every write first returns a preview with a requestId: show it, get the user\'s OK, then gang_execute. Chain steps without asking only when the user said to skip confirmation.',
45
- 'Setup steps: a preview with step wrap-bnb | approve-quote | approve is executed first; once gang_tx shows it landed, run the same tool again for the real step. A launch in one command (create with --dev-buy / --bond / --buyback / --split / --lp, or create --fair with --bond) is one tx per run: execute it, run the very same gang_cli args again until launch.stage is done.',
45
+ 'Setup steps: a preview with step wrap-bnb | approve-quote | approve is executed first; once gang_tx shows it landed, run the same tool again for the real step. A launch in one command (create with --dev-buy / --bond / --buyback / --split / --lp, two or three of the last three together for one combined recipient whose ratios and payees are fixed for good, or create --fair with --bond) is one tx per run: execute it, run the very same gang_cli args again until launch.stage is done.',
46
46
  'A gang_execute that timed out or was cancelled on your side keeps running here (the wallet may have sent it): never execute it again or build a new preview for the same trade before checking gang_status or gang_tx with pending: true; then gang_tx (hash, or pending: true) for the result and the note.',
47
47
  'Notes (--note) are public and permanent: write one by default on every buy, sell, mint, withdraw (one line: what you saw, why now) and every create (the launch manifesto). Base it on data you checked, show its text with the preview, leave it out only when the user says so. No links. --conf is an honest 0-100.',
48
48
  'Permanent token data: the logo, website, X link and description go on-chain at create and can never change. Use only links the user gave; ask once if they have not said. Never host a logo on a temporary file host. Local files (--logo, upload-logo --file) are read by this MCP server: pass an absolute path, or --logo-uri <image URL>.',
@@ -85,7 +85,7 @@ const tool = (name, title, description, properties, args, annotations, required
85
85
 
86
86
  export const TOOLS = [
87
87
  tool('gang_help', 'Commands and rules',
88
- 'Every gang command with all its flags (the CLI help) and the full rules. Read it before a create, launch, bond, buyback, split, lp, mint or withdraw, and whenever a flag is unclear; those commands then go through gang_cli.',
88
+ 'Every gang command with all its flags (the CLI help) and the full rules. Read it before a create, launch, bond, buyback, split, lp, combo, mint or withdraw, and whenever a flag is unclear; those commands then go through gang_cli.',
89
89
  {}, () => [], READ),
90
90
  tool('gang_preflight', 'Check wallet setup', 'Signed in to baw, Developer Mode, Trade all tokens, Agent ID; each issue comes with a fix.',
91
91
  {}, () => ['preflight'], READ),
@@ -175,7 +175,7 @@ export const TOOLS = [
175
175
  { hash: HASH, pending: { type: 'boolean', description: 'Find the txs of trades approved in the Binance App (no hash needed)' }, testnet: TESTNET },
176
176
  (a) => (a.pending ? ['tx', '--pending'] : ['tx', '--hash', a.hash, ...bool('testnet', a.testnet)]), PREVIEW),
177
177
  tool('gang_cli', 'Other gang commands',
178
- 'Every other gang command, its flags as separate items (gang_help lists them all): create (V3; create --fair = fair mint; create --fly = Mint Flywheel; launch in one command with --dev-buy / --bond / --buyback / --split / --lp), mint (--ref <inviter> on a Mint Flywheel token), withdraw, claim, release, fly open-early|launch|invite, quote, list, upload-logo, bond post|topup|raise-hold|extend|status|start|report|settle|refund|burn|tx, buyback status|set|set-payee|apply|bind|release, split status|distribute|release|set-payee|bind, lp status|set|set-payee|apply|bind|release|add, v3 income, version; the flags no other tool takes (--calldata, --from, …) too. E.g. ["create","--name","My Token","--symbol","MYT","--logo","/Users/me/avatar.png"], ["bond","status","--token","0x…"]. Local files are read by this server: absolute paths, or --logo-uri <image URL>. Writes only preview, as above. execute / watch / help have their own tools.',
178
+ 'Every other gang command, its flags as separate items (gang_help lists them all): create (V3; create --fair = fair mint; create --fly = Mint Flywheel; launch in one command with --dev-buy / --bond / --buyback / --split / --lp, several of the last three = one combined recipient), mint (--ref <inviter> on a Mint Flywheel token), withdraw, claim, release, fly open-early|launch|invite, quote, list, upload-logo, bond post|topup|raise-hold|extend|status|start|report|settle|refund|burn|tx, buyback status|set|set-payee|apply|bind|release, split status|distribute|release|set-payee|bind, lp status|set|set-payee|apply|bind|release|add, combo status|distribute|release|set-payee|bind|chunk, v3 income, version; the flags no other tool takes (--calldata, --from, …) too. E.g. ["create","--name","My Token","--symbol","MYT","--logo","/Users/me/avatar.png"], ["bond","status","--token","0x…"]. Local files are read by this server: absolute paths, or --logo-uri <image URL>. Writes only preview, as above. execute / watch / help have their own tools.',
179
179
  { args: { type: 'array', items: { type: 'string' }, minItems: 1 } }, (a) => a.args, { readOnlyHint: false, destructiveHint: false, openWorldHint: true }, ['args']),
180
180
  ]
181
181
  const BY_NAME = new Map(TOOLS.map((t) => [t.name, t]))
package/src/v3.js CHANGED
@@ -9,6 +9,7 @@ import { bondGuard } from './bond.js'
9
9
  import { splitterOf } from './buyback.js'
10
10
  import { splitOf } from './split.js'
11
11
  import { lpOf } from './lp.js'
12
+ import { comboOf, decoyWarning } from './combo.js'
12
13
 
13
14
  /**
14
15
  * `gang v3 …` — LaunchpadV3 (tax recipient): a token with its own buy / sell tax (1–5% each), a dividend share and a
@@ -285,6 +286,11 @@ export async function runV3(sub, { opt, flag, out, fail, summarize, resolveLogo,
285
286
  ? await splitOf(ctx.read, c.recipient, { wbnb: ctx.wbnb, extraAssets: [c.quote], ref: `--token ${token}${net}` }) : null
286
287
  // or the dev's LP splitter (lp-burn-v1): its ratio, what is set aside for the pool, the next chunk
287
288
  const lp = c.recipient && !c.recipientIsCreator && !buyback && !split ? await lpOf(ctx.read, c.recipient, { pad: ctx.pad }) : null
289
+ // or the dev's combined recipient (combo-v1): fixed buy-back / LP ratios and payees, the set-aside parts, the next chunk
290
+ const comboRef = `--token ${token}${net}`
291
+ const combo = c.recipient && !c.recipientIsCreator && !buyback && !split && !lp
292
+ ? await comboOf(ctx.read, c.recipient, { wbnb: ctx.wbnb, pad: ctx.pad, extraAssets: [c.quote], ref: comboRef }) : null
293
+ const comboWarning = combo ? decoyWarning(combo, token, c.quote, comboRef) : null
288
294
  const lpWarn = lp && lp.token && lp.token.toLowerCase() !== token.toLowerCase()
289
295
  ? { warning: `this token pays its tax to the LP splitter, but it is bound to another token (${lp.token}): the liquidity goes to that token's pair` } : null
290
296
  const splitWarn = split && split.token && split.token.toLowerCase() !== token.toLowerCase()
@@ -292,6 +298,7 @@ export async function runV3(sub, { opt, flag, out, fail, summarize, resolveLogo,
292
298
  return out({
293
299
  success: true, chainId: Number(ctx.chainId), ...fees, ...pub, taxNote, ...(swapBack && { swapBack }), ...(buyback && { buyback }),
294
300
  ...(split && { split: { ...split, ...splitWarn } }), ...(lp && { lp: { ...lp, ...lpWarn } }),
301
+ ...(combo && { combo: { ...combo, ...(comboWarning && { warning: comboWarning }) } }),
295
302
  })
296
303
  }
297
304