docs(tbv): align Technical Details + Safety pages with Vlad's updates

[web3jenks]

Summary

Vlad (Vladyslav Horilyi) updated the four Phase-2 TBV pages in Confluence and asked us to align the docs and fix any issues. This PR re-ports all four to match his current sources and re-publishes them (PR #448 had hidden them via draft: true pending these corrections).

Confluence sources:

• Protocol architecture (450101360)
• Safety & trust assumptions (450002958)
• TBV Protocol actors (450003021)
• Aave v4 integration (450035784)

What changed vs. the previous port

The earlier port (PR #443) had editorial additions Vlad has since revised away. Aligning to his rewrite means:

Safety & trust assumptions

• "Self-host your own Vault Provider" framing → "Choose or run a Vault Provider (where provider registration is available)". Added explicit note that the depositor cannot register as an AVK/UC but doesn't need to.
• Added Governance risk and Vault Swap liquidity dependency to the risk surface; "Ethereum light client correctness" → "Cross-chain proof pipeline".
• Dropped the named operator list (RockX/Altlayer/Babylon) and the separate "Public testnet caveats" section.

Protocol actors

• "Vault Keeper" now scopes to VP + AVK only; Universal Challenger is explicitly a separate protocol-level monitor.
• Dropped the "Who runs these actors today" operator-count section and the "Summary of responsibilities" table (not in Vlad's rewrite).

Protocol architecture

• "Burn event proof" → "Redemption proof"; "burn event"/BurnExecuted → "redemption event"/"redemption log".
• Dropped contract code-names and the dedicated "Vault lifecycle and states" section, matching Vlad's streamlined structure.

Aave v4 integration

• vaultBTC described as ERC-20-compatible internal accounting token (explicitly not a wrapped BTC token); position-proxy isolation claim softened; testnet reserves flagged as mock assets.

Throughout: code-identifiers (CouncilNoPayout, ChallengeAssert, VaultRedeemable) replaced with plain language, per Vlad's wording. A few obvious typos in the Confluence source were corrected (Vlad invited direct fixes).

Mechanics preserved

• Frontmatter, local relative .mdx links, existing diagrams, and the consistent end-of-page "Related" nav blocks.
• Restored the "Technical Details" sidebar category and the "Safety & trust assumptions" Start Here entry.

Verification

• Production build (NODE_ENV=production docusaurus build, onBrokenLinks: 'throw') passes; all four routes now build to index.html.
• All cross-links resolve; no draft flags remain.

Note on diagrams

The two embedded diagrams (protocol-architecture/10.png, safety-and-trust-assumptions/7.png) were retained as-is and not re-verified against Confluence this session — full-res attachment download requires a browser session cookie. Their components/actors are unchanged in Vlad's text, but please confirm whether Vlad updated either diagram; if so, they can be refreshed in a follow-up.

🤖 Generated with Claude Code

[github-actions]

🔐 Commit Signature Verification

✅ All 4 commit(s) passed verification

Commit	Author	Signature	Key Type	Key Check
9f8e669df13e	Jenks	✅	sk-ssh-ed25519	✅
ae562d4dc034	Jenks	✅	sk-ssh-ed25519	✅
5278a96a1882	Jenks	✅	sk-ssh-ed25519	✅
f981395701ed	Jenks	✅	sk-ssh-ed25519	✅

Summary

• Commits verified: 4
• Signature check: ✅ All passed
• Key type enforcement: ✅ All sk-ssh-ed25519

---

Required key type: sk-ssh-ed25519 (FIDO2 hardware key)

Last verified: 2026-07-02 05:02 UTC

[greptile-apps]

Greptile Summary

This PR republishes the Phase-2 TBV docs and restores them in navigation. The main changes are:

• Removed draft status from four TBV documentation pages.
• Rewrote the safety, actors, architecture, and Aave integration pages.
• Restored the Safety page and Technical Details category in the sidebar.

Confidence Score: 4/5

The docs are close, but the published safety page needs its public testnet warnings restored.

• The sidebar entries and page publication look structurally sound.
• The safety page can mislead testnet users about state persistence and current operator redundancy.
• The architecture page lost concrete mapping for activation and contract names that sibling docs still rely on.

docs/trustless-bitcoin-vault/start-here/safety-and-trust-assumptions.mdx; docs/trustless-bitcoin-vault/technical-details/protocol-architecture.mdx

Security Review

The safety page no longer states the current public testnet operator set, which weakens the documentation around liveness and challenge assumptions for today’s deployment.

Important Files Changed

Filename	Overview
docs/trustless-bitcoin-vault/start-here/safety-and-trust-assumptions.mdx	Re-published and rewrote the safety page, but removed current public testnet caveats and operator-set details.
docs/trustless-bitcoin-vault/technical-details/aave-v4-integration.mdx	Re-published and updated Aave integration wording, including clearer mock-asset and vaultBTC language.
docs/trustless-bitcoin-vault/technical-details/protocol-actors.mdx	Re-published and rewrote actor definitions, including the narrower Vault Keeper framing.
docs/trustless-bitcoin-vault/technical-details/protocol-architecture.mdx	Re-published and simplified protocol architecture, but lost some concrete contract and activation-call mapping.
sidebars-default.js	Added the Safety page and Technical Details pages back to the TBV sidebar.

_{Reviews (1): Last reviewed commit: "docs(tbv): align Technical Details + Saf..." | Re-trigger Greptile}

[web3jenks]

Diagram verification (follow-up on the note above): pulled the current Confluence attachments for all four pages and compared to the repo. Both embedded diagrams are byte-for-byte identical to what's already committed — no image update needed.

• Protocol architecture 10.png: Confluence attachment version 1, SHA-256 59f31cc208d5e931264ad2d94895916691ed9284cf9bac3335c92890b2a8c64e == repo
• Safety & trust assumptions 7.png: Confluence attachment version 1, SHA-256 98ebb685a6ef45389cbf579ba1f7b165036e1499c10f7545a0510d3d26b14c87 == repo
• Protocol actors & Aave v4 pages: no attachments (no diagrams)

The PR is complete: text aligned to Vlad's current Confluence + diagrams confirmed current.

[web3jenks]

@kkkk666 could you review when you have a chance? 🙏

This aligns the four Technical Details + Safety pages with Vlad's latest Confluence updates (his copy is the source of truth) and re-publishes them (they were temporarily hidden in #448 pending his corrections). All CI is green and the production build passes with no broken links.

One heads-up: the architecture diagram (protocol-architecture page) still needs to be updated — that update will be completed later today. The current diagram is a placeholder pending Vlad's revised version; everything else (prose across all four pages) is final and ready for your review now.

[web3jenks]

Update: the architecture diagram is now in ✅ — Alina's revised version (TBV6-architecture.png from Confluence) replaces the previous one on the protocol-architecture page.

• Full 4K (3840×2160), validated as a coherent architecture diagram matching the page's three-layer structure (Bitcoin vaults → Trustless Protocol → Ethereum protocol + Aave v4 integration) with the Vault Provider / Vault Keeper / Universal Challenger actors.
• Production build passes; no broken links.

The PR is now complete end-to-end (prose + diagram) and ready for review, @kkkk666.

Minor note for a later Confluence tidy-up (not blocking this PR): the diagram image has two cosmetic typos — "non-fungable" (→ non-fungible) and stylized "BaBe" — worth flagging to Alina.

[web3jenks]

Applied review polish from the Codex + Antigravity passes (commit ae562d4):

• vaultBTC units clarified on the Aave page (1 vaultBTC = 1 BTC; smallest unit = 1 satoshi) — removes the '1 BTC' vs 'one satoshi' ambiguity both reviewers flagged.
• Minor grammar/terminology polish: 'Assert transaction', 'wrongly challenged transaction', 'batched Pre-PegIn transaction', de-run-on the self-refund sentence, a couple of missing commas, 'target level'.

Two substantive items live in Vlad's source-of-truth Confluence, so rather than diverge here I raised them as inline comments for him to confirm/backport:

• Aave / vaultBTC wording: https://babylonlabs.atlassian.net/wiki/spaces/BABYLON/pages/450035784/Aave+v4+integration?focusedCommentId=480346173
• Safety / fee-refund timeout wording (setup-ack ~24h vs activation ~48h): https://babylonlabs.atlassian.net/wiki/spaces/BABYLON/pages/450002958/Safety+trust+assumptions?focusedCommentId=480378964

Note: Antigravity's backtick 'medium' findings were checked and rejected — those identifiers are already backticked. Build passes; no broken links.

[web3jenks]

Diagram audit + settled architecture edits (commit 9f8e669):

Diagram alignment — audited every TBV docs diagram against the canonical folder (TBV1–TBV6). 5 of 6 were already byte-for-byte current (TBV1/TBV2 on what-is-tbv, TBV4/TBV5 on how-it-works, TBV6 on protocol-architecture). Added the one missing canonical diagram, TBV3-LIQUIDATION.png, to use-for-lending/liquidation-risk.mdx (it was in the set but unused). Safety 7.png kept as-is (no counterpart in the canonical set).

Architecture text — applied 5 settled edits that resolve open Confluence review comments: dropped the 'Bitcoin and Ethereum layers are shared' sentence; 'surrounded by' → 'locked by'; removed the depositor + Security-Council-multisig lines from Participants; dropped the '(about 24 hours)' and 'activation timeout window (about 48 hours)' figures. Contested/WIP edits (BTCVault/UTXO terminology, VP/UC-as-challenger, the currently-broken Assert bullet) were deliberately skipped pending Vlad finalizing those threads.

Build passes; no broken links.

FYI for Alina — source-side typos inside the diagram images (not fixable here): 'non-fungable' (architecture/vaultBTC), 'BaBe', and 'untoched' (TBV3 liquidation).