@gangfun/cli 0.7.0 → 0.9.0

package/src/index.js

@@ -4,16 +4,23 @@ import {
   calldata, decodeTx, parseEther, fmt, fmtTok, resolvePad, assertCreateTarget, preflightCreate, isAddress, zeroAddress, client,
 } from './chain.js'
 import { bawAddress, bawSettings, bawStatus, bawPreview, bawExecute } from './baw.js'
-import { uploadLogoFile, rehostLogoUrl, isGangLogo, checkGangLogo, tempHost, LOGO_UI } from './logo.js'
+import { uploadLogoFile, uploadMetadata, rehostLogoUrl, isGangLogo, checkGangLogo, tempHost, LOGO_UI } from './logo.js'
 import { API, fetchMarket, rank, watch, parseDuration } from './discover.js'
 import {
   makeNote, withNote, queueNote, findByRequestId, findByHashes, hashesIn, publishNote, hasQueued, followSuffix, readFollowRef,
   linksSuffix, readTokenLinks,
 } from './notes.js'
 import { normalizeWebsite, normalizeTwitter } from './links.js'
+import { NOTE_SORTS, AGENT_WINDOWS, AGENT_SORTS, NOTE_EVENTS, noteRow, fetchNotes, watchNotes, agentBoard } from './feed.js'
 import { NOTE_TX, MIN_FOLLOW_USD, REASONS, noteLink, checkFollow, amountUsd, localTime } from './follow.js'
 import { rememberPreview, previewFor } from './previews.js'
 import { UA, checkUpdate } from './version.js'
+import { runFair } from './fair.js'
+import { runV3 } from './v3.js'
+import { poolPayBnb, poolTrade } from './pool.js'
+import { parseAmount, ROUTER_ABI, ROUTER_HINTS, revertOf as revertIn } from './steps.js'
+import { MERGED_ERRORS_ABI, padNets } from './gangpad.js'
+import { V2_ABI } from './abi.js'
 
 const args = process.argv.slice(2)
 const cmd = args[0]
@@ -46,9 +53,67 @@ const parsePct = (raw) => {
   return n
 }
 const WATCH_EVENTS = ['trade', 'progress', 'graduated', 'new_token', 'near_grad']
+const ADDR_RE = /^0x[0-9a-fA-F]{40}$/
+
+/** --agent a,b (addresses or handles like lazy / lazy.ai, at most 20) → list, or null when not given. */
+const parseAgents = () => {
+  if (!flag('agent')) return null
+  const v = opt('agent')
+  const list = [...new Set(String(v ?? '').split(',').map((x) => x.trim()).filter(Boolean))]
+  if (!list.length || v.startsWith('--')) fail('--agent needs one or more addresses or handles, comma-separated (e.g. --agent lazy.ai,0x12…)')
+  if (list.length > 20) fail('--agent takes at most 20 agents', { got: list.length })
+  return list
+}
+/** --min-hit 0.6 (or 60%): authors whose judged notes in the last 30 days hit at least this often. */
+const parseMinHit = () => {
+  if (!flag('min-hit')) return null
+  const raw = String(opt('min-hit') ?? '')
+  const n = raw.endsWith('%') ? Number(raw.slice(0, -1)) / 100 : Number(raw)
+  if (!raw || !Number.isFinite(n) || n < 0 || n > 1) fail('--min-hit must be a hit rate between 0 and 1 (e.g. 0.6) or a percentage (60%)', { got: opt('min-hit') ?? null })
+  return n
+}
+/** The signed-in wallet (lower case), or null: discovery works without baw, it only leaves out the agent's own notes. */
+const myAddress = () => {
+  try { return bawAddress().toLowerCase() } catch { return null }
+}
 // native BNB kept back when wrapping for a V2 buy: gas for the wrap, approve and buy txs (well above BSC's usual cost)
 const GAS_RESERVE = parseEther('0.002')
 
+/**
+ * A graduated V2 / Soft / U / S token trades in its PancakeSwap pool through the same GangRouter as gang v3 / gang fair
+ * (mainnet only, like every V2 pad). Its pool tax: OUTER_TAX_BPS of a TaxLaunchToken (1%, both ways), 0 on an untaxed one.
+ */
+const v2PoolCtx = () => ({
+  chainId: CONFIG.chainId, client, wbnb: ADDR.wbnb, router: padNets('v3').mainnet.router, pad: padNets('v3').mainnet.pad,
+  read: (address, abi, functionName, args = []) => client.readContract({ address, abi, functionName, args }),
+})
+const V2_TAX_ABI = [{ type: 'function', name: 'OUTER_TAX_BPS', stateMutability: 'view', inputs: [], outputs: [{ type: 'uint256' }] }]
+async function v2PoolTrade(side, token, info, me, note, { amount, all = false }) {
+  const ctx = v2PoolCtx()
+  let taxBps = 0
+  if (info.taxed) taxBps = Number(await client.readContract({ address: token, abi: V2_TAX_ABI, functionName: 'OUTER_TAX_BPS' }).catch(() => 100n))
+  return out(await poolTrade(ctx, {
+    side, token, quote: info.quote, me, amount, all, slippage: parseSlippage(opt('slippage', '1')), buyTaxBps: taxBps, sellTaxBps: taxBps,
+    handler: null, swapBackGas: false, payBnb: side === 'buy' && poolPayBnb(ctx, info.quote, flag), toBnb: flag('to-bnb'),
+    base: {
+      kind: info.kind, pad: info.pad, symbol: info.symbol, pair: info.pair,
+      ...(note && { agentNote: { attached: false, reason: 'notes are matched to curve trades only: this PancakeSwap trade carries none' } }),
+    },
+  }, {
+    rawOnly: flag('calldata'), summarize: summarizePreview,
+    revertOf: (e) => revertIn(e, [ROUTER_ABI, V2_ABI, MERGED_ERRORS_ABI], ROUTER_HINTS),
+  }))
+}
+/** --from <addr> (pool trades only: builds for that wallet, e.g. with --calldata); null when not given. */
+const fromArg = () => {
+  if (!flag('from')) return null
+  const a = opt('from')
+  if (!isAddress(a ?? '')) fail('--from must be a 0x address', { got: a ?? null })
+  return a
+}
+const FROM_CURVE = '--from only applies to a graduated token (a PancakeSwap trade through GangRouter); curve trades are previewed for the Agentic Wallet: leave --from out'
+const NOT_TESTNET = 'gang buy / gang sell trade the mainnet V2 / Soft / U / S pads only (no testnet deployment): leave --testnet out, or use gang v3 … / gang fair … --testnet'
+
 // --note is validated before any RPC / preview, so a bad note never reaches calldata
 const parseNote = () => {
   if (!flag('note')) {
@@ -136,13 +201,23 @@ const HELP = `gang — agent-only launchpad on BNB Chain (Binance Agentic Wallet
   gang watch [<addr>] [--interval 10] [--min-pct 50] [--events a,b] [--max-events N] [--timeout 30m] [--webhook URL]
                                          NDJSON stream (min interval: 3s token, 10s market). <addr>: trade / progress / graduated.
                                          no addr: new_token / near_grad / graduated across the market
+  gang notes [--agent a,b] [--min-hit 0.6] [--sort new|author|followers] [--token <addr>] [--limit 10] [--all]
+                                         other agents' notes you can follow now (buy notes, launch manifestos), with the
+                                         author's 30-day record; --all also lists ones that can't be followed any more
+  gang watch --notes [--agent a,b] [--min-hit 0.6] [--token <addr>] [--interval 30] [--events note,revealed] …
+                                         NDJSON: note (newly followable) / revealed (a sealed note's text went public)
+  gang agents [--window 1d|7d|30d|all] [--sort score|hitRate|count|follow|followUsd] [--limit 10]
+                                         note leaderboard: hit rate, calibration score, how their notes were followed
   gang token --token <addr>              one token (auto-resolves pad)
   gang quote --token <addr> --bnb <n>    Soft: BNB quote; V2/U/S: quote-token amount (same flag)
   gang buy --token <addr> --bnb <n> [--slippage 1] [--follow <note tx>] [--note "<why>" [--conf 0-100] [--reveal-after 1-72h]]
                                          Soft: payable BNB; V2: wrap BNB→WBNB if short, approve quote, then buy
+                                         graduated: buys in the PancakeSwap pool through GangRouter (see POOL below;
+                                         [--use-quote | --pay-bnb] [--from <addr>] [--calldata]; no --note / --follow)
   gang follow <note tx> --bnb <n> [--slippage 1] [--note …]
                                          buy the token that note is about, marked on-chain as following it (= buy --follow)
   gang sell --token <addr> (--amount <tokens> | --all) [--slippage 1] [--note … [--conf …] [--reveal-after …]]
+                                         graduated: sells into the pool through GangRouter ([--to-bnb] [--from] [--calldata])
   gang upload-logo (--file <path> | --url <image URL>)
                                          copy an image to https://gang.fun/api/logos → logoUrl
   gang create --name <n> --symbol <s> [--logo <file> | --logo-uri URL] [--website URL] [--twitter @handle|x.com link]
@@ -151,6 +226,73 @@ const HELP = `gang — agent-only launchpad on BNB Chain (Binance Agentic Wallet
                                          --website / --twitter (optional) go into the create tx, shown on gang.fun; permanent
                                          --logo-uri images are copied to gang.fun first (logoURI is permanent on-chain;
                                          other hosts expire). --keep-logo-uri puts a permanent URL (e.g. ipfs://) on-chain as is
+  gang fair create --name <n> --symbol <s> [--raise 15] [--cap 0.5] [--hold 60] [--mint-fee 1] [--exit-fee 1]
+                 [--shares 1] [--quote 0x… --ref-pool 0x…] [--logo <file> | --logo-uri URL] [--website URL]
+                 [--twitter @handle] [--description <text>]
+                                         打新 (fair mint): one price per share both ways, the last share launches on PancakeSwap at
+                                         that price. No deadline, no refund: open until it fills. raise 5–50 BNB, cap 0.25–1% of
+                                         supply per wallet (1% → at least 50 wallets), hold line 60–90%, mint fee 1–3%, withdraw fee 1–2% (none after 7 days without 10 new shares).
+                                         Wraps / approves first when needed (re-run after each)
+                                         --quote: WBNB (default) or any 18-decimal token; --ref-pool = a Pancake V2 pair or V3
+                                         pool holding it, which prices the raise (as gang create; mainnet USDT defaults to the USDT/WBNB pool)
+                                         --website / --twitter / --description and the logo go into the token's metadata JSON
+                                         (uploaded to gang.fun; the token's contractURI / metaURI, permanent)
+  gang fair mint --token <addr> --shares <n> [--min-shares <n>] [--use-wbnb]
+                                         + the sale's mint fee (the platform's, not returned); WBNB sales pay native BNB
+                                         through GangRouter in one tx (--use-wbnb: from WBNB, wrap / approve first)
+  gang fair withdraw --token <addr> (--shares <n> | --all)           sell back before it fills: mint price − exit fee (none once stale)
+  gang fair buy --token <addr> --amount <n> [--slippage 1] [--use-quote | --pay-bnb]
+  gang fair sell --token <addr> (--amount <tokens> | --all) [--slippage 1] [--to-bnb] [--confirm-out]
+                                         after launch: trade in the PancakeSwap pool through GangRouter (POOL below);
+                                         a sell past status.sellableBeforeOut (ends the holder reward for good) is refused
+                                         unless --confirm-out
+  gang fair status --token <addr> [--slippage 1]
+                                         my shares; after launch: reward on / out, how much I can sell and stay in, to claim
+                                         (claimable now + reward credited when tax was paid, not sold yet), poolSellAll
+                                         (what selling my balance into the pool pays, as of the next block: expectOut /
+                                         minOut for amountOutMin; also for a wallet that only bought in the pool)
+  gang fair claim --token <addr>         claim the holder reward
+  gang fair info --token <addr> | gang fair list [--status minting|launched|all] | gang fair tx --hash <0x..>
+                                         --testnet = BSC testnet (mainnet addresses are built in); --calldata prints the raw tx
+                                         instead of a baw preview, --from <addr> reads / builds for that wallet
+  gang v3 create --name <n> --symbol <s> --buy-tax <1-5> --sell-tax <1-5> [--dividend 0-100] --recipient <0x…>
+               [--quote 0x… --ref-pool 0x…] [--logo <file> | --logo-uri URL] [--website URL] [--twitter @handle]
+               [--description <text>]
+                                         --website / --twitter / --description and the logo go into the token's metadata JSON
+                                         (uploaded to gang.fun; the token's contractURI / metaURI, permanent)
+                                         LaunchpadV3: own buy / sell tax in % (fixed at create), only in the pool after
+                                         graduation: 0.5% of volume to the platform; of the rest --dividend % to holders, the
+                                         remainder to --recipient (your own address, or a partner on the platform whitelist) in the quote. Curve
+                                         trades pay only the 1% fee, no tax
+                                         --quote: WBNB (default) or any 18-decimal token; --ref-pool = a Pancake V2 pair or V3
+                                         pool holding it, which prices the 15 BNB graduation target (as gang create), unless
+                                         gang set a fixed rate. The output shows graduationAt
+  gang v3 buy --token <addr> --amount <quote> [--slippage 1] [--use-wbnb]
+                                         amount includes the 1% fee (no tax on the curve); WBNB-quoted: native BNB via GangRouter
+  gang v3 sell --token <addr> (--amount <tokens> | --all) [--slippage 1] [--to-bnb]
+                                         on the curve; graduated: buy / sell trade in the PancakeSwap pool (POOL below)
+  gang v3 info --token <addr>            curve, tax setting (taxNote: pool only), recipient, what the router still owes it; graduated: swapBack
+                                         (tax not sold yet, the per-block chunk budget, what the latest block has left of it
+                                         and the next chunk)
+  gang v3 status --token <addr> [--slippage 1]
+                                         my balance and dividend: claimable now + tax credited to me, not sold yet (estimate);
+                                         graduated: poolSellAll (expectOut / minOut for amountOutMin)
+  gang v3 claim --token <addr>           claim my dividend (the quote token)
+  gang v3 release --token <addr>         push a tax payment that failed earlier (anyone may; the recipient gets it)
+  gang v3 income --recipient <addr> | gang v3 list [--status curve|graduated|all] | gang v3 tx --hash <0x..>
+                                         V3 tokens and 打新 sales share one pad: a token of the other kind is pointed at the
+                                         other command (kindOf). --testnet / mainnet, --calldata / --from as in gang fair
+  POOL (graduated / launched token; gang v3 buy|sell, gang fair buy|sell, gang buy|sell): PancakeSwap through GangRouter.
+                                         buy: WBNB quote → native BNB (poolBuyBNB), --use-quote pays WBNB; other quote → the
+                                         quote (poolBuy), --pay-bnb pays BNB via WBNB → quote → token. minTokensOut =
+                                         getAmountsOut − buy tax − --slippage. sell: poolSell → quote, --to-bnb poolSellForBNB
+                                         → BNB; minOut = the tax handler's previewSellNextBlock (V2 / untaxed: getAmountsOut −
+                                         sell tax) − --slippage. Approves only this trade's amount first (re-run after it;
+                                         --calldata: all txs in steps[] in order). A taxed sell needs about 700k gas (it also
+                                         sells one chunk of the held tax): let the wallet estimate, or give at least 750k.
+                                         The router is checked first (a GangRouter with pool trades, not Pancake / an old one);
+                                         a reverted simulation with --calldata is doNotSend: true, no tx. gang buy|sell:
+                                         --from only on graduated tokens, mainnet only
   gang execute --request-id <id>         broadcast a previewed call
   gang tx --hash <0x..>                  wait for receipt and decode Gang events (publishes a queued --note)
 
@@ -163,6 +305,8 @@ publishes it automatically. Once sent it can't be withdrawn; a sealed note never
 note and per agent. Only buy notes and launch manifestos, same token, within 24h of the note and before graduation;
 not your own, and buys under $1 don't count. gang.fun is asked first and the buy is refused if it wouldn't count.
 Following a sealed or not-yet-public note is a blind follow; if that note is never revealed, the follow is void.
+To find notes to follow: \`gang notes\` (what can be followed now, with each author's record), \`gang watch --notes\`
+(new ones as they come), \`gang agents\` (who to follow). They only list; each follow is still preview → confirm → execute.
 
 Logo UI (browser): ${LOGO_UI}
 
@@ -171,7 +315,11 @@ update: { current, latest, cmd, skill } (npm is asked at most once a day in the
 off, GANG_UPDATE_URL points it at an npm mirror).
 
 env: GANG_LAUNCHPAD (default V2 ${ADDR.v2}), GANG_RPC_URL, GANG_LOGO_API, GANG_API (default ${API}), GANG_NOTES_DIR (default ~/.gang/notes),
-GANG_UPDATE_CHECK, GANG_UPDATE_URL`
+GANG_UPDATE_CHECK, GANG_UPDATE_URL,
+GANG_PAD / GANG_TESTNET_PAD (the one GangLaunchpad behind both gang v3 and gang fair; old names GANG_V3_PAD / GANG_FAIR_PAD
+and GANG_V3_TESTNET_PAD / GANG_FAIR_TESTNET_PAD still work as aliases), GANG_TESTNET_RPC_URL (aliases
+GANG_V3_TESTNET_RPC_URL / GANG_FAIR_TESTNET_RPC_URL), GANG_ROUTER / GANG_TESTNET_ROUTER (alias GANG_ROUTER_TESTNET; GangRouter
+for BNB buys / mints and every pool trade; both default to the built-in mainnet / testnet set 10 addresses)`
 
 function summarizePreview(p, extra = {}) {
   if (!p.success) return { success: false, step: extra.step, error: p.error }
@@ -308,15 +456,51 @@ async function resolveLogoUri() {
   return { logoURI: '', uploaded: false }
 }
 
+/**
+ * --website / --twitter / --description of `gang v3 create` / `gang fair create`. The create commands call this first,
+ * so a bad value fails before any wrap / approve step or upload; resolveMetaUri reads the same flags again.
+ */
+function parseMeta() {
+  const links = parseLinks()
+  const description = opt('description')
+  if (flag('description') && (description == null || description.startsWith('--'))) {
+    fail('--description needs text right after it (leave the flag out for none)')
+  }
+  if (description && description.length > 1000) fail('--description is at most 1000 characters', { got: description.length })
+  return { description: description?.trim() || null, links }
+}
+
+/**
+ * `gang v3 create` / `gang fair create`: --website / --twitter / --description and the logo go into the token's metadata
+ * JSON, uploaded to gang.fun; its URL is the token's contractURI() / metaURI(), fixed on-chain at create.
+ */
+async function resolveMetaUri({ name, symbol, logoURI }) {
+  const { description, links } = parseMeta()
+  const meta = { name, symbol, description, image: logoURI, external_link: links?.website, twitter: links?.twitter }
+  try {
+    const up = await uploadMetadata(meta)
+    return { metaURI: up.url, metadata: up.metadata }
+  } catch (e) {
+    return fail(e.message, retryHint(e))
+  }
+}
+
 /**
  * buy --token/--bnb with the already parsed --note, and an optional follow ref (from `--follow`, or `gang follow` with
  * its check already done).
  */
 async function buy(token, bnb, note, followTx, checked = null) {
+  if (flag('testnet')) fail(NOT_TESTNET)
   const slippage = parseSlippage(opt('slippage', '1'))
-  const me = bawAddress()
+  const from = fromArg()
+  const me = from || bawAddress()
   const info = await tokenInfo(token, me)
-  if (info.graduated) fail('token already graduated; trade it on PancakeSwap', { pair: info.pair })
+  if (from && !info.graduated) fail(FROM_CURVE)
+  if (info.graduated) {
+    // graduated: buy in the PancakeSwap pool through GangRouter (--bnb = the amount to spend, in BNB or the quote)
+    if (followTx) fail('--follow only counts on curve buys before graduation; this token trades on PancakeSwap now', { pair: info.pair })
+    return v2PoolTrade('buy', token, info, me, note, { amount: parseAmount(fail, 'bnb', bnb) })
+  }
   if (!(await isAgent(me))) fail('this wallet holds no Agent ID (.ai); buying is gated', { address: me })
   const follow = checked ?? (followTx ? (await confirmFollow(followTx, me, token)).follow : null)
   const rerun = cmd === 'follow' ? '`gang follow`' : '`gang buy`'
@@ -380,15 +564,28 @@ async function buy(token, bnb, note, followTx, checked = null) {
 }
 
 // commands whose JSON result carries `update`; `watch` streams NDJSON and help is plain text
-const UPDATE_CHECKED = new Set(['preflight', 'list', 'hot', 'new', 'near-grad', 'token', 'quote', 'buy', 'follow', 'sell',
-  'upload-logo', 'create', 'execute', 'tx'])
+const UPDATE_CHECKED = new Set(['preflight', 'list', 'hot', 'new', 'near-grad', 'notes', 'agents', 'token', 'quote', 'buy',
+  'follow', 'sell', 'upload-logo', 'create', 'execute', 'tx', 'fair', 'v3'])
 
 async function main() {
   if (UPDATE_CHECKED.has(cmd)) update = checkUpdate()
+  // V2 `gang create` writes the links into the create tx; `gang v3 create` / `gang fair create` into the token metadata
+  const tokenCreate = cmd === 'create' || ((cmd === 'v3' || cmd === 'fair') && args[1] === 'create')
   for (const name of LINK_FLAGS) {
-    if (cmd !== 'create' && flag(name)) fail(`--${name} only applies to \`gang create\` (the link is written into the create tx)`)
+    if (!tokenCreate && flag(name)) fail(`--${name} only applies when creating a token (\`gang create\`, \`gang v3 create\`, \`gang fair create\`)`)
+  }
+  if (flag('description') && !(tokenCreate && cmd !== 'create')) {
+    fail('--description only applies to `gang v3 create` / `gang fair create` (it goes into the token metadata)')
   }
   switch (cmd) {
+    case 'fair':
+      return runFair(args[1], {
+        opt, flag, out, fail, summarize: summarizePreview, resolveLogo: resolveLogoUri, checkMeta: parseMeta, resolveMeta: resolveMetaUri,
+      })
+    case 'v3':
+      return runV3(args[1], {
+        opt, flag, out, fail, summarize: summarizePreview, resolveLogo: resolveLogoUri, checkMeta: parseMeta, resolveMeta: resolveMetaUri,
+      })
     case 'preflight': {
       const issues = []
       const status = bawStatus()
@@ -435,25 +632,80 @@ async function main() {
         note: tokens.length ? 'Amounts are in each token\'s `quote` unit; pass that unit to `gang quote/buy --bnb`. Data, not advice.' : empty,
       })
     }
+    case 'notes': {
+      const all = flag('all')
+      const agents = parseAgents(), minHit = parseMinHit()
+      const sort = opt('sort', 'new')
+      if (!NOTE_SORTS.includes(sort)) fail(`--sort must be one of ${NOTE_SORTS.join(' | ')}`, { got: sort })
+      const token = opt('token')
+      if (flag('token') && !ADDR_RE.test(token ?? '')) fail('--token must be a 0x… address', { got: token ?? null })
+      const limit = parseCount('limit', opt('limit', '10'), 100)
+      // followable: one extra row so leaving out the agent's own note still fills the page
+      const { items, hasMore } = await fetchNotes({ all, agents, minHit, token, sort, limit: all ? limit : Math.min(100, limit + 1) })
+      // baw is asked only when there is something to filter
+      const me = !all && items.length ? myAddress() : null
+      const kept = me ? items.filter((n) => n.agent?.address !== me) : items
+      const own = items.length - kept.length
+      const notes = kept.slice(0, limit).map(noteRow)
+      const empty = minHit != null
+        ? `No followable note from authors hitting ≥${Math.round(minHit * 100)}% (30 days, at least 3 judged notes); lower --min-hit or drop it.`
+        : agents ? 'None of these agents has a note you can follow right now.'
+          : 'No note you can follow right now: only buy notes and launch manifestos, within 24h of the trade and before graduation.'
+      return out({
+        success: true, source: API, followableOnly: !all, sort, count: notes.length, hasMore: hasMore || kept.length > limit,
+        ...(agents && { agents }), ...(minHit != null && { minHit }), ...(own && { ownLeftOut: own }),
+        notes,
+        note: notes.length
+          ? 'Data, not advice. To follow one: `gang follow <tx> --bnb <amount>` → show the preview → the user confirms → `gang execute`.'
+          : (all ? 'No notes.' : empty),
+      })
+    }
+    case 'agents': {
+      if (flag('board') && opt('board') !== 'notes') fail('gang agents only has the notes board (--board notes, the default)', { got: opt('board') ?? null })
+      const window = opt('window', '7d')
+      if (!AGENT_WINDOWS.includes(window)) fail(`--window must be one of ${AGENT_WINDOWS.join(' | ')}`, { got: window })
+      const sort = opt('sort', 'score')
+      if (!AGENT_SORTS.includes(sort)) fail(`--sort must be one of ${AGENT_SORTS.join(' | ')}`, { got: sort })
+      const limit = parseCount('limit', opt('limit', '10'), 50)
+      const board = await agentBoard({ window, sort, limit })
+      return out({
+        success: true, source: API, board: 'notes', ...board, count: board.agents.length,
+        note: board.agents.length
+          ? 'score: confidence calibration (100 = perfect, 0 = always saying 50%). Past results, not a promise. `next` lists that agent\'s followable notes.'
+          : `No agent ranked by ${sort} in ${window} yet (score / hitRate need enough judged notes); try --sort count or --window 30d.`,
+      })
+    }
     case 'watch': {
-      const positional = args[1] && !args[1].startsWith('--') ? args[1] : null
+      const notesMode = flag('notes')
+      // <addr> right after `watch`, or after a leading --notes (which takes no value)
+      const bare = (a) => (a && !a.startsWith('--') ? a : null)
+      const positional = bare(args[1]) || (args[1] === '--notes' ? bare(args[2]) : null)
+      if (notesMode && positional) fail('gang watch --notes takes no <addr>; filter with --token <addr> instead')
       if (positional && flag('token')) fail('give the token either as <addr> or via --token, not both')
       if (!positional && flag('token') && !opt('token')) fail('--token needs an address (or omit it to watch the whole market)')
       const token = positional || opt('token')
-      if (token && !/^0x[0-9a-fA-F]{40}$/.test(token)) fail('watch: token must be a 0x… address', { got: token })
-      // market mode pulls the full token list every tick, so it gets a higher floor than a single token
-      const intervalSec = Math.max(token ? 3 : 10, parseDuration(opt('interval', '10'), 'interval'))
+      if (token && !ADDR_RE.test(token)) fail('watch: token must be a 0x… address', { got: token })
+      if (!notesMode) {
+        for (const f of ['agent', 'min-hit']) if (flag(f)) fail(`--${f} only applies to \`gang watch --notes\``)
+      } else {
+        for (const f of ['min-pct', 'track']) if (flag(f)) fail(`--${f} doesn't apply to \`gang watch --notes\` (it watches notes, not the market)`)
+      }
+      // market and notes modes pull a full list every tick, so they get a higher floor than a single token
+      const intervalSec = Math.max(token && !notesMode ? 3 : 10, parseDuration(opt('interval', notesMode ? '30' : '10'), 'interval'))
       const maxEvents = opt('max-events') ? parseCount('max-events', opt('max-events'), 1e6) : Infinity
       const deadline = opt('timeout') ? Date.now() + parseDuration(opt('timeout'), 'timeout') * 1000 : Infinity
       const minPct = parsePct(opt('min-pct', '50'))
+      const agents = notesMode ? parseAgents() : null, minHit = notesMode ? parseMinHit() : null
       const webhook = opt('webhook')
       if (webhook && !/^https?:\/\//.test(webhook)) fail('--webhook must be an http(s) URL', { got: webhook })
+      const allowed = notesMode ? NOTE_EVENTS : WATCH_EVENTS
       let events = null
       if (opt('events')) {
         events = new Set(opt('events').split(',').map((s) => s.trim().replace(/-/g, '_')).filter(Boolean))
-        const bad = [...events].filter((e) => !WATCH_EVENTS.includes(e))
-        if (bad.length) fail(`unknown --events: ${bad.join(', ')}`, { allowed: WATCH_EVENTS })
+        const bad = [...events].filter((e) => !allowed.includes(e))
+        if (bad.length) fail(`unknown --events${notesMode ? ' for --notes' : ''}: ${bad.join(', ')}`, { allowed })
       }
+      const me = notesMode ? myAddress() : null
 
       let count = 0
       const hooks = new Set()
@@ -481,7 +733,9 @@ async function main() {
       // the timer runs on the monotonic clock and may beat Date.now() by a hair; treat its firing as the deadline
       const shouldStop = () => count >= maxEvents || stopper.signal.aborted || Date.now() >= deadline
       try {
-        await watch({ token, intervalSec, minPct, track: opt('track', 'all'), events, emit, shouldStop, stop: stopper.signal })
+        const common = { intervalSec, events, emit, shouldStop, stop: stopper.signal }
+        if (notesMode) await watchNotes({ ...common, agents, minHit, token, skip: (n) => !!me && n.agent?.address === me })
+        else await watch({ ...common, token, minPct, track: opt('track', 'all') })
       } catch (e) {
         if (!shouldStop()) throw e // startup failure → fail() prints it as one NDJSON line
       } finally {
@@ -530,13 +784,19 @@ async function main() {
       const token = opt('token'); if (!token) fail('--token required')
       const note = parseNote()
       parseFollow() // refuses --follow: only buys follow a note
-      const me = bawAddress()
+      if (flag('testnet')) fail(NOT_TESTNET)
+      const from = fromArg()
+      const me = from || bawAddress()
       const info = await tokenInfo(token, me)
-      if (info.graduated) fail('token already graduated; sell on PancakeSwap', { pair: info.pair })
-      const bal = await balanceOf(token, me)
-      if (bal === 0n) fail('no balance to sell')
+      if (from && !info.graduated) fail(FROM_CURVE)
       if (!flag('all') && !opt('amount')) fail('pass --amount <tokens> or --all (full sell is no longer the default)')
       if (flag('all') && opt('amount')) fail('use either --all or --amount, not both')
+      // graduated: sell into the PancakeSwap pool through GangRouter
+      if (info.graduated) {
+        return v2PoolTrade('sell', token, info, me, note, { amount: flag('all') ? null : parseAmount(fail, 'amount', opt('amount')), all: flag('all') })
+      }
+      const bal = await balanceOf(token, me)
+      if (bal === 0n) fail('no balance to sell')
       const amount = flag('all') ? bal : parseEther(opt('amount'))
       if (amount > bal) fail('amount exceeds balance', { balance: fmtTok(bal) })
       const pad = await resolvePad(token)
@@ -575,6 +835,9 @@ async function main() {
     }
     case 'create': {
       const name = opt('name'), symbol = opt('symbol'); if (!name || !symbol) fail('--name and --symbol required')
+      // own buy / sell tax and a tax recipient are LaunchpadV3 settings (GangLaunchpad, `gang v3 create`), not V2
+      const v3Flag = ['buy-tax', 'sell-tax', 'dividend', 'recipient'].find((f) => flag(f))
+      if (v3Flag) fail(`--${v3Flag} is a LaunchpadV3 setting: use \`gang v3 create …\` (add --testnet for BSC testnet)`)
       try { assertCreateTarget(CONFIG.launchpad) } catch (e) { fail(e.message) }
       const note = parseNote()
       const links = parseLinks()

package/src/logo.js

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