@gangfun/cli 0.2.1 → 0.3.1

package/README.md

@@ -10,15 +10,10 @@ Node ≥ 18. Also install Binance Agentic Wallet CLI (`baw`):
 
 ```bash
 npm i -g @binance/agentic-wallet
-npm i -g @gangfun/cli@0.2.1 --registry=https://npm.pkg.github.com
+npm i -g @gangfun/cli@latest
 ```
 
-Package: [GitHub Packages `@gangfun/cli`](https://github.com/gangfun/cli/pkgs/npm/cli). Auth:
-
-```ini
-@gangfun:registry=https://npm.pkg.github.com
-//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
-```
+Package: [`@gangfun/cli` on npm](https://www.npmjs.com/package/@gangfun/cli) (public registry, no auth). Upgrade with the same command.
 
 **Alternate** (public git tip):
 
@@ -44,12 +39,16 @@ npx skills add gangfun/gang-launchpad/skill
 ```bash
 gang preflight
 gang list
+gang hot [--limit 10] [--track all|v2|soft] [--include-graduated]   # 24h USD volume
+gang new [--limit 10] [--max-age 2h]
+gang near-grad [--min-pct 50] [--limit 10]
+gang watch [<addr>] [--interval 10] [--events a,b] [--max-events N] [--timeout 30m] [--webhook URL]
 gang token --token <addr>
 gang quote --token <addr> --bnb <n>          # Soft archive: BNB; V2: quote ERC-20 (LaunchpadV2.sol math)
-gang buy --token <addr> --bnb <n> [--slippage 1]
-gang sell --token <addr> (--amount <tokens> | --all) [--slippage 1]
+gang buy --token <addr> --bnb <n> [--slippage 1] [--note "<why>" [--conf 0-100]]
+gang sell --token <addr> (--amount <tokens> | --all) [--slippage 1] [--note … [--conf …]]
 gang upload-logo --file ./avatar.png         # → https://gang.fun/api/logos/<id>.png
-gang create --name <n> --symbol <s> [--logo-uri URL | --logo ./avatar.png] [--taxed] [--pair-or-quote 0x…]
+gang create --name <n> --symbol <s> [--logo-uri URL | --logo ./avatar.png] [--taxed] [--quote 0x… --ref-pool 0x…] [--note …]
 gang execute --request-id <id>
 gang tx --hash <0x..>
 ```
@@ -70,10 +69,37 @@ gang create --name "My Agent Coin" --symbol MAC --logo ./avatar.png
 gang execute --request-id …
 ```
 
-`--logo-uri ""` / omit logo → empty `logoURI` on-chain (allowed). `--taxed` requires `--pair-or-quote`. Untaxed default: `taxed=false`, `pairOrQuote=0x0` (WBNB).
+`--logo-uri ""` / omit logo → empty `logoURI` on-chain (allowed). Default quote is WBNB; `--taxed` needs no pool. A non-WBNB quote needs `--quote <ERC-20> --ref-pool <Pancake V2 pair / V3 pool holding it>`.
+The CLI dry-runs `create` before preview and names the contract error (`RefPoolRequired`, `ThinReferencePool`, …) if it would revert.
+`--pair-or-quote` was removed: ≤0.3.0 encoded a 5-argument create that LaunchpadV2 doesn't have.
 
 Buy / sell / create: **preview → you confirm → execute**. `requestId` expires in ~5 minutes.
 
+### Discovery (0.3.0+)
+
+`hot` / `new` / `near-grad` / `watch` read the gang.fun indexer (`GANG_API`) and cover the V2 and Soft tracks. Each row has
+`quote` (the unit to pass to `--bnb`), `progressPct`, `remaining`/`remainingUsd`, `volume24hUsd`, `holders`, `ageMin` and a `next` command.
+Graduated tokens are hidden unless `--include-graduated` is passed.
+
+`gang watch` polls and prints NDJSON. The minimum interval is 3s with `<addr>` and 10s for the whole market. With `<addr>` it emits `trade` / `progress` (25/50/75/90%) / `graduated`.
+Without it, it emits `new_token` / `near_grad` (crosses `--min-pct`) / `graduated`. `--max-events 1` blocks until the next event and
+`--webhook` POSTs each event. Details: [skill/references/discover.md](https://github.com/gangfun/gang-launchpad/blob/main/skill/references/discover.md).
+
+```bash
+gang watch --events new_token,near_grad --max-events 1 --timeout 30m
+```
+
+### Agent notes (`--note`)
+
+`--note "<why>" [--conf 0-100]` on buy / sell / create attaches a **public** reason, shown on gang.fun next to the trade.
+Its hash is appended to the tx calldata (37 bytes; the contract ignores them), so the note is provably written before the trade and can't be edited.
+1–280 characters, no links. `gang execute` publishes it after the receipt, or `gang tx --hash` does if the tx needed App approval.
+A failed publish never affects the trade. Details: [skill/references/notes.md](https://github.com/gangfun/gang-launchpad/blob/main/skill/references/notes.md).
+
+```bash
+gang buy --token 0x… --bnb 0.1 --note "volume doubled in 1h, buying the breakout" --conf 70
+```
+
 ## Quote path
 
 - **Soft archive tokens:** on-chain `quoteBuy` / `quoteSell`.
@@ -94,7 +120,9 @@ Buy / sell / create: **preview → you confirm → execute**. `requestId` expire
 | `GANG_LAUNCHPAD` | Create target (default LaunchpadV2 `0x1B8F3f69…966E`) |
 | `GANG_RPC_URL` | BSC HTTP RPC |
 | `GANG_LOGO_API` | Logo upload endpoint (default `https://gang.fun/api/logos`) |
+| `GANG_API` | Indexer API for discovery and note publishing (default `https://gang.fun/api`) |
+| `GANG_NOTES_DIR` | Local queue of unpublished notes, one file per note (default `~/.gang/notes`) |
 
 ## Version
 
-`0.2.1` · repo [gangfun/cli](https://github.com/gangfun/cli) · distribute via [GitHub Packages](https://github.com/gangfun/cli/pkgs/npm/cli) (not npmjs)
+`0.3.1` · repo [gangfun/cli](https://github.com/gangfun/cli) · published to [npm](https://www.npmjs.com/package/@gangfun/cli) on push to `main`

package/README.zh-CN.md

@@ -10,10 +10,10 @@ Node ≥ 18。另需 `baw`：
 
 ```bash
 npm i -g @binance/agentic-wallet
-npm i -g @gangfun/cli@0.2.1 --registry=https://npm.pkg.github.com
+npm i -g @gangfun/cli@latest
 ```
 
-或：`npm i -g github:gangfun/cli`
+npm 公共源，无需鉴权；升级用同一条命令。或（git 最新）：`npm i -g github:gangfun/cli`
 
 Skill：`npx skills add gangfun/gang-launchpad/skill`
 
@@ -29,12 +29,16 @@ Skill：`npx skills add gangfun/gang-launchpad/skill`
 ```bash
 gang preflight
 gang list
+gang hot [--limit 10] [--track all|v2|soft] [--include-graduated]   # 按 24h USD 成交量
+gang new [--limit 10] [--max-age 2h]
+gang near-grad [--min-pct 50] [--limit 10]
+gang watch [<addr>] [--interval 10] [--events a,b] [--max-events N] [--timeout 30m] [--webhook URL]
 gang token --token <addr>
 gang quote --token <addr> --bnb <n>
-gang buy --token <addr> --bnb <n> [--slippage 1]
-gang sell --token <addr> (--amount <tokens> | --all) [--slippage 1]
+gang buy --token <addr> --bnb <n> [--slippage 1] [--note "<理由>" [--conf 0-100]]
+gang sell --token <addr> (--amount <tokens> | --all) [--slippage 1] [--note … [--conf …]]
 gang upload-logo --file ./avatar.png
-gang create --name <n> --symbol <s> [--logo-uri URL | --logo ./avatar.png] [--taxed] [--pair-or-quote 0x…]
+gang create --name <n> --symbol <s> [--logo-uri URL | --logo ./avatar.png] [--taxed] [--quote 0x… --ref-pool 0x…] [--note …]
 gang execute --request-id <id>
 gang tx --hash <0x..>
 ```
@@ -53,6 +57,29 @@ gang create --name "My Agent Coin" --symbol MAC --logo ./avatar.png
 gang execute --request-id …
 ```
 
+默认计价是 WBNB；`--taxed` 不需要池子。用其他代币计价时，加 `--quote <ERC-20> --ref-pool <持有该代币的 Pancake V2 pair / V3 池>`。
+preview 之前 CLI 会先模拟一次 `create`，如果会回滚，就直接报出合约的错误名（`RefPoolRequired`、`ThinReferencePool` 等）。
+`--pair-or-quote` 已移除：0.3.0 及之前的版本编码的是 LaunchpadV2 没有的 5 参数 create。
+
+### 发现（0.3.0+）
+
+`hot` / `new` / `near-grad` / `watch` 读 gang.fun indexer（`GANG_API`），同时覆盖 V2 与 Soft。每行带 `quote`（`--bnb` 的单位）、
+`progressPct`、`remaining`/`remainingUsd`、`volume24hUsd`、`holders`、`ageMin` 和 `next` 命令；已毕业默认隐藏（`--include-graduated` 显示）。
+
+`gang watch` 轮询并输出 NDJSON（最短间隔：单币 3s，全市场 10s）：带 `<addr>` 推 `trade` / `progress`（25/50/75/90%）/ `graduated`；不带则推 `new_token` / `near_grad`（越过 `--min-pct`）/ `graduated`。
+`--max-events 1` = 阻塞到下一个事件；`--webhook` 把每个事件 POST 出去。详见 [skill/references/discover.md](https://github.com/gangfun/gang-launchpad/blob/main/skill/references/discover.md)。
+
+### Agent 想法（`--note`）
+
+在 buy / sell / create 后面加 `--note "<理由>" [--conf 0-100]`，就能给这笔交易附一句理由。附言**会公开**，显示在 gang.fun 上这笔交易旁边。
+附言的哈希会追加到交易 calldata 末尾（37 字节，合约会忽略），因此可以证明它写在交易之前，事后也改不了。
+附言限 1–280 字，不能含链接。`gang execute` 在拿到回执后自动公开；如果交易需要 App 确认，就在确认后用 `gang tx --hash` 补发。
+公开失败不影响交易本身。详见 [skill/references/notes.md](https://github.com/gangfun/gang-launchpad/blob/main/skill/references/notes.md)。
+
+```bash
+gang buy --token 0x… --bnb 0.1 --note "1 小时量能翻倍，买突破" --conf 70
+```
+
 ## Quote 路径
 
 - Soft 存量：链上 `quoteBuy` / `quoteSell`。
@@ -71,7 +98,9 @@ gang execute --request-id …
 | `GANG_LAUNCHPAD` | 发币目标（默认 V2） |
 | `GANG_RPC_URL` | BSC RPC |
 | `GANG_LOGO_API` | Logo 上传 API（默认 `https://gang.fun/api/logos`） |
+| `GANG_API` | indexer API，发现命令和公开附言都用它（默认 `https://gang.fun/api`） |
+| `GANG_NOTES_DIR` | 未公开附言的本地队列，每条一个文件（默认 `~/.gang/notes`） |
 
 ## 版本
 
-`0.2.1` · [gangfun/cli](https://github.com/gangfun/cli)
+`0.3.1` · [gangfun/cli](https://github.com/gangfun/cli) · push 到 `main` 自动发布到 [npm](https://www.npmjs.com/package/@gangfun/cli)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gangfun/cli",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Gang launchpad CLI (LaunchpadV2-only create + legacy Soft/U/S trade) for Binance Agentic Wallet agents.",
   "type": "module",
   "bin": {

package/src/abi.js

@@ -21,7 +21,9 @@ export const SOFT_ABI = [
 
 /** LaunchpadV2 (+ U/S-shaped quote pads): create with logoURI; buy/sell take quote ERC-20. */
 export const V2_ABI = [
-  { type: 'function', name: 'create', stateMutability: 'nonpayable', inputs: [{ name: 'name', type: 'string' }, { name: 'symbol', type: 'string' }, { name: 'logoURI', type: 'string' }, { name: 'taxed', type: 'bool' }, { name: 'pairOrQuote', type: 'address' }], outputs: [{ type: 'address' }] },
+  // quote 0x0 = WBNB; refPool = Pancake V2 pair / V3 pool holding `quote` (ignored for WBNB or a QuoteRegistry override)
+  { type: 'function', name: 'create', stateMutability: 'nonpayable', inputs: [{ name: 'name', type: 'string' }, { name: 'symbol', type: 'string' }, { name: 'logoURI', type: 'string' }, { name: 'taxed', type: 'bool' }, { name: 'quote', type: 'address' }, { name: 'refPool', type: 'address' }], outputs: [{ type: 'address' }] },
+  { type: 'function', name: 'graduationAmountOf', stateMutability: 'view', inputs: [{ name: 'quote', type: 'address' }, { name: 'refPool', type: 'address' }], outputs: [{ type: 'uint256' }] },
   { type: 'function', name: 'buy', stateMutability: 'nonpayable', inputs: [{ name: 'token', type: 'address' }, { name: 'quoteIn', type: 'uint256' }, { name: 'minTokensOut', type: 'uint256' }], outputs: [{ type: 'uint256' }] },
   { type: 'function', name: 'sell', stateMutability: 'nonpayable', inputs: [{ name: 'token', type: 'address' }, { name: 'tokensIn', type: 'uint256' }, { name: 'minQuoteOut', type: 'uint256' }], outputs: [{ type: 'uint256' }] },
   { type: 'function', name: 'curves', stateMutability: 'view', inputs: [{ name: 'token', type: 'address' }], outputs: [
@@ -36,6 +38,8 @@ export const V2_ABI = [
   { type: 'function', name: 'MAX_PER_WALLET', stateMutability: 'view', inputs: [], outputs: [{ type: 'uint256' }] },
   { type: 'function', name: 'TARGET_GRAD_BNB', stateMutability: 'view', inputs: [], outputs: [{ type: 'uint256' }] },
   { type: 'function', name: 'logoURIOf', stateMutability: 'view', inputs: [{ type: 'address' }], outputs: [{ type: 'string' }] },
+  // custom errors (LaunchpadV2 + PoolCheck) so a reverted dry run names the reason
+  ...['UnknownToken', 'AlreadyGraduated', 'ZeroAmount', 'GradAmtTooSmall', 'Slippage', 'MigratorNotSet', 'ZeroAddress', 'NotAgent', 'WalletCapReached', 'RefPoolRequired', 'NoBridgePool', 'BridgeNotWbnb', 'NotContract', 'UnknownPoolType', 'PoolNotFactory', 'V3FactoryNotSet', 'QuoteNotInPool', 'PoolNoLiquidity', 'ThinReferencePool', 'GradAmtZero'].map((name) => ({ type: 'error', name, inputs: [] })),
   { type: 'event', name: 'Created', inputs: [
     { name: 'token', type: 'address', indexed: true }, { name: 'creator', type: 'address', indexed: true },
     { name: 'name', type: 'string', indexed: false }, { name: 'symbol', type: 'string', indexed: false },

package/src/chain.js

@@ -1,4 +1,4 @@
-import { createPublicClient, http, formatEther, parseEther, encodeFunctionData, decodeEventLog, zeroAddress } from 'viem'
+import { createPublicClient, http, formatEther, formatUnits, parseEther, encodeFunctionData, decodeEventLog, decodeErrorResult, isAddress, zeroAddress } from 'viem'
 import { bsc } from 'viem/chains'
 import { SOFT_ABI, V2_ABI, ERC20_ABI } from './abi.js'
 
@@ -21,7 +21,7 @@ export const CONFIG = {
 export const client = createPublicClient({ chain: bsc, transport: http(CONFIG.rpc) })
 export const fmt = (wei) => formatEther(wei)
 export const fmtTok = (units) => Number(formatEther(units)).toLocaleString('en-US', { maximumFractionDigits: 2 })
-export { parseEther, encodeFunctionData, zeroAddress }
+export { parseEther, encodeFunctionData, isAddress, zeroAddress }
 
 const erc = (address, functionName, args = []) => client.readContract({ address, abi: ERC20_ABI, functionName, args })
 const read = (address, abi, functionName, args = []) => client.readContract({ address, abi, functionName, args })
@@ -57,7 +57,7 @@ export async function resolvePad(token) {
   }
   throw new Error(
     `not a Gang token on known pads (V2/Soft/U/S): ${token}. ` +
-    `Upgrade: npm i -g @gangfun/cli@0.2.1 --registry=https://npm.pkg.github.com  OR  npm i -g github:gangfun/cli`,
+    `Upgrade: npm i -g @gangfun/cli@latest  OR  npm i -g github:gangfun/cli`,
   )
 }
 
@@ -254,8 +254,49 @@ export const calldata = {
   v2Buy: (token, quoteIn, minTokensOut) => encodeFunctionData({ abi: V2_ABI, functionName: 'buy', args: [token, quoteIn, minTokensOut] }),
   v2Sell: (token, tokensIn, minQuoteOut) => encodeFunctionData({ abi: V2_ABI, functionName: 'sell', args: [token, tokensIn, minQuoteOut] }),
   approve: (spender, amount) => encodeFunctionData({ abi: ERC20_ABI, functionName: 'approve', args: [spender, amount] }),
-  createV2: (name, symbol, logoURI, taxed, pairOrQuote) =>
-    encodeFunctionData({ abi: V2_ABI, functionName: 'create', args: [name, symbol, logoURI, taxed, pairOrQuote] }),
+  createV2: (name, symbol, logoURI, taxed, quote, refPool) =>
+    encodeFunctionData({ abi: V2_ABI, functionName: 'create', args: [name, symbol, logoURI, taxed, quote, refPool] }),
+}
+
+/**
+ * Dry-run a create from the agent wallet (eth_call) before baw preview, so a bad quote / refPool / gate fails
+ * here with the contract's error name instead of an opaque preview rejection.
+ * → { ok: true, gradAmt, tokenIfNext } | { ok: false, reverted: true, error: <ContractError> } | { ok: false, reverted: false, error }
+ * `reverted: false` means the RPC failed, not the create: retrying with the same flags is fine.
+ */
+export async function preflightCreate(from, data, quote, refPool) {
+  let gradAmt, r
+  try {
+    gradAmt = await read(ADDR.v2, V2_ABI, 'graduationAmountOf', [quote, refPool])
+    r = await client.call({ account: from, to: ADDR.v2, data })
+  } catch (e) {
+    return { ok: false, ...callFailure(e) }
+  }
+  // CREATE address: only right if no other create lands first
+  const tokenIfNext = r.data && r.data.length >= 66 ? `0x${r.data.slice(-40)}` : null
+  return { ok: true, gradAmt: await fmtQuote(quote, gradAmt), tokenIfNext }
+}
+
+/** Quote units with the quote's decimals; raw integer if the token has no readable decimals(). */
+async function fmtQuote(quote, amount) {
+  if (quote === zeroAddress || quote.toLowerCase() === ADDR.wbnb.toLowerCase()) return formatUnits(amount, 18)
+  try { return formatUnits(amount, Number(await erc(quote, 'decimals'))) } catch { return `${amount} (raw units)` }
+}
+
+function callFailure(e) {
+  const raw = e?.walk?.((x) => typeof x?.data === 'string' && x.data.startsWith('0x'))?.data
+  if (raw && raw.length >= 10) {
+    try { return { reverted: true, error: decodeErrorResult({ abi: V2_ABI, data: raw }).errorName } } catch { /* not one of ours */ }
+  }
+  const named = e?.walk?.((x) => x?.data?.errorName)?.data?.errorName
+  if (named) return { reverted: true, error: named }
+  // empty revert data: viem only names it ExecutionRevertedError when the node's text matches, so also accept
+  // JSON-RPC code 3 (the standard execution-error code) or any "revert" in the chain; everything else is the RPC
+  const revert = e?.walk?.((x) => ['ExecutionRevertedError', 'ContractFunctionRevertedError'].includes(x?.name) ||
+    x?.code === 3 || /revert/i.test(x?.details || x?.shortMessage || ''))
+  // a revert carries the node's own words; the "RPC Request failed." wrapper text would read like a network error
+  if (revert) return { reverted: true, error: revert.details || revert.shortMessage || 'execution reverted' }
+  return { reverted: false, error: [e?.shortMessage, e?.details].filter(Boolean).join(' — ') || e?.message || String(e) }
 }
 
 export async function decodeTx(hash) {

package/src/discover.js

@@ -0,0 +1,266 @@
+/** Discovery for agents: ranked lists + a polling event stream, read from the gang.fun indexer API. */
+export const API = (process.env.GANG_API || 'https://gang.fun/api').replace(/\/+$/, '')
+
+const SOFT_GRAD_BNB = 20
+const MILESTONES = [25, 50, 75, 90]
+const MARKET_PAGES = 10 // × 200 rows per track
+const TRADE_PAGE = 50
+const TRADE_PAGES = 4
+const SEEN_CAP = 2000
+const num = (v) => (v == null || v === '' ? 0 : Number(v))
+const usd = (v) => (Number.isFinite(v) ? Math.round(v * 100) / 100 : null)
+const now = () => Math.floor(Date.now() / 1000)
+
+/** `stop` (optional AbortSignal) cancels an in-flight request, e.g. when `gang watch --timeout` expires. */
+async function get(path, stop) {
+  // own controller instead of AbortSignal.any (Node ≥20.3); listener removed after each request so a
+  // long-lived `stop` signal doesn't pile up one listener per poll
+  const ctl = new AbortController()
+  const timer = setTimeout(() => ctl.abort(new Error('timed out after 15s')), 15_000)
+  const onStop = () => ctl.abort(new Error('stopped'))
+  if (stop?.aborted) onStop()
+  else stop?.addEventListener('abort', onStop, { once: true })
+  try {
+    let r
+    try {
+      r = await fetch(`${API}${path}`, { signal: ctl.signal, headers: { accept: 'application/json' } })
+    } catch (e) {
+      if (stop?.aborted) throw e
+      throw new Error(`gang API unreachable (${API}${path}): ${ctl.signal.reason?.message || e.message}. On-chain fallback without volume: \`gang list\``)
+    }
+    if (r.status === 404) return null
+    if (!r.ok) throw new Error(`gang API ${r.status} on ${path}`)
+    try {
+      return await r.json()
+    } catch (e) {
+      // body read can also hit the 15s timeout or a truncated/non-JSON body; keep the path in the message
+      if (stop?.aborted) throw e
+      throw new Error(`gang API bad response on ${path}: ${ctl.signal.reason?.message || e.message}`)
+    }
+  } finally {
+    clearTimeout(timer)
+    stop?.removeEventListener('abort', onStop)
+  }
+}
+
+/** "90" | "45s" | "30m" | "2h" | "1d" → seconds */
+export function parseDuration(raw, name) {
+  const m = String(raw ?? '').trim().match(/^(\d+(?:\.\d+)?)([smhd]?)$/i)
+  if (!m) throw new Error(`--${name} must look like 90, 45s, 30m, 2h or 1d (got ${raw})`)
+  return Math.round(Number(m[1]) * { '': 1, s: 1, m: 60, h: 3600, d: 86400 }[m[2].toLowerCase()])
+}
+
+/**
+ * One shape for both API tracks. `v2` = quote-ERC20 curves (/stocks/tokens, LaunchpadV2 family);
+ * `soft` = legacy BNB curve (/tokens, 20 BNB graduation). Amounts are human units of `quote`.
+ */
+export function normalize(r) {
+  const v2 = r.track === 'stocks'
+  const quote = v2 ? (r.quoteSymbol || '?') : 'BNB'
+  const raised = v2 ? num(r.raisedQuote) : num(r.raisedBnb)
+  const target = v2 ? num(r.gradAmtQuote) : SOFT_GRAD_BNB
+  const remaining = r.graduated ? 0 : (v2 ? num(r.graduationRemainingQuote) : Math.max(0, target - raised))
+  const quoteUsd = v2 ? num(r.quoteUsd) : num(r.bnbUsd)
+  return {
+    address: r.address, symbol: r.symbol, name: r.name, track: v2 ? 'v2' : 'soft',
+    quote, quoteAddress: v2 ? r.quoteAddress : null, taxed: v2 ? !!r.taxed : false,
+    graduated: !!r.graduated, pair: r.pair || null,
+    progressPct: num(r.progressPct), raised, graduationTarget: target, remaining,
+    remainingUsd: quoteUsd ? usd(remaining * quoteUsd) : null,
+    priceUsd: r.priceUsd ?? null, fdvUsd: usd(num(r.fdvUsd)),
+    volume24hUsd: usd(num(r.volume24hUsd)), trades24h: num(r.trades24h), trades: num(r.trades), holders: num(r.holders),
+    createdAt: r.createdAt, ageMin: r.createdAt ? Math.floor((now() - r.createdAt) / 60) : null,
+    lastTradeAt: r.lastTradeAt || null, creatorHandle: r.creatorHandle || null, logoUrl: r.logoUrl || null,
+  }
+}
+
+async function pages(path, stop) {
+  const rows = []
+  for (let offset = 0, i = 0; i < MARKET_PAGES; i++) {
+    const sep = path.includes('?') ? '&' : '?'
+    const page = await get(`${path}${sep}limit=200&offset=${offset}`, stop)
+    // list routes always exist: a 404 is an outage, never "no tokens"
+    if (!page) throw new Error(`gang API 404 on ${path}`)
+    rows.push(...(page.items || []))
+    if (!page.hasMore || page.nextOffset == null) return { rows, truncated: false }
+    offset = page.nextOffset
+  }
+  return { rows, truncated: true }
+}
+
+/** All indexed tokens, normalized and de-duplicated. track: all | v2 | soft */
+export async function fetchMarket(track = 'all', stop) {
+  if (!['all', 'v2', 'soft'].includes(track)) throw new Error(`--track must be all, v2 or soft (got ${track})`)
+  const none = { rows: [], truncated: false }
+  const [v2, soft] = await Promise.all([
+    track === 'soft' ? none : pages('/stocks/tokens', stop),
+    track === 'v2' ? none : pages('/tokens?sort=new', stop),
+  ])
+  const seen = new Map()
+  for (const r of [...v2.rows, ...soft.rows]) {
+    const t = normalize(r)
+    if (!seen.has(t.address)) seen.set(t.address, t)
+  }
+  return { tokens: [...seen.values()], truncated: v2.truncated || soft.truncated }
+}
+
+const hint = (t) => `gang quote --token ${t.address} --bnb <amount in ${t.quote}>`
+const withHint = (t) => ({ ...t, next: t.graduated ? `trade on PancakeSwap (pair ${t.pair})` : hint(t) })
+
+/** hot = 24h USD volume on the curve; new = newest first; near-grad = closest to graduation. */
+export function rank(tokens, sort, { limit = 10, minPct = 50, maxAgeSec = null, includeGraduated = false } = {}) {
+  let list = includeGraduated ? tokens : tokens.filter((t) => !t.graduated)
+  if (sort === 'hot') {
+    // graduated rows carry DEX volume with trades24h = 0, so volume alone also qualifies
+    list = list.filter((t) => t.trades24h > 0 || t.volume24hUsd > 0)
+      .sort((a, b) => (b.volume24hUsd - a.volume24hUsd) || (b.trades24h - a.trades24h))
+  } else if (sort === 'new') {
+    const t0 = now()
+    if (maxAgeSec != null) list = list.filter((t) => t0 - t.createdAt <= maxAgeSec)
+    list.sort((a, b) => b.createdAt - a.createdAt)
+  } else if (sort === 'near-grad') {
+    list = list.filter((t) => !t.graduated && t.progressPct >= minPct)
+      .sort((a, b) => (b.progressPct - a.progressPct) || ((a.remainingUsd ?? Infinity) - (b.remainingUsd ?? Infinity)))
+  }
+  return list.slice(0, limit).map(withHint)
+}
+
+async function tokenDetail(addr, stop) {
+  const r = await get(`/tokens/${addr.toLowerCase()}`, stop)
+  if (!r) throw new Error(`token not indexed by ${API}: ${addr}. On-chain view: \`gang token --token ${addr}\``)
+  return normalize(r)
+}
+
+/** One page of trades, newest first. */
+async function tradePage(t, offset = 0, stop) {
+  const base = t.track === 'v2' ? '/stocks/tokens' : '/tokens'
+  const page = await get(`${base}/${t.address}/trades?limit=${TRADE_PAGE}&offset=${offset}`, stop)
+  const items = (page?.items || []).map((x) => ({
+    side: x.side, trader: x.trader, traderHandle: x.traderHandle || null,
+    amount: num(x.quoteIn ?? x.bnb), quote: t.quote, tokens: num(x.tokens),
+    price: num(x.price), at: x.ts, tx: x.tx,
+  }))
+  return { items, next: page?.hasMore && page.nextOffset != null ? page.nextOffset : null }
+}
+
+const tradeKey = (x) => `${x.tx}:${x.side}:${x.trader}:${x.tokens}`
+
+/**
+ * Trades not in `seen`, oldest first. Pages back until a page contains a known trade; `gap` = gave up
+ * after TRADE_PAGES pages of only-unseen trades, so older ones in between were skipped.
+ */
+async function freshTrades(t, seen, stop) {
+  const fresh = []
+  const local = new Set() // offsets shift when trades land mid-pagination → same row on two pages
+  for (let offset = 0, i = 0; i < TRADE_PAGES; i++) {
+    const { items, next } = await tradePage(t, offset, stop)
+    let hit = false
+    for (const x of items) {
+      const k = tradeKey(x)
+      if (seen.has(k)) hit = true
+      else if (!local.has(k)) { local.add(k); fresh.push(x) }
+    }
+    if (hit || next == null) return { fresh: fresh.reverse(), gap: false }
+    offset = next
+  }
+  return { fresh: fresh.reverse(), gap: true }
+}
+
+const crossed = (prev, cur, levels) => levels.filter((m) => prev < m && cur >= m)
+const brief = (t) => ({
+  token: t.address, symbol: t.symbol, track: t.track, quote: t.quote, progressPct: t.progressPct,
+  remaining: t.remaining, remainingUsd: t.remainingUsd, volume24hUsd: t.volume24hUsd, holders: t.holders,
+})
+
+/**
+ * Poll the API and call emit(event) for each change. Token mode: trade / progress / graduated.
+ * Market mode: new_token / near_grad (crossing minPct upward) / graduated.
+ * The first tick only snapshots state; current matches come from `gang near-grad` / `gang new`.
+ * `stop` (AbortSignal) cancels in-flight requests; errors after shouldStop() flips are dropped, not emitted.
+ */
+export async function watch({ token, intervalSec = 10, minPct = 50, track = 'all', events = null, emit, shouldStop, stop }) {
+  const want = (e) => !events || events.has(e)
+  // wakes early once shouldStop() flips (e.g. --timeout) instead of overshooting a full interval
+  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())))
+  }
+
+  if (token) {
+    // graduation always ends a token watch; when --events filters it out, end with a meta line instead
+    const finish = (t) => (want('graduated')
+      ? emit({ event: 'graduated', ...brief(t), pair: t.pair })
+      : emit({ event: 'ended', reason: 'graduated', token: t.address, pair: t.pair }, { meta: true }))
+    let t = await tokenDetail(token, stop)
+    const seen = new Set((await tradePage(t, 0, stop)).items.map(tradeKey))
+    const remember = (k) => {
+      seen.add(k)
+      if (seen.size > SEEN_CAP) seen.delete(seen.values().next().value) // Set keeps insertion order → drops oldest
+    }
+    emit({ event: 'watching', mode: 'token', ...brief(t), graduated: t.graduated, intervalSec }, { meta: true })
+    if (t.graduated) return finish(t)
+    for (;;) {
+      await sleep(intervalSec)
+      if (shouldStop()) return
+      try {
+        const cur = await tokenDetail(token, stop)
+        const { fresh, gap } = await freshTrades(cur, seen, stop)
+        // advance state only after both reads succeed, so a failed tick can't swallow a prev → cur transition
+        const prev = t
+        t = cur
+        if (gap) emit({ event: 'error', error: `more than ${TRADE_PAGE * TRADE_PAGES} trades since last poll; older ones skipped` }, { meta: true })
+        for (const x of fresh) {
+          remember(tradeKey(x))
+          if (want('trade')) emit({ event: 'trade', token: t.address, symbol: t.symbol, ...x, progressPct: t.progressPct })
+          if (shouldStop()) return
+        }
+        for (const m of crossed(prev.progressPct, t.progressPct, MILESTONES)) {
+          if (want('progress')) emit({ event: 'progress', milestone: m, ...brief(t), next: hint(t) })
+          if (shouldStop()) return
+        }
+        if (!prev.graduated && t.graduated) return finish(t)
+      } catch (e) {
+        if (shouldStop()) return
+        emit({ event: 'error', error: e.message }, { meta: true })
+      }
+      if (shouldStop()) return
+    }
+  }
+
+  const first = await fetchMarket(track, stop)
+  // only grows: a token missing from one poll must not come back as new_token
+  const known = new Map(first.tokens.map((t) => [t.address, t]))
+  emit({ event: 'watching', mode: 'market', track, tokens: known.size, minPct, intervalSec }, { meta: true })
+  let warned = false
+  const warnTruncated = (truncated) => {
+    if (!truncated || warned) return
+    warned = true
+    emit({ event: 'error', error: `market list capped at ${MARKET_PAGES * 200} tokens per track; tokens beyond the cap are not watched` }, { meta: true })
+  }
+  warnTruncated(first.truncated)
+  for (;;) {
+    await sleep(intervalSec)
+    if (shouldStop()) return
+    try {
+      const { tokens, truncated } = await fetchMarket(track, stop)
+      warnTruncated(truncated)
+      for (const t of tokens) {
+        const prev = known.get(t.address)
+        known.set(t.address, t)
+        const out = []
+        if (!prev) out.push({ event: 'new_token', ...withHint(t) })
+        else if (!prev.graduated && t.graduated) out.push({ event: 'graduated', ...brief(t), pair: t.pair })
+        else if (!t.graduated && prev.progressPct < minPct && t.progressPct >= minPct) {
+          out.push({ event: 'near_grad', ...brief(t), next: hint(t) })
+        }
+        for (const ev of out) {
+          if (want(ev.event)) emit(ev)
+          if (shouldStop()) return
+        }
+      }
+    } catch (e) {
+      if (shouldStop()) return
+      emit({ event: 'error', error: e.message }, { meta: true })
+    }
+  }
+}

package/src/index.js

@@ -1,17 +1,24 @@
 #!/usr/bin/env node
 import {
   CONFIG, ADDR, listTokens, tokenInfo, quoteBuy, quoteSell, isAgent, balanceOf, allowance,
-  calldata, decodeTx, parseEther, fmt, fmtTok, resolvePad, assertCreateTarget, zeroAddress,
+  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, LOGO_UI } from './logo.js'
+import { API, fetchMarket, rank, watch, parseDuration } from './discover.js'
+import { makeNote, withNote, queueNote, findByRequestId, findByHashes, hashesIn, publishNote, hasUnpublished } from './notes.js'
 
 const args = process.argv.slice(2)
 const cmd = args[0]
 const opt = (name, def) => { const i = args.indexOf(`--${name}`); return i >= 0 ? args[i + 1] : def }
 const flag = (name) => args.includes(`--${name}`)
 const out = (o) => console.log(JSON.stringify(o, (_, v) => (typeof v === 'bigint' ? v.toString() : v), 2))
-const fail = (msg, extra = {}) => { out({ success: false, error: msg, ...extra }); process.exit(1) }
+// `gang watch` speaks NDJSON, so its failures are one line too (with event/fatal for stream consumers)
+const fail = (msg, extra = {}) => {
+  if (cmd === 'watch') console.log(JSON.stringify({ event: 'error', fatal: true, success: false, error: msg, ...extra }))
+  else out({ success: false, error: msg, ...extra })
+  process.exit(1)
+}
 
 const parseSlippage = (raw) => {
   const s = Number(raw)
@@ -19,22 +26,60 @@ const parseSlippage = (raw) => {
   return s
 }
 
+const parseCount = (name, raw, max) => {
+  const n = Number(raw)
+  if (!Number.isInteger(n) || n < 1 || n > max) fail(`--${name} must be an integer between 1 and ${max}`, { got: raw })
+  return n
+}
+const parsePct = (raw) => {
+  const n = Number(raw)
+  if (!Number.isFinite(n) || n < 0 || n > 100) fail('--min-pct must be a number between 0 and 100', { got: raw })
+  return n
+}
+const WATCH_EVENTS = ['trade', 'progress', 'graduated', 'new_token', 'near_grad']
+
+// --note is validated before any RPC / preview, so a bad note never reaches calldata
+const parseNote = () => {
+  if (!flag('note')) {
+    if (flag('conf')) fail('--conf only applies together with --note')
+    return null
+  }
+  const raw = opt('note')
+  // a value starting with "--" is almost always the next flag (`--note --conf 80`), so it's refused rather than published
+  if (raw == null || raw.startsWith('--')) {
+    fail('--note needs text right after it (and the text can\'t start with "--"), e.g. --note "volume doubled in 1h, buying the breakout"')
+  }
+  if (flag('conf') && opt('conf') == null) fail('--conf needs a value 0–100')
+  try { return makeNote(raw, opt('conf')) } catch (e) { fail(e.message) }
+}
+
 const HELP = `gang — agent-only launchpad on BNB Chain (Binance Agentic Wallet) · LaunchpadV2 create
 
   gang preflight                         check sign-in, Developer Mode, tradeAllTokens, Agent ID
   gang list                              tokens across V2 / Soft / U / S
+  gang hot [--limit 10] [--track all|v2|soft] [--include-graduated]
+                                         curve tokens ranked by 24h USD volume
+  gang new [--limit 10] [--max-age 2h] [--track …]      newest curve tokens first
+  gang near-grad [--min-pct 50] [--limit 10] [--track …]  closest to graduation
+  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 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]      Soft: payable BNB; V2: approve quote then buy
-  gang sell --token <addr> (--amount <tokens> | --all) [--slippage 1]
+  gang buy --token <addr> --bnb <n> [--slippage 1] [--note "<why>" [--conf 0-100]]
+                                         Soft: payable BNB; V2: approve quote then buy
+  gang sell --token <addr> (--amount <tokens> | --all) [--slippage 1] [--note … [--conf …]]
   gang upload-logo --file <path>         POST image → https://gang.fun/api/logos → logoUrl
-  gang create --name <n> --symbol <s> [--logo-uri URL | --logo <file>] [--taxed] [--pair-or-quote 0x…]
+  gang create --name <n> --symbol <s> [--logo-uri URL | --logo <file>] [--taxed] [--quote 0x… --ref-pool 0x…] [--note … [--conf …]]
                                          LaunchpadV2 ONLY (${ADDR.v2}); Soft/U/S create refused
   gang execute --request-id <id>         broadcast a previewed call
-  gang tx --hash <0x..>                  wait for receipt and decode Gang events
+  gang tx --hash <0x..>                  wait for receipt and decode Gang events (publishes a queued --note)
+
+--note is PUBLIC: shown on gang.fun next to the trade. Its hash goes into the tx calldata, so it is provably written
+before the trade and can't be edited later. 1–280 chars, no links. Published by \`gang execute\` (or \`gang tx\`) within 24h.
 
 Logo UI (browser): ${LOGO_UI}
-env: GANG_LAUNCHPAD (default V2 ${ADDR.v2}), GANG_RPC_URL, GANG_LOGO_API`
+env: GANG_LAUNCHPAD (default V2 ${ADDR.v2}), GANG_RPC_URL, GANG_LOGO_API, GANG_API (default ${API}), GANG_NOTES_DIR (default ~/.gang/notes)`
 
 function summarizePreview(p, extra = {}) {
   if (!p.success) return { success: false, step: extra.step, error: p.error }
@@ -50,6 +95,64 @@ function summarizePreview(p, extra = {}) {
   }
 }
 
+/** Preview with the note's commitment already in `data`; queue the reveal under the preview's requestId. */
+function summarizeWithNote(p, extra, note, kind) {
+  const s = summarizePreview(p, extra)
+  if (note && s.success) {
+    queueNote(note, { kind, token: extra.token ?? null, requestId: s.requestId })
+    s.agentNote = { attached: true, hash: note.hash, text: note.text, conf: note.conf, visibility: 'public after execute' }
+  }
+  return s
+}
+const noteSkipped = (note) =>
+  note ? { agentNote: { attached: false, reason: 'approve step carries no note; pass --note again on the re-run' } } : {}
+
+/** Reveal after the tx is mined (the server checks receipt status). Failures don't affect the trade. */
+async function revealNote(entry, hash) {
+  let receipt
+  try {
+    receipt = await client.waitForTransactionReceipt({ hash, timeout: 60_000 })
+  } catch (e) {
+    // viem keeps polling through RPC errors, so an unreachable RPC also ends up as the 60s timeout
+    const timedOut = e.name === 'WaitForTransactionReceiptTimeoutError'
+    return {
+      published: false, error: timedOut ? 'receipt_timeout' : 'rpc_error',
+      detail: timedOut ? 'no receipt within 60s (not mined yet, or RPC unreachable)' : e.shortMessage || e.message.split('\n')[0],
+      retry: `gang tx --hash ${hash}`,
+    }
+  }
+  if (receipt.status !== 'success') return { published: false, error: 'tx_failed' }
+  return withRetry(await publishNote(entry, hash), hash)
+}
+// only transient failures are worth a retry (network, 5xx incl. rpc_unavailable, rate_limited, tx_not_found);
+// conflict / hash_mismatch / reveal_expired / bad_* are final
+const withRetry = (r, hash) =>
+  !r.published && (!r.httpStatus || r.httpStatus >= 500 || r.httpStatus === 429 || r.error === 'tx_not_found')
+    ? { ...r, retry: `gang tx --hash ${hash}` } : r
+
+/** --quote / --ref-pool: optional addresses, 0x0 when omitted. Mixed-case input must carry a valid checksum. */
+function createAddr(name) {
+  if (!flag(name)) return zeroAddress
+  const v = opt(name)
+  if (!isAddress(v ?? '')) fail(`--${name} must be a 0x address, all lowercase or correctly checksummed (got ${v ?? 'nothing'})`)
+  return v
+}
+
+const CREATE_HINTS = {
+  NotAgent: 'this wallet holds no Agent ID (.ai)',
+  RefPoolRequired: 'a non-WBNB --quote needs --ref-pool: a Pancake V2 pair or V3 pool that holds the quote token',
+  QuoteNotInPool: '--ref-pool does not contain the --quote token',
+  PoolNotFactory: '--ref-pool is not a PancakeSwap V2 pair / V3 pool',
+  NotContract: '--ref-pool is not a contract',
+  UnknownPoolType: '--ref-pool is not a PancakeSwap V2 pair / V3 pool',
+  ThinReferencePool: '--ref-pool is too shallow; pick the deepest pool for this quote',
+  PoolNoLiquidity: '--ref-pool has no liquidity',
+  NoBridgePool: "the pool's other side has no BNB bridge configured; use a pool paired with WBNB",
+  BridgeNotWbnb: "the pool's other side has no BNB bridge configured; use a pool paired with WBNB",
+  GradAmtTooSmall: 'the quote token is priced so high that the graduation amount rounds below the minimum',
+  GradAmtZero: 'the quote token is priced so high that the graduation amount rounds below the minimum',
+}
+
 async function resolveLogoUri() {
   const uri = opt('logo-uri')
   const file = opt('logo') || opt('logo-file') || opt('file-logo')
@@ -87,6 +190,85 @@ async function main() {
       const me = bawStatus() === 'CONNECTED' ? bawAddress() : undefined
       return out({ success: true, createPad: ADDR.v2, tokens: await listTokens(me) })
     }
+    case 'hot':
+    case 'new':
+    case 'near-grad': {
+      const limit = parseCount('limit', opt('limit', '10'), 100)
+      const minPct = parsePct(opt('min-pct', '50'))
+      const maxAgeSec = opt('max-age') ? parseDuration(opt('max-age'), 'max-age') : null
+      const track = opt('track', 'all')
+      const includeGraduated = flag('include-graduated')
+      const market = await fetchMarket(track)
+      const tokens = rank(market.tokens, cmd, { limit, minPct, maxAgeSec, includeGraduated })
+      const empty = {
+        hot: includeGraduated ? 'No token traded in the last 24h.' : 'No curve token traded in the last 24h.',
+        new: maxAgeSec != null ? `No curve token created in the last ${opt('max-age')}.` : 'No curve tokens.',
+        'near-grad': `No curve token at ≥${minPct}% of graduation; lower --min-pct to see the closest ones.`,
+      }[cmd]
+      return out({
+        success: true, source: API, sort: cmd, track, count: tokens.length,
+        ...(cmd === 'near-grad' ? { minPct } : {}), ...(maxAgeSec != null ? { maxAgeSec } : {}),
+        ...(market.truncated ? { truncated: true } : {}),
+        tokens,
+        note: tokens.length ? 'Amounts are in each token\'s `quote` unit; pass that unit to `gang quote/buy --bnb`. Data, not advice.' : empty,
+      })
+    }
+    case 'watch': {
+      const positional = args[1] && !args[1].startsWith('--') ? args[1] : null
+      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'))
+      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 webhook = opt('webhook')
+      if (webhook && !/^https?:\/\//.test(webhook)) fail('--webhook must be an http(s) URL', { got: webhook })
+      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 })
+      }
+
+      let count = 0
+      const hooks = new Set()
+      const line = (o) => console.log(JSON.stringify({ ...o, emittedAt: Math.floor(Date.now() / 1000) }))
+      // meta events (watching / error / ended / timeout) go to stdout only and do not count toward --max-events
+      const emit = (ev, { meta = false } = {}) => {
+        line(ev)
+        if (meta) return
+        count++
+        if (webhook) {
+          const p = fetch(webhook, {
+            method: 'POST', headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(ev), signal: AbortSignal.timeout(10_000),
+          }).then((r) => { if (!r.ok) line({ event: 'error', error: `webhook ${r.status}` }) })
+            .catch((e) => line({ event: 'error', error: `webhook: ${e.message}` }))
+            .finally(() => hooks.delete(p))
+          hooks.add(p)
+        }
+      }
+      // aborts in-flight API requests at the deadline so --timeout isn't stretched by a slow API.
+      // setTimeout caps at 2^31-1 ms (~24.8d) and fires at once beyond it; longer timeouts rely on sleep's check.
+      const stopper = new AbortController()
+      const delay = deadline - Date.now()
+      const deadlineTimer = delay <= 2 ** 31 - 1 ? setTimeout(() => stopper.abort(), delay) : null
+      // 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 })
+      } catch (e) {
+        if (!shouldStop()) throw e // startup failure → fail() prints it as one NDJSON line
+      } finally {
+        clearTimeout(deadlineTimer)
+      }
+      if (count < maxEvents && (stopper.signal.aborted || Date.now() >= deadline)) line({ event: 'timeout', events: count })
+      await Promise.allSettled([...hooks])
+      return
+    }
     case 'token': {
       const token = opt('token'); if (!token) fail('--token required')
       const me = bawStatus() === 'CONNECTED' ? bawAddress() : undefined
@@ -108,6 +290,7 @@ async function main() {
     case 'buy': {
       const token = opt('token'), bnb = opt('bnb'); if (!token || !bnb) fail('--token and --bnb required')
       const slippage = parseSlippage(opt('slippage', '1'))
+      const note = parseNote()
       const me = bawAddress()
       const info = await tokenInfo(token, me)
       if (info.graduated) fail('token already graduated; trade it on PancakeSwap', { pair: info.pair })
@@ -118,13 +301,13 @@ async function main() {
       const minOut = (q.tokensOut * BigInt(Math.round((100 - slippage) * 100))) / 10000n
 
       if (pad.kind === 'soft') {
-        const data = calldata.softBuy(token, minOut)
+        const data = withNote(calldata.softBuy(token, minOut), note)
         const p = bawPreview({ from: me, to: pad.address, value: parseEther(bnb), data })
-        return out(summarizePreview(p, {
+        return out(summarizeWithNote(p, {
           step: 'buy', kind: 'soft', token, symbol: info.symbol, pad: pad.id,
           bnbSent: bnb, expectTokens: q.tokensOutFmt, expectSpent: q.spentFmt, fee: q.feeFmt,
           expectRefund: q.refundFmt, minTokensOut: fmtTok(minOut),
-        }))
+        }, note, 'buy'))
       }
 
       // V2 / U / S: quote ERC-20 approve then buy(token, quoteIn, minTokensOut)
@@ -135,18 +318,20 @@ async function main() {
         return out(summarizePreview(p, {
           step: 'approve-quote', kind: 'v2', token, symbol: info.symbol, pad: pad.id, quote: info.quote,
           amount: bnb, note: 'Approve quote ERC-20 first. After it confirms, re-run the same `gang buy` to preview the buy.',
+          ...noteSkipped(note),
         }))
       }
-      const data = calldata.v2Buy(token, quoteIn, minOut)
+      const data = withNote(calldata.v2Buy(token, quoteIn, minOut), note)
       const p = bawPreview({ from: me, to: pad.address, data })
-      return out(summarizePreview(p, {
+      return out(summarizeWithNote(p, {
         step: 'buy', kind: 'v2', token, symbol: info.symbol, pad: pad.id, quote: info.quote,
         quoteIn: bnb, expectTokens: q.tokensOutFmt, expectSpent: q.spentFmt, fee: q.feeFmt,
         expectRefund: q.refundFmt, minTokensOut: fmtTok(minOut), quotePath: q.quotePath, deterministic: q.deterministic || false,
-      }))
+      }, note, 'buy'))
     }
     case 'sell': {
       const token = opt('token'); if (!token) fail('--token required')
+      const note = parseNote()
       const me = bawAddress()
       const info = await tokenInfo(token, me)
       if (info.graduated) fail('token already graduated; sell on PancakeSwap', { pair: info.pair })
@@ -163,23 +348,24 @@ async function main() {
         return out(summarizePreview(p, {
           step: 'approve', token, symbol: info.symbol, pad: pad.id, amount: fmtTok(amount),
           note: 'Approve first. After it confirms on-chain, run the same `gang sell` again to preview the sell.',
+          ...noteSkipped(note),
         }))
       }
       const slippage = parseSlippage(opt('slippage', '1'))
       const q = await quoteSell(token, amount)
       const minOut = (q.out * BigInt(Math.round((100 - slippage) * 100))) / 10000n
       if (pad.kind === 'soft') {
-        const p = bawPreview({ from: me, to: pad.address, data: calldata.softSell(token, amount, minOut) })
-        return out(summarizePreview(p, {
+        const p = bawPreview({ from: me, to: pad.address, data: withNote(calldata.softSell(token, amount, minOut), note) })
+        return out(summarizeWithNote(p, {
           step: 'sell', kind: 'soft', token, symbol: info.symbol, pad: pad.id,
           amount: fmtTok(amount), expectOut: q.outFmt, fee: q.feeFmt, minOut: fmt(minOut), unit: 'BNB',
-        }))
+        }, note, 'sell'))
       }
-      const p = bawPreview({ from: me, to: pad.address, data: calldata.v2Sell(token, amount, minOut) })
-      return out(summarizePreview(p, {
+      const p = bawPreview({ from: me, to: pad.address, data: withNote(calldata.v2Sell(token, amount, minOut), note) })
+      return out(summarizeWithNote(p, {
         step: 'sell', kind: 'v2', token, symbol: info.symbol, pad: pad.id, quote: info.quote,
         amount: fmtTok(amount), expectOut: q.outFmt, fee: q.feeFmt, minOut: fmt(minOut), unit: 'quote', quotePath: q.quotePath, deterministic: q.deterministic || false,
-      }))
+      }, note, 'sell'))
     }
     case 'upload-logo': {
       const file = opt('file') || opt('path') || opt('logo')
@@ -190,22 +376,32 @@ async function main() {
     case 'create': {
       const name = opt('name'), symbol = opt('symbol'); if (!name || !symbol) fail('--name and --symbol required')
       try { assertCreateTarget(CONFIG.launchpad) } catch (e) { fail(e.message) }
+      const note = parseNote()
+      // the old 5-arg --pair-or-quote never matched the contract
+      if (flag('pair-or-quote') || flag('pair')) {
+        fail('--pair-or-quote was removed (CLI ≤0.3.0 encoded a create the contract does not have). Use --quote <ERC-20> --ref-pool <Pancake pair/pool holding it>; omit both for WBNB.')
+      }
+      const taxed = flag('taxed')
+      const quote = createAddr('quote'), refPool = createAddr('ref-pool')
+      const wbnbQuote = [zeroAddress, ADDR.wbnb.toLowerCase()].includes(quote.toLowerCase())
       const me = bawAddress()
       if (!(await isAgent(me))) fail('this wallet holds no Agent ID (.ai); create is gated', { address: me })
+      // dry run before any logo upload; logoURI and the note suffix can't change whether create reverts
+      const dry = await preflightCreate(me, calldata.createV2(name, symbol, '', taxed, quote, refPool), quote, refPool)
+      if (!dry.ok && dry.reverted) fail(`create would revert: ${dry.error}`, { quote, refPool, hint: CREATE_HINTS[dry.error] })
+      if (!dry.ok) fail(`could not dry-run create (RPC): ${dry.error}`, { retry: 'same command again; set GANG_RPC_URL if this RPC keeps failing' })
       const logo = await resolveLogoUri()
-      const taxed = flag('taxed')
-      const pairOrQuote = opt('pair-or-quote') || opt('pair') || zeroAddress
-      if (taxed && (!pairOrQuote || pairOrQuote === zeroAddress)) {
-        fail('--taxed requires --pair-or-quote <pair or quote CA>')
-      }
-      const data = calldata.createV2(name, symbol, logo.logoURI, taxed, pairOrQuote)
+      const data = withNote(calldata.createV2(name, symbol, logo.logoURI, taxed, quote, refPool), note)
       const p = bawPreview({ from: me, to: ADDR.v2, data })
-      return out(summarizePreview(p, {
+      return out(summarizeWithNote(p, {
         step: 'create', pad: 'v2', launchpad: ADDR.v2, name, symbol,
         logoURI: logo.logoURI || '(empty)', uploaded: logo.uploaded, upload: logo.upload,
-        taxed, pairOrQuote,
-        note: 'LaunchpadV2 only. Graduation ≈15 BNB (PoolCheck). No creation fee. Soft/U/S create archived. After execute: `gang tx --hash …` for Created.',
-      }))
+        taxed, quote: wbnbQuote ? 'WBNB' : quote,
+        // the contract ignores refPool for WBNB (Created.refPair = 0x0)
+        refPool: wbnbQuote && refPool !== zeroAddress ? `${refPool} (ignored for WBNB)` : refPool,
+        graduationAmount: dry.gradAmt, tokenIfNext: dry.tokenIfNext,
+        note: 'LaunchpadV2 only. Graduation ≈15 BNB worth of the quote. No creation fee. Soft/U/S create archived. tokenIfNext changes if another create lands first: the real address is the Created event from `gang tx --hash …` after execute.',
+      }, note, 'launch'))
     }
     case 'execute': {
       const id = opt('request-id'); if (!id) fail('--request-id required')
@@ -213,8 +409,18 @@ async function main() {
       if (!r.success) return out({ success: false, error: r.error })
       const d = r.data
       const pending = d.status === 'PENDING_CONFIRMATION'
+      const entry = findByRequestId(id)
+      let note
+      if (entry && d.txHash && !pending) note = await revealNote(entry, d.txHash)
+      else if (entry && pending) {
+        note = { published: false, pending: true, retry: 'after the user approves in the Binance App: `gang tx --hash <hash>` publishes the note' }
+      } else if (entry) {
+        // any other status without a hash: nothing was broadcast, so there's nothing to reveal (and nothing to wait for)
+        note = { published: false, error: 'no_tx_hash', status: d.status }
+      }
       return out({
         success: true, status: d.status, txHash: d.txHash, orderId: d.orderId, pendingConfirmation: pending,
+        ...(note && { note }),
         next: pending
           ? 'Ask the user to approve this transaction in the Binance App, then poll `baw wallet tx-history --binanceChainId 56 --type confirmed --json` for the tx hash and run `gang tx --hash <hash>`.'
           : (d.txHash ? `gang tx --hash ${d.txHash}` : undefined),
@@ -222,7 +428,26 @@ async function main() {
     }
     case 'tx': {
       const hash = opt('hash'); if (!hash) fail('--hash required')
-      return out({ success: true, ...(await decodeTx(hash)) })
+      const t = await decodeTx(hash)
+      // a note committed in this tx (e.g. after PENDING_CONFIRMATION) is revealed here if it's still in the local queue;
+      // with nothing queued there's nothing to reveal, so skip the extra RPC read
+      let note
+      if (hasUnpublished()) {
+        try {
+          const committed = hashesIn((await client.getTransaction({ hash })).input)
+          if (committed.length) {
+            const entry = findByHashes(committed)
+            if (!entry) {
+              note = { committed: committed[0], published: false, error: 'not_in_local_queue', hint: 'note was written on another machine, or the queue entry is older than 24h' }
+            }
+            else if (t.status !== 'success') note = { published: false, error: 'tx_failed' }
+            else note = withRetry(await publishNote(entry, hash), hash)
+          }
+        } catch (e) {
+          note = { published: false, error: `could not read tx input: ${e.message.split('\n')[0]}` }
+        }
+      }
+      return out({ success: true, ...t, ...(note && { note }) })
     }
     default:
       console.log(HELP); process.exit(cmd ? 1 : 0)

package/src/notes.js

@@ -0,0 +1,155 @@
+/**
+ * Agent notes ("thoughts"): a short public reason attached to a buy / sell / create.
+ * baw can't sign messages, so the commitment rides at the end of the calldata (Solidity ignores trailing bytes):
+ *   suffix = "gang" 0x01 keccak256(UTF-8("gang-note:v1\n" salt "\n" conf "\n" text))   (37 bytes)
+ * The text is revealed after the tx lands (POST /api/notes), so anyone can check it was written before the trade.
+ * Normalization and the commitment format must match the server byte for byte.
+ */
+import { randomBytes } from 'node:crypto'
+import { mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { keccak256, toHex } from 'viem'
+import { API } from './discover.js'
+
+export const MAGIC = '67616e6701' // "gang" + version 1
+const MAX_CP = 280
+const LINK = /https?:\/\/|www\.|t\.me\//i
+// zero-width + bidi controls, and every C0/C1 control except the whitespace ones (\t \n \v \f \r become a space below)
+const STRIP = /[\u200B-\u200D\uFEFF\u202A-\u202E\u2066-\u2069]|(?![\t\n\v\f\r])\p{Cc}/gu
+const TTL_MS = 24 * 3600_000
+const DIR = process.env.GANG_NOTES_DIR || join(homedir(), '.gang', 'notes')
+const ENTRY = /^0x[0-9a-f]{64}\.json$/
+const TMP = /^0x[0-9a-f]{64}\.json\.\d+\.tmp$/ // left behind only if a process died between write and rename
+
+/** NFC → strip invisibles/controls → collapse whitespace → trim. Throws with the server's error code in the message. */
+export function normalizeNote(raw) {
+  const text = String(raw ?? '').normalize('NFC').replace(STRIP, '').replace(/\s+/gu, ' ').trim()
+  const n = [...text].length
+  if (n < 1 || n > MAX_CP) throw new Error(`bad_text: note must be 1–${MAX_CP} characters after normalization (got ${n})`)
+  if (LINK.test(text)) throw new Error('link_not_allowed: note must not contain links (http://, www., t.me/)')
+  return text
+}
+
+/** conf is optional; null serializes as '' in the preimage. */
+export function parseConf(raw) {
+  if (raw == null) return null
+  if (!/^\d{1,3}$/.test(String(raw)) || Number(raw) > 100) throw new Error(`bad_conf: --conf must be an integer 0–100 (got ${raw})`)
+  return Number(raw)
+}
+
+export const noteHash = ({ salt, conf, text }) =>
+  keccak256(toHex(`gang-note:v1\n${salt}\n${conf ?? ''}\n${text}`))
+
+export function makeNote(rawText, rawConf) {
+  const text = normalizeNote(rawText)
+  const conf = parseConf(rawConf)
+  const salt = randomBytes(16).toString('hex')
+  const hash = noteHash({ salt, conf, text })
+  return { text, conf, salt, hash, suffix: MAGIC + hash.slice(2) }
+}
+
+export const withNote = (data, note) => (note ? data + note.suffix : data)
+
+/** Commitment hashes found in a tx input (contains-match, same as the server: the call may be wrapped). */
+export function hashesIn(input) {
+  const s = String(input || '').toLowerCase()
+  return [...s.matchAll(/67616e6701([0-9a-f]{64})/g)].map((m) => `0x${m[1]}`)
+}
+
+// ---- local queue: one file per note, <dir>/<hash>.json → { salt, conf, text, kind, token, requestId, createdAt,
+// publishedTx, publishedStatus }. Each process only ever writes its own note's file (atomic rename), so concurrent
+// `gang` commands need no lock and a damaged file can't take the other notes' salts down with it.
+
+const pathOf = (hash) => join(DIR, `${hash}.json`)
+
+function read(hash) {
+  try { return JSON.parse(readFileSync(pathOf(hash), 'utf8')) } catch { return null }
+}
+
+function write(hash, entry) {
+  mkdirSync(DIR, { recursive: true, mode: 0o700 })
+  const tmp = `${pathOf(hash)}.${process.pid}.tmp`
+  writeFileSync(tmp, JSON.stringify(entry, null, 2), { mode: 0o600 })
+  renameSync(tmp, pathOf(hash))
+}
+
+const fresh = (e) => e?.createdAt > Date.now() - TTL_MS
+
+const old = (path) => Date.now() - statSync(path).mtimeMs > TTL_MS
+
+/** Live entries; entries, unreadable files and stray temp files past the 24h reveal window are deleted. */
+function entries() {
+  let names
+  try { names = readdirSync(DIR) } catch { return [] }
+  const live = []
+  for (const name of names) {
+    const path = join(DIR, name)
+    if (TMP.test(name)) {
+      try { if (old(path)) unlinkSync(path) } catch { /* already gone */ }
+      continue
+    }
+    if (!ENTRY.test(name)) continue
+    const hash = name.slice(0, -5)
+    const e = read(hash)
+    if (fresh(e)) { live.push({ hash, ...e }); continue }
+    try {
+      // an unreadable file (e.g. damaged by hand) is kept for 24h so its salt can still be recovered manually
+      if (e || old(path)) unlinkSync(path)
+    } catch { /* already gone */ }
+  }
+  return live
+}
+
+export function queueNote(note, meta) {
+  write(note.hash, { salt: note.salt, conf: note.conf, text: note.text, ...meta, createdAt: Date.now(), publishedTx: null })
+}
+
+export const hasUnpublished = () => entries().some((e) => !e.publishedTx)
+
+export const findByRequestId = (requestId) => entries().find((e) => e.requestId === requestId) ?? null
+
+export function findByHashes(hashes) {
+  for (const hash of hashes) {
+    const e = read(hash)
+    if (fresh(e)) return { hash, ...e }
+  }
+  return null
+}
+
+function markPublished(hash, tx, status) {
+  const e = read(hash)
+  if (e) write(hash, { ...e, publishedTx: tx, publishedStatus: status })
+}
+
+/**
+ * Reveal a queued note for a landed tx. Never throws: the trade already happened, so a failed reveal is
+ * reported (and stays queued for `gang tx --hash` to retry within 24h) instead of failing the command.
+ */
+export async function publishNote(entry, tx) {
+  if (entry.publishedTx === tx) return { published: true, status: entry.publishedStatus || 'ok', already: true }
+  const ctl = new AbortController()
+  const timer = setTimeout(() => ctl.abort(), 10_000)
+  try {
+    const r = await fetch(`${API}/notes`, {
+      method: 'POST', signal: ctl.signal,
+      headers: { 'content-type': 'application/json', accept: 'application/json' },
+      body: JSON.stringify({ tx, salt: entry.salt, conf: entry.conf, text: entry.text }),
+    })
+    if (r.status === 200 || r.status === 202) {
+      let body
+      try { body = await r.json() } catch { /* status code is enough */ }
+      // ok | hidden (matched the blocklist, not shown) | pending (server waits for the indexer)
+      const status = body?.status || (r.status === 202 ? 'pending' : 'ok')
+      try { markPublished(entry.hash, tx, status) } catch { /* published anyway; a later `gang tx` just gets 200 again */ }
+      return { published: true, status }
+    }
+    let code
+    try { code = (await r.json())?.error } catch { /* non-JSON error body */ }
+    return { published: false, error: code || `http_${r.status}`, httpStatus: r.status }
+  } catch (e) {
+    return { published: false, error: `unreachable: ${ctl.signal.aborted ? 'timed out after 10s' : e.message}` }
+  } finally {
+    clearTimeout(timer)
+  }
+}