docs: AI-agent-friendly README + two rounds of API doc review fixes#2
Open
jluxinlan wants to merge 4 commits into
Open
docs: AI-agent-friendly README + two rounds of API doc review fixes#2jluxinlan wants to merge 4 commits into
jluxinlan wants to merge 4 commits into
Conversation
merge to main
Aligns README with the AI Agent API documentation standard so that agents read units, encodings, and side effects unambiguously. - Fix code/doc contradiction: replace SDK examples (getAddressPermission, createWebSocket, ws.on, baseUrl) with the real MultiSigClient API (queryAuth, queryTransactionList, connectWebSocket + onPendingTransaction, baseURL). - Add Data Conventions section: SUN/TRX (1 TRX = 1e6 SUN), timestamp units (ms vs seconds, expire_time marker), Base58 vs Hex address dual-encoding, big-number caveat, empty != error. - Add Presence and Unit/Encoding columns to response field tables for all four endpoints. - Mark POST /multi/transaction as state-changing / irreversible on-chain broadcast. - Add "When to use / When not to use" guidance in overview. - Add "Reading this example" interpretation notes to response examples (raw -> display mapping for SUN and ABI-encoded TRC20 amounts). - Fix invalid JSON: remove inline // comment in WebSocket subscribe example so agents can parse it as-is. - Cross-reference empty != error in Error Codes and per-endpoint notes.
…ontracts Resolves the items flagged by the API-doc review (2026-05-27) so the doc satisfies the §6.6 P0 gate where actionable from this side. P0: - P0-1: align BASE_URL across .env.example, README, and examples/web-react (App.tsx + locales) — all point at walletadapter.org now. - P0-2: error code 20004 description used `version`; should be `sign_version`. - P0-3: document that `contract[].parameter.value` is an object in submit request / list response but a protobuf-hex string in WS push; agents must typeof-branch. Cross-referenced from the WS push field table. - P0-4: WS push example state was 1 (Success) but current_weight < threshold; changed to 0 (Processing) so the example is internally consistent. - P0-5: add Presence + Unit/Encoding columns to raw_data Object table and Presence to the contract Item table. - P0-6: rewrite Error Codes — split HTTP vs business layer, add Retryable and Hint columns, assert the code set is complete (drop "representative examples" caveat), and break Empty != Error into a per-endpoint table. - P0-7: replace the single state-changing callout on POST /multi/transaction with a two-row table (Local Write below threshold vs Remote Write + Destructive at threshold); mark the other three endpoints as Network Read. - P0-10: add an AI Agent End-to-End Acceptance section with the verification protocol and a record table to be filled by the team (the actual run requires real credentials and is out of scope of this commit). P1: - P1-1: add txID, visible, raw_data_hex to the transaction Object table; link operations bitmask to TRON Tron.proto ContractType and give a bit-test snippet; clarify Permission_id maps to active_permissions index. - P1-4: add an API Key tier table (all four endpoints are Required). - P1-5: add §VI Rate Limiting describing 4501 retry semantics, granularity, and Retry-After backoff (QPS values left as TBD for backend ops). Deferred: - P0-9 (one-doc-per-URL + llms.txt) — needs a structural docs/ split or doc-site migration; per user, handled separately. - P0-10 actual run; P1-7 web-react backend-proxy refactor; P1-8/P1-9 changelog and OpenAPI generation.
- P0-C: document signature array as full-set-per-POST (Plan B), covered in 4 places (field table, flow Phase II, core example, acceptance pitfalls) - P0-B: add ref_block_num / auths / scripts to the raw_data field table - P0-A: 20004 hint now lists all 7 common params (was missing `address`) - P1-A: unify function_selector to "Conditional" in both tables - P2-a: add a path-based disambiguation table for the overloaded `data` key - P2-b: explain business-code ranges (4xxx / 2xxxx / 1xxxx) - P2-d: drop the duplicated env table in §IV; cross-reference Quick Start - P2-f: widen WebSocketMessage to TransactionDetail | TransactionDetail[]
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Syncs
devwith the documentation overhaul and review fixes done on the fork.Net: 6 files, +295/-95 — almost entirely docs, plus a BASE_URL correction
across examples and one SDK type fix. Merges cleanly (fast-forward).
Bundles 3 commits:
a9ed781(README rewrite),aa3cf0f(review round 1),d77437f(review round 2).What changed
README.md (bulk)
Rewritten for AI-agent consumption: an agent can complete a full multisig
transfer from the README alone.
Correctness/consistency: unified
BASE_URLtowalletadapter.org; completebusiness error-code table (code / retryable / hint / ranges) with unknown-code
fallback; per-endpoint side-effect annotations (read vs local-write vs
destructive broadcast); API-key tier table; "empty result ≠ error" per endpoint.
Data conventions: SUN/decimals, timestamp units (ms vs s), dual address
encodings (Base58
T…vs Hex41…), and disambiguation of the overloadeddatakey.parameter.valuedual-form (object in request/list vs protobuf-hex in WS push)with
typeof-branch guidance.Signature semantics:
transaction.signatureis submitted as the FULL seteach POST (append to the existing array, not incremental) — covered in 4 places.
raw_datafield table completed (ref_block_num/auths/scripts);function_selectorpresence unified to "Conditional".AI-agent end-to-end acceptance protocol + predicted pitfalls.
.env.example,App.tsx,en-US.json,zh-CN.json:niletest.tronlink.org→apinile.walletadapter.org.SDK type fix
src/types/index.ts:WebSocketMessagewidened toTransactionDetail | TransactionDetail[]to match theonPendingTransactioncallback and runtime (initial array push vs single-object updates).
Notes
Docs/examples/types only — no runtime logic changes. Deferred (separate tracking):
docs/ split + llms.txt, OpenAPI schema, CHANGELOG, web-react backend-proxy
refactor, and the E2E acceptance run.