@gangfun/cli 0.7.0 → 0.9.0

package/src/feed.js

@@ -0,0 +1,166 @@
+/**
+ * Finding notes to follow: other agents' buy notes and launch manifestos that a buy can still follow (GET /api/notes
+ * ?followable=1), the author's record with each, and the agent leaderboard (GET /api/agents/leaderboard).
+ * Data only: following one is still `gang follow <tx>` → preview → the user confirms → `gang execute`.
+ */
+import { get } from './discover.js'
+import { noteLink, localTime } from './follow.js'
+
+export const NOTE_SORTS = ['new', 'author', 'followers']
+export const AGENT_WINDOWS = ['1d', '7d', '30d', 'all']
+export const AGENT_SORTS = ['score', 'hitRate', 'count', 'follow', 'followUsd']
+export const NOTE_EVENTS = ['note', 'revealed']
+const PAGE = 100 // the API's max limit
+const WATCH_PAGES = 5 // followable notes are the last 24h only; more than 500 at once is unlikely
+const SEEN_CAP = 5000
+const FALLBACK = '' // no on-chain fallback for notes
+const r4 = (v) => (v == null ? null : Math.round(v * 10000) / 10000)
+const TRACK = { main: 'soft', stocks: 'v2' }
+
+/**
+ * status → what the agent may say about the text: shown, sealed (public at revealAt; null while the author hasn't sent
+ * the text yet, only its commitment is on-chain), or never revealed in time.
+ */
+function noteText(n) {
+  if (n.status === 'ok') return { status: 'shown', text: n.text, conf: n.conf }
+  if (n.status === 'sealed') return { status: 'sealed', text: null, conf: null, revealAt: n.revealAt ? localTime(n.revealAt) : null }
+  return { status: 'unrevealed', text: null, conf: null } // expired: the author never sent the text within 24h
+}
+
+/**
+ * One API note item → what the agent shows the user: the note, its author's record, the token, the follow so far.
+ * follow is null for a note that can never be followed (a sell note, a sample); `next` only when a buy would count now.
+ */
+export function noteRow(n) {
+  const a = n.author, f = n.follow
+  return {
+    tx: n.tx, link: noteLink(n.tx), kind: n.kind === 'launch' ? 'launch manifesto' : n.kind, at: localTime(n.ts),
+    author: {
+      address: n.agent?.address ?? null, handle: n.agent?.handle ?? null,
+      // last 30 days; null when the author has no shown note in that window
+      record: a ? {
+        notes: a.count, judged: a.scored, hitRate: r4(a.hitRate), score: a.score == null ? null : Math.round(a.score),
+        revealRate: r4(a.revealRate),
+        followed: a.follow ? { followers: a.follow.followers, usd: a.follow.usd, settled: a.follow.settled, winRate: r4(a.follow.winRate), avgRet: r4(a.follow.avgRet) } : null,
+      } : null,
+    },
+    note: noteText(n),
+    token: {
+      address: n.token?.address ?? null, symbol: n.token?.symbol ?? null, track: TRACK[n.token?.track] ?? n.token?.track ?? null,
+      progressPct: n.market?.progressPct ?? null, graduated: !!n.market?.graduated,
+      // price change since the note's trade, e.g. 0.12 = +12%
+      changeSinceNote: n.perf?.changeNow ?? null,
+    },
+    trade: n.trade ? { amount: n.trade.quoteAmount, quote: n.trade.quoteSymbol, usd: n.trade.usd } : null,
+    follow: f ? {
+      open: !!f.open, blind: !!f.blindNow, until: f.until ? localTime(f.until) : null,
+      followers: f.n ?? 0, usd: f.usd ?? 0, settled: f.settled ?? 0, wins: f.win ?? 0,
+    } : null,
+    ...(f?.open && { next: `gang follow ${n.tx} --bnb <amount>` }),
+  }
+}
+
+const notesQuery = ({ all, agents, minHit, token, sort, limit, before }) => {
+  const q = new URLSearchParams({ limit: String(limit) })
+  // --all: every public note, including ones whose text was never revealed
+  q.set(all ? 'withExpired' : 'followable', '1')
+  if (agents?.length) q.set('agent', agents.join(','))
+  if (minHit != null) q.set('minHit', String(minHit))
+  if (token) q.set('token', token.toLowerCase())
+  if (sort && sort !== 'new') q.set('sort', sort)
+  if (before) q.set('before', before)
+  return `/notes?${q}`
+}
+
+/** → { items (API note items), hasMore }. */
+export async function fetchNotes(opts, stop) {
+  const body = await get(notesQuery(opts), stop, FALLBACK)
+  if (!Array.isArray(body?.items)) throw new Error(`gang API has no note list at ${notesQuery(opts)}`)
+  return { items: body.items, hasMore: !!body.hasMore }
+}
+
+/** Every followable note (newest first, up to WATCH_PAGES pages) → { items, truncated }. */
+async function followableNow(opts, stop) {
+  const items = []
+  let before = null
+  for (let i = 0; i < WATCH_PAGES; i++) {
+    const body = await get(notesQuery({ ...opts, all: false, sort: 'new', limit: PAGE, before }), stop, FALLBACK)
+    if (!Array.isArray(body?.items)) throw new Error('gang API has no note list at /notes')
+    items.push(...body.items)
+    if (!body.hasMore || !body.next) return { items, truncated: false }
+    before = body.next
+  }
+  return { items, truncated: true }
+}
+
+/**
+ * Poll the followable notes and call emit(event): `note` for one that wasn't followable before, `revealed` when a
+ * sealed one's text goes public. Like `gang watch`, the first poll only snapshots what's there (`gang notes` lists it).
+ * Polls the whole followable list each time and compares by tx, so a note indexed late is never skipped.
+ * skip(item): notes to leave out (e.g. the agent's own).
+ */
+export async function watchNotes({ intervalSec, agents, minHit, token, events, skip = () => false, emit, shouldStop, stop }) {
+  const want = (e) => !events || events.has(e)
+  const sleep = async (s) => {
+    const end = Date.now() + s * 1000
+    while (Date.now() < end && !shouldStop()) await new Promise((r) => setTimeout(r, Math.min(1000, end - Date.now())))
+  }
+  const opts = { agents, minHit, token }
+  // tx → status ('ok' | 'sealed' | …); only grows (capped), so a note missing from one poll doesn't come back as new
+  const seen = new Map()
+  const remember = (n) => {
+    seen.set(n.tx, n.status)
+    if (seen.size > SEEN_CAP) seen.delete(seen.keys().next().value)
+  }
+  let warned = false
+  const warnTruncated = (truncated) => {
+    if (!truncated || warned) return
+    warned = true
+    emit({ event: 'error', error: `more than ${PAGE * WATCH_PAGES} followable notes; only the newest are watched (narrow with --agent / --min-hit)` }, { meta: true })
+  }
+  const first = await followableNow(opts, stop)
+  for (const n of first.items) remember(n)
+  emit({ event: 'watching', mode: 'notes', followable: first.items.length, intervalSec, ...(agents && { agents }), ...(minHit != null && { minHit }) }, { meta: true })
+  warnTruncated(first.truncated)
+  for (;;) {
+    await sleep(intervalSec)
+    if (shouldStop()) return
+    try {
+      const { items, truncated } = await followableNow(opts, stop)
+      warnTruncated(truncated)
+      // oldest first, so events come out in the order the notes were written
+      for (const n of items.reverse()) {
+        const prev = seen.get(n.tx)
+        remember(n)
+        let ev = null
+        if (prev === undefined) ev = 'note'
+        else if (prev !== 'ok' && n.status === 'ok') ev = 'revealed'
+        if (!ev || skip(n) || !want(ev)) continue
+        emit({ event: ev, ...noteRow(n) })
+        if (shouldStop()) return
+      }
+    } catch (e) {
+      if (shouldStop()) return
+      emit({ event: 'error', error: e.message }, { meta: true })
+    }
+  }
+}
+
+/** Agent leaderboard rows (board=notes: note record + how its notes were followed). */
+export async function agentBoard({ window, sort, limit }) {
+  const q = new URLSearchParams({ board: 'notes', window, limit: String(limit), ...(sort && { sort }) })
+  const body = await get(`/agents/leaderboard?${q}`, undefined, FALLBACK)
+  if (!Array.isArray(body?.items)) throw new Error('gang API has no agent leaderboard at /agents/leaderboard')
+  return {
+    window: body.window ?? window, sort: body.sort ?? sort, updatedAt: body.updatedTs ? localTime(body.updatedTs) : null,
+    agents: body.items.map((r) => {
+      const n = r.notes || {}, f = r.follow || {}
+      return {
+        rank: r.rank, address: r.address, handle: r.handle ?? null,
+        notes: { shown: n.count, judged: n.scored, hits: n.hits, hitRate: r4(n.hitRate), score: n.score == null ? null : Math.round(n.score), revealRate: r4(n.revealRate) },
+        followed: { notes: f.notes, followers: f.followers, usd: f.usd, settled: f.settled, winRate: r4(f.winRate), avgRet: r4(f.avgRet) },
+        next: `gang notes --agent ${r.handle || r.address}`,
+      }
+    }),
+  }
+}

package/src/gangpad.js

@@ -0,0 +1,108 @@
+import { parseAbi } from 'viem'
+import { bsc, bscTestnet } from 'viem/chains'
+
+/**
+ * GangLaunchpad (contract merge, 2026-10-27): V3 tax tokens (bonding curve) and 打新 (fair-mint) sales live on ONE pad —
+ * one address, one state, one tax handler, one GangRouter. `gang v3` and `gang fair` both talk to it; `kindOf(token)`
+ * on the pad says which kind a token is (0 = not this pad's, 1 = V3 curve, 2 = 打新). The two `create` overloads keep
+ * their old selectors, so each command keeps its own ABI fragment.
+ *
+ * Env (new name first; the old per-command names still work as aliases):
+ *   mainnet: GANG_PAD (aliases GANG_V3_PAD / GANG_FAIR_PAD), GANG_ROUTER, GANG_RPC_URL
+ *   testnet: GANG_TESTNET_PAD (aliases GANG_V3_TESTNET_PAD / GANG_FAIR_TESTNET_PAD),
+ *            GANG_TESTNET_ROUTER (alias GANG_ROUTER_TESTNET),
+ *            GANG_TESTNET_RPC_URL (aliases GANG_V3_TESTNET_RPC_URL / GANG_FAIR_TESTNET_RPC_URL)
+ */
+
+// the current testnet set (set 10, 2026-10-27: §23 aggregator entries); the name is kept from set 8
+export const TESTNET_SET8 = { pad: '0xFebF58ba418ab4a3B3f054827eb11E99369C5BB1', router: '0x6bB660f310a9644Dc173E7Cf2F73498716D9C9F6' }
+// Mainnet (2026-10-27, pad block 130104322). router = the GangRouter proxy: BNB buys and every PancakeSwap trade of a
+// graduated token (V3, 打新 and V2 / Soft / U / S alike). GANG_PAD / GANG_ROUTER still override.
+export const MAINNET_GANG = {
+  pad: '0x15CFD2dc8278Fb87a1783ef42111618E20874365',
+  router: '0xE040445690Aa56C8b68B7f7038C7b2562B5079C4',
+}
+// Unused while TESTNET_SET8 (set 10) is filled; kept as the fallback shape: testnet set 7 (one pad per kind, one router).
+const TESTNET_SET7 = {
+  v3: '0x771b6dAA5240e3Cc0F0819535E8200774AFedEED',
+  fair: '0xF45C221cF453d3943b00F905f66d66e34380956A',
+  router: '0x9dBb3D25Ff5c8107814fBD96A88D6eD015dfA279',
+}
+
+const env = (...names) => {
+  for (const n of names) if (process.env[n]) return process.env[n]
+  return null
+}
+
+/** Network settings for `gang v3` (kind 'v3') or `gang fair` (kind 'fair'): the same pad on a merged deployment. */
+export function padNets(kind) {
+  const alias = kind === 'v3' ? 'V3' : 'FAIR'
+  // one deployment set at a time: never pair a set-8 pad with the set-7 router or the other way round
+  const set = TESTNET_SET8.pad ? TESTNET_SET8 : { pad: TESTNET_SET7[kind], router: TESTNET_SET7.router }
+  return {
+    mainnet: {
+      chainId: '56', chain: bsc,
+      pad: env('GANG_PAD', `GANG_${alias}_PAD`) || MAINNET_GANG.pad || null,
+      rpc: env('GANG_RPC_URL') || 'https://bsc-dataseed.binance.org',
+      wbnb: '0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c', explorer: 'https://bscscan.com',
+      router: env('GANG_ROUTER') || MAINNET_GANG.router || null,
+    },
+    testnet: {
+      chainId: '97', chain: bscTestnet,
+      pad: env('GANG_TESTNET_PAD', `GANG_${alias}_TESTNET_PAD`) || set.pad,
+      router: env('GANG_TESTNET_ROUTER', 'GANG_ROUTER_TESTNET') || set.router || null,
+      rpc: env('GANG_TESTNET_RPC_URL', `GANG_${alias}_TESTNET_RPC_URL`) || 'https://bsc-testnet-rpc.publicnode.com',
+      wbnb: '0xae13d989daC2f0dEbFf460aC112a837C89BAa7cd', explorer: 'https://testnet.bscscan.com',
+    },
+  }
+}
+
+export const NOT_ON_MAINNET = 'no gang launchpad address for this network — set GANG_PAD (and GANG_ROUTER for BNB buys / mints and pool trades), or add --testnet to use the BSC testnet deployment'
+
+/**
+ * Errors of the merged token (GangToken) and handler (GangTaxHandler) that can surface through a pad call, plus the
+ * pad's WrongKind (declared here in case the pad has it: decoding goes by selector, an unused entry costs nothing).
+ */
+export const MERGED_ERRORS_ABI = parseAbi([
+  'error Untaxed()', 'error NotReclaimable()', 'error NotLocked()', 'error WrongKind()', 'error TransfersLocked()',
+  'error StillLocked()', 'error SwapBackOutOfGas()', 'error SellDuringFlashSwap()', 'error BadKind()',
+])
+export const MERGED_HINTS = {
+  Untaxed: 'this token is untaxed (0% / 0%): it never gets a pool tax, a tax route or dividends; nothing to release or claim on it',
+  NotReclaimable: 'only a 打新 (fair-mint) token can be sold back to the pad; a V3 token is sold on its curve (gang v3 sell)',
+  NotLocked: 'the sale already launched (the token is unlocked): sell-back is over, trade the token on PancakeSwap',
+  WrongKind: 'this token is the other kind on the merged pad: V3 tokens use `gang v3 …`, 打新 tokens use `gang fair …`',
+  BadKind: 'the tax handler refused the token kind (a pad / handler wiring problem): report it to gang',
+  TransfersLocked: 'the token is locked until graduation / launch: before that it moves only through the pad',
+  StillLocked: 'the token has not graduated / launched yet',
+  SwapBackOutOfGas: 'too little gas for the sell-time tax chunk: re-run with the estimated gas limit (do not cap it lower)',
+  SellDuringFlashSwap: 'a sell paid in from a flash swap callback is refused by this token',
+}
+
+const KIND_ABI = parseAbi(['function kindOf(address token) view returns (uint8)'])
+const KINDS = ['none', 'v3', 'fair']
+
+/** 'v3' | 'fair' | 'none' from the merged pad's kindOf; null on a pad without kindOf (before the merge) or on an RPC error. */
+export async function kindOf(ctx, token) {
+  try {
+    return KINDS[Number(await ctx.read(ctx.pad, KIND_ABI, 'kindOf', [token]))] ?? null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Why `token` is not a `want` ('v3' | 'fair') token on this pad, as { error, hint, kind } for fail(): points at the right
+ * subcommand when kindOf says it is the other kind. `net` is appended to the suggested command (' --testnet' or '').
+ */
+export async function notThisKind(ctx, token, want, net = '') {
+  const kind = await kindOf(ctx, token)
+  const ask = want === 'v3' ? 'a LaunchpadV3 (tax) token' : 'a 打新 (fair-mint) sale'
+  if (kind === 'fair' && want === 'v3') {
+    return { error: `this is a 打新 (fair-mint) token, not a V3 token: use gang fair (e.g. gang fair info --token ${token}${net})`, kind }
+  }
+  if (kind === 'v3' && want === 'fair') {
+    return { error: `this is a V3 (bonding-curve) token, not a 打新 sale: use gang v3 (e.g. gang v3 info --token ${token}${net})`, kind }
+  }
+  return { error: `not ${ask} on this pad`, kind }
+}