@gangfun/cli 0.3.0 → 0.3.1

package/README.md

@@ -45,10 +45,10 @@ 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..>
 ```
@@ -69,7 +69,9 @@ 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.
 
@@ -87,6 +89,17 @@ Without it, it emits `new_token` / `near_grad` (crosses `--min-pct`) / `graduate
 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`.
@@ -107,8 +120,9 @@ gang watch --events new_token,near_grad --max-events 1 --timeout 30m
 | `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 (default `https://gang.fun/api`) |
+| `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.3.0` · repo [gangfun/cli](https://github.com/gangfun/cli) · published to [npm](https://www.npmjs.com/package/@gangfun/cli) on push to `main`
+`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

@@ -35,10 +35,10 @@ 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..>
 ```
@@ -57,6 +57,10 @@ 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` 的单位）、
@@ -65,6 +69,17 @@ gang execute --request-id …
 `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`。
@@ -83,8 +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_API` | indexer API，发现命令和公开附言都用它（默认 `https://gang.fun/api`） |
+| `GANG_NOTES_DIR` | 未公开附言的本地队列，每条一个文件（默认 `~/.gang/notes`） |
 
 ## 版本
 
-`0.3.0` · [gangfun/cli](https://github.com/gangfun/cli) · push 到 `main` 自动发布到 [npm](https://www.npmjs.com/package/@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.3.0",
+  "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 })
@@ -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/index.js

@@ -1,11 +1,12 @@
 #!/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]
@@ -37,6 +38,21 @@ const parsePct = (raw) => {
 }
 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
@@ -50,16 +66,20 @@ const HELP = `gang — agent-only launchpad on BNB Chain (Binance Agentic Wallet
                                          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, GANG_API (default ${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 }
@@ -75,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')
@@ -212,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 })
@@ -222,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)
@@ -239,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 })
@@ -267,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')
@@ -294,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')
@@ -317,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),
@@ -326,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)
+  }
+}