@gangfun/cli 0.33.0 → 0.35.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/combo.js CHANGED
@@ -233,7 +233,7 @@ const iso = (s) => (Number(s) > 0 ? new Date(Number(s) * 1000).toISOString() : n
233
233
  const q18 = (x) => formatUnits(x, 18)
234
234
 
235
235
  /** _kindOf: the larger set-aside part (a buy-back on a tie); a liquidity part under 2 wei has no half. */
236
- function kindOf(bb, lp) {
236
+ export function kindOf(bb, lp) {
237
237
  const canBurn = bb !== 0n, canAdd = lp / 2n !== 0n
238
238
  if (!canBurn && !canAdd) return null
239
239
  if (!canAdd) return 'buy-back'
package/src/creatorfee.js CHANGED
@@ -2,13 +2,15 @@ import { createPublicClient, encodeFunctionData, hexToString, isAddress, parseAb
2
2
  import { revertOf as revertIn, step, units } from './steps.js'
3
3
  import { atTokenPad, CREATOR_FEE_ABI, creatorFeeShareOf, NOT_ON_MAINNET, padNets, rpcTransport } from './gangpad.js'
4
4
  import { walletFor } from './fair.js'
5
+ import { promoteTermsOf } from './promote.js'
5
6
 
6
7
  /**
7
8
  * `gang creator-fee` — the GangLaunchpad 2.0 creator fee (docs/SPEC-CURVE-CREATOR-FEE-2026-10-31.md): of the 1% fee on
8
9
  * each V3 curve buy and sell, 70% is kept on the pad for the token's creator (`creatorFeeOf`), the rest goes to the
9
10
  * platform. The creator claims it with `claimCreatorFee(token, to)`, to any address, before or after graduation, with no
10
11
  * deadline. It is the creating wallet's own: it never goes to the tax recipient, a buy-back splitter, a split module or
11
- * an LP splitter. 打新 sales and 1.0 pads have none (on 1.0 the whole curve fee is the platform's).
12
+ * an LP splitter. 打新 sales and 1.0 pads have none (on 1.0 the whole curve fee is the platform's). A token made with
13
+ * promoter terms (gang create --promote) pays part of it to the promoter of each bound wallet: creatorFeeOf is already net of that.
12
14
  */
13
15
 
14
16
  const CURVES_ABI = parseAbi([
@@ -21,6 +23,7 @@ const CURVES_ABI = parseAbi([
21
23
  const SYMBOL_ABI = parseAbi(['function symbol() view returns (string)'])
22
24
  const MODULE_TYPE_ABI = parseAbi(['function moduleType() view returns (bytes32)'])
23
25
  const QUOTE_ABI = parseAbi(['function quote() view returns (address)'])
26
+ const CAP_QUOTE_ABI = parseAbi(['function capQuote() view returns (address)'])
24
27
  const ABIS = [CREATOR_FEE_ABI, CURVES_ABI]
25
28
  const HINTS = {
26
29
  NotCreator: 'only the token\'s creator (the wallet that created it) can claim its creator fee; pass that wallet with --from',
@@ -59,15 +62,21 @@ export async function createNote(ctx, net = '') {
59
62
  /**
60
63
  * What pays out a fee claimed into a module, by its moduleType(): the buy-back and LP splitters pay their payee only
61
64
  * when they split (the keeper's chunks do it after graduation), the split module and the combined recipient on
62
- * distribute. null: not one of these.
65
+ * distribute. The capped recipient splits its own quote as the tax (the payees' part counted against the cap) and
66
+ * burns any other asset. null: not one of these.
63
67
  */
64
68
  export function payOutCmd(moduleType, at, net = '', { asset, assetSymbol } = {}) {
65
69
  const t = String(moduleType ?? '')
66
70
  const base = t.startsWith('buyback-burn-') ? 'gang buyback' : t === 'lp-burn-v1' ? 'gang lp'
67
- : t === 'split-v1' ? 'gang split' : t === 'combo-v1' ? 'gang combo' : null
71
+ : t === 'split-v1' ? 'gang split' : t === 'combo-v1' ? 'gang combo' : t === 'capped-v1' ? 'gang capped' : null
68
72
  if (!base) return null
69
73
  const splitter = base === 'gang buyback' || base === 'gang lp'
70
74
  const m = `--module ${at ?? '<module>'}`
75
+ if (base === 'gang capped') {
76
+ return asset
77
+ ? `${base} distribute ${m} --asset ${asset}${net} (anyone) sends ALL of it to 0xdead: ${assetSymbol ?? 'this asset'} is not the module's quote, so it is burned, paid to nobody`
78
+ : `${base} distribute ${m}${net} (anyone) then splits it as the tax: the payees' part is pushed and counted against the cap (so it only uses the cap up sooner), the rest set aside for buy-back and liquidity`
79
+ }
71
80
  // a fee in another quote than the module's own: split / distribute of the bound quote never moves it
72
81
  if (asset) {
73
82
  return splitter
@@ -82,11 +91,18 @@ export function payOutCmd(moduleType, at, net = '', { asset, assetSymbol } = {})
82
91
  * The claim's --to note when --to is a module (pure: unit-tested): `bound` is its quote() (zero: not bound yet),
83
92
  * `quote` the token's. { payOut, warning }: a fee in another quote is not moved by split / distribute.
84
93
  */
85
- export function claimToModule({ moduleType, at, net = '', bound, quote, quoteSymbol, boundSymbol }) {
94
+ export function claimToModule({ moduleType, at, net = '', bound, quote, quoteSymbol, boundSymbol, capQuote, capSymbol }) {
86
95
  const other = !!bound && !!quote && bound.toLowerCase() !== quote.toLowerCase()
87
96
  const unbound = !bound || /^0x0{40}$/.test(bound)
88
- const payOut = payOutCmd(moduleType, at, net, other && !unbound ? { asset: quote, assetSymbol: quoteSymbol } : {})
97
+ // a capped recipient burns every asset but its quote: unbound, its quote is already fixed (capQuote)
98
+ const burned = moduleType === 'capped-v1' && !!quote && (unbound ? !!capQuote && capQuote.toLowerCase() !== quote.toLowerCase() : other)
99
+ const payOut = payOutCmd(moduleType, at, net, (other && !unbound) || burned ? { asset: quote, assetSymbol: quoteSymbol } : {})
89
100
  if (!payOut) return { payOut: null, warning: null }
101
+ if (burned) return { payOut, warning: `the capped recipient's quote is ${(unbound ? capSymbol : boundSymbol) ?? (unbound ? capQuote : bound)}, this fee is in ${quoteSymbol ?? quote}: it sends any other asset to 0xdead in full, so a fee claimed there is burned` }
102
+ // its quote unknown (capQuote() unread): never stay silent about a burn that may follow
103
+ if (moduleType === 'capped-v1' && unbound && !capQuote) {
104
+ return { payOut, warning: `could not read the capped recipient's quote (capQuote): if it is not ${quoteSymbol ?? quote}, this fee's quote, a fee claimed there is burned (it sends any other asset to 0xdead in full). Check gang capped status --module ${at ?? '<module>'}${net} first` }
105
+ }
90
106
  if (unbound) return { payOut, warning: 'the module is not bound to a token yet: it pays this out only once it is bound (its launch binds it)' }
91
107
  if (!other) return { payOut, warning: null }
92
108
  return {
@@ -94,11 +110,13 @@ export function claimToModule({ moduleType, at, net = '', bound, quote, quoteSym
94
110
  warning: `the module's own quote is ${boundSymbol ?? bound}, this fee is in ${quoteSymbol ?? quote}: split / distribute of the module's quote leave it where it is`,
95
111
  }
96
112
  }
97
- const LAUNCH_TYPES = { buyback: 'buyback-burn-v4', lp: 'lp-burn-v1', split: 'split-v1', combo: 'combo-v1' }
113
+ const LAUNCH_TYPES = { buyback: 'buyback-burn-v4', lp: 'lp-burn-v1', split: 'split-v1', combo: 'combo-v1', capped: 'capped-v1' }
98
114
 
99
- /** Added to the create's note when the tax recipient is one of the dev's modules (`module`: its name; `kind`: buyback | lp | split | combo). */
115
+ /** Added to the create's note when the tax recipient is one of the dev's modules (`module`: its name; `kind`: buyback | lp | split | combo | capped). */
100
116
  export const notThroughModule = (module, { token, at, net = '', kind } = {}) =>
101
117
  `This creator fee is yours, the creating wallet's: it does not go through the ${module}, which gets only the recipient's part of the pool tax after graduation.`
118
+ // capped: the fee kept (or claimed anywhere else) is never limited by the cap; claimed into the module it is split as tax
119
+ + (kind === 'capped' ? ' The cap never limits it: it covers only the recipient\'s part of the pool tax.' : '')
102
120
  + (at ? ` To put it into the ${module} anyway, claim it there: gang creator-fee --token ${token ?? '<token>'}${net} --claim --to ${at}` : '')
103
121
  + (at && kind && LAUNCH_TYPES[kind] ? `; ${payOutCmd(LAUNCH_TYPES[kind], at, net)}` : '')
104
122
 
@@ -117,10 +135,11 @@ export async function curveCreatorFee(ctx, token, { creator, quote }, net = '')
117
135
  }
118
136
  const padGen = ctx.gen ?? (share == null ? '1.0' : '2.0')
119
137
  if (share == null) return { padGen, creatorFee: null }
138
+ const terms = await promoteTermsOf(ctx, token).catch(() => null)
120
139
  return {
121
140
  padGen,
122
141
  creatorFee: {
123
- sharePct: pctOf(share), creator, claimable: await units(ctx, quote, owed), claimableRaw: owed.toString(),
142
+ sharePct: pctOf(share), creator, ...(terms?.shareBps > 0 && { promoterSharePct: terms.sharePct, promoterNote: `on trades of wallets bound to a promoter, ${terms.sharePct}% of this goes to the promoter; claimable is what is left for the creator` }), claimable: await units(ctx, quote, owed), claimableRaw: owed.toString(),
124
143
  ...(owed > 0n && { claim: `${claimCmd(token, net)} (the creator only)` }),
125
144
  note: `${pctOf(share)}% of the 1% curve fee of each curve buy and sell is kept for the creator, apart from the pool tax and its recipient; the creator claims it any time`,
126
145
  },
@@ -203,7 +222,7 @@ export async function runCreatorFee({ opt, flag, out, fail, summarize }) {
203
222
  return out({
204
223
  success: true, chainId, creator: me, ...r,
205
224
  ...(r.scanned.some((s) => s.read < s.tokens) && { scanNote: `only the newest ${MAX_SCAN} tokens of a pad were read` }),
206
- note: 'GangLaunchpad 2.0 and 3.0 keep 70% of the 1% curve fee of each curve buy and sell for the token\'s creator; 1.0 tokens and 打新 sales have none',
225
+ note: 'GangLaunchpad 2.0 and 3.0 keep 70% of the 1% curve fee of each curve buy and sell for the token\'s creator, less the share of any promoter the creator set (gang create --promote); 1.0 tokens and 打新 sales have none',
207
226
  ...(due.length && { next: due.map((x) => claimCmd(x.token, net)) }),
208
227
  })
209
228
  }
@@ -247,9 +266,10 @@ export async function runCreatorFee({ opt, flag, out, fail, summarize }) {
247
266
  let toModule = { payOut: null, warning: null }
248
267
  if (toType && payOutCmd(toType, to)) {
249
268
  const bound = await ctx.read(to, QUOTE_ABI, 'quote').catch(() => null)
269
+ const capQuote = toType === 'capped-v1' ? await ctx.read(to, CAP_QUOTE_ABI, 'capQuote').catch(() => null) : null
250
270
  const sym = (a) => (a && !/^0x0{40}$/.test(a) ? ctx.read(a, SYMBOL_ABI, 'symbol').catch(() => null) : null)
251
- const [quoteSymbol, boundSymbol] = await Promise.all([sym(quote), sym(bound)])
252
- toModule = claimToModule({ moduleType: toType, at: to, net, bound, quote, quoteSymbol, boundSymbol })
271
+ const [quoteSymbol, boundSymbol, capSymbol] = await Promise.all([sym(quote), sym(bound), sym(capQuote)])
272
+ toModule = claimToModule({ moduleType: toType, at: to, net, bound, quote, quoteSymbol, boundSymbol, capQuote, capSymbol })
253
273
  }
254
274
  const { payOut, warning } = toModule
255
275
  return out(step(ctx, { from: me, to: ctx.pad, data }, {
package/src/flags.js CHANGED
@@ -8,7 +8,7 @@ import { LAUNCH_FLAGS } from './launch.js'
8
8
 
9
9
  export const LINK_FLAGS = ['website', 'twitter']
10
10
  // gang create: V3 by default, a 打新 sale with --fair; a setting of the other kind is refused, not ignored
11
- export const V3_CREATE_FLAGS = ['buy-tax', 'sell-tax', 'dividend', 'recipient']
11
+ export const V3_CREATE_FLAGS = ['buy-tax', 'sell-tax', 'dividend', 'recipient', 'promote', 'promote-days']
12
12
  export const FAIR_CREATE_FLAGS = ['raise', 'cap', 'hold', 'mint-fee', 'exit-fee', 'shares']
13
13
 
14
14
  export const CREATE_ACCEPTS = new Set([
@@ -21,6 +21,20 @@ export const CREATE_ACCEPTS = new Set([
21
21
  'follow', 'cover', 'taxed', 'pair', 'pair-or-quote', 'hours',
22
22
  ])
23
23
 
24
+ // every flag a buy's code reads, whatever the token's kind: a buy refuses the rest, since a misspelled --promoter would fall
25
+ // through to a plain first buy, which uses up the wallet's only chance to bind
26
+ export const BUY_ACCEPTS = new Set([
27
+ 'agent', 'all', 'amount', 'bnb', 'board', 'break-bond', 'buy-tax', 'calldata', 'cap', 'conf', 'confirm-out',
28
+ 'description', 'dev-buy', 'dev-cut', 'dev-shares', 'dividend', 'events', 'exit-fee', 'fair', 'file', 'file-logo',
29
+ 'fly', 'follow', 'from', 'grad', 'guard', 'hash', 'hold', 'hours', 'include-graduated', 'interval',
30
+ 'keep-logo-uri', 'kind', 'limit', 'logo', 'logo-file', 'logo-uri', 'max-age', 'max-events', 'min-hit', 'min-pct',
31
+ 'min-shares', 'mint-fee', 'name', 'no-post-mint', 'note', 'notes', 'pair', 'pair-or-quote', 'path', 'pay-bnb',
32
+ 'pending', 'poll', 'post-mint', 'preset', 'promoter', 'quote', 'raise', 'recipient', 'ref', 'ref-pool',
33
+ 'request-id', 'reveal-after', 'sell-tax', 'settle-first', 'shares', 'slippage', 'sort', 'status', 'symbol',
34
+ 'taxed', 'testnet', 'tier', 'timeout', 'to-bnb', 'token', 'track', 'twap-window', 'twitter', 'url', 'use-quote',
35
+ 'use-wbnb', 'vault', 'webhook', 'website', 'who', 'window',
36
+ ])
37
+
24
38
  // what people type for the two link flags
25
39
  const LINK_TYPOS = {
26
40
  website: ['url', 'site', 'web', 'homepage', 'link', 'website-url', 'web-url', 'site-url', 'websiteurl', 'www'],
package/src/gangpad.js CHANGED
@@ -11,10 +11,10 @@ import { bsc, bscTestnet } from 'viem/chains'
11
11
  *
12
12
  * Env (new name first; the old per-command names still work as aliases). The contracts set the create target (gangGens):
13
13
  * mainnet: GANG_PAD (aliases GANG_V3_PAD / GANG_FAIR_PAD), GANG_ROUTER, GANG_BOND, GANG_SPLITTER_FACTORY,
14
- * GANG_SPLIT_FACTORY, GANG_LP_FACTORY, GANG_RPC_URL
14
+ * GANG_SPLIT_FACTORY, GANG_LP_FACTORY, GANG_PROMOTE_POOL_FACTORY, GANG_RPC_URL
15
15
  * testnet: GANG_TESTNET_PAD (aliases GANG_V3_TESTNET_PAD / GANG_FAIR_TESTNET_PAD),
16
16
  * GANG_TESTNET_ROUTER (alias GANG_ROUTER_TESTNET), GANG_TESTNET_BOND, GANG_TESTNET_SPLITTER_FACTORY,
17
- * GANG_TESTNET_SPLIT_FACTORY, GANG_TESTNET_LP_FACTORY,
17
+ * GANG_TESTNET_SPLIT_FACTORY, GANG_TESTNET_LP_FACTORY, GANG_TESTNET_PROMOTE_POOL_FACTORY,
18
18
  * GANG_TESTNET_RPC_URL (aliases GANG_V3_TESTNET_RPC_URL / GANG_FAIR_TESTNET_RPC_URL)
19
19
  * An RPC variable takes one URL or a comma-separated list; set, it replaces the public nodes below.
20
20
  */
@@ -48,12 +48,19 @@ export const GANG_GENS = {
48
48
  // GangRouter, tax handler (owned by its GangHandlerAdmin 0xC833…Af76), GangBond and the four module factories, all
49
49
  // bound to this proxy (docs/MAINNET-GANG-LAUNCHPAD-3-MODULES-2026-11-03.md). Vault mode since the Safe's upgrade at
50
50
  // block 131454282 (implementation 0x88A4…028D, Pad3Module 0xa712…409A); vaultModeOf reads it from the pad. 铸币飞轮 mode
51
- // and 打新 through the entry since 2026-11-04 (fly tax handler 0x7De9…3ba0, vault core 0x9d90…767E, deployer 0x2C95…072E)
51
+ // and 打新 through the entry since 2026-11-04 (fly tax handler 0x7De9…3ba0, vault core 0x9d90…767E, deployer 0x2C95…072E).
52
+ // Promoter share since the Safe's upgrade at block 132216700 (implementation 0xB06D…F7a4, Pad3Module 0x4E7E…bd6c)
52
53
  {
53
54
  gen: PAD3_GEN, pad: '0x2bEbED4be8c8F46C17776C71D7a6A45dbC5CAB29', router: '0xec9717E5C68b9F18fA76D3961C9Cd7e67b5E61e7',
54
55
  bond: '0x830b38F695Ca1bCbdD313CD5AA5943e2125Be9D6', splitterFactory: '0xc1282e7Fd3DFa5e00e74E9EbF8c54fFfB5763194',
55
56
  splitFactory: '0x904D4498a9257E4d7638afEbB95A1162cB2171f2', lpFactory: '0x98C506F0F4762F9d1Ec96C27499CE8B7e5981752',
56
57
  comboFactory: '0x20188054dE31De844df205712768852BdeD3eA39',
58
+ // capped-v1, 2026-11-08, block 132418984; the Safe allowed it on GangHandlerAdmin at block 132420220
59
+ // (docs/MAINNET-CAPPED-MODULE-2026-11-08.md)
60
+ cappedFactory: '0x294E901ecb66af280C1cDD26fD871601d89a2Dca',
61
+ // the pool side of the promoter share, 2026-11-07, block 132218466; the Safe allowed it on GangHandlerAdmin at block
62
+ // 132219892 (docs/MAINNET-GANG-LAUNCHPAD-3-PROMOTE-2026-11-07.md)
63
+ promotePoolFactory: '0xA633e499ADcD69A4F91dc83587096b2c1903167A',
57
64
  },
58
65
  // 2026-10-31, pad block 130874052: 2.0 with the creator fee and the graduation target the creator picks (the create
59
66
  // target until 3.0; its tokens trade and claim here); its own GangRouter, GangBond, buy-back factory
@@ -64,6 +71,7 @@ export const GANG_GENS = {
64
71
  bond: '0x231339463d04A2127E6dD5756756Dd56853AE0D8', splitterFactory: '0x77e499c892e5E6B3eEe1721e6821e9DA1293803C',
65
72
  splitFactory: '0xa73dC3d63AAf72E70b1cb012e5f3A541360Bec59', lpFactory: '0x8ac85f150f87B536fb05eA163908b1077D95c0E4',
66
73
  comboFactory: '0xcCeA388DbC0Edb206eC25C9715546d57029198Be',
74
+ cappedFactory: null,
67
75
  },
68
76
  // 2026-10-27, pad block 130104322. router = the GangRouter proxy: BNB buys and every PancakeSwap trade of a graduated
69
77
  // token (V3, 打新 and V2 / Soft / U / S alike). GangBond 2026-10-29 with the re-review L-1 fix; it replaces 0xf26F…C817
@@ -76,6 +84,7 @@ export const GANG_GENS = {
76
84
  splitFactory: '0x27e08271E52B2D129c824CD245e69471a8d3067c', lpFactory: '0xE0436867dAFcf42Ee1418083251a9B8B61F0C248',
77
85
  // combo-v1, 2026-10-31 (the Safe allowed it on GangHandlerAdmin at block 130811492)
78
86
  comboFactory: '0xd33C38BE3f8472b3013167830F0638C1704e1DBd',
87
+ cappedFactory: null,
79
88
  },
80
89
  // 2026-11-02, pad block 131081707: 2.0 金库版 (GangVaultLaunchpad; docs/MAINNET-GANG-VAULT-LAUNCHPAD-2026-11-02.md).
81
90
  // The 2.0 curves, each bound at create to one vault the platform listed (createWithVault, by the wallet the Safe
@@ -83,7 +92,7 @@ export const GANG_GENS = {
83
92
  // GangBond and no module factories (none is wired to it)
84
93
  {
85
94
  gen: VAULT_GEN, pad: '0xE90851A90C6278E3d6e4C24320101f8B13D90A11', router: '0xAcd4944A4090c13d9DACAe60f3019cef9d9bB1Ad',
86
- bond: null, splitterFactory: null, splitFactory: null, lpFactory: null, comboFactory: null,
95
+ bond: null, splitterFactory: null, splitFactory: null, lpFactory: null, comboFactory: null, cappedFactory: null,
87
96
  },
88
97
  ],
89
98
  testnet: [
@@ -95,6 +104,10 @@ export const GANG_GENS = {
95
104
  bond: '0xa87727dc3CC28a44709649A22aDbD77287B99fc1', splitterFactory: '0x3533E63EF0386adfBC96227C50f1b82EEA18d110',
96
105
  splitFactory: '0xf8d4FA57FD65Bf16427Eef653518811fFa2606dc', lpFactory: '0x4A3aC160eAF4A2747046b119631988D5D8056B07',
97
106
  comboFactory: '0xdc1687961c8aAf5A0340c1A73b604cf3a2be543C',
107
+ // capped-v1, 2026-11-08 (deployed at block 141527185, allowed on the GangHandlerAdmin at block 141527190)
108
+ cappedFactory: '0xe3f61865d98993dd39c136Af19651C6F6686498A',
109
+ // the pool side of the promoter share, 2026-11-05 (docs/TESTNET-GANG-LAUNCHPAD-3-2026-11-03.md)
110
+ promotePoolFactory: '0x7a68A65d27591a21C44f91015F930422BA79F1c2',
98
111
  },
99
112
  // 2026-10-31, pad block 139940227: 2.0 with the graduation target the creator picks (GRAD_BNB_TIERS, createWithGradTarget;
100
113
  // docs/SPEC-CURVE-GRAD-TARGET-2026-10-31.md), the create target until 3.0; buy-back factory buyback-burn-v4, split-v1,
@@ -104,6 +117,7 @@ export const GANG_GENS = {
104
117
  bond: '0x39749B59066d9cd1c55E2Fc48B31a3978C9951F9', splitterFactory: '0xDC9EdA9a29F4Ff66E7dAb6E5A2142df5a7aC0f6e',
105
118
  splitFactory: '0xb9ab949C717a4F7f05c7B003C612C437280C3513', lpFactory: '0xAEec7e7948FfDb7a212E14c0b9cc1DA2922436E4',
106
119
  comboFactory: '0x312c86F7139b3e3a75ee66b4D5Bfdbe5077584BD',
120
+ cappedFactory: null,
107
121
  },
108
122
  // 2026-10-31, pad block 139866088: the first 2.0 (creator fee, no graduation pick), no longer creating; its tokens trade
109
123
  // and claim here. Its modules from the same scripts as 1.0's (docs/TESTNET-GANGLAUNCHPAD2-2026-10-31.md)
@@ -112,6 +126,7 @@ export const GANG_GENS = {
112
126
  bond: '0x913966122b9f8CC00C0d81000988A483c6B7F97f', splitterFactory: '0xBc26A6585B3Dc2Cbf1522475fB5b18df6C1033AE',
113
127
  splitFactory: '0x860D51808E9FBB4f887FC7d0Aa9e1F8E19E00879', lpFactory: '0x4f1544e4e8853fC62088f0A4eCbEF409D2e11619',
114
128
  comboFactory: null, // none: its tokens can't have a combined recipient
129
+ cappedFactory: null,
115
130
  },
116
131
  // set 10 (2026-10-27: §23 aggregator entries). GangBond 2026-10-29, block 139463214 — the audited version (earlier:
117
132
  // 0x587f…5d7E, 0x5a99…d716, 0xB034…EBE3; docs/TESTNET-GANG-BOND-2026-10-28.md); split and LP factories
@@ -121,27 +136,29 @@ export const GANG_GENS = {
121
136
  bond: '0xd6a8dd5d1E6641a34A255f25Db2B3ED397CB1086', splitterFactory: '0x7E63fF8A9FB9Ab1BE4e2128e9f6C8D1054292BBe',
122
137
  splitFactory: '0x5F7dC7502E945A860Cf49cca72dA8bD60Fb1567E', lpFactory: '0xA729C60FCa0Bd0D28a55E22126D3fE412AA41591',
123
138
  comboFactory: '0x52a8f90a92E5C1828b4436a0B99C6b293f7F4CFE',
139
+ cappedFactory: null,
124
140
  },
125
141
  // 2026-11-01, pad block 140215635: 2.0 金库版, testnet v3 (docs/TESTNET-GANG-VAULT-LAUNCHPAD-2026-11-01.md)
126
142
  {
127
143
  gen: VAULT_GEN, pad: '0x9108e7b85e69060A5E626A04Ce6DEf323071C8a9', router: '0x9bF3E197a6719Af856a7c82d23CABFdBcc184f69',
128
- bond: null, splitterFactory: null, splitFactory: null, lpFactory: null, comboFactory: null,
144
+ bond: null, splitterFactory: null, splitFactory: null, lpFactory: null, comboFactory: null, cappedFactory: null,
129
145
  },
130
146
  ],
131
147
  }
132
148
  // what a generation brings to a ctx (gen: '1.0' | '2.0' | PAD3_GEN | VAULT_GEN, null for a pad named by the env that this CLI does not know)
133
- const GEN_FIELDS = ['gen', 'pad', 'router', 'bond', 'splitterFactory', 'splitFactory', 'lpFactory', 'comboFactory']
149
+ const GEN_FIELDS = ['gen', 'pad', 'router', 'bond', 'splitterFactory', 'splitFactory', 'lpFactory', 'comboFactory', 'cappedFactory', 'promotePoolFactory']
134
150
  // the env names of each field, per network (new name first; the old per-command names still work as aliases)
135
151
  const GEN_ENV = {
136
152
  mainnet: {
137
153
  pad: ['GANG_PAD', 'GANG_V3_PAD', 'GANG_FAIR_PAD'], router: ['GANG_ROUTER'], bond: ['GANG_BOND'],
138
154
  splitterFactory: ['GANG_SPLITTER_FACTORY'], splitFactory: ['GANG_SPLIT_FACTORY'], lpFactory: ['GANG_LP_FACTORY'],
139
- comboFactory: ['GANG_COMBO_FACTORY'],
155
+ comboFactory: ['GANG_COMBO_FACTORY'], cappedFactory: ['GANG_CAPPED_FACTORY'], promotePoolFactory: ['GANG_PROMOTE_POOL_FACTORY'],
140
156
  },
141
157
  testnet: {
142
158
  pad: ['GANG_TESTNET_PAD', 'GANG_V3_TESTNET_PAD', 'GANG_FAIR_TESTNET_PAD'], router: ['GANG_TESTNET_ROUTER', 'GANG_ROUTER_TESTNET'],
143
159
  bond: ['GANG_TESTNET_BOND'], splitterFactory: ['GANG_TESTNET_SPLITTER_FACTORY'], splitFactory: ['GANG_TESTNET_SPLIT_FACTORY'],
144
- lpFactory: ['GANG_TESTNET_LP_FACTORY'], comboFactory: ['GANG_TESTNET_COMBO_FACTORY'],
160
+ lpFactory: ['GANG_TESTNET_LP_FACTORY'], comboFactory: ['GANG_TESTNET_COMBO_FACTORY'], cappedFactory: ['GANG_TESTNET_CAPPED_FACTORY'],
161
+ promotePoolFactory: ['GANG_TESTNET_PROMOTE_POOL_FACTORY'],
145
162
  },
146
163
  }
147
164
 
package/src/index.js CHANGED
@@ -22,10 +22,12 @@ import { runV3, v3Ctx, V3_EVENT_ABIS } from './v3.js'
22
22
  import { runBond } from './bond.js'
23
23
  import { runBuyback } from './buyback.js'
24
24
  import { runSplit, SPLIT_EVENT_ABIS } from './split.js'
25
+ import { runPromote, PROMOTE_EVENT_ABIS } from './promote.js'
25
26
  import { runLp, LP_EVENT_ABIS } from './lp.js'
26
27
  import { runCombo, COMBO_EVENT_ABIS } from './combo.js'
28
+ import { runCapped, CAPPED_EVENT_ABIS } from './capped.js'
27
29
  import { runFly, flyCtx, isFlyToken, FLY_EVENT_ABIS, FLY_CREATE_FLAGS } from './fly.js'
28
- import { FAIR_DEV_BUY, isLaunch, LAUNCH_FLAGS, runLaunch } from './launch.js'
30
+ import { FAIR_DEV_BUY, isLaunch, LAUNCH_FLAGS, runLaunch, TAX_CAP_ALONE } from './launch.js'
29
31
  import { poolPayBnb, poolTrade } from './pool.js'
30
32
  import { parseAmount, ROUTER_ABI, ROUTER_HINTS, revertOf as revertIn, step as writeStep } from './steps.js'
31
33
  import { MERGED_ERRORS_ABI, genOf, padNets } from './gangpad.js'
@@ -36,7 +38,7 @@ import { portfolio } from './portfolio.js'
36
38
  import { codeOf, record } from './telemetry.js'
37
39
  import { trending, trendingBlock, TRENDING_NOTE } from './trending.js'
38
40
  import { shareFor } from './share.js'
39
- import { CREATE_ACCEPTS, FAIR_CREATE_FLAGS, LINK_FLAGS, V3_CREATE_FLAGS, unknownFlagError } from './flags.js'
41
+ import { BUY_ACCEPTS, CREATE_ACCEPTS, FAIR_CREATE_FLAGS, LINK_FLAGS, suggestFlag, V3_CREATE_FLAGS, unknownFlagError } from './flags.js'
40
42
  import { parseAbi } from 'viem'
41
43
 
42
44
  const args = process.argv.slice(2)
@@ -249,6 +251,27 @@ async function resolveRef(me) {
249
251
  const followSkipped = (follow) =>
250
252
  follow ? { follow: { ...follow, attached: false, reason: 'this setup step carries no follow ref; re-run the same command' } } : {}
251
253
 
254
+ /**
255
+ * A misspelled --promoter on a buy must not fall through to a plain first buy: that buy uses up the wallet's only chance
256
+ * to bind, for good.
257
+ */
258
+ function checkPromoterTypo() {
259
+ const argv = process.argv.slice(2)
260
+ for (const [i, a] of argv.entries()) {
261
+ // -promoter, —promoter (phones and chat apps turn -- into a dash), promoter: no flag parser sees these, so they'd drop silently
262
+ // argv[0] is the command itself: gang promote buy
263
+ if (i > 0 && !/^--[A-Za-z]/.test(a) && !['--note', '--ref', '--promoter'].includes(argv[i - 1]) && (/^[-\u2010-\u2015\u2212]+[A-Za-z]/.test(a) || /^promot/i.test(a))) {
264
+ fail(`${a} is not a flag: flags start with two plain hyphens, like --promoter <addr>. Nothing was built: a first buy without a promoter can never bind later`)
265
+ }
266
+ if (!/^--[A-Za-z]/.test(a) || a === '--promoter') continue
267
+ const name = a.slice(2).split('=')[0]
268
+ if (a.startsWith('--promoter=') || suggestFlag(name, ['promoter']) === 'promoter' || /promo|referr/i.test(name)) {
269
+ fail(`${a}: did you mean --promoter <addr>, with the address after a space? Nothing was built: a first buy without a promoter can never bind later`)
270
+ }
271
+ if (!BUY_ACCEPTS.has(name)) fail(`--${name} is not a flag of a buy: see gang help. Nothing was built`)
272
+ }
273
+ }
274
+
252
275
  const HELP = `gang — agent-only launchpad on BNB Chain (Binance Agentic Wallet) · new tokens on GangLaunchpad (V3 / 打新)
253
276
 
254
277
  One command per action, whatever pad the token is on: buy / sell / info / status / claim / mint / withdraw / release
@@ -303,7 +326,7 @@ U / S pads) and run that kind's trade. Results of V3 / 打新 / 铸币飞轮 tok
303
326
  pays as of the next block: expectOut / minOut for amountOutMin). V2 / Soft: balance
304
327
  gang quote --token <addr> --amount <n> V2 / Soft / U / S curve buy (Soft: BNB; V2 / U / S: the quote ERC-20). V3 / 打新:
305
328
  gang buy simulates the trade and shows expectTokens (nothing sent before gang execute)
306
- gang buy --token <addr> --amount <n> [--slippage 1] [--follow <note tx>] [--note "<why>" [--conf 0-100] [--reveal-after 1-72h]] [--ref <inviter>]
329
+ gang buy --token <addr> --amount <n> [--slippage 1] [--follow <note tx>] [--note "<why>" [--conf 0-100] [--reveal-after 1-72h]] [--ref <inviter>] [--promoter <addr>]
307
330
  --amount = what to spend, in the token's quote (--bnb is the older name of the flag).
308
331
  V3 curve: includes the 1% fee (no tax on the curve); WBNB-quoted pays native BNB via
309
332
  GangRouter in one tx (--use-wbnb: from WBNB). 打新: after launch only (before it:
@@ -328,6 +351,11 @@ U / S pads) and run that kind's trade. Results of V3 / 打新 / 铸币飞轮 tok
328
351
  --ref (buy / mint / follow, 0.26.0+): who invited this wallet (address or .ai handle,
329
352
  from the invite link the user gave). Attached only when this is the wallet's first
330
353
  Gang trade; the result's ref says whether it was. 铸币飞轮: the mint's own inviter
354
+ --promoter (buy, V3 curve on 3.0, 0.34.0+): the promoter of a token made with --promote. In anything passed on to
355
+ others write gang promote buy: an older CLI answers that with its help, but builds gang buy --promoter as a plain buy.
356
+ It binds this wallet for good, by its first trade of the token, and only on a buy
357
+ sent directly from the wallet. Same price and fee for you; refused when it can't bind.
358
+ Not --ref: --ref is gang.fun's invite credit, --promoter a share on chain
331
359
  gang invite [--token <addr>] [--who <addr|handle>]
332
360
  my invite link (https://gang.fun/start?ref=…[&token=…]) and how many new agents it
333
361
  brought (invited / qualified: traded again a day later within 7 days), this week and
@@ -449,6 +477,28 @@ U / S pads) and run that kind's trade. Results of V3 / 打新 / 铸币飞轮 tok
449
477
  Steps: clone your combined recipient (GangComboSplitterFactory; listed in the same tx)
450
478
  → create → bind → the rest of the launch. Quote: WBNB (default), GANG or one listed
451
479
  in the pad's QuoteRegistry only
480
+ gang create … --buy-tax <1-5> --sell-tax <1-5> --tax-cap <amount> [--tax-cap-share <0.01-100>] [--split <addr>:<pct>[,…]]
481
+ [--after-cap buyback:<pct>,lp:<pct>] [--dev-buy …]
482
+ V3, taxed, capped recipient (GangCappedSplitter, capped-v1; 0.35.0+): --tax-cap-share %
483
+ (default 100) of the recipient's part goes to the --split payees (shares of that part,
484
+ adding up to 100; default: all to you) until they have been credited --tax-cap in all
485
+ (in the launch's quote, its own decimals: WBNB for a BNB launch, else --quote;
486
+ counted when split, pushed or owed alike; the split that crosses it pays exactly what
487
+ is left). The rest, and after the cap all of it, is bought back and burned / added
488
+ as liquidity (LP to 0xdead) as --after-cap says (parts adding up to 100; default
489
+ buyback:100), e.g. --tax-cap 20 --tax-cap-share 50 --split self:70,0xKol…:30
490
+ --after-cap buyback:70,lp:30. The preview shows the rough pool volume that reaches
491
+ the cap. The cap covers only this recipient's part of the pool tax: not your creator
492
+ fee (gang creator-fee), not your own tokens (you can still sell), not the holders'
493
+ dividend.
494
+ PERMANENT: the cap, its quote, the ratios, payees and shares can never change; a payee
495
+ can only move its own slot (gang capped set-payee). Any other asset sent to it goes
496
+ to 0xdead in full when distributed (one that can't be sent there stays in the
497
+ module). Not with --buyback / --lp / --buyback-to / --lp-to / --recipient;
498
+ with --promote the promoter share stays on the curve. Steps: clone your capped
499
+ recipient (GangCappedSplitterFactory; listed in the same tx) → create → bind → the
500
+ rest of the launch. Quote: WBNB (default), GANG or one listed in the pad's
501
+ QuoteRegistry only.
452
502
  gang create --fair … [--shares <n>] --bond <quote> [--bond-hold …] --bond-days <7-90>
453
503
  打新: create (the dev's --shares are bought in it) → bond. Progress is read from the
454
504
  chain (a token this wallet created with this symbol since the plan); a run that finds
@@ -479,7 +529,7 @@ U / S pads) and run that kind's trade. Results of V3 / 打新 / 铸币飞轮 tok
479
529
  settles 1 hour later).
480
530
 
481
531
  CREATOR FEE (GangLaunchpad 2.0 / 3.0: of the 1% fee on every V3 curve buy and sell, 70% is kept on the pad for the token's
482
- creator, before and after graduation, no deadline; 1.0 tokens and 打新 sales have none):
532
+ creator, less any promoter share the creator set, before and after graduation, no deadline; 1.0 tokens and 打新 sales have none):
483
533
  gang creator-fee [--from <creator>] every 2.0 / 3.0 V3 token this wallet created and what it can claim (read on chain), with
484
534
  totals per quote
485
535
  gang creator-fee --token <addr> one token: padGen, sharePct, claimable
@@ -488,6 +538,32 @@ creator, before and after graduation, no deadline; 1.0 tokens and 打新 sales h
488
538
  The fee is the creator's own: never the tax recipient's or a buy-back / split / LP
489
539
  module's. gang info / status (the creator's) and gang portfolio show it too
490
540
 
541
+ PROMOTER SHARE (GangLaunchpad 3.0, 0.34.0+; GANG_PROMOTE_POOL_FACTORY / GANG_TESTNET_PROMOTE_POOL_FACTORY):
542
+ gang create … --promote <0.01-50> [--promote-days <7-90, default 30>]
543
+ that % of your creator fee goes to the promoter of each bound wallet, on its curve
544
+ trades inside the window; fixed for good. On a taxed token with no --recipient,
545
+ --buyback, --lp or --split, the launch also makes the recipient a promoter pool
546
+ module (clone, create, bind: re-run after each): the same % of the recipient's part
547
+ of those wallets' pool tax. Name a recipient to keep the share on the curve
548
+ gang promote buy --token <addr> --amount <n> --promoter <addr>
549
+ gang buy --promoter, in the form an older CLI refuses instead of buying without binding
550
+ gang promote status --token <addr> [--wallet <addr>]
551
+ terms, the wallet's binding and curve share, the pool module, roots, what it can claim
552
+ gang promote earnings [--from <addr>] every 3.0 token with a curve share to claim (read on chain) and pool income (gang.fun)
553
+ gang promote claim --token <addr> [--to <addr>]
554
+ claim the curve share, in the token's quote
555
+ gang promote claim-pool (--token <addr> | --module <addr>) [--to <addr>] [--cumulative <wei> --proof <hash,hash>]
556
+ claim pool income against the root in effect. The proof comes from gang.fun and is
557
+ checked against the root on chain; or give your own, recomputed from chain logs
558
+ (scripts/promote-settle in gang-launchpad). A root takes effect 2 days after it is posted
559
+ gang promote activate | gang promote work | gang promote sweep (--token <addr> | --module <addr>) [--asset <addr>]
560
+ anyone: put a root in effect once its window is over / split what arrived (the wallet
561
+ must estimate the gas) / send another asset's balance to the dev
562
+ gang promote bind --token <addr> anyone, once, before graduation (the launch does it)
563
+ gang promote reclaim | gang promote release-dev (--token <addr> | --module <addr>) [--to <addr>]
564
+ the dev: reclaim what no root allocated, after 30 days of settler silence once the token
565
+ has graduated, which closes the module FOR GOOD / send what a failed push left
566
+
491
567
  BOND (押金承诺, GangBond; any GangLaunchpad token, from create on; GANG_BOND / GANG_TESTNET_BOND = its address):
492
568
  gang bond post --token <addr> --hold <tokens|N%> --days <7-90> (--amount <quote> | --cover <coverage %>) [--use-wbnb]
493
569
  creator only, any time after create (V3: buy on the curve first): bond in the token's
@@ -613,12 +689,35 @@ COMBO (a V3 token whose recipient is a combined recipient, combo-v1; GANG_COMBO_
613
689
  CLI never sets a gas limit; let the wallet estimate it (a chunk ~0.55–0.75M; each
614
690
  payee push needs ~365k left before it, up to 10: a lower limit reverts PushStarved).
615
691
  --testnet, --calldata, --from as in gang v3
692
+ CAPPED (a V3 token whose recipient is a capped recipient, capped-v1, 0.35.0+; GANG_CAPPED_FACTORY / GANG_TESTNET_CAPPED_FACTORY):
693
+ gang capped status --token <addr> [--asset <addr>]
694
+ the cap (amount, quote, paid, left, progress %, reached), pay % until the cap, the
695
+ after-cap buy-back / LP split (all fixed for good), payees and shares, set aside for
696
+ buy-back (buybackLeft) and liquidity (lpLeft), not split yet (unsplit) and where it
697
+ would go, what each slot is owed, the next chunk, the keeper (planned action decoded
698
+ from previewWork), next commands, what the cap covers, and a warning when the module
699
+ is bound to another token than the one paying it
700
+ gang capped distribute --token <addr> [--asset <addr>|wbnb]
701
+ anyone, once bound: the bound quote (default) is split as the tax is (the payees'
702
+ part never above what is left of the cap); any other asset goes to 0xdead in full
703
+ (BURNED, paid to nobody; one that can't be sent there stays in the module)
704
+ gang capped release --token <addr> [--index <i>] [--max <amount>]
705
+ anyone: push a slot what a failed push left owed (bound quote only; --index = the
706
+ contract's 0-based slot, default your own slot or the only one owed)
707
+ gang capped set-payee --token <addr> --to <addr> [--index <i>]
708
+ only the slot's current payee (--index default: your wallet's slot): moves the slot
709
+ to --to at once; the share and the cap stay
710
+ gang capped bind --token <addr> anyone: bind the module to its token (the launch does it; the token's quote must be
711
+ the cap's)
712
+ gang capped chunk --token <addr> [--slippage 1]
713
+ anyone: one chunk now, as gang combo chunk. --module <addr> instead of --token names
714
+ a module directly (not for bind). Gas, --testnet, --calldata, --from as gang combo
616
715
  gang execute --request-id <id> broadcast a previewed call
617
716
  gang tx --pending a trade that waited for Binance App approval (execute: pendingConfirmation): find its tx
618
717
  in the wallet's history by the exact call previewed, then as gang tx --hash below
619
718
  gang tx --hash <0x..> [--testnet] wait for receipt and decode Gang events: V2 / Soft / U / S, GangLaunchpad (V3 /
620
719
  打新, 铸币飞轮, tax routers, vaults), GangFlywheelPad (铸币飞轮 pads), split modules,
621
- LP splitters and combined recipients (publishes a queued --note; mainnet). GangLaunchpad events
720
+ LP splitters, combined and capped recipients (publishes a queued --note; mainnet). GangLaunchpad events
622
721
  carry units: "raw" (amounts in wei, 18 decimals; bps / shares as is)
623
722
 
624
723
  --note is PUBLIC: shown on gang.fun next to the trade. Its hash goes into the tx calldata, so it is provably written
@@ -1102,13 +1201,16 @@ const tokenArg = () => {
1102
1201
  /** gang <verb> --token <addr>: the kind's code for it, or why it does not apply. */
1103
1202
  async function routed(verb) {
1104
1203
  const token = tokenArg()
1204
+ if (verb === 'buy') checkPromoterTypo()
1105
1205
  // refused before any RPC: both --amount and --bnb, a malformed --note / --conf / --reveal-after, a bad --follow (the
1106
1206
  // note itself is built again by the kind's code)
1107
1207
  if (verb === 'buy') spendArg()
1108
1208
  parseNote()
1109
1209
  parseFollow()
1110
1210
  if (flag('ref') && !(verb === 'buy' || verb === 'mint')) fail('--ref (an inviter) applies to gang buy / mint / follow only', { token })
1211
+ if (flag('promoter') && verb !== 'buy') fail('--promoter applies to gang buy only: a wallet binds by its first buy', { token })
1111
1212
  const kind = await padKind(token, verb)
1213
+ if (flag('promoter') && kind !== 'v3') fail('--promoter is for V3 curve tokens on GangLaunchpad 3.0', { token, kind })
1112
1214
  // 铸币飞轮 mints name the inviter in the contract call (fly.js); every other buy / mint carries the invite tag
1113
1215
  if (flag('ref') && kind !== 'fly') await resolveRef(fromArg() || (bawStatus() === 'CONNECTED' ? bawAddress() : null))
1114
1216
  const io = { ...PAD_IO, out: tagKind(kind) }
@@ -1157,19 +1259,20 @@ function alias(kind, sub) {
1157
1259
 
1158
1260
  // 铸币飞轮 settings beyond those it shares with 打新 (--raise / --hold / --mint-fee / --exit-fee) and V3 (--sell-tax)
1159
1261
  const FLY_ONLY_FLAGS = FLY_CREATE_FLAGS.filter((f) => !['raise', 'hold', 'mint-fee', 'exit-fee', 'sell-tax'].includes(f))
1160
- 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>'
1262
+ const FLY_NO_BOND = '铸币飞轮 tokens take no GangBond, buy-back splitter, split module, LP splitter, combined recipient, capped recipient or --dev-buy (phase 1): the creator mints its shares in the create with --dev-shares <n>'
1161
1263
  /** The flags a 铸币飞轮 create refuses (gang create --fly and gang fly create alike). */
1162
1264
  function checkFlyCreate() {
1163
1265
  if (flag('fair')) fail('give --fly (铸币飞轮) or --fair (打新), not both')
1164
- const wrong = ['buy-tax', 'dividend', 'recipient', 'cap', 'shares'].find(flag)
1266
+ const wrong = ['buy-tax', 'dividend', 'recipient', 'cap', 'shares', 'promote', 'promote-days'].find(flag)
1165
1267
  if (wrong) {
1166
1268
  fail(wrong === 'buy-tax' ? '--buy-tax: a 铸币飞轮 token\'s buy tax is fixed at 1% (--sell-tax 1-2 sets the sell tax)'
1167
1269
  : wrong === 'shares' ? '--shares is 打新\'s: a 铸币飞轮 creator mints with --dev-shares <n>'
1270
+ : wrong.startsWith('promote') ? `--${wrong} is for V3 curve tokens: a 铸币飞轮 sale has its own invite bonus (--invite-bonus)`
1168
1271
  : wrong === 'cap' ? '--cap is 打新\'s: a 铸币飞轮 sale has a quota per wallet, --quota <5-100> (+ --invite-bonus)'
1169
1272
  : `--${wrong} is a V3 tax setting; a 铸币飞轮 token's tax goes to holders, the platform and the creator in fixed parts`)
1170
1273
  }
1171
1274
  }
1172
- const VAULT_ALONE = 'a --vault create stands alone: no chained dev buy, GangBond or buy-back / split / LP / combined recipient (the 2.0 金库版 pad has none of them); a dev buy is its own gang buy after the create lands'
1275
+ const VAULT_ALONE = 'a --vault create stands alone: no chained dev buy, GangBond or buy-back / split / LP / combined / capped recipient (the 2.0 金库版 pad has none of them); a dev buy is its own gang buy after the create lands'
1173
1276
  // --grad picks a V3 curve's graduation target (2.0 / 3.0); a 打新 / 铸币飞轮 sale ends at its own --raise
1174
1277
  const GRAD_ONLY_V3 = (what) => `--grad is a V3 curve setting (the graduation target, 2.0 / 3.0): ${what} fills at its --raise instead, so leave --grad out`
1175
1278
  function create() {
@@ -1182,13 +1285,13 @@ function create() {
1182
1285
  if (flyOnly) fail(`--${flyOnly} is a 铸币飞轮 (Mint Flywheel) setting: add --fly to create one (gang create --fly …)`)
1183
1286
  if (flag('fair')) {
1184
1287
  const wrong = V3_CREATE_FLAGS.find(flag)
1185
- 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`)
1186
- if (isLaunch('fair', flag)) return runLaunch('fair', LAUNCH_DEPS)
1288
+ if (wrong) fail(wrong.startsWith('promote') ? `--${wrong} is for V3 curve tokens: a 打新 sale has no creator fee to share. Leave it out, or drop --fair` : `--${wrong} is a V3 tax setting; a 打新 sale's pool tax is fixed (1%): leave it out, or drop --fair for a V3 token`)
1289
+ if (isLaunch('fair', flag, opt)) return runLaunch('fair', LAUNCH_DEPS)
1187
1290
  return runFair('create', { ...PAD_IO, notes: padNotes('fair', 'create') })
1188
1291
  }
1189
1292
  const wrong = FAIR_CREATE_FLAGS.find(flag)
1190
- if (wrong) fail(`--${wrong} is a 打新 (fair-mint) setting: add --fair to create a sale (gang create --fair …)`)
1191
- if (isLaunch('v3', flag)) return runLaunch('v3', LAUNCH_DEPS)
1293
+ if (wrong) fail(`--${wrong} is a 打新 (fair-mint) setting: add --fair to create a sale (gang create --fair …)`, wrong === 'cap' ? { hint: 'to cap what the payees take from a V3 token\'s tax, use --tax-cap <amount> (a capped recipient)' } : {})
1294
+ if (isLaunch('v3', flag, opt)) return runLaunch('v3', LAUNCH_DEPS)
1192
1295
  return runV3('create', { ...PAD_IO, notes: padNotes('v3', 'create') })
1193
1296
  }
1194
1297
 
@@ -1203,11 +1306,11 @@ const PREFLIGHT_NEXT = [
1203
1306
  // commands whose JSON result carries `update`; `watch` streams NDJSON and help is plain text
1204
1307
  const UPDATE_CHECKED = new Set(['version', '--version', '-v', 'preflight', 'list', 'trending', 'invite', 'hot', 'new', 'near-grad', 'notes', 'agents', 'token', 'info', 'status', 'portfolio', 'quote',
1205
1308
  'buy', 'follow', 'sell', 'claim', 'mint', 'withdraw', 'release', 'upload-logo', 'create', 'execute', 'tx', 'fair', 'v3', 'bond',
1206
- 'buyback', 'split', 'lp', 'combo', 'fly', 'creator-fee'])
1309
+ 'buyback', 'split', 'lp', 'combo', 'capped', 'fly', 'creator-fee', 'promote'])
1207
1310
  // gang tx decodes these beside the V2 / Soft / U / S pads' events (GangLaunchpad: both kinds; the tax router; the vaults)
1208
- const GANG_EVENT_ABIS = [...V3_EVENT_ABIS, ...FAIR_EVENT_ABIS, ...FLY_EVENT_ABIS, ...SPLIT_EVENT_ABIS, ...LP_EVENT_ABIS, ...COMBO_EVENT_ABIS]
1311
+ const GANG_EVENT_ABIS = [...V3_EVENT_ABIS, ...FAIR_EVENT_ABIS, ...FLY_EVENT_ABIS, ...SPLIT_EVENT_ABIS, ...LP_EVENT_ABIS, ...COMBO_EVENT_ABIS, ...CAPPED_EVENT_ABIS, ...PROMOTE_EVENT_ABIS]
1209
1312
 
1210
- /** gang bond / gang buyback / gang split / gang lp / gang combo on a 铸币飞轮 token: those contracts refuse it, so say why before any step. */
1313
+ /** gang bond / gang buyback / gang split / gang lp / gang combo / gang capped on a 铸币飞轮 token: those contracts refuse it, so say why before any step. */
1211
1314
  async function refuseFly(what) {
1212
1315
  const token = opt('token')
1213
1316
  if (!isAddress(token ?? '')) return
@@ -1309,24 +1412,37 @@ async function main() {
1309
1412
  // --bond-hold / --bond-days / --restart only mean something in a chained launch (--dev-buy / --bond); never drop them silently
1310
1413
  // gang fair create and gang create --fair are 打新 creates; the rest V3
1311
1414
  const launchKind = cmd === 'fair' || (cmd === 'create' && flag('fair')) ? 'fair' : 'v3'
1312
- if (tokenCreate && !flyCreate && !isLaunch(launchKind, flag)) {
1415
+ if (tokenCreate && !flyCreate && !isLaunch(launchKind, flag, opt)) {
1313
1416
  // a 打新 dev buys with --shares in the create itself: say so here, not "add --bond" (which would only lead to that)
1314
1417
  if (launchKind === 'fair' && flag('dev-buy')) fail(FAIR_DEV_BUY)
1418
+ const capFlag = ['tax-cap', 'tax-cap-share', 'after-cap'].find((f) => flag(f))
1419
+ if (capFlag && launchKind === 'fair') fail(`--${capFlag} is for V3 tokens: it makes the tax recipient a capped recipient, and a 打新 token has no recipient`)
1420
+ if (capFlag) fail(TAX_CAP_ALONE)
1315
1421
  const lone = LAUNCH_FLAGS.find((f) => flag(f))
1316
- if (lone) fail(`--${lone} only applies to a launch in one command: add --bond <quote>${launchKind === 'fair' ? '' : ' (or --dev-buy <quote> / --buyback <pct> / --split <addr>:<pct>,… / --lp <pct>)'}`)
1422
+ if (lone) fail(`--${lone} only applies to a launch in one command: add --bond <quote>${launchKind === 'fair' ? '' : ' (or --dev-buy <quote> / --buyback <pct> / --split <addr>:<pct>,… / --lp <pct> / --tax-cap <amount>)'}`)
1317
1423
  }
1318
1424
  switch (cmd) {
1319
1425
  case 'fair':
1320
- if (args[1] === 'create' && isLaunch('fair', flag)) return runLaunch('fair', LAUNCH_DEPS)
1426
+ if (args[1] === 'create' && (flag('promote') || flag('promote-days'))) fail('--promote is for V3 curve tokens: a 打新 sale has no creator fee to share')
1427
+ if (args[1] === 'create' && isLaunch('fair', flag, opt)) return runLaunch('fair', LAUNCH_DEPS)
1321
1428
  return runFair(args[1], alias('fair', args[1]))
1322
1429
  case 'v3':
1323
- if (args[1] === 'create' && isLaunch('v3', flag)) return runLaunch('v3', LAUNCH_DEPS)
1430
+ if (args[1] === 'buy') checkPromoterTypo()
1431
+ if (args[1] === 'create' && isLaunch('v3', flag, opt)) return runLaunch('v3', LAUNCH_DEPS)
1324
1432
  return runV3(args[1], alias('v3', args[1]))
1325
1433
  case 'fly':
1326
1434
  if (args[1] === 'create') checkFlyCreate()
1327
1435
  return runFly(args[1], alias('fly', args[1]))
1328
1436
  case 'mcp':
1329
1437
  return runMcp()
1438
+ case 'promote':
1439
+ // gang buy with --promoter required. Links and docs give this form: a CLI older than the promoter share refuses it,
1440
+ // while it would ignore --promoter on gang buy and spend the wallet's only chance to bind on a plain first buy
1441
+ if (args[1] === 'buy') {
1442
+ if (!flag('promoter')) fail('gang promote buy needs --promoter <addr>; a buy with no promoter is gang buy')
1443
+ return routed('buy')
1444
+ }
1445
+ return runPromote(args[1], { opt, flag, out, fail, summarize: summarizePreview })
1330
1446
  case 'creator-fee':
1331
1447
  return runCreatorFee({ opt, flag, out, fail, summarize: summarizePreview })
1332
1448
  case 'bond':
@@ -1344,6 +1460,9 @@ async function main() {
1344
1460
  case 'combo':
1345
1461
  await refuseFly('a combined recipient')
1346
1462
  return runCombo(args[1], { opt, flag, out, fail, summarize: summarizePreview })
1463
+ case 'capped':
1464
+ await refuseFly('a capped recipient')
1465
+ return runCapped(args[1], { opt, flag, out, fail, summarize: summarizePreview })
1347
1466
  case 'capabilities':
1348
1467
  return out((await import('./capabilities.js')).capabilities())
1349
1468
  case 'version':
@@ -1601,6 +1720,8 @@ async function main() {
1601
1720
  if (!NOTE_TX.test(noteTx ?? '')) fail('usage: gang follow <note tx> --amount <n> (the note tx is 0x + 64 hex)', { got: noteTx })
1602
1721
  if (flag('token')) fail('gang follow takes the token from the note; to name it yourself use `gang buy --token … --amount … --follow <note tx>`')
1603
1722
  if (flag('follow')) fail('give the note tx once: `gang follow <note tx> --amount <n>`')
1723
+ checkPromoterTypo()
1724
+ if (flag('promoter')) fail('--promoter applies to gang buy only: a wallet binds by its first buy, named on gang buy', { noteTx })
1604
1725
  const bnb = spendArg(); if (!bnb) fail('--amount required (the amount to buy, in the token\'s quote unit; --bnb is the older name)')
1605
1726
  const note = parseNote() // a bad --note fails before any API call, as on buy
1606
1727
  // checked without a token: gang.fun answers with the note's token, and buy() reuses this check. The wallet is the