Conversation
Code Review ReportProject: BankOfAI Docs PR OverviewBranch Information
Commit History
Review SummaryVerdict
Findings at a Glance
SummaryThis PR adds two categories of documentation changes: (1) a full suite of SUN CLI documentation (Introduction, Quick Start, Command Guide, and FAQ) in both English and Simplified Chinese, and (2) updates across existing x402 payment documentation to introduce a new The SUN CLI documentation is well-structured, thorough, and closely follows the style of existing docs. The One Major issue is present: the FAQ for SUN CLI links to a third-party personal GitHub repository ( Change SummaryGroup 1 — New SUN CLI Documentation (English + Chinese)
Purpose: Document the Group 2 — x402
|
| File | Change Type | Description |
|---|---|---|
docs/x402/core-concepts/network-and-token-support.md |
Modified | Added exact_gasfree scheme section; updated payment scheme count from two to three; table updated |
docs/x402/faq.md |
Modified | Expanded payment scheme answer to include exact_gasfree |
docs/x402/sdk-features.md |
Modified | Added exact_gasfree/tron, SufficientBalancePolicy, GasFree, and USDD (TRC-20) entries |
docs/x402/getting-started/quickstart-for-human.md |
Modified | Added Python and TypeScript code examples for ExactGasFreeClientMechanism |
docs/x402/getting-started/quickstart-for-agent.md |
Modified | Softened TronGrid API key note; added fallback endpoint explanation |
docs/x402/getting-started/quickstart-for-sellers.md |
Modified | Same TronGrid fallback language update |
docs/x402/index.md |
Modified | Bolded TRON and BSC in intro paragraph |
i18n/zh-Hans/... (x402 files) |
Modified | Chinese locale mirrors all of the above changes |
i18n/zh-Hans/.../sdk-features.md |
Modified | Also corrects BSC network IDs from bsc:mainnet/testnet to eip155:56/97 |
Purpose: Document the newly shipped exact_gasfree payment scheme (zero-gas TRON payments via BankOfAI GasFree proxy) and reflect the new TronGrid fallback behavior across all relevant pages.
Detailed Findings
Major
[MJ-01] FAQ Links to Third-Party Personal GitHub Repository
| Property | Value |
|---|---|
| Severity | Major |
| Category | Documentation |
| File | docs/McpServer-Skills/MCP/SUNCli/FAQ.md : Line 133 |
Description
The "Still Need Help?" section directs users to file issues on
https://github.com/nicholaskarlson/sun-cli. This is a third-party personal GitHub account, not an official BankOfAI or BofAI organization repository. Users who follow this link to report bugs or read source code will be directed to the wrong project. The Chinese translation (i18n/zh-Hans/.../FAQ.md, line 133) contains the same incorrect link.
Code
If your question isn't covered here, check the [Command Guide](./CommandGuide.md) for detailed usage,
or file an issue on the [GitHub repository](https://github.com/nicholaskarlson/sun-cli).Recommendation
Replace with the official BofAI repository URL. If the public repository is:
https://github.com/BofAI/sun-cli
then:
or file an issue on the [GitHub repository](https://github.com/BofAI/sun-cli).
Apply the same fix in i18n/zh-Hans/.../FAQ.md.Minor
[MN-01] Inconsistent TronGrid API Key Environment Variable Name Across Product Docs
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | docs/McpServer-Skills/MCP/SUNCli/QuickStart.md : Line 134 vs docs/x402/getting-started/quickstart-for-agent.md : Line 63 |
Description
The SUN CLI
QuickStart.mdusesTRONGRID_API_KEY, while all x402 documentation (also modified in this PR) consistently usesTRON_GRID_API_KEY. Both refer to the same TronGrid API credential concept. A user who follows the x402 agent quickstart, setsTRON_GRID_API_KEY, then moves to SUN CLI docs will be told to setTRONGRID_API_KEY— and may not realize these are two different variables for two different tools. The inconsistency can cause user confusion especially since the documentation is cross-linked.
Code
# QuickStart.md (SUN CLI) — line 134
export TRONGRID_API_KEY="<YOUR_KEY>"
# quickstart-for-agent.md (x402) — line 63
export TRON_GRID_API_KEY="your_trongrid_api_key_here"Recommendation
Determine the canonical variable name for each respective SDK/tool and note clearly in both documents that these are separate products with separate variable names. If the names are intentionally different, add a short callout box in each QuickStart noting the distinction. Example in
QuickStart.md:> **Note:** SUN CLI uses `TRONGRID_API_KEY`. The x402 SDK uses a separate variable `TRON_GRID_API_KEY`. These are distinct products and the variable names are not interchangeable.
[MN-02] exact_gasfree Network Scope Ambiguous in SDK Features Table
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | docs/x402/sdk-features.md : Line 49 (after patch) |
Description
The SDK features table adds
exact_gasfree/tronlisted alongsideexact_permit/tron,exact/tron, etc. However, the narrative documentation clearly states thatexact_gasfreeis only available ontron:mainnetandtron:nile— it is NOT available ontron:shasta. The table row gives no indication of this network restriction, unlike the prose description that explicitly enumerates the supported networks. This discrepancy between table and prose could lead developers to attempt to useexact_gasfreeon Shasta and receive confusing errors.
Code
| exact_gasfree/tron | ✅ | ✅ |Recommendation
| exact_gasfree/tron (mainnet & nile only) | ✅ | ✅ |Apply the same fix in
i18n/zh-Hans/.../sdk-features.md.
[MN-03] Low-Level Swap Commands Lack Sufficient Risk Warnings
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md : Lines 218–231 |
Description
The
swap:quote-rawandswap:exact-inputcommands are documented with minimal context.swap:exact-inputdirectly executes a swap via a specific router using raw--argsJSON, bypassing the high-level routing layer. Unlike the top-levelswapcommand, these low-level commands have no built-in slippage protection, no route validation, and accept raw contract arguments that — if malformed or incorrect — could result in permanent loss of funds. The documentation section provides only a one-line description and example without any caution statement.
Code
### `swap:exact-input`
Low-level exact-input swap via a specific router.
```bash
sun swap:exact-input --router <routerAddress> --args '[...]' --value 1000000
**Recommendation**
> Add a warning admonition before the low-level command section:
>
> ```markdown
> :::danger Low-level commands
> `swap:quote-raw` and `swap:exact-input` bypass the high-level routing engine.
> They require raw contract call arguments and do not perform route validation or
> slippage protection. Incorrect arguments may result in **permanent fund loss**.
> Only use these commands if you have deep familiarity with the SunSwap router ABI.
> For most use cases, prefer `swap` and `swap:quote`.
> :::
> ```
---
#### [MN-04] BankOfAI Proxy Trust Model Not Disclosed for `exact_gasfree`
| Property | Value |
|----------|-------|
| **Severity** | Minor |
| **Category** | Documentation / Security |
| **File** | `docs/x402/core-concepts/network-and-token-support.md` : Lines 837–843 |
**Description**
> The `exact_gasfree` scheme documentation highlights that "no API keys required" because all GasFree API calls are routed through the BankOfAI proxy at `https://facilitator.bankofai.io/{mainnet,nile}`. While convenience is mentioned, the documentation does not disclose the trust implications: users are routing all their GasFree settlement requests through BankOfAI's infrastructure. If this proxy is unavailable, compromised, or exhibits unexpected behavior, `exact_gasfree` payments will fail or be handled in a non-transparent manner. Users should be informed they are trusting a third-party intermediary, not a permissionless on-chain path.
**Code**
```markdown
- **No API keys required**: All GasFree API calls route through the BankOfAI proxy at
`https://facilitator.bankofai.io/{mainnet,nile}`, so clients do not need to configure
`GASFREE_API_KEY` or `GASFREE_API_SECRET`
Recommendation
Add a transparency note:
- **No API keys required**: All GasFree API calls route through the BankOfAI proxy at `https://facilitator.bankofai.io/{mainnet,nile}`, so clients do not need to configure `GASFREE_API_KEY` or `GASFREE_API_SECRET`. Note that this means settlement requests pass through BankOfAI-operated infrastructure. Users who require a fully permissionless or self-hosted setup should deploy their own GasFree proxy and configure it directly.
Suggestions
[S-01] Token Decimal Unit Explanation Should Be Co-Located with Token Table
File: docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md : Lines 358–383
Description: The built-in token symbol table lists decimal counts (e.g., USDD = 18, TRX = 6) but does not remind readers that all command amounts must be expressed in the smallest unit (e.g., 1000000 = 1 TRX). This explanation exists in the FAQ but not in the Command Guide where users will most likely consult the token table while writing commands.
Suggestion: Add a brief note below the table:
> **Amount units:** All command amounts are expressed in the token's smallest unit.
> For TRX (6 decimals), `1000000` = 1 TRX. For USDD (18 decimals), `1000000000000000000` = 1 USDD.[S-02] Consider Adding --dry-run Example for Liquidity Commands
File: docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md : Lines 236–290 (Liquidity section)
Description: The Swap section mentions that --dry-run is available globally and returns intent without broadcasting. The Liquidity section (which covers potentially large transactions: V2, V3, V4 mint/increase/decrease/collect) does not include any --dry-run example. Given that liquidity operations are higher-risk write operations, a prominent dry-run example would reinforce the safety-first message already established in the Security Notes.
Suggestion: Add a dry-run example at the top of the Liquidity section, similar to how it is shown in the Global Flags section.
[S-03] Chinese SDK Features Table Also Should Clarify exact_gasfree Network Scope
File: i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/sdk-features.md
Description: Same issue as MN-02 applies to the Chinese locale file. This is listed as a separate suggestion since it is a translation file, but it requires the same fix as the English source.
Suggestion: Apply the same network-scope annotation （仅限 mainnet 和 nile） to the exact_gasfree/tron row in the zh-Hans sdk-features table.
Positive Observations
| Area | Observation |
|---|---|
| Security warnings | The SUN CLI docs include well-placed security callout boxes (:::warning, :::caution, :::tip) discouraging hardcoded private keys and encouraging testnet-first workflows |
| Bilingual parity | All 8 new SUN CLI pages and all modified x402 pages have matching Chinese translations with accurate content — no missing sections or stale translations observed |
| Cross-linking | Internal links between Intro, QuickStart, CommandGuide, and FAQ are consistent in both English and Chinese, and correctly use relative paths |
| Sidebar consistency | Both sidebars.js (EN) and the zh-Hans sidebars.js add the SUN CLI category with the same ordering (Intro → QuickStart → CommandGuide → FAQ), which is logical and consistent with other MCP tool sections |
| BSC network ID correction | The zh-Hans sdk-features.md correctly updates bsc:mainnet / bsc:testnet to the canonical EIP-155 chain identifiers eip155:56 / eip155:97, aligning with the English source |
exact_gasfree code examples |
The Python and TypeScript integration examples in quickstart-for-human.md are complete, correct, and show both languages registering the new mechanism side-by-side — reducing integration friction |
| TronGrid fallback documentation | The updated TronGrid API key language clearly explains the new fallback behavior without being alarmist, and is consistently applied across agent, human, and seller quickstart guides |
Checklist Results
| Category | Items Checked | Pass | Fail | N/A | Notes |
|---|---|---|---|---|---|
| Correctness | 5 | 4 | 1 | 2 | MN-02: network scope inconsistency in table vs prose |
| Security | 6 | 4 | 2 | 2 | MN-03: missing low-level command warning; MN-04: undisclosed proxy trust model |
| Performance | 3 | 0 | 0 | 3 | Not applicable to documentation changes |
| Code Quality | 5 | 4 | 1 | 1 | MN-01: env var naming inconsistency |
| Testing | 4 | 0 | 0 | 4 | No code changes; test coverage N/A |
| Documentation | 6 | 5 | 1 | 0 | MJ-01: incorrect external repository link |
| Compatibility | 3 | 3 | 0 | 0 | Sidebar and i18n changes are additive and backward compatible |
| Observability | 2 | 0 | 0 | 2 | Not applicable to documentation changes |
Disclaimer
This is an automated code review. It supplements but does not replace human review. The reviewer analyzed only the diff between main and update-mcp-server. Runtime behavior, integration testing, and deployment impact are not covered.
Report generated by Code Review Skill v1.0.0
Date: 2026-04-07
Code Review Audit ReportDate: 2026-04-07 1. PR Overview
Commits (oldest to newest)Files ChangedNew files (8):
Modified files (16):
2. Change SummaryGroup A — SUN CLI Documentation (New Feature)Four new documentation pages introduce the
Chinese ( Group B —
|
Code Review ReportProject: BankOfAI Docs PR OverviewBranch Information
Commit History (recent, feature-relevant)
Review SummaryVerdict
A small number of issues should be addressed before merge — one confirmed documentation error (wrong flag name in a code example) and one environment-variable naming inconsistency. Everything else is either a suggestion or a positive practice. Findings at a Glance
SummaryThis PR is a documentation-only change that introduces four new pages documenting the SUN CLI ( Overall the documentation is thorough, well-structured, and security-conscious — prominently warning users about private key hygiene, testnet-first practices, and One Major issue was identified: a copy-paste error in the Change Summary1. SUN CLI Documentation (New)
Purpose: Introduce full user-facing documentation for 2. Navigation Update
Purpose: Register the new SUN CLI pages in the Docusaurus sidebar navigation. 3.
|
| File | Change Type | Description |
|---|---|---|
docs/x402/core-concepts/network-and-token-support.md |
Modified | Added exact_gasfree scheme section; minor trailing-whitespace cleanup |
docs/x402/faq.md |
Modified | Updated payment scheme FAQ answer to include exact_gasfree |
docs/x402/sdk-features.md |
Modified | Added exact_gasfree/tron, SufficientBalancePolicy, GasFree, and USDD rows to feature tables |
docs/x402/getting-started/quickstart-for-human.md |
Modified | Added Python and TypeScript code examples using ExactGasFreeClientMechanism |
i18n/zh-Hans/.../quickstart-for-human.md |
Modified | Chinese translation of the above code example additions |
i18n/zh-Hans/.../x402/ (multiple) |
Modified | Chinese translations for the x402 content updates |
Purpose: Document the new zero-gas TRON payment mechanism that lets buyers pay without holding TRX.
4. TronGrid API Key Guidance Update
| File | Change Type | Description |
|---|---|---|
docs/x402/getting-started/quickstart-for-agent.md |
Modified | Changed "required for mainnet" → explains automatic BankOfAI fallback endpoint when key is not set |
docs/x402/getting-started/quickstart-for-sellers.md |
Modified | Same language update in .env comments and mainnet deployment checklist |
i18n/zh-Hans/... (same files) |
Modified | Chinese translations of the above |
Purpose: Accurately document the actual behavior — that RPC calls fall back to a BankOfAI-operated endpoint instead of failing when TRON_GRID_API_KEY is not provided.
Detailed Findings
Major
[MJ-01] Wrong Option Flag in v2:add Example
| Property | Value |
|---|---|
| Severity | Major |
| Category | Documentation / Correctness |
| File | docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md : Line 337 |
Description
The
liquidity v2:addsingle-sided example uses--amount0, which is the V3/V4 flag naming convention. Thev2:addcommand's option table (three lines above) correctly defines the flag as--amount-a. A user following this example verbatim will pass an unrecognised flag, causing the command to silently ignore the amount or error out.
Code
<!-- Option table (correct) -->
| `--amount-a <raw>` | Amount of token A (raw units) | — |
| `--amount-b <raw>` | Amount of token B (raw units) | — |
...
> Provide at least one of `--amount-a` or `--amount-b`. When only one is given, the other is auto-calculated from pool reserves.
<!-- Example below (incorrect: uses --amount0 instead of --amount-a) -->
sun liquidity v2:add --token-a TRX --token-b USDT --amount0 1000000Recommendation
sun liquidity v2:add --token-a TRX --token-b USDT --amount-a 1000000The same error is present in the Chinese translation at i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/CommandGuide.md and should be fixed there simultaneously.
Minor
[MN-01] Environment Variable Naming Inconsistency: TRONGRID_API_KEY vs TRON_GRID_API_KEY
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation / Consistency |
| File | docs/McpServer-Skills/MCP/SUNCli/QuickStart.md : Lines 1270 |
Description
The SUN CLI QuickStart page exports
TRONGRID_API_KEY(no underscore betweenTRONandGRID), while the x402 quickstart guides (quickstart-for-agent.md,quickstart-for-sellers.md) consistently useTRON_GRID_API_KEY. Users who configure the environment using the SUN CLI QuickStart guide will set an incorrectly named variable that the x402 SDK will not recognise.
Code
# SUNCli/QuickStart.md (incorrect)
export TRONGRID_API_KEY="<YOUR_KEY>"
# quickstart-for-agent.md (correct, consistent)
export TRON_GRID_API_KEY="your_trongrid_api_key_here"Recommendation
Update SUNCli/QuickStart.md (and its Chinese translation) to use TRON_GRID_API_KEY:
export TRON_GRID_API_KEY="<YOUR_KEY>"[MN-02] CommandGuide.md Has No Inline Security Warning Near Sensitive Flags
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation / Security |
| File | docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md : Lines 26-29 |
Description
The global flags table lists
-k, --private-key <key>and-m, --mnemonic <phrase>without any adjacent caution that these values will appear in shell history. TheIntro.mdpage contains a:::warningadmonition about this, but users reading the command reference directly may miss it. Given that this is a DeFi tool with real on-chain assets at stake, the risk of command-history exposure warrants a visible inline note in the reference guide.
Code
| `-k, --private-key <key>` | Provide a private key for this invocation only |
| `-m, --mnemonic <phrase>` | Provide a mnemonic for this invocation only |Recommendation
Add a short :::caution admonition immediately after the global flags table:
:::caution Shell history exposure
Flags `-k` and `-m` place your private key or mnemonic directly in the shell command line,
which may be recorded in shell history. Prefer `AGENT_WALLET_PRIVATE_KEY` / `AGENT_WALLET_MNEMONIC`
environment variables, or use agent-wallet's encrypted storage.
:::Suggestions
[S-01] BankOfAI Fallback Endpoint: Add Explicit Privacy Note
File: docs/x402/getting-started/quickstart-for-agent.md, quickstart-for-sellers.md
Description: The updated docs now disclose that mainnet RPC calls are automatically routed through a BankOfAI-operated fallback endpoint when TRON_GRID_API_KEY is not set. However, there is no note explaining what data is forwarded (e.g., transaction payloads, addresses) or what privacy/SLA guarantees apply to this endpoint. Users with stricter data residency or privacy requirements may be silently routing sensitive blockchain queries through a third-party proxy without realising it.
Suggestion: Add a brief note (e.g., a :::info admonition) next to the fallback endpoint description clarifying what the endpoint is, who operates it, and how to opt out by providing a direct TRON_GRID_API_KEY. Optionally, link to a BankOfAI privacy policy or Terms of Service.
[S-02] exact_gasfree Scheme: Document Why tron:shasta Is Not Supported
File: docs/x402/core-concepts/network-and-token-support.md
Description: The exact_gasfree section states it is available on tron:mainnet and tron:nile but does not mention tron:shasta. Shasta is listed as a supported testnet elsewhere in the docs. The omission is likely intentional (GasFree may not be available on Shasta), but it creates an implicit gap that developers testing on Shasta will hit with no explanation.
Suggestion: Add a brief sentence such as:
tron:shastais not supported — the GasFree infrastructure is not available on that network. Usetron:nilefor testnet validation.
[S-03] contract send Missing Error-Handling Guidance
File: docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md : Lines 809-827
Description: The contract send section states "contract send returns tronscanUrl when a transaction is broadcast successfully" but gives no guidance on what is returned or logged when a transaction fails, is reverted, or encounters a broadcast error. Given this is the most open-ended and potentially destructive command in the CLI, a note on error output and retry behaviour would improve the user experience.
Suggestion: Add a note similar to:
If the transaction fails to broadcast or is reverted on-chain, a non-zero exit code is returned along with a descriptive error message. Check the TronScan link (if available) for revert details.
Positive Observations
| Area | Observation |
|---|---|
| Security callouts | Intro.md uses a prominent :::warning admonition covering private key hygiene, testnet-first practice, minimum-funds principle, and dry-run usage — exactly where users will read before starting. |
| Read vs. Write clarity | Every command in CommandGuide.md is explicitly labelled (read) or (write), making it immediately clear which commands require a configured wallet. |
| Dry-run support | The --dry-run flag is documented at the global level and re-enforced in the security notes — a valuable safety net for AI agents using the CLI in automation pipelines. |
| Bilingual rollout | English and Simplified Chinese translations are added in the same PR, preventing documentation lag for Chinese-speaking users. |
| Fallback endpoint transparency | Changing the TRON_GRID_API_KEY guidance from "required for mainnet" (which was inaccurate) to honestly documenting the BankOfAI fallback improves transparency about actual system behaviour. |
| Cross-reference coverage | All four new SUN CLI pages cross-link to each other appropriately (QuickStart → CommandGuide → FAQ → Intro), and QuickStart.md correctly links to the existing SUNMCPServer/Intro.md (path verified to exist). |
| Testnet-first pattern | Every write-operation example either uses --network nile explicitly or is accompanied by a :::tip reminding users to validate on Nile before mainnet. |
| Consistent table formatting | All command option tables use a uniform ` |
Checklist Results
| Category | Items Checked | Pass | Fail | N/A | Notes |
|---|---|---|---|---|---|
| Correctness | 4 | 3 | 1 | — | --amount0 flag error in v2:add example (MJ-01) |
| Security | 5 | 4 | 0 | — | MN-02: inline warning proximity; no hardcoded secrets found |
| Performance | 3 | — | — | 3 | Documentation-only; not applicable |
| Code Quality | 4 | 3 | 1 | — | MN-01: env var naming inconsistency |
| Testing | 2 | — | — | 2 | Documentation-only; not applicable |
| Documentation | 6 | 5 | 0 | 1 | Suggestions S-01/S-02/S-03 are improvements, not failures |
| Compatibility | 3 | 3 | 0 | — | Sidebar changes use existing Docusaurus category pattern |
| Observability | 2 | — | — | 2 | Documentation-only; not applicable |
Disclaimer
This is an automated code review. It supplements but does not replace human review. The reviewer analysed only the diff between remotes/origin/main and remotes/origin/update-mcp-server. Runtime behaviour (e.g., whether --amount0 is actually accepted or rejected by the CLI binary), integration testing, and deployment impact are not covered.
Report generated by Code Review Skill v1.0.0
Date: 2026-04-07
Code Review ReportProject: BofAI Docs (x402-tron/docs) PR OverviewBranch Information
Commit History
Review SummaryVerdict
Findings at a Glance
SummaryThis PR is a documentation-only change to a Docusaurus-based documentation site. It introduces two categories of changes: (1) four new SUN CLI documentation pages ( The SUN CLI documentation is well-structured, comprehensive, and follows good practices — the security warning admonitions, Change SummaryGroup 1: New SUN CLI Documentation (English + Chinese)
Purpose: Introduces comprehensive documentation for the Group 2: Sidebar Navigation Updates (English + Chinese)
Purpose: Registers the new SUN CLI documentation pages in both the English and Chinese navigation trees. Group 3: x402
|
| File | Change Type | Description |
|---|---|---|
docs/x402/core-concepts/network-and-token-support.md |
Modified | Documents new exact_gasfree scheme, updates payment scheme count from 2 to 3, updates facilitator summary table |
docs/x402/faq.md |
Modified | Rewrites payment scheme FAQ answer to include exact_gasfree |
docs/x402/sdk-features.md |
Modified | Adds exact_gasfree/tron, SufficientBalancePolicy, GasFree, and USDD (TRC-20) rows to feature tables |
docs/x402/getting-started/quickstart-for-human.md |
Modified | Adds ExactGasFreeClientMechanism registration to both Python and TypeScript code examples |
i18n/zh-Hans/... (x402 files) |
Modified | Chinese translations mirroring all above x402 changes |
Purpose: Surfaces the newly released exact_gasfree payment scheme, which allows TRON buyers to pay with USDT/USDD without holding TRX for gas fees, routing via a BankOfAI-operated GasFree proxy.
Group 4: TronGrid API Key Messaging Updates
| File | Change Type | Description |
|---|---|---|
docs/x402/getting-started/quickstart-for-agent.md |
Modified | Changes TRON_GRID_API_KEY description from "required for mainnet" to "recommended for production; BankOfAI fallback used automatically when not set" |
docs/x402/getting-started/quickstart-for-sellers.md |
Modified | Same messaging update for the sellers quickstart |
i18n/zh-Hans/... (agent & sellers quickstart) |
Modified | Chinese translations mirroring TronGrid messaging changes |
Purpose: Reflects a new BankOfAI-operated fallback RPC endpoint that activates automatically when TRON_GRID_API_KEY is absent.
Group 5: Package Version Bump & Misc Fixes
| File | Change Type | Description |
|---|---|---|
package.json |
Modified | Version bumped from 1.2.7 to 1.2.8 |
docs/x402/index.md + i18n |
Modified | Bold formatting added to TRON and BSC network names |
i18n/zh-Hans/.../sdk-features.md |
Modified | BSC network identifiers corrected from bsc:mainnet/bsc:testnet to eip155:56/eip155:97 (Chinese only) |
Purpose: Documentation maintenance and version tracking.
Detailed Findings
Major
[MJ-01] Silent Mainnet Traffic Routing to BankOfAI Infrastructure Without Opt-in Disclosure
| Property | Value |
|---|---|
| Severity | Major |
| Category | Security / Documentation |
| File | docs/x402/getting-started/quickstart-for-agent.md : Lines 60–63, docs/x402/getting-started/quickstart-for-sellers.md : Lines 396–400 |
Description
Previously, the docs stated that
TRON_GRID_API_KEYis "required for mainnet". This PR changes that to "recommended for production; when not set, a BankOfAI fallback endpoint is used automatically". The practical effect is that users who follow the quick-start guide and omit the API key will have their mainnet RPC calls silently proxied through BankOfAI's infrastructure (https://facilitator.bankofai.ioor similar). This is a centralization and trust concern: users' transaction data, wallet activity, and timing information passes through a third-party-controlled endpoint without explicit opt-in. There is no mention of what data the fallback endpoint logs, how long it is retained, or how to opt out. The change effectively converts a security-by-default requirement into a convenience feature that may catch users unaware.
Code
-export TRON_GRID_API_KEY="your_trongrid_api_key_here" # Recommended to avoid RPC rate limits
+export TRON_GRID_API_KEY="your_trongrid_api_key_here" # Recommended for production workloads-> 💡 **How to get a TronGrid API Key:** ... it is required for mainnet.
+> 💡 **How to get a TronGrid API Key:** ... When `TRON_GRID_API_KEY` is not set, mainnet RPC calls are automatically routed to a BankOfAI-operated fallback endpoint. Setting this key is recommended for production workloads to ensure optimal performance.Recommendation
Add an explicit opt-in notice and data handling disclosure alongside the fallback description. The messaging should make it clear that using the fallback means traffic is routed through BankOfAI infrastructure, and offer a note on privacy implications. Consider adding a :::warning admonition:
:::warning Fallback Endpoint Privacy Notice
When `TRON_GRID_API_KEY` is not set, mainnet RPC calls are automatically routed through
a BankOfAI-operated fallback endpoint. This means BankOfAI may observe your wallet
addresses, transaction timing, and query patterns. For production use with real assets,
we strongly recommend registering your own [TronGrid API key](https://www.trongrid.io/)
to avoid this dependency.
:::[MJ-02] English and Chinese sdk-features.md Are Inconsistent — BSC Network Identifier Corrections Only Applied to Chinese Version
| Property | Value |
|---|---|
| Severity | Major |
| Category | Documentation / Correctness |
| File | i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/sdk-features.md : Lines 24–25 vs docs/x402/sdk-features.md |
Description
The Chinese translation of
sdk-features.mdreceived a correction that was never applied to the English source file. The Chinese version changedbsc:mainnet→eip155:56 (BSC Mainnet)andbsc:testnet→eip155:97 (BSC Testnet)to use the canonical EIP-155 chain identifier format. The English version still uses the non-standardbsc:mainnet/bsc:testnetlabels. This is an inconsistency between the two language versions on a technical specification page, where accuracy matters. Users reading the English version will see different network identifiers than Chinese readers, which could cause confusion when configuring SDK integrations.
Code
# Chinese version (zh-Hans) — CORRECTED:
-| bsc:mainnet | ✅ | ✅ |
-| bsc:testnet | ✅ | ✅ |
+| eip155:56 (BSC Mainnet) | ✅ | ✅ |
+| eip155:97 (BSC Testnet) | ✅ | ✅ |
# English version (docs/x402/sdk-features.md) — NOT updated:
| bsc:mainnet | ✅ | ✅ | ← still present, inconsistent
| bsc:testnet | ✅ | ✅ | ← still present, inconsistentRecommendation
Apply the same BSC network identifier corrections to docs/x402/sdk-features.md:
| eip155:56 (BSC Mainnet) | ✅ | ✅ |
| eip155:97 (BSC Testnet) | ✅ | ✅ |Minor
[MN-01] CommandGuide.md Global Flags Table Missing Inline Security Warning for --private-key
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Security / Documentation |
| File | docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md : Lines 15–27 |
Description
The Global Flags reference table lists
-k, --private-key <key>and-m, --mnemonic <phrase>as standard flags without any security note at the point of reference. A developer scanning the command reference for available flags will see these listed equivalently to benign flags like--outputor--json. The risk is that using-kon the command line exposes the private key in shell history (.bash_history,.zsh_history), process lists (ps aux), and potentially CI/CD logs. WhileIntro.mdcontains a security section andFAQ.mdbriefly mentions it, theCommandGuide.mdis the primary command reference and should include an inline note at the point of use.
Recommendation
Add a short inline note below the Global Flags table, or extend the table with a Warning column for sensitive flags:
> ⚠️ **Security note:** Passing `-k` / `-m` on the command line exposes
> credentials in shell history and process lists. Prefer environment variables
> (`AGENT_WALLET_PRIVATE_KEY`, `AGENT_WALLET_MNEMONIC`) or agent-wallet
> encrypted storage for production and shared environments.[MN-02] Chinese sdk-features.md Missing exact_gasfree TRON-Only Annotation in Mechanisms Table
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation / Correctness |
| File | i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/sdk-features.md : Mechanisms table |
Description
The English
sdk-features.mdaddsexact_gasfree/tronto the mechanisms table. The Chinese version mirrors this correctly. However, the English version'snetwork-and-token-support.mdandfaq.mdrepeatedly note thatexact_gasfreeis TRON-only. The Chinese SDK features table does not include any "(TRON only)" annotation on theexact_gasfree/tronrow. While the mechanism name itself includes/tron, readers unfamiliar with the naming convention may not realize this scheme is unavailable for BSC. This is a parity issue with the Englishsdk-features.mdwhich also lacks this annotation — but since the Chinese version is reviewed here, the recommendation applies to both.
Recommendation
For both docs/x402/sdk-features.md and its Chinese translation, consider annotating the row:
| exact_gasfree/tron *(TRON only)* | ✅ | ✅ |[MN-03] QuickStart.md Missing Testnet Faucet Link for New Users
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation / Usability |
| File | docs/McpServer-Skills/MCP/SUNCli/QuickStart.md : Lines 101–115 |
Description
The QuickStart guide instructs users to configure a wallet and run a swap on the Nile testnet. However, it does not provide a link to a Nile testnet faucet to obtain test TRX or USDT. Without test tokens, a new user following the guide will hit an "Insufficient balance" error when attempting the example swap command. The agent quickstart guide (
quickstart-for-agent.md) in the x402 docs already references faucets — this SUN CLI guide should do the same for consistency and user experience.
Recommendation
Add a testnet faucet reference in the wallet configuration section:
:::tip Get Nile testnet tokens
You'll need test TRX to pay for gas on the Nile testnet. Claim tokens from the
[Nile faucet](https://nileex.io/join/getJoinPage) before running write operations.
:::[MN-04] QuickStart.md Internal Cross-Reference Path Should Be Verified
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation / Correctness |
| File | docs/McpServer-Skills/MCP/SUNCli/QuickStart.md : Last line |
Description
The QuickStart guide ends with a cross-reference link:
[SUN MCP Server](../SUNMCPServer/Intro.md). The path../SUNMCPServer/Intro.mdresolves todocs/McpServer-Skills/MCP/SUNMCPServer/Intro.md. While the file does exist (confirmed in the repository), Docusaurus uses document IDs (not file paths) for cross-references in MDX-based sites, and relative path resolution can behave differently across Docusaurus versions. If not tested, this link may render as broken in the deployed site.
Recommendation
Use a Docusaurus-style doc ID reference to ensure reliability:
- **[SUN MCP Server](../SUNMCPServer/Intro)** — Prefer AI-driven DeFi? Use SUN MCP Server for natural language interaction(drop the .md extension, which is the Docusaurus convention, consistent with all other links in sidebars.js)
Suggestions
[S-01] Add Environment Variable Reference Table to QuickStart.md
File: docs/McpServer-Skills/MCP/SUNCli/QuickStart.md
Description: The quickstart mentions TRON_NETWORK, TRONGRID_API_KEY, and TRON_RPC_URL at the end but treats them as isolated snippets. Users benefit from a consolidated reference table showing all supported environment variables, their purpose, and defaults.
Suggestion: Add a small table listing all env vars (TRON_NETWORK, TRONGRID_API_KEY, TRON_RPC_URL, AGENT_WALLET_PRIVATE_KEY, AGENT_WALLET_PASSWORD, AGENT_WALLET_DIR) with their default values and descriptions.
[S-02] CommandGuide.md swap:quote-raw Section Should Include a Complete End-to-End Example
File: docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md
Description: The swap:quote-raw command section shows required arguments (--router, --args) but provides no complete usage example. This is the only command in the guide without a concrete sun ... example.
Suggestion: Add a realistic example call, even with placeholder values, to maintain documentation consistency with all other commands.
[S-03] exact_gasfree Scheme Documentation Could Benefit from a Flow Diagram Description
File: docs/x402/core-concepts/network-and-token-support.md
Description: The existing Authorize → Execute → Settle flow explanation (3 steps) was preserved for exact_permit/exact, but exact_gasfree has no analogous flow description. Since it introduces a new routing path through a BankOfAI GasFree proxy, users setting up server-side facilitators may be confused about who handles which step.
Suggestion: Add a brief step-by-step flow for exact_gasfree analogous to the existing 3-step flow, clarifying the GasFree proxy's role in the settlement step.
[S-04] Commit Messages Are Not Descriptive Enough for Traceability
File: N/A (git history)
Description: Commit messages such as add cuncli, add suncli, add gas free, and fix are too vague to be useful for future traceability or changelog generation. The commit message add cuncli appears to be a typo of add suncli.
Suggestion: Use descriptive commit messages that reference the scope and intent (e.g., docs(sun-cli): add SUN CLI introduction, quickstart, command guide, and FAQ). The apparent typo cuncli in one commit should be clarified.
Positive Observations
| Area | Observation |
|---|---|
| Security documentation | Intro.md contains a well-crafted :::warning admonition with six specific security principles, including hardcoded key avoidance, testnet-first workflow, minimum-funds principle, and dry-run usage. This is well above average for CLI documentation. |
| Structured command reference | CommandGuide.md consistently formats every command with a synopsis, options table (with Default column), and concrete bash code examples. The format is professional and scannable. |
| CLI vs MCP comparison table | The Intro.md comparison table between SUN CLI and SUN MCP Server clearly articulates the use-case difference. This reduces user confusion and supports appropriate tool selection. |
--dry-run flag documentation |
The global --dry-run flag is documented prominently in both the Global Flags table and the security notes. This is a critical safety feature for DeFi automation. |
| Localization parity | The 4 new SUN CLI docs and all 6 modified x402 docs were simultaneously updated in both English and Chinese (zh-Hans), maintaining full localization parity — a significant quality signal. |
| FAQ error coverage | FAQ.md covers the common unknown command 'nile' error caused by flag ordering — a subtle CLI gotcha — which reflects genuine user-testing or production feedback. |
| Code examples in quickstart-for-human.md | The Python and TypeScript code examples for exact_gasfree registration are clear, complete, and follow the same structural pattern as the existing exact_permit examples, making adoption easy. |
| Version bump discipline | The package.json version bump (1.2.7 → 1.2.8) is included in the same PR as documentation content changes, reflecting good release hygiene. |
Checklist Results
| Category | Items Checked | Pass | Fail | N/A | Notes |
|---|---|---|---|---|---|
| Correctness | 5 | 4 | 1 | 2 | English/Chinese sdk-features.md inconsistency (MJ-02) |
| Security | 6 | 4 | 2 | 4 | Silent RPC fallback routing (MJ-01); missing inline key warning (MN-01) |
| Performance | 7 | — | — | 7 | Not applicable — documentation-only PR |
| Code Quality | 8 | 7 | 1 | 2 | Vague commit messages (S-04) |
| Testing | 7 | — | — | 7 | Not applicable — documentation-only PR |
| Documentation | 8 | 6 | 2 | 1 | Missing faucet link (MN-03); missing cross-ref (MN-04) |
| Compatibility | 5 | 5 | — | — | Sidebar changes are additive; no breaking navigation changes |
| Observability | 4 | — | — | 4 | Not applicable — documentation-only PR |
Disclaimer
This is an automated code review. It supplements but does not replace human review. The reviewer analyzed only the diff between main and update-mcp-server. Runtime behavior, integration testing (e.g., Docusaurus build verification, link checking), and deployment impact are not covered by this report. For a documentation site, a docusaurus build pass and a broken-links check (e.g., docusaurus-plugin-check-links) are strongly recommended as part of the CI pipeline.
Report generated by Code Review Skill v1.0.0
Date: 2026-04-08
Code Review ReportProject: @x402-tron/docs PR OverviewBranch Information
Commit History
Review SummaryVerdict
Findings at a Glance
SummaryThis PR makes two categories of changes to the BankOfAI documentation site: (1) it introduces a brand-new SUN CLI section — comprising Introduction, Quick Start, Command Guide, and FAQ — in both English and Chinese, and (2) it updates existing x402 documentation to reflect a new third payment scheme ( However, three major concerns need to be resolved before merging. The most impactful is an environment variable name inconsistency ( Change SummaryGroup 1: New SUN CLI Documentation (English + Chinese)
Purpose: Introduces documentation for the new Group 2: x402
|
| File | Change Type | Description |
|---|---|---|
docs/x402/core-concepts/network-and-token-support.md |
Modified | Documented exact_gasfree payment scheme |
docs/x402/faq.md |
Modified | Updated FAQ to list three payment schemes |
docs/x402/sdk-features.md |
Modified | Added exact_gasfree/tron, GasFree, SufficientBalancePolicy, and USDD to SDK feature tables |
docs/x402/getting-started/quickstart-for-human.md |
Modified | Added Python and TypeScript code examples for ExactGasFreeClientMechanism |
i18n/zh-Hans/.../ (x402 files) |
Modified | Chinese translations of all x402 changes |
Purpose: Documents the newly available exact_gasfree payment scheme, a TRON-specific mechanism allowing USDT/USDD payments without buyers holding TRX for gas. Settlement routes through the BankOfAI facilitator endpoint.
Group 3: TronGrid API Key Guidance Update
| File | Change Type | Description |
|---|---|---|
docs/x402/getting-started/quickstart-for-agent.md |
Modified | Changed TronGrid key from "required for mainnet" to "recommended for production" |
docs/x402/getting-started/quickstart-for-sellers.md |
Modified | Same wording change in sellers guide and .env comment |
i18n/zh-Hans/.../ (agent + sellers files) |
Modified | Chinese translations of the above |
Purpose: Reflects that mainnet now has a BankOfAI-operated fallback RPC endpoint when TRON_GRID_API_KEY is not set, so the key is no longer strictly required.
Group 4: Package Version Bump
| File | Change Type | Description |
|---|---|---|
package.json |
Modified | Version bumped from 1.2.7 to 1.2.8 |
Purpose: Reflects the new documentation content added in this PR.
Detailed Findings
Major
[MJ-01] Inconsistent Environment Variable Name: TRONGRID_API_KEY vs. TRON_GRID_API_KEY
| Property | Value |
|---|---|
| Severity | Major |
| Category | Correctness / Documentation |
| File | docs/McpServer-Skills/MCP/SUNCli/QuickStart.md : Line 7 of Network & API Configuration section; i18n/zh-Hans/.../SUNCli/QuickStart.md : equivalent section |
Description
The SUN CLI Quick Start guide (both English and Chinese) documents the TronGrid API key environment variable as TRONGRID_API_KEY:
export TRONGRID_API_KEY="<YOUR_KEY>"However, every other documentation file in this PR and on main consistently uses TRON_GRID_API_KEY:
quickstart-for-agent.md:export TRON_GRID_API_KEY="your_trongrid_api_key_here"quickstart-for-sellers.md:TRON_GRID_API_KEY=x402/core-concepts/network-and-token-support.md: referencesTRON_GRID_API_KEY
A user following the SUN CLI Quick Start will set TRONGRID_API_KEY in their environment, but the SDK will look for TRON_GRID_API_KEY — causing the variable to be silently ignored and the fallback endpoint to be used without the user realizing it. This is a runtime behavioral bug disguised as a documentation issue.
Recommendation
Change both QuickStart files (English and Chinese) to use the correct variable name:
export TRON_GRID_API_KEY="<YOUR_KEY>"[MJ-02] Downgraded TronGrid Requirement Silently Introduces Undisclosed Third-Party Trust Dependency for Mainnet
| Property | Value |
|---|---|
| Severity | Major |
| Category | Security / Documentation |
| File | docs/x402/getting-started/quickstart-for-agent.md : Lines 60-73; docs/x402/getting-started/quickstart-for-sellers.md : Lines 396-403, 545-548 |
Description
The PR changes the documentation for TRON_GRID_API_KEY from:
# Recommended to avoid RPC rate limits
and:
# TronGrid API Key (required for mainnet, can be left blank for testnet)
to:
# Recommended for production workloads
and:
# TronGrid API Key (recommended for production; when not set, a BankOfAI fallback endpoint is used automatically)
This change is semantically significant: operators who previously understood the key as "required for mainnet" will now leave it blank, and their mainnet RPC traffic will be silently routed through a BankOfAI-operated infrastructure endpoint. The implications are:
- Trust without explicit consent: Operators running their own Facilitator nodes may not realize their production mainnet traffic flows through a third-party endpoint they did not explicitly choose.
- Availability dependency: The BankOfAI fallback is an undocumented SLA; if it goes down, mainnet operations fail silently for operators who omitted the key.
- No link to fallback endpoint documentation: The doc mentions "BankOfAI-operated fallback endpoint" but provides no URL, SLA, rate limits, or terms for this service.
Recommendation
Add an explicit callout block wherever this fallback is mentioned, for example:
:::note Fallback RPC Endpoint
When `TRON_GRID_API_KEY` is not set, mainnet RPC calls are automatically
routed through a BankOfAI-operated public endpoint
(`https://api.trongrid.io` proxied via BankOfAI). This endpoint has no
guaranteed SLA and may be rate-limited under high load. For production
workloads, set your own `TRON_GRID_API_KEY` to ensure reliability and
independence from BankOfAI's infrastructure.
:::[MJ-03] Private Key Flag Examples in Command Guide Lack Inline Security Warnings
| Property | Value |
|---|---|
| Severity | Major |
| Category | Security / Documentation |
| File | docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md : Lines 26-54; i18n/zh-Hans/.../CommandGuide.md : equivalent lines |
Description
The Command Guide prominently documents -k, --private-key <key> as a global flag and provides a runnable code example:
sun -k your_private_key --network nile --yes swap TRX USDT 1000000Passing private keys as CLI arguments is dangerous because:
- The key appears in the shell's command history (
~/.bash_history,~/.zsh_history). - It may appear in process listings (
ps aux), CI/CD logs, and terminal session recordings.
The FAQ does mention this risk: "be cautious with command-line flags (-k, -m) as they may appear in your shell history" — but this warning is buried in the FAQ, far from the point of use in the Command Guide. Developers copy-paste from the Command Guide first.
The Intro.md has a security callout (:::warning block) that says "Never hardcode private keys" and recommends environment variables — but this applies to the CLI flags too, and that connection is never made in the Command Guide.
Recommendation
Add a :::caution block immediately after the Global Flags table in the Command Guide:
:::caution Private Key Security
The `-k` / `--private-key` and `-m` / `--mnemonic` flags pass sensitive
material as command-line arguments, which may be recorded in shell history
and process listings. Prefer environment variables (`AGENT_WALLET_PRIVATE_KEY`,
`AGENT_WALLET_MNEMONIC`) or [agent-wallet](https://github.com/BofAI/agent-wallet)
encrypted storage for all non-throwaway keys.
:::Apply the same addition to the Chinese CommandGuide.md.
Minor
[MN-01] exact_gasfree Available on tron:nile But Not tron:shasta — Inconsistency Not Surfaced
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation / Correctness |
| File | docs/x402/core-concepts/network-and-token-support.md : exact_gasfree section |
Description
The exact_gasfree scheme is documented as available on tron:mainnet and tron:nile only. However, the documentation does not explain why Shasta is excluded, nor does it warn developers who use Shasta as their test environment that this scheme will not work there. Other payment schemes appear to support all three TRON networks. Developers on Shasta who try to use exact_gasfree will encounter a failure with no helpful error message pointed to by the docs.
Recommendation
Add a note explaining the Shasta exclusion:
> **Note:** `exact_gasfree` is not available on `tron:shasta`. Use `tron:nile` for testnet
> development with this scheme, as GasFree infrastructure is not deployed on Shasta.[MN-02] SDK Feature Table Uses Inconsistent BSC Network Identifier Format
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation / Consistency |
| File | i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/sdk-features.md : Lines 24-25 |
Description
The Chinese sdk-features.md was correctly updated to replace bsc:mainnet/bsc:testnet with the canonical EIP-155 identifiers eip155:56 (BSC Mainnet)/eip155:97 (BSC Testnet). The English sdk-features.md had a row added (exact_gasfree/tron) but was not updated with the same BSC identifier fix. The English table still contains the non-canonical bsc:mainnet/bsc:testnet labels in the unchanged rows.
Recommendation
Apply the same BSC network identifier fix to docs/x402/sdk-features.md (English):
| eip155:56 (BSC Mainnet) | ✅ | ✅ |
| eip155:97 (BSC Testnet) | ✅ | ✅ |[MN-03] exact_gasfree Trust Model Not Clearly Articulated — Proxy Architecture Opaque to Readers
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation / Security |
| File | docs/x402/core-concepts/network-and-token-support.md : exact_gasfree section; docs/x402/getting-started/quickstart-for-human.md : GasFree code examples |
Description
The exact_gasfree documentation states:
"All GasFree API calls route through the BankOfAI proxy at
https://facilitator.bankofai.io/{mainnet,nile}, so clients do not need to configureGASFREE_API_KEYorGASFREE_API_SECRET."
This is useful, but the documentation does not clarify:
- What data is sent to the proxy (e.g., signed payment authorizations, amounts, recipient addresses).
- What the trust implications are for a buyer whose payment is settled through BankOfAI's infrastructure.
- Whether the proxy is open-source or auditable.
Security-conscious developers and DeFi users will want to understand what they are trusting before configuring ExactGasFreeClientMechanism for production use.
Recommendation
Add a brief trust-model note in network-and-token-support.md under the exact_gasfree section explaining the data flow and any relevant audit/open-source information about the facilitator proxy.
Suggestions
[S-01] Hardcoded Price Example May Mislead Users About Expected Output
File: docs/McpServer-Skills/MCP/SUNCli/QuickStart.md, i18n/zh-Hans/.../QuickStart.md
Description: The Quick Start guide shows a concrete sample output with a fixed TRX price:
│ TRX │ 0.301739439813 │
This is a snapshot value. As time passes and TRX price changes, new users may think the CLI is returning stale data when they see a different value. The Chinese translation contains the same hardcoded price.
Suggestion: Append a brief note such as: "The displayed price reflects live market data and will differ from the example above."
[S-02] swap:quote-raw and swap:exact-input Examples Are Missing
File: docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md : Lines 192-222
Description: The low-level commands swap:quote-raw and swap:exact-input are documented with option tables but have no bash example invocations, unlike every other command in the guide. This creates an inconsistency and makes these advanced commands harder to use correctly.
Suggestion: Add at least one illustrative example for each command, even if with placeholder values, consistent with the rest of the Command Guide format.
[S-03] wallet address Description Slightly Diverges Between English and Chinese
File: docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md vs. i18n/zh-Hans/.../CommandGuide.md
Description:
- English:
"Print the active wallet address." - Chinese:
"显示已配置的钱包地址."(Display the configured wallet address.)
The English says "active wallet" while the Chinese says "configured wallet" — these are subtly different concepts (an active wallet may be selected from multiple configured ones). This is a minor translation inconsistency.
Suggestion: Align terminology across both language versions to use a consistent concept ("active" / "当前激活的").
Positive Observations
| Area | Observation |
|---|---|
| Security Guidance | Intro.md and QuickStart.md both include prominent :::warning / :::caution callout blocks advising users to use environment variables rather than command-line flags for private keys, and to test on Nile before mainnet. This is excellent practice. |
| Dual Language Coverage | All new content and every changed doc page is fully mirrored in Chinese (zh-Hans), ensuring non-English-speaking users receive complete, up-to-date documentation. |
| Read vs. Write Labeling | Every command entry in the Command Guide is consistently tagged with (read) or (write), making it immediately clear whether a wallet is required. This is a developer-experience best practice for DeFi tooling. |
--dry-run Promotion |
Both the CLI docs and existing x402 docs promote --dry-run as a safety mechanism. This is highlighted in security callouts and the Command Guide, reinforcing safe usage patterns. |
| Sidebar Navigation | The SUN CLI docs are registered in both sidebars.js files with a logical ordering (Intro → QuickStart → CommandGuide → FAQ), following the established pattern for other MCP server sections. |
| Consistency in Command Structure | The Command Guide follows a consistent structure throughout: description, synopsis, options table with defaults, and runnable examples. This makes the 852-line reference document easy to navigate. |
exact_gasfree Feature Completeness |
The new payment scheme is documented across all relevant files (concept doc, FAQ, SDK features, quickstart code examples in both Python and TypeScript, and both languages) — no orphaned references. |
| Version Bump | The package.json version was correctly incremented from 1.2.7 to 1.2.8 to reflect the new documentation content. |
Checklist Results
| Category | Items Checked | Pass | Fail | N/A | Notes |
|---|---|---|---|---|---|
| Correctness | 5 | 4 | 1 | 0 | Env var name inconsistency (MJ-01) |
| Security | 6 | 4 | 2 | 0 | Private key examples (MJ-03), undisclosed trust dependency (MJ-02) |
| Performance | 3 | 0 | 0 | 3 | No performance-relevant code changes |
| Code Quality | 5 | 4 | 1 | 0 | Missing examples for 2 commands (S-02) |
| Testing | 4 | 0 | 0 | 4 | Documentation-only PR; no executable code changed |
| Documentation | 8 | 6 | 2 | 0 | BSC identifier inconsistency EN vs ZH (MN-02); trust model gap (MN-03) |
| Compatibility | 3 | 3 | 0 | 0 | No breaking changes to existing docs or APIs |
| Observability | 2 | 2 | 0 | 0 | N/A for documentation |
Disclaimer
This is an automated code review. It supplements but does not replace human review. The reviewer analyzed only the diff between main and update-mcp-server. Runtime behavior of the documented CLI tool itself, SDK correctness, and deployment impact are not covered.
Report generated by Code Review Skill v1.0.0
Date: 2026-04-08
Code Review ReportProject: @x402-tron/docs PR OverviewBranch Information
Commit History
Review SummaryVerdict
Findings at a Glance
SummaryThis PR adds two major feature areas to the documentation site: (1) a brand-new SUN CLI section ( Overall the documentation is well-structured, detailed, and contains appropriate security cautions. However, there are several Major findings: an internal cross-reference link is broken, the English Command Guide is one line longer than its Chinese counterpart (minor sync drift that could silently surface), and the new Change Summary1. SUN CLI Documentation (New)
Purpose: Expose the 2. x402
|
| File | Change Type | Description |
|---|---|---|
docs/x402/core-concepts/network-and-token-support.md |
Modified | Added exact_gasfree scheme section; updated scheme count from two to three; updated summary table |
docs/x402/faq.md |
Modified | Updated payment schemes answer to include exact_gasfree |
docs/x402/getting-started/quickstart-for-agent.md |
Modified | Added fallback RPC endpoint note; updated TronGrid API key guidance |
docs/x402/getting-started/quickstart-for-human.md |
Modified | Added ExactGasFreeClientMechanism registration to Python and TypeScript code examples |
docs/x402/getting-started/quickstart-for-sellers.md |
Modified | Updated TronGrid API key guidance; added fallback RPC endpoint note |
docs/x402/index.md |
Modified | Minor formatting: bolded network names |
docs/x402/sdk-features.md |
Modified | Added exact_gasfree/tron, SufficientBalancePolicy, GasFree, and USDD (TRC-20) to feature table |
i18n/zh-Hans/... (7 files) |
Modified | Chinese locale mirrors of all x402 changes above |
Purpose: Document the newly implemented exact_gasfree TRON payment scheme, which enables buyers to pay with USDT/USDD without holding TRX for gas fees.
3. Package Version Bump
| File | Change Type | Description |
|---|---|---|
package.json |
Modified | Version bumped 1.2.7 → 1.2.8 |
Detailed Findings
Major
[MJ-01] Broken Internal Cross-Reference Link in FAQ
| Property | Value |
|---|---|
| Severity | Major |
| Category | Correctness / Documentation |
| File | docs/McpServer-Skills/MCP/SUNCli/FAQ.md : Line 5 (footer) |
Description
The FAQ footer links to ./CommandGuide.md — which is correct — but it also references an issue tracker at https://github.com/BofAI/sun-cli. This external link points to a repository path (BofAI/sun-cli) that is inconsistent with the npm package name (@bankofai/sun-cli) and the agent-wallet link used elsewhere in the same documents (https://github.com/ABlockofAI/agent-wallet). The org name varies between BofAI, bankofai, and ABlockofAI across the PR, suggesting at least one of these GitHub URLs is stale or incorrect.
Additionally, the Quick Start page links to ../SUNMCPServer/Intro.md which may not resolve if the SUNMCPServer directory does not exist at that relative path.
Code
<!-- docs/McpServer-Skills/MCP/SUNCli/FAQ.md, last line -->
or file an issue on the [GitHub repository](https://github.com/BofAI/sun-cli).
<!-- docs/McpServer-Skills/MCP/SUNCli/QuickStart.md, line ~147 -->
- **[SUN MCP Server](../SUNMCPServer/Intro.md)** — Prefer AI-driven DeFi?
<!-- docs/McpServer-Skills/MCP/SUNCli/Intro.md — agent-wallet link -->
[agent-wallet](https://github.com/ABlockofAI/agent-wallet)
<!-- docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md — same link -->
[agent-wallet](https://github.com/ABlockofAI/agent-wallet)Recommendation
- Standardize all GitHub org references. Confirm the canonical org (
BofAI,bankofai, orABlockofAI) and apply it consistently across all new files. - Verify that
../SUNMCPServer/Intro.mdresolves to an existing file before merging; if it does not yet exist, replace with a placeholder or remove the link.
[MJ-02] English and Chinese CommandGuide.md Line Count Divergence
| Property | Value |
|---|---|
| Severity | Major |
| Category | Documentation / Correctness |
| File | docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md (860 lines) vs i18n/zh-Hans/.../SUNCli/CommandGuide.md (859 lines) |
Description
The English source CommandGuide.md is 860 lines while the Chinese translation is 859 lines. While the diff shows largely equivalent content, this one-line discrepancy suggests content may have diverged silently during the multiple fix commits (64a0c36, 53baadb, 0f53ddb). Docusaurus i18n relies on translations being kept in sync; a content difference can mislead Chinese-speaking users.
Code
+++ b/docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md
@@ -0,0 +1,860 @@
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNCli/CommandGuide.md
@@ -0,0 +1,859 @@
Recommendation
Diff the English and Chinese CommandGuide.md files locally to identify the diverging line. Either add the missing line to the Chinese version or confirm the difference is intentional (e.g., a condensed Chinese paragraph). Add a translation-sync note in the PR description.
[MJ-03] Dual tron:* Mechanism Registration Without Priority/Selection Documentation
| Property | Value |
|---|---|
| Severity | Major |
| Category | Correctness / Documentation |
| File | docs/x402/getting-started/quickstart-for-human.md : Lines ~436–437 (Python), ~461–464 (TypeScript) |
Description
The new code examples register both ExactPermitTronClientMechanism and ExactGasFreeClientMechanism on the same tron:* wildcard pattern. Neither the inline comments nor the surrounding prose explains which mechanism takes priority, under what conditions each is selected, or whether both are attempted in sequence. A developer following this quickstart literally will be left uncertain whether their payment will use exact_permit or exact_gasfree on any given request, and may unknowingly send the wrong mechanism to a server that only accepts one.
Code
# Python – quickstart-for-human.md
x402_client.register("tron:*", ExactPermitTronClientMechanism(signer))
x402_client.register("tron:*", ExactGasFreeClientMechanism(signer, clients=gasfree_clients))// TypeScript – quickstart-for-human.md
x402.register('tron:*', new ExactPermitTronClientMechanism(signer))
x402.register('tron:*', new ExactGasFreeClientMechanism(signer, {
'tron:nile': new GasFreeAPIClient(getGasFreeApiBaseUrl('tron:nile')),
'tron:mainnet': new GasFreeAPIClient(getGasFreeApiBaseUrl('tron:mainnet')),
}))Recommendation
Add explanatory prose above the code examples, e.g.:
Registering both mechanisms allows the client to handle servers that advertise either
exact_permitorexact_gasfreein their402response. The SDK selects the mechanism whose scheme name matches the server's advertised scheme — if no match is found the payment is declined. The order ofregister()calls does not set a priority; each mechanism is selected by scheme name.
Also consider showing a simpler example first (single mechanism) and presenting the multi-mechanism registration as an advanced pattern.
Minor
[MN-01] exact_gasfree Only References Nile Testnet — Shasta Omitted
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | docs/x402/core-concepts/network-and-token-support.md : Lines ~1318–1327 |
Description
The new exact_gasfree scheme description lists only tron:mainnet and tron:nile as supported networks, but the x402 documentation elsewhere lists tron:shasta as a supported TRON network. It is unclear whether exact_gasfree is intentionally unavailable on Shasta or simply omitted. This ambiguity could confuse developers who test on Shasta.
Code
- **TRON only**: Available on `tron:mainnet` and `tron:nile`Recommendation
Explicitly state whether Shasta support is planned, in progress, or unsupported:
- **TRON only**: Available on `tron:mainnet` and `tron:nile`. `tron:shasta` is not currently supported.[MN-02] Inconsistent TronGrid API Key Guidance Between Agent and Sellers Quickstarts
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | docs/x402/getting-started/quickstart-for-agent.md and quickstart-for-sellers.md |
Description
The old documentation stated that TRON_GRID_API_KEY is "required for mainnet" — a strong, clear instruction. The PR softens this to "recommended for production workloads" and introduces a fallback BankOfAI-proxied endpoint. While this is technically accurate, the change may lead production users to skip configuring a proper API key, relying on an endpoint with "no guaranteed SLA" (which is noted in the new callout boxes, but easy to miss). The sellers quickstart .env comment is now subtly inconsistent with the fallback callout that immediately follows it:
Code
# quickstart-for-sellers.md .env comment:
# TronGrid API Key (required for mainnet; recommended for production workloads)The phrase "required for mainnet; recommended for production workloads" is self-contradictory — "required" and "recommended" apply to the same scenario (mainnet production).
Recommendation
Unify the guidance. Since the fallback endpoint exists, "required" is no longer accurate. Use consistent language:
# TronGrid API Key — strongly recommended for production workloads.
# Without it, mainnet RPC calls fall back to a BankOfAI-operated proxy with no SLA guarantee.[MN-03] Code Examples in CommandGuide Use Placeholder Addresses That May Be Confusing
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md : Lines ~814, ~832 |
Description
The contract read and contract send examples use TYourAddress, TContract, and TRecipient as placeholder addresses. While the intent is clear, TRON addresses follow a specific T-prefixed base58 format and these placeholders look syntactically valid to a casual reader, which may lead to copy-paste errors — especially for the contract send example, which references TRecipient in both the address position and inside the JSON args array.
Code
sun contract read TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t balanceOf --args '["TYourAddress"]'
sun contract send TRecipient transfer --args '["TRecipient","1000000"]' --value 0Recommendation
Use clearly invalid placeholder notation (e.g., <YOUR_TRON_ADDRESS>) or use a real well-known testnet address for the example:
sun contract send <CONTRACT_ADDRESS> transfer --args '["<RECIPIENT_ADDRESS>","1000000"]' --value 0[MN-04] wallet address Description Differs Between English and Chinese
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md vs i18n/zh-Hans/.../CommandGuide.md |
Description
The English wallet address command is described as "Print the active wallet address." whereas the Chinese translation renders it as "显示已配置的钱包地址" ("Display the configured wallet address"). These are semantically close but not identical ("active" vs. "configured"), which may cause translation mismatches in future updates.
Recommendation
Align the English description to "Print the configured wallet address." to match the more accurate Chinese phrasing and avoid future drift.
[MN-05] Chinese sdk-features.md Renames BSC Network Identifiers Without English Equivalent
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/sdk-features.md : Lines ~62–63 |
Description
The Chinese sdk-features.md changes bsc:mainnet → eip155:56 (BSC Mainnet) and bsc:testnet → eip155:97 (BSC Testnet). This is a substantive correction (using the canonical EIP-155 chain IDs) but the equivalent change was not made to the English docs/x402/sdk-features.md, leaving the two files inconsistent.
Code
-| bsc:mainnet | ✅ | ✅ |
-| bsc:testnet | ✅ | ✅ |
+| eip155:56 (BSC Mainnet) | ✅ | ✅ |
+| eip155:97 (BSC Testnet) | ✅ | ✅ |Recommendation
Apply the same identifier correction to the English docs/x402/sdk-features.md to keep both locales in sync. If bsc:mainnet is a valid SDK identifier (not just a friendly name), document both the friendly name and the EIP-155 chain ID.
Suggestions
[S-01] Add exact_gasfree to the quickstart-for-agent.md Code Examples
File: docs/x402/getting-started/quickstart-for-agent.md
Description: The agent quickstart updated prose and the fallback RPC note but did not add ExactGasFreeClientMechanism registration to its code examples (unlike the human quickstart which was updated). If the exact_gasfree feature is relevant to AI agents — which it should be, since removing the TRX gas requirement simplifies autonomous agent wallet management — the agent quickstart should show how to register it.
Suggestion: Mirror the mechanism registration pattern from quickstart-for-human.md into quickstart-for-agent.md, with a note explaining that exact_gasfree is particularly useful for agents that don't manage TRX balances.
[S-02] Document contract send TronscanUrl Return Behavior More Prominently
File: docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md : Line 835
Description: The note "contract send returns tronscanUrl when a transaction is broadcast successfully" appears only for contract send but not for swap, liquidity v2:add, liquidity v3:mint, etc. — all of which presumably also return a transaction ID. Consistent return-value documentation across write commands would improve the reference quality.
Suggestion: Add a "Returns" row or note to each write command's table indicating what is returned on success (e.g., txId, tronscanUrl, pool address).
[S-03] Consider Adding Version or "Since" Tags to New Features
File: docs/x402/sdk-features.md, docs/x402/core-concepts/network-and-token-support.md
Description: The exact_gasfree scheme and SufficientBalancePolicy are new features. Adding a "since version" tag (e.g., Since v1.2.8) would help users know which SDK version they need to upgrade to in order to access these features.
Suggestion: Add a Since: x.y.z badge or inline note next to the new rows in sdk-features.md.
[S-04] Security Caution in CommandGuide — Expand Shell History Risk Guidance
File: docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md : Lines 34–40
Description: The :::caution Private Key Security block correctly warns about shell history and process listings. Consider also mentioning ps aux as a live exposure risk (not just history), and suggesting unset commands after setting sensitive env vars.
Suggestion:
:::caution Private Key Security
The `-k` / `--private-key` and `-m` / `--mnemonic` flags pass sensitive
material as command-line arguments, which may be visible in shell history
(`~/.bash_history`, `~/.zsh_history`), process listings (`ps aux`), and
system logs. Prefer environment variables or agent-wallet encrypted storage.
After setting a sensitive environment variable for a session, run `unset AGENT_WALLET_PRIVATE_KEY`
when done.
:::Positive Observations
| Area | Observation |
|---|---|
| Security messaging | Both new CLI docs and x402 docs consistently include prominent :::caution and :::warning blocks for private key handling — this is excellent practice for DeFi documentation. |
| Dry-run / testnet first guidance | Multiple pages explicitly recommend --dry-run and testnet validation before mainnet operations. This layered safety advice reduces user errors in irreversible DeFi operations. |
| Read vs. write command labeling | Every command in the Command Guide is labeled (read) or (write), making it immediately clear which commands require a wallet. This is a well-thought-out UX detail. |
| Bilingual parity | All four new SUN CLI pages have corresponding Chinese translations, and all modified x402 pages have corresponding Chinese updates. This shows discipline in maintaining i18n parity. |
| Fallback RPC transparency | The new :::note Fallback RPC Endpoint callouts clearly disclose the BankOfAI-operated fallback, its SLA limitations, and how to override it — this is honest and user-respectful documentation. |
| Code example quality | The quickstart-for-human.md examples are complete, runnable snippets (proper imports, env var usage, async patterns) rather than fragments — good for copy-paste workflows. |
Checklist Results
| Category | Items Checked | Pass | Fail | N/A | Notes |
|---|---|---|---|---|---|
| Correctness | 8 | 6 | 2 | 0 | Broken/inconsistent links (MJ-01); zh/en line count divergence (MJ-02) |
| Security | 10 | 10 | 0 | 0 | Security warnings present; no hardcoded keys; private key caution blocks included |
| Performance | 7 | 0 | 0 | 7 | Documentation-only PR; not applicable |
| Code Quality | 8 | 6 | 2 | 0 | Dual-mechanism registration undocumented (MJ-03); placeholder addresses (MN-03) |
| Testing | 7 | 0 | 0 | 7 | Documentation-only PR; not applicable |
| Documentation | 6 | 4 | 2 | 0 | zh/en identifier mismatch (MN-05); API key guidance inconsistency (MN-02) |
| Compatibility | 5 | 5 | 0 | 0 | Docusaurus sidebar entries follow existing patterns; i18n mirrored correctly |
| Observability | 4 | 0 | 0 | 4 | Documentation-only PR; not applicable |
Disclaimer
This is an automated code review. It supplements but does not replace human review. The reviewer analyzed only the diff between main and update-mcp-server. Runtime behavior, integration testing, and deployment impact are not covered. All links to external GitHub repositories and npm packages were evaluated based on text consistency only — actual URL validity was not verified.
Report generated by Code Review Skill v1.0.0
Date: 2026-04-08
Code Review ReportProject: BofAI Docs PR OverviewBranch Information
Commit History
Review SummaryVerdict
Findings at a Glance
SummaryThis PR introduces a large documentation expansion: a brand-new four-file SUN CLI documentation suite (~1,300 lines), updates to the TRON MCP Server docs (Privy wallet support, Docker deployment, version changelog entries), significant new x402 protocol quickstarts (agent, human, seller), an OpenClaw extension installer walkthrough, Agent Wallet CLI/SDK updates (Windows support, Node.js 20, However, three critical issues must be resolved before merge: a broken GitHub organisation name in a security-critical warning, an environment-variable naming inconsistency that would cause silent authentication failures in the x402 agent quickstart, and an unpinned Change Summary1. SUN CLI — New Documentation Suite (4 new files)
Purpose: Documents the new SUN CLI tool that exposes SunSwap DeFi capabilities as a structured command-line interface for both human and AI-agent consumers. 2. TRON MCP Server — Documentation Updates
Purpose: Updates the TRON MCP Server documentation to reflect v1.1.7 changes, deprecate the old private-key based wallet in favour of Agent Wallet, and document the new Docker deployment path. 3. Agent Wallet — Documentation Updates
Purpose: Reflects new Agent Wallet capabilities: Privy server-wallet support, Windows compatibility, new CLI commands, and a Node.js 20 minimum. 4. x402 Protocol — Documentation Suite
Purpose: Substantially expands the x402 payment protocol documentation to cover all three user roles (agent, human developer, API seller) with working code examples in both TypeScript and Python. 5. Other Changes
Detailed FindingsCritical[C-01] Wrong GitHub Organisation Name in Security-Critical Warning
Description The caution admonition that warns users away from the insecure Code :::caution
For security reasons, avoid using `-k` and `-m` flags in production...
Instead, configure an **agent-wallet** (https://github.com/ABlockofAI/agent-wallet)
:::Recommendation :::caution
For security reasons, avoid using `-k` and `-m` flags in production...
Instead, configure an **agent-wallet** (https://github.com/BofAI/agent-wallet)
:::[C-02]
|
| Property | Value |
|---|---|
| Severity | Critical |
| Category | Correctness / Security |
| File | docs/x402/getting-started/quickstart-for-agent.md : lines 62–96 |
Description
Option B ("Static Private Key") for TRON instructs users to set TRON_PRIVATE_KEY. The Agent Wallet SDK documentation consistently uses AGENT_WALLET_PRIVATE_KEY for static injection mode. If the underlying SDK reads AGENT_WALLET_PRIVATE_KEY and not TRON_PRIVATE_KEY, the x402 agent integration will silently fail at payment time — the environment variable will be set but the wallet SDK will not find it, resulting in a "no wallet configured" error that a user would not be able to trace to this naming mismatch.
Code
# Option B: Static Private Key (for development/testing only)
export TRON_PRIVATE_KEY="your-tron-private-key-here"
# Verify it's set:
echo $TRON_PRIVATE_KEYRecommendation
Clarify which environment variable is actually consumed by the x402-payment skill vs. the Agent Wallet SDK. If TRON_PRIVATE_KEY is a skill-level wrapper that the skill translates internally, state this explicitly. If the correct name is AGENT_WALLET_PRIVATE_KEY, fix the example:
# Option B: Static Private Key (for development/testing only)
# Note: the x402-payment skill reads this via Agent Wallet SDK's static injection mode
export AGENT_WALLET_PRIVATE_KEY="your-tron-private-key-here"Also add a prominent production warning that the fallback BankOfAI public endpoint should not be relied upon in production deployments.
[C-03] Python SDK Installed from Unpinned git+https:// URL
| Property | Value |
|---|---|
| Severity | Critical |
| Category | Security / Code Quality |
| File | docs/x402/getting-started/quickstart-for-human.md : line 96–97; docs/x402/getting-started/quickstart-for-sellers.md : line 128 |
Description
Both the human and seller quickstart guides install the Python SDK directly from the repository's HEAD:
pip install "bankofai-x402[tron] @ git+https://github.com/BofAI/x402.git#subdirectory=python/x402"Installing from an unpinned git URL means: (1) the installed version changes without user knowledge whenever the repository is updated; (2) a malicious commit merged to the default branch becomes immediately distributed to all users who re-run the install command; (3) the install is unreliable (fails if the repo is renamed, deleted, or made private). There is no published PyPI package referenced, making this the only available install path.
Recommendation
Option A — Publish to PyPI and document:
pip install "bankofai-x402[tron]"Option B — Pin to a specific tag or commit:
pip install "bankofai-x402[tron] @ git+https://github.com/BofAI/x402.git@v1.0.0#subdirectory=python/x402"At minimum, add a callout:
:::caution Development build
This installs directly from the repository's default branch. The version may change
without notice. For production use, pin to a specific release tag.
:::Major
[MJ-01] contract send Example Conflates Contract Address and Recipient
| Property | Value |
|---|---|
| Severity | Major |
| Category | Correctness / Code Quality |
| File | docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md : lines 825–827 |
Description
The example uses TRecipient as both the positional <address> argument (the smart contract address) and as the first element of --args (the transfer recipient). These are two distinct addresses. A TRC20 transfer call needs the token contract address (e.g., USDT at TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t) in the first position, and the recipient wallet address in --args. As written, the example would point contract send at a wallet address rather than a contract, producing a confusing runtime failure.
Code
sun contract send TRecipient transfer --args '["TRecipient","1000000"]' --value 0Recommendation
# Transfer 1 USDT (6 decimals) from your wallet to TRecipientAddress
sun contract send TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t transfer \
--args '["TRecipientAddress","1000000"]' --value 0[MJ-02] Unverifiable MCP Protocol and SDK Version Numbers
| Property | Value |
|---|---|
| Severity | Major |
| Category | Correctness |
| File | docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md : line 207 |
Description
The FAQ states the server uses @modelcontextprotocol/sdk 1.22.0 or higher with protocol version 2025-11-25. The protocol version string looks unusual (future-dated from a historical perspective and much higher than publicly known releases), and @modelcontextprotocol/sdk 1.22.0 would be a very high minor version for that package. If these numbers are incorrect, developers who attempt to peer their own MCP client will fail to negotiate the correct protocol version.
Recommendation
Verify the exact values against the actual package.json of the deployed TRON MCP Server. Add an npm badge or direct link to the package page so readers can check the latest version themselves:
Uses `@modelcontextprotocol/sdk` [v1.22.0+](https://www.npmjs.com/package/@modelcontextprotocol/sdk) with protocol version `2025-11-25`.[MJ-03] Broken Cross-Document Link in SUNCli QuickStart
| Property | Value |
|---|---|
| Severity | Major |
| Category | Correctness / Navigation |
| File | docs/McpServer-Skills/MCP/SUNCli/QuickStart.md : line 147 |
Description
The "Next Steps" section links to ../SUNMCPServer/Intro.md. The actual directory under McpServer-Skills/MCP/ does not appear to contain a SUNMCPServer subdirectory (the TRON MCP Server lives under TRONMCPServer). This link will 404 in the rendered documentation site.
Recommendation
Verify the target directory name and correct the link. If no SUN MCP Server documentation exists yet, replace with a valid link or remove the forward reference until it is created:
<!-- If linking to TRON MCP Server: -->
[TRON MCP Server →](../TRONMCPServer/Intro.md)[MJ-04] FAQ File Name Case Sensitivity Risk (BANKOFAISkill)
| Property | Value |
|---|---|
| Severity | Major |
| Category | Correctness / Navigation |
| File | docs/McpServer-Skills/SKILLS/BANKOFAISkill.md : line 283 |
Description
The "Next Steps" section links to ./Faq.md (capital F, lowercase aq). On case-sensitive Linux filesystems used in CI/CD and production servers, this link will 404 if the file is named FAQ.md (all caps), which is the convention used everywhere else in this repo. The sidebar entry references McpServer-Skills/SKILLS/Faq — implying the file might intentionally be named Faq.md — but this violates the convention and is likely an error.
Recommendation
Rename the file to FAQ.md to match all other FAQ files, update the sidebar entry accordingly, and update the link in BANKOFAISkill.md:
[FAQ →](./FAQ.md)[MJ-05] TRON Server Example Missing Explicit Mechanism Registration
| Property | Value |
|---|---|
| Severity | Major |
| Category | Code Quality / Correctness |
| File | docs/x402/getting-started/quickstart-for-sellers.md : lines 163–164 |
Description
The TRON server code uses schemes=["exact_permit"] but does not explicitly register ExactPermitTronServerMechanism on the X402Server object, unlike the BSC example which follows an explicit pattern. This silently relies on SDK defaults. If the default mechanism changes in a future SDK version, the TRON server will break without a clear error.
Code
# TRON version (implicit)
server = X402Server(schemes=["exact_permit"], ...)
# BSC version (explicit - more robust)
server = X402Server(...)
server.register_mechanism(ExactPermitBscServerMechanism(...))Recommendation
Apply the same explicit registration pattern to the TRON example:
from bankofai.x402.server.mechanisms.tron import ExactPermitTronServerMechanism
server = X402Server(...)
server.register_mechanism(
ExactPermitTronServerMechanism(pay_to_address=PAY_TO_ADDRESS)
)[MJ-06] PAY_TO_ADDRESS Placeholder Not Validated at Startup
| Property | Value |
|---|---|
| Severity | Major |
| Category | Security / Code Quality |
| File | docs/x402/getting-started/quickstart-for-sellers.md : line 178 |
Description
The code uses PAY_TO_ADDRESS = "YourTronWalletAddressHere" as a placeholder. Python does not validate this string at import time, so the FastAPI app will start successfully even if the user forgets to replace it. The error will only manifest at payment verification time — likely with a confusing cryptographic failure, not a clear configuration error.
Recommendation
Add an explicit startup check:
PAY_TO_ADDRESS = "YourTronWalletAddressHere"
# Add this validation block immediately after the assignment:
if not PAY_TO_ADDRESS.startswith("T") or len(PAY_TO_ADDRESS) != 34:
raise ValueError(
"PAY_TO_ADDRESS is still a placeholder. "
"Replace it with your TRON wallet address before starting the server."
)[MJ-07] Windows Support Version Number Cannot Be Verified
| Property | Value |
|---|---|
| Severity | Major |
| Category | Correctness |
| File | docs/Agent-Wallet/FAQ.md : line 144 |
Description
The FAQ states Windows support was introduced in Agent Wallet v2.3.x. No other document in this repository or PR references Agent Wallet version numbers, and the docs package.json is at 1.2.8. If the Agent Wallet library is at a different version, this claim is incorrect and will mislead users trying to determine if their installed version supports Windows.
Recommendation
Verify the exact release version from the Agent Wallet changelog and add a link:
Windows support was added in **[v2.3.0](https://github.com/BofAI/agent-wallet/releases/tag/v2.3.0)**.[MJ-08] Confusing Env-Var vs HTTP-Header Documentation for TronGrid API Key
| Property | Value |
|---|---|
| Severity | Major |
| Category | Correctness / Clarity |
| File | docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md : lines 94–98 |
Description
The FAQ mixes two different configuration contexts within the same answer: the environment variable TRONGRID_API_KEY (for local deployments) and the HTTP header TRONGRID-API-KEY:your-key (for the cloud service). These are two distinct mechanisms, and the distinction is never explained clearly. A user may set the env var and expect the cloud service to use it, or vice versa.
Recommendation
Split the answer into two clearly labelled subsections:
**Local deployment:** Set the environment variable `TRONGRID_API_KEY=your-key` in your `.env` file.
**Official cloud service:** Pass the HTTP header `TRONGRID-API-KEY: your-key` in each request to the hosted endpoint.[MJ-09] Python SDK Cookbook Example Has No 0x-Prefix Guard
| Property | Value |
|---|---|
| Severity | Major |
| Category | Code Quality |
| File | docs/Agent-Wallet/Developer/SDK-Cookbook.md : lines 337–338 |
Description
The EVM transfer cookbook example calls bytes.fromhex(signed_tx_hex) which will raise ValueError if signed_tx_hex starts with 0x. While the SDK documentation states signatures are returned without the 0x prefix, this assumption is not guarded against. If a future SDK version changes this, the example breaks with an opaque error.
Code
raw_tx = bytes.fromhex(signed_tx_hex) # breaks if SDK ever returns "0x..." prefixRecommendation
# Strip any '0x' prefix defensively, as SDK contract guarantees prefix-less output
# but this makes the example resilient to future SDK changes
raw_tx = bytes.fromhex(signed_tx_hex.removeprefix("0x"))[MJ-10] TRON_GRID_API_KEY vs TRONGRID_API_KEY — One Is Wrong
| Property | Value |
|---|---|
| Severity | Major |
| Category | Correctness / Consistency |
| File | docs/McpServer-Skills/MCP/SUNCli/QuickStart.md : line 134 |
Description
SUNCli's QuickStart references the environment variable as TRON_GRID_API_KEY (with an underscore between TRON and GRID), while all other documentation in this PR and the existing codebase uses TRONGRID_API_KEY (no underscore). Only one of these can be the variable actually read by the underlying SDK. A user who sets the wrong one will get silent failures when TronGrid rate-limits their requests.
Recommendation
Verify the correct variable name against the source code of the TRON MCP Server / SUN CLI and update all references to the single canonical name. Then add a cross-file find-and-replace to ensure consistency.
Minor
[MN-01] GitHub Org Name Used for SUN CLI Repository is Unverified
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Correctness |
| File | docs/McpServer-Skills/MCP/SUNCli/FAQ.md : line 133 |
Description
The "Still Need Help?" section links to https://github.com/BofAI/sun-cli. Three different organisation names appear across this PR: BofAI (GitHub, most files), bankofai (npm scope), and ABlockofAI (one wrong occurrence in CommandGuide). The BofAI/sun-cli link should be verified to exist before the PR is merged.
Recommendation
Confirm the correct GitHub repository URL for the SUN CLI project and ensure it is used consistently throughout the documentation.
[MN-02] -p Password Flag Shown Without Shell-History Warning
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Security |
| File | docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md : line 51 |
Description
The Global Flags example sun -p your_agent_wallet_password wallet address shows the password inline without noting that this records it in shell history — the same risk the caution block warns about for -k and -m.
Recommendation
Add a note beneath the -p example:
> **Note:** Passing `-p` inline records the password in shell history. For automation, set `AGENT_WALLET_PASSWORD` as an environment variable instead.[MN-03] SUN CLI Intro Describes SUN MCP Server Before Introducing SUN CLI
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation Quality |
| File | docs/McpServer-Skills/MCP/SUNCli/Intro.md : line 7 |
Description
The opening paragraph describes SUN MCP Server before introducing SUN CLI, which is the subject of the document. A new reader will be confused about what they are reading.
Recommendation
Reorder the opening to introduce SUN CLI first, then contrast it with SUN MCP Server.
[MN-04] --no-blacklist Flag Description is Ambiguous
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation Quality |
| File | docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md : line 246 |
Description
--no-blacklist is described as "Include blacklisted pools" with default false. While logically consistent, the phrasing is confusing: --no-blacklist (disable the blacklist) and "Include blacklisted pools" say the same thing in different ways.
Recommendation
Restate as: Disable the blacklist filter (include all pools regardless of blacklist status).
[MN-05] Docker Volume Mount Command Incompatible with Windows
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Compatibility |
| File | docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md : lines 150–156 |
Description
The Docker run example uses $(pwd)/logs:/app/logs. On Windows, $(pwd) does not work in PowerShell (${PWD}) or CMD (%cd%). Since this PR adds Windows support documentation in Agent Wallet FAQ, the Docker command should be consistent.
Recommendation
Add a tabbed Windows/macOS-Linux code block or inline note:
# macOS / Linux:
-v $(pwd)/logs:/app/logs
# PowerShell (Windows):
-v ${PWD}/logs:/app/logs[MN-06] QuickStart Omits agent-wallet start Initialisation Step
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Completeness |
| File | docs/McpServer-Skills/MCP/SUNCli/QuickStart.md : lines 83–89 |
Description
The QuickStart installs agent-wallet but does not tell users to run agent-wallet start to initialise it. Users who install but do not initialise the wallet will receive a confusing "No wallet configured" error when first running SUN CLI commands.
Recommendation
Add an explicit initialisation step after the install command:
npm install -g @bankofai/agent-wallet
agent-wallet start # creates and encrypts your wallet[MN-07] change-password Command Offers No Secure Non-Interactive Path for New Password
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Security |
| File | docs/Agent-Wallet/Developer/CLI-Reference.md : lines 300–325 |
Description
The change-password command documents only the inline --new-password flag approach for non-interactive use, which records the new password in shell history. Unlike the init/start commands, no env-var or file-based alternative is offered.
Recommendation
Add guidance for a secure non-interactive path:
# Preferred: pipe the new password from a secrets manager
echo "NewSecurePassword" | agent-wallet change-password --new-password-stdin
# Or set via environment variable (if supported by the version)
AGENT_WALLET_NEW_PASSWORD="NewSecurePassword" agent-wallet change-password[MN-08] Python Version Requirement Inconsistency (3.10 vs 3.11)
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Consistency |
| File | docs/x402/getting-started/quickstart-for-human.md : line 30 |
Description
The x402 human quickstart lists Python 3.10+ as a prerequisite. The Agent Wallet SDK Guide requires Python ≥3.11. A user who installs Python 3.10 based on the x402 guide will later fail when using the Agent Wallet SDK.
Recommendation
Standardise the minimum Python version to 3.11 across all documents, or explicitly note which component requires which version.
[MN-09] SDK Install Verification Command Tests the Wrong Import
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Code Quality |
| File | docs/x402/getting-started/quickstart-for-sellers.md : line 139 |
Description
The verification step python -c "import bankofai.x402; print('SDK installed successfully!')" only confirms the top-level module imports. It does not verify that the specific server components used in the tutorial are importable.
Recommendation
python -c "from bankofai.x402.server import X402Server; print('SDK installed successfully!')"[MN-10] x402 FAQ Contradicts Quickstart on Self-Hosting vs. Official Facilitator
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Consistency |
| File | docs/x402/faq.md : line 43 |
Description
The FAQ says "Typically, you run your own Facilitator service. x402 is designed for self-hosting." The seller quickstart recommends the Official Facilitator first. This contradiction creates a misleading first impression for FAQ readers.
Recommendation
Update the FAQ to reflect the recommended path:
You can use the **Official Facilitator** service (recommended for getting started quickly)
or run your own **self-hosted Facilitator** for full control in production.[MN-11] Full-Width CJK Parentheses in BANKOFAISkill.md
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Formatting |
| File | docs/McpServer-Skills/SKILLS/BANKOFAISkill.md : line 247 |
Description
The example URL contains full-width CJK parentheses: https://api.example.com （replace with the actual paid endpoint URL you want to call）. These are Unicode full-width characters, not standard ASCII parentheses.
Recommendation
Replace with standard ASCII parentheses:
https://api.example.com (replace with the actual paid endpoint URL you want to call)[MN-12] OpenClaw Private Key Terminal Prompt Exposure Not Mentioned
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Security |
| File | docs/Openclaw-extension/QuickStart.md : lines 254–263 |
Description
The installer caution mentions that the config file permissions are set to 600, but does not note that typing a private key into an interactive terminal prompt may itself be logged by some terminal audit configurations.
Recommendation
Add a brief note:
> **Note:** The private key is accepted via an interactive prompt, which may be logged
> by terminal audit software (e.g., `script`, `ttyrec`). Use a minimal-balance dedicated
> wallet for the BNB Chain integration.[MN-13] TypeScript SDK Server Role Not Available — Missing Prominent Warning
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Completeness |
| File | docs/x402/sdk-features.md and docs/x402/getting-started/quickstart-for-sellers.md |
Description
The SDK feature matrix marks TypeScript Server, Facilitator and related server-role features as ⏳ (planned). The seller quickstart is Python-only, but there is no prominent notice at the top of that guide informing TypeScript developers that server-side support is not yet available.
Recommendation
Add to the top of quickstart-for-sellers.md:
:::info TypeScript server support coming soon
The server-side code in this guide is Python only. TypeScript server support is currently
planned — see [SDK Features](../sdk-features.md) for the current roadmap.
:::[MN-14] start Script Uses --openssl-legacy-provider (Outdated Dependencies Signal)
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Code Quality |
| File | package.json : line 8 |
Description
The start script uses NODE_OPTIONS='--openssl-legacy-provider', indicating the project relies on deprecated OpenSSL behavior due to an outdated Docusaurus 2.4.3 dependency chain. This flag may stop working in future Node.js LTS releases and represents accumulated technical debt.
Recommendation
Consider upgrading to Docusaurus 3.x which supports Node.js 20+ natively without the legacy flag. At minimum, document why the flag is present in a CONTRIBUTING.md note.
[MN-15] Shell Comment Says "capture the hash output" — Should Be "signature"
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation Quality |
| File | docs/Agent-Wallet/Developer/CLI-Reference.md : lines 350–362 |
Description
A shell script example contains the comment # capture the hash output but sign msg returns a signature, not a hash.
Recommendation
# capture the signature output
SIGNATURE=$(agent-wallet sign msg "Hello from my script" -n tron)Suggestions
[S-01] Add a Read/Write Legend at the Top of CommandGuide.md
File: docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md
Description: Many command section headers include (read) or (write) labels but there is no legend explaining what these mean or their resource implications (write operations cost TRX bandwidth/energy).
Suggestion: Add a brief table at the top of the command reference explaining the labelling system and wallet/resource requirements for write operations.
[S-02] Explain V4 vs V3 Token Argument Differences in Liquidity Section
File: docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md (Liquidity section)
Description: V4 liquidity commands require --token0/--token1 at every call, while V3 treats them as optional. This architectural difference is not explained.
Suggestion: Add a brief note explaining that V4 uses a different position identification model from V3 NFTs, which is why token context is required at every V4 call.
[S-03] Provide a Self-Hostable Fallback for the Demo Endpoint
File: docs/x402/getting-started/quickstart-for-agent.md, docs/x402/getting-started/quickstart-for-human.md
Description: Both guides use https://x402-demo.bankofai.io/protected-nile as the test endpoint. If this is down, users cannot complete the tutorial.
Suggestion: Point users to the seller quickstart to spin up their own test server as a fallback, or provide a status page URL for the demo endpoint.
[S-04] Add a Docker Update Path to the TRON MCP Server FAQ
File: docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md : line 200
Description: The "How do I update to the latest version?" section covers source-based deployments only. Docker users (Option D in the deployment guide) have no documented update path.
Suggestion:
**Docker deployment:**
docker pull bankofai/tron-mcp-server:latest
docker stop mcp-server-tron && docker rm mcp-server-tron
# Then re-run the original docker run command[S-05] Consider Removing Emoji from Developer SDK Guide Headers
File: docs/Agent-Wallet/Developer/SDK-Guide.md : line 146
Description: Section headers use emoji (🛡️,
Suggestion: Standardise developer-oriented docs to plain text headers, reserving emoji for user-facing guides where they aid quick scanning.
Cross-File Consistency Issues
| # | Issue | Files Affected | Severity |
|---|---|---|---|
| X-1 | Node.js version inconsistency: Openclaw-extension/QuickStart.md still requires v18 while all other docs now require v20 |
docs/Openclaw-extension/QuickStart.md vs 5 other files |
Major |
| X-2 | GitHub org name: ABlockofAI (1 occurrence) vs BofAI (everywhere else) |
docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md |
Critical (covered in C-01) |
| X-3 | TronGrid env var: TRON_GRID_API_KEY vs TRONGRID_API_KEY — only one can be correct |
docs/McpServer-Skills/MCP/SUNCli/QuickStart.md vs all others |
Major (covered in MJ-10) |
| X-4 | Python minimum version: 3.10 vs 3.11 across different documents | docs/x402/getting-started/quickstart-for-human.md vs Agent-Wallet/Developer/SDK-Guide.md |
Minor (covered in MN-08) |
Positive Observations
| Area | Observation |
|---|---|
| Security messaging | Security warnings are prominent, appropriately placed, and use :::danger/:::caution admonitions correctly throughout all new documentation |
| Privy wallet integration | Privy wallet type is consistently documented across CLI-Reference, FAQ, SDK-Guide, and QuickStart — including accurate security tradeoffs between cloud custody and local encryption |
| SUN CLI command coverage | CommandGuide.md comprehensively covers all command categories with uniform table formatting, required/optional flag labeling, and working examples |
| Agent Wallet error hierarchy | New Privy-specific error types (PrivyConfigError, PrivyRequestError, PrivyRateLimitError, PrivyAuthError) are correctly documented in the error type hierarchy |
| x402 seller quickstart structure | The separation of Official Facilitator vs. Self-Hosted paths, the mainnet migration checklist, and the troubleshooting table are all production-quality documentation |
| SDK Cookbook defensive coding | The TRON transfer example validates fromAddress vs wallet address, checks for txID, and guards against missing signatures — demonstrating best-practice error handling in examples |
| Windows support documentation | The Openclaw QuickStart includes Windows-specific icacls permission notes and the FAQ covers npm permission fixes — thorough cross-platform coverage |
| Admonition consistency | Use of :::tip, :::caution, :::danger, and :::warning is consistent and contextually appropriate throughout all changed files |
--dry-run flag promotion |
The repeated recommendation to use --dry-run before executing write operations is an excellent safety-oriented pattern throughout the SUN CLI docs |
Checklist Results
| Category | Items Checked | Pass | Fail | N/A |
|---|---|---|---|---|
| Correctness | 8 | 5 | 3 | 0 |
| Security | 10 | 7 | 3 | 0 |
| Performance | 7 | 7 | 0 | 0 |
| Code Quality | 10 | 7 | 3 | 0 |
| Testing | 7 | 3 | 2 | 2 |
| Documentation | 6 | 4 | 2 | 0 |
| Compatibility | 5 | 3 | 2 | 0 |
| Observability | 5 | 5 | 0 | 0 |
Disclaimer
This is an automated code review. It supplements but does not replace human review. The reviewer analysed only the diff between main and update-mcp-server. Runtime behaviour, integration testing, and deployment impact are not covered. All command examples and version numbers in the changed documentation should be validated against the actual source code before merge.
Report generated by Code Review Skill v1.0.0
Date: 2026-04-08
Code Review ReportProject: BofAI/docs PR OverviewBranch Information
Commit History
Review SummaryVerdict
Findings at a Glance
SummaryThis PR is a substantial documentation update spanning 54 files across English and Chinese (zh-Hans) localizations. The core changes introduce an entirely new SUN CLI section (4 files + 4 zh-Hans translations), update the TRON MCP Server docs to reflect v1.1.7 breaking changes (removal of legacy The overall quality is high: security posture is improved (legacy plaintext key variables removed, migration to encrypted Agent Wallet enforced, SDK examples updated to Change Summary1. SUN CLI — New Documentation (4 files + 4 zh-Hans mirrors)
Purpose: Introduces SUN CLI ( 2. TRON MCP Server v1.1.7 Breaking Changes
Purpose: Reflects v1.1.7 changes: 3. Agent-Wallet Documentation Updates
Purpose: Documents new wallet type ( 4. x402 Documentation Updates
Purpose: Documents the new 5. OpenClaw Extension and BANKOFAI Skill Updates
Purpose: Reflects updated installer behavior and documents additional skill capabilities. 6. Configuration
Detailed FindingsMajor[MJ-01] Breaking Change Migration Path Not Visible from QuickStart
Description
Code +:::caution Legacy wallet options removed
+As of v1.1.7, the legacy `TRON_PRIVATE_KEY` and `TRON_MNEMONIC` environment variables
+are no longer supported. All wallet management is now handled through Agent Wallet.
+If you were previously using plaintext private keys or mnemonics, please migrate to
+Agent Wallet for improved security.
+:::(Only appears in Recommendation Add a visible migration banner to :::caution Breaking change in v1.1.7
`TRON_PRIVATE_KEY` and `TRON_MNEMONIC` are no longer supported. Migrate to
[Agent Wallet](./LocalPrivatizedDeployment.md#agent-wallet) before upgrading.
:::Minor[MN-01] Likely Broken Internal Link in SUN CLI QuickStart
Description
Code - **[SUN MCP Server](../SUNMCPServer/Intro.md)** — Prefer AI-driven DeFi? Use SUN MCP Server
for natural language interactionRecommendation
[MN-02]
|
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md |
Description
The English
CLI-Reference.mdgained a 24-line section documenting the newagent-wallet initcommand (initialize secrets directory without creating a wallet). The zh-Hans translation ofCLI-Reference.mdhas +54 lines vs the English's +89 lines, and theinitsection is not present in the Chinese diff. Chinese-speaking users who read the zh-Hans version will not know this command exists.
Code
### `agent-wallet init` (Initialize Secrets Directory)
Initialize the secrets directory and set the master password — without creating a
wallet yet. This is useful for advanced scenarios where you want to prepare the
directory before adding wallets.
...(Present in English; absent from zh-Hans.)
Recommendation
Add the translated
agent-wallet initsection to the zh-HansCLI-Reference.mdto keep the translation parity consistent with the English source.
[MN-03] --show-address Inspect Flag Missing from zh-Hans CLI-Reference Translation
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md |
Description
The English version documents a new
--show-addressflag for theagent-wallet inspectcommand (lines 71–79 in the English diff). This is also not present in the zh-Hans diff, continuing the pattern of translation gap for new commands.
Code
Show wallet metadata along with derived addresses:
```bash
agent-wallet inspect my-bsc-wallet --show-address| Flag | Description |
|---|---|
--show-address |
Derive and display EVM + TRON addresses ... |
*(Present in English; absent from zh-Hans.)*
**Recommendation**
> Add the translated `--show-address` documentation block to the zh-Hans `CLI-Reference.md`.
---
#### [MN-04] GasFree Activation Deposit Amount Is Hardcoded and May Become Stale
| Property | Value |
|----------|-------|
| **Severity** | Minor |
| **Category** | Documentation |
| **File** | `docs/x402/core-concepts/network-and-token-support.md` : Line (GasFree activation section) |
**Description**
> The documentation states that GasFree account activation "deposits a small amount of tokens (~3.05 USDT on nile)". Hardcoding a specific token amount in documentation is risky — if the protocol changes the activation deposit requirement, this figure silently becomes incorrect and may mislead users who rely on it for pre-funding their wallets.
**Code**
```markdown
The activation process deposits a small amount of tokens (~3.05 USDT on nile) to fund
the GasFree wallet, then submits a GasFree transaction to trigger activation.
Recommendation
Replace the hardcoded amount with a directional note and refer users to the GasFree info command for the current value:
The activation process deposits a small amount of tokens (run `--gasfree-info` first to see the current required amount) to fund the GasFree wallet, then submits a GasFree transaction to trigger activation.
Suggestions
[S-01] SUN CLI Examples Normalize --private-key Inline Flag Despite Security Warning
File: docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md
Description: The CommandGuide correctly includes a :::caution Private Key Security block warning that -k/--private-key flags appear in shell history. However, the Global Flags example immediately below still shows sun -k your_private_key --network nile --yes swap TRX USDT 1000000, which normalizes the unsafe pattern. Consider replacing the inline key example with an environment variable version, or adding an explicit note that the inline example is only for illustration.
Suggestion: Replace the example with an agent-wallet or environment-variable-based equivalent, and label inline key examples as "NOT RECOMMENDED for production".
[S-02] httpx Timeout Increase (60→120) Undocumented in Code Comments
File: docs/x402/getting-started/quickstart-for-human.md
Description: The Python examples change httpx.AsyncClient(timeout=60.0) to timeout=120 without any explanation. Users copying this code may not understand why 120 seconds is needed — it may be due to GasFree transaction submission latency, but it's not stated.
Suggestion: Add a brief inline comment: # GasFree transactions may take longer to settle — use a generous timeout.
[S-03] exact_gasfree Activation Scope Not Clarified (One-Time vs Per-Token)
File: docs/x402/core-concepts/network-and-token-support.md
Description: The GasFree activation docs say it is "required before first use" but don't specify whether activation is per-wallet (one-time ever), per-wallet-per-network, or per-wallet-per-token. The --gasfree-activate --token USDT flag implies it may be per-token, but this is not explicitly stated.
Suggestion: Add a clarifying sentence, e.g.: "Activation is required once per wallet address per supported token. If you intend to pay with both USDT and USDD, activate each token separately."
Positive Observations
| Area | Observation |
|---|---|
| Security | Legacy plaintext TRON_PRIVATE_KEY and TRON_MNEMONIC removed from TRON MCP Server — enforces encrypted Agent Wallet for all write operations |
| Security | SDK examples in quickstart-for-human.md migrated from os.getenv("TRON_PRIVATE_KEY") to TronClientSigner.create() — removes the temptation to hardcode env var names in application code |
| Security | Shell history caution added to change-password non-interactive mode docs — appropriate for a sensitive operation |
| Security | SUN CLI CommandGuide includes a prominent :::caution Private Key Security admonition for the -k/--private-key flag |
| Security | BANKOFAI skill docs now explicitly state that self-transfers are automatically rejected and unlimited (MAX_UINT256) approvals are blocked |
| UX | New resolve-address and --show-address commands make address inspection clear without requiring a signing operation |
| UX | GasFree scheme clearly documents that no API keys are required on the client side (routed through BankOfAI proxy) |
| UX | Docker deployment documentation includes a health check endpoint reference (/health) — useful for monitoring |
| UX | dry-run mode prominently documented in SUN CLI — encourages safe testing before live transactions |
| Consistency | Node.js version bump (18→20) applied consistently across QuickStart, SDK-Guide, FAQ in both English and zh-Hans |
| Consistency | Tool count 95→97 updated consistently across all four files referencing it (Intro, ToolList, OfficialServerAccess, QuickStart) |
| Structure | SUN CLI docs are well-structured with Intro → QuickStart → CommandGuide → FAQ, matching the established pattern of other tool sections |
| Completeness | CommandGuide.md is thorough at 860 lines, covering every command category with option tables, defaults, and usage examples |
Checklist Results
| Category | Items Checked | Pass | Fail | N/A | Notes |
|---|---|---|---|---|---|
| Correctness | 4 | 3 | 1 | 4 | Broken internal link (MN-01); all other doc facts internally consistent |
| Security | 6 | 5 | 0 | 1 | Good security posture; private-key normalization is a suggestion only |
| Performance | 3 | 3 | 0 | 5 | N/A (docs-only PR) |
| Code Quality | 5 | 4 | 0 | 3 | Hardcoded GasFree amount (MN-04) |
| Testing | 2 | 2 | 0 | 6 | N/A (docs-only PR) |
| Documentation | 8 | 5 | 3 | 0 | Breaking change visibility gap (MJ-01); two zh-Hans translation gaps (MN-02, MN-03) |
| Compatibility | 3 | 2 | 0 | 1 | Breaking change is intentional and documented (though not prominently) |
| Observability | 2 | 2 | 0 | 6 | N/A (docs-only PR) |
Disclaimer
This is an automated code review. It supplements but does not replace human review. The reviewer analyzed only the diff between the specified branches. Runtime behavior, integration testing, and deployment impact are not covered. All findings relate to documentation content, accuracy, and user safety — no application code was changed in this PR.
Report generated by Code Review Skill v1.0.0
Date: 2026-04-08
Code Review ReportProject: BofAI/docs PR OverviewBranch Information
Commit History
Review SummaryVerdict
Findings at a Glance
SummaryThis PR introduces a comprehensive documentation update centered around three themes: (1) brand-new SUN CLI documentation (4 files covering Intro, QuickStart, CommandGuide, FAQ in both English and Chinese), (2) a breaking v1.1.7 change to TRON MCP Server that removes legacy wallet modes ( Overall quality is high: documentation is clear, well-structured, and security-conscious throughout. However, two major issues need resolution before merge: a potentially confusing cross-env-var hint in the human quickstart that may cause BSC signing failures, and a broken link to a Change Summary1. SUN CLI — New Documentation (4 files × 2 locales)
Purpose: Introduce SUN CLI ( 2. TRON MCP Server — v1.1.7 Breaking Changes + Docker
Purpose: Document the v1.1.7 breaking removal of 3. Agent-Wallet — Node.js 20, Windows, Privy, New Commands
Purpose: Reflect the upgraded Node.js requirement, new Privy managed-wallet support, new CLI commands, and Windows compatibility added in recent versions. 4. x402 — GasFree Payment Scheme + SDK Updates
Purpose: Document the new 5. BANKOFAISkill + Openclaw Extension
6. Build & Navigation
Detailed FindingsMajor[MJ-01] Cross-network env var reuse hint may break BSC signing
Description The PR adds a new hint in the BSC configuration tab:
This implies that Code > 💡 **Recommended:** Create a `.env` file in your project directory containing `AGENT_WALLET_PRIVATE_KEY=your_key`, then add `.env` to `.gitignore` to prevent accidental commits.
>
> 💡 If you already set `TRON_PRIVATE_KEY` in the TRON tab, the same key works for BSC — no need to set it again.Recommendation Verify whether the EVM signer actually falls back to [MJ-02] SUNCli QuickStart links to a potentially non-existent
|
| Property | Value |
|---|---|
| Severity | Major |
| Category | Correctness / Documentation |
| File | docs/McpServer-Skills/MCP/SUNCli/QuickStart.md : Line 147 (Next Steps) |
Description
The "Next Steps" section at the bottom of both the English and Chinese QuickStart files links to:
../SUNMCPServer/Intro.md
This assumes a directory docs/McpServer-Skills/MCP/SUNMCPServer/ exists in the repository. The diff does not add this directory, and it is not present among the changed files. If the directory does not exist, this will produce a broken link / 404 in the deployed documentation site.
Code
- **[SUN MCP Server](../SUNMCPServer/Intro.md)** — Prefer AI-driven DeFi? Use SUN MCP Server for natural language interactionRecommendation
- Verify whether
docs/McpServer-Skills/MCP/SUNMCPServer/already exists on themainbranch (it is not included in the diff). - If the directory does not exist yet, either remove this link for this PR and add it when SUN MCP Server docs are merged, or replace with a placeholder link to a relevant existing page (e.g., the TRON MCP Server intro:
../TRONMCPServer/Intro.md). - Apply the same fix to
i18n/zh-Hans/…/SUNCli/QuickStart.md.
Minor
[MN-01] Breaking-change migration notice is buried — missing from QuickStart
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md, docs/McpServer-Skills/MCP/TRONMCPServer/Intro.md |
Description
The removal of TRON_PRIVATE_KEY and TRON_MNEMONIC in v1.1.7 is a breaking change — existing users will find their write operations silently failing with "Wallet not configured" instead of working as before. Migration guidance exists only in FAQ.md (caution callout) and LocalPrivatizedDeployment.md (caution callout). The QuickStart.md and Intro.md pages — the first pages most returning users land on — contain no upgrade notice. This increases the risk that existing users are stranded without knowing why.
Recommendation
Add a brief :::caution Upgrading from < v1.1.7 callout near the top of both QuickStart.md and Intro.md that directs users to the FAQ migration section:
:::caution Upgrading from v1.1.6 or earlier?
v1.1.7 removes `TRON_PRIVATE_KEY` and `TRON_MNEMONIC` wallet modes. If write tools return "Wallet not configured", see the [migration guide in the FAQ](./FAQ.md#migrating-from-legacy-wallet-modes).
:::[MN-02] agent-wallet init section missing shell-history security caution
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Security / Documentation |
| File | docs/Agent-Wallet/Developer/CLI-Reference.md : agent-wallet init section |
Description
The new agent-wallet init section documents a --password, -p <pw> flag to pass the master password in non-interactive mode. The change-password section added in the same PR already correctly includes a :::caution note that -p and --new-password will be recorded in shell history. The init section omits this same warning, inconsistently exposing users to an undocumented security risk when using -p with agent-wallet init.
Code
**Non-interactive mode:**
```bash
agent-wallet init -p 'Abc12345!'| Flag | Description |
|---|---|
--password, -p <pw> |
Master password (skip prompt) |
--save-runtime-secrets |
Persist password to runtime_secrets.json |
**Recommendation**
Add the same caution box as in `change-password`:
```markdown
:::caution
`-p` will be recorded in shell history. For production use, prefer interactive mode or pipe passwords from a secrets manager.
:::
Apply the same fix to the corresponding Chinese locale file.
[MN-03] Docker deployment omits guidance for write operations via volume mount
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation / Completeness |
| File | docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md : Option D section |
Description
The Docker deployment section states the image "runs in read-only HTTP mode by default" and the tip says "For local write operations, use Option A or B." However, it does not explain that write operations could be enabled via Docker by mounting the agent-wallet directory and passing AGENT_WALLET_PASSWORD as an env var. Users who want reproducible containerised deployments with write access have no documented path.
Recommendation
Expand the Docker section with an example showing how to enable write operations:
docker run -d \
-p 3001:3001 \
-v $HOME/.agent-wallet:/root/.agent-wallet:ro \
-e AGENT_WALLET_PASSWORD="<your-password>" \
-e TRONGRID_API_KEY="<your-key>" \
mcp-server-tronOr explicitly state that write operations are intentionally unsupported in the Docker image to avoid confusion.
[MN-04] Inconsistent GitHub organization names across SUN CLI docs
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation / Consistency |
| File | docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md (caution callout), docs/McpServer-Skills/MCP/SUNCli/FAQ.md (footer link) |
Description
The SUN CLI documentation references two different GitHub organization names:
- CommandGuide.md (caution):
https://github.com/ABlockofAI/agent-wallet - FAQ.md (footer):
https://github.com/BofAI/sun-cli
Other docs in this repo consistently use https://github.com/BofAI/…. If ABlockofAI is incorrect or a stale organization name, users clicking the agent-wallet link from the SUN CLI command guide will reach a 404. The Chinese locale mirrors this inconsistency.
Code
# CommandGuide.md caution:
Prefer environment variables (`AGENT_WALLET_PRIVATE_KEY`,
`AGENT_WALLET_MNEMONIC`) or [agent-wallet](https://github.com/ABlockofAI/agent-wallet)
encrypted storage for all non-throwaway keys.
# FAQ.md footer:
file an issue on the [GitHub repository](https://github.com/BofAI/sun-cli).Recommendation
Standardize all agent-wallet GitHub links to use https://github.com/BofAI/agent-wallet (matching the SDK-Cookbook and other existing references), unless ABlockofAI is the authoritative org — in that case, audit and update all existing references.
[MN-05] exact_gasfree activation cost undocumented for mainnet
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation / Completeness |
| File | docs/x402/core-concepts/network-and-token-support.md : GasFree Account Management section |
Description
The GasFree activation section mentions the testnet cost:
"deposits a small amount of tokens (~3.05 USDT on nile)"
But does not document the equivalent mainnet activation cost. For a financial operation involving real assets on mainnet, users need to know the expected cost before proceeding — a vague "small amount" is insufficient for production deployments.
Recommendation
Document the mainnet activation amount explicitly, or add a note directing users to check current activation requirements before running on mainnet:
Use `--gasfree-info` to check the current required activation deposit for the target network before activating.[MN-06] network-and-token-support.md GasFree section missing in Chinese locale
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation / Consistency |
| File | i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/network-and-token-support.md |
Description
The diff shows the Chinese version of network-and-token-support.md was updated with only 37 line changes (+37/-7) compared to the English version's 46 line changes (+46/-10). Based on the diff content visible in the Chinese locale for this file, the GasFree CLI command examples block (--gasfree-info, --gasfree-activate) appears to be missing or incomplete. This means Chinese-locale readers get less information about how to manage GasFree accounts than English readers.
Recommendation
Ensure the Chinese locale network-and-token-support.md includes the full GasFree Account Management section with CLI examples, mirroring the English version.
[MN-07] quickstart-for-human.md Chinese locale quickstart-for-agent.md section still uses Option B only for TRON wallet setup
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation / Consistency |
| File | i18n/zh-Hans/…/x402/getting-started/quickstart-for-agent.md |
Description
The English quickstart-for-agent.md was restructured to present two options:
- Option A: Agent Wallet (Recommended)
- Option B: Static Private Key
The Chinese locale version received the same update (+17/-7 lines). However, inspecting the diff context, the Chinese version correctly mirrors the English dual-option structure. This item is verified as consistent. (Non-issue, noted for completeness.)
Suggestions
[S-01] Commit messages are not descriptive
File: Git log
Description: 9 of 16 commits have messages of "fix", "add suncli", "add cuncli" (possible typo for "sun-cli"), or "update all docs" — none describe what was fixed or updated. This makes git bisect and changelog generation difficult.
Suggestion: For future PRs, use conventional commit format: e.g., docs(sun-cli): add CommandGuide for @bankofai/sun-cli, docs(tron-mcp): document v1.1.7 breaking wallet mode changes. A d69c9eb add cuncli commit message also appears to be a typo for "sun-cli".
[S-02] SUN CLI CommandGuide missing liquidity v4:burn / exit documentation
File: docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md
Description: The CommandGuide documents v4:mint, v4:increase, v4:decrease, v4:collect, and v4:info for V4 liquidity. There is no v4:burn or full exit command documented. V3 similarly has no full-exit shortcut. Users needing to fully exit a position must combine decrease (to 0) and collect steps — this flow is not documented.
Suggestion: Add an example showing how to fully exit a V3 or V4 position (decrease to 0 + collect), or confirm that a dedicated exit command is not available.
[S-03] TronGrid API key env var inconsistency between components
File: Multiple files
Description: The documentation uses two different env var names for the TronGrid API key:
TRON_GRID_API_KEY— used in x402 quickstart files and.env.samplereferencesTRONGRID_API_KEY— used in the updated TRON MCP Server LocalPrivatizedDeployment and Docker example
This inconsistency may confuse users configuring multiple tools (x402 facilitator + TRON MCP Server) on the same machine.
Suggestion: Standardize on one env var name across all documentation and tools, or add a note in the getting-started pages explaining that the two components use different variable names intentionally.
Positive Observations
| Area | Observation |
|---|---|
| Security Awareness | The SUN CLI CommandGuide prominently warns about -k/--private-key flag risks in shell history, and recommends encrypted agent-wallet storage — a good security-first default |
| Dry-run Pattern | Both SUN CLI and BANKOFAISkill document --dry-run / dry-run mode as a safe preview mechanism before financial operations — excellent UX for AI agents |
| Testnet-First Guidance | Consistently throughout the PR, all write-operation sections recommend testing on Nile testnet first with explicit warnings that mainnet operations are irreversible |
| Fallback RPC Transparency | The new fallback RPC endpoint note in x402 docs (agents/sellers quickstart) honestly discloses the BANK OF AI proxy, its lack of SLA, and recommends users configure their own key for production — good transparency |
| Structured Migration Path | The TRON MCP Server breaking change in v1.1.7 is well-documented with :::caution callouts in both FAQ and LocalPrivatizedDeployment, including explicit steps to migrate |
| GasFree UX | Documenting that exact_gasfree requires no API keys on the client side (all routed via BANK OF AI proxy) is a clear and user-friendly design choice that is well-communicated |
| Bilingual Parity | All new English documentation (SUN CLI, agent-wallet updates, x402 changes) has corresponding Chinese translations, maintaining locale parity |
:::danger Lockout Warning |
BANKOFAISkill multisig section correctly adds a :::danger callout warning that Owner permission changes are irreversible — appropriate severity level |
Checklist Results
| Category | Items Checked | Pass | Fail | N/A | Notes |
|---|---|---|---|---|---|
| Correctness | 6 | 4 | 2 | 0 | MJ-01 (BSC env var hint), MJ-02 (broken link) |
| Security | 5 | 4 | 1 | 0 | MN-02 (missing shell history warning in init) |
| Performance | 4 | 4 | 0 | 0 | Timeout increase 60→120s is appropriate |
| Code Quality | 5 | 4 | 1 | 0 | MN-04 (inconsistent GitHub org names) |
| Testing | 3 | 2 | 0 | 1 | No test files in scope |
| Documentation | 8 | 5 | 3 | 0 | MN-01, MN-03, MN-05 |
| Compatibility | 4 | 3 | 1 | 0 | MN-01 (no prominent breaking-change notice in QuickStart) |
| Observability | 2 | 2 | 0 | 0 | Health endpoint documented for Docker |
Disclaimer
This is an automated code review. It supplements but does not replace human review. The reviewer analyzed only the diff between the specified branches (main...update-mcp-server). Runtime behavior, integration testing, and deployment impact are not covered. Findings are based on documentation quality, internal consistency, link validity, and security best practices.
Report generated by Code Review Skill v1.0.0
Date: 2026-04-08
Code Review ReportProject: BofAI/docs — Documentation Site PR OverviewBranch Information
Commit History
Review SummaryVerdict
Findings at a Glance
SummaryThis is a substantial documentation-only PR that introduces complete documentation for the new SUN CLI tool (4 files in English + 4 in Chinese), documents TRON MCP Server v1.1.7 breaking changes (removal of legacy Overall quality is good — security cautions are present throughout, new features are well-explained, and migration paths for breaking changes are clearly communicated. However, there are three major issues: the Chinese translation of CLI-Reference.md is materially incomplete compared to its English counterpart, a dead link exists in the SUN CLI Quick Start, and the Change Summary1. SUN CLI Documentation (New Feature)
Purpose: Document a new command-line DeFi tool ( 2. Agent Wallet — New Features & Version Bump
Purpose: Document Agent Wallet v2.3.x additions: Privy-managed cloud wallets, new CLI commands ( 3. TRON MCP Server v1.1.7 — Breaking Changes
Purpose: Reflect v1.1.7 changes: removal of 4. x402 Payment —
|
| File | Change Type | Description |
|---|---|---|
docs/x402/core-concepts/network-and-token-support.md |
Modified | exact_gasfree scheme documented, CLI management commands |
docs/x402/faq.md |
Modified | exact_gasfree added to payment scheme FAQ |
docs/x402/sdk-features.md |
Modified | exact_gasfree, SufficientBalancePolicy, USDD, EIP-155 network IDs |
docs/x402/getting-started/quickstart-for-human.md |
Modified | SDK examples use agent-wallet, BSC_PRIVATE_KEY → AGENT_WALLET_PRIVATE_KEY, ExactGasFreeClientMechanism added, timeout 60s → 120s |
docs/x402/getting-started/quickstart-for-agent.md |
Modified | Agent Wallet as recommended option A, fallback RPC documented |
docs/x402/getting-started/quickstart-for-sellers.md |
Modified | BSC_PRIVATE_KEY → AGENT_WALLET_PRIVATE_KEY, TronGrid key now optional with fallback |
docs/x402/index.md |
Modified | Bold "TRON" and "BSC" |
Purpose: Introduce gas-free TRON payments (users pay USDT/USDD without holding TRX). SDK examples migrate from raw private-key construction to agent-wallet's async create() factory.
5. BANK OF AI Skill & Openclaw Extension Updates
| File | Change Type | Description |
|---|---|---|
docs/McpServer-Skills/SKILLS/BANKOFAISkill.md |
Modified | Advanced TRC-20 features, safety guardrails, multisig details, lockout warning |
docs/Openclaw-extension/QuickStart.md |
Modified | x402 config in clean-install list, TRON MCP auto-install, TronScan API key section |
Purpose: Expand skill documentation with advanced features and safety guidance; update Openclaw installer flow documentation.
Detailed Findings
Major
[MJ-01] Chinese CLI-Reference.md is Missing ~35 Lines of Content vs English
| Property | Value |
|---|---|
| Severity | Major |
| Category | Documentation |
| File | i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md |
Description
The English docs/Agent-Wallet/Developer/CLI-Reference.md adds 89 lines in this PR, while the Chinese counterpart adds only 54 lines (per git diff --stat). Reviewing the Chinese diff confirms that two sections present in the English version are absent from the Chinese translation:
agent-wallet initcommand (~22 lines): Explains initializing the secrets directory without creating a wallet — critical for CI/CD users and Privy import scenarios.--show-addressflag foragent-wallet inspect(~8 lines): Without this, Chinese-speaking users have no documentation for the--show-addressoption.
The missing content leaves Chinese users unable to find documentation for these commands in their language.
Code
English diff adds (absent from Chinese translation):
### `agent-wallet init` (Initialize Secrets Directory)
Initialize the secrets directory and set the master password — without
creating a wallet yet...
| Flag | Description |
| `--password, -p <pw>` | Master password (skip prompt) |
| `--save-runtime-secrets` | Persist password to `runtime_secrets.json` |Show wallet metadata along with derived addresses:
| Flag | Description |
| `--show-address` | Derive and display EVM + TRON addresses ... |Recommendation
Add the missing agent-wallet init section and --show-address flag documentation to the Chinese CLI-Reference.md, mirroring the English content.
[MJ-02] Dead Link in SUN CLI QuickStart
| Property | Value |
|---|---|
| Severity | Major |
| Category | Documentation |
| File | docs/McpServer-Skills/MCP/SUNCli/QuickStart.md : Line 1596 (in the diff) |
Description
The SUN CLI Quick Start page links to a page that does not appear to exist in this PR or in the sidebar:
- **[SUN MCP Server](../SUNMCPServer/Intro.md)** — Prefer AI-driven DeFi?
Use SUN MCP Server for natural language interactionThe path ../SUNMCPServer/Intro.md refers to docs/McpServer-Skills/MCP/SUNMCPServer/Intro.md. No file matching this path is added in this PR and no entry for SUNMCPServer appears in the updated sidebars.js. If this page does not exist, clicking the link will result in a 404 error in the deployed docs site.
Code
- **[SUN MCP Server](../SUNMCPServer/Intro.md)** — Prefer AI-driven DeFi?Recommendation
Either:
- Remove the link and replace with a note that SUN MCP Server documentation is coming soon, or
- Change the link target to an existing page (e.g., the TRON MCP Server intro at
../TRONMCPServer/Intro.md), or - Add the
SUNMCPServer/Intro.mdfile in this PR.
Also check whether the corresponding Chinese translation (i18n/zh-Hans/.../SUNCli/QuickStart.md) has the same broken link and apply the same fix.
[MJ-03] exact_gasfree Activation Cost Hardcoded to Testnet Value
| Property | Value |
|---|---|
| Severity | Major |
| Category | Documentation / Correctness |
| File | docs/x402/core-concepts/network-and-token-support.md : exact_gasfree section |
Description
The documentation for GasFree account activation hardcodes a specific testnet amount that is presented ambiguously:
The activation process deposits a small amount of tokens (~3.05 USDT on nile)
to fund the GasFree wallet, then submits a GasFree transaction to trigger activation.The phrase "~3.05 USDT on nile" may mislead users who are activating on mainnet — they may assume the mainnet cost is the same or similar. Gas-free activation costs can differ between testnet and mainnet and can change over time. Additionally, the statement does not clarify who bears this deposit (the user's wallet), which could surprise users.
Code
The activation process deposits a small amount of tokens (~3.05 USDT on nile) to fund
the GasFree wallet, then submits a GasFree transaction to trigger activation.
Use `--gasfree-info` first to check whether your account is already active.Recommendation
Rewrite to avoid hardcoding a specific amount and to clarify that:
- Costs differ between testnet and mainnet.
- The deposit comes from the user's wallet.
- Users should run
--gasfree-infoto check the required deposit before activating.
Example:
The activation process deposits a small amount of tokens from your wallet to fund
the GasFree account, then submits a GasFree transaction to trigger activation.
The required deposit amount varies by network — run `--gasfree-info` first to
check whether your account is already active and to see the required deposit.Minor
[MN-01] change-password Shell History Warning Missing from Chinese Translation
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Security / Documentation |
| File | i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md |
Description
The English CLI-Reference adds a :::caution block warning that --password and --new-password flags are recorded in shell history and recommends interactive mode or piping from a secrets manager for production use. This caution block is present in the Chinese diff, so it appears to be translated. However, confirmed by line count differences discussed in MJ-01, ensure the caution block around change-password is fully present and properly translated in the Chinese file.
Recommendation
Verify the :::caution warning about shell history exposure for change-password -p and --new-password is present and visible in the Chinese translation.
[MN-02] Privy App Secret Storage Guidance Missing
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Security / Documentation |
| File | docs/Agent-Wallet/Developer/CLI-Reference.md, docs/Agent-Wallet/FAQ.md |
Description
The Privy wallet documentation instructs users they will need "a Privy App ID, App Secret, and Wallet ID" to configure the privy wallet type. However, the documentation gives no guidance on how to store the Privy App Secret securely. Unlike local private keys (which are encrypted by Agent Wallet), the Privy App Secret is an API credential and if leaked grants access to all Privy-managed wallets. The omission of storage guidance is a notable gap compared to the detailed security advice given for local_secure and raw_secret types.
Code
You'll need a Privy App ID, App Secret, and Wallet ID to configure it:Recommendation
Add guidance that the Privy App Secret should be stored in environment variables or a secrets manager and never hardcoded in config files, similar to the guidance given for private keys.
[MN-03] HTTP Timeout Doubling Not Explained in Docs
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | docs/x402/getting-started/quickstart-for-human.md |
Description
The SDK quickstart examples silently double the HTTP client timeout from 60s to 120s:
# Before
async with httpx.AsyncClient(timeout=60.0) as http_client:
# After
async with httpx.AsyncClient(timeout=120) as http_client:No explanation is provided for why the timeout was doubled. New users copying the example code will use a 120-second timeout without understanding the rationale. This change likely relates to the exact_gasfree mechanism adding network round-trips, but this is not documented.
Recommendation
Add a brief inline comment explaining the timeout, e.g.:
# 120s timeout to accommodate gas-free payment settlement round-trips
async with httpx.AsyncClient(timeout=120) as http_client:[MN-04] i18n Sidebar File Not Confirmed Updated
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | i18n/zh-Hans/docusaurus-plugin-content-docs/current/sidebars.js |
Description
The diff stats show i18n/zh-Hans/.../current/sidebars.js | 11 +, confirming the Chinese sidebar was updated. However, the McpServer-Skills/SKILLS/Intro.md and McpServer-Skills/SKILLS/QuickStart.md files appear in the diff stat with 2 changed lines each (Intro.md | 2 ±, QuickStart.md | 2 ±). These may be locale/sidebar reference updates. Confirm the SKILLS section in both sidebars.js files properly references the updated BANKOFAISkill.md with the new subsections that were added.
Recommendation
Verify the SKILLS sidebar links still resolve correctly after this PR's changes, especially if any anchors or headings were renamed.
[MN-05] Write Tools Visibility Change Not Prominently Flagged as Breaking in QuickStart
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation / UX |
| File | docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md |
Description
The behavior change in v1.1.7 — write tools are now always visible in the AI's tool list rather than hidden when no wallet is configured — represents a material UX change. A user who had previously relied on the absence of write tools as a safety indicator (no wallet = no write tools shown) will now see write tools even in read-only mode. While this change is documented in ToolList.md, FAQ.md, and LocalPrivatizedDeployment.md, the QuickStart.md page was not updated to mention this behavioral shift. New users following the Quick Start guide may be confused when write tools appear before a wallet is configured.
Recommendation
Add a brief note in QuickStart.md (or in the Quick Start's "What you can do" section) explaining that write tools appear in the tool list but require a configured Agent Wallet to execute.
Suggestions
[S-01] Commit Message Quality
File: All files
Description: Several commits are named fix with no further context (a080ac3 fix, 91f6996 fix, 64a0c36 fix, 53baadb fix, 0f53ddb fix). While this PR is documentation-only and the semantic risk of poor commit messages is lower, having five undifferentiated "fix" commits makes the git history difficult to bisect or audit.
Suggestion: Adopt more descriptive commit messages going forward (e.g., "fix: correct broken link in SUNCli QuickStart" or "fix: add missing zh-Hans CLI-Reference sections").
[S-02] GasFree CLI Usage Belongs in CLI-Reference, Not network-and-token-support
File: docs/x402/core-concepts/network-and-token-support.md
Description: The exact_gasfree section includes CLI invocation examples (npx tsx x402-payment/src/x402_invoke.ts --gasfree-info) that feel out of place in a conceptual "network and token support" document.
Suggestion: Move the --gasfree-info and --gasfree-activate CLI usage to a dedicated how-to guide or to the existing quickstart-for-human.md, and keep network-and-token-support.md at the conceptual level.
[S-03] BSC_PRIVATE_KEY → AGENT_WALLET_PRIVATE_KEY Rename Not Documented as Breaking in a Changelog
File: docs/x402/getting-started/quickstart-for-human.md, quickstart-for-sellers.md, quickstart-for-agent.md
Description: The environment variable BSC_PRIVATE_KEY has been renamed to AGENT_WALLET_PRIVATE_KEY across all quickstart guides. This is a breaking change for any user with existing .env files or CI pipelines. The rename is reflected in the docs but there is no changelog entry or migration callout box warning users that their existing env var name will stop working.
Suggestion: Add a :::caution Migration required admonition in the BSC tab of each quickstart that explicitly states BSC_PRIVATE_KEY is deprecated and replaced by AGENT_WALLET_PRIVATE_KEY.
[S-04] Fallback RPC Endpoint Dependency on BANK OF AI Infrastructure
File: docs/x402/getting-started/quickstart-for-agent.md, quickstart-for-sellers.md
Description: The docs now mention a fallback RPC endpoint operated by BANK OF AI when TRON_GRID_API_KEY is not set. The docs correctly note there is no SLA guarantee. However, the endpoint URL (https://api.trongrid.io proxied via BANK OF AI) is not explicitly stated in the docs, making it harder for users to configure firewall rules or understand what network traffic is generated.
Suggestion: Consider explicitly documenting the fallback endpoint domain so users know what external connections are made without a TronGrid key, or confirm it is intentionally kept opaque.
Positive Observations
| Area | Observation |
|---|---|
| Security warnings | Every place where private keys could be exposed via shell flags (-k, -m, --new-password) includes a visible caution block — excellent practice. |
| Breaking change communication | The removal of TRON_PRIVATE_KEY / TRON_MNEMONIC is communicated in three places (FAQ, LocalPrivatizedDeployment, ToolList) with explicit migration guidance and a version callout (:::caution Migrating from legacy wallet modes). |
| Testnet-first guidance | Both SUN CLI and TRON MCP Server docs consistently emphasize testing on Nile testnet before mainnet operations. |
| Dry-run mode | SUN CLI and x402 docs prominently feature --dry-run / --dry-run flags to encourage safe operation before committing on-chain. |
| Safety guardrails for TRC-20 | BANKOFAISkill.md documents platform-enforced safety limits (MAX_UINT256 blocked, self-transfer rejected) — good transparency. |
| Docker support | Docker deployment option is well-documented with practical docker run examples, health-check endpoint, and a clear note that Docker is read-only by design. |
| Bilingual coverage | All major new content (SUN CLI: 4 files) has corresponding Chinese translations, maintaining language parity. |
agent-wallet init UX tip |
The :::tip When to use init vs start callout clearly distinguishes the two commands — reduces common user confusion. |
| Multisig lockout warning | The :::danger Lockout warning for Owner permission changes is a genuinely important user protection that prevents irreversible lockouts. |
Checklist Results
| Category | Items Checked | Pass | Fail | N/A | Notes |
|---|---|---|---|---|---|
| Correctness | 5 | 3 | 2 | 0 | Hardcoded activation cost (MJ-03); dead link (MJ-02) |
| Security | 6 | 5 | 1 | 0 | Privy App Secret storage guidance missing (MN-02) |
| Performance | 3 | 2 | 0 | 1 | Timeout change not explained (MN-03); N/A for doc-only |
| Code Quality | 5 | 4 | 1 | 0 | Incomplete Chinese translation (MJ-01) |
| Testing | 4 | 0 | 0 | 4 | No code logic changed — all documentation |
| Documentation | 8 | 5 | 3 | 0 | MJ-01, MJ-02, MN-01 |
| Compatibility | 3 | 2 | 1 | 0 | BSC_PRIVATE_KEY rename not flagged as breaking (S-03) |
| Observability | 2 | 2 | 0 | 0 | Fallback RPC documented (with SLA caveat) |
Disclaimer
This is an automated code review. It supplements but does not replace human review. The reviewer analyzed only the diff between the specified branches. Runtime behavior, integration testing, and deployment impact are not covered. This PR is documentation-only — no executable code was changed.
Report generated by Code Review Skill v1.0.0
Date: 2026-04-08
Code Review ReportProject: BANK OF AI / docs PR OverviewBranch Information
Commit History
Review SummaryVerdict
Findings at a Glance
SummaryThis PR introduces a significant volume of new documentation across three major areas: (1) a brand-new SUN CLI section covering a command-line DeFi tool for the SunSwap ecosystem; (2) TRON MCP Server v1.1.7 updates that migrate from legacy wallet modes ( The documentation quality is generally strong—security warnings are present, command examples are clear, and the material is well-structured. However, the review found four Major issues that should be resolved before merging. The most impactful are: (1) a cross-product inconsistency where TRON MCP Server docs declare Change SummaryGroup 1 – SUN CLI Documentation (New)
Purpose: Introduce Group 2 – TRON MCP Server v1.1.7 Updates
Purpose: Align all TRON MCP Server docs with v1.1.7 which mandates Agent Wallet and makes write tools always visible. Group 3 – x402 GasFree Payment Scheme
Purpose: Document the new Group 4 – Agent Wallet Updates
Purpose: Document Agent Wallet v2.x additions: Privy wallet type, Group 5 – BANKOFAISkill, Openclaw, and Configuration
Group 6 – i18n (zh-Hans) Mirrored ChangesAll groups above are mirrored under Detailed FindingsMajor[MJ-01] x402
|
| Property | Value |
|---|---|
| Severity | Major |
| Category | Correctness / Documentation |
| File | docs/x402/getting-started/quickstart-for-human.md : Step 1 (credential setup) and the code examples section |
Description
The guide presents two credential options:
- Option A: Agent Wallet (
AGENT_WALLET_PASSWORD) — recommended - Option B: Static Private Key (
TRON_PRIVATE_KEY/AGENT_WALLET_PRIVATE_KEY) — for test environments
However, every code example in the page was migrated to use TronClientSigner.create() / EvmClientSigner.create(), which auto-resolves the wallet from Agent Wallet. The old os.getenv("TRON_PRIVATE_KEY") / os.getenv("BSC_PRIVATE_KEY") approach has been removed entirely. Users who choose Option B and copy-paste either Python or TypeScript sample code will get a runtime failure (wallet not found) because create() looks for Agent Wallet, not a raw env var.
Code (before → after in Python TRON example):
# REMOVED (Option B users set this up):
signer = TronClientSigner.from_private_key(os.getenv("TRON_PRIVATE_KEY"))
# NOW (only works with Option A / Agent Wallet):
signer = await TronClientSigner.create()Recommendation
Either:
- Remove Option B from Step 1 (simplify to Agent Wallet only), or
- Provide parallel code snippets showing how to initialize the signer with a raw private key (
from_private_key) alongside the Agent Wallet variant, so Option B is usable end-to-end.
[MJ-02] Cross-product env var conflict: TRON MCP Server deprecates TRON_PRIVATE_KEY, x402 guides still promote it
| Property | Value |
|---|---|
| Severity | Major |
| Category | Correctness / Documentation |
| File | docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md (lines 47–60), docs/x402/getting-started/quickstart-for-agent.md (Step 1), docs/x402/getting-started/quickstart-for-sellers.md |
Description
TRONMCPServer/FAQ.md explicitly states:
"If you were previously using
TRON_PRIVATE_KEYorTRON_MNEMONICenvironment variables, these are no longer supported as of v1.1.7."
Yet quickstart-for-agent.md (Option B) still instructs users to:
export TRON_PRIVATE_KEY="your_agent_wallet_private_key_here"And quickstart-for-sellers.md still shows TRON_PRIVATE_KEY=paste_your_facilitator_private_key_here in the TRON .env block. A user reading both sections in the same session will receive contradictory guidance. Even if the two products (mcp-server-tron and x402) are independent and TRON_PRIVATE_KEY remains valid for x402, this conflict should be made explicit.
Recommendation
Add a clarification note in the x402 quickstarts:
:::note
`TRON_PRIVATE_KEY` is used by the x402 SDK and SUN CLI only.
If you are also using TRON MCP Server (v1.1.7+), that product
has migrated to Agent Wallet exclusively — see
[TRON MCP Server Local Deployment](../../McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md).
:::[MJ-03] i18n versioned LocalPrivatizedDeployment.md diverges from the English source
| Property | Value |
|---|---|
| Severity | Major |
| Category | Correctness / Documentation |
| File | i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md |
Description
The diff stat shows the English source has +43 / -47 lines net change while the i18n copy has +47 / -61 lines net change — a discrepancy of ~18 lines. This means either the i18n file received additional changes not present in the English source, or the i18n base was already divergent before this PR and the merge compounded the drift. Readers of the Chinese documentation will encounter different content than English readers on the same deployment guide, which is the most critical setup document in this PR (it guides users through wallet configuration and Docker deployment).
Code (diff stat evidence):
90 43 47 docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md
108 47 61 i18n/zh-Hans/.../MCP/TRONMCPServer/LocalPrivatizedDeployment.md
Recommendation
Diff the two files directly to identify the delta. Either reconcile them to identical content, or document which sections are intentionally localized. Prefer keeping structural and code-example sections identical between locales to avoid divergent instructions.
[MJ-04] BSC credential env var renamed inconsistently across docs
| Property | Value |
|---|---|
| Severity | Major |
| Category | Correctness / Documentation |
| File | docs/x402/getting-started/quickstart-for-agent.md (BSC tab), docs/x402/getting-started/quickstart-for-human.md (BSC tab), docs/x402/getting-started/quickstart-for-sellers.md (BSC tab) |
Description
All three quickstart guides rename the BSC credential env var from BSC_PRIVATE_KEY → AGENT_WALLET_PRIVATE_KEY. However:
- TRON tab in the same guides still uses
TRON_PRIVATE_KEY(product-specific naming) - The BSC sellers
.envcomment says "Private key of the dedicated Facilitator wallet (NOT your receiving wallet!)" but the new var nameAGENT_WALLET_PRIVATE_KEYis a generic name shared with other components
This creates confusion: TRON_PRIVATE_KEY and AGENT_WALLET_PRIVATE_KEY appear to be parallel options on different tabs but have different naming conventions. A user setting up both networks in the same environment may set AGENT_WALLET_PRIVATE_KEY for BSC but wonder whether it conflicts with the TRON configuration.
Code:
# TRON tab (unchanged):
export TRON_PRIVATE_KEY="your_agent_wallet_private_key_here"
# BSC tab (renamed):
export AGENT_WALLET_PRIVATE_KEY="your_agent_wallet_private_key_here"Recommendation
Either normalize both to AGENT_WALLET_PRIVATE_KEY (and update TRON_PRIVATE_KEY references in x402 guides), or add an explicit note explaining that each env var is consumed by the respective network's signer and they do not conflict. A side-by-side table at the top of Step 1 listing which env vars correspond to which network/mode would resolve the ambiguity.
Minor
[MN-01] SUN CLI --network root-flag ordering — not documented in Intro or QuickStart
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | docs/McpServer-Skills/MCP/SUNCli/QuickStart.md, docs/McpServer-Skills/MCP/SUNCli/Intro.md |
Description
The FAQ correctly documents a non-obvious CLI behavior: --network (and all global flags) must be placed before the subcommand, otherwise nile is parsed as an unknown command. This is a common error. The Intro and QuickStart pages show examples without any mention of this ordering rule. New users who read only those two pages and try sun swap TRX USDT 1000000 --network nile will get a confusing error before ever reaching the FAQ.
Code (FAQ correctly shows, but Intro/QuickStart omit the warning):
# This works (shown in QuickStart without comment):
sun swap TRX USDT 1000000 --network nile --yes
# But this is what beginners naturally write:
sun swap TRX USDT 1000000 --network nile ← Fails if --network is not root positionRecommendation
Add a brief callout in the QuickStart's "Network & API Configuration" section:
:::note Root flag ordering
Global flags like `--network`, `--json`, and `-k` must be placed **before** the subcommand:
`sun --network nile swap TRX USDT 1000000` ✅
`sun swap TRX USDT 1000000 --network nile` ❌
:::[MN-02] exact_gasfree GasFree account activation commands assume local source checkout
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation / Correctness |
| File | docs/x402/core-concepts/network-and-token-support.md : GasFree Account Management section |
Description
The GasFree management commands use npx tsx x402-payment/src/x402_invoke.ts, which requires a local checkout of the x402-payment source tree:
npx tsx x402-payment/src/x402_invoke.ts --gasfree-info
npx tsx x402-payment/src/x402_invoke.ts --gasfree-activateThese commands will fail for anyone who installed @bankofai/x402 via npm (npm install @bankofai/x402) without cloning the repository. The document does not explain this prerequisite, nor does it link to a repository clone step or an npm-published CLI alternative.
Recommendation
Add a prerequisite note clarifying that these commands require the x402-payment skill to be installed (via Openclaw or manual clone), or document the equivalent workflow via the published npm package if one exists. Example:
:::info Prerequisite
The commands below require the `x402-payment` skill installed locally.
See [Openclaw Extension QuickStart](../../Openclaw-extension/QuickStart.md) for installation.
:::[MN-03] Docker deployment section missing instructions for enabling write operations
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation / Completeness |
| File | docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md : Option D (Docker) |
Description
The Docker section states: "The Docker image runs in read-only HTTP mode by default" and the tip says: "For local write operations, use Option A or B with a configured Agent Wallet." However, Docker is a legitimate deployment target for write operations in many production environments (e.g., passing environment variables via docker run -e or Docker Secrets). There is no guidance on how to configure Agent Wallet with Docker, and no explanation of whether the Docker image supports the AGENT_WALLET_PASSWORD / AGENT_WALLET_DIR environment variables at all.
Recommendation
Either:
- Explicitly state that the Docker image does not support write operations (by design) and explain why, or
- Add a short example showing how to pass Agent Wallet credentials to the container:
docker run -d \
-p 3001:3001 \
-e AGENT_WALLET_PASSWORD="<your-password>" \
-e AGENT_WALLET_DIR="/app/.agent-wallet" \
-v "$HOME/.agent-wallet:/app/.agent-wallet:ro" \
mcp-server-tron[MN-04] quickstart-for-human.md HTTP timeout silently doubled with no rationale
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | docs/x402/getting-started/quickstart-for-human.md : TRON Python example (line ~240), BSC Python example (line ~370) |
Description
Both Python client examples change timeout=60.0 to timeout=120 (seconds) with no explanation:
# Before:
async with httpx.AsyncClient(timeout=60.0) as http_client:
# After:
async with httpx.AsyncClient(timeout=120) as http_client:For a quickstart guide this is significant — doubling the timeout will cause user scripts to hang for two minutes on failures instead of one, and it implies some known latency increase (possibly from GasFree settlement or the new fallback RPC endpoint). Developers copy-pasting this as a baseline will bake in an unnecessarily high timeout without understanding why.
Recommendation
Add an inline comment explaining the reasoning:
# GasFree settlement may take up to 60s on TRON; timeout set to 120s for safety
async with httpx.AsyncClient(timeout=120) as http_client:[MN-05] agent-wallet change-password non-interactive flags expose passwords in shell history
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Security / Documentation |
| File | docs/Agent-Wallet/Developer/CLI-Reference.md : change-password section |
Description
The new non-interactive mode for change-password documents:
agent-wallet change-password -p 'OldPassword123!' --new-password 'NewPassword456!'The caution admonition correctly warns:
"Both
-pand--new-passwordwill be recorded in shell history."
However, the example itself demonstrates the exact insecure pattern it warns against, with no alternative shown. Showing passwords inline in code blocks—even as placeholders—normalizes this pattern and could easily be used verbatim in scripts.
Recommendation
Replace the example with a safer alternative:
# Read passwords from environment variables (not shell history):
agent-wallet change-password \
-p "$OLD_WALLET_PASS" \
--new-password "$NEW_WALLET_PASS"And reference a password manager or CI secrets vault for obtaining the values.
[MN-06] SUN CLI CommandGuide shows raw private key flag inline in code examples
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Security / Documentation |
| File | docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md : Global Flags Examples section |
Description
Despite a well-written :::caution Private Key Security block, the Global Flags example section immediately below it demonstrates:
sun -k your_private_key --network nile --yes swap TRX USDT 1000000This is a live-fire write operation example (mainnet-equivalent swap) with a private key flag. The caution block appears above this example but a reader skimming to examples will encounter the --yes bypass and private key pattern first. The juxtaposition—security warning followed immediately by a demonstrative example of the warned-against pattern—risks normalizing the behavior.
Recommendation
Relocate the -k flag example to an "Advanced / Legacy" subsection or replace it with the environment variable approach:
# Preferred: private key from environment variable
export AGENT_WALLET_PRIVATE_KEY=your_private_key
sun --network nile --yes swap TRX USDT 1000000Suggestions
[S-01] Add exact_gasfree to the sellers quickstart as a receivable payment scheme
File: docs/x402/getting-started/quickstart-for-sellers.md
Description: The sellers guide thoroughly covers server setup for exact_permit and exact schemes, but never mentions that sellers can also accept exact_gasfree payments from buyers who don't hold TRX. A seller following this guide has no way to know whether their server will automatically handle GasFree payments or needs additional configuration.
Suggestion: Add a short section (or a note under the TRON configuration) explaining whether exact_gasfree requires any server-side changes and whether the Facilitator wallet needs GasFree activation.
[S-02] SUNCli CommandGuide (860 lines) would benefit from a top-level anchor table
File: docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md
Description: At 860 lines, the command reference is comprehensive but has no quick-jump index. Users looking for a specific command group (e.g., farm, contract) must scroll through the entire document.
Suggestion: Add an anchor table at the top, similar to the one in the Intro capability table:
| Category | Commands |
|----------|----------|
| [Wallet & Portfolio](#wallet--portfolio) | `wallet address`, `wallet balances` |
| [Swap](#swap) | `swap`, `swap:quote`, `swap:quote-raw`, `swap:exact-input` |
| [Pool](#pool) | `pool list`, `pool search`, `pool top-apy`, `pool hooks`, ... |
...[S-03] GasFree SDK code examples in quickstart-for-human.md lack error handling for activation state
File: docs/x402/getting-started/quickstart-for-human.md : TRON Python/TypeScript examples
Description: The new GasFree examples register ExactGasFreeClientMechanism but include no guidance on the prerequisite that the GasFree account must be activated before first use (--gasfree-activate). A first-time user who copies the SDK example without activating their GasFree account will get an unclear error.
Suggestion: Add a step (or a callout) before the SDK code block:
:::caution GasFree account activation required
Before using `exact_gasfree`, activate your GasFree account once:
`npx tsx x402-payment/src/x402_invoke.ts --gasfree-activate --network nile`
See [GasFree Account Management](../../x402/core-concepts/network-and-token-support.md#gasfree-account-management).
:::[S-04] agent-wallet resolve-address command missing from the FAQ's quick-reference list
File: docs/Agent-Wallet/FAQ.md
Description: The FAQ has a section on "What values does the network parameter accept?" and other usage questions, but the new resolve-address command (which displays EVM + TRON addresses for a wallet) is not mentioned anywhere in the FAQ. This is particularly useful for users who need to find their TRON address after wallet creation.
Suggestion: Add an FAQ entry: "How do I find the on-chain address for my wallet?" that points to agent-wallet resolve-address and links to the CLI Reference.
Positive Observations
| Area | Observation |
|---|---|
| Security warnings — SUN CLI | The CommandGuide and Intro both include prominent :::caution and :::warning admonitions covering private key hygiene, testnet-first validation, minimum-funds principle, and dry-run usage. These are well-placed and comprehensive. |
| Breaking change communication | The v1.1.7 migration from TRON_PRIVATE_KEY / TRON_MNEMONIC to Agent Wallet is documented in three places (FAQ, LocalPrivatizedDeployment, ToolList) with clear :::caution Migrating from legacy wallet modes blocks and actionable next steps. |
| SUN CLI vs SUN MCP Server comparison table | The Intro provides a clear side-by-side feature comparison helping users choose the right tool. This prevents unnecessary support questions. |
| GasFree proxy transparency | The exact_gasfree docs clearly disclose that BANK OF AI operates the proxy endpoint, that it has no guaranteed SLA, and that users should bring their own TRON_GRID_API_KEY for production. This is an honest and user-respecting disclosure. |
| Fallback RPC endpoint documented in two places | Both quickstart-for-agent.md and quickstart-for-sellers.md include an identical :::note Fallback RPC Endpoint block, ensuring the caveat reaches both buyer and seller audiences. |
--dry-run pattern promoted |
The CommandGuide, Intro security notes, and BANKOFAISkill all consistently promote --dry-run before high-value writes. This is a solid safety-first pattern. |
| Docker health check endpoint documented | The new Docker deployment section mentions the /health endpoint, which is important for container orchestration and often forgotten in documentation. |
| Node.js version bump consistent | The upgrade from Node.js ≥18 to ≥20 is applied consistently across QuickStart, FAQ, and SDK Guide for Agent Wallet. No partial-update confusion. |
| MultiSig lockout warning | The new :::danger Lockout warning in BANKOFAISkill.md is appropriately prominent for an irreversible operation (Owner permission changes). |
Checklist Results
| Category | Items Checked | Pass | Fail | N/A | Notes |
|---|---|---|---|---|---|
| Correctness | 8 | 6 | 2 | 0 | [MJ-01] code/doc mismatch; [MJ-04] env var inconsistency |
| Security | 10 | 8 | 0 | 2 | Warnings present; [MN-05][MN-06] minor normalization issues |
| Performance | 7 | 6 | 0 | 1 | Timeout change noted [MN-04]; no perf-critical code changes |
| Code Quality | 8 | 7 | 0 | 1 | N/A — documentation repo |
| Testing | 7 | 0 | 0 | 7 | N/A — documentation only |
| Documentation | 10 | 7 | 3 | 0 | [MJ-02][MJ-03][MN-01][MN-02][MN-03] |
| Compatibility | 5 | 4 | 1 | 0 | [MJ-02] cross-product env var conflict |
| Observability | 4 | 3 | 0 | 1 | N/A — documentation only |
Disclaimer
This is an automated code review. It supplements but does not replace human review. The reviewer analyzed only the diff between origin/main and origin/update-mcp-server. Runtime behavior, integration testing, and deployment impact are not covered. All findings are based on documentation consistency, cross-reference accuracy, and security best practices.
Report generated by Code Review Skill v1.0.0
Date: 2026-04-08
Code Review ReportProject: BofAI / docs PR OverviewBranch Information
Commit History
Review SummaryVerdict
Findings at a Glance
SummaryThis is an entirely documentation-only PR that introduces a large set of new and updated Markdown reference pages across four product areas: SUN CLI (brand-new, 4 files), TRON MCP Server (v1.1.7 changelog), Agent Wallet (Privy wallet type, Node.js 20 requirement, new commands), and x402 payment protocol ( The overall quality is high — content is clear, well-structured, and the security-first messaging around private key management is exemplary. However, three Major issues need to be addressed before merge: a broken cross-document link in the SUN CLI Quick Start page, a silent breaking-change that removes Change Summary1 — New SUN CLI Documentation (4 new files)
Purpose: Introduces 2 — TRON MCP Server v1.1.7 Changes
Purpose: Documents the breaking removal of 3 — Agent Wallet Documentation Updates
Purpose: Documents Agent Wallet v2.x features: Privy cloud-custody wallet type, new CLI subcommands, Windows support, and the Node.js 20 requirement upgrade. 4 — x402 Payment Protocol Updates
Purpose: Documents the new gas-free TRON payment path and unifies wallet credential naming under 5 — SKILLS, OpenClaw & Navigation
Purpose: Registers SUN CLI in navigation, adds Detailed FindingsMajor[MJ-01] Broken Cross-Document Link in SUN CLI QuickStart
Description
Code - **[SUN MCP Server](../SUNMCPServer/Intro.md)** — Prefer AI-driven DeFi? Use SUN MCP Server for natural language interactionRecommendation - **[SUN MCP Server (TRON)](../TRONMCPServer/Intro.md)** — Prefer AI-driven DeFi? Use TRON MCP Server for natural language interactionVerify the target file exists at [MJ-02] Silent Breaking Change —
|
| Property | Value |
|---|---|
| Severity | Major |
| Category | Documentation / Compatibility |
| File | docs/x402/getting-started/quickstart-for-agent.md, quickstart-for-human.md, quickstart-for-sellers.md |
Description
All three x402 quickstart guides silently replace
TRON_PRIVATE_KEY/BSC_PRIVATE_KEYwith the unifiedAGENT_WALLET_PRIVATE_KEY. While the TRON MCP Server FAQ does contain a ":::cautionMigrating from legacy wallet modes" callout, the x402 quickstart pages that existing users are most likely to revisit contain no migration note. A user who already hasTRON_PRIVATE_KEYset in their shell profile will follow the updated guide, miss that their environment variable name is now wrong, and silently get aPrivate key not founderror at runtime.
Code
-export TRON_PRIVATE_KEY="your_agent_wallet_private_key_here"
+export AGENT_WALLET_PRIVATE_KEY="your_agent_wallet_private_key_here"Recommendation
Add a short callout directly above the export AGENT_WALLET_PRIVATE_KEY instruction in each of the three files:
:::caution Upgrading from a previous version?
If you previously set `TRON_PRIVATE_KEY` or `BSC_PRIVATE_KEY`, rename the variable to `AGENT_WALLET_PRIVATE_KEY`. The old names are no longer recognized.
```bash
export AGENT_WALLET_PRIVATE_KEY="$TRON_PRIVATE_KEY" # one-time rename
unset TRON_PRIVATE_KEY:::
---
#### [MJ-03] i18n Chinese CLI-Reference Missing `inspect --show-address` Section
| Property | Value |
|----------|-------|
| **Severity** | Major |
| **Category** | Documentation / Compatibility |
| **File** | `i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md` |
**Description**
> The English `CLI-Reference.md` adds two new subsections — `inspect --show-address` (flag table) and `resolve-address` command — but the Chinese translation only adds `resolve-address`. The `inspect --show-address` flag table and its description are absent from the Chinese file. Chinese-language readers following the localized documentation will have incomplete information about the `inspect` subcommand.
**Code** (present in English, absent in Chinese)
```markdown
Show wallet metadata along with derived addresses:
```bash
agent-wallet inspect my-bsc-wallet --show-address
| Flag | Description |
|---|---|
--show-address |
Derive and display EVM + TRON addresses (requires password for local_secure wallets) |
**Recommendation**
Add the translated equivalent of the `--show-address` block to the Chinese CLI-Reference immediately after the `agent-wallet inspect` command example, before the `Sign with a specific wallet` paragraph.
---
### Minor
#### [MN-01] `agent-wallet` Skill Listed as Snyk "High Risk" Without User Explanation
| Property | Value |
|----------|-------|
| **Severity** | Minor |
| **Category** | Documentation |
| **File** | `docs/McpServer-Skills/SKILLS/QuickStart.md` : Security Risk Assessments table |
**Description**
> The security risk assessment table for the 8-skill installer now shows `agent-wallet` with a `High Risk` Snyk rating — the only skill rated that highly. No prose accompanies this entry to explain what Snyk flagged (e.g., dependency vulnerabilities in a cryptographic library, permissive file I/O, etc.) or whether users should be concerned. Users who see this rating with no context may either dismiss the entire installer out of caution or, worse, proceed without understanding the actual risk.
**Recommendation**
Add a short callout or footnote after the table, e.g.:
> **Note on agent-wallet Snyk rating:** The High Risk flag reflects Snyk's detection of cryptographic key-management dependencies (e.g., `keystore`, `scrypt`). These are intentional — the skill is a key management tool. All key operations happen locally; no keys are transmitted to remote services.
---
#### [MN-02] `import os` Removed From Python x402 Code Examples Without Verification Comment
| Property | Value |
|----------|-------|
| **Severity** | Minor |
| **Category** | Correctness / Documentation |
| **File** | `docs/x402/getting-started/quickstart-for-human.md` : TRON Python tab, BSC Python tab |
**Description**
> `import os` was removed from both Python client examples after the `os.getenv("TRON_PRIVATE_KEY")` calls were replaced by the `TronClientSigner.create()` / `EvmClientSigner.create()` factory. The removal is functionally correct if `create()` handles env resolution internally, but the diff provides no comment confirming this. If a user copies the code and later tries to add their own `os.getenv()` call, they will see an `NameError: name 'os' is not defined` which can be confusing. The standard practice for tutorial code is to keep common-sense imports even if not immediately used, or leave a brief note.
**Recommendation**
Either retain `import os` at the top of the example for clarity (no runtime cost), or add a comment:
```python
# os import not needed — TronClientSigner.create() resolves the private key
# from AGENT_WALLET_PRIVATE_KEY automatically
[MN-03] HTTP Timeout Changed Inconsistently — 60.0 (float) → 120 (int) in Python, 60.0 → 120 in Two Separate Places
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Code Quality / Documentation |
| File | docs/x402/getting-started/quickstart-for-human.md : TRON Python tab and BSC Python tab |
Description
The
httpx.AsyncClient(timeout=...)value was changed from60.0to120in both the TRON and BSC Python code examples. The change itself is reasonable (longer timeout for GasFree transactions), but the rationale for the doubling is not explained. Additionally,60.0is a float that matcheshttpx'stimeoutparameter type signature, while120is an int. Both are accepted byhttpx, but documentation-level consistency matters: users who adapt the code for their own use might not realize why the value doubled.
Recommendation
Add a one-line comment next to the timeout value:
async with httpx.AsyncClient(timeout=120) as http_client: # increased for GasFree settlement latency[MN-04] SUN CLI CommandGuide --network Flag Placement Warning May Confuse Users of Subcommand Options
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation / Clarity |
| File | docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md : Lines 1–15 (Global Flags section) |
Description
The Global Flags table states: "Root flags must be placed before the subcommand." However, individual subcommand option tables (e.g.,
pool vol-history,farm tx) also include date and time range--start/--endoptions that look syntactically identical to root-level flags. A first-time user could easily attemptsun pool top-apy --network nile --page-size 5and receive an error because--networkwas placed after the subcommand. The FAQ file does address this, but only for the specificunknown command 'nile'error. The root of the misunderstanding could be prevented at the CommandGuide level.
Recommendation
Add a short note directly under the Global Flags table header:
Important: Place root-level flags (this table) before the subcommand name. Sub-command options (flags listed per-command below) go after the subcommand.
# Correct: sun --network nile --json pool top-apy --page-size 5 # Wrong: sun pool top-apy --network nile ← --network after subcommand
Suggestions
[S-01] Add exact_gasfree Activation Prerequisite to x402 QuickStart for Agents
File: docs/x402/getting-started/quickstart-for-agent.md
Description: The exact_gasfree mechanism requires a GasFree account to be activated before the first use (--gasfree-activate). The code examples now register ExactGasFreeClientMechanism by default, but the quickstart page does not mention that GasFree accounts need prior activation. A new user whose account is not activated will get a silent failure or confusing error.
Suggestion: Add a short note or optional activation step in the Prerequisites section pointing to network-and-token-support.md#gasfree-account-management.
[S-02] Provide a Dedicated v1.1.7 Migration Guide Page
File: docs/McpServer-Skills/MCP/TRONMCPServer/ (new file suggestion)
Description: The v1.1.7 changes (legacy wallet removal, write tools always visible, Docker support) are material breaking changes scattered across FAQ and LocalPrivatizedDeployment. Users upgrading from v1.1.6 must hunt across multiple pages to understand what changed.
Suggestion: Add a Changelog.md or MigrationGuide.md to the TRONMCPServer directory summarising all v1.1.7 breaking changes and migration steps in one place.
[S-03] Link to Privy Official Docs From Privy Wallet Type Sections
File: docs/Agent-Wallet/Developer/CLI-Reference.md, docs/Agent-Wallet/FAQ.md
Description: The new Privy wallet type docs mention "Privy App ID, App Secret, and Wallet ID" but do not link to Privy's documentation for obtaining these credentials. Users unfamiliar with Privy will have to search separately.
Suggestion: Add [Privy documentation](https://docs.privy.io/reference/server-wallets) wherever Privy App ID is first mentioned.
[S-04] Consider Adding --gasfree Flag to the SUN CLI Command Guide
File: docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md
Description: The swap command table does not mention any GasFree option, even though the x402 documents describe GasFree as a TRON-specific payment path. If SUN CLI v1.x or future versions expose a --gasfree flag for swaps, the command guide should be kept in sync. At minimum, a forward-looking note could prevent confusion.
Suggestion: Add a note to the swap command section: "GasFree swap execution is available via the x402 payment layer — see x402 GasFree docs."
Positive Observations
| Area | Observation |
|---|---|
| Security messaging | The PR consistently and prominently warns against plaintext private keys, shell history exposure, and the use of raw_secret wallets. The change-password non-interactive mode includes a :::caution about shell history — this is exactly the right level of prominence. |
| Breaking-change disclosure | The :::caution Migrating from legacy wallet modes callout in LocalPrivatizedDeployment.md and the v1.1.7 FAQ entry are clear and actionable. Existing users are told exactly which env vars to stop using. |
| Dry-run / testnet first patterns | Both SUN CLI and TRON MCP Server docs consistently promote --dry-run and testnet-first approaches before mainnet writes. The testnet-first tip appears in 4+ places, which is appropriate for a financial operations tool. |
| Consistent structure across new SUN CLI files | All four new SUN CLI pages (Intro, QuickStart, CommandGuide, FAQ) follow a consistent formatting style — tables with (read) / (write) labels, caution blocks for key-passing flags, --- section dividers. |
Unified AGENT_WALLET_PRIVATE_KEY |
Replacing three separate env var names (TRON_PRIVATE_KEY, BSC_PRIVATE_KEY, legacy wallet modes) with a single AGENT_WALLET_PRIVATE_KEY is a clear developer-experience improvement that reduces cognitive overhead for multi-chain users. |
| Fallback RPC transparency | The three :::note Fallback RPC Endpoint callouts in the x402 quickstart files honestly disclose that the fallback endpoint has no SLA and routes through BANK OF AI infrastructure. This is appropriately transparent. |
| Docker deployment documentation | The new Docker Option D is well-scoped — it clearly states the image runs read-only by default and links back to Options A/B for write operations. |
Checklist Results
| Category | Items Checked | Pass | Fail | N/A | Notes |
|---|---|---|---|---|---|
| Correctness | 8 | 7 | 1 | 0 | MJ-01: broken link; MJ-03: translation gap |
| Security | 10 | 10 | 0 | 0 | Excellent security-first documentation throughout |
| Performance | 7 | 5 | 0 | 2 | Timeout changes noted (MN-03); N/A for docs-only context |
| Code Quality | 8 | 5 | 3 | 0 | MN-02 (import), MN-03 (timeout), MN-04 (flag placement) |
| Testing | 5 | 0 | 0 | 5 | N/A — documentation-only PR |
| Documentation | 6 | 4 | 2 | 0 | MJ-02 migration notice; MJ-03 translation gap |
| Compatibility | 5 | 3 | 1 | 1 | MJ-02 breaking change without inline notice |
| Observability | 3 | 0 | 0 | 3 | N/A — documentation-only PR |
Disclaimer
This is an automated code review. It supplements but does not replace human review. The reviewer analyzed only the diff between the specified branches. Runtime behavior, integration testing, and deployment impact are not covered. All file paths and line numbers refer to the update-mcp-server branch state at the time of this review.
Report generated by Code Review Skill v1.0.0
Date: 2026-04-09
Code Review ReportProject: @x402-tron/docs PR OverviewBranch Information
Commit History
Review SummaryVerdict
Findings at a Glance
SummaryThis PR is a documentation update covering four primary areas: (1) introduction of a brand-new SUN CLI section with four pages (Intro, QuickStart, CommandGuide, FAQ) in both English and Chinese; (2) updates to Agent Wallet docs adding Privy wallet type, The documentation is well-written, security-conscious, and consistently bilingual (EN + ZH). The SUN CLI reference is thorough and well-structured. However, two major issues require attention before merging: the v1.1.7 breaking wallet change lacks a prominent migration guide (users upgrading without reading the FAQ will silently lose write-tool access), and the security scan in Change SummaryGroup 1 — SUN CLI Documentation (New)
Purpose: Document the new Group 2 — Agent Wallet Documentation Updates
Purpose: Document Privy wallet type, new CLI commands ( Group 3 — TRON MCP Server v1.1.7 Updates
Purpose: Reflect the v1.1.7 breaking change removing legacy wallet env vars, and the addition of Docker deployment support (v1.1.6). Group 4 — x402 SDK Documentation Updates
Purpose: Document the Group 5 — Skills & Other
Detailed FindingsMajor[MJ-01] Breaking Wallet Variable Change Lacks a Dedicated Migration Guide
Description The v1.1.7 release removes The migration note currently lives only in two places:
Neither location is a first-stop for an upgrading user. There is no dedicated migration guide, no changelog entry in the docs, and no banner/notice on the Code (from :::caution Migrating from legacy wallet modes
If you were previously using `TRON_PRIVATE_KEY` or `TRON_MNEMONIC` environment variables,
these are no longer supported as of v1.1.7. Please migrate to Agent Wallet.
:::Recommendation
[MJ-02]
|
| Property | Value |
|---|---|
| Severity | Major |
| Category | Security / Documentation |
| File | docs/McpServer-Skills/SKILLS/QuickStart.md : Lines 84–105 |
Description
The security scan table shown during skill installation — and reproduced verbatim in the docs — now lists agent-wallet with a High Risk Snyk score, a Med Risk Gen score, and 1 Socket alert. The documentation proceeds directly to a "Proceed with installation? Yes" prompt without any explanation of what the High Risk rating means, what specific vulnerability was flagged, or whether users should take mitigating action.
This creates two problems:
- Security-conscious users may incorrectly assume it's safe to dismiss (because the docs show "Yes" as the answer).
- Non-security-conscious users are unaware of the real risk level of an npm package being installed globally.
For comparison, x402-payment now shows Safe / 1 alert / Med Risk (improved from the previous Med / 1 alert / Med), which makes the agent-wallet High Risk flag more prominent and potentially alarming.
Code (from QuickStart.md):
│ agent-wallet Med Risk 1 alert High Risk │
│ ... │
◇ Proceed with installation?
│ Yes
Recommendation
- Add a note below the security scan table that explains the specific Snyk finding (e.g., "The High Risk rating relates to
xyzdependency — see [link to Snyk advisory]. This is a known false positive / being tracked in issue #N."). - If the High Risk is a genuine concern, resolve it before documenting the install flow.
- At minimum, link to the Snyk report or GitHub issue so users can make an informed decision.
Minor
[MN-01] Node.js Version Bump (18 → 20) Not Flagged as a Breaking Change for Existing Users
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation / Compatibility |
| File | docs/Agent-Wallet/QuickStart.md : Lines 15–44, docs/Agent-Wallet/Developer/SDK-Guide.md : Lines 22–55, docs/Agent-Wallet/FAQ.md : Line 143 |
Description
Node.js 18 is still in Active LTS (End-of-Life: April 2025). The PR uniformly bumps the minimum requirement from >= 18 to >= 20 across all Agent Wallet and SUN CLI docs. This is a breaking change for users currently running Node 18, but no warning note is added. Users who installed Node 18 per the old docs may encounter cryptic runtime errors if they upgrade the package before upgrading Node.
Code (SDK-Guide.md):
-Requires Node.js ≥ 18. Check your current version:
+Requires Node.js ≥ 20. Check your current version:Recommendation
Add a short note near the requirement statement:
> **Note:** As of v2.x, Node.js ≥ 20 is required. If you're on Node 18, upgrade to LTS 20 before proceeding.[MN-02] BANK OF AI Proxy as Implicit Opt-Out Default for TronGrid RPC
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Security / Transparency |
| File | docs/x402/getting-started/quickstart-for-agent.md : Lines 65–79, docs/x402/getting-started/quickstart-for-human.md : Lines 165–179, docs/x402/getting-started/quickstart-for-sellers.md : Lines 545–555 |
Description
The PR correctly discloses (via a :::note admonition) that when TRON_GRID_API_KEY is not set, mainnet RPC calls are automatically routed through a BANK OF AI-operated public proxy:
When TRON_GRID_API_KEY is not set, mainnet RPC calls are automatically
routed through a BANK OF AI-operated public endpoint
(https://api.trongrid.io proxied via BANK OF AI).
While disclosing this is good, the design is an implicit opt-out: all users without a TronGrid key silently depend on BANK OF AI infrastructure, sending their mainnet transaction data through a third-party relay with no SLA. This is only disclosed in a collapsible note, and users who skip it may not realise they have a hidden dependency on a specific vendor.
Recommendation
- Move the proxy disclosure from a
:::noteto a:::cautionto ensure higher visibility. - In the QuickStart instructions, explicitly offer the choice:
Option A: Set TRON_GRID_API_KEY (recommended for production) Option B: Use the BANK OF AI public fallback (testing only, no SLA) - Consider providing the
TRON_RPC_URLenv var as an explicit opt-in for users who want to use their own or another public endpoint.
[MN-03] change-password Non-Interactive Example Shows Plaintext Passwords in Command String
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Security / Documentation |
| File | docs/Agent-Wallet/Developer/CLI-Reference.md : Lines 300–315 |
Description
The new non-interactive change-password section shows the following example prominently:
agent-wallet change-password -p 'OldPassword123!' --new-password 'NewPassword456!'A :::caution block below correctly warns that both flags are recorded in shell history. However, the structure of the page (example first, warning after) means users may copy-paste the command before reading the caution. This is especially risky because password changes are a sensitive, infrequent operation — users may be in a hurry and not read carefully.
Recommendation
Move the :::caution block before the non-interactive example, so the warning is read before the command is shown:
:::caution Shell History Warning
Both `-p` and `--new-password` will be recorded in shell history. For production use,
prefer interactive mode or pipe passwords from a secrets manager.
:::
**Non-interactive mode** (for automation scripts where interactive input is unavailable):
```bash
agent-wallet change-password -p 'OldPassword123!' --new-password 'NewPassword456!'[MN-04] SUN CLI CommandGuide.md Lists TRX with a "Virtual Contract Address" without Clarification
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation / Correctness |
| File | docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md : Lines 840–855 |
Description
The "Built-In Token Symbols" table lists TRX with address T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb. This is the native TRX virtual address used internally by TRON DeFi protocols for routing — it is not a real TRC-20 contract, and a standard contract read call against this address will fail. A user who reads the "you can use either the symbol or the full address" guidance might try to use this address in another context and be confused.
Code:
| `TRX` | `T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb` | 6 |Recommendation
Add a footnote or inline note clarifying that the TRX address is a virtual convention for router/pool APIs:
| `TRX` | `T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb` ¹ | 6 |
¹ This is the virtual TRX address used by SunSwap's router contracts — it is not a deployed TRC-20 contract. You cannot call `contract read` on it directly.Suggestions
[S-01] Consider a Dedicated "Migration Guide: v1.1.6 → v1.1.7" Page
File: docs/McpServer-Skills/MCP/TRONMCPServer/
Description: The v1.1.7 wallet-mode removal is the most significant breaking change in this PR. A dedicated migration page (even a short one) would be far more discoverable than FAQ bullet points.
Suggestion: Create docs/McpServer-Skills/MCP/TRONMCPServer/Migration-v1.1.7.md with a step-by-step guide: detect old env vars → install agent-wallet → import key → set AGENT_WALLET_PASSWORD → verify. Link it prominently from the sidebar and from LocalPrivatizedDeployment.md.
[S-02] Document What Happens If Both Old and New Env Vars Are Set Simultaneously
File: docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md
Description: A user upgrading in-place may have both TRON_PRIVATE_KEY and AGENT_WALLET_PASSWORD in their shell profile. The docs don't explain which takes precedence or whether the old var is ignored or causes an error.
Suggestion: Add an FAQ entry: "I have both TRON_PRIVATE_KEY and AGENT_WALLET_PASSWORD set — what happens?" that clearly states the old var is ignored in v1.1.7+.
[S-03] SUN CLI QuickStart Should Note That --yes Bypasses All Confirmation — Including Destructive Ones
File: docs/McpServer-Skills/MCP/SUNCli/QuickStart.md : Line 118
Description: The QuickStart introduces --yes as a simple convenience flag (sun swap TRX USDT 1000000 --network nile --yes). The CommandGuide lists --yes in Global Flags correctly, but nowhere is it called out that --yes also bypasses confirmation for irreversible write operations (liquidity removal, large swaps).
Suggestion: Add a callout in the QuickStart: "The --yes flag skips all confirmation prompts — including for irreversible on-chain actions. Use it only in trusted automated pipelines, not interactively."
[S-04] agent-wallet Skill Entry in BANKOFAISkill.md Mentions Agent-Restricted Commands but inspect Is Not Included
File: docs/McpServer-Skills/SKILLS/BANKOFAISkill.md : Lines 93–96
Description: The new agent-wallet skill entry correctly marks remove, reset, and change-password as agent-restricted (must be run manually). However, the new inspect --show-address command (which can derive and display wallet addresses) is not mentioned. Depending on the threat model, address revelation may be a sensitive operation worth noting.
Suggestion: Confirm whether inspect --show-address is also agent-restricted, and if so, add it to the caution list. If not, note that it is safe for agent invocation.
Positive Observations
| Area | Observation |
|---|---|
| Security warnings | Security cautions are comprehensive, prominent, and consistently placed throughout all new SUN CLI docs (CommandGuide :::caution Private Key Security, Intro :::warning, QuickStart :::caution) |
| Testnet-first philosophy | All write operation examples use --network nile first and include explicit reminders that mainnet operations are irreversible |
| Unified private key env var | Consolidating to AGENT_WALLET_PRIVATE_KEY across all x402 quickstart guides simplifies onboarding and reduces multi-chain confusion |
| GasFree proxy transparency | The docs proactively disclose the BANK OF AI proxy dependency for GasFree operations in multiple locations, even though this is a competitive disadvantage |
| SUN CLI comprehensiveness | The 860-line CommandGuide covers all command categories with consistent table formatting, read/write labels, required vs. optional flags, and examples |
| Bilingual parity | All 56 changed files have corresponding Chinese translations that are semantically equivalent to the English versions |
| Privy wallet type | The new Privy wallet type is well-documented with appropriate warnings and comparison table, filling an important gap for server-side AI agents |
| Docker deployment | The new Docker option for TRON MCP Server is well-documented with a working docker run example and health check mention |
| Error hierarchy | Adding Privy-specific error classes (PrivyConfigError, PrivyRateLimitError, PrivyAuthError) to the SDK error tree improves debuggability |
--dry-run promotion |
The SUN CLI docs consistently promote --dry-run before high-value write operations — a best practice not always seen in DeFi tooling docs |
Checklist Results
| Category | Items Checked | Pass | Fail | N/A | Notes |
|---|---|---|---|---|---|
| Correctness | 8 | 7 | 1 | 0 | MN-04: TRX virtual address not clarified |
| Security | 10 | 7 | 3 | 0 | MJ-02 (High Risk undisclosed), MN-02 (implicit proxy), MN-03 (password example order) |
| Performance | 7 | 7 | 0 | 0 | Documentation-only PR; no performance impact |
| Code Quality | 8 | 8 | 0 | 0 | Consistent formatting, good use of admonitions, proper table alignment |
| Testing | 5 | 5 | 0 | 0 | No test code changed; example commands are clear and verifiable |
| Documentation | 6 | 4 | 2 | 0 | MJ-01 (breaking change guide missing), S-01 (migration page) |
| Compatibility | 5 | 3 | 2 | 0 | MJ-01 (wallet migration), MN-01 (Node.js version) |
| Observability | 4 | 4 | 0 | 0 | Logging, exit codes, error messages well covered in CLI docs |
Disclaimer
This is an automated code review. It supplements but does not replace human review. The reviewer analyzed only the diff between the specified branches. Runtime behavior, integration testing, and deployment impact are not covered.
Report generated by Code Review Skill v1.0.0
Date: 2026-04-09
Code Review ReportProject: BofAI/docs PR OverviewBranch Information
Commit History
Review SummaryVerdict
Findings at a Glance
SummaryThis PR is a large documentation release (23 commits, 60 files) that ships four major content areas: (1) all-new SUN CLI documentation ( The documentation is generally of high quality — clear writing, strong security callouts, well-structured tables, and consistent use of Docusaurus admonition blocks. However, there are three major issues requiring attention before merge: an incomplete migration guide for existing users losing access to the now-removed Change Summary1. New SUN CLI Documentation (4 new files)
Purpose: Introduce 2. TRON MCP Server Docs — v1.1.7 Breaking Changes
Purpose: Document the v1.1.7 release which removes legacy plaintext wallet modes and makes write tools always registered (with runtime wallet check), plus a new Docker deployment option. 3. SUN MCP Server Docs — Wallet Mode Consolidation
Purpose: Mirror the v1.1.7 wallet-mode consolidation for SUN MCP Server. 4. Agent Wallet Documentation Updates
Purpose: Document new CLI commands, the new Privy wallet type, Windows support added in v2.3.x, and the Node.js version bump. 5. x402 SDK Documentation Updates
Purpose: Align x402 quickstarts with Agent Wallet integration and document GasFree TRON payment mechanism support. 6. Skills & Openclaw Docs Updates
Purpose: Surface 7. Sidebar & Package
Detailed FindingsMajor[MJ-01] Incomplete Migration Path for Removed Legacy Wallet Modes
Description The PR removes all documentation for Code :::caution Migrating from legacy wallet modes
If you were previously using `TRON_PRIVATE_KEY` or `TRON_MNEMONIC` environment variables,
these are no longer supported as of v1.1.7. Please migrate to Agent Wallet.
You can import your existing private key into Agent Wallet —
see the [Agent-Wallet documentation](../../../Agent-Wallet/Intro) for details.
:::Recommendation Add the concrete migration steps inline (or in a dedicated "Migrating from v1.1.6" subsection) so users do not need to hunt through a secondary doc set under time pressure: :::caution Migrating from legacy wallet modes
`TRON_PRIVATE_KEY` and `TRON_MNEMONIC` are removed as of v1.1.7.
To migrate your existing private key:
```bash
# 1. Install agent-wallet (if not already installed)
npm install -g @bankofai/agent-wallet
# 2. Initialize and create an encrypted wallet from your private key
agent-wallet start
# When prompted, choose "local_secure" and paste your private key.
# 3. Replace your environment variable
unset TRON_PRIVATE_KEY
export AGENT_WALLET_PASSWORD='your-chosen-master-password'See Agent Wallet Quick Start for full details. Recommendation Update Without wallet configuration, write operations will return a "wallet not configured" error.
All tools (read and write) remain visible in the tool list — wallet availability is checked
at execution time. To enable write operations, configure Agent Wallet (see Step 1 below).[MJ-03]
|
| Property | Value |
|---|---|
| Severity | Major |
| Category | Security / Documentation |
| File | docs/Agent-Wallet/Developer/CLI-Reference.md : Lines 301–322 |
Description
The newly documented non-interactive change-password syntax passes both the old and new master passwords as CLI flags. The caution block only mentions shell history, but omits the more immediate risk: /proc/<pid>/cmdline exposure on Linux systems means any process with read access to /proc can read the passwords in real time while the command runs — this is a more serious risk than shell history alone, especially in multi-tenant or containerised environments.
Additionally, the doc says "For production use, prefer interactive mode or pipe passwords from a secrets manager" but does not provide any example of the piping technique, leaving the reader without a safe alternative for automation use-cases.
Code
:::caution
Both `-p` and `--new-password` will be recorded in shell history. For production use,
prefer interactive mode or pipe passwords from a secrets manager.
:::Recommendation
Expand the caution to name both threat vectors and provide a safe automation alternative:
:::caution Password exposure risks
Passing `-p` and `--new-password` as CLI flags exposes passwords in two ways:
1. **Shell history** — recorded in `~/.bash_history` / `~/.zsh_history`
2. **Process listings** — visible via `ps aux` or `/proc/<pid>/cmdline` while the command runs
For automation, prefer reading passwords from a secrets manager and passing them
via standard input or a named pipe rather than as direct flags:
```bash
# Example: read passwords from stdin using a subshell (passwords not in history)
agent-wallet change-password <<EOF
OldPassword123!
NewPassword456!
EOFOnly use the flag form in fully private, single-user environments.
:::
---
### Minor
#### [MN-01] Inconsistent Environment Variable for Raw Private Key Across SUN CLI and x402 Docs
| Property | Value |
|----------|-------|
| **Severity** | Minor |
| **Category** | Documentation / Consistency |
| **File** | `docs/McpServer-Skills/MCP/SUNCli/FAQ.md` : Lines 33–36 vs. `docs/x402/getting-started/quickstart-for-agent.md` |
**Description**
`SUNCli/FAQ.md` documents three separate env vars for SUN CLI wallet resolution:
- `AGENT_WALLET_PRIVATE_KEY` (direct private key)
- `AGENT_WALLET_MNEMONIC` (mnemonic phrase)
- `AGENT_WALLET_PASSWORD` (encrypted wallet)
However, the x402 quickstart and sellers guide only ever reference `AGENT_WALLET_PRIVATE_KEY` and `AGENT_WALLET_PASSWORD`. The existence of `AGENT_WALLET_MNEMONIC` is not documented anywhere in the Agent Wallet CLI Reference or FAQ under the non-interactive section. If this env var is real, it needs to appear in the authoritative Agent Wallet docs; if it is SUN-CLI-specific, the FAQ should clarify that.
**Code**
```markdown
<!-- SUNCli/FAQ.md -->
- `AGENT_WALLET_PRIVATE_KEY` — direct private key
- `AGENT_WALLET_MNEMONIC` — mnemonic phrase
- `AGENT_WALLET_PASSWORD` — encrypted wallet via agent-wallet
Recommendation
Either add AGENT_WALLET_MNEMONIC to docs/Agent-Wallet/Developer/CLI-Reference.md under the non-interactive execution section, or remove it from the SUN CLI FAQ if it is not a real supported env var. Whichever env vars are supported should be listed consistently across all docs.
[MN-02] agent-wallet resolve-address Example Uses CAIP-2 Identifier While All Other Docs Use Plain Names
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation / Consistency |
| File | docs/Agent-Wallet/Developer/CLI-Reference.md (new resolve-address section) vs. sign examples |
Description
The sign command examples throughout CLI-Reference.md use network identifiers like -n tron and -n eip155:56 interchangeably. However, there is no explanation anywhere in the added sections of what eip155:56 means compared to tron, and whether resolve-address also accepts eip155:* identifiers. The inconsistency between human-readable (tron, bsc) and CAIP-2 (eip155:56) identifiers could confuse new users configuring multi-chain wallets.
Code
# sign example uses CAIP-2
agent-wallet sign msg "Hello" -n eip155:56 -w my-bsc-wallet -p 'Abc12345!'
# resolve-address example uses no -n flag at all — shows both networks in output
agent-wallet resolve-address my-walletRecommendation
Add a small note in the "Wallet Management" section explaining the network identifier format:
> **Network identifiers:** SUN CLI accepts both short-form names (`tron`, `bsc`, `mainnet`)
> and CAIP-2 format (`eip155:56` for BSC, `eip155:1` for Ethereum). Both forms are
> equivalent — use whichever is more readable in your context.[MN-03] Docker Deployment Section Does Not Explain How to Enable Write Operations
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation / Completeness |
| File | docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md : Lines 130–170 |
Description
The new Docker Option D section says "The Docker image runs in read-only HTTP mode by default" and the tip says to use Option A or B for write operations. However, it does not explain whether Docker can be configured for write operations at all (e.g., by mounting an Agent Wallet directory and setting AGENT_WALLET_PASSWORD and AGENT_WALLET_DIR as env vars), leaving advanced users without guidance.
Code
:::tip
The Docker image is designed for read-only cloud deployments. For local write operations
(transfers, staking, etc.), use Option A or B with a configured Agent Wallet.
:::Recommendation
Add a brief note clarifying whether Docker write mode is supported and, if so, how to enable it:
:::tip Write operations in Docker
If you need write operations, mount your Agent Wallet directory and pass credentials:
```bash
docker run -d \
-p 3001:3001 \
-v $HOME/.agent-wallet:/root/.agent-wallet \
-e AGENT_WALLET_PASSWORD="your-password" \
-e TRONGRID_API_KEY="your-key" \
mcp-server-tronThis gives the container access to your local encrypted keystore while keeping
the key material off the container image.
:::
---
#### [MN-04] Security Scan Table in QuickStart Shows High Risk for `agent-wallet` Without Context
| Property | Value |
|----------|-------|
| **Severity** | Minor |
| **Category** | Documentation / User Experience |
| **File** | `docs/McpServer-Skills/SKILLS/QuickStart.md` : Lines 84–101 |
**Description**
The updated security scan table shows `agent-wallet` as `Med Risk` (Gen), `1 alert` (Socket), and `High Risk` (Snyk). Unlike `x402-payment` which shows only `Med` ratings, `agent-wallet` carries a `High Risk` Snyk score — yet no explanation or context is provided for why this is acceptable. Users unfamiliar with Snyk's risk scoring for cryptographic key management libraries may be alarmed and choose not to install the skill.
**Code**
```markdown
│ agent-wallet Med Risk 1 alert High Risk │
Recommendation
Add a brief parenthetical or follow-up note explaining the risk ratings:
> **Note on security risk ratings:** The `High Risk` Snyk rating for `agent-wallet` reflects
> the presence of cryptographic key management code — a category Snyk flags conservatively.
> The skill has been reviewed and the flagged code is intentional signing functionality.
> See the [agent-wallet GitHub repository](https://github.com/BofAI/agent-wallet) for audit details.[MN-05] quickstart-for-agent.md Removes import os But Python Code Still Has Implicit os Dependency via AGENT_WALLET_PRIVATE_KEY
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Correctness / Documentation |
| File | docs/x402/getting-started/quickstart-for-agent.md : Lines 216–218 (TRON section), Lines 354–358 (BSC section) |
Description
The diff removes import os from both the TRON and BSC Python client examples (replaced with the TronClientSigner.create() and EvmClientSigner.create() factory methods). This is correct — the factories resolve credentials internally. However, the env var AGENT_WALLET_PRIVATE_KEY is still referenced in Step 2 as the credential source, and if users follow the environment-variable path (rather than encrypted wallet), the create() factory presumably reads this env var using os.getenv() internally. There is no doc note confirming create() is aware of AGENT_WALLET_PRIVATE_KEY, leaving the credential resolution chain implicit. A user debugging a "wallet not found" error from create() will not know which env var to check.
Code
# import os <-- removed in diff
...
signer = await TronClientSigner.create() # how does it find AGENT_WALLET_PRIVATE_KEY?Recommendation
Add a brief inline comment or an info admonition clarifying the resolution order:
# TronClientSigner.create() resolves wallet credentials in priority order:
# 1. Encrypted agent-wallet keystore (if AGENT_WALLET_PASSWORD is set)
# 2. AGENT_WALLET_PRIVATE_KEY environment variable
# 3. AGENT_WALLET_MNEMONIC environment variable
signer = await TronClientSigner.create()This aligns with the info block already present at the top of the file but makes it immediately visible at the point of use.
Suggestions
[S-01] Add a --dry-run Example to the x402 Quickstart
File: docs/x402/getting-started/quickstart-for-agent.md
Description: The SUN CLI docs prominently feature --dry-run as a safety mechanism. The x402 quickstart-for-agent guide doesn't mention any analogous preview capability before executing a payment. If the x402 SDK supports a simulation or dry-run mode, a brief mention would align the safety messaging across the docs suite.
Suggestion: Add a tip block: "Before running your client in production, verify the server returns a 402 response correctly by checking the WWW-Authenticate header with a simple httpx.get() call first."
[S-02] SUN CLI CommandGuide Could Cross-Reference v3/v4 Tick Computation
File: docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md
Description: The liquidity v3:mint and v4:mint commands list --tick-lower and --tick-upper as optional with "Auto" defaults, but do not explain how the automatic tick range is computed (e.g., full-range, ±10 ticks from current price). This is a common source of confusion for DeFi users managing concentrated liquidity.
Suggestion: Add a brief note: "When --tick-lower / --tick-upper are omitted, the CLI defaults to the full tick range for the pool's fee tier. For custom ranges, calculate tick values using 1.0001^tick = price or use an external tick calculator."
[S-03] Privy Wallet Type Should Reference a Minimum Privy SDK Version
File: docs/Agent-Wallet/Developer/CLI-Reference.md, docs/Agent-Wallet/FAQ.md
Description: The new privy wallet type documentation says "You'll need a Privy App ID, App Secret, and Wallet ID" but does not state which version of agent-wallet introduced Privy support or what minimum Privy server wallet SDK version is required.
Suggestion: Add "Privy wallet support was introduced in agent-wallet v2.x.x. Requires Privy server wallet API v1." (substituting actual versions) to the tip block in CLI-Reference.md.
[S-04] Version 1.2.8 Bump Should Have a CHANGELOG Entry
File: package.json
Description: The package version is bumped from 1.2.7 to 1.2.8 but no CHANGELOG.md exists or is referenced. The TRON MCP Server FAQ has an inline changelog section ("What changed in v1.1.7?"), which is a good pattern — but the doc-site's own version history is not tracked.
Suggestion: Either create a CHANGELOG.md at the repo root or add a note in docs/ documenting what doc-site version 1.2.8 includes, so external users can identify when specific documentation was updated.
Positive Observations
| Area | Observation |
|---|---|
| Security callouts | Every new section involving private keys or mnemonic phrases includes a :::caution or :::warning admonition. The CommandGuide.md even includes a full-width caution on the very first page about --private-key shell history risk. |
| Read-only vs. write labeling | All SUN CLI commands are consistently labeled (read) or (write) throughout CommandGuide.md. This makes the access model immediately clear to both human operators and AI agents consuming the docs. |
| Testnet-first guidance | Both SUNCli/QuickStart.md and SUNCli/Intro.md prominently recommend Nile testnet before mainnet. The tip block in QuickStart is well-placed immediately before the first write operation example. |
| Dry-run support documented | --dry-run is documented as a global flag and is reflected in examples, supporting safe automation workflows without risking on-chain state changes. |
| Docker deployment addition | The Docker Option D section for TRON MCP Server is a welcome addition, including a health check endpoint and log-mount details — practical information often omitted from initial deployment docs. |
| Fallback RPC disclosure | The :::note Fallback RPC Endpoint blocks in x402 quickstarts honestly disclose that BANK OF AI's public endpoint has no SLA guarantees. This is the right level of transparency for production users. |
| agent-wallet multisig danger warning | The new :::danger Lockout warning in BANKOFAISkill.md for the multisig skill is critical safety information that was previously absent. |
| Consistent versioned-docs mirroring | Every change in docs/ is correctly mirrored in versioned_docs/current/, ensuring versioned site builds remain consistent. |
Checklist Results
| Category | Items Checked | Pass | Fail | N/A | Notes |
|---|---|---|---|---|---|
| Correctness | 8 | 6 | 2 | 0 | MJ-02 (behavior change inconsistency), MN-05 (implicit env var resolution) |
| Security | 10 | 8 | 1 | 1 | MJ-03 (process-listing risk underexplained); auth checks N/A (doc-only repo) |
| Performance | 7 | 0 | 0 | 7 | Not applicable to documentation |
| Code Quality | 6 | 5 | 1 | 0 | MN-01 (inconsistent env var naming across docs) |
| Testing | 5 | 0 | 0 | 5 | Not applicable to documentation |
| Documentation | 6 | 4 | 2 | 0 | MJ-01 (incomplete migration steps), MN-03 (Docker write-mode undocumented) |
| Compatibility | 5 | 3 | 0 | 2 | Node ≥20 bump is justified; migration guide needed (MJ-01) |
| Observability | 4 | 4 | 0 | 0 | Logging, error messages, and RPC fallback disclosures are all present |
Disclaimer
This is an automated code review. It supplements but does not replace human review. The reviewer analyzed only the diff between the specified branches (main...update-mcp-server). This is a documentation-only repository; findings focus on accuracy, consistency, security messaging, and completeness of the documentation changes rather than code runtime behavior.
Report generated by Code Review Skill v1.0.0
Date: 2026-04-09
Code Review ReportProject: BofAI/docs PR OverviewBranch Information
Commit History
Review SummaryVerdict
Findings at a Glance
SummaryThis PR is primarily a documentation update release encompassing three major content areas: (1) introduction of the SUN CLI tool with four new documentation pages (Intro, QuickStart, CommandGuide, FAQ); (2) migration of TRON MCP Server and SUN MCP Server from supporting three wallet modes ( The overall quality of this documentation is high — content is well-structured, security warnings are prominently placed, and i18n (zh-Hans) translations are kept in sync. However, two major issues require attention before merge: the Docker deployment example leaks the API key via command-line arguments (a documented security anti-pattern in this very project), and the breaking change removal of Change Summary1. New SUN CLI Documentation (4 new files)
Purpose: Introduce SUN CLI ( 2. TRON MCP Server v1.1.7 Breaking Change — Agent Wallet Only
Purpose: Document v1.1.7 breaking changes: legacy wallet env vars removed; write tools now always visible (wallet checked at execution time); Docker support added; all wallet management through Agent Wallet. 3. SUN MCP Server — Agent Wallet Migration
Purpose: Mirror the same wallet-only migration for SUN MCP Server docs. 4. Agent Wallet — New Features
Purpose: Document the 5. x402 Payment — GasFree and Unified Key Config
Purpose: Document the new 6. Skills and Extension Updates
Purpose: Introduce 7. Configuration / Navigation
Detailed FindingsMajor[MJ-01] Docker Run Example Passes API Key via Inline
|
| Property | Value |
|---|---|
| Severity | Major |
| Category | Security |
| File | docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md : Lines 130–143 (Option D) |
Description
The newly added Docker deployment example uses inline
-e KEY="value"to pass theTRONGRID_API_KEY. This approach records the API key in shell history, exposes it indocker inspectoutput (visible to any user who can rundocker inspect), and may appear in system-level process listings. This is the exact security anti-pattern that this same PR warns against extensively elsewhere (e.g., the "plaintext in environment variables" caution removed from the non-Docker options). A documentation project that teaches security-sensitive blockchain tooling should model secure practices in all code samples.
Code
docker run -d \
-p 3001:3001 \
-v $(pwd)/logs:/app/logs \
-e TRONGRID_API_KEY="<your-key>" \
mcp-server-tronRecommendation
Use --env-file to pass secrets, which avoids shell history and docker inspect exposure:
# 1. Create a .env file (never commit this file)
cat > .env.docker << 'EOF'
TRONGRID_API_KEY=your-key-here
EOF
# 2. Run with --env-file
docker run -d \
-p 3001:3001 \
-v $(pwd)/logs:/app/logs \
--env-file .env.docker \
mcp-server-tronAlso add a :warning admonition:
:::warning
Never pass API keys with `-e KEY=value` in production — the value appears in
shell history and `docker inspect`. Use `--env-file` with a file excluded from
version control.
:::[MJ-02] Breaking Change — No Migration Warning on QuickStart Pages
| Property | Value |
|---|---|
| Severity | Major |
| Category | Documentation / Compatibility |
| File | docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md, docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md |
Description
The removal of
TRON_PRIVATE_KEYandTRON_MNEMONICenvironment variable support (v1.1.7) is a breaking change for all existing users who currently run either MCP server with those variables set. Their deployments will silently break on upgrade — they will see a "Wallet not configured" error at runtime with no indication of why (the env vars they set are now ignored). The FAQ and LocalPrivatizedDeployment pages include caution blocks about this, but these are not the first pages returning users will consult on upgrade. The QuickStart pages and top-level sidebar pages lack any upgrade notice, changelog link, or "⚠️ Upgrading from v1.1.6?" banner. Users who rely on the QuickStart as their reference will be confused.
Code
<!-- Current QuickStart.md has NO mention of v1.1.7 breaking change -->
These are just the tip of the iceberg. For the full list of 97 tools...Recommendation
Add a prominent admonition at the top of TRONMCPServer/QuickStart.md and link from the sidebar intro:
:::warning Upgrading from v1.1.6 or earlier?
As of **v1.1.7**, the `TRON_PRIVATE_KEY` and `TRON_MNEMONIC` environment variables
are no longer supported. All wallet management now uses **Agent Wallet**.
If you had either variable set, write operations will fail until you migrate.
See [Migrating to Agent Wallet](./LocalPrivatizedDeployment.md#agent-wallet) for
step-by-step instructions.
:::The same notice should appear at the top of SUNMCPServer/QuickStart.md (if one exists) and the respective LocalPrivatizedDeployment.md intro sections.
Minor
[MN-01] agent-wallet init -p Lacks Security Caution
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Security / Documentation |
| File | docs/Agent-Wallet/Developer/CLI-Reference.md : agent-wallet init section |
Description
The new
agent-wallet initsection documents a non-interactive mode that accepts the master password via the-pflag (agent-wallet init -p 'Abc12345!'). Passing passwords as CLI arguments records them in shell history (.bash_history,.zsh_history) and process listings (ps aux). Theagent-wallet change-passwordsection immediately below this one correctly includes a:cautionblock about exactly this risk. Theinitsection is missing the equivalent warning, creating an inconsistency that may mislead users into treating-pas safe oninitbut not onchange-password.
Code
**Non-interactive mode:**
```bash
agent-wallet init -p 'Abc12345!'
**Recommendation**
Add a `:caution` admonition immediately after the non-interactive example, mirroring the `change-password` section:
```markdown
:::caution
`-p` will be recorded in shell history. For production use, prefer the interactive
mode (`agent-wallet init` without flags) or set the `AGENT_WALLET_PASSWORD`
environment variable instead.
:::
[MN-02] --save-runtime-secrets Flag Has No Security Warning
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Security / Documentation |
| File | docs/Agent-Wallet/Developer/CLI-Reference.md : agent-wallet init and agent-wallet change-password flag tables |
Description
Both the
agent-wallet initandagent-wallet change-passwordsections list a--save-runtime-secretsflag described as persisting the password toruntime_secrets.json. This flag stores the master password — the sole credential protecting all encrypted wallet keys — in a plaintext JSON file on disk. This is a significant security trade-off: any process or user with file system access can read it. The flag is listed in a plain table row with no warning, no note about where the file is stored, and no recommendation about when it is or is not appropriate to use.
Code
| `--save-runtime-secrets` | 将密码持久化保存到 `runtime_secrets.json` |(Same in the English version of CLI-Reference.md)
Recommendation
Expand the flag description and add a warning:
| `--save-runtime-secrets` | Persist the master password to `runtime_secrets.json` in the wallet directory. **Only use in fully trusted, isolated environments (e.g., containerized CI).** |And add an admonition below the flags table:
:::danger `--save-runtime-secrets` stores your master password in plaintext
`runtime_secrets.json` is not encrypted. Any process with read access to the
wallet directory can retrieve your master password and decrypt all wallet keys.
Do not use this flag on shared machines or in environments where the wallet
directory may be accessible to other users or processes.
:::[MN-03] agent-wallet "High Risk" Snyk Rating Not Explained in Security Table
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | docs/McpServer-Skills/SKILLS/QuickStart.md : Security Risk Assessments table |
Description
The updated security scan table now shows
agent-walletwithMed Risk(Gen),1 alert(Socket), andHigh Risk(Snyk). This is the highest Snyk rating in the table and applies to a skill that manages private keys and wallet credentials — the most security-critical component. Yet the table provides no explanation of what the risk is, whether it is a known transitive dependency issue, or what users should do about it. All other skills with ratings show lower levels. A user evaluating whether to install the skill has no context to make an informed decision. This is especially concerning given the sensitive nature of wallet management.
Code
│ agent-wallet Med Risk 1 alert High Risk │
Recommendation
Add a footnote or expandable callout below the security table:
> **Note on agent-wallet risk ratings:** The Snyk "High Risk" rating reflects a
> known transitive dependency issue in the underlying crypto libraries (e.g., a
> `secp256k1` or `elliptic` advisory). The `agent-wallet` skill itself does not
> expose these functions to untrusted input. Review the full Snyk report at
> [link] before installing in production environments.If the risk is not yet characterized, the minimum acceptable change is a note such as:
> The `agent-wallet` Snyk rating is under review. See [GitHub issue #XX] for
> details.[MN-04] SUN CLI CommandGuide Missing -p/--agent-wallet-password Security Caution
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Security / Documentation |
| File | docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md : Global Flags section |
Description
The CommandGuide's Global Flags section correctly includes a
:cautionblock warning about shell history and process listings for the-k/--private-keyand-m/--mnemonicflags. However, the-p/--agent-wallet-passwordflag — which also passes a sensitive credential (the Agent Wallet master password) as a CLI argument — is listed in the same table without any equivalent security warning. A user reading the docs will see the caution for private keys and mnemonics, but may not realize that-pcarries the same shell-history risk.
Code
| `-p, --agent-wallet-password <password>` | Override `AGENT_WALLET_PASSWORD` for this invocation |(Listed without any security note, while -k and -m have a caution block immediately following the table)
Recommendation
Extend the existing :caution block to cover -p as well:
:::caution Private Credential Security
The `-k` / `--private-key`, `-m` / `--mnemonic`, and `-p` / `--agent-wallet-password`
flags pass sensitive material as command-line arguments, which may be recorded in
shell history and process listings. Prefer environment variables
(`AGENT_WALLET_PRIVATE_KEY`, `AGENT_WALLET_MNEMONIC`, `AGENT_WALLET_PASSWORD`)
or [agent-wallet](https://github.com/ABlockofAI/agent-wallet) for production use.
:::Suggestions
[S-01] exact_gasfree Scheme — Add Fallback Behavior Documentation
File: docs/x402/core-concepts/network-and-token-support.md, docs/x402/getting-started/quickstart-for-human.md
Description: The new exact_gasfree payment scheme routes through a BANK OF AI proxy with "no SLA guarantee." The documentation mentions this limitation in passing but does not describe what happens from a user/buyer perspective when the proxy is unavailable — does the transaction fail silently, fall back to exact, or return an error? Sellers implementing this scheme need to understand the failure modes to build robust integrations.
Suggestion: Add a subsection on failure behavior and a recommendation to always have an exact payment option as a fallback for production deployments. Consider also documenting proxy availability, rate limits, and any monitoring endpoints.
[S-02] Docker Deployment — Add --readonly Flag Note
File: docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md : Option D (Docker)
Description: The :tip block for Docker says "The Docker image is designed for read-only cloud deployments." However, neither the Docker section nor the docker run example mentions the --readonly flag documented elsewhere. Users who want read-only behavior explicitly should know to pass this flag, and users who want write operations should know that they need a different deployment option rather than trying to add AGENT_WALLET_PASSWORD to the Docker run command.
Suggestion: Reference --readonly explicitly in the Docker tip block and clarify why write operations are not supported in the Docker image (missing Agent Wallet directory mount, or by design).
[S-03] SUN CLI QuickStart — Mention TRON_GRID_API_KEY Recommendation
File: docs/McpServer-Skills/MCP/SUNCli/QuickStart.md : Network & API Configuration section
Description: The QuickStart mentions TRON_GRID_API_KEY as a configurable variable but does not convey that it is recommended for production use (the x402 docs elsewhere use language like "required for mainnet; recommended for production workloads"). A new SUN CLI user querying mainnet data may hit rate limits without understanding why, since the section currently presents the API key as optional without context.
Suggestion: Add a note similar to: "Without a TronGrid API key, SUN CLI uses a shared fallback endpoint with no SLA guarantee. For production or high-frequency queries, set TRON_GRID_API_KEY."
[S-04] i18n zh-Hans sidebars.js Not Updated
File: i18n/zh-Hans/docusaurus-plugin-content-docs/current/sidebars.js
Description: The root sidebars.js was updated to add the SUN CLI category. The diff shows i18n/zh-Hans/docusaurus-plugin-content-docs/current/sidebars.js was also updated (confirmed in the diff). However, 4 new SUNCli .md files were added under i18n/zh-Hans/... but double check that the zh-Hans sidebar includes SUNCli/Intro, SUNCli/QuickStart, SUNCli/CommandGuide, SUNCli/FAQ in the correct order to match the English sidebar. If the translation sidebar ordering diverges from the English one, Chinese users will see a different navigation structure.
Suggestion: Verify the zh-Hans sidebars.js SUNCli entry order matches the English sidebars.js exactly.
Positive Observations
| Area | Observation |
|---|---|
| Security messaging | Security cautions are placed proactively throughout new content. The :::caution Private Key Security block in CommandGuide.md is clear and actionable; the agent-wallet change-password section explicitly warns about shell history. |
| Breaking change disclosure | Every directly relevant page (FAQ, LocalPrivatizedDeployment) includes a :::caution Legacy wallet options removed block with migration direction. |
| i18n completeness | All 31 zh-Hans files are kept in sync with English counterparts in the same PR, avoiding documentation drift. |
| Test-first guidance | SUN CLI QuickStart and TRON MCP Server docs consistently recommend Nile testnet before mainnet — good practice for financial operations. |
| Consistent link fixing | Internal links have been systematically updated from bare fragment paths (e.g., ../../../Agent-Wallet/Intro) to explicit .md-extension paths (e.g., ../../../Agent-Wallet/Intro.md), improving Docusaurus link validation. |
| Docker documentation | The new Docker option is well-structured with build, run, and configuration notes including a health check endpoint reference. |
| Dangerous op restriction | The agent-wallet skill section explicitly states that remove, reset, and change-password are agent-restricted (must be run in terminal by the user), which is an important safety guardrail documented clearly. |
--dry-run promotion |
Both SUN CLI and the GasFree docs prominently surface --dry-run as a first step before executing write operations — excellent practice for financial tooling. |
Checklist Results
| Category | Items Checked | Pass | Fail | N/A | Notes |
|---|---|---|---|---|---|
| Correctness | 8 | 7 | 1 | 0 | Tool count 95→97 consistent across all files; Docker example uses insecure -e pattern |
| Security | 10 | 6 | 4 | 0 | init -p, --save-runtime-secrets, Docker -e, sun -p flag all missing or inconsistent warnings |
| Performance | 3 | 3 | 0 | 0 | N/A for docs; pagination/rate limit guidance present in SUN CLI |
| Code Quality | 6 | 5 | 1 | 0 | agent-wallet Snyk rating unexplained; consistent style otherwise |
| Testing | 2 | 2 | 0 | 0 | --dry-run and testnet guidance present throughout |
| Documentation | 8 | 6 | 2 | 0 | Breaking change not surfaced in QuickStart; --save-runtime-secrets not explained |
| Compatibility | 4 | 2 | 2 | 0 | No QuickStart upgrade warning; migration path only in FAQ/deployment pages |
| Observability | 3 | 3 | 0 | 0 | Log path in Docker, --dry-run pattern, error messages documented |
Disclaimer
This is an automated code review. It supplements but does not replace human review. The reviewer analyzed only the diff between the specified branches. Runtime behavior, integration testing, and deployment impact are not covered.
Report generated by Code Review Skill v1.0.0
Date: 2026-04-09
Code Review ReportProject: BofAI/docs PR OverviewBranch Information
Commit History
Review SummaryVerdict
Findings at a Glance
SummaryThis PR delivers a substantial and well-structured documentation update with three main thrusts: (1) introduction of the new SUN CLI tool as a complete 4-file documentation suite, (2) a breaking wallet-mode migration across TRON MCP Server, SUN MCP Server, and x402 — retiring The prose is clear, the new SUN CLI reference is thorough, and security admonitions are generally well placed. However, three meaningful issues require resolution before merge: an incorrect GitHub organisation URL in a code example ( Change Summary1. SUN CLI — New Documentation Suite (4 new files)
Purpose: Introduce 2. Wallet-Mode Migration — TRON MCP Server & SUN MCP Server
Purpose: Align documentation with v1.1.7 breaking change — legacy 3. Agent Wallet — New Features & Node.js Version Bump
Purpose: Document Privy cloud wallet support, two new CLI commands ( 4. x402 —
|
| File | Change Type | Description |
|---|---|---|
docs/x402/core-concepts/network-and-token-support.md |
Modified | Adds exact_gasfree scheme documentation with GasFree account management CLI examples |
docs/x402/faq.md |
Modified | Updates payment scheme list to include exact_gasfree |
docs/x402/sdk-features.md |
Modified | Adds exact_gasfree/tron, SufficientBalancePolicy, GasFree, USDD to feature matrix |
docs/x402/getting-started/quickstart-for-agent.md |
Modified | Replaces TRON_PRIVATE_KEY/BSC_PRIVATE_KEY with AGENT_WALLET_PRIVATE_KEY; simplifies platform prerequisites; adds TronClientSigner.create() async API; registers ExactGasFreeClientMechanism |
docs/x402/getting-started/quickstart-for-human.md |
Modified | Same env-var unification; adds ExactGasFreeClientMechanism; adds fallback-RPC note |
docs/x402/getting-started/quickstart-for-sellers.md |
Modified | Env-var rename; adds fallback RPC note |
docs/x402/index.md |
Modified | Minor formatting (bold network names) |
Purpose: Surface the new exact_gasfree zero-gas payment scheme for TRON, and unify all wallet private-key env vars to AGENT_WALLET_PRIVATE_KEY.
5. Skills & Navigation
| File | Change Type | Description |
|---|---|---|
docs/McpServer-Skills/SKILLS/BANKOFAISkill.md |
Modified | Adds agent-wallet skill entry (table, use-case examples, security admonitions, TRC20 advanced features, Multi-Sig danger callout) |
docs/McpServer-Skills/SKILLS/Intro.md |
Modified | 7→8 skills; adds agent-wallet capability blurb |
docs/McpServer-Skills/SKILLS/QuickStart.md |
Modified | Updated installer UI screenshots to show 8 skills and agent-wallet security risk ratings |
docs/Openclaw-extension/QuickStart.md |
Modified | Reflects 8 skills in installer output; auto-config for mcp-server-tron; adds x402-config cleanup line |
sidebars.js |
Modified | Adds "SUN CLI" category to MCP section with 4 child pages |
i18n/current/sidebars.js |
Modified | Same sidebar change mirrored to versioned docs |
package.json |
Modified | Version bump 1.2.7→1.2.8 |
Purpose: Register agent-wallet as the 8th skill, add SUN CLI to sidebar navigation, and mirror all key changes into the versioned (i18n/current/) copy of the docs.
Detailed Findings
Major
[MJ-01] Wrong GitHub Organisation URL in CommandGuide.md
| Property | Value |
|---|---|
| Severity | Major |
| Category | Correctness |
| File | docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md : Lines 29–34 |
Description
The Global Flags security caution in CommandGuide.md links to https://github.com/ABlockofAI/agent-wallet, but every other reference throughout the codebase consistently uses https://github.com/BofAI/agent-wallet. ABlockofAI appears to be an incorrect or legacy organisation name. Users clicking this link from the command reference will reach a 404 or an unrelated repository.
Code
:::caution Private Key Security
The `-k` / `--private-key` and `-m` / `--mnemonic` flags pass sensitive
material as command-line arguments, which may be recorded in shell history
and process listings. Prefer environment variables (`AGENT_WALLET_PRIVATE_KEY`,
`AGENT_WALLET_MNEMONIC`) or [agent-wallet](https://github.com/ABlockofAI/agent-wallet)
encrypted storage for all non-throwaway keys.
:::Recommendation
or [agent-wallet](https://github.com/BofAI/agent-wallet)Cross-reference: docs/McpServer-Skills/MCP/SUNCli/Intro.md correctly uses https://github.com/BofAI/agent-wallet.
[MJ-02] Plaintext Private Key Security Warning Removed Without Replacement
| Property | Value |
|---|---|
| Severity | Major |
| Category | Security / Documentation |
| File | docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md : Lines 86–110 (and mirror in docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md) |
Description
The PR removes the :::warning admonitions that explained the security risks of plaintext private keys in environment variables (exposure via shell history, ps aux, log files). The replacement "Option B: Import an Existing Private Key" now instructs users to run export AGENT_WALLET_PRIVATE_KEY=your_private_key_here — the same plaintext exposure risk — but provides only a :::tip about persistence and no mention of the security trade-off. Users who previously understood the risk from the warning may miss it in the new layout; new users have no warning at all for this path.
The :::caution Legacy wallet options removed note at the end of Option B discusses migration, not security risk.
Code
-:::warning
-Using a plaintext private key in environment variables carries a **real risk of fund theft**
-— environment variables can be leaked via shell history, process listings (`ps aux`), or
-log files. **Only keep small amounts of funds** in wallets configured this way.
-:::
+#### Option B: Import an Existing Private Key
+
+If you already have a private key you want to use, set it via the `AGENT_WALLET_PRIVATE_KEY`
+environment variable:
+
+```bash
+export AGENT_WALLET_PRIVATE_KEY=your_private_key_hereRecommendation
Add a :::warning (or at minimum :::caution) admonition immediately under the Option B heading:
#### Option B: Import an Existing Private Key
:::warning Security trade-off
Setting `AGENT_WALLET_PRIVATE_KEY` as an environment variable exposes the key in
shell history, process listings (`ps aux`), and potentially log files. Only keep
small amounts of funds in wallets configured this way. For production or
significant funds, use Option A (generate a new wallet via `agent-wallet start`)
which stores the key encrypted on disk.
:::[MJ-03] Inconsistent Internal Link Format in TRONMCPServer/LocalPrivatizedDeployment.md
| Property | Value |
|---|---|
| Severity | Major |
| Category | Correctness |
| File | docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md : Lines 57, 66 |
Description
Two newly introduced links inside LocalPrivatizedDeployment.md reference Agent-Wallet/Intro without the .md file extension, while the immediately preceding link on line 53 — and all other Agent Wallet links added in this PR across every other file — correctly use the .md extension. Docusaurus resolves links at build time; depending on the trailingSlash and markdown.format configuration, bare links without .md may fail or generate 404 pages in production.
Code
<!-- Line 53 — correct -->
TRON MCP Server uses [Agent Wallet](../../../Agent-Wallet/Intro.md) for secure wallet management.
<!-- Line 57 — missing .md -->
TRON MCP Server uses [Agent Wallet](../../../Agent-Wallet/Intro) for wallet management.
<!-- Line 66 — missing .md -->
> For installation, initialization, and detailed usage of Agent Wallet, see the
> [Agent-Wallet documentation](../../../Agent-Wallet/Intro).Recommendation
<!-- Line 57 -->
TRON MCP Server uses [Agent Wallet](../../../Agent-Wallet/Intro.md) for wallet management.
<!-- Line 66 -->
> For installation, initialization, and detailed usage of Agent Wallet, see the
> [Agent-Wallet documentation](../../../Agent-Wallet/Intro.md).Verify the same lines in i18n/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md — the versioned copy carries the same issue.
Minor
[MN-01] agent-wallet "High Risk" Snyk Rating Shown Without Context
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | docs/McpServer-Skills/SKILLS/QuickStart.md : Lines 88–100 |
Description
The newly added agent-wallet skill shows High Risk from Snyk and Med Risk from Gen in the installer security scan output, with no accompanying explanation in the prose. x402-payment also shows Med Risk from Snyk in both the previous and current version, and a comment was added for it elsewhere; but the agent-wallet rating — significantly higher — is left without context. Users may be alarmed and abort installation, or worse, dismiss the rating without understanding it. Since this is a wallet-signing skill, user trust is especially important here.
Code
│ agent-wallet Med Risk 1 alert High Risk │
Recommendation
Add a brief note after the security scan block (or as a :::note admonition) explaining what these ratings reflect:
:::note About the agent-wallet security rating
The "High Risk" Snyk rating reflects that `agent-wallet` handles cryptographic
key material, which scanner heuristics flag by design. The skill signs locally
and never transmits private keys to external services. Review the
[agent-wallet source](https://github.com/BofAI/agent-wallet) if you wish to
audit the signing logic yourself.
:::The same note (already present for x402-payment elsewhere) should be consistent.
[MN-02] --save-runtime-secrets Flag Documented Without Security Warning
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Security / Documentation |
| File | docs/Agent-Wallet/Developer/CLI-Reference.md : Lines (new agent-wallet init section) |
Description
The new agent-wallet init command documentation lists the --save-runtime-secrets flag (which persists the master password to runtime_secrets.json) with no security warning about the risks of storing the master password in a plaintext JSON file on disk. This is particularly sensitive because runtime_secrets.json could be read by any process with file system access, undermining the encryption model of local_secure wallets.
The agent-wallet change-password section added in the same PR does include a caution about shell history for non-interactive use — the same standard should apply here.
Code
| Flag | Description |
| :--- | :--- |
| `--password, -p <pw>` | Master password (skip prompt) |
| `--save-runtime-secrets` | Persist password to `runtime_secrets.json` |Recommendation
Add a caution admonition:
:::caution
`--save-runtime-secrets` writes your master password to `runtime_secrets.json`
in plaintext. Any process with read access to this file can decrypt all
`local_secure` wallets. Use only in fully isolated environments (e.g., a
dedicated CI runner). Prefer interactive password entry for developer machines.
:::[MN-03] No Migration Note for x402 SDK Users Switching Env Var Names
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | docs/x402/getting-started/quickstart-for-agent.md, quickstart-for-human.md, quickstart-for-sellers.md |
Description
The PR renames the chain-specific private key env vars (TRON_PRIVATE_KEY, BSC_PRIVATE_KEY) to the unified AGENT_WALLET_PRIVATE_KEY across all three x402 quick-start guides. Existing users who have TRON_PRIVATE_KEY or BSC_PRIVATE_KEY set in their shells, .env files, CI pipelines, or Docker configs will experience silent key resolution failure — the SDK will find no wallet and fail at runtime. Unlike the MCP server docs, these x402 guides contain no upgrade callout banner or migration note.
Recommendation
Add an upgrade notice at the top of each affected quickstart, consistent with the pattern already used in TRONMCPServer/QuickStart.md:
:::warning Migrating from an earlier x402 SDK version?
The environment variable for your private key has changed:
- `TRON_PRIVATE_KEY` → `AGENT_WALLET_PRIVATE_KEY`
- `BSC_PRIVATE_KEY` → `AGENT_WALLET_PRIVATE_KEY`
Update your shell profile, `.env` files, and CI/CD pipeline configs before upgrading.
:::[MN-04] exact_gasfree Routes Through Third-Party Proxy Without Explicit Trust Notice
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Security / Documentation |
| File | docs/x402/core-concepts/network-and-token-support.md : exact_gasfree section |
Description
The exact_gasfree documentation states that "all GasFree API calls route through the BANK OF AI facilitator endpoint at https://facilitator.bankofai.io/{mainnet,nile}" to eliminate the need for client-side API keys. This means payment transaction metadata (wallet addresses, amounts, signatures) is relayed through a third-party operated proxy. The docs explain the convenience benefit but do not disclose what data the proxy receives, whether it logs requests, or what trust assumptions users are making.
Recommendation
Add a transparency note:
:::note Privacy and trust
When using `exact_gasfree`, your wallet address, payment amounts, and
authorization signatures are transmitted to `https://facilitator.bankofai.io`
for relay to the GasFree API. The BANK OF AI facilitator does not retain
custody of funds but does see transaction metadata. For production workloads
requiring full data sovereignty, consider running your own GasFree relay.
:::Suggestions
[S-01] Add a Dedicated v1.1.7 Migration Guide
File: docs/McpServer-Skills/MCP/TRONMCPServer/ (new file suggested)
Description: The v1.1.7 breaking changes (wallet mode removal, write-tool visibility change) are documented in-line across FAQ, Intro, QuickStart, and LocalPrivatizedDeployment. A single dedicated migration page (e.g. MigratingToV1.1.7.md) would give users a single authoritative reference, and could be linked from all upgrade warning banners.
Suggestion: Create docs/McpServer-Skills/MCP/TRONMCPServer/MigratingToV1.1.7.md covering: what changed, why, step-by-step migration instructions for each former wallet mode, and a verification checklist.
[S-02] Document TronClientSigner.create() API Change Impact
File: docs/x402/getting-started/quickstart-for-human.md : Python code block
Description: The Python code example now uses await TronClientSigner.create() (async factory) instead of the synchronous TronClientSigner.from_private_key(os.getenv("TRON_PRIVATE_KEY")). This is a significant API surface change. Users who have built their own x402 clients based on the previous snippet will need to update their code, but there is no API changelog or SDK version gate mentioned.
Suggestion: Add a brief inline comment and/or a :::note SDK version admonition indicating the minimum SDK version that supports TronClientSigner.create(), and note that from_private_key() is deprecated.
[S-03] Docker Section Could Clarify Read-Only Limitation More Prominently
File: docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md : Option D Docker
Description: The Docker deployment section notes at the end (in a :::tip) that "The Docker image is designed for read-only cloud deployments." This important constraint is easy to miss. Users expecting write operations in Docker may configure the container and only discover the limitation after attempting a transaction.
Suggestion: Move the read-only limitation to the opening of the Docker section as a :::warning or make it the first sentence of the section body, so users can decide whether Docker is the right option before reading the setup steps.
Positive Observations
| Area | Observation |
|---|---|
| Upgrade warnings | TRON MCP Server Intro.md and QuickStart.md both open with a prominent :::warning callout for v1.1.7 upgraders — excellent pattern that proactively prevents user confusion. |
| Docker security guidance | The Docker section explicitly warns against passing secrets with -e KEY=value and mandates --env-file — this is the correct pattern and well articulated. |
change-password non-interactive warning |
New change-password docs correctly warn that -p / --new-password flags will appear in shell history and recommend interactive mode for production. |
--dry-run throughout SUN CLI |
The CommandGuide and QuickStart consistently promote --dry-run before high-value write operations. |
| Consistent migration callouts | The :::caution Legacy wallet options removed admonition is consistently placed at the end of each affected wallet section across both TRON MCP and SUN MCP server docs. |
| SUN CLI vs SUN MCP comparison table | The Intro.md for SUN CLI includes a clear side-by-side comparison table helping users choose the right tool — this is an excellent UX addition. |
exact_gasfree fallback RPC transparency |
Each quickstart now includes a :::note Fallback RPC Endpoint callout that honestly discloses the no-SLA nature of the public fallback, encouraging users to get their own API key for production. |
| Sidebar navigation | Adding the SUN CLI category to both sidebars.js and i18n/current/sidebars.js ensures consistent navigation in both the default and versioned docs. |
Checklist Results
| Category | Items Checked | Pass | Fail | N/A | Notes |
|---|---|---|---|---|---|
| Correctness | 8 | 6 | 2 | 0 | Broken GitHub org URL (MJ-01); broken link format (MJ-03) |
| Security | 7 | 5 | 2 | 0 | Missing plaintext key warning (MJ-02); --save-runtime-secrets undisclosed risk (MN-02) |
| Performance | 3 | 3 | 0 | 0 | N/A — documentation repo |
| Code Quality | 6 | 5 | 1 | 0 | Inconsistent link format (MJ-03); minor prose duplication |
| Testing | 2 | 2 | 0 | 0 | No test files in this repo |
| Documentation | 8 | 6 | 2 | 0 | Missing env-var migration note (MN-03); missing gasfree trust model (MN-04) |
| Compatibility | 4 | 3 | 1 | 0 | No x402 SDK migration guide for breaking API change (S-02) |
| Observability | 2 | 2 | 0 | 2 | N/A — documentation repo |
Disclaimer
This is an automated code review. It supplements but does not replace human review. The reviewer analyzed only the diff between main and update-mcp-server. Runtime behavior, integration testing, and deployment impact are not covered.
Report generated by Code Review Skill v1.0.0
Date: 2026-04-09
Code Review ReportProject: BofAI/docs (x402-tron Documentation) PR OverviewBranch Information
Commit History
Review SummaryVerdict
Findings at a Glance
SummaryThis PR is a substantial documentation update covering four main areas: (1) adding full SUN CLI documentation (Intro, QuickStart, CommandGuide, FAQ — approximately 1,267 new lines), (2) migrating TRON MCP Server and SUN MCP Server wallet configuration from legacy The changes are well-structured and represent a meaningful improvement in security posture (moving users away from plaintext private keys). However, three major issues require attention before merge: two newly introduced broken internal links, a numbering gap in deployment options (Option C is missing — jumping from B to D), and a version inconsistency where the Change Summary1. SUN CLI Documentation (New)Four new files added under
Both 2. TRON MCP Server & SUN MCP Server — Wallet Migration (Breaking Change for Existing Users)All references to 3. Agent Wallet Documentation Updates
4. x402 Payment Scheme —
|
| Category | Status | Notes |
|---|---|---|
| A. Correctness & Logic | Partial | Node.js version inconsistency (Finding 3); Option numbering gap (Finding 2) |
| B. Security | Partial | echo $AGENT_WALLET_PRIVATE_KEY reveals private key (Finding 4); MCP_HOST=0.0.0.0 needs security note (Finding 7) |
| C. Performance | N/A | Documentation only |
| D. Code Quality | Partial | Broken links (Finding 1); org name inconsistency (Finding 5); option numbering gap (Finding 2) |
| E. Testing | N/A | Documentation only — no automated link checking visible in CI configuration |
| F. Documentation & Maintainability | Partial | New docs are thorough; broken links and version inconsistency need resolution |
Disclaimer
This review was performed by an automated AI reviewer on the diff between origin/main and origin/update-mcp-server. Only changed lines were evaluated for issues. Full file context was read to understand impact. This review does not replace human judgment and may not capture all issues, particularly those requiring runtime validation or deep domain expertise in the underlying blockchain protocols.
Code Review ReportProject: BofAI/docs PR OverviewBranch Information
Commit History
Review SummaryVerdict
Findings at a Glance
SummaryThis PR is a large documentation-only update covering five main areas: (1) introduction of a brand-new SUN CLI section (four new pages, ~1,400 lines), (2) TRON and SUN MCP Server v1.1.7 migration away from legacy The overall quality of the content is high — security guidance is generally thorough, new features are well explained, and the migration notice for v1.1.7 is prominently placed. However, the PR introduces several issues that need attention before merge: a Node.js version inconsistency between files, loss of explicit security warnings when moving from plaintext keys to the new Change Summary1. New SUN CLI Documentation
Purpose: Document the new 2. TRON MCP Server v1.1.7 Changes
Purpose: Reflect v1.1.7 API changes: 3. SUN MCP Server Wallet Mode Removal
Purpose: Mirror the TRON MCP Server wallet change for SUN MCP Server; remove legacy wallet options. 4. Agent Wallet Documentation Expansion
Purpose: Document new Node.js 20 requirement, Privy managed wallet type, new CLI commands, and expanded SDK examples. 5. x402 Protocol Updates
Purpose: Document 6. Skills and Navigation Updates
Detailed FindingsMajor[MJ-01] Node.js Version Inconsistency: "18+" in quickstart-for-human.md vs "20+" Everywhere Else
Description The prerequisite checklist in Every other changed file in this PR explicitly bumps the Node.js requirement to 20+ — Code - [ ] **Python 3.11+** or **Node.js 18+** installed (depending on your chosen language)Recommendation - [ ] **Python 3.11+** or **Node.js 20+** installed (depending on your chosen language)[MJ-02] Security Warning Downgraded:
|
| Property | Value |
|---|---|
| Severity | Major |
| Category | Security |
| File | docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md, docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md, docs/x402/getting-started/quickstart-for-sellers.md : Multiple locations |
Description
The previous version of LocalPrivatizedDeployment.md (both TRON and SUN) included explicit :::warning blocks when documenting TRON_PRIVATE_KEY and TRON_MNEMONIC:
"Using a plaintext private key in environment variables carries a real risk of fund theft — environment variables can be leaked via shell history, process listings (
ps aux), or log files."
This PR removes those wallet options in favor of AGENT_WALLET_PRIVATE_KEY, but the new "Option B / Path 2: Import an Existing Private Key" sections show:
export AGENT_WALLET_PRIVATE_KEY=your_private_key_here...with only a :::tip about persistence and no security warning at all. The key is still plaintext in shell history and process listings. quickstart-for-sellers.md similarly shows:
export AGENT_WALLET_PRIVATE_KEY=paste_your_facilitator_private_key_herewith no accompanying caution. The CLI-Reference.md for change-password does include a :::caution about shell history for that specific command, establishing a precedent the deployment guides should follow.
Recommendation
Add a :::caution or :::warning admonition wherever export AGENT_WALLET_PRIVATE_KEY=<key> appears in plaintext, e.g.:
:::caution Shell history risk
This command stores your private key in shell history (`~/.zsh_history` or `~/.bash_history`).
For production use, prefer importing the key via `agent-wallet start` (encrypted keystore, Path 1)
or load it from a secrets manager. If you must use this method, run `history -d $(history 1)` after
setting the variable, or prefix the command with a space (if your shell supports `HISTCONTROL=ignorespace`).
:::[MJ-03] Python Code Example Missing Request Parameter Import in Seller Quick Start
| Property | Value |
|---|---|
| Severity | Major |
| Category | Correctness |
| File | docs/x402/getting-started/quickstart-for-sellers.md : Lines 153, 195 (TRON and BSC tabs) |
Description
The diff adds Request to two FastAPI endpoint function signatures:
-async def protected_endpoint():
+async def protected_endpoint(request: Request):The import line was also updated:
-from fastapi import FastAPI
+from fastapi import FastAPI, RequestBoth changes are necessary and consistent in the diff. This is a correct fix (without Request in the import the code would raise NameError at startup). However, the i18n mirror file (i18n/current/x402/getting-started/quickstart-for-sellers.md) must also reflect this change. If it does not, users reading the versioned/translated documentation will have broken example code.
Recommendation
Verify that the corresponding i18n mirror file at i18n/current/x402/getting-started/quickstart-for-sellers.md contains the same from fastapi import FastAPI, Request and async def protected_endpoint(request: Request): corrections. The diff stat shows this file was changed (+240 lines) but the exact content should be validated.
[MJ-04] Self-Hosted Facilitator References Undocumented Repo Change (x402-demo → x402-facilitator)
| Property | Value |
|---|---|
| Severity | Major |
| Category | Documentation |
| File | docs/x402/getting-started/quickstart-for-sellers.md : Self-Hosted tab, Step 3.2 |
Description
The self-hosted Facilitator instructions silently change the repository from https://github.com/BofAI/x402-demo.git to https://github.com/BofAI/x402-facilitator.git, the configuration format from a .env file to a YAML config file, and the startup command from ./start.sh facilitator to python src/main.py. Users who bookmarked the old guide or cloned the old repository will find the instructions entirely incompatible with their setup. There is no migration note, no explanation of why the repo changed, and no link to a changelog.
Code
# Old (removed):
git clone https://github.com/BofAI/x402-demo.git
cd x402-demo
# ...
./start.sh facilitator
# New:
git clone https://github.com/BofAI/x402-facilitator.git
cd x402-facilitator
# ...
python src/main.pyRecommendation
Add a callout at the top of the self-hosted section explaining the repo change:
:::info Facilitator repository change
As of this release, the self-hosted Facilitator has moved to its own dedicated repository:
`https://github.com/BofAI/x402-facilitator`. The old demo repo (`x402-demo`) is no longer
the canonical source for the Facilitator service. If you previously cloned `x402-demo`, please
re-clone from the new repository and follow the updated configuration steps below.
:::Minor
[MN-01] Broken Anchor Link: #agent-wallet-reset-reset-all-data May Not Resolve
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md : Line approx 80; docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md : Line approx 134 |
Description
Both files reference:
[CLI Reference → Reset](../../../Agent-Wallet/Developer/CLI-Reference.md#agent-wallet-reset-reset-all-data)The heading in CLI-Reference.md is ### \agent-wallet reset` (Reset All Data). Docusaurus generates anchors by stripping backticks and converting spaces/special characters to hyphens. The resulting anchor is typically agent-wallet-reset-reset-all-data`, which should match. However, if the heading text has changed (other commits in this PR rename headings), the anchor silently becomes a dead link. These should be verified.
Recommendation
Manually verify that navigating to CLI-Reference.md#agent-wallet-reset-reset-all-data resolves to the correct section after build. Consider adding an explicit {#agent-wallet-reset} anchor id to the heading for stability.
[MN-02] agent-wallet Skill "High Risk" Rating Unexplained in Security Assessment Table
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | docs/McpServer-Skills/SKILLS/QuickStart.md, docs/Openclaw-extension/QuickStart.md |
Description
Both files now display the updated security risk assessment table showing:
│ agent-wallet Med Risk 1 alert High Risk
The existing x402-payment row shows Safe / Med Risk and gets no additional explanation. The new agent-wallet row shows a High Risk (Snyk) rating, which is significantly more alarming. No explanation is provided about what the Snyk finding relates to, whether it is a false positive, a transitive dependency issue, or an accepted risk. Users who notice "High Risk" in the installation UI may abandon the installation or feel misled if they later read this documentation.
Recommendation
Add a brief note after the table explaining what the agent-wallet Snyk alert is:
:::info About the agent-wallet Snyk rating
The "High Risk" Snyk rating for agent-wallet is triggered by a transitive dependency
used only in development (e.g., a test runner or bundler). It does not affect the runtime
package. The BANK OF AI team has reviewed this finding and determined it poses no risk to
production use. See [issue #XXX](link) for details.
:::If the actual cause is unknown or unreviewed, this needs investigation before publishing.
[MN-03] Inconsistent Python Version Requirement: quickstart-for-sellers.md Section 3.1 Still Says Python 3.10+
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Correctness |
| File | docs/x402/getting-started/quickstart-for-sellers.md : Section 3.1 Prerequisites |
Description
Section 3.1 of the self-hosted Facilitator path begins with:
- **Python 3.10+** and **Git** (confirmed in the Prerequisites section above)
The top-level Prerequisites in quickstart-for-human.md was bumped to Python 3.11+, and the SUNCli/FAQ.md says "Node.js 20.0.0 or later." However quickstart-for-sellers.md section 3.1 still mentions 3.10+. If the Facilitator service itself requires 3.11+, this is a silent breakage; if 3.10 is genuinely supported for the Facilitator, then quickstart-for-human.md should clarify the context.
Recommendation
Align to a single Python minimum version throughout. If the Facilitator requires 3.11+, update the sellers guide to match. If 3.10 is valid for the Facilitator specifically, add a note clarifying the different requirements.
[MN-04] USDD Base Fee Value Missing Explanatory Comment in YAML Example
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | docs/x402/getting-started/quickstart-for-sellers.md : YAML config snippet |
Description
The YAML config for the self-hosted TRON Facilitator shows:
base_fee:
USDT: 100 # 0.0001 USDT per settlement (adjust as needed)
USDD: 100000000000000The USDT line has a helpful comment explaining the human-readable amount. The USDD line has no comment. Since USDD has 18 decimals on TRON (vs. 6 for USDT), 100000000000000 represents 0.0001 USDD, but this is non-obvious and may cause misconfiguration if users assume the values should be the same magnitude.
Recommendation
USDD: 100000000000000 # 0.0001 USDD per settlement (18 decimals — adjust as needed)[MN-05] SUNCli/CommandGuide.md tx scan Uses --offset Pagination, Inconsistent with All Other Commands
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md : Transaction section |
Description
Every listing command in CommandGuide.md (token list, pool list, farm list, position list, farm tx, etc.) uses --page <n> for pagination. The tx scan command uses --offset <offset> and --page-size <n> but has no --page parameter. This cursor-based pagination is likely intentional (the underlying API may use offsets), but the inconsistency is not explained and will confuse users who try --page 2 expecting the standard behavior.
Recommendation
Add a brief note in the tx scan description:
> Note: `tx scan` uses offset-based pagination (`--offset`) rather than
> the page-number pagination (`--page`) used by other commands.[MN-06] SUNCli/CommandGuide.md Built-In Token Symbol WIN Decimal Listed as 6 — Verify Accuracy
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Correctness |
| File | docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md : Built-In Token Symbols table |
Description
The built-in token table lists:
| `WIN` | `TLa2f6VPqDgRE67v1736s7bJ8Ray5wYjU7` | 6 |
The WIN token on TRON is widely documented as having 6 decimals, so this appears correct. However, it is worth double-checking against the live contract, as a wrong decimal causes incorrect amount calculations in swap commands. Other tokens like SUN, JST, BTT are correctly listed at 18 decimals. This warrants a quick on-chain verification before publishing.
Recommendation
Verify WIN decimals against https://tronscan.org/#/token20/TLa2f6VPqDgRE67v1736s7bJ8Ray5wYjU7. If confirmed as 6, no change needed. If incorrect, update the table.
Suggestions
[S-01] quickstart-for-agent.md — Clarify GasFree Account Activation Is Required Before First Use
File: docs/x402/getting-started/quickstart-for-agent.md
Description: The GasFree scheme is introduced in the x402 docs, and network-and-token-support.md mentions activation is required (--gasfree-activate). However, quickstart-for-agent.md introduces GasFreeAPIClient without telling agents they need to activate first.
Suggestion: Add a callout near the GasFree integration note: "Before your first GasFree payment, you must activate your GasFree account with --gasfree-activate."
[S-02] TRON MCP Server Docker Option Warns Against -e KEY=value But Should Also Warn Against Committing .env.docker
File: docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md : Option D Docker section
Description: The warning correctly tells users to use --env-file, but only says "add .env.docker to your .gitignore" in a tip. A stricter instruction would be to explicitly run echo '.env.docker' >> .gitignore as a command in the example.
Suggestion: Add the gitignore command inline with the setup steps:
echo '.env.docker' >> .gitignore[S-03] Consolidate Repeated TRON Fallback RPC Warning Into a Shared Admonition
File: docs/x402/getting-started/quickstart-for-agent.md, docs/x402/getting-started/quickstart-for-human.md, docs/x402/getting-started/quickstart-for-sellers.md
Description: The identical "Fallback RPC Endpoint" :::note block appears three times verbatim across three files. Any future change to the fallback URL or policy will require updates in all three places.
Suggestion: Consider extracting this into a Docusaurus shared MDX component or a :::note in a reusable include. At minimum, add a comment noting these are duplicates to be kept in sync.
[S-04] SUNCli/FAQ.md — Missing --json Output Format Caveat for AI Agent Integration
File: docs/McpServer-Skills/MCP/SUNCli/FAQ.md : AI Agent Integration section
Description: The FAQ recommends --json for machine-readable responses. However, it doesn't mention that some commands (e.g., wallet address) may still output error messages to stderr in human-readable form even when --json is set. AI agents parsing stdout may be surprised by stderr output mixing into their input stream.
Suggestion: Add a note: "Errors are written to stderr in human-readable form regardless of --output setting. Capture stderr separately or check the exit code before parsing stdout."
[S-05] BANKOFAISkill.md — multisig Proposal Expiry Hardcoded "24 hours" Should Reference Config
File: docs/McpServer-Skills/SKILLS/BANKOFAISkill.md : multisig section
Description: The new content states "Proposals expire after 24 hours by default." If this is a configurable default, document the configuration parameter. If it's hardcoded in the skill, note that explicitly.
Suggestion: Link to or reference the relevant configuration file or skill setting, or add "(hardcoded, cannot be changed)" if it's not configurable.
Positive Observations
| Area | Observation |
|---|---|
| Security — Docker | The Docker deployment guide correctly instructs users to use --env-file instead of -e KEY=value flags to avoid leaking secrets into shell history and docker inspect. |
| Breaking change UX | The v1.1.7 migration is announced at the top of both Intro.md and QuickStart.md for TRON MCP Server with a :::warning admonition — users who update packages will immediately see the migration path. |
| GasFree disclosure | The docs proactively disclose that BANK OF AI operates a fallback RPC proxy and explain its SLA limitations, giving users the information they need to decide whether to supply their own API key. |
| Facilitator rate limits | The new rate limiting table for the Facilitator /settle endpoint (1000 req/min authenticated vs 1 req/min anonymous) is clear and actionable, helping sellers plan their API key needs. |
| Dry-run promotion | --dry-run is prominently featured in the SUNCli docs and Security Notes, reducing the risk of users accidentally executing write operations. |
| Testnet-first guidance | Every write-operation example in the new SUNCli docs includes a network flag (--network nile) and an explicit tip recommending testnet validation before mainnet — good practice for financial tooling. |
| Link anchor fixes | Several ../../../Agent-Wallet/FAQ and similar links missing .md extensions were corrected to ../../../Agent-Wallet/FAQ.md, improving cross-reference reliability. |
| Windows support | The Agent Wallet FAQ now explicitly documents Windows support (v2.3.x+) with notes about graceful handling of chmod 600 on Windows — preventing user confusion when running on non-Unix systems. |
Checklist Results
| Category | Items Checked | Pass | Fail | N/A | Notes |
|---|---|---|---|---|---|
| Correctness | 8 | 6 | 2 | 0 | Node.js 18/20 mismatch; Python 3.10/3.11 mismatch |
| Security | 5 | 3 | 2 | 0 | Missing plaintext key warnings; agent-wallet High Risk unexplained |
| Performance | 0 | 0 | 0 | 8 | Not applicable (docs only) |
| Code Quality | 4 | 3 | 1 | 0 | Inconsistent pagination pattern in CommandGuide |
| Testing | 0 | 0 | 0 | 6 | No test files changed |
| Documentation | 10 | 7 | 3 | 0 | Broken anchors; repo change unexplained; USDD comment missing |
| Compatibility | 3 | 2 | 1 | 0 | Self-hosted Facilitator breaks existing users without migration note |
| Observability | 1 | 1 | 0 | 0 | Logging/startup output examples updated for new Facilitator |
Disclaimer
This is an automated code review. It supplements but does not replace human review. The reviewer analyzed only the diff between the specified branches. Runtime behavior, integration testing, and deployment impact are not covered. All findings are based on static analysis of documentation content.
Report generated by Code Review Skill v1.0.0
Date: 2026-04-10
Code Review ReportProject: BofAI / docs PR OverviewBranch Information
Commit History
Review SummaryVerdict
Findings at a Glance
SummaryThis PR is a documentation-only update — no executable code, smart contracts, or server logic changed. It introduces four new SUN CLI documentation pages, expands Agent Wallet docs with Privy wallet support and new CLI commands, migrates all MCP server wallet configuration from the legacy The overall documentation quality is high — security warnings are prominent, testnet-first guidance is consistent, and sensitive-data handling is thoroughly covered. However, four major defects were found: a Node.js minimum version inconsistency that will cause runtime failures for users who follow the FAQ; an HTTP server flag inconsistency that will prevent connections; a large block of duplicated content in Change Summary1. New SUN CLI Documentation (4 new files + zh-Hans mirrors)
Purpose: Introduces a new CLI product ( 2. Agent Wallet CLI & SDK Updates
Purpose: Documents v2.3.x Agent Wallet release which adds Privy-managed server wallets, Windows support, and new administrative CLI commands. 3. TRON MCP Server & SUN MCP Server Wallet Migration
Purpose: Removes plaintext private-key environment variable support (as of v1.1.7) and migrates all wallet management to the encrypted Agent Wallet system. 4. x402 Protocol Documentation Expansion
Purpose: Documents the new 5. Skills & Navigation
Detailed FindingsMajor[MJ-01] Node.js Minimum Version Inconsistency in SUN MCP Server FAQ
Description
Code 1. **Check Node.js Installation**
```bash
node --version # Should return v18+
npm --versionRecommendation
# In docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md, "Connection Refused in HTTP Mode"
sun-mcp-server --transport streamable-http --host 127.0.0.1 --port 8080 --mcpPath /mcp
[MJ-03] Duplicated Deployment Steps in SUN MCP Server LocalPrivatizedDeployment.md
Description
Code ### Step 2: Local Private Deployment
#### Option A: Run directly with npx (Recommended)
...
npx -y @bankofai/sun-mcp-server
...
#### Option B: Clone from Source
...
git clone https://github.com/BofAI/sun-mcp-server.git
...
### Step 3: Server Running Methods ← identical content repeated below
### Option A: Run directly with npx (Recommended)
...
npx -y @bankofai/sun-mcp-server ← exact same block
...
### Option B: Clone from Source ← exact same block
...
git clone https://github.com/BofAI/sun-mcp-server.git
...Recommendation
[MJ-04] Wrong Expected Output in Deployment Verification Step
Description
Code #### Query Test
Try the following command in chat:
Check the current prices of USDT and TRX on SunSwap Recommendation #### Query Test
Try the following command in chat:
Check the current prices of USDT and TRX on SunSwap Minor[MN-01] Inconsistent Nile Testnet Faucet URLs
Description
Recommendation
[MN-02] Misleading USDD
|
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | docs/x402/getting-started/quickstart-for-sellers.md : Lines 500–502 |
Description
In the YAML config example for the self-hosted Facilitator (TRON tab), the comment
# 0.0001 USDT per settlementis incorrectly placed next to theUSDDfield. USDD uses 18 decimals on TRON, so the value100000000000000(10^14) does equal 0.0001 USDD — but the comment says "USDT", not "USDD". This copy-paste error will confuse operators who try to set a matching fee for both USDT and USDD, as USDT uses only 6 decimals. SettingUSDT: 100(= 0.0001 USDT) andUSDD: 100(= 0.0000000000001 USDD) would result in a near-zero USDD fee that was clearly not intended.
Code
base_fee:
USDT: 100 # 0.0001 USDT per settlement (adjust as needed)
USDD: 100000000000000 # ← comment says "0.0001 USDT" but this is USDDRecommendation
base_fee:
USDT: 100 # 0.0001 USDT per settlement (6 decimals; adjust as needed)
USDD: 100000000000000 # 0.0001 USDD per settlement (18 decimals; adjust as needed)[MN-03] Private Key Persisted to Shell Profile Without Plaintext Storage Warning
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Security |
| File | docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md : Lines 96–107 (same block in SUNMCPServer/LocalPrivatizedDeployment.md : Lines 92–107) |
Description
The tip advising users to persist
AGENT_WALLET_PRIVATE_KEYin~/.zshrcor~/.bashrcdoes not warn that these files store the private key as plaintext and are commonly included in cloud backup services (iCloud Drive syncing~/.zshrcon macOS, Dropbox or OneDrive home folder syncs on Linux/Windows). A user who does not know this may inadvertently back up or sync their private key to a third-party cloud service. The docs correctly warn about shell history (via the:::caution Shell history riskadmonition elsewhere), but no equivalent warning appears in this:::tipblock.
Code
:::tip
To make this persist across terminal sessions, add it to your shell configuration file:
```bash
echo 'export AGENT_WALLET_PRIVATE_KEY=your_private_key' >> ~/.zshrc # zsh (macOS default)
echo 'export AGENT_WALLET_PRIVATE_KEY=your_private_key' >> ~/.bashrc # bash (Linux default):::
**Recommendation**
```markdown
:::tip
To make this persist across terminal sessions, add it to your shell configuration file:
```bash
echo 'export AGENT_WALLET_PRIVATE_KEY=your_private_key' >> ~/.zshrc # zsh (macOS default)
echo 'export AGENT_WALLET_PRIVATE_KEY=your_private_key' >> ~/.bashrc # bash (Linux default)
⚠️ ~/.zshrcand~/.bashrcstore this value as plaintext. If your home directory is synced to a cloud service (e.g., iCloud, Dropbox, OneDrive), the private key will be uploaded. Consider using a secrets manager or encrypted keystore (Agent Wallet'slocal_securemode) for wallets holding real funds.
:::
---
#### [MN-04] GasFree Management Commands Reference Developer-Internal Paths
| Property | Value |
|----------|-------|
| **Severity** | Minor |
| **Category** | Documentation |
| **File** | `docs/x402/core-concepts/network-and-token-support.md` : Lines 133–145 |
**Description**
> The GasFree account management examples under the `exact_gasfree` scheme documentation use `npx tsx x402-payment/src/x402_invoke.ts` — a path that refers to a TypeScript source file within the `x402-payment` local directory. This is a developer-local repository path that will not work for end users who have only installed the SDK via `pip`. A user reading this documentation will run the commands and receive a "Cannot find module" or "file not found" error, as the directory `x402-payment/src/` does not exist in their environment. Either a published CLI entrypoint should be used, or the examples should include a prerequisite note to clone the repo first.
**Code**
```bash
# Query GasFree wallet info
npx tsx x402-payment/src/x402_invoke.ts --gasfree-info
# Activate a GasFree account
npx tsx x402-payment/src/x402_invoke.ts --gasfree-activate
Recommendation
Either:
- Replace with a published CLI command (e.g.,
x402-payment --gasfree-infoorpython -m bankofai.x402.gasfree --info) if one exists, or- Add a prerequisite block before the examples:
# First, clone the x402 repository and navigate to the skill directory: git clone https://github.com/BofAI/x402.git cd x402/x402-payment npm install # Then run: npx tsx src/x402_invoke.ts --gasfree-info
Suggestions
[S-01] Missing Step-by-Step Migration Guide for Legacy TRON_PRIVATE_KEY Users
File: docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md, TRONMCPServer/LocalPrivatizedDeployment.md
Description: The PR removes support for TRON_PRIVATE_KEY and TRON_MNEMONIC and replaces them with Agent Wallet. There are :::caution admonitions noting the removal, but no step-by-step migration guide for existing users who have the legacy variables configured. Users with production deployments may face sudden auth failures after upgrading and will not know how to recover.
Suggestion: Add a dedicated migration section (or link to one) that walks users through: (1) exporting the existing private key from the old env var, (2) running agent-wallet start to create an encrypted keystore, (3) unsetting the legacy variables, and (4) restarting the server.
[S-02] agent-wallet resolve-address Output Format Not Documented for Private-Key Wallets
File: docs/Agent-Wallet/Developer/CLI-Reference.md : Lines 167–189
Description: The resolve-address command documentation includes a sample output for a mnemonic-derived wallet (showing both EVM and TRON addresses). However, the text says "For private-key-based wallets, it shows the single address for the configured network" without providing a sample output. An example output for both wallet types would make the documentation complete.
Suggestion: Add a second output example for a raw_secret or imported private-key wallet showing only a single address entry.
[S-03] No .gitignore Reminder for config/facilitator.config.yaml
File: docs/x402/getting-started/quickstart-for-sellers.md : Lines 482–519
Description: The self-hosted Facilitator setup instructs users to copy facilitator.config.example.yaml to facilitator.config.yaml and fill in the database connection string, which may include the database password. The guide warns about protecting the private key env var but does not remind users to add config/facilitator.config.yaml to .gitignore to prevent accidentally committing the database credentials.
Suggestion: Add a reminder after the config copy step:
echo "config/facilitator.config.yaml" >> .gitignorePositive Observations
| Area | Observation |
|---|---|
| Security warnings | :::danger admonitions are consistently and prominently used for raw_secret key warnings, shell history risks for -p flag usage, and Docker --env-file best practices. |
| Testnet-first guidance | Every write-operation example includes a reminder to test on Nile first before using mainnet, reducing the risk of accidental fund loss. |
| Legacy deprecation communication | The removal of TRON_PRIVATE_KEY/TRON_MNEMONIC is clearly communicated with :::caution Legacy wallet options removed blocks in all affected files. |
| Comprehensive CLI reference | The new SUN CLI CommandGuide.md covers all command categories exhaustively with flag tables, defaults, and examples — setting a high documentation standard. |
| CI/CD example | The GitHub Actions example in CLI-Reference.md correctly uses repository secrets rather than hardcoded passwords — a good security practice. |
| Docker security | The Docker deployment section correctly warns against -e KEY=value on the command line and prescribes --env-file with a .gitignore entry. |
| Trust model clarity | The x402 facilitator.md trust model section clearly explains what even a malicious Facilitator cannot do, which is valuable for user trust. |
| Bilingual parity | All English content changes are consistently mirrored to i18n/zh-Hans/, ensuring non-English users are not left with outdated documentation. |
Checklist Results
| Category | Items Checked | Pass | Fail | N/A | Notes |
|---|---|---|---|---|---|
| Correctness | 8 | 5 | 3 | 0 | Node.js version (MJ-01), HTTP flag (MJ-02), wrong expected output (MJ-04) |
| Security | 5 | 4 | 1 | 0 | Plaintext ~/.zshrc storage not warned (MN-03) |
| Performance | 3 | 3 | 0 | 0 | N/A for documentation |
| Code Quality | 6 | 5 | 1 | 0 | Duplicated deployment steps (MJ-03) |
| Testing | 4 | 3 | 0 | 1 | No executable code changed |
| Documentation | 7 | 5 | 2 | 0 | USDD comment (MN-02), GasFree paths (MN-04) |
| Compatibility | 3 | 2 | 0 | 1 | Legacy migration noted |
| Observability | 2 | 2 | 0 | 0 | — |
Disclaimer
This is an automated code review. It supplements but does not replace human review. The reviewer analyzed only the diff between the specified branches. Runtime behavior, integration testing, and deployment impact are not covered. This PR is documentation-only — all findings relate to accuracy, consistency, and usability of the documentation content.
Report generated by Code Review Skill v1.0.0
Date: 2026-04-10
Code Review ReportProject: BofAI Docs ( PR OverviewBranch Information
Commit History
Review SummaryVerdict
Findings at a Glance
SummaryThis PR is a documentation-only release that introduces four major functional additions: (1) a completely new SUN CLI section (4 new files, ~1,720 lines), (2) TRON and SUN MCP Server v1.1.7 migration from legacy The overall content quality is high — the SUN CLI reference is comprehensive, the MCP migration path is clearly motivated, and the security cautions on Change Summary1. New SUN CLI Documentation (4 new files)
Purpose: Introduce the 2. TRON MCP Server v1.1.7 Breaking-Change Migration
Purpose: Document that 3. SUN MCP Server: Same Agent Wallet Migration
Purpose: Mirror TRON MCP Server's wallet migration in the SUN MCP Server docs. 4. Agent Wallet Enhancements
Purpose: Document Privy wallet support, new CLI subcommands, Node.js 20 requirement, and Windows support. 5. x402 Payment Updates
6. Skills Ecosystem Updates
7. Configuration Files
Detailed FindingsMajor[MJ-01] Plaintext Private Key Persisted to Shell Profile Presented Without Adequate Security Warning
Description The new "Option B / Path 2: Import an Existing Private Key" and x402 Step 1 sections across multiple files instruct users to persist their plaintext private key directly into their shell profile file ( echo 'export AGENT_WALLET_PRIVATE_KEY=your_private_key' >> ~/.zshrc # zsh (macOS default)
echo 'export AGENT_WALLET_PRIVATE_KEY=your_private_key' >> ~/.bashrc # bash (Linux default)
source ~/.zshrcIn the old documentation, the equivalent approach ( Writing the private key into
The removal of the security warning is a documentation regression, especially since the PR's headline security benefit is migrating away from plaintext key exposure. Code # TRONMCPServer/LocalPrivatizedDeployment.md (Path 2) and x402 quickstarts:
echo 'export AGENT_WALLET_PRIVATE_KEY=your_private_key' >> ~/.zshrc # zsh (macOS default)
echo 'export AGENT_WALLET_PRIVATE_KEY=your_private_key' >> ~/.bashrc # bash (Linux default)
source ~/.zshrc # or source ~/.bashrc — takes effect immediately without restarting the terminalRecommendation Restore a :::caution Security risk: plaintext key in shell profile
Writing your private key to `~/.zshrc` stores it as plaintext on disk and in
any backup, dotfile repo, or sync tool that touches your home directory. It
is also visible via `ps aux` and environment inspection tools. This method
is **lower security** than using Agent Wallet's encrypted keystore (Option A
/ Path 1). If you use this path:
- Never commit your shell profile to a public repository
- Keep the wallet funded with only the minimum tokens required for your task
- For production workloads, use the encrypted wallet approach instead
:::[MJ-02] Breaking Change Migration Warning is Inconsistent Across Affected Servers
Description The removal of However, the SUN MCP Server documentation has no equivalent top-level upgrade banner. The only mention is a Code # TRONMCPServer/Intro.md — good, prominent warning:
+:::warning Upgrading from v1.1.6 or earlier?
+As of **v1.1.7**, the `TRON_PRIVATE_KEY` and `TRON_MNEMONIC` environment variables
+are no longer supported...
+:::
# SUNMCPServer/LocalPrivatizedDeployment.md — only a buried caution block:
+:::caution Legacy wallet options removed
+The legacy `TRON_PRIVATE_KEY` and `TRON_MNEMONIC` environment variables are no
+longer supported. All wallet management is now handled through Agent Wallet...
+:::Recommendation Add the same Minor[MN-01]
|
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Security |
| File | docs/x402/getting-started/quickstart-for-agent.md : ~line 100; docs/x402/getting-started/quickstart-for-human.md : ~line 215; docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md : ~line 100; docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md : ~line 100 |
Description
Multiple guides use the following as a "success check":
echo $AGENT_WALLET_PRIVATE_KEYPrinting a private key to the terminal is problematic because:
- Terminal output is captured in CI/CD logs (GitHub Actions, Jenkins, etc.)
- Shell history records the command and output in some terminals
- Screen sharing or screenshots during onboarding will expose the key
- Some terminal multiplexers (tmux, screen) log session buffers
Recommendation
Replace with a non-revealing check that confirms the variable is set but does not print the value:
# Verify the variable is set (without printing the value)
[[ -n "$AGENT_WALLET_PRIVATE_KEY" ]] && echo "✅ AGENT_WALLET_PRIVATE_KEY is set" || echo "❌ Not set"This pattern is already used in the TRON MCP Server FAQ ([[ -n "$AGENT_WALLET_PASSWORD" ]] && echo "Password is set"), so it's consistent with existing documentation.
[MN-02] Python Version Inconsistency (3.10+ vs 3.11+)
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation / Correctness |
| File | docs/x402/getting-started/quickstart-for-human.md : line 27; docs/x402/getting-started/quickstart-for-sellers.md (unchanged) |
Description
quickstart-for-human.md was updated to require Python 3.11+, but quickstart-for-sellers.md still references Python 3.10+ in its prerequisites section, and the new self-hosted Facilitator section (added in this PR) also mentions Python 3.10+:
# quickstart-for-human.md (changed):
- [ ] **Python 3.10+** or **Node.js 18+** installed
+ [ ] **Python 3.11+** or **Node.js 18+** installed
# quickstart-for-sellers.md (self-hosted section, added in this PR — unchanged at 3.10+):
Before starting, make sure you have:
- **Python 3.10+** and **Git**A user who runs the seller's self-hosted Facilitator on Python 3.10 but tries to follow the client quickstart may encounter confusing errors, or the reverse.
Recommendation
Align all x402 Python references to the same version. Determine the actual minimum required version, then update quickstart-for-sellers.md (and the new self-hosted facilitator section) to match quickstart-for-human.md.
[MN-03] TRON MCP Server Tool Count Increased (95 → 97) Without New Tools Listed
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation / Correctness |
| File | docs/McpServer-Skills/MCP/TRONMCPServer/ToolList.md |
Description
TRONMCPServer/Intro.md, ToolList.md, OfficialServerAccess.md, and QuickStart.md all update the tool count from 95 to 97. However, the actual tool table in ToolList.md was not updated with 2 new tool entries — the diff only shows the header being changed and two link fixes (.md extension added). A user who reads "97 tools" and then counts the table will find a mismatch.
Code
# ToolList.md header changed:
-TRON MCP Server provides **95 tools**...
+TRON MCP Server provides **97 tools**...
# But no new tool rows were added to the table below.Recommendation
Either add the 2 new tool entries to the tool table with their descriptions and parameters, or revert the count to 95 until the actual entries are documented. If the 2 new tools are list_wallets and select_wallet (which already existed), verify the accurate count before publishing.
[MN-04] agent-wallet Skill Shows "High Risk" (Snyk) Without Explanation
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation / Security |
| File | docs/McpServer-Skills/SKILLS/QuickStart.md : ~line 100; docs/Openclaw-extension/QuickStart.md : ~line 320 |
Description
Both the Skills QuickStart and Openclaw QuickStart now display a security risk assessment table where the new agent-wallet skill is rated High Risk by Snyk:
│ agent-wallet Med Risk 1 alert High Risk │
All other skills are rated at most "Med Risk." The documentation does not explain what "High Risk" means, why it applies to agent-wallet, or what users should know before accepting this risk. Users who do not understand the security scanning context may either blindly proceed or be unnecessarily alarmed without guidance.
Recommendation
Add a brief contextual note near the security table explaining the risk rating. For example:
:::info Understanding the security assessment
The `agent-wallet` skill is rated "High Risk" by Snyk due to its use of
cryptographic and key management libraries (a common flag for security-sensitive
packages). This does not indicate a known vulnerability — it reflects that the
package handles private key material. Review the [agent-wallet source](https://github.com/BofAI/agent-wallet)
if you require independent verification.
:::[MN-05] TRX Token Address in Built-In Token Symbol List May Be Incorrect
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation / Correctness |
| File | docs/McpServer-Skills/MCP/SUNCli/CommandGuide.md : ~line 1150 |
Description
The built-in token symbol table lists TRX as having address T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb:
| `TRX` | `T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb` | 6 |
TRX is the native coin of TRON — it does not have a TRC-20 contract address. This address (T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb) is typically associated with a system or wrapped contract for TRX representation in DEX contexts. This discrepancy could confuse users who verify the address against TRON explorers (where TRX won't appear as a standard TRC-20 contract).
Recommendation
Add a footnote or explanation clarifying that TRX's address entry is the DEX-internal representation used by SunSwap (e.g., the energy/bandwidth sentinel address), not a TRC-20 contract. The existing note about WTRX (TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR) helps, but users may not understand the relationship between TRX and WTRX in V3/V4 pools.
[MN-06] Non-Interactive change-password Example Exposes Passwords to Shell History Without Platform-Specific Guidance
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Security / Documentation |
| File | docs/Agent-Wallet/Developer/CLI-Reference.md : ~line 130 |
Description
The new non-interactive change-password example is:
agent-wallet change-password -p 'OldPassword123!' --new-password 'NewPassword456!'The :::caution block correctly warns that "Both -p and --new-password will be recorded in shell history." However, it does not address:
- macOS/Linux:
HISTCONTROL=ignorespaceprefix (leading space suppresses history) - Shell-history-exclusion patterns (
HISTIGNORE) - Piping from a password manager (e.g.,
pass,1password)
Recommendation
Augment the caution to include the most practical workaround:
:::caution
Both `-p` and `--new-password` will appear in shell history. For non-interactive use
**without** exposing passwords in history, prefix the command with a space (suppresses
history entry in bash/zsh with `HISTCONTROL=ignorespace`), or pipe from a secrets
manager. For production use, interactive mode is always preferred.
:::Suggestions
[S-01] No .env File Pattern Documented for x402 Private Key Setup
File: docs/x402/getting-started/quickstart-for-agent.md, docs/x402/getting-started/quickstart-for-human.md
Description: The previous documentation recommended creating a .env file and adding it to .gitignore as a project-scoped alternative to exporting to the global shell profile. This pattern (scoped, revocable, repo-specific) is safer than a global shell export for development use and is standard in Node.js and Python projects. The new documentation only covers the global export approach and the encrypted wallet approach, leaving a gap for developers working within a project context.
Suggestion: Restore the .env/.gitignore pattern as a named option (e.g., alongside the shell profile export), with a note that the .env file must be in .gitignore.
[S-02] Self-Hosted Facilitator Setup Is Significantly Expanded — Consider Standalone Guide
File: docs/x402/getting-started/quickstart-for-sellers.md
Description: The self-hosted Facilitator section has grown substantially (from ~20 lines to ~220 lines), covering PostgreSQL installation across 4 OS variants, database configuration, password authentication setup, and a new git repository (x402-facilitator). This is now significantly heavier than the rest of the "Quick Start for Sellers" page and may overwhelm users who only want the hosted path.
Suggestion: Consider extracting the self-hosted Facilitator setup into a dedicated page (e.g., quickstart-for-selfhosted-facilitator.md) and replacing the current inline content with a brief summary and a link. This keeps the seller quickstart focused on the most common path.
[S-03] i18n/current/ Files Are Not Verified Against docs/ Changes
File: All i18n/current/** files (30 files changed)
Description: Every changed doc in docs/ has a corresponding change in i18n/current/. The files appear to be near-identical copies. There is no automated check in this PR that the i18n copies are in sync with the source. For example, if a security fix is applied to docs/x402/getting-started/quickstart-for-agent.md post-merge but the i18n copy is forgotten, users viewing the versioned docs would see outdated guidance.
Suggestion: Document or implement a CI step (e.g., a diff check or sync script) to ensure i18n/current/ files stay in sync with docs/. Alternatively, document that i18n/current/ is auto-generated and explain how/when it is updated.
Positive Observations
| Area | Observation |
|---|---|
| Breaking change notices | TRON MCP Server Intro.md and QuickStart.md both have prominent top-of-page :::warning banners for v1.1.7 migration — well-placed and actionable. |
| Security improvement: removed insecure env vars | Eliminating TRON_PRIVATE_KEY and TRON_MNEMONIC as first-class wallet options is a genuine security improvement. The encrypted Agent Wallet approach is better. |
Docker --env-file pattern |
The new Docker deployment section explicitly warns against -e KEY=value and mandates --env-file, with a note to add the file to .gitignore. This is a best-practice pattern correctly documented. |
| SUN CLI global flag security caution | CommandGuide.md includes a :::caution Private Key Security block warning about -k/--private-key appearing in shell history and process listings, recommending env vars or agent-wallet instead. |
FastAPI Request import fix |
Both TRON and BSC Python server examples in quickstart-for-sellers.md correctly add from fastapi import FastAPI, Request — this fixes a real runtime error in the existing sample code. |
| Dry-run and testnet-first culture | Multiple new pages (SUN CLI Intro, FAQ, QuickStart) consistently emphasize testnet-first and --dry-run for write operations. |
exact_gasfree scheme documentation |
The zero-gas payment scheme is well-explained with key characteristics, activation steps, and correct notes about GasFree API routing through the BANK OF AI proxy. |
Non-interactive mode for change-password |
Adding the non-interactive flags and the associated caution block is a useful addition for CI pipelines. |
agent-wallet skill caution block |
The skill overview correctly flags that remove, reset, and change-password are agent-restricted (terminal-only), preventing accidental key deletion by the AI. |
| Tool mode labels (read/write) in SUN CLI | Every SUN CLI command entry consistently labels operations as (read) or (write) — greatly improves scannability for security-conscious users. |
Checklist Results
| Category | Items Checked | Pass | Fail | N/A | Notes |
|---|---|---|---|---|---|
| Correctness | 5 | 3 | 2 | — | Python version inconsistency; tool count mismatch |
| Security | 6 | 4 | 2 | — | Plaintext key in shell profile; echo of private key |
| Performance | 3 | — | — | 3 | Not applicable (docs-only PR) |
| Code Quality | 5 | 4 | 1 | — | Shell history exposure underdocumented |
| Testing | 2 | — | — | 2 | Not applicable (docs-only PR) |
| Documentation | 6 | 4 | 2 | — | Inconsistent migration banners; missing risk rating explanation |
| Compatibility | 3 | 2 | 1 | — | Breaking change banners missing in SUN MCP Server entry points |
| Observability | 2 | — | — | 2 | Not applicable (docs-only PR) |
Disclaimer
This is an automated code review. It supplements but does not replace human review. The reviewer analyzed only the diff between the specified branches. Runtime behavior, integration testing, and deployment impact are not covered. This PR contains exclusively documentation (.md) and configuration (package.json, sidebars.js) changes — no executable code was introduced.
Report generated by Code Review Skill v1.0.0
Date: 2026-04-10
Code Review ReportProject: x402-tron/docs PR OverviewBranch Information
Commit History (recent)
Review SummaryVerdict
Findings at a Glance
SummaryThis PR is a large, documentation-only release that introduces a new SUN CLI tool section (4 new files, ~1,267 lines), migrates all wallet configuration guidance from legacy plaintext modes ( The documentation is comprehensive, well-structured, and shows strong security intent in consolidating around encrypted Agent Wallet storage over plaintext private keys. However, three Major issues warrant changes before merge: a regression in security guidance where the plaintext private key warning was silently dropped from the key import path, an invocation path in the GasFree examples that will not work for skill-installed users, and a minor inconsistency where some docs still reference Node.js 18+ after the project-wide bump to 20. The parallel Change Summary1. New SUN CLI Documentation (4 new files)
Purpose: Introduce 2. MCP Server Wallet Mode Consolidation
Purpose: Enforce Agent Wallet as the sole supported wallet mechanism as of v1.1.7, removing the legacy plaintext private key and mnemonic options. 3. Agent Wallet Documentation Updates
Purpose: Document new Agent Wallet features: Privy custody wallet type, 4. x402 Documentation Updates
Purpose: Document 5. Skills & Sidebar Updates
Purpose: Introduce the Detailed FindingsMajor[MJ-01] Security Regression: Private Key Warning Silently Removed from Key Import Path
Description In the old documentation, "Option 2: Private Key" and "Option 3: Mnemonic Phrase" were clearly marked with export AGENT_WALLET_PRIVATE_KEY=your_private_key_hereand even recommends persisting it via: echo 'export AGENT_WALLET_PRIVATE_KEY=your_private_key' >> ~/.zshrcThe second command writes the raw private key into shell history and into the shell profile file — the same attack surface the old warnings described. The This is a regression: users migrating from the old docs (which explicitly warned about this) will no longer receive that guidance, and new users will find no warning at all. Code (new path, no warning): # Path 2: Import an Existing Private Key
export AGENT_WALLET_PRIVATE_KEY=your_private_key_here
:::tip
To make this persist across terminal sessions, add it to your shell configuration file:
echo 'export AGENT_WALLET_PRIVATE_KEY=your_private_key' >> ~/.zshrc
echo 'export AGENT_WALLET_PRIVATE_KEY=your_private_key' >> ~/.bashrcRecommendation Replace the :::warning Security Risk
Storing your private key as a plaintext environment variable carries real risks:
- The `echo 'export ...'` command above records your key in shell history (`~/.zsh_history`, `~/.bash_history`)
- The key is stored in plaintext in `~/.zshrc` or `~/.bashrc` — any process with filesystem access can read it
- Environment variables can be leaked via process listings (`ps aux`) or log files
**Only keep small amounts of funds in wallets configured this way.**
For wallets holding significant funds, use `agent-wallet start` (Path 1) to generate a fully encrypted keystore instead.
:::Also add a brief caution to the SUN CLI FAQ under "I get 'No wallet configured'". [MJ-02] GasFree CLI Examples Reference Unreachable Source File Path
Description The new npx tsx x402-payment/src/x402_invoke.ts --gasfree-info
npx tsx x402-payment/src/x402_invoke.ts --gasfree-activateThis invocation path ( Furthermore, these commands require Code: # Query GasFree wallet info
npx tsx x402-payment/src/x402_invoke.ts --gasfree-info
npx tsx x402-payment/src/x402_invoke.ts --gasfree-info --network nile
npx tsx x402-payment/src/x402_invoke.ts --gasfree-activateRecommendation Either:
[MJ-03] Node.js Version Requirement Inconsistency Across Docs
Description This PR updates the Node.js minimum requirement from 18 to 20 across
This creates a direct contradiction within the same page and across the documentation suite. Users who check Code: ### Checklist Before You Start
- [ ] **Python 3.11+** or **Node.js 18+** installed (depending on your chosen language)Recommendation Update the checklist line in - [ ] **Python 3.11+** or **Node.js 20+** installed (depending on your chosen language)Also audit Minor[MN-01]
|
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | docs/McpServer-Skills/SKILLS/QuickStart.md : Lines 94-107 (security risk table) and docs/Openclaw-extension/QuickStart.md : matching section |
Description
The updated security risk assessment table now shows agent-wallet with a High Risk Snyk score and Med Risk Gen score — the highest risk rating of any skill listed. The prior highest was x402-payment at Med Risk Snyk. The docs show these ratings as-is with no explanation of what they mean or why they are considered acceptable to install. Users who understand security scanners will be rightfully alarmed at "High Risk" for a wallet management tool and may refuse to install it, defeating the purpose of the PR. Users who don't understand security scanners will blindly install it without informed consent.
Code:
│ agent-wallet Med Risk 1 alert High Risk │
Recommendation
Add a callout below the risk table explaining the scoring methodology and why the agent-wallet package receives a High Risk Snyk score (likely flagged due to cryptographic dependencies or key management scope):
:::info About Security Risk Scores
The ratings above come from automated static analysis tools (Snyk, Socket.dev). A "High Risk" Snyk score for `agent-wallet` does not indicate malware — it reflects the tool's use of cryptographic libraries for private key management, which static analyzers flag as sensitive. The BANK OF AI team reviews all skill code before publishing. You can inspect the source at [github.com/BofAI/skills](https://github.com/BofAI/skills).
:::[MN-02] Ambiguity in Agent Wallet Environment Variable for MCP Server Runtime
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Correctness / Documentation |
| File | docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md and docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md |
Description
The new deployment docs establish two separate flows:
- Path 1 (new wallet): Run
agent-wallet start. No additional env vars needed — Agent Wallet manages the keystore. - Path 2 (import key): Set
AGENT_WALLET_PRIVATE_KEY=...
However, in Step 2 (Configure API Key) and throughout the FAQ, the docs consistently refer to AGENT_WALLET_PASSWORD as the env var for the MCP server to use. For users on Path 2 (using AGENT_WALLET_PRIVATE_KEY), it's unclear:
- Do they also need to set
AGENT_WALLET_PASSWORD? - Does
AGENT_WALLET_PRIVATE_KEYbypass the password requirement entirely? - Is
AGENT_WALLET_PRIVATE_KEYa runtime env var for the MCP server, or only for theagent-walletCLI during initial import?
This ambiguity could leave Path 2 users unable to start the MCP server or unsure whether their setup is correct.
Recommendation
Add a consolidating note in the Step 3 (Local Private Deployment) section that explicitly maps each path to its runtime environment variable:
**Runtime environment variable summary:**
| Setup Path | Runtime Env Var for MCP Server |
|------------|-------------------------------|
| Path 1: New wallet via `agent-wallet start` | `AGENT_WALLET_PASSWORD=<your-master-password>` |
| Path 2: Imported via `AGENT_WALLET_PRIVATE_KEY` | `AGENT_WALLET_PRIVATE_KEY=<your-private-key>` (no password needed) |[MN-03] Docker Option D Omits .gitignore Instruction for .env.docker
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Security / Documentation |
| File | docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md : Lines 175-205 (Option D Docker) |
Description
The Docker deployment example correctly instructs users to use --env-file .env.docker instead of -e KEY=value to avoid leaking keys in shell history and docker inspect. The warning block says "add .env.docker to your .gitignore" but does not show the actual command to do so. Users new to Docker or Git may miss this step, leading to accidental commits of secrets.
Code:
cat > .env.docker << 'EOF'
TRONGRID_API_KEY=your-key-here
EOF(No .gitignore update shown)
Recommendation
Add the .gitignore step explicitly in the code block sequence:
# 1. Create a .env file for sensitive variables
cat > .env.docker << 'EOF'
TRONGRID_API_KEY=your-key-here
EOF
# 2. Exclude it from version control
echo ".env.docker" >> .gitignore
# 3. Build and run...[MN-04] SUN CLI liquidity v4:mint Missing Default for --fee Flag
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | docs/McpServer-Skills/Tools/SUNCli/CommandGuide.md : liquidity v4:mint section |
Description
In the liquidity v3:mint command, the --fee flag has a documented default of 3000. In the liquidity v4:mint command, --fee is listed as optional but no default value is shown. It is unclear whether V4 uses the same default or requires explicit specification. Users attempting to mint a V4 position without --fee may get an unexpected error or unexpected behavior.
Code:
| `--fee <n>` | Pool fee tier | — | ← v4:mint (no default)
| `--fee <n>` | Pool fee tier | `3000` | ← v3:mint (has default)Recommendation
Either document the actual default for V4 --fee if one exists, or add a note clarifying that this parameter is required for V4 if no default applies:
| `--fee <n>` | Pool fee tier | `3000` (or mark as required) |[MN-05] Privy Wallet Type Documentation is Incomplete for Production Use
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | docs/Agent-Wallet/FAQ.md, docs/Agent-Wallet/Developer/CLI-Reference.md |
Description
The new Privy wallet type is introduced across several documents but only as tip boxes. For a wallet type that delegates private key custody to a third-party cloud service, users need to understand:
- What data is sent to Privy's servers (signing requests include transaction data)
- What happens if Privy is unavailable (signing operations fail)
- How to migrate from Privy to a local wallet
- Whether Privy wallets are compatible with all operations (e.g., does
list_walletswork?)
Without this information, users cannot make an informed decision about adopting Privy custody for production workloads.
Recommendation
Add a dedicated "Privy wallet type" subsection (or link to Privy documentation) covering: availability dependency, data sent to Privy, migration path, and compatibility matrix with Agent Wallet operations.
Suggestions
[S-01] SUN CLI CommandGuide: Add Warning About --network as Root-Only Flag
File: docs/McpServer-Skills/Tools/SUNCli/CommandGuide.md — Global Flags table
Description: The FAQ correctly documents that --network must precede the subcommand, but the CommandGuide's Global Flags section has no such callout. The --network entry in the table reads the same as any other flag, which may lead users to append it after the subcommand.
Suggestion: Add an inline note to the --network row: "--network must appear before the subcommand (e.g., sun --network nile swap ...). Appending it after the subcommand will cause a parse error."
[S-02] Docker Deployment Should Note Agent Wallet Limitation
File: docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md — Option D (Docker)
Description: The Docker section notes the image runs in "read-only HTTP mode" and recommends Options A/B/C for write operations. It doesn't explain why Docker can't easily do write operations — the Agent Wallet keystore lives on the host filesystem and would need to be bind-mounted, with care taken around the master password. A brief technical note would help advanced users who want to explore Docker-based write deployments.
Suggestion: Add: "Write operations require Agent Wallet access. To enable writes in Docker, bind-mount your ~/.agent-wallet directory and pass AGENT_WALLET_PASSWORD via --env-file. Ensure the mounted directory has correct permissions inside the container."
[S-03] agent-wallet init vs agent-wallet start Disambiguation Could Be Clearer
File: docs/Agent-Wallet/Developer/CLI-Reference.md — agent-wallet init section
Description: The tip box says "start = init + create a wallet in one step", which is helpful. However, the surrounding text doesn't emphasize that for most users (including all CI scenarios described), start is simpler and sufficient. New users reading the CLI Reference top-to-bottom may try init thinking it's the recommended starting point.
Suggestion: Move the "When to use init vs start" tip to the top of the init section (currently it's at the bottom after the flag table), and add "For most users, agent-wallet start is the right starting point."
[S-04] x402 Quickstart for Agent: Remove Mention of npx skills add -y -g Without Explaining Flags
File: docs/x402/getting-started/quickstart-for-agent.md — Step 2
Description: The simplified install command npx skills add https://github.com/BofAI/skills -y -g uses -y (skip prompts) and -g (global install) without sufficient explanation. For users who may want per-project installation or who want to review security assessments before accepting, the -y flag bypasses that entirely. The page later references the Skills Quick Start for a "detailed walkthrough" but only for the interactive path.
Suggestion: Add a one-line explanation of each flag immediately after the command, and note that the interactive path (npx skills add without flags) lets users review security assessments before accepting.
Positive Observations
| Area | Observation |
|---|---|
| Security architecture | Consolidating all wallet modes to Agent Wallet (encrypted keystore) is a meaningful security improvement over the previous plaintext TRON_PRIVATE_KEY / TRON_MNEMONIC environment variables. The encrypted-first design is well-motivated and consistently applied. |
| Docker warning | The Docker section includes an explicit :::warning against using -e KEY=value on the command line. This is exactly the right guidance and is well-placed. |
| CLI Command Reference structure | The SUN CLI CommandGuide is thorough, consistently formatted, and includes sensible defaults, required/optional marking, and practical examples for every command. The :::caution Private Key Security block for the -k/-m flags is appropriate and well-placed. |
| Testnet-first guidance | Throughout SUN CLI docs, the guidance to test on Nile testnet before mainnet is consistently applied and marked clearly. |
| v1.1.7 changelog entry | Adding an explicit FAQ entry for "What changed in v1.1.7?" is excellent practice — it gives users a single place to understand breaking changes (removal of TRON_PRIVATE_KEY/TRON_MNEMONIC) and migration guidance. |
| i18n parity | The i18n/current/ directory mirrors all documentation changes, indicating good discipline in keeping localized versions in sync. |
| Rate limiting documentation | The new Facilitator rate limiting section (1000 req/min authenticated vs 1 req/min anonymous) is actionable and clearly presented with a comparison table. This was previously undocumented. |
| Non-interactive mode coverage | The agent-wallet change-password non-interactive mode documentation includes a :::caution about shell history exposure for passwords passed as flags — consistent with the overall security-forward tone of the PR. |
Checklist Results
| Category | Items Checked | Pass | Fail | N/A | Notes |
|---|---|---|---|---|---|
| Correctness | 8 | 6 | 2 | 0 | Node.js version inconsistency (MJ-03); GasFree path incorrect (MJ-02) |
| Security | 6 | 5 | 1 | 0 | Plaintext key warning removed from import path (MJ-01) |
| Performance | 5 | 0 | 0 | 5 | Not applicable (documentation only) |
| Code Quality | 6 | 5 | 0 | 1 | Consistent formatting; minor v4 fee default gap (MN-04) |
| Testing | 5 | 0 | 0 | 5 | Not applicable (documentation only) |
| Documentation | 6 | 4 | 2 | 0 | Privy docs incomplete (MN-05); agent-wallet risk score unexplained (MN-01) |
| Compatibility | 4 | 3 | 1 | 0 | Path 2 runtime env var ambiguity (MN-02) |
| Observability | 3 | 0 | 0 | 3 | Not applicable (documentation only) |
Disclaimer
This is an automated code review. It supplements but does not replace human review. The reviewer analyzed only the diff between the specified branches. Runtime behavior, integration testing, and deployment impact are not covered. All content reviewed is documentation (Markdown files) and configuration (sidebars.js, package.json) — no application source code was changed in this PR.
Report generated by Code Review Skill v1.0.0
Date: 2026-04-10
Code Review ReportProject: BofAI Docs ( PR OverviewBranch Information
Commit History (recent)
Review SummaryVerdict
Findings at a Glance
SummaryThis is a documentation-only PR that delivers three primary changes: (1) a new SUN CLI tool section with 4 new reference documents, (2) a wallet architecture consolidation that removes legacy The documentation quality is generally high — consistent formatting, appropriate security admonitions, and clear command examples. However, the PR contains several significant documentation gaps and internal inconsistencies that would actively mislead users or silently break existing deployments. The most pressing concerns are: an undisclosed breaking change for existing MCP Server users relying on raw private-key env vars; a behavioural inconsistency between TRONMCPServer (errors on write) and SUNMCPServer (read-only fallback) that is documented as a design difference without clear rationale; and credentials embedded in example YAML configs without a matching These issues do not affect production code (this repo is documentation only), but they directly affect users' ability to securely configure and operate the referenced software and should be resolved before publication. Change Summary1. SUN CLI Documentation (New Files)
Purpose: Introduces SUN CLI as a new tool under the McpServer-Skills section, providing complete reference documentation. 2. Wallet Architecture Consolidation
Purpose: Consolidates all wallet configuration docs to use Agent Wallet only; adds Privy wallet type support and new CLI commands. 3. x402 Protocol Updates
Purpose: Documents the new 4. Skills and Navigation Updates
Purpose: Reflects new skill count and Agent Wallet as a first-class skill; updates installer UX screenshots. Detailed FindingsMajor[MJ-01] Undisclosed Breaking Change: Legacy Wallet Env Vars Removed Without Migration Guide
Description The PR entirely removes documentation for There is no:
Code -#### Option 2: Private Key
-export TRON_PRIVATE_KEY="<your-private-key-hex>"
-
-#### Option 3: Mnemonic Phrase
-export TRON_MNEMONIC="word1 word2 word3 ... word12"Recommendation Add a versioned migration notice at the top of the affected deployment docs. Example: :::caution Breaking change in v1.1.7
`TRON_PRIVATE_KEY`, `TRON_MNEMONIC`, and `BSC_PRIVATE_KEY` environment variables
are no longer supported. Migrate to Agent Wallet using one of the two paths below.
See the [migration guide](#migration-from-env-var-wallet-modes) for step-by-step instructions.
:::[MJ-02] Behavioural Inconsistency: TRONMCPServer vs SUNMCPServer on Missing Wallet
Description The two docs describe different server behaviour when no wallet is configured:
These are contradictory descriptions of what should be equivalent functionality. Users running both servers will encounter inconsistency that erodes trust in the documentation. This may also be a genuine software bug masked by the docs if the two servers actually behave differently. Code # TRONMCPServer/LocalPrivatizedDeployment.md
+TRON MCP Server uses [Agent Wallet]... If no wallet is configured, write tools will return an error...
# SUNMCPServer/LocalPrivatizedDeployment.md
+SUN MCP Server uses [Agent Wallet]... If no wallet is configured, the server automatically runs in read-only mode.Recommendation Align both descriptions to reflect actual behaviour. If TRON MCP Server changed to error-on-write (per [MJ-03] Database Credentials in Example YAML Config Without
|
| Property | Value |
|---|---|
| Severity | Major |
| Category | Security |
| File | docs/x402/getting-started/quickstart-for-sellers.md : Self-Hosted Facilitator section, Step 3.3 |
Description
The new YAML configuration example shows a real database connection string containing a password:
database:
url: "postgresql+asyncpg://postgres:yourpassword@localhost:5432/x402"The doc instructs users to populate config/facilitator.config.yaml with their actual password but never tells them to add this file to .gitignore. Users following the guide while working in a Git repository risk accidentally committing their database credentials. The old .env-based approach at least implicitly carried the convention of never committing .env files.
Code
database:
url: "postgresql+asyncpg://postgres:yourpassword@localhost:5432/x402"Recommendation
Add an explicit warning immediately after the cp config/facilitator.config.example.yaml config/facilitator.config.yaml step:
:::warning
`config/facilitator.config.yaml` will contain your database password. Add it to
your `.gitignore` before committing:
```bash
echo "config/facilitator.config.yaml" >> .gitignore:::
---
#### [MJ-04] `AGENT_WALLET_PRIVATE_KEY` Persisted Plaintext to Shell Profile Without Security Warning
| Property | Value |
|----------|-------|
| **Severity** | Major |
| **Category** | Security |
| **File** | `docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md` : Path 2 (~line 95); same pattern in `SUNMCPServer/LocalPrivatizedDeployment.md`, `quickstart-for-agent.md`, `quickstart-for-human.md`, `quickstart-for-sellers.md` |
**Description**
The PR's new "Option B / Path 2" instructs users to persist their raw private key directly into their shell profile (`~/.zshrc` or `~/.bashrc`). This stores the private key as plaintext in a file that is typically backed up, synced (e.g., dotfiles repos), or readable by any process running under the same user. The original docs had an explicit `:::warning` admonition about this risk when documenting `TRON_PRIVATE_KEY`. The replacement docs drop the warning and instead suggest this as a normal workflow with a friendly `:::tip` callout.
**Code**
```bash
# Suggested in the "tip" block:
echo 'export AGENT_WALLET_PRIVATE_KEY=your_private_key' >> ~/.zshrc
echo 'export AGENT_WALLET_PRIVATE_KEY=your_private_key' >> ~/.bashrc
Recommendation
Replace the :::tip with a :::warning admonition that explicitly states the security trade-off:
:::warning Plaintext key in shell profile
Adding a raw private key to `~/.zshrc` or `~/.bashrc` stores it as plaintext.
Any process or script that reads your environment — or anyone with access to your
dotfiles — can extract it. Only use this approach for **dedicated test wallets with
minimal funds**. For production or significant-fund wallets, use Agent Wallet's
encrypted keystore (`agent-wallet start`) instead.
:::[MJ-05] Python Version Requirement Inconsistency Across Docs
| Property | Value |
|---|---|
| Severity | Major |
| Category | Correctness / Documentation |
| File | docs/x402/getting-started/quickstart-for-human.md : Prerequisites vs docs/x402/getting-started/quickstart-for-sellers.md : Prerequisites |
Description
quickstart-for-human.md bumps the Python requirement from 3.10+ to 3.11+ in this PR, but quickstart-for-sellers.md retains Python 3.10+ in its prerequisites checklist. Users who follow the sellers guide first and use Python 3.10 may encounter issues when following the human/agent quickstart later, with no warning.
Code
# quickstart-for-human.md
-**Python 3.10+** or **Node.js 18+**
+**Python 3.11+** or **Node.js 18+**
# quickstart-for-sellers.md (unchanged — still says 3.10+)
- [ ] **Python 3.10+** or **Node.js 18+** installedRecommendation
Decide on the canonical minimum Python version and apply it consistently across all x402 quickstart guides. If 3.11 is the new minimum (likely due to asyncio / tomllib changes), update quickstart-for-sellers.md to match.
Minor
[MN-01] USDD Fee Amount in YAML Example Is Unexplained and Potentially Confusing
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | docs/x402/getting-started/quickstart-for-sellers.md : Step 3.3, TRON YAML tab |
Description
The YAML example shows USDT: 100 alongside USDD: 100000000000000. The 12-order-of-magnitude difference (100 vs 10^14) is technically correct if USDT uses 6 decimals and USDD uses 18 decimals, but this is never explained. A developer unfamiliar with TRON token decimal conventions may simply copy-paste the USDD value and set a fee vastly larger or smaller than intended.
Code
base_fee:
USDT: 100 # 0.0001 USDT per settlement (adjust as needed)
USDD: 100000000000000Recommendation
Add a comment explaining the decimal conversion:
base_fee:
USDT: 100 # 0.0001 USDT (USDT uses 6 decimals: 100 / 10^6)
USDD: 100000000000000 # 0.0001 USDD (USDD uses 18 decimals: 10^14 / 10^18)[MN-02] agent-wallet Skill Shows High Risk Rating With No Explanation
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | docs/McpServer-Skills/SKILLS/QuickStart.md : Security Risk Assessments table; docs/Openclaw-extension/QuickStart.md : same |
Description
Both quickstart guides now show the agent-wallet skill with a High Risk Snyk rating:
│ agent-wallet Med Risk 1 alert High Risk
No explanation is provided for why this skill has a High Risk rating. Users may either ignore this (normalising security warnings) or be scared away from installing the skill. The x402-payment skill changed from Med to Med Risk/Safe between the two guides, which is also inconsistent.
Recommendation
Add a footnote or follow-up paragraph explaining what the security scan findings mean for agent-wallet and whether the risk is accepted/mitigated. Example:
> ℹ️ The `agent-wallet` High Risk (Snyk) rating refers to transitive
> dependency vulnerabilities. The core signing and key management code
> does not use the affected packages. Review the full Snyk report at
> [link] before making your own risk assessment.[MN-03] Node.js Version Bump (18 → 20) Not Highlighted as a Breaking Requirement Change
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | docs/Agent-Wallet/QuickStart.md, docs/Agent-Wallet/Developer/SDK-Guide.md, docs/Agent-Wallet/FAQ.md |
Description
The Node.js minimum requirement is raised from 18 to 20 across the Agent Wallet docs. Node.js 18 is still in active LTS support through April 2025, so users on 18 will silently get failures without understanding why. The change is made inline in existing text with no callout. Given the PR targets users who may already have agent-wallet installed with Node 18, a more prominent notice is warranted.
Recommendation
Add a versioned note at the top of the affected pages or in a "What's New" section:
:::note Node.js 20+ required as of agent-wallet v2.x
Node.js 18 is no longer supported. If you are on Node 18, upgrade before proceeding.
:::[MN-04] AGENT_WALLET_MNEMONIC Env Var Referenced in SUNCli Docs But Not in Agent-Wallet Docs
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation / Consistency |
| File | docs/McpServer-Skills/Tools/SUNCli/CommandGuide.md : Global Flags, Wallet Configuration section |
Description
The SUN CLI command guide references AGENT_WALLET_MNEMONIC as a supported environment variable:
- `AGENT_WALLET_MNEMONIC` — mnemonic phrase
This env var does not appear anywhere in the Agent-Wallet documentation (CLI Reference, SDK Guide, or FAQ) in this PR. If it is a supported feature, it should be documented in Agent-Wallet. If it is not yet supported or is SUNCli-specific, the scope should be clarified.
Recommendation
Either add AGENT_WALLET_MNEMONIC to the Agent-Wallet CLI Reference with usage examples, or add a note in SUNCli's docs clarifying it is a CLI-specific feature.
[MN-05] Anonymous Facilitator Rate Limit (1 req/min) Not Flagged as Impactful for Testing
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation |
| File | docs/x402/core-concepts/facilitator.md : Rate Limiting section |
Description
The new rate limiting table states anonymous users are limited to 1 request per minute on the /settle endpoint. This is extremely restrictive and will break any automated test suite that doesn't configure an API key. The docs do not warn developers setting up for the first time that they will immediately hit this limit during the quickstart workflow.
Code
| **Anonymous** | 1 request / minute | No API Key provided |Recommendation
Add a callout before the rate limit table:
> ⚠️ **Developers:** The 1 req/min anonymous limit will be hit during
> any automated test run. Apply for an API Key via the
> [Admin Portal](https://admin-facilitator.bankofai.io) before
> running integration tests.[MN-06] exact_gasfree Activation Flow Has No Recovery / Troubleshooting Docs
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation / Completeness |
| File | docs/x402/core-concepts/network-and-token-support.md : exact_gasfree Scheme section |
Description
The new exact_gasfree scheme requires a one-time "GasFree account activation" step, documented as:
npx tsx x402-payment/src/x402_invoke.ts --gasfree-activateHowever, there is no documentation for:
- What happens if activation fails (network error, insufficient funds)
- How to check if an account is already activated
- Whether activation is per-token or per-account
- What error messages to expect if using the scheme on a non-activated account
Recommendation
Add a "Troubleshooting GasFree" subsection or FAQ entry covering activation failure modes and recovery steps.
Suggestions
[S-01] Consolidate Duplicate Wallet Setup Sections Between TRON and SUN MCP Servers
File: docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md and docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md
Description: The wallet setup sections in these two files are now nearly identical (same Agent Wallet table, same Path 1/Path 2 instructions). Any future updates will need to be applied in two places, risking drift.
Suggestion: Extract the common wallet setup into a shared include file (e.g., _partials/agent-wallet-setup.md) using Docusaurus's MDX import mechanism, then reference it from both deployment guides.
[S-02] Docker Deployment Section Should Note Agent Wallet Cannot Be Used in Read-Only Container
File: docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md : Option D
Description: The Docker tip says the image runs in "read-only HTTP mode by default" and directs users to Options A/B/C for write operations. It would be helpful to explain why Docker mode is read-only (i.e., the Agent Wallet keystore can't be mounted into the container without additional volume configuration), so users understand the architectural reason rather than treating it as an arbitrary limitation.
Suggestion: Add one sentence: "Docker mode is read-only because mounting an encrypted Agent Wallet keystore into a container requires additional volume and secret configuration beyond the scope of this guide."
[S-03] quickstart-for-sellers.md Self-Hosted Section Should Reference Docker Compose Alternative
File: docs/x402/getting-started/quickstart-for-sellers.md : Section 3
Description: The new self-hosted Facilitator section requires users to manually install PostgreSQL (with detailed OS-specific instructions). A Docker Compose alternative would dramatically reduce setup friction and is now standard practice for self-hosted services.
Suggestion: Add an optional "Option C — Docker Compose" tab alongside the direct install and Railway cloud options.
[S-04] CLI Reference change-password Non-Interactive Warning Duplicates Itself
File: docs/Agent-Wallet/Developer/CLI-Reference.md : change-password section
Description: The new caution block for change-password non-interactive mode warns that -p and --new-password will be recorded in shell history — but this same concern applies to any flag containing sensitive material (e.g., agent-wallet start -p), which is documented elsewhere without a warning. The warning is inconsistently applied.
Suggestion: Either add a general shell-history warning to the top of the CLI Reference, or ensure every section that accepts passwords via flags carries the same caution.
Positive Observations
| Area | Observation |
|---|---|
| Bug fix | quickstart-for-sellers.md correctly adds request: Request to FastAPI endpoint function signatures — this was a genuine FastAPI usage bug that would cause runtime errors |
| Security transparency | The fallback RPC endpoint note clearly discloses BANK OF AI's infrastructure dependency, SLA limitations, and how to opt out — this is honest and developer-friendly |
| Docker security | Option D's Docker deployment explicitly warns against -e KEY=value and mandates --env-file, with an explanation of why (shell history, docker inspect) |
New exact_gasfree docs |
The GasFree scheme is documented comprehensively with activation CLI commands, account query commands, and clear "no API keys required" note |
| Structured admonitions | Consistent use of :::tip, :::warning, :::caution, :::danger, and :::info throughout, making safety-critical information scannable |
| SUNCli security notes | CommandGuide.md includes a prominent :::caution Private Key Security block for -k/-m flags and a dedicated Security Notes section |
| PostgreSQL setup | Multi-distro PostgreSQL installation instructions (macOS, Ubuntu, Amazon Linux, Arch, Windows) plus pg_hba.conf auth configuration are thorough and cover a common pain point |
--dry-run documentation |
Consistent documentation of --dry-run across SUN CLI commands promotes safe testing practices |
| Privy wallet type | New privy wallet type is well-documented with a clear comparison table and appropriate caveats about API credentials |
| Facilitator rate limits | Publishing the rate limit policy (previously undocumented) reduces user frustration and sets correct expectations |
Checklist Results
| Category | Items Checked | Pass | Fail | N/A | Notes |
|---|---|---|---|---|---|
| Correctness | 8 | 6 | 2 | 0 | Version inconsistency (Python 3.10 vs 3.11); TRON vs SUN MCP behaviour mismatch |
| Security | 10 | 7 | 3 | 0 | Plaintext key in shell profile tip; no .gitignore for YAML config; no warning on AGENT_WALLET_PRIVATE_KEY persistence |
| Performance | 7 | 7 | 0 | 0 | No performance-impacting doc changes |
| Code Quality | 8 | 7 | 1 | 0 | Duplicate wallet setup content between TRON/SUN MCP docs |
| Testing | 5 | 3 | 0 | 2 | No test files changed; N/A for docs-only PR |
| Documentation | 6 | 3 | 3 | 0 | Missing breaking change notice; missing migration guide; AGENT_WALLET_MNEMONIC undocumented in Agent-Wallet |
| Compatibility | 5 | 3 | 2 | 0 | Node 18→20 bump not prominently flagged; legacy env vars removed without migration path |
| Observability | 4 | 4 | 0 | 0 | Rate limiting and fallback endpoints are now documented |
Disclaimer
This is an automated code review. It supplements but does not replace human review. The reviewer analysed only the diff between main and update-mcp-server. All files reviewed are documentation (Markdown). No runtime code, smart contracts, or backend logic was changed in this PR. Runtime behaviour, integration testing, and deployment impact of the referenced software are not covered by this review.
Report generated by Code Review Skill v1.0.0
Date: 2026-04-10
Code Review ReportProject: BofAI/docs (MCP Server & Agent Wallet Documentation) PR OverviewBranch Information
Commit History
Review SummaryVerdict
Findings at a Glance
SummaryThis PR is a substantial documentation update for the BANK OF AI ecosystem, covering four main areas: (1) introduction of the new SUN CLI tool ( Overall quality is good. The writing is clear, examples are practical, and critical security guidance (encrypted storage over plaintext keys, testnet-first advice, history-exposure warnings for CLI flags) is consistently present. The migration away from plaintext private keys in environment variables is a meaningful security improvement and is well-executed across both English and Chinese localisations. The main concerns are: a security-sensitive example in the "Import an Existing Private Key" path that instructs users to persist a raw private key into shell profile files without adequate context-appropriate warning; a minor but notable version inconsistency ( Change Summary1. New SUN CLI Documentation (4 new files)
2. Agent Wallet — Wallet Configuration Migration
3. MCP Server — Wallet Mode Simplification
4. x402 Payment Scheme Updates
5. Openclaw Extension
Detailed Findings[MJ-01] Persisting Raw Private Key to Shell Profile Without Adequate Warning
Description
Code Recommendation Change the :::tip block to a :::warning or :::caution block, and add explicit guidance:
:::warning Private key security — shell profile
Adding your private key to `~/.zshrc` or `~/.bashrc` stores it in **plaintext on disk**.
Any process that reads your shell config, or anyone with access to your home directory,
can extract it. For long-lived deployments, use agent-wallet encrypted storage instead
(`agent-wallet start` and set `AGENT_WALLET_PASSWORD`). Only use this method for
short-lived test sessions.
:::[MJ-02] Printing Private Key to Terminal Recommended as a "Success Indicator"
Description
Code echo $AGENT_WALLET_PRIVATE_KEY
# > ✅ Success indicator: The terminal prints your private key string (not blank)Recommendation # Verify the variable is set without revealing the value:
[[ -n "$AGENT_WALLET_PRIVATE_KEY" ]] && echo "AGENT_WALLET_PRIVATE_KEY is set" || echo "NOT set"
# > ✅ Success indicator: Terminal prints "AGENT_WALLET_PRIVATE_KEY is set"[MJ-03] Self-Hosted Facilitator Config Includes Password in Connection String Example
Description
Code database:
url: "postgresql+asyncpg://postgres:yourpassword@localhost:5432/x402"Recommendation Add a note alongside the YAML example:
> **Security note:** Do not commit `config/facilitator.config.yaml` to version control
> if it contains the database password. Consider using an environment variable
> (`DATABASE_URL`) and referencing it in your config, or add the file to `.gitignore`.[MN-01] Python Version Inconsistency Between Documents
Description
Code - [ ] **Python 3.11+** or **Node.js 18+** installed (depending on your chosen language)Recommendation - [ ] **Python 3.11+** or **Node.js 20+** installed (depending on your chosen language)[MN-02] Broken Anchor Fragment in CLI-Reference Links (Partial Fix)
Description
Code <!-- In TRONMCPServer/FAQ.md: -->
Run `agent-wallet reset` to wipe and start over — see [CLI Reference → Reset](../../../Agent-Wallet/Developer/CLI-Reference.md#agent-wallet-reset-reset-all-data)
<!-- In zh-Hans CLI-Reference.md — anchor IS present: -->
<a id="agent-wallet-reset-reset-all-data"></a>
### `agent-wallet reset`（重置所有数据）
<!-- In English CLI-Reference.md — anchor is NOT present -->
### `agent-wallet reset` (Reset All Data)Recommendation Add the anchor tag to the English CLI-Reference.md at the Reset section heading:
<a id="agent-wallet-reset-reset-all-data"></a>
### `agent-wallet reset` (Reset All Data)[MN-03] Docker Deployment (Option D) Missing Security Note About Agent Wallet Private Key
Description
Code # From Option D example:
cat > .env.docker << 'EOF'
TRONGRID_API_KEY=your-key-here
EOFRecommendation Add a note below the tip:
> To enable write operations in a Docker container, either:
> - Add `AGENT_WALLET_PRIVATE_KEY=<key>` to `.env.docker` (ensure the file is in `.gitignore`)
> - Mount the agent-wallet directory: add `-v ~/.agent-wallet:/root/.agent-wallet` and
> pass `AGENT_WALLET_PASSWORD` in the env file
>
> The latter is preferred for production: it keeps the plaintext key off disk
> and uses the encrypted keystore.[MN-04]
|
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Correctness / Docs |
| File | docs/x402/core-concepts/network-and-token-support.md : GasFree Account Management section |
Description
The GasFree account management commands reference
npx tsx x402-payment/src/x402_invoke.tsdirectly. This assumes that the user has cloned the repository and is running from the project root. This context is not established at the point where the commands appear in the network-and-token-support reference page, which is a conceptual reference document, not a setup guide. Users reading this page without having set up the x402-payment skill locally would be confused. The pathx402-payment/src/x402_invoke.tsalso appears to be an implementation detail that may change.
Code
npx tsx x402-payment/src/x402_invoke.ts --gasfree-info
npx tsx x402-payment/src/x402_invoke.ts --gasfree-activateRecommendation
Add a prerequisite note before the commands:
> The following commands require the `x402-payment` skill to be installed and
> run from its root directory. See the [Skills Quick Start](../../McpServer-Skills/SKILLS/QuickStart.md)
> for installation instructions.
Or, if the skill installs a CLI binary, update to use the binary name instead
of the `npx tsx` invocation.[MN-05] quickstart-for-human.md Removes .env File Recommendation Without Replacement
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Security / Docs |
| File | docs/x402/getting-started/quickstart-for-human.md : Step Two |
Description
The previous version included a
:::tiprecommending users create a.envfile and add it to.gitignore:💡 Recommended: Create a `.env` file in your project directory containing `TRON_PRIVATE_KEY=your_key`, then add `.env` to `.gitignore` to prevent accidental commits.This recommendation was removed in the PR. The replacement is to export the variable directly and optionally persist it to the shell profile (which as noted in MJ-01, has its own risks). For developers building with the Python or TypeScript SDK, the
.envfile pattern (withdotenv/python-dotenv) is a common and appropriate pattern. Removing this guidance leaves a gap.
Code
- > 💡 **Recommended:** Create a `.env` file in your project directory containing `TRON_PRIVATE_KEY=your_key`,
- then add `.env` to `.gitignore` to prevent accidental commits.Recommendation
Re-add or update the .env guidance for SDK users:
> 💡 **Tip for SDK projects:** You can also store `AGENT_WALLET_PRIVATE_KEY` in a `.env`
> file in your project root (using `python-dotenv` or `dotenv` for Node.js), then add
> `.env` to `.gitignore` to prevent accidental commits.[S-01] Suggestion: Consolidate Repeated "Fallback RPC Endpoint" Note
| Property | Value |
|---|---|
| Severity | Suggestion |
| Category | Quality / Docs |
| File | docs/x402/getting-started/quickstart-for-agent.md, docs/x402/getting-started/quickstart-for-human.md, docs/x402/getting-started/quickstart-for-sellers.md |
Description
The identical "Fallback RPC Endpoint" note block appears three times across the three quickstart files, with identical text about
TRON_GRID_API_KEYfallback behavior and the BANK OF AI proxy. This is a documentation maintenance concern — if the fallback URL or behavior changes, it needs to be updated in three places. Consider extracting this into a Docusaurus admonition partial or linking from the quickstarts to a single canonical page that describes the fallback behavior.
Recommendation
Create a shared admonition partial (e.g., `_partials/_tron-rpc-fallback.mdx`) and
import it in all three quickstart files using Docusaurus's MDX import feature,
or add a cross-reference to a single canonical page.[S-02] Suggestion: agent-wallet Skill Security Risk Rating in QuickStart
| Property | Value |
|---|---|
| Severity | Suggestion |
| Category | Docs |
| File | docs/McpServer-Skills/SKILLS/QuickStart.md, docs/Openclaw-extension/QuickStart.md |
Description
The security risk assessment tables now show
agent-walletasHigh Risk(Snyk) andMed Risk(Gen), while all other skills (exceptx402-payment) show no risk flags or lower ratings. This is displayed without any explanation. Users who are unfamiliar with security scanners may be confused or alarmed. A brief note explaining that the risk rating reflects the presence of cryptographic and key management dependencies (not a vulnerability) would improve user confidence.
Recommendation
Add a note after the security assessment table:
> ℹ️ The `agent-wallet` skill manages private keys and uses cryptographic libraries,
> which typically trigger higher scanner ratings. The warnings reflect the presence
> of sensitive-operation dependencies, not known vulnerabilities.[S-03] Suggestion: i18n/zh-Hans sidebars.js Diverges from Root sidebars.js
| Property | Value |
|---|---|
| Severity | Suggestion |
| Category | Quality |
| File | i18n/zh-Hans/docusaurus-plugin-content-docs/current/sidebars.js |
Description
The diff shows that both
sidebars.js(root) and the zh-Hanssidebars.jsare modified independently to add the SUN CLI section. The two files appear to have slightly different structures (the zh-Hans one adds one extra item in the Skills intro). If this is intentional, that is fine, but maintaining two separate sidebar files risks drift over time. Docusaurus supports locale-specific sidebar overrides but it is worth confirming whether a single sidebar source of truth would be more maintainable.
Recommendation
Consider using Docusaurus's locale sidebar override mechanism and keeping
sidebar structure synchronized through a shared base, annotating any
intentional locale-specific differences with comments.[S-04] Suggestion: New SUNCli CommandGuide.md Missing swap:exact-input Required Parameters Table
| Property | Value |
|---|---|
| Severity | Suggestion |
| Category | Docs |
| File | docs/McpServer-Skills/Tools/SUNCli/CommandGuide.md : swap:exact-input section |
Description
The
swap:exact-inputcommand documentation lists--routerand--argsas(required)in the description column, but unlike many other commands in the same file, it does not provide a usage example. Theswap:quote-rawcommand is similarly missing an example. Given that these are low-level commands that developers are most likely to get wrong, adding a simple illustrative example would improve the reference.
Recommendation
Add a minimal example for swap:exact-input:
```bash
sun swap:exact-input \
--router TRouterContractAddress \
--args '[[...path], amountIn, amountOutMin, deadline]'
---
## Positive Observations
| Area | Observation |
|------|-------------|
| Security posture improvement | Removing all three plaintext wallet modes (TRON_PRIVATE_KEY, TRON_MNEMONIC, BSC_PRIVATE_KEY) and standardizing on AGENT_WALLET_PRIVATE_KEY with explicit guidance toward encrypted storage is a meaningful security improvement across the entire documentation set. |
| Consistent security messaging | Every new SUN CLI section includes a prominent `:::warning` or `:::caution` block about not hardcoding private keys, testnet-first advice, and the `--dry-run` pattern. The "caution" note about `-k`/`-m` flags in the CommandGuide global flags section is particularly well-placed. |
| Docker security guidance | The new Docker Option D explicitly warns against `-e KEY=value` and prescribes `--env-file`, which is the correct pattern. The warning callout is well-positioned directly after the command. |
| Privy integration documentation | The addition of `privy` wallet type is thoroughly documented across CLI reference, SDK guide, FAQ comparison table, and error hierarchy, in both English and Chinese. |
| Bilingual parity | The zh-Hans localisation is updated in sync with the English docs for all major changes, including error type names, wallet type comparisons, and Node.js version requirements. |
| Facilitator rate limiting documentation | The new rate limiting table in `facilitator.md` clearly communicates the differentiated anonymous vs authenticated limits and links to the Admin Portal for API key registration. |
| Tool count accuracy | The tool count update from 95 to 97 is applied consistently across all documents that mention it (Intro, ToolList, OfficialServerAccess, QuickStart). |
---
## Checklist Results
| Category | Items Checked | Pass | Fail | N/A | Notes |
|----------|:---:|:---:|:---:|:---:|-------|
| Correctness | 8 | 6 | 2 | 0 | Node.js version inconsistency in human quickstart; broken anchor in English CLI-Reference |
| Security | 10 | 7 | 3 | 0 | Raw key persistence without warning; key echo as success indicator; DB password in config example |
| Performance | 3 | 3 | 0 | 0 | Pagination present on all list commands; no unbounded queries documented |
| Code Quality | 8 | 6 | 0 | 2 | Repeated RPC fallback note (suggestion only); sidebar duplication (suggestion only) |
| Testing | 4 | 4 | 0 | 0 | N/A — documentation changes; example commands follow correct --dry-run / testnet-first advice |
| Documentation | 12 | 10 | 2 | 0 | Missing anchor tag in English CLI-Reference; GasFree commands lack context for reference page |
| Compatibility | 5 | 5 | 0 | 0 | Node.js 20 requirement consistently updated; Windows support noted with caveats |
| Observability | 3 | 3 | 0 | 0 | Log file guidance, health check endpoint, and tronscanUrl return value documented |
---
## Disclaimer
This is an automated code review. It supplements but does not replace human review.
---
*Report generated by Code Review Skill v1.0.0*
*Date: 2026-04-10*
Audit Report: PR
|
| Property | Value |
|---|---|
| Source Branch | update-mcp-server |
| Target Branch | main |
| Total Commits | 33 |
| Files Changed | 62 |
| Lines Added | ~4,189 |
| Lines Removed | ~755 |
Commit Summary (most recent first)
dee690c fix
f50ce16 change python-version
e24ac5c delete caution
71a3720 fix
a82086c add sun-cli
2d193a0 fix
174c30d add setup
d883416 update content
daea552 fix seller example
ffb5377 chang wallet mode
b3fc365 fix agent-wallet
05d402c add sunmcpserver
24bfe40 add inspect
37d478b update x402
408ec4b update x402,skills,agent-wallet,mcp-server
f7f440e adjust content
cc7feb9 add agent-wallet cli-reference
85c1a65 fix gasfree
... (and more)
Files Changed (key files)
| File | Change Type | Lines +/- |
|---|---|---|
docs/McpServer-Skills/Tools/SUNCli/CommandGuide.md |
New | +860 |
docs/McpServer-Skills/Tools/SUNCli/FAQ.md |
New | +133 |
docs/McpServer-Skills/Tools/SUNCli/Intro.md |
New | +127 |
docs/McpServer-Skills/Tools/SUNCli/QuickStart.md |
New | +147 |
docs/McpServer-Skills/SKILLS/BANKOFAISkill.md |
New | +67 |
docs/x402/getting-started/quickstart-for-sellers.md |
Major update | +264/-X |
docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md |
Major update | +115/-X |
docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md |
Major update | +71/-X |
docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md |
Updated | +41 |
docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md |
Updated | +53 |
docs/Agent-Wallet/Developer/CLI-Reference.md |
Updated | +89 |
docs/Agent-Wallet/Developer/SDK-Guide.md |
Updated | +26 |
docs/Agent-Wallet/FAQ.md |
Updated | +19 |
docs/Agent-Wallet/QuickStart.md |
Updated | +8 |
docs/x402/core-concepts/network-and-token-support.md |
Updated | +50 |
docs/x402/core-concepts/facilitator.md |
Updated | +29 |
sidebars.js |
Updated | +18 |
package.json |
Minor update | +1/-1 |
| (i18n/zh-Hans mirrors of all above) | Mirrored | various |
2. Change Summary
2.1 New SUN CLI Documentation (Major New Feature)
Four new pages added under docs/McpServer-Skills/Tools/SUNCli/:
- Intro.md — Overview comparing SUN CLI vs SUN MCP Server, output modes, supported networks, security notes
- QuickStart.md — 5-step guide: install, first query, explore, wallet setup, execute swap
- CommandGuide.md — Full command reference: wallet, price, token, swap, pool, liquidity, position, pair, farm, protocol, transaction, contract (~860 lines)
- FAQ.md — Troubleshooting: installation, wallet configuration, common errors, AI agent integration
2.2 Wallet Architecture Migration
The MCP server docs (TRON, SUN) have been significantly updated to:
- Remove three-way wallet mode support (
AGENT_WALLET_PASSWORD,TRON_PRIVATE_KEY,TRON_MNEMONIC) - Consolidate to Agent Wallet as the only supported wallet system
- Add
AGENT_WALLET_PRIVATE_KEYimport path as a secondary option for key import - Update error messaging ("Conflicting Wallet Modes" → "Wallet Not Found")
- Update write-tool behavior: tools now always appear, availability checked at execution time
2.3 Node.js Version Bump
Updated minimum Node.js requirement from >=18 to >=20 across:
docs/Agent-Wallet/QuickStart.mddocs/Agent-Wallet/Developer/SDK-Guide.mddocs/Agent-Wallet/FAQ.mddocs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.mddocs/McpServer-Skills/Tools/SUNCli/QuickStart.mdandFAQ.md- All i18n mirrors
2.4 Agent Wallet CLI Additions
docs/Agent-Wallet/Developer/CLI-Reference.md gains:
- New
agent-wallet initcommand documentation - New
agent-wallet resolve-addresscommand documentation - New
--show-addressflag foragent-wallet inspect - Non-interactive
change-passwordflags (--password,--new-password,--save-runtime-secrets) - New
--yesflag foragent-wallet remove - Example output snippets for
sign msgandsign tx
2.5 Privy Wallet Support
Agent Wallet docs now document a third wallet type (privy):
- FAQ comparison table extended to include
privy - CLI-Reference includes a tip block describing Privy setup requirements
- SDK-Guide error hierarchy adds
PrivyConfigError,PrivyRequestError,PrivyRateLimitError,PrivyAuthError
2.6 x402 Protocol Updates
network-and-token-support.mdaddsexact_gasfreeas a third payment schemefacilitator.mdadds Facilitator API endpoint table including/payments/{payment_id}and scoped query behaviorquickstart-for-sellers.mdandquickstart-for-agent.mdupdated with YAML vs wire-protocol network identifier distinction (bsc:mainnetvseip155:56)sdk-features.mdupdated
2.7 Skills Documentation
- New
docs/McpServer-Skills/SKILLS/BANKOFAISkill.md— comprehensive skill catalog with skill-by-skill breakdowns, sample prompts, and safety warnings SKILLS/QuickStart.mdandSKILLS/Intro.mdupdatedsidebars.jsupdated with new TOOLS/SUN CLI section
2.8 i18n Mirrors
All English documentation changes are mirrored in i18n/zh-Hans/docusaurus-plugin-content-docs/current/. This roughly doubles the surface area of changes.
3. Detailed Findings
[MAJOR-01] package.json engines.node Not Updated to Match Documentation
| Property | Value |
|---|---|
| Severity | Major |
| Category | Correctness & Logic / Documentation Consistency |
| File | package.json : Line 55 |
Description:
The documentation throughout this PR explicitly raises the Node.js minimum requirement from >=18 to >=20. The package.json engines field, however, still specifies "node": ">=18". This creates an inconsistency: the toolchain itself advertises Node 18 compatibility, but all documentation and user-facing guides now require Node 20. Developers following the docs will set up Node 20; contributors or CI pipelines relying on package.json may use Node 18 and experience unexpected behavior if the project's own build tooling relies on Node 20 features.
Code:
"engines": {
"node": ">=18",
"yarn": ">=1.22"
}Recommendation:
Update package.json engines to "node": ">=20" to align with all documentation changes in this PR.
[MAJOR-02] Security Risk: echo $AGENT_WALLET_PRIVATE_KEY Leaks Private Key in Documentation
| Property | Value |
|---|---|
| Severity | Major |
| Category | Security — Sensitive Data / Input Validation |
| File | docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md : Lines 103-107; docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md : lines ~98-102; docs/x402/getting-started/quickstart-for-agent.md : Lines 68-72 |
Description:
Multiple documentation sections instruct users to verify their private key is set by running echo $AGENT_WALLET_PRIVATE_KEY. This command prints the raw private key to the terminal — including shell history, terminal scrollback, and any screen-sharing or pair-programming sessions. This is contrary to security best practices for sensitive credential verification.
The SUN CLI FAQ correctly demonstrates a safe verification pattern ([[ -n "$AGENT_WALLET_PASSWORD" ]] && echo "Password is set"), but the TRON/SUN MCP deployment guides and the x402 quickstart-for-agent do not follow this pattern.
Code (from TRON LocalPrivatizedDeployment.md):
Verify the environment variable is set:
```bash
echo $AGENT_WALLET_PRIVATE_KEY
**Code (from quickstart-for-agent.md):**
```bash
echo $AGENT_WALLET_PRIVATE_KEY
✅ Success indicator: The terminal prints your private key string (not blank)
Recommendation:
Replace all echo $AGENT_WALLET_PRIVATE_KEY verification examples with a safe, non-revealing check:
# Safe verification — confirms the variable is set without revealing the value
[[ -n "$AGENT_WALLET_PRIVATE_KEY" ]] && echo "Private key is set" || echo "Private key NOT set"Additionally, add a security caution note explaining why printing the key is discouraged in shared or logged environments.
[MAJOR-03] Inconsistency: TRON MCP FAQ References AGENT_WALLET_PASSWORD for Path 2 (Private Key Import), but AGENT_WALLET_PRIVATE_KEY is the Correct Variable
| Property | Value |
|---|---|
| Severity | Major |
| Category | Correctness & Logic — API Contract |
| File | docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md : Lines 54-57 |
Description:
The TRON MCP Server FAQ section "Write tools appear but return 'Wallet not configured' error" instructs users to "Set AGENT_WALLET_PASSWORD environment variable with your master password." This only covers the encrypted keystore path (Path 1). The LocalPrivatizedDeployment.md introduced a second path — importing a private key via AGENT_WALLET_PRIVATE_KEY — but the FAQ was not updated to mention this option. A user who followed Path 2 (private key import) and hits this error would be given incorrect guidance.
Code:
To enable write operations, configure [Agent Wallet](../../../Agent-Wallet/Intro.md):
- Set `AGENT_WALLET_PASSWORD` environment variable with your master password
- Optionally set `AGENT_WALLET_DIR` if using a custom wallet directory
Recommendation:
Update the FAQ to list both wallet credential options:
AGENT_WALLET_PASSWORD— for encrypted keystore walletsAGENT_WALLET_PRIVATE_KEY— for raw private key import
Mirror the same fix in the equivalent SUN MCP FAQ section.
[MAJOR-04] Broken/Inconsistent Internal Link Patterns: Mixed .md-Suffixed and Non-Suffixed Links
| Property | Value |
|---|---|
| Severity | Major |
| Category | Documentation & Maintainability |
| File | Multiple files |
Description:
The diff shows a systematic conversion of internal links from bare paths (e.g., [Agent-Wallet FAQ](../../../Agent-Wallet/FAQ)) to .md-suffixed paths (e.g., [Agent-Wallet FAQ](../../../Agent-Wallet/FAQ.md)). This conversion is incomplete — the BANKOFAISkill.md file and some Skills pages use bare paths without .md extensions in their cross-references. In Docusaurus, both forms can work depending on configuration, but inconsistency within a single PR is a quality concern and may cause build warnings or failures depending on the strict mode settings.
Examples of remaining non-suffixed links in newly added files:
BANKOFAISkill.mdline 37:[Quick Start](./QuickStart.md#...)— this one uses.md(OK)BANKOFAISkill.mdline 323:[FAQ](./Faq.md)— note casing:Faq.mdvs the likely actual filenameFAQ.md
Code (BANKOFAISkill.md line 323-325):
- Running into issues? → [FAQ](./Faq.md)Recommendation:
Verify the actual filename for the SKILLS FAQ (likely FAQ.md not Faq.md) and fix the casing. Perform a consistency audit of all internal links in new files to ensure they resolve correctly, especially on case-sensitive Linux filesystems.
[MINOR-01] SUN CLI FAQ: AGENT_WALLET_MNEMONIC Environment Variable Mentioned but Not Documented Elsewhere
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation & Maintainability — Missing Docs |
| File | docs/McpServer-Skills/Tools/SUNCli/FAQ.md : Lines 29-33 |
Description:
The SUN CLI FAQ lists three wallet credential sources: AGENT_WALLET_PRIVATE_KEY, AGENT_WALLET_MNEMONIC, and AGENT_WALLET_PASSWORD. However, AGENT_WALLET_MNEMONIC is not mentioned anywhere in the MCP server deployment guides, the Agent Wallet documentation, or the quickstart guides in this PR. This creates an undocumented public API surface. Users may attempt to use it and find no guidance for the expected format (BIP-39 mnemonic phrase) or behavior.
Code:
Write operations (swap, liquidity, contract send) require a wallet. Set exactly one wallet source:
- `AGENT_WALLET_PRIVATE_KEY` — direct private key
- `AGENT_WALLET_MNEMONIC` — mnemonic phrase
- `AGENT_WALLET_PASSWORD` — encrypted wallet via agent-wallet
Recommendation:
Either document AGENT_WALLET_MNEMONIC in the Agent Wallet CLI Reference and deployment guides (including format, derivation path behavior), or remove it from the SUN CLI FAQ if it is not yet supported. Consistency with other docs is essential to avoid user confusion.
[MINOR-02] SUN CLI CommandGuide: --network Flag Used Post-Subcommand in Example (Known Parser Behavior Not Explained Consistently)
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Documentation & Maintainability |
| File | docs/McpServer-Skills/Tools/SUNCli/FAQ.md : Lines 49-56; docs/McpServer-Skills/Tools/SUNCli/CommandGuide.md : Line 55 |
Description:
The SUN CLI FAQ correctly explains that --network must appear before the subcommand. However, the CommandGuide section on global flags includes an example:
sun -k your_private_key --network nile --yes swap TRX USDT 1000000This example places --network before the subcommand — which is correct — but the FAQ description of the same issue says --network as a subcommand-level flag is wrong, without clearly explaining it's a root-level only flag. Some users will be confused. The CommandGuide also does not reinforce this constraint.
Recommendation:
Add a prominent note in the CommandGuide's Global Flags section that all root-level flags must appear before the subcommand. This is described in the FAQ but should also appear where the flags are defined.
[MINOR-03] quickstart-for-agent.md: Private Key Stored in Shell Profile Without Warning About Shell History
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Security — Sensitive Data |
| File | docs/x402/getting-started/quickstart-for-agent.md : Lines 59-64 |
Description:
The guide recommends persisting AGENT_WALLET_PRIVATE_KEY by appending to .zshrc/.bashrc using:
echo 'export AGENT_WALLET_PRIVATE_KEY=your_key' >> ~/.zshrcWhile the guide does say "Keep your private key only in local environment variables or a .env file", it doesn't mention that the echo command itself (with the literal key as an argument) will be saved to the shell history file. A malicious process or attacker with access to shell history (.bash_history, .zsh_history) can extract the key.
Recommendation:
Add a note to use a text editor to manually add the export line to .zshrc/.bashrc, rather than using echo with the key as an argument. For example:
# Open your shell config in a text editor instead
nano ~/.zshrc
# Add this line manually: export AGENT_WALLET_PRIVATE_KEY=your_key[MINOR-04] BANKOFAISkill.md: Emoji Used in Section Headers
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Code Quality — Naming / Style |
| File | docs/McpServer-Skills/SKILLS/BANKOFAISkill.md : Line 28 |
Description:
The new BANKOFAISkill.md includes emoji in a section header:
### 🔑 Where Do I Get These Keys? How Do I Set Them Up?While not a technical defect, emoji in section headers can cause issues: they may not render correctly in all contexts (RSS feeds, screen readers, some PDF exports), and they can interfere with anchor link generation in static site generators (Docusaurus may generate anchors like --where-do-i-get-these-keys). This is inconsistent with the coding style of the rest of the documentation.
Recommendation:
Remove the emoji from the section header or confirm that Docusaurus handles anchor generation correctly with emoji, and that it aligns with the project's style guide.
[MINOR-05] Redundant Paragraph in TRONMCPServer/LocalPrivatizedDeployment.md
| Property | Value |
|---|---|
| Severity | Minor |
| Category | Code Quality — Duplication |
| File | docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md : Lines 53-57 |
Description:
The "Agent Wallet" section header is immediately followed by a redundant paragraph that repeats the same information already stated in the table above it:
TRON MCP Server uses [Agent Wallet] for wallet management. Private keys are encrypted and stored on local disk, never exposed as plaintext in environment variables. Even if environment variables are leaked, the attacker still needs the encrypted keystore file to access funds. Agent Wallet also supports multi-wallet management and runtime wallet switching via the `select_wallet` tool.
The same text was present in the preceding sentence: "TRON MCP Server uses Agent Wallet for secure wallet management." This duplication adds length without adding clarity.
Recommendation:
Consolidate the introductory paragraph and table. The security explanation can be retained once, ideally in a callout block rather than repeated inline text.
[SUGGESTION-01] quickstart-for-sellers.md: No Step to Verify Facilitator is Running Before Starting API Server
| Property | Value |
|---|---|
| Severity | Suggestion |
| Category | Documentation & Maintainability — User Experience |
| File | docs/x402/getting-started/quickstart-for-sellers.md |
Description:
The self-hosted Facilitator tab in the quickstart guide instructs users to install and configure the Facilitator in Step 3, but does not include a verification step (e.g., curl http://localhost:8001/health) before proceeding to start the API server in Step 2. Because Step 2 is introduced before Step 3, a user who follows steps in order will start the API server pointing at a Facilitator that isn't running yet, leading to confusing connection errors.
Recommendation:
Reorder the steps so Facilitator setup precedes API server startup, or add an explicit "Verify Facilitator is running" step with a curl /health check before the API server is started.
[SUGGESTION-02] SUNCli/CommandGuide.md: Missing Documentation for --dry-run Flag Behavior
| Property | Value |
|---|---|
| Severity | Suggestion |
| Category | Documentation & Maintainability |
| File | docs/McpServer-Skills/Tools/SUNCli/CommandGuide.md : Lines 27, 59 |
Description:
The --dry-run flag is listed in the global flags table with the description "Print intent without sending the write action." However, the CommandGuide does not include any example of --dry-run output in the write command sections (swap, liquidity, contract send). Users trying to use dry-run for the first time will not know what to expect.
Recommendation:
Add a concrete --dry-run output example for at least one major write command (e.g., sun --dry-run swap TRX USDT 1000000) showing what the intent preview looks like.
[SUGGESTION-03] Agent-Wallet/FAQ.md: Windows Support Claim Should Reference Minimum Version
| Property | Value |
|---|---|
| Severity | Suggestion |
| Category | Documentation & Maintainability |
| File | docs/Agent-Wallet/FAQ.md : Lines ~141-143 |
Description:
The FAQ now states "Windows support was added in v2.3.x." However, no corresponding note is added to the Quick Start or SDK Guide pages that were also updated in this PR. Users discovering Windows support via those entry points will have no version context.
Recommendation:
Add a brief note in QuickStart.md and SDK-Guide.md that Windows support requires v2.3.x or later, pointing to the FAQ for more details.
[SUGGESTION-04] sidebars.js and i18n/.../sidebars.js: TOOLS Section Should Align Category Label Casing
| Property | Value |
|---|---|
| Severity | Suggestion |
| Category | Code Quality — Naming Consistency |
| File | sidebars.js : Lines 146-163 |
Description:
The new TOOLS category uses all-caps 'TOOLS' for the label, while sibling categories use mixed case: 'MCP Server', 'SKILLS'. The inconsistency (TOOLS vs SKILLS — one is all-caps, the other is also all-caps, but MCP Server is not) may be intentional for display purposes, but it is worth confirming the style is deliberate.
Recommendation:
Confirm whether the label casing in sidebars.js is intentional, and if so document the convention to keep future additions consistent.
4. Positive Observations
-
Strong Security Messaging Throughout: The SUN CLI documentation consistently includes
:::cautionblocks warning about private key exposure via CLI flags. The CommandGuide explicitly advises preferring environment variables or encrypted agent-wallet storage over-k/--private-key. The security principles callout inTRONMCPServer/LocalPrivatizedDeployment.mdis prominent and clear. -
Excellent Coverage of New SUN CLI Tool: The four new SUN CLI docs (Intro, QuickStart, CommandGuide, FAQ) are comprehensive and well-structured. The CommandGuide (~860 lines) is thorough and well-organized by category. The comparison table between SUN CLI and SUN MCP Server in
Intro.mdis a useful navigational aid. -
Architectural Simplification is Well-Motivated: Removing the three-way wallet mode (Agent Wallet / Private Key / Mnemonic) in favor of a single Agent Wallet system is a sound security improvement. The migration is clearly communicated in both the deployment guides and FAQ, with useful migration instructions.
-
Consistent i18n Mirroring: All English documentation changes are mirrored in the Chinese (
zh-Hans) translation directory. This is a significant maintenance effort that ensures users of both language variants receive up-to-date information simultaneously. -
Good Use of Docusaurus Admonitions: The PR makes good use of
:::tip,:::caution,:::danger, and:::infoblocks to call out important security considerations, recommended paths, and edge cases at appropriate levels of urgency. -
Privy Wallet Documentation is Well-Segregated: The Privy wallet type additions in CLI-Reference and FAQ are additive and non-breaking. The tip blocks clearly explain what Privy is and when to use it, without burying it in the main flow.
-
Link Consistency Improvement: The systematic update from bare paths to
.md-suffixed paths in cross-references improves portability and is consistent with Docusaurus best practices for explicit file references. -
exact_gasfreeScheme is Clearly Documented: The new payment scheme is well-explained with its key differentiators (zero gas cost for buyers, TRON-only, routed via BANK OF AI facilitator) and includes CLI management commands for GasFree account activation.
5. Checklist Results
| Category | Status | Notes |
|---|---|---|
| A. Correctness & Logic | Node.js version mismatch in package.json; FAQ references wrong env var for Path 2 |
|
| B. Security | echo $AGENT_WALLET_PRIVATE_KEY pattern reveals key; echo '...key...' in profile setup goes to shell history |
|
| C. Performance | ✅ Pass | Documentation only; no performance concerns |
| D. Code Quality | Faq.md case issue; redundant paragraph; emoji in header; AGENT_WALLET_MNEMONIC undocumented |
|
| E. Testing | N/A | Documentation PR; no test coverage concerns |
| F. Documentation & Maintainability | Inconsistent link styles; incomplete Windows version context; step ordering in seller quickstart |
6. Review Verdict
Verdict: Request Changes
Rationale
This PR is a substantial, well-organized documentation update that introduces a new major tool (SUN CLI), documents a meaningful architectural change (single-wallet-mode consolidation), and keeps both English and Chinese documentation in sync. The quality of the new SUN CLI documentation is high.
However, the PR has two issues that should be fixed before merge:
-
[MAJOR-01]: The
package.jsonengines.nodefield is not updated to>=20, creating a verifiable inconsistency between the toolchain definition and all user-facing documentation. This may cause CI/CD or contributor environment issues. -
[MAJOR-02]: The
echo $AGENT_WALLET_PRIVATE_KEYverification pattern is a real security risk in user-facing documentation. Multiple new pages instruct users to print their private key to the terminal as a setup verification step. This pattern should be replaced with a safe non-revealing check. -
[MAJOR-03]: The TRON MCP FAQ's guidance for "Wallet not configured" errors only mentions
AGENT_WALLET_PASSWORDbut not the newly-introducedAGENT_WALLET_PRIVATE_KEYpath, leaving Path 2 users with incorrect troubleshooting steps.
The [MAJOR-04] link casing issue (Faq.md vs FAQ.md) should also be confirmed, as it may cause a 404 on case-sensitive file systems (Linux production environments).
Once these issues are addressed, this PR is ready to merge.
2 participants
No description provided.