Designed SVG diagrams + upgrade-date fix (follow-up to #436) - #451
Merged
Conversation
Every architecture and bridging diagram was a light-pastel Lucidchart PNG on a dark-only site. All are redrawn as inline SVGs in the docs' visual language (stepped dark surfaces, mono uppercase zone kickers, Etherlink-green vs Tezos-blue lanes, 12px radii), matching the new overview diagram: - network/architecture.md: high-level + full transaction-flow diagrams. Content updated for Etherlink 7.0 - EVM nodes now show both the Ethereum JSON-RPC and Tezos RPC endpoints (the old PNGs predated the Michelson interface), with a matching sentence added to the Nodes section. The full diagram folds the two observer hops into one stacked node and drops the '...other blocks' chain ends (the hash-of-previous-block bullet already conveys chaining). - overview/architecture.md: the NAC call-sequence mermaid diagram is now a designed SVG sequence (lane-colored participants, dashed returns, the atomicity note as the white-pill emphasis element). - bridging-tezos.md, bridging-fa-how.md, bridging-evm.mdx: all five bridging diagrams redrawn with the same zones (Clients / Tezos Layer 1 / Etherlink / LayerZero), faithful to the original flows. The seven replaced PNGs are deleted (no remaining references); wab-details.png stays - it is a product screenshot, not a diagram. All pages verified visually on a local build. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Design-system floor for captions: the mono connector labels and bullet lists sat at 9.5-10.5px, rendering below comfortable reading size in the ~640px content column. Raised across the board (labels 10.5 -> 11.5, bullets 10 -> 11 with taller line-height, section labels 11 -> 12), and fixed the overflows the larger type introduced: wrapped bullets that touched zone borders, split two labels onto two lines, stacked the FA 'ticket + data' label around its arrow instead of across the neighboring cards. Verified on a local build (network architecture + tez bridging pages spot-checked at final size). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- 'store tez, create ticket' collided with the commitment block: split onto two lines right of the self-loop - the 'include in commitment' block floated outside the zone against the canvas edge: recentered under the elbow, inside the Etherlink zone, as 'include in commitment: (ticket, user's layer 1 address)' - the send-transaction bullets ran past the Clients zone bottom: zone made taller Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…overlap The 'trigger outbox message' and 'send transaction' edges landed on the Smart Rollup outbox 5px apart, reading as a doubled arrow: the trigger edge now enters the outbox's left side through the helper gap (widened to fit the 'send ticket' label), while the proxy edge keeps the bottom entry. The send-transaction bullet block also ran into the EVM wallet card - moved up clear of it, and the blue 'send transaction' label anchored inside the Etherlink zone. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
An independent reviewer (fresh context, playing a Solidity developer reading the docs for the first time) audited all nine diagrams. Fixes, by their ranking: Blocking: - withdrawal flows had no reading order: all four bridge diagrams now carry numbered step chips (1..n) in the lane color - withdrawals silently implied deposit-like latency: both now annotate 'after the commitment is cemented (~2 weeks)' on the trigger step - network architecture 'track' arrows pointed INTO layer 1 while their labels described reading FROM it: flipped - fa-withdrawal's proxy->outbox hop said 'send transaction' (wrong vocabulary, wrong mental model): now 'queue outbox message', and the precompile->proxy hop is labeled 'burn tokens' Nice-to-have: - jargon sub-labels: Null precompile '0x0000...0000', Delayed inbox 'forced inclusion', Octez client 'anyone can run it', high-latency node 'trusts only layer-1-final state', 'verify L1 finality' - fa-deposit: 'take tokens' -> 'transfer tokens' (asset vocabulary), send ticket / send tokens labels each moved onto their own arrow, 'ticket + data' repositioned off the arrow line - arch-high-level: 'send blocks' vs 'publish blocks and commitments' disambiguated Cosmetic: self-loops get arrowheads and repositioned labels, deeper hanging indent in the BLOCK bullet list, NAC pill arrowheads now point outward at the runtimes, assorted clearance nudges. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Checked every bridge diagram against the numbered step list on its own page. Two real divergences found and fixed in the FA withdrawal diagram (both inherited from the old PNG, which already contradicted its page): - the entry point is the FA bridging precompiled contract (0xff00...0002, same as deposits), not a separate 'FA withdrawal precompile' - renamed, with the address as a sub-label like the text - the tokens exit through the helper contract (ticketer burns the ticket and returns tokens to the helper, which sends them to the target layer 1 address) - the diagram sent them straight from the ticketer to the wallet. Rerouted; the 8 step chips now map 1:1 onto the page's 8 numbered steps. Also for text/diagram coherence: the tez withdrawal precompile carries its address (0xff00...0001) like the page links it, and FA withdrawal's 'Any user' notes 'via an Octez client' as the text says (matching the tez withdrawal diagram). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Merged
saroupille
force-pushed
the
diagrams-followup
branch
from
August 19, 2026 20:39
805a14b to
25d265b
Compare
- michelson/wallet-support pointed Mainnet users at the tezos-x previewnet GitHub repo for RPC endpoints: now links Michelson network information (Previewnet endpoint referenced for testing) - michelson/getting-started 'Get tez' dead-ended on a page whose faucet row says 'not yet available': now gives the three concrete routes (Previewnet faucet for testing, bridge from layer 1 on Mainnet, network information for Shadownet faucet status) - michelson/getting-started claimed TzKT displays Michelson-interface operations while network information says no indexer is available: qualified as in progress - websockets.md said Instant Confirmations need octez-evm-node 0.49; transactions.md and upgrades.md say 0.52: aligned on 0.52 - rpc-reference constants row: '660,000 gas (~30M EVM gas / 22)' was bad arithmetic - verified against the kernel (tezlink_constants.ml): 30M EVM gas x 22 milligas / 1000 = 660k gas; also explained why minimal_block_delay reads 1s (protocol encoding cannot express sub-second periods) vs the 500ms cadence - progress/upgrades Ganesha section now carries the octez-evm-node >= 0.64 requirement like other upgrade sections do - the '/tezlink' legacy-path hedge now appears at every occurrence (rpc-reference, evm-nodes), and the potluck example describes its contracts/tezlink/ directory as the Michelson-interface contract Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- fa-bridging-transactions: tie the two-week refutation period to the ~15-day end-to-end withdrawal time in one sentence (the other 'two weeks' mentions correctly describe the refutation period itself and stand as written) - conref partials (cementing-delay, gas-price-warning, rate-limit) published as orphan context-less pages: renamed with the underscore prefix so Docusaurus excludes them from routing and search; imports updated - websockets subscription example used chain id 0x1f308 (127752), which is no documented network: now Shadownet (0x1f34f) - 'Self-address test' page retitled 'Aliases and caller-equals-self' (same content, same URL) - sidebar: michelson/tools/dapps moved from the Developing category to Tools where it lives on disk - the three Michelson stub pages (smart contracts, tokens, dapps) now carry a caveat box naming the layer 1 differences that affect those exact workflows (partial simulate_operation, async injection not honored, 1 mutez/byte storage) with links to the compatibility and RPC reference pages Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- typos: desscribed, developping, 'you own tokens', 'the the', 'Uses can subscribe', 'A Etherlink' (x2), heading colon - glossary: drop the 'planned to be fused' meta-note - michelson network information: https:// scheme on both endpoints - evm/index: drop the '(formerly the only developer experience)' historical scaffolding - homepage: '<500ms confirmation times' overstated the ~500ms block cadence; now 'around 500 ms' Left deliberately: the Ebisu section's missing activation date (not verifiable from the repo), the temporary relayer URL (tracked in an HTML comment), and third-party repo URLs. Full docusaurus build passes after the batch (broken-links check throws on failure); the conref partials no longer publish as pages. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…e, complete michelson/bridging
Counter-check of the FA withdrawal flow against the deployed bridge
contracts (baking-bad/etherlink-bridge):
- ticketer.mligo 'withdraw' sends the unlocked tokens DIRECTLY to the
receiver from the routing info ('Token.send_transfer ... receiver'),
and token-bridge-helper.mligo 'withdraw' is a stateless pass-through
that forwards {receiver; ticket} 'keeping the same routing
information'. The page text claiming the helper stores the address,
receives the tokens from the ticketer, and forwards them was wrong -
rewritten (8 -> 6 steps). The diagram returns to the direct
ticketer -> wallet exit (7 step chips) accordingly.
michelson/bridging is no longer a stub:
- deposits: native tez bridges from layer 1 straight to tz* accounts
via the same bridge flow with Michelson routing data (the kernel
rejects KT1 receivers) - script reference in the bridge repository
until the web UI supports it
- withdrawals: no direct Michelson-side path yet; interim route via an
EVM-interface account's Michelson alias and the standard EVM
withdrawal
- FA tokens: unchanged design rationale (single canonical wrap on the
EVM side, used via NAC)
Full build passes (anchor and links checked).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Independent verification pass confirmed all 14 previous fixes landed with no regressions and fact-checked the rewritten FA withdrawal flow and the new michelson/bridging page against the bridge contract sources. Remaining items, all fixed here: - bridging-fa-how: 'generates calls the withdrawal endpoint' (garbled, pre-existing) -> 'calls the withdrawal endpoint' - compatibility: orphaned 'including the following ones' with no list; stale 'Self-address test' link text after the retitle - overview/architecture: sentence-ending colon promised a call diagram that sits a section later; first-person aside about the EVM-node naming recast as a neutral note - FA withdrawal aria-label attributed the outbox message to the precompile while the page text (correctly) attributes it to the proxy: aligned Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Deliberate branding exception to the Etherlink-only rule: the preview network is named Tezos X Previewnet (matching its endpoints, faucet, and repository), not Etherlink Previewnet. Renamed the page title, the section headings, and every prose mention accordingly; no anchor references pointed at the renamed headings, and the full build passes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
francoisthire
approved these changes
Aug 20, 2026
francoisthire
left a comment
francoisthire
left a comment
There was a problem hiding this comment.
Reviewed batch by batch: designed diagram set (validated visually and against each page's step lists), three audit batches from the independent full-site review, the FA withdrawal correction verified against the bridge contract sources, the completed Michelson bridging page, and the Tezos X Previewnet naming. Two independent audit passes confirm all fixes landed with no regressions; full builds pass throughout.
ethereum.org migrated its JSON-RPC page anchors from underscores to hyphens (#eth_getbalance -> #eth-getbalance), which broke 13 external- anchor checks in CI. Updated all fragments in information.md and transactions.md, and normalized the one /en/-less URL. The remaining CI failure (layerzeroscan.com) is the site rate-limiting the checker (HTTP 429), not a dead link - unchanged. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Collaborator
It looks like the |
The {/* TX */}-style rebranding markers leak wherever MDX stringifies
raw heading/paragraph text: page outlines rendered 'Etherlink/* TX */
Mainnet' and meta descriptions carried 'Etherlink{/ TX /}'. HTML
comments (<!--TX-->), already used in every .md file, are invisible in
all of those surfaces (verified on the built site), and the MDX
pipeline supports them in .mdx too. Converted all 175 markers across
13 .mdx files; the markers remain greppable in source for the future
rename.
Reported by @skenaja on #451.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
Author
|
Good catch — reproduced and fixed in |
skenaja
approved these changes
Aug 20, 2026
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
3 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.
Follow-up to #436, which reached
maintoday via the #443 merge (its branch was based onimport-tx-doc), taking the Etherlink 7 docs to production ahead of Thursday's plan.Contents (reviewable batch by batch, one commit each):
0xff0...0002; tokens exit through the helper contract), validated against each page's own step list./tezlinklegacy-path hedge at every occurrence.Docs are written as the post-activation state (per PM decision) — no "expected 20 August" gating was added;
progress/upgrades.mdkeeps "went live on 20 August 2026", which becomes true at activation. Fulldocusaurus buildpasses after each batch.🤖 Generated with Claude Code