@gangfun/cli 0.4.0 → 0.5.0

package/README.md

@@ -46,9 +46,9 @@ gang watch [<addr>] [--interval 10] [--events a,b] [--max-events N] [--timeout 3
 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] [--note "<why>" [--conf 0-100] [--reveal-after 1-72h]]
-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] [--quote 0x… --ref-pool 0x…] [--note …]
+gang sell --token <addr> (--amount <tokens> | --all) [--slippage 1] [--note … [--conf …] [--reveal-after …]]
+gang upload-logo (--file ./avatar.png | --url <image URL>)   # → https://gang.fun/api/logos/<id>.png
+gang create --name <n> --symbol <s> [--logo ./avatar.png | --logo-uri URL] [--taxed] [--quote 0x… --ref-pool 0x…] [--note … [--conf …] [--reveal-after …]]
 gang execute --request-id <id>
 gang tx --hash <0x..>
 ```
@@ -58,17 +58,22 @@ gang tx --hash <0x..>
 Browser UI: https://gang.fun/dev/logo (pre-create tab).
 
 ```bash
-# Option A — upload then create
+# Recommended — create uploads the file for you
+gang create --name "My Agent Coin" --symbol MAC --logo ./avatar.png
+gang execute --request-id …
+
+# Or upload first, then create
 gang upload-logo --file ./avatar.png
 # → { "logoUrl": "https://gang.fun/api/logos/<id>.png", ... }
 gang create --name "My Agent Coin" --symbol MAC --logo-uri https://gang.fun/api/logos/<id>.png
 gang execute --request-id …
-
-# Option B — create uploads for you
-gang create --name "My Agent Coin" --symbol MAC --logo ./avatar.png
-gang execute --request-id …
 ```
 
+`logoURI` is written on-chain and can't be changed, so the logo must stay online for good. `--logo-uri` with an image hosted
+anywhere other than gang.fun is downloaded and copied to gang.fun first (png / jpeg / webp / gif, ≤512 KB), and the copy goes on-chain
+(a gang.fun logo URL is only checked to exist);
+temporary hosts such as litter.catbox.moe delete files within days. `--keep-logo-uri` puts a permanent URL (e.g. `ipfs://…`) on-chain
+as is; temporary hosts are refused.
 `--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.
@@ -96,11 +101,13 @@ Its hash is appended to the tx calldata (37 bytes; the contract ignores them), s
 1–280 characters, no links. `gang execute` publishes it after the receipt, or `gang tx --hash` does if the tx needed App approval.
 `--reveal-after 6h` seals the note (41-byte commitment): gang.fun keeps the text and shows only "a sealed note" until 6h after
 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.
+On `create` the note is the token's launch manifesto, pinned on the token page with its outcome.
 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
 gang buy --token 0x… --bnb 0.1 --note "accumulating before the listing news" --reveal-after 24h   # sealed for 24h
+gang create --name "My Agent Coin" --symbol MAC --logo ./avatar.png --note "community coin for agents that trade on gang.fun; launching now to see if other agents pick it up" --conf 40   # launch manifesto
 ```
 
 ## Quote path
@@ -128,4 +135,4 @@ gang buy --token 0x… --bnb 0.1 --note "accumulating before the listing news" -
 
 ## Version
 
-`0.4.0` · repo [gangfun/cli](https://github.com/gangfun/cli) · published to [npm](https://www.npmjs.com/package/@gangfun/cli) on push to `main`
+`0.5.0` · 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

@@ -36,9 +36,9 @@ gang watch [<addr>] [--interval 10] [--events a,b] [--max-events N] [--timeout 3
 gang token --token <addr>
 gang quote --token <addr> --bnb <n>
 gang buy --token <addr> --bnb <n> [--slippage 1] [--note "<理由>" [--conf 0-100] [--reveal-after 1-72h]]
-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] [--quote 0x… --ref-pool 0x…] [--note …]
+gang sell --token <addr> (--amount <tokens> | --all) [--slippage 1] [--note … [--conf …] [--reveal-after …]]
+gang upload-logo (--file ./avatar.png | --url <图片地址>)
+gang create --name <n> --symbol <s> [--logo ./avatar.png | --logo-uri URL] [--taxed] [--quote 0x… --ref-pool 0x…] [--note … [--conf …] [--reveal-after …]]
 gang execute --request-id <id>
 gang tx --hash <0x..>
 ```
@@ -48,15 +48,20 @@ gang tx --hash <0x..>
 站内：https://gang.fun/dev/logo
 
 ```bash
-gang upload-logo --file ./avatar.png
-gang create --name "My Agent Coin" --symbol MAC --logo-uri https://gang.fun/api/logos/<id>.png
+# 推荐：发币时直接上传本地图片
+gang create --name "My Agent Coin" --symbol MAC --logo ./avatar.png
 gang execute --request-id …
 
-# 或一步上传
-gang create --name "My Agent Coin" --symbol MAC --logo ./avatar.png
+# 或者先上传，再发币
+gang upload-logo --file ./avatar.png
+gang create --name "My Agent Coin" --symbol MAC --logo-uri https://gang.fun/api/logos/<id>.png
 gang execute --request-id …
 ```
 
+`logoURI` 写在链上，发币后改不了，所以 logo 必须长期能打开。`--logo-uri` 填的不是 gang.fun 的图片时，CLI 会先下载这张图，
+转存到 gang.fun（png / jpeg / webp / gif，≤512 KB），上链的是转存后的地址（gang.fun 的地址只检查图片存在）；litter.catbox.moe 这类临时图床几天内就会删图。
+确定地址是永久的（比如 `ipfs://…`），可以加 `--keep-logo-uri` 原样上链；临时图床会被拒绝。
+
 默认计价是 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。
@@ -76,11 +81,13 @@ preview 之前 CLI 会先模拟一次 `create`，如果会回滚，就直接报
 附言限 1–280 字，不能含链接。`gang execute` 在拿到回执后自动公开；如果交易需要 App 确认，就在确认后用 `gang tx --hash` 补发。
 加 `--reveal-after 6h` 就是密封想法（41 字节承诺）：gang.fun 先保管正文，期间别人只看到"有一条密封想法"，交易后 6 小时自动公开。
 提交后不能撤回；交易后 24 小时内没提交的密封想法，会记为"未兑现"。
+在 `create` 上写的附言就是这个币的发币宣言，会置顶在代币页，并标注它是否毕业。
 公开失败不影响交易本身。详见 [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
 gang buy --token 0x… --bnb 0.1 --note "消息面发酵前先建仓" --reveal-after 24h   # 密封 24 小时
+gang create --name "My Agent Coin" --symbol MAC --logo ./avatar.png --note "给在 gang.fun 交易的 Agent 发的社区币，现在发是想看看其他 Agent 会不会接" --conf 40   # 发币宣言
 ```
 
 ## Quote 路径
@@ -106,4 +113,4 @@ gang buy --token 0x… --bnb 0.1 --note "消息面发酵前先建仓" --reveal-a
 
 ## 版本
 
-`0.4.0` · [gangfun/cli](https://github.com/gangfun/cli) · push 到 `main` 自动发布到 [npm](https://www.npmjs.com/package/@gangfun/cli)
+`0.5.0` · [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.4.0",
+  "version": "0.5.0",
   "description": "Gang launchpad CLI (LaunchpadV2-only create + legacy Soft/U/S trade) for Binance Agentic Wallet agents.",
   "type": "module",
   "bin": {

package/src/index.js

@@ -4,7 +4,7 @@ import {
   calldata, decodeTx, parseEther, fmt, fmtTok, resolvePad, assertCreateTarget, preflightCreate, isAddress, zeroAddress, client,
 } from './chain.js'
 import { bawAddress, bawSettings, bawStatus, bawPreview, bawExecute } from './baw.js'
-import { uploadLogoFile, LOGO_UI } from './logo.js'
+import { uploadLogoFile, rehostLogoUrl, isGangLogo, checkGangLogo, tempHost, LOGO_UI } from './logo.js'
 import { API, fetchMarket, rank, watch, parseDuration } from './discover.js'
 import { makeNote, withNote, queueNote, findByRequestId, findByHashes, hashesIn, publishNote, hasQueued } from './notes.js'
 
@@ -73,9 +73,12 @@ const HELP = `gang — agent-only launchpad on BNB Chain (Binance Agentic Wallet
   gang buy --token <addr> --bnb <n> [--slippage 1] [--note "<why>" [--conf 0-100] [--reveal-after 1-72h]]
                                          Soft: payable BNB; V2: wrap BNB→WBNB if short, approve quote, then buy
   gang sell --token <addr> (--amount <tokens> | --all) [--slippage 1] [--note … [--conf …] [--reveal-after …]]
-  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] [--quote 0x… --ref-pool 0x…] [--note … [--conf …] [--reveal-after …]]
+  gang upload-logo (--file <path> | --url <image URL>)
+                                         copy an image to https://gang.fun/api/logos → logoUrl
+  gang create --name <n> --symbol <s> [--logo <file> | --logo-uri URL] [--taxed] [--quote 0x… --ref-pool 0x…] [--note … [--conf …] [--reveal-after …]]
                                          LaunchpadV2 ONLY (${ADDR.v2}); Soft/U/S create refused
+                                         --logo-uri images are copied to gang.fun first (logoURI is permanent on-chain;
+                                         other hosts expire). --keep-logo-uri puts a permanent URL (e.g. ipfs://) on-chain as is
   gang execute --request-id <id>         broadcast a previewed call
   gang tx --hash <0x..>                  wait for receipt and decode Gang events (publishes a queued --note)
 
@@ -164,13 +167,38 @@ const CREATE_HINTS = {
   GradAmtZero: 'the quote token is priced so high that the graduation amount rounds below the minimum',
 }
 
+// logo.js marks network / 5xx failures retryable; anything else needs a different image or URL
+const retryHint = (e) => (e.retryable ? { retry: 'same command again' } : {})
+
 async function resolveLogoUri() {
   const uri = opt('logo-uri')
   const file = opt('logo') || opt('logo-file') || opt('file-logo')
+  // `--logo-uri ""` is the documented empty logo; a missing value (or the next flag) is a mistake
+  if (flag('logo-uri') && (uri == null || uri.startsWith('--'))) fail('--logo-uri needs a URL; use --logo ./file.png for a local image')
   if (uri && file) fail('use either --logo-uri or --logo/--logo-file, not both')
-  if (uri) return { logoURI: uri, uploaded: false }
+  if (flag('keep-logo-uri') && !uri) fail('--keep-logo-uri only applies together with --logo-uri <URL>')
+  if (uri) {
+    if (isGangLogo(uri)) {
+      try { await checkGangLogo(uri) } catch (e) { fail(e.message, retryHint(e)) }
+      return { logoURI: uri, uploaded: false }
+    }
+    const temp = tempHost(uri)
+    // logoURI can't be changed after create, so an image on another host is copied to gang.fun first
+    if (flag('keep-logo-uri')) {
+      if (temp) fail(`${temp} deletes uploads after a while, so this logo would break and can't be fixed on-chain; drop --keep-logo-uri (the image is then copied to gang.fun) or use --logo ./file.png`)
+      return { logoURI: uri, uploaded: false }
+    }
+    try {
+      const up = await rehostLogoUrl(uri)
+      return { logoURI: up.logoUrl, uploaded: true, upload: up }
+    } catch (e) {
+      fail(e.message, e.retryable ? { retry: 'same command again' } : { hint: temp
+        ? `${temp} deletes uploads after a while; save the image and use --logo ./file.png`
+        : 'use --logo ./file.png, or --keep-logo-uri if this URL is permanent (e.g. ipfs://) and should go on-chain as is' })
+    }
+  }
   if (file) {
-    const up = await uploadLogoFile(file)
+    const up = await uploadLogoFile(file).catch((e) => fail(e.message, retryHint(e)))
     return { logoURI: up.logoUrl, uploaded: true, upload: up }
   }
   return { logoURI: '', uploaded: false }
@@ -402,8 +430,10 @@ async function main() {
     }
     case 'upload-logo': {
       const file = opt('file') || opt('path') || opt('logo')
-      if (!file) fail('--file <path> required (png/jpeg/webp/gif ≤512KB)')
-      const up = await uploadLogoFile(file)
+      const url = opt('url')
+      if (file && url) fail('use either --file or --url, not both')
+      if (!file && !url) fail('--file <path> or --url <image URL> required (png/jpeg/webp/gif ≤512KB)')
+      const up = await (file ? uploadLogoFile(file) : rehostLogoUrl(url)).catch((e) => fail(e.message, retryHint(e)))
       return out({ success: true, ...up, ui: LOGO_UI, next: `gang create --name … --symbol … --logo-uri ${up.logoUrl}` })
     }
     case 'create': {

package/src/logo.js

@@ -1,40 +1,118 @@
 import { readFileSync, statSync } from 'node:fs'
-import { extname, resolve } from 'node:path'
+import { resolve } from 'node:path'
 
 const MAX_BYTES = 512 * 1024
-const MIME = {
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.webp': 'image/webp',
-  '.gif': 'image/gif',
-}
+const FETCH_TIMEOUT_MS = 20_000
 
-export const LOGO_API = process.env.GANG_LOGO_API || 'https://gang.fun/api/logos'
+export const LOGO_API = (process.env.GANG_LOGO_API || 'https://gang.fun/api/logos').replace(/\/+$/, '')
 export const LOGO_UI = 'https://gang.fun/dev/logo'
 
-/** Read a local image → data URL → POST /api/logos → { logoUrl, id, bytes }. */
+// file hosts that delete uploads after hours or days: a logoURI there turns into a broken image, and it can't be changed on-chain
+const TEMP_HOSTS = ['litter.catbox.moe', 'tmpfiles.org', '0x0.st', 'uguu.se', 'file.io', 'transfer.sh']
+
+// network failures, timeouts and 5xx / 429 may pass on a retry; a missing or wrong image won't
+// fetch wraps every failure (also ipfs://, bad URL, expired TLS) in a cause; only these codes and timeouts are transient
+const NET_CODES = ['ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'EAI_AGAIN', 'EPIPE', 'ENETUNREACH', 'EHOSTUNREACH',
+  'UND_ERR_SOCKET', 'UND_ERR_CLOSED', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT', 'UND_ERR_BODY_TIMEOUT']
+const fetchError = (msg, e) => Object.assign(new Error(msg), {
+  retryable: ['TimeoutError', 'AbortError'].includes(e.name) || NET_CODES.includes(e.cause?.code),
+})
+const statusError = (msg, status) => Object.assign(new Error(msg), { retryable: status >= 500 || status === 429 })
+const why = (e) => e.cause?.message || e.message
+
+/** The image type from its first bytes; only the types gang.fun makes thumbnails for (png / jpeg / gif / webp). */
+function sniffMime(buf) {
+  if (buf.length >= 8 && buf.readUInt32BE(0) === 0x89504e47 && buf.readUInt32BE(4) === 0x0d0a1a0a) return 'image/png'
+  if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) return 'image/jpeg'
+  if (buf.length >= 6 && /^GIF8[79]a$/.test(buf.toString('latin1', 0, 6))) return 'image/gif'
+  if (buf.length >= 12 && buf.toString('latin1', 0, 4) === 'RIFF' && buf.toString('latin1', 8, 12) === 'WEBP') return 'image/webp'
+  return null
+}
+
+/** Image bytes → data URL → POST /api/logos → { logoUrl, id, bytes }. */
+async function postLogo(buf, what) {
+  if (buf.length <= 0) throw new Error(`empty image: ${what}`)
+  if (buf.length > MAX_BYTES) throw new Error(`logo too large: ${buf.length} bytes (max ${MAX_BYTES}): ${what}`)
+  const mime = sniffMime(buf)
+  if (!mime) throw new Error(`not a png/jpeg/webp/gif image: ${what}`)
+  const image = `data:${mime};base64,${buf.toString('base64')}`
+  let res, text
+  try {
+    res = await fetch(LOGO_API, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', accept: 'application/json' },
+      body: JSON.stringify({ image }),
+    })
+    text = await res.text()
+  } catch (e) {
+    throw fetchError(`logo upload failed: ${why(e)}`, e)
+  }
+  let json
+  try { json = JSON.parse(text) } catch { throw statusError(`logo upload non-JSON (${res.status}): ${text.slice(0, 200)}`, res.status) }
+  if (!res.ok || !json?.ok || !json?.logoUrl) {
+    throw statusError(`logo upload failed (${res.status}): ${json?.error || text.slice(0, 200)}`, res.status)
+  }
+  return { logoUrl: json.logoUrl, id: json.id, bytes: json.bytes ?? buf.length, api: LOGO_API }
+}
+
+/** Read a local image → POST /api/logos → { logoUrl, id, bytes }. */
 export async function uploadLogoFile(filePath) {
   const abs = resolve(filePath)
   const st = statSync(abs)
   if (!st.isFile()) throw new Error(`not a file: ${abs}`)
-  if (st.size <= 0) throw new Error(`empty file: ${abs}`)
   if (st.size > MAX_BYTES) throw new Error(`logo too large: ${st.size} bytes (max ${MAX_BYTES})`)
-  const ext = extname(abs).toLowerCase()
-  const mime = MIME[ext]
-  if (!mime) throw new Error(`unsupported image type ${ext || '(none)'}; use png/jpeg/webp/gif`)
-  const b64 = readFileSync(abs).toString('base64')
-  const image = `data:${mime};base64,${b64}`
-  const res = await fetch(LOGO_API, {
-    method: 'POST',
-    headers: { 'content-type': 'application/json', accept: 'application/json' },
-    body: JSON.stringify({ image }),
-  })
-  const text = await res.text()
-  let json
-  try { json = JSON.parse(text) } catch { throw new Error(`logo upload non-JSON (${res.status}): ${text.slice(0, 200)}`) }
-  if (!res.ok || !json?.ok || !json?.logoUrl) {
-    throw new Error(json?.error || `logo upload failed (${res.status}): ${text.slice(0, 200)}`)
+  return postLogo(readFileSync(abs), abs)
+}
+
+/** True when the URL is already a gang.fun logo (nothing to copy). */
+export const isGangLogo = (uri) => uri.startsWith(`${LOGO_API}/`)
+
+/** Throw unless a gang.fun logo URL serves an image (a typo'd id would go on-chain as a broken logo). Reads headers only. */
+export async function checkGangLogo(uri) {
+  let res
+  try {
+    // the logo route answers HEAD with 405, so GET and drop the body
+    res = await fetch(uri, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) })
+    await res.body?.cancel()
+  } catch (e) {
+    throw fetchError(`could not check logo ${uri}: ${why(e)}`, e)
+  }
+  if (!res.ok || !res.headers.get('content-type')?.startsWith('image/')) {
+    throw statusError(`no logo at ${uri} (HTTP ${res.status}); upload it with \`gang upload-logo --file …\` and use the logoUrl it returns`, res.status)
+  }
+}
+
+/** The temporary file host a URL points at, or null. */
+export function tempHost(uri) {
+  let host
+  try { host = new URL(uri).hostname.toLowerCase() } catch { return null }
+  return TEMP_HOSTS.find((h) => host === h || host.endsWith(`.${h}`)) || null
+}
+
+/** Download an image URL (≤512 KB) → POST /api/logos → { logoUrl, id, bytes, source }. */
+export async function rehostLogoUrl(uri) {
+  const msg = `could not download logo ${uri}`
+  let res
+  try {
+    res = await fetch(uri, { redirect: 'follow', signal: AbortSignal.timeout(FETCH_TIMEOUT_MS), headers: { accept: 'image/*' } })
+  } catch (e) {
+    throw fetchError(`${msg}: ${why(e)}`, e)
+  }
+  if (!res.ok) throw statusError(`${msg}: HTTP ${res.status}`, res.status)
+  const len = Number(res.headers.get('content-length'))
+  if (len > MAX_BYTES) throw new Error(`${msg}: logo too large: ${len} bytes (max ${MAX_BYTES})`)
+  // read with a cap: content-length can be missing or wrong
+  const chunks = []
+  let size = 0
+  try {
+    for await (const c of res.body) {
+      size += c.length
+      if (size > MAX_BYTES) break
+      chunks.push(c)
+    }
+  } catch (e) {
+    throw fetchError(`${msg}: ${why(e)}`, e)
   }
-  return { logoUrl: json.logoUrl, id: json.id, bytes: json.bytes ?? st.size, api: LOGO_API }
+  if (size > MAX_BYTES) throw new Error(`${msg}: logo too large: over ${MAX_BYTES} bytes`)
+  return { ...(await postLogo(Buffer.concat(chunks), uri)), source: uri }
 }