Skip to content

feat: TON family support (ton, ton-testnet)#286

Open
artemrootman wants to merge 4 commits into
arootman/starknet-supportfrom
arootman/ton-support
Open

feat: TON family support (ton, ton-testnet)#286
artemrootman wants to merge 4 commits into
arootman/starknet-supportfrom
arootman/ton-support

Conversation

@artemrootman

Copy link
Copy Markdown
Contributor

What

Adds the TON blockchain family (BlockchainType = "ton") — a REST family with the chain's real two-API split: the toncenter v2 HTTP API on the primary rest connector (base URL carries /api/v2) and the v3 indexer on rest-additional, routed statically by the method specs (58 methods: 31 v2 + 27 v3; upstreams without a v3 connector never advertise v3 methods).

Design doc: docs/superpowers/specs/2026-07-17-ton-support-design.md.

Stacked on #285 (starknet family); will retarget as the stack merges.

How

  • ton_specific: poll head via getMasterchainInfo (last.seqno + base64 root_hash); the masterchain is BFT-final, so latest == finalized. EmptyHash parent instead of dshackle's random-string hack.
  • Race-free chain validation: compares the network zerostate hashes from getMasterchainInfo.init — one call, immune to the tonlib masterchain-ref race that forced dshackle to ship disable_upstream_validation for ton. Testnet zerostate verified against the public endpoint.
  • Liveness health validation (dshackle has none for ton).
  • ton_labels: client type/version from the v2 openapi.json (TON HTTP API C++ton-http-api-cpp).
  • ton_bounds: verified-archive probe (lookupBlock seqno=1, generous timeout); non-archival liteservers report an honest UnknownBound, and a not-in-db answer clears any stale cached bound.
  • No envelope surgery needed: v2's {"ok":false,"error":...,"code":N} errors arrive as non-2xx with a structured body the existing REST error parsing already understands, and bodies pass to clients byte-exact with status parity.

Testing

  • Unit tests across all new packages (incl. testnet-zerostate cross-check and the not-in-db cache-clearing bound path).
  • Live corpus against the production mainnet node: 27/27 identical (v2 compared modulo the volatile @extra field), including HTTP-status parity on all error passthroughs and the v3 empty-200 semantics. Details in the design doc.

REST family with the two-connector split the chain actually has: the v2
HTTP API on the primary rest connector (base URL carries /api/v2) and the
v3 indexer on rest-additional - method specs route the 58-method surface
(31 v2 + 27 v3) statically, upstreams without a v3 connector never
advertise v3 methods.

- ton_specific: poll head via getMasterchainInfo (masterchain is BFT-final,
  latest == finalized); EmptyHash parent instead of dshackle's random-string
  hack.
- ton_validations: race-free chain validation via the zerostate hashes in
  getMasterchainInfo.init (one call; avoids the tonlib masterchain-ref race
  that made dshackle disable ton validation entirely; testnet zerostate
  verified against the public endpoint) + liveness health (dshackle has
  none).
- ton_labels: client type/version from the v2 openapi.json document
  (TON HTTP API C++ -> ton-http-api-cpp).
- ton_bounds: verified-archive probe (lookupBlock seqno=1, 30s probe
  timeout); non-archival liteservers report an honest UnknownBound and a
  not-in-db result clears any stale cached bound.
- registry: getMethodSpecName ton case + factory case.
- v2 error envelope needs no new code: non-2xx bodies parse through the
  existing structured REST error path and pass to clients byte-exact.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant