Conversation
…afe AGENTS.txt, security model page, CI bundle regen
- Add scripts/dump_mcp_tools.py + docs/reference/mcp-tools.json: static one-fetch
snapshot of all 62 MCP tool contracts (mcp-server-tronlink@0.1.1, 55 tools;
mcp-tronlink-signer@0.1.4, 7 tools) captured via MCP tools/list from the
published npm packages; linked from llms indexes, AGENTS files, AI overview
and MCP server pages with runtime list_tools kept as SSOT
- docs/AGENTS.txt: absolute URLs so links survive HTTP fetching (repo-root
AGENTS.md keeps repo-relative links); both gain a Continuous-verification
section surfacing the CI doc↔schema parity gate and post-deploy link check
- gh-pages.yml: regenerate llms bundles before mkdocs build so deployed
commit/timestamp headers can never drift from content
- Add ai-support/security-model.{en,zh}.md: cross-surface security invariants
(HITL, no auto-retry on writes, prompt-injection stance, SSRF allowlist,
confused deputy, secret handling, tl_evaluate grading, testnet-first) with
links into each surface's own boundary section; wired into nav, llms
indexes and bundle page lists
- Enable attr_list; give zh security/error-code headings explicit ASCII ids
aligned with their EN translation pair and fix the previously broken
#错误码 anchors (CJK headings render as _N ids); also activates the
pre-existing { width } attrs on passive-messages images
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
… by standards review
Verified every claim against the published binaries/npm packages before editing
(@tronlink/tronlink-cli@1.0.1 tarball, mcp-server-tronlink@0.1.1 source,
mcp-tronlink-signer@0.1.4, docs/reference/mcp-tools.json).
CLI (en+zh) — align docs with the shipped binary:
- Exit codes: replace the fictional 0-5 class table with reality (0 success /
1 any failure) and document the real machine contract: stderr JSON line
{status:"error", error:"<classified message>"} with per-class stable
prefixes from the v1.0.1 classifier
- --json compatibility contract: stable keys are Status/TxID/Explorer (+ read
data keys), not the never-implemented ok/error.code/error.retryable/txid;
drop the fictional error.code-enum-SSOT claim
- Preview docs now mention Contract/Decimals/FeeLimit rows (FeeLimit = max TRX
burn, unit TRX, default 100); binary name tronlink (not tronlink-cli)
- Examples pin --network nile with an explicit default-is-mainnet warning
(incl. AI transfer flow); case-insensitivity scoped to option NAMES only;
headless/CI limitation stated (no unattended signing path)
MCP server (en+zh) — on-chain semantics agents were missing:
- tl_chain_send amount unit trap: TRX human units vs TRC10/TRC20 RAW smallest
units (no decimals conversion; decimal point rejected) + warning block
- swap_v3: amount is raw smallest units; fee_tier inline enum removed (runtime
schema has none — doc mirror no longer overpromises); slippage documented as
the ONLY output bound (no minimum-output field exists)
- Swap safety rewritten: slippage-based guidance, auto-approve(MAX_UINT256)
unlimited-allowance disclosure, router pinning rationale
- multisig raw_data.fee_limit: required, untyped in runtime schema, unit SUN;
Permission_id semantics (0=owner, active from 2, must match signing keys)
- New bullets: broadcast != executed != final (contractRet check, ~19 SR
confirmations) and fixed on-chain costs (setup_multisig 100 TRX)
Signer (en+zh) — retry-safety contradictions resolved:
- TIMEOUT: clarified strictly pre-sign (nothing signed/broadcast; post-broadcast
pending is status:"pending") — removes the retryable-Yes-but-maybe-in-flight
contradiction; BROWSER_DISCONNECTED: 'Reconcile first' with the before/after
approval distinction spelled out
- TIP-712 naming; typed-data domain.chainId<->network verification warning;
raw-tx expiration (~60s) vs 5-min approval window mismatch; idempotent
replay vs rebuild-and-resign distinction; headless + address-poisoning notes
Error-code map (en+zh): add Signer MCP column joining its documented dialect
(USER_REJECTED/TIMEOUT/...); CLI column now reflects exit 0/1 + stderr message
class; rate-limited row cross-references TL_CHAIN_QUERY_FAILED (HTTP 429);
downstream-SSOT note acknowledges the signer dialect
Security model (en+zh): new 'Transaction lifecycle & finality' section;
TL_RATE_LIMITED (nonexistent code I previously introduced) corrected to the
real 429 mapping. mcp-core: tl_chain_get_address no longer says 'from private
key'. Skills: crypto usage scoped to Base58Check validation (no signing).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ance, response fields, layer cross-notes
- Add Troubleshooting sections to CLI / MCP server / MCP signer (en+zh):
signer-disconnect, approval timeout, port clash, 429 backoff, wallet/
extension setup, install verification via list_tools tool counts
- Document write-tool response payload from published typings: ChainTxResult
{ success, tx_id, message? } — field is tx_id (snake_case), success means
broadcast acceptance only (compensates for missing outputSchema)
- Cross-note the SDK<->MCP layering: SDK status:"failed" surfaces as
ON_CHAIN_FAILED at the MCP layer where status is only success/pending
- Signer: concrete MCP error-envelope JSON example
- Skills (en+zh): name the actual data sources verified from source
(TronGrid, Tronscan apilist, SUN.io smart-router, CoinGecko) + a Data
Sources & Freshness section (live-at-query, single in-process metadata
cache, queried addresses visible to public APIs); Claude Desktop
claude_desktop_config.json sample; MCP-mode coverage note listing the 8
CLI-only commands; Which-Mode-to-Use table; credential hygiene note
- error-code-map zh: restore fragment anchors on provider/deeplink/mcp header
refs (explicit ids added to zh target headings)
- Fix 4 legacy broken zh anchors (broadcast-result, inline-changelog,
deeplink result-code self-reference)
- Normalize halfwidth CJK-context punctuation across touched zh pages (75x)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…can P1/P2) - SECURITY.md (repo root) + RFC 9116 security.txt served at /.well-known/security.txt and /security.txt, using TronLink's published contact address (tronlink@tronlink.org) - deploy workflow mirrors AGENTS.txt at /AGENTS.md and /CLAUDE.md - post-deploy verify now probes agent-entry mirrors + security.txt - security-model pages (en/zh) gain a Reporting-a-vulnerability section; AGENTS.txt/AGENTS.md and llms indexes link the channel Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…view verification) Verified against published artifacts (@tronlink/mcp-server-tronlink@0.1.1, mcp-tronlink-signer@0.1.4, tronlink-signer@0.1.4, tronlink-skills@d26c02e): - signer TIMEOUT: timer wraps whole round trip, not cancelled at Approve — reclassified to reconcile-first (was: 'nothing broadcast, safe re-issue'); timeout is hardcoded, dropped 'raise the timeout' advice - mcp-server: TRX-input swap unit double-bug documented as known-unusable; fee_limit ceilings corrected (V2 150 / V3 200 / approve+TRC20 100 TRX); V2/V3 routers have built-in defaults — 'no default' claims inverted - meta.schemaVersion claims removed (absent from both servers' wire) - SSRF invariant scoped: tl_navigate accepts arbitrary URLs into the wallet browser; retryable-flag wording scoped to surfaces that emit it - skills: 43 commands / 25 MCP tools / 18 CLI-only at d26c02e; read-only claims scoped to the MCP surface — 1.0.0 added ten raw-key CLI write commands (documented with key-hygiene warnings); version pin 1.0.1→1.0.0 - annotations claim dropped (0 of 62 tools publish them); AGENTS variants synced (error-code-map row); llms-full now includes error-code-map (25 pgs) - dump_mcp_tools: fix buffered-readline race that dropped responses arriving with notifications (raw-fd line assembly); snapshot regenerated - CI: deploy concurrency serialized; verify gates on deployed commit stamp; security.txt freshness in daily cron + pre-build gate; parity paths extended to security.txt and gen_llms_full.py Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ped-behavior gaps (review round 2)
- tronlink-skills: previous round documented the INTERNAL repo (43 cmds /
25 tools / raw-key write commands); the public GitHub repo is v1.1.0 @
7b37eaf0 — 40 commands / 39 MCP tools / only swap-route CLI-only (alias)
/ fully read-only. Page redone bilingually; security-model + AGENTS
raw-key claims reverted; install steps unified (clone path vs
~/.tronlink-skills installer flow)
- mcp-server: Nile sample no longer pins mainnet/stale routers (wrong-
network unlimited-approve hazard); per-page SSRF row admits tl_navigate;
all remaining meta.schemaVersion / error.retryable wire claims removed
(core envelope verified: {ok, error{code,message,details}, meta{
timestamp,sessionId,durationMs}}); parity workflow link fork→org
- mcp-core: envelope example + compat section aligned to real wire
- CLI: approval-timeout row now reconcile-first (race verified in 1.0.1:
outer timer never aborts the browser flow); TRONLINK_TIMEOUT documented
- skills routing: TRX-input swap intent no longer routed to the broken
tl_chain_swap_v3 path
- security-model: side-effect grades admitted absent from tool descriptions
- CI: cache-buster now unique per run; expiry check tolerates missing tz;
stale deploy trigger branch removed; verify sample 5→15/locale
- dump script: stamp semantics documented; snapshot + bundles regenerated
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Three rounds of AI-readability review + verification against the published
artifacts (npm tarballs / public repos). Every machine-facing claim in the
docs now matches shipped behavior.
Accuracy fixes (verified against published packages)
cancelled on Approve — re-issuing after timeout can double-spend.
Reclassified to "reconcile on-chain first" everywhere.
0.1.1), corrected fee_limit ceilings (V2 150 / V3 200 / approve 100 TRX),
fixed inverted claims about built-in SunSwap router defaults, removed the
wrong-network router pins from the Nile sample config.
meta.schemaVersion,error.retryable,tool
annotations) from all pages; retryable is now consistently framedas the Error Code Map's classification.
tools / read-only; previous numbers came from an internal fork).
tl_navigateopens arbitrary caller URLs in thewallet browser.
New
SECURITY.md, RFC 9116security.txt(
/.well-known/+ legacy), disclosure section on the Security Model page./AGENTS.mdand/CLAUDE.md; static MCP toolcontracts (
reference/mcp-tools.json, 62 tools); error-code-map added tothe llms-full bundles (25 pages per locale).
CI hardening
.nojekyll(dot-dirs were dropped by Pages), serialized deploys,post-deploy verify now gates on the deployed commit stamp with per-run
cache busting, security.txt expiry checked pre-deploy and in the daily
cron, fixed a buffered-read race in
dump_mcp_tools.py.Verified: build clean, doc↔schema parity green, 3175 internal links zero
broken, all changes confirmed live on a fork deployment.