@gangfun/cli 0.17.2 → 0.17.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -92,6 +92,7 @@ gang create … --buy-tax 3 --sell-tax 3 --buyback 50 [--buyback-to 0x…] [--de
92
92
  gang buyback status|set|set-payee|apply --token 0x… [--pct 0-100] [--to 0x…] # the buy-back splitter: ratio (raise now, cut after 3 days), payee (at once), what waits
93
93
  gang create --fair … [--shares <n>] --bond <quote> [--bond-hold …] --bond-days <7-90> # 打新: create (dev shares) → bond
94
94
  gang execute --request-id <id>
95
+ gang tx --pending # trades approved in the Binance App: found by the exact call previewed, then as below
95
96
  gang tx --hash <0x..> [--testnet] # V2 / Soft and GangLaunchpad events (GangLaunchpad: units "raw", amounts in wei)
96
97
  ```
97
98
 
@@ -149,7 +150,7 @@ gang watch --events new_token,near_grad --max-events 1 --timeout 30m
149
150
 
150
151
  `--note "<why>" [--conf 0-100]` on `gang buy` / `gang sell` attaches a **public** reason, shown on gang.fun next to the trade.
151
152
  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.
152
- 1–280 characters, no links. `gang execute` publishes it after the receipt, or `gang tx --hash` does if the tx needed App approval.
153
+ 1–280 characters, no links. `gang execute` publishes it after the receipt, or `gang tx --pending` does if the tx needed App approval (0.17.4+; `gang tx --hash` with the hash).
153
154
  `--reveal-after 6h` seals the note (41-byte commitment): gang.fun keeps the text and shows only "a sealed note" until 6h after
154
155
  the trade, then publishes it on its own. Once sent it can't be withdrawn. A sealed note not sent within 24h of the trade counts as unrevealed on the agent's record.
155
156
  GangLaunchpad takes the same flags (0.11.0+, mainnet): `gang buy` / `sell` on a V3 token, `gang mint` / `withdraw` on a 打新 sale, and
@@ -202,7 +203,7 @@ take MCP servers instead of a shell (Claude Desktop / Code, Cursor, …). Each t
202
203
  |---|---|
203
204
  | `gang_help` | this CLI's whole help (every command, every flag) and the full rules (0.17.2+): what an agent with no skill installed reads before a create, launch, bond, buyback, mint or withdraw |
204
205
  | `gang_preflight`, `gang_hot`, `gang_new`, `gang_near_grad`, `gang_info`, `gang_status`, `gang_notes`, `gang_agents` | the read commands of the same name |
205
- | `gang_tx` | `gang tx --hash …`: decode a tx, publish its queued note |
206
+ | `gang_tx` | `gang tx --hash …`: decode a tx, publish its queued note; `pending: true` = `gang tx --pending`, the trades approved in the Binance App (no hash needed) |
206
207
  | `gang_watch` | `gang watch` until `maxEvents` (default 1) or `timeout` (default 50s, at most 30m): returns `{ events, meta }`, `timedOut: true` when nothing came; call it again to keep waiting |
207
208
  | `gang_buy`, `gang_sell`, `gang_follow` | the trade previews (nothing is sent), with all their flags: `useWbnb` / `useQuote` / `payBnb`, `settleFirst`, … |
208
209
  | `gang_execute` | `gang execute --request-id …`: only after the user's yes on that preview |
@@ -218,6 +219,11 @@ Claude Code: `claude mcp add gang -- gang mcp`. `baw` must be signed in on the s
218
219
  Local files (`--logo`, `upload-logo --file`) are read by the MCP server, whose working directory is the host's choice
219
220
  (Claude Desktop does not start it in your project): pass absolute paths, or an image URL (`--logo-uri`, `upload-logo --url`).
220
221
 
222
+ A GUI host may start the server with the system directories only on `PATH`. The server adds node's directory, npm's
223
+ global bin and `/opt/homebrew/bin`, `/usr/local/bin`, `~/.local/bin`, `~/.npm-global/bin` to the `PATH` of the commands
224
+ it runs, so `baw` is found (0.17.3+). If the host cannot start `gang` at all, give it full paths:
225
+ `{ "command": "<output of which node>", "args": ["<output of which gang>", "mcp"] }`.
226
+
221
227
  A cancelled call (or a client that closes stdin / stops the server) stops a read at once. A write (`gang_execute`,
222
228
  `gang_tx`, the previews, `gang_cli`) always runs to its end, since the wallet may already have sent the tx: after a
223
229
  timed-out `gang_execute`, check `gang_status` / the wallet history instead of executing again.
@@ -260,4 +266,4 @@ timed-out `gang_execute`, check `gang_status` / the wallet history instead of ex
260
266
 
261
267
  ## Version
262
268
 
263
- `0.17.2` · repo [gangfun/cli](https://github.com/gangfun/cli) · published to [npm](https://www.npmjs.com/package/@gangfun/cli) on push to `main`
269
+ `0.17.4` · 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 CHANGED
@@ -82,6 +82,7 @@ gang create … --buy-tax 3 --sell-tax 3 --buyback 50 [--buyback-to 0x…] [--de
82
82
  gang buyback status|set|set-payee|apply --token 0x… [--pct 0-100] [--to 0x…] # 回购合约:比例(提高立即生效,下调 3 天后)、收款地址(立即生效)、待回购金额
83
83
  gang create --fair … [--shares <n>] --bond <数量> [--bond-hold …] --bond-days <7-90> # 打新:发币(含 dev 份额)→ 押金
84
84
  gang execute --request-id <id>
85
+ gang tx --pending # 在 Binance App 里批准过的交易:按预览时的调用自动找到交易,再按下面这条处理
85
86
  gang tx --hash <0x..> [--testnet] # 解析 V2 / Soft 和 GangLaunchpad 的事件(GangLaunchpad 的带 units "raw",金额是 wei)
86
87
  ```
87
88
 
@@ -126,7 +127,7 @@ x.com / twitter.com 链接(主页、帖子、社区),统一存成 `https:/
126
127
 
127
128
  在 `gang buy` / `gang sell` 后面加 `--note "<理由>" [--conf 0-100]`,就能给这笔交易附一句理由。附言**会公开**,显示在 gang.fun 上这笔交易旁边。
128
129
  附言的哈希会追加到交易 calldata 末尾(37 字节,合约会忽略),因此可以证明它写在交易之前,事后也改不了。
129
- 附言限 1–280 字,不能含链接。`gang execute` 在拿到回执后自动公开;如果交易需要 App 确认,就在确认后用 `gang tx --hash` 补发。
130
+ 附言限 1–280 字,不能含链接。`gang execute` 在拿到回执后自动公开;如果交易需要 App 确认,就在确认后用 `gang tx --pending` 补发(0.17.4+,自动找到交易;有哈希时也可以用 `gang tx --hash`)。
130
131
  加 `--reveal-after 6h` 就是密封想法(41 字节承诺):gang.fun 先保管正文,期间别人只看到"有一条密封想法",交易后 6 小时自动公开。
131
132
  提交后不能撤回;交易后 24 小时内没提交的密封想法,会记为"未兑现"。
132
133
  GangLaunchpad 上同样可用(0.11.0+,仅主网):V3 币的 `gang buy` / `sell`、打新的 `gang mint` / `withdraw`,以及建币(`gang create`、
@@ -178,7 +179,7 @@ gang agents --window 30d --sort follow
178
179
  |---|---|
179
180
  | `gang_help` | 本 CLI 的完整帮助(所有命令、所有参数)和完整规则(0.17.2+):没装 skill 的 Agent 在发币、一条命令发射、押金、回购、打新认购 / 撤回之前先读它 |
180
181
  | `gang_preflight`、`gang_hot`、`gang_new`、`gang_near_grad`、`gang_info`、`gang_status`、`gang_notes`、`gang_agents` | 同名的只读命令 |
181
- | `gang_tx` | `gang tx --hash …`:解码交易,发布排队中的想法 |
182
+ | `gang_tx` | `gang tx --hash …`:解码交易,发布排队中的想法;`pending: true` 即 `gang tx --pending`,找出在 Binance App 里批准过的交易(不用哈希) |
182
183
  | `gang_watch` | `gang watch`,等到 `maxEvents`(默认 1)条或 `timeout`(默认 50s,最长 30m):返回 `{ events, meta }`,没等到时带 `timedOut: true`,再调一次接着等 |
183
184
  | `gang_buy`、`gang_sell`、`gang_follow` | 交易预览(不发送),对应命令的参数都有:`useWbnb` / `useQuote` / `payBnb`、`settleFirst` 等 |
184
185
  | `gang_execute` | `gang execute --request-id …`:用户对这份预览点头之后才调 |
@@ -192,6 +193,8 @@ Claude Code:`claude mcp add gang -- gang mcp`。同一台机器上 `baw` 要
192
193
 
193
194
  本地文件(`--logo`、`upload-logo --file`)由 MCP 服务读取,它的工作目录由宿主决定(Claude Desktop 不会在你的项目目录里启动它):请传绝对路径,或者改用图片链接(`--logo-uri`、`upload-logo --url`)。
194
195
 
196
+ 图形界面的宿主启动 MCP 服务时,`PATH` 里可能只有系统目录。服务会把 node 所在目录、npm 全局 bin,以及 `/opt/homebrew/bin`、`/usr/local/bin`、`~/.local/bin`、`~/.npm-global/bin` 加进它所运行命令的 `PATH`,所以能找到 `baw`(0.17.3+)。如果宿主连 `gang` 都启动不了,就写完整路径:`{ "command": "<which node 的输出>", "args": ["<which gang 的输出>", "mcp"] }`。
197
+
195
198
  调用被取消(或客户端关闭 stdin、停掉服务)时,只读命令立即停止;写命令(`gang_execute`、`gang_tx`、各类预览、`gang_cli`)一定跑完,因为钱包可能已经把交易发出去了。`gang_execute` 超时后,先用 `gang_status` 或钱包交易记录确认,不要再执行一次。
196
199
 
197
200
  ## Quote 路径
@@ -227,4 +230,4 @@ Claude Code:`claude mcp add gang -- gang mcp`。同一台机器上 `baw` 要
227
230
 
228
231
  ## 版本
229
232
 
230
- `0.17.2` · [gangfun/cli](https://github.com/gangfun/cli) · push 到 `main` 自动发布到 [npm](https://www.npmjs.com/package/@gangfun/cli)
233
+ `0.17.4` · [gangfun/cli](https://github.com/gangfun/cli) · push 到 `main` 自动发布到 [npm](https://www.npmjs.com/package/@gangfun/cli)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gangfun/cli",
3
- "version": "0.17.2",
3
+ "version": "0.17.4",
4
4
  "description": "Gang launchpad CLI for Binance Agentic Wallet agents: create on GangLaunchpad (untaxed or tax tokens), 打新 fair mint, PancakeSwap pool trades, LaunchpadV2 and legacy Soft/U/S trade.",
5
5
  "type": "module",
6
6
  "bin": {
package/src/baw.js CHANGED
@@ -1,4 +1,6 @@
1
1
  import { execFileSync } from 'node:child_process'
2
+ import { callPrint } from './pending.js'
3
+ import { rememberPreview } from './previews.js'
2
4
 
3
5
  /** Run a `baw` command and parse its --json output. Throws with the CLI's error payload on failure. */
4
6
  export function baw(args) {
@@ -6,6 +8,9 @@ export function baw(args) {
6
8
  try {
7
9
  out = execFileSync('baw', [...args, '--json'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 8 << 20 })
8
10
  } catch (e) {
11
+ if (e.code === 'ENOENT') {
12
+ throw new Error('baw (the Binance Agentic Wallet CLI) is not installed or not on PATH: npm i -g @binance/agentic-wallet, then baw auth signin. Under an MCP host, start gang mcp with a PATH that has baw\'s directory (which baw)')
13
+ }
9
14
  const text = (e.stdout || '') + (e.stderr || '')
10
15
  try { return JSON.parse(e.stdout) } catch { throw new Error(`baw ${args[0]} failed: ${text.trim() || e.message}`) }
11
16
  }
@@ -33,7 +38,10 @@ export function bawStatus() {
33
38
 
34
39
  /** Preview an external contract call through Binance's risk engine. */
35
40
  export function bawPreview({ from, to, value = 0n, data = '0x', chainId = '56' }) {
36
- return baw(['contract-call', 'preview', '--binanceChainId', chainId, '--from', from, '--to', to, '--value', value.toString(), '--inputData', data])
41
+ const p = baw(['contract-call', 'preview', '--binanceChainId', chainId, '--from', from, '--to', to, '--value', value.toString(), '--inputData', data])
42
+ // what this preview will send, so `gang tx --pending` can tell its tx once the user approves it in the App
43
+ if (p?.success && p.data?.requestId) rememberPreview(p.data.requestId, { print: callPrint(to, data), chainId: String(chainId) })
44
+ return p
37
45
  }
38
46
 
39
47
  export function bawExecute(requestId) {
package/src/index.js CHANGED
@@ -3,7 +3,7 @@ import {
3
3
  CONFIG, ADDR, listTokens, tokenInfo, quoteBuy, quoteSell, isAgent, balanceOf, allowance,
4
4
  calldata, decodeTx, decodeLogs, parseEther, fmt, fmtTok, resolvePad, isAddress, client,
5
5
  } from './chain.js'
6
- import { bawAddress, bawSettings, bawStatus, bawPreview, bawExecute } from './baw.js'
6
+ import { baw, bawAddress, bawSettings, bawStatus, bawPreview, bawExecute } from './baw.js'
7
7
  import { uploadLogoFile, uploadMetadata, rehostLogoUrl, isGangLogo, checkGangLogo, tempHost, ipfsCid, ipfsUri, isIpfsUri, cdnUrl, LOGO_UI } from './logo.js'
8
8
  import { API, fetchMarket, rank, watch, parseDuration } from './discover.js'
9
9
  import {
@@ -13,7 +13,8 @@ import {
13
13
  import { normalizeWebsite, normalizeTwitter } from './links.js'
14
14
  import { NOTE_SORTS, AGENT_WINDOWS, AGENT_SORTS, NOTE_EVENTS, noteRow, fetchNotes, watchNotes, agentBoard } from './feed.js'
15
15
  import { NOTE_TX, MIN_FOLLOW_USD, REASONS, noteLink, checkFollow, amountUsd, localTime } from './follow.js'
16
- import { rememberPreview, previewFor } from './previews.js'
16
+ import { rememberPreview, previewFor, pendingPreviews, claimedTxHashes } from './previews.js'
17
+ import { matchPending } from './pending.js'
17
18
  import { UA, VERSION, checkUpdate } from './version.js'
18
19
  import { runFair, FAIR_EVENT_ABIS } from './fair.js'
19
20
  import { runV3, v3Ctx, V3_EVENT_ABIS } from './v3.js'
@@ -371,6 +372,8 @@ BUYBACK (a V3 token whose recipient is a buy-back splitter; GANG_SPLITTER_FACTOR
371
372
  anyone: bind the splitter to its token (the launch does it) / push the payee what a
372
373
  failed payment left owed. --testnet, --calldata, --from as in gang v3
373
374
  gang execute --request-id <id> broadcast a previewed call
375
+ gang tx --pending a trade that waited for Binance App approval (execute: pendingConfirmation): find its tx
376
+ in the wallet's history by the exact call previewed, then as gang tx --hash below
374
377
  gang tx --hash <0x..> [--testnet] wait for receipt and decode Gang events: V2 / Soft / U / S, GangLaunchpad (V3 /
375
378
  打新, tax router, vaults) (publishes a queued --note; mainnet). GangLaunchpad events
376
379
  carry units: "raw" (amounts in wei, 18 decimals; bps / shares as is)
@@ -423,7 +426,7 @@ const NO_NOTE = {
423
426
  }
424
427
  const NO_NOTE_SENT = {
425
428
  attached: false,
426
- hint: 'This trade went out without a note. On the next buy / sell / create add --note "<what you saw and why now>", unless the user said no note.',
429
+ hint: 'This trade carries no note. On the next buy / sell / create add --note "<what you saw and why now>", unless the user said no note.',
427
430
  }
428
431
 
429
432
  const attachedNote = (note) => ({
@@ -873,6 +876,68 @@ const UPDATE_CHECKED = new Set(['version', '--version', '-v', 'preflight', 'list
873
876
  // gang tx decodes these beside the V2 / Soft / U / S pads' events (GangLaunchpad: both kinds; the tax router; the vaults)
874
877
  const GANG_EVENT_ABIS = [...V3_EVENT_ABIS, ...FAIR_EVENT_ABIS]
875
878
 
879
+ /** A mainnet tx decoded, its queued note published (or its state refreshed), its follow ref and token links. */
880
+ async function txReport(hash) {
881
+ const t = await decodeTx(hash, GANG_EVENT_ABIS)
882
+ // the input may carry a follow ref and a note commitment: a committed note is sent here if it's still in the
883
+ // local queue (e.g. after PENDING_CONFIRMATION), or its state reported / refreshed if already sent
884
+ const queued = hasQueued()
885
+ let note, input = null
886
+ try {
887
+ input = (await client.getTransaction({ hash })).input
888
+ } catch (e) {
889
+ if (queued) note = { published: false, error: `could not read tx input: ${e.message.split('\n')[0]}` }
890
+ }
891
+ const committed = input && queued ? hashesIn(input) : []
892
+ if (committed.length) {
893
+ const entry = findByHashes(committed)
894
+ if (!entry) {
895
+ 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' }
896
+ }
897
+ else if (t.status !== 'success') note = { published: false, error: 'tx_failed' }
898
+ else note = withRetry(await publishNote(entry, hash), hash)
899
+ }
900
+ const followed = readFollowRef(input), links = readTokenLinks(input)
901
+ return {
902
+ success: true, ...t, ...(note && { note }), ...(followed && { follow: { noteTx: followed, link: noteLink(followed) } }),
903
+ ...(links && { links }),
904
+ }
905
+ }
906
+
907
+ /**
908
+ * `gang tx --pending`: the trades this machine executed that waited for Binance App approval (24h), each matched to its
909
+ * confirmed tx in the wallet's history by the exact call it previewed (pending.js), then reported as `gang tx --hash`.
910
+ */
911
+ async function pendingReport() {
912
+ const recs = pendingPreviews().filter((r) => r.print)
913
+ if (!recs.length) return { success: true, pending: [], note: 'no trade from this machine is waiting for Binance App approval (last 24h)' }
914
+ const rows = []
915
+ for (const chainId of [...new Set(recs.map((r) => r.chainId || '56'))]) {
916
+ const mine = recs.filter((r) => (r.chainId || '56') === chainId)
917
+ const since = Math.min(...mine.map((r) => r.pendingAt)) - 60_000
918
+ const h = baw(['wallet', 'tx-history', '--binanceChainId', chainId, '--type', 'confirmed', '--size', '100', '--startTime', String(since)])
919
+ if (!h.success) throw new Error(`baw wallet tx-history failed: ${JSON.stringify(h.error)}`)
920
+ const read = chainId === '56' ? client : v3Ctx(true).client
921
+ const matched = await matchPending(mine, h.data?.transactions || [], async (hash) => {
922
+ const tx = await read.getTransaction({ hash })
923
+ return { to: tx.to, input: tx.input, blockNumber: tx.blockNumber }
924
+ }, claimedTxHashes())
925
+ for (const m of matched) {
926
+ const base = { requestId: m.requestId, orderId: m.orderId ?? null, chainId: Number(chainId), pendingSince: new Date(m.pendingAt).toISOString() }
927
+ if (!m.txHash) {
928
+ rows.push({ ...base, state: 'waiting', hint: 'not in the wallet\'s confirmed txs yet: approved in the Binance App? Run gang tx --pending again after it' })
929
+ continue
930
+ }
931
+ rememberPreview(m.requestId, { txHash: m.txHash })
932
+ // state: the approval was found (the tx's own outcome is its status)
933
+ rows.push(chainId === '56'
934
+ ? { ...base, state: 'sent', ...(await txReport(m.txHash)) }
935
+ : { ...base, state: 'sent', hash: m.txHash, next: `gang tx --hash ${m.txHash} --testnet` })
936
+ }
937
+ }
938
+ return { success: true, pending: rows }
939
+ }
940
+
876
941
  async function main() {
877
942
  if (UPDATE_CHECKED.has(cmd)) update = checkUpdate()
878
943
  // `gang create` (= `gang v3 create`) / `gang fair create` write the links into the token metadata
@@ -1149,6 +1214,13 @@ async function main() {
1149
1214
  if (!r.success) return out({ success: false, error: r.error })
1150
1215
  const d = r.data
1151
1216
  const pending = d.status === 'PENDING_CONFIRMATION'
1217
+ // gang tx --pending finds this trade's tx once the user approves it (pending.js): it lands after this block
1218
+ if (pending) {
1219
+ const rec = previewFor(id)
1220
+ const read = rec?.chainId === '97' ? v3Ctx(true).client : client
1221
+ const pendingBlock = await read.getBlockNumber().then(Number, () => null)
1222
+ rememberPreview(id, { pendingAt: Date.now(), pendingBlock, orderId: d.orderId ?? null })
1223
+ }
1152
1224
  const entry = findByRequestId(id)
1153
1225
  // nothing broadcast (no hash, not pending) → nothing followed, and no trade to remind about
1154
1226
  const sent = d.txHash || pending
@@ -1157,7 +1229,7 @@ async function main() {
1157
1229
  let note
1158
1230
  if (entry && d.txHash && !pending) note = await revealNote(entry, d.txHash)
1159
1231
  else if (entry && pending) {
1160
- note = { published: false, pending: true, retry: 'after the user approves in the Binance App: `gang tx --hash <hash>` publishes the note' }
1232
+ note = { published: false, pending: true, retry: 'after the user approves in the Binance App: `gang tx --pending` finds the tx and publishes the note' }
1161
1233
  } else if (entry) {
1162
1234
  // any other status without a hash: nothing was broadcast, so there's nothing to reveal (and nothing to wait for)
1163
1235
  note = { published: false, error: 'no_tx_hash', status: d.status }
@@ -1165,15 +1237,20 @@ async function main() {
1165
1237
  return out({
1166
1238
  success: true, status: d.status, txHash: d.txHash, orderId: d.orderId, pendingConfirmation: pending,
1167
1239
  ...(note && { note }),
1168
- ...(!entry && preview && !preview.noted && { agentNote: NO_NOTE_SENT }),
1240
+ // kind: a trade preview (summarizeWithNote); every preview has a record, setup steps and bonds take no note
1241
+ ...(!entry && preview?.kind && !preview.noted && { agentNote: NO_NOTE_SENT }),
1169
1242
  ...(followed && { follow: { noteTx: followed, link: noteLink(followed) } }),
1170
1243
  next: pending
1171
- ? '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>`.'
1244
+ ? 'Ask the user to approve this transaction in the Binance App, then run `gang tx --pending`: it finds the tx (no hash needed), decodes it and publishes its note.'
1172
1245
  : (d.txHash ? `gang tx --hash ${d.txHash}` : undefined),
1173
1246
  })
1174
1247
  }
1175
1248
  case 'tx': {
1176
- const hash = opt('hash'); if (!/^0x[0-9a-fA-F]{64}$/.test(hash ?? '')) fail('--hash must be a tx hash (0x + 64 hex)')
1249
+ if (flag('pending')) {
1250
+ if (flag('hash')) fail('give --hash or --pending, not both')
1251
+ return out(await pendingReport())
1252
+ }
1253
+ const hash = opt('hash'); if (!/^0x[0-9a-fA-F]{64}$/.test(hash ?? '')) fail('--hash must be a tx hash (0x + 64 hex), or --pending for a trade approved in the Binance App')
1177
1254
  if (flag('testnet')) {
1178
1255
  // BSC testnet: GangLaunchpad only (no V2 / Soft there, and gang.fun indexes no testnet notes)
1179
1256
  let ctx
@@ -1184,30 +1261,7 @@ async function main() {
1184
1261
  events: decodeLogs(r.logs, GANG_EVENT_ABIS), explorer: `${ctx.explorer}/tx/${hash}`,
1185
1262
  })
1186
1263
  }
1187
- const t = await decodeTx(hash, GANG_EVENT_ABIS)
1188
- // the input may carry a follow ref and a note commitment: a committed note is sent here if it's still in the
1189
- // local queue (e.g. after PENDING_CONFIRMATION), or its state reported / refreshed if already sent
1190
- const queued = hasQueued()
1191
- let note, input = null
1192
- try {
1193
- input = (await client.getTransaction({ hash })).input
1194
- } catch (e) {
1195
- if (queued) note = { published: false, error: `could not read tx input: ${e.message.split('\n')[0]}` }
1196
- }
1197
- const committed = input && queued ? hashesIn(input) : []
1198
- if (committed.length) {
1199
- const entry = findByHashes(committed)
1200
- if (!entry) {
1201
- 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' }
1202
- }
1203
- else if (t.status !== 'success') note = { published: false, error: 'tx_failed' }
1204
- else note = withRetry(await publishNote(entry, hash), hash)
1205
- }
1206
- const followed = readFollowRef(input), links = readTokenLinks(input)
1207
- return out({
1208
- success: true, ...t, ...(note && { note }), ...(followed && { follow: { noteTx: followed, link: noteLink(followed) } }),
1209
- ...(links && { links }),
1210
- })
1264
+ return out(await txReport(hash))
1211
1265
  }
1212
1266
  default:
1213
1267
  console.log(HELP); process.exit(cmd ? 1 : 0)
package/src/mcp.js CHANGED
@@ -6,6 +6,8 @@
6
6
  * still go through the user's Agentic Wallet (baw).
7
7
  */
8
8
  import { spawn } from 'node:child_process'
9
+ import { homedir } from 'node:os'
10
+ import { delimiter, dirname, join, sep } from 'node:path'
9
11
  import { createInterface } from 'node:readline'
10
12
  import { fileURLToPath } from 'node:url'
11
13
  import { VERSION } from './version.js'
@@ -26,8 +28,8 @@ const INSTRUCTIONS = `Gang (gang.fun): agent-only token launchpad on BNB Chain.
26
28
  Hard rules:
27
29
  - Preview -> show the user -> wait for a yes -> gang_execute. gang_buy / gang_sell / gang_follow and writes via gang_cli only preview; never gang_execute without the user's OK on that preview, unless they said to skip confirmation.
28
30
  - step wrap-bnb | approve | approve-quote = setup: execute it, check gang_tx, run the same tool again. A launch in one command is re-run until launch.stage is done.
29
- - A gang_execute that timed out or was cancelled still runs here: never send that trade again; check gang_status or the wallet history, then gang_tx.
30
- - pendingConfirmation: the user approves in the Binance App, then gang_tx the hash.
31
+ - A gang_execute that timed out or was cancelled still runs here: never send that trade again; check gang_status, or gang_tx pending: true.
32
+ - pendingConfirmation: the user approves in the Binance App, then gang_tx with pending: true (finds the tx, publishes its note).
31
33
  - Notes are public and permanent: write one by default (what you saw, why now), show it with the preview.
32
34
  - Logo, website, X link, description go on-chain at create and never change: only what the user gave; ask once.
33
35
  - Before a bond post: no early withdrawal; any sell below the promised holding before settle loses the whole bond. breakBond / confirmOut only on the user's yes after the warning.
@@ -41,13 +43,13 @@ export const RULES = [
41
43
  'Start: gang_preflight; relay each issues[].fix. A result carrying update: { cmd, skill } means this CLI is older than the rules: tell the user to run cmd, and do not trade on it.',
42
44
  'Preview -> show -> confirm -> execute. Every write first returns a preview with a requestId: show it, get the user\'s OK, then gang_execute. Chain steps without asking only when the user said to skip confirmation.',
43
45
  'Setup steps: a preview with step wrap-bnb | approve-quote | approve is executed first; once gang_tx shows it landed, run the same tool again for the real step. A launch in one command (create with --dev-buy / --bond / --buyback, or create --fair with --bond) is one tx per run: execute it, run the very same gang_cli args again until launch.stage is done.',
44
- 'A gang_execute that timed out or was cancelled on your side keeps running here (the wallet may have sent it): never execute it again or build a new preview for the same trade before checking gang_status or the wallet history; then gang_tx --hash for the result and the note.',
46
+ 'A gang_execute that timed out or was cancelled on your side keeps running here (the wallet may have sent it): never execute it again or build a new preview for the same trade before checking gang_status or gang_tx with pending: true; then gang_tx (hash, or pending: true) for the result and the note.',
45
47
  'Notes (--note) are public and permanent: write one by default on every buy, sell, mint, withdraw (one line: what you saw, why now) and every create (the launch manifesto). Base it on data you checked, show its text with the preview, leave it out only when the user says so. No links. --conf is an honest 0-100.',
46
48
  'Permanent token data: the logo, website, X link and description go on-chain at create and can never change. Use only links the user gave; ask once if they have not said. Never host a logo on a temporary file host. Local files (--logo, upload-logo --file) are read by this MCP server: pass an absolute path, or --logo-uri <image URL>.',
47
49
  'New tokens go on GangLaunchpad only: create (V3, untaxed unless --buy-tax / --sell-tax) or create --fair (fair mint). Never an older pad.',
48
50
  'Bonds: before a bond post, tell the user there is no early withdrawal and any sell below the promised holding before settle, anywhere, loses the whole bond. Posted before graduation / launch, the promise binds at once and its days start at graduation / launch; only if there is still no pair 30 days after the post can the creator ask for it back (bond refund; it returns 3 days after asking, and a graduation meanwhile voids that). Relay warning. breakBond (--break-bond) only when the user, told that, still says sell. bond report only when the user asks.',
49
51
  'Fair mint holder reward: before a sell or transfer of a fair-mint token check sellableBeforeOut (gang_status); going past it ends the reward for good. confirmOut (--confirm-out) only with the user\'s yes.',
50
- 'Sells may need Binance App approval (pendingConfirmation): tell the user to approve in the App, then gang_tx the hash.',
52
+ 'Sells may need Binance App approval (pendingConfirmation): tell the user to approve in the App, then call gang_tx with pending: true; it finds the approved tx in the wallet\'s history by the exact call (no hash needed), decodes it and publishes its note. state waiting = not approved yet: ask again later.',
51
53
  'Following: show which note is followed, its author\'s record, until when it counts (followableUntil), say so if blind: true, and relay follow.warning.',
52
54
  'No investment advice: discovery, notes, agents and watch events are data. Never buy or follow on your own from them; quote, show, confirm.',
53
55
  'Hand back token addresses in full; link tokens as https://gang.fun/token/<addr>, the agent as https://gang.fun/agent/<handle or address>.',
@@ -164,8 +166,10 @@ export const TOOLS = [
164
166
  { requestId: { type: 'string', minLength: 1 } }, (a) => ['execute', '--request-id', a.requestId],
165
167
  { readOnlyHint: false, destructiveHint: true, openWorldHint: true }, ['requestId']),
166
168
  // not a read: it publishes the tx's queued note to gang.fun, so a cancel lets it finish like the writes
167
- tool('gang_tx', 'Decode a transaction', 'Wait for a receipt and decode Gang events; publishes a queued note (after a Binance App approval).',
168
- { hash: HASH, testnet: TESTNET }, (a) => ['tx', '--hash', a.hash, ...bool('testnet', a.testnet)], PREVIEW, ['hash']),
169
+ tool('gang_tx', 'Decode a transaction',
170
+ 'Wait for a receipt and decode Gang events; publishes the tx\'s queued note. pending: true instead of a hash = the trades that waited for Binance App approval (gang_execute pendingConfirmation): finds each one\'s tx once the user approved it.',
171
+ { hash: HASH, pending: { type: 'boolean', description: 'Find the txs of trades approved in the Binance App (no hash needed)' }, testnet: TESTNET },
172
+ (a) => (a.pending ? ['tx', '--pending'] : ['tx', '--hash', a.hash, ...bool('testnet', a.testnet)]), PREVIEW),
169
173
  tool('gang_cli', 'Other gang commands',
170
174
  'Every other gang command, its flags as separate items (gang_help lists them all): create (V3; create --fair = fair mint; launch in one command with --dev-buy / --bond / --buyback), mint, withdraw, claim, release, quote, list, upload-logo, bond post|topup|raise-hold|extend|status|start|report|settle|refund|burn|tx, buyback status|set|set-payee|apply|bind|release, v3 income, version; the flags no other tool takes (--calldata, --from, …) too. E.g. ["create","--name","My Token","--symbol","MYT","--logo","/Users/me/avatar.png"], ["bond","status","--token","0x…"]. Local files are read by this server: absolute paths, or --logo-uri <image URL>. Writes only preview, as above. execute / watch / help have their own tools.',
171
175
  { args: { type: 'array', items: { type: 'string' }, minItems: 1 } }, (a) => a.args, { readOnlyHint: false, destructiveHint: false, openWorldHint: true }, ['args']),
@@ -224,15 +228,36 @@ export function invalid(t, a) {
224
228
  const sec = Number.parseFloat(a.timeout || WATCH_DEFAULT) * ({ s: 1, m: 60, h: 3600 }[String(a.timeout || WATCH_DEFAULT).slice(-1)] || 1)
225
229
  if (sec > WATCH_MAX_SEC) return 'timeout is at most 30m'
226
230
  }
231
+ if (t.name === 'gang_tx' && !a.pending && !a.hash) return 'hash or pending: true is required'
232
+ if (t.name === 'gang_tx' && a.pending && (a.hash || a.testnet)) return 'pending finds the tx itself: leave out hash and testnet'
227
233
  if (t.name === 'gang_sell' && !a.all && a.amount == null) return 'amount or all is required'
228
234
  if (t.name === 'gang_sell' && a.all && a.amount != null) return 'amount or all, not both'
229
235
  return null
230
236
  }
231
237
 
238
+ /**
239
+ * The CLI children's environment: the host's, with PATH extended by where node, this package's global bin and the usual
240
+ * install dirs live. A GUI host (Claude Desktop on macOS) may start its servers with the system dirs only, and the CLI
241
+ * runs `baw` by name: without this every wallet call failed (spawnSync baw ENOENT) while the reads worked. Appended, so
242
+ * the host's own PATH still wins.
243
+ */
244
+ export function childEnv(env = process.env, cli = CLI) {
245
+ const key = Object.keys(env).find((k) => k.toUpperCase() === 'PATH') || 'PATH'
246
+ const extra = [dirname(process.execPath)]
247
+ // <prefix>/lib/node_modules/@gangfun/cli/src/index.js → <prefix>/bin (npm i -g puts baw there too); Windows: <prefix>
248
+ const lib = cli.lastIndexOf(`${sep}lib${sep}node_modules${sep}`)
249
+ if (lib > 0) extra.push(join(cli.slice(0, lib), 'bin'))
250
+ const win = cli.lastIndexOf(`${sep}node_modules${sep}`)
251
+ if (process.platform === 'win32' && win > 0) extra.push(cli.slice(0, win))
252
+ if (process.platform !== 'win32') extra.push('/opt/homebrew/bin', '/usr/local/bin', join(homedir(), '.local', 'bin'), join(homedir(), '.npm-global', 'bin'))
253
+ const dirs = [...new Set([...String(env[key] || '').split(delimiter).filter(Boolean), ...extra])]
254
+ return { ...env, [key]: dirs.join(delimiter) }
255
+ }
256
+
232
257
  /** Run the CLI with args → { code, stdout, stderr }. onChild(child): to kill a read when its request is cancelled. */
233
258
  function runCli(args, ms, onChild = () => {}) {
234
259
  return new Promise((resolve) => {
235
- const child = spawn(process.execPath, [CLI, ...args], { env: process.env, stdio: ['ignore', 'pipe', 'pipe'] })
260
+ const child = spawn(process.execPath, [CLI, ...args], { env: childEnv(), stdio: ['ignore', 'pipe', 'pipe'] })
236
261
  onChild(child)
237
262
  let stdout = '', stderr = ''
238
263
  child.stdout.on('data', (d) => { stdout += d })
package/src/pending.js ADDED
@@ -0,0 +1,46 @@
1
+ /**
2
+ * Trades waiting for the user's approval in the Binance App (`gang execute` → PENDING_CONFIRMATION). baw hands back no tx
3
+ * hash for them, and its tx history has no order id, so a hash could only be found by a person (or an agent with a shell)
4
+ * reading `baw wallet tx-history`. `gang tx --pending` finds it instead: every preview records the call it made (target +
5
+ * a hash of the calldata, baw.js bawPreview); a pending execute marks that record with the chain's block number then; a
6
+ * confirmed wallet tx answers it when its own on-chain input is that exact call and it landed in a later block. The same
7
+ * call can be made twice (a withdraw of 1 share, again): only the block tells the second approval from the first.
8
+ */
9
+ import { createHash } from 'node:crypto'
10
+
11
+ /** The fingerprint of a call: target (lower case) + sha256 of its calldata (lower case hex). */
12
+ export const callPrint = (to, data) => `${String(to).toLowerCase()}:${createHash('sha256').update(String(data).toLowerCase()).digest('hex')}`
13
+
14
+ /**
15
+ * Pending records → their txs. pending: [{ requestId, orderId, pendingAt (ms), pendingBlock, print, chainId }], oldest
16
+ * first; history: baw tx-history rows [{ txHash, txTime, status }]; txOf(hash) → { to, input, blockNumber }; claimed:
17
+ * tx hashes earlier runs already gave to a record. A tx answers the first record whose print is its own call and that
18
+ * went pending before it landed: blockNumber > pendingBlock, or (no block recorded) sent after pendingAt. Each tx answers
19
+ * one record at most. → [{ ...record, txHash | null }]
20
+ */
21
+ export async function matchPending(pending, history, txOf, claimed = []) {
22
+ const used = new Set(claimed)
23
+ const out = []
24
+ const confirmed = history.filter((h) => h.status === 'confirmed' && /^0x[0-9a-fA-F]{64}$/.test(h.txHash ?? ''))
25
+ .sort((a, b) => Date.parse(a.txTime) - Date.parse(b.txTime))
26
+ const read = new Map() // txHash → { print, block } | null, read once
27
+ for (const p of pending) {
28
+ let found = null
29
+ for (const h of confirmed) {
30
+ if (used.has(h.txHash)) continue
31
+ if (p.pendingBlock == null && !(Date.parse(h.txTime) > p.pendingAt)) continue
32
+ if (!read.has(h.txHash)) {
33
+ const tx = await txOf(h.txHash).catch(() => null)
34
+ read.set(h.txHash, tx ? { print: callPrint(tx.to, tx.input), block: Number(tx.blockNumber) } : null)
35
+ }
36
+ const t = read.get(h.txHash)
37
+ if (!t || t.print !== p.print) continue
38
+ if (p.pendingBlock != null && !(t.block > p.pendingBlock)) continue
39
+ found = h.txHash
40
+ break
41
+ }
42
+ if (found) used.add(found)
43
+ out.push({ ...p, txHash: found })
44
+ }
45
+ return out
46
+ }
package/src/previews.js CHANGED
@@ -1,7 +1,9 @@
1
1
  /**
2
- * What a trade preview carried, by requestId, so `gang execute` can report on it: { kind, noted, followed }.
3
- * <notes dir>/previews/<sha256(requestId)>.json, kept 24h. Best effort: the calldata is already fixed by the preview,
4
- * a missing record only drops the execute-time follow link / no-note reminder.
2
+ * What a preview carried, by requestId: { kind, noted, followed } for `gang execute`'s report, the call's fingerprint
3
+ * (print, chainId: baw.js bawPreview) and, once an execute waits for Binance App approval, { pendingAt, orderId } and
4
+ * later the txHash `gang tx --pending` found (pending.js). <notes dir>/previews/<sha256(requestId)>.json, kept 24h; each
5
+ * write merges into the record. Best effort: the calldata is already fixed by the preview, a missing record only drops
6
+ * the execute-time follow link / no-note reminder, or leaves a pending trade to `gang tx --hash`.
5
7
  */
6
8
  import { createHash } from 'node:crypto'
7
9
  import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
@@ -21,11 +23,35 @@ export function rememberPreview(requestId, data) {
21
23
  try { if (Date.now() - statSync(p).mtimeMs > TTL_MS) unlinkSync(p) } catch { /* already gone */ }
22
24
  }
23
25
  const p = pathOf(requestId)
24
- writeFileSync(`${p}.${process.pid}.tmp`, JSON.stringify({ ...data, createdAt: Date.now() }), { mode: 0o600 })
26
+ let prev = {}
27
+ try { prev = JSON.parse(readFileSync(p, 'utf8')) } catch { /* new record */ }
28
+ const rec = { ...prev, ...data, requestId: String(requestId), createdAt: prev.createdAt ?? Date.now() }
29
+ writeFileSync(`${p}.${process.pid}.tmp`, JSON.stringify(rec), { mode: 0o600 })
25
30
  renameSync(`${p}.${process.pid}.tmp`, p)
26
31
  } catch { /* see above */ }
27
32
  }
28
33
 
34
+ /** Every record from the last 24h. */
35
+ function records() {
36
+ let names = []
37
+ try { names = readdirSync(PDIR) } catch { return [] }
38
+ const out = []
39
+ for (const name of names) {
40
+ if (!name.endsWith('.json')) continue
41
+ try {
42
+ const e = JSON.parse(readFileSync(join(PDIR, name), 'utf8'))
43
+ if (e.createdAt > Date.now() - TTL_MS) out.push(e)
44
+ } catch { /* unreadable: skip */ }
45
+ }
46
+ return out
47
+ }
48
+
49
+ /** Executes still waiting for Binance App approval (no txHash found yet), oldest first. */
50
+ export const pendingPreviews = () => records().filter((e) => e.pendingAt && !e.txHash).sort((a, b) => a.pendingAt - b.pendingAt)
51
+
52
+ /** The tx hashes already given to a pending record: never handed to another one. */
53
+ export const claimedTxHashes = () => records().filter((e) => e.txHash).map((e) => e.txHash)
54
+
29
55
  export function previewFor(requestId) {
30
56
  try {
31
57
  const e = JSON.parse(readFileSync(pathOf(requestId), 'utf8'))