Update Verify Trustlines guide to use RPC instead of Horizon

[wmendes]

Fixes #1743 (child of #1529).

Removes the Horizon section and rebuilds the RPC section around the modern JS SDK helpers.

What changed

• Deleted ## Checking a Trustline through the Horizon API. Matches @ElliotFriend's note on the issue and the sibling migrations (Update Fee-bump transactions to use rpc instead of horizon #1769, Update sponsored reserve examples to use RPC in both languages #1779, commit for claimable balance rework to use RPC in the docs #1784, Update "Create Account" tutorial to use RPC #1786, Update clawback docs to use RPC instead of horizon #1793), which all stripped Horizon code rather than demoting it. The only remaining mention of Horizon is a prose link to the official Migrate from Horizon to RPC page, whose GET /accounts/{address} row documents exactly the gap this guide fills: "RPC will not provide trust line information associated with the account directly, as Horizon does. You will need to derive this from ledger entries."
• Split the RPC section in two. getAssetBalance is the quick path for "does this trustline exist and is it authorized"; getLedgerEntries is only needed for the trustline limit, which BalanceResponse doesn't surface.

Bugs fixed along the way

The RPC section already existed, but it wasn't in shape to be promoted as the primary path:

• Private API. It called rpc._getLedgerEntries(key) and therefore hand-decoded xdr.LedgerEntryData.fromXDR(entry.xdr, "base64"). The public getLedgerEntries returns entries[].val already decoded.
• Flags bitmask bug. if (trustlineData.flags() !== 1) is wrong — trustline flags are a bitfield. An authorized and clawback-enabled trustline has flags() === 5 and was falsely reported "not authorized". Now !(flags() & 1), which is what the SDK itself does.
• Stale receiver. GCLNZP3W… returns 404 on Testnet — wiped by a reset, so the snippet threw at step 1 for anyone copy-pasting. Replaced with a "G..." placeholder plus a comment on creating one, so it can't go stale again.
• SAC section: authorized doesn't return false for a missing trustline. The simulation fails with Error(Contract, #13) (trustline entry is missing for account) instead, so the prose now says which branch handles which case.
• SAC bindings package name. The command wrote to --output-dir=./bindings (package name bindings) while the snippet did import { Client } from "sac" — that import cannot resolve. Command now points at ./sac.
• Removed a commented-out xlmClient.transfer({...}) block referencing undefined variables, and fixed "conver" / "addresss" / "cient" / "Now we defined".

Testing

Every snippet was run against Testnet with @stellar/stellar-sdk@16.2.0:

Case	Result
getAssetBalance, trustline present	authorized: true, balance 1252.7872975
getAssetBalance, no trustline	Throws Trustline for USDC:… not found — hence try/catch, not if (!balanceEntry)
getLedgerEntries → entries[0].val.trustLine()	flags() === 1, limit and balance read correctly
getLedgerEntries, no trustline	entries: [], no throw
Insufficient limit	Created an account with changeTrust limit 0.5; the limit - balance < sendingAmount branch fires
SAC authorized, trustline present	Returns true
SAC authorized, no trustline	Simulation fails with Error(Contract, #13)
Bindings command	Regenerated; package name resolves as sac and builds

pnpm build and pnpm check:mdx both pass.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Updates the “Verify Trustlines” guide to use Stellar RPC-first patterns (including getAssetBalance and getLedgerEntries) and clarifies how to check existence, authorization, and limits for trustlines and SAC authorization.

Changes:

• Replaces older trustline-check examples with RPC-focused approaches (getAssetBalance, getLedgerEntries) and adds guidance on when to use each.
• Adds a dedicated section on checking trustline limits and improves the trustline-flags authorization logic.
• Clarifies SAC authorized behavior, especially the “missing trustline” simulation failure case.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[stellar-jenkins-ci]

Preview is available here:
http://developers-pr2760.previews.kube001.services.stellar-ops.com

[wmendes]

Worked through the Copilot review. Two comments were correct and are now fixed, one was correct in spirit but not fixable as suggested, one was wrong, and one was a false premise. Everything was checked against Testnet rather than reasoned about.

Fixed — int64 precision (limit / balance lines). Real bug. Trustline limits routinely sit at the int64 maximum (922,337,203,685.4775807), roughly 1024x above 2^53 - 1, so Number() rounding was ~2048 stroops. With the limit at maximum and 1000 stroops of headroom, sending 0.0001 was reported as exceeding the limit — a false rejection of a valid payment. The snippet now stays in BigInt stroops end to end, with a string-wise toStroops helper (Math.round(parseFloat(x) * 1e7) would reintroduce the same error). Links Amount precision.

Fixed differently — error conflation on getAssetBalance. The concern is real, but inspecting the error shape can't work: the SDK's getTrustline has a bare catch that discards the original error and always throws the same "not found" message. Against a dead endpoint, getAssetBalance reports "trustline not found" while getLedgerEntries correctly raises an AxiosError. So the example now rethrows the original error, says "could not confirm a trustline", and a warning documents the caveat and points at getLedgerEntries for callers that must distinguish. I'll raise the swallowed error upstream on js-stellar-sdk.

Not a bug — amount units. balanceEntry.amount is stroops, built from tl.balance().toString(). Same trustline: Horizon reports 1252.7872975, getAssetBalance returns "12527872975". The / 10 ** 7 was right. That said, the comment pointed at a real adjacent problem — Number(amount) is unsafe for large int64 balances — so I removed that arithmetic and report the stroops string directly.

Not applicable — "docs/build/ is a generated artifact". It's the Build section of the docs site, hand-authored and git-tracked. Docusaurus output goes to build/ at the repo root, and .gitignore has no docs/ entry.

Re-verified after the changes: toStroops round-trips the int64 maximum exactly; all four previously-misjudged precision cases now resolve correctly; the trustline-present, missing-trustline, and insufficient-limit paths all behave as documented against Testnet (including a 0.4-under-a-0.5-limit case that must pass). pnpm build and pnpm check:mdx pass.

[stellar-jenkins-ci]

Preview is available here:
http://developers-pr2760.previews.kube001.services.stellar-ops.com