docs(website): add Use Cases section with Light Wallets, Bridges; add Case Studies section with Daedalus by dalibran · Pull Request #3200 · input-output-hk/mithril

dalibran · 2026-04-14T18:35:53Z

Summary

Adds a Use Cases dropdown to the navbar, positioned between Manual and Protocol
Renames navbar labels: "User manual" → "Manual", "About Mithril" → "Protocol"
Adds a Wallets use case page (/use-cases/wallets) covering two audiences:
- Wallet developers: value prop, how Mithril fits existing stack, integration guide, Discord CTA
- Wallet users: plain-language explanation of what Mithril-enabled wallets mean for them
Includes a caution admonition noting protocol security scales with SPO participation — the client is production-ready but full production wallet deployment should wait for sufficient stake coverage
Adds useCasesSideBar to sidebars.js and version-maintained-sidebars.json
Mirrors new docs into versioned_docs/version-maintained/ to support the version dropdown

Notes for reviewers

The caution admonition wording around stake participation thresholds is intentionally vague — flagging for technical review to sharpen the specific threshold language
The version dropdown label/ordering is a separate open question flagged for future discussion

Test plan

Verify Use Cases dropdown appears in navbar and links correctly
Verify Wallets page renders correctly in both current and maintained versions
Verify caution and note admonitions render correctly
Verify Discord button opens correct channel
Check right-side TOC shows correct heading hierarchy

🤖 Generated with Claude Code

- Add Use Cases dropdown to navbar (between Manual and Protocol) - Rename navbar labels: "User manual" → "Manual", "About Mithril" → "Protocol" - Add Wallets use case page covering developer and end-user audiences - Add useCasesSideBar to sidebars.js and versioned sidebars - Wallet page includes: security caution admonition, integration guide, Discord CTA button, and note on server membership Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions · 2026-04-14T18:57:15Z

Test Results

5 files ± 0 203 suites +4 54m 12s ⏱️ - 25m 40s
3 058 tests +128 3 058 ✅ +128 0 💤 ±0 0 ❌ ±0
10 457 runs +161 10 457 ✅ +161 0 💤 ±0 0 ❌ ±0

Results for commit 1166231. ± Comparison against base commit c064115.

This pull request removes 157 and adds 285 tests. Note that renamed tests count towards both.

mithril-aggregator ‑ database::query::signed_entity::get_signed_entity::tests::test_get_record_by_id
mithril-client ‑ file_downloader::http::tests::test_download_http_file_send_feedback
mithril-client ‑ file_downloader::http::tests::test_download_local_file_send_feedback
mithril-common ‑ crypto_helper::merkle_map::tests::get_keys
mithril-common ‑ crypto_helper::merkle_map::tests::test_mk_map_replace_should_accept_replacement_with_same_root_value
mithril-common ‑ crypto_helper::merkle_map::tests::test_mk_map_replace_should_reject_replacement_if_key_doesnt_exist
mithril-common ‑ crypto_helper::merkle_map::tests::test_mk_map_replace_should_reject_replacement_with_different_root_value
mithril-common ‑ crypto_helper::merkle_map::tests::test_mk_map_should_accept_replacement_with_same_root_value
mithril-common ‑ crypto_helper::merkle_map::tests::test_mk_map_should_clone_and_compute_same_root
mithril-common ‑ crypto_helper::merkle_map::tests::test_mk_map_should_compress_correctly
…

mithril-aggregator ‑ database::query::signed_entity::get_signed_entity::tests::test_get_record_by_id_and_signed_entity_type
mithril-aggregator ‑ database::query::signed_entity::get_signed_entity::tests::test_get_record_by_id_and_signed_entity_type_must_return_none_if_signed_entity_type_does_not_match
mithril-client ‑ file_downloader::http::tests::downloading_http_file_handle_early_unpack_receiver_closure
mithril-client ‑ file_downloader::http::tests::downloading_http_file_send_feedback
mithril-client ‑ file_downloader::http::tests::downloading_local_file_handle_early_unpack_receiver_closure
mithril-client ‑ file_downloader::http::tests::downloading_local_file_send_feedback
mithril-client-cli ‑ commands::tools::utxo_hd::snapshot_converter::tests::calculate_number_of_steps::returns_1_when_local_bin_mode_is_true_and_commit_is_false
mithril-client-cli ‑ commands::tools::utxo_hd::snapshot_converter::tests::calculate_number_of_steps::returns_2_when_local_bin_mode_is_true_and_commit_is_true
mithril-client-cli ‑ commands::tools::utxo_hd::snapshot_converter::tests::calculate_number_of_steps::returns_3_when_local_bin_mode_is_false_and_commit_is_false
mithril-client-cli ‑ commands::tools::utxo_hd::snapshot_converter::tests::calculate_number_of_steps::returns_4_when_local_bin_mode_is_false_and_commit_is_true
…

♻️ This comment has been updated with latest results.

Wrap button text in a span to prevent MDX from injecting a paragraph element with inherited margin-bottom, and use explicit height on the anchor for reliable vertical centering. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-authored-by: Jean-Philippe Raynaud <jp.raynaud@gmail.com>

Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com>

- Rename page/sidebar label to "Light wallets" (sentence case) - Move Use Cases dropdown to end of left navbar - Remove unused spoCta note about IOG Discord membership - Update browser support paragraph with compatibility link, example, and Rust crate link - Remove "For wallet developers" title casing Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Remove specific security caveat content from the caution admonition, replacing it with a neutral info admonition pointing to the Protocol security page. Drop the Swift/Kotlin mobile bindings paragraph. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

jpraynaud · 2026-04-24T08:49:25Z

Maybe we just need a .md file here as this is only static content?

If we want to keep the styled discord button, then we need .mdx. I can remove the button if you don't think it adds much.

Adds a Bridges page under Use Cases following the same structure as Light wallets. Wires it into the Use Cases navbar dropdown and mirrors the page into the maintained docs version. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Introduce a Case Studies docs section with a Daedalus entry covering Mithril-based initial sync, including navbar dropdown, sidebar, and wordmark styling. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

jpraynaud · 2026-05-13T07:55:46Z

+The easiest path for most bridge teams to integrate is using the official WASM package:
+
+```bash
+npm install @mithril-dev/mithril-client-wasm
+```
+
+It works in Node.js and in the browser, making it suitable for relayers, monitoring services, and validator software. All major browsers are supported — see the [Browser Compatibility](https://www.npmjs.com/package/@mithril-dev/mithril-client-wasm#browser-compatibility) section of the npm package for details. A [Rust crate](https://crates.io/crates/mithril-client) is also available for native services.


This should primarily be the Rust client library or the Client CLI.

jpraynaud · 2026-05-13T15:02:54Z

+
+## How Mithril helps
+
+Fresh installations of Daedalus now download a Mithril-certified snapshot of the Cardano node database and restore it locally, rather than replaying the chain. The snapshot's integrity is verified against the Mithril certificate chain, anchored in Cardano's stake distribution — so users get the same trust guarantees as a chain-replayed node, without the wait.


Maybe you can specify how long it takes with Mithril: usually 30min to 1h depending on hardware and internet connection.

jpraynaud · 2026-05-13T15:06:51Z

+sidebar_label: Bridges
+---
+
+# Using Mithril for bridges


This can also be applied to other layer 2 solutions I guess.

jpraynaud · 2026-05-13T15:10:08Z

+
+When a user locks assets on Cardano, the bridge needs to confirm that the lock transaction was included on-chain before authorizing the corresponding action on the destination chain. With Mithril, the bridge can verify this using a Merkle proof linked to a certificate signed by a stake-weighted quorum of SPOs. The proof can be checked locally, without trusting the source of the data.
+
+This changes the bridge's security posture. The integrity of cross-chain transfers no longer depends on the honesty of any single data provider or on the operational security of any one node. A compromised API, a misconfigured indexer, or a hostile relayer cannot produce a valid Mithril proof — and a bridge that verifies proofs will reject anything that fails verification.


This part is not very clear: "and a bridge that verifies proofs will reject anything that fails verification."

jpraynaud · 2026-05-13T15:12:23Z

+
+### How it fits into existing bridge architectures
+
+Most bridges have an off-chain component — relayers, validators, or watchers — that observes events on the source chain and submits attestations to the destination chain. Mithril does not replace this component. It strengthens it: instead of trusting whatever endpoint the relayer happens to query, the relayer verifies a Mithril proof against the current certificate chain before treating a Cardano transaction as final.


"final": it'd be better to say "certified".

jpraynaud · 2026-05-13T15:17:50Z

+1. Observe the lock or burn transaction on Cardano
+2. Query the Mithril aggregator for a transaction proof once the tx hash is known
+3. Verify the proof against the current Mithril certificate chain
+4. Treat the transaction as final and authorize the corresponding action on the destination chain.


Finality is a bit more complex:

with the legacy certification the transcactions are considered very likely final after 100 blocks. This may be enough for small transactions but not for bigger ones

with the upcoming certification, the criterion to determine if a transaction is considered final is left to the end user (who can use the depth from the tip of the chain at snapshot time to make a choice).

This also applies to the next paragraph.

jpraynaud · 2026-05-13T15:20:53Z

+
+## For bridge users
+
+When a bridge supports Mithril, cross-chain transfers from Cardano are more secure. Whether you interact with the bridge directly, or through a wallet or aggregator that abstracts the swap behind a simpler interface, the underlying assertion is the same: that your Cardano transaction was actually included on-chain before the bridge took action on the other side.


The term aggregator is ambiguous here.

By aggregator I meant something like Jumper / Li.Fi that is aggregating different routes across various exchanges, bridges, etc. I will update the language

Co-authored-by: Jean-Philippe Raynaud <jp.raynaud@gmail.com>

Replace the standalone Light Wallets page with a Wallets landing that introduces both wallet shapes and surfaces the Light wallets integration guide and the Daedalus case study as cards. Merge the separate Case Studies section into Use Cases so the Daedalus study lives under Wallets in the sidebar. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

dalibran self-assigned this Apr 14, 2026

dalibran requested review from jpraynaud and olgahryniuk April 14, 2026 18:36

docs(website): fix prettier formatting on wallet use case pages

7fa7a6c

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

dalibran temporarily deployed to testing-preview April 14, 2026 18:59 — with GitHub Actions Inactive

jpraynaud requested changes Apr 15, 2026

View reviewed changes

olgahryniuk approved these changes Apr 17, 2026

View reviewed changes

dalibran and others added 11 commits April 17, 2026 12:03

Update docs/website/root/use-cases/wallets.mdx

9fdf48b

Co-authored-by: Jean-Philippe Raynaud <jp.raynaud@gmail.com>

Update docs/website/root/use-cases/wallets.mdx

88c6c2f

Co-authored-by: Jean-Philippe Raynaud <jp.raynaud@gmail.com>

Update docs/website/root/use-cases/wallets.mdx

f285b0f

Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com>

Update docs/website/root/use-cases/wallets.mdx

dd964ca

Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com>

Update docs/website/root/use-cases/wallets.mdx

0ba1d7a

Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com>

Update docs/website/root/use-cases/wallets.mdx

b6afce5

Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com>

Update docs/website/root/use-cases/wallets.mdx

7c5510d

Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com>

Update docs/website/root/use-cases/wallets.mdx

28be924

Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com>

Update docs/website/root/use-cases/wallets.mdx

c24ec10

Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com>

Update docs/website/root/use-cases/wallets.mdx

38d2f26

Co-authored-by: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com>

dalibran mentioned this pull request Apr 17, 2026

Improving Mithril Documentation #3013

Open

dalibran linked an issue Apr 17, 2026 that may be closed by this pull request

Improving Mithril Documentation #3013

Open

dalibran temporarily deployed to testing-preview April 17, 2026 19:59 — with GitHub Actions Inactive

jpraynaud reviewed Apr 24, 2026

View reviewed changes

dalibran and others added 2 commits May 13, 2026 15:08

docs(website): add Daedalus case study page

3388129

Introduce a Case Studies docs section with a Daedalus entry covering Mithril-based initial sync, including navbar dropdown, sidebar, and wordmark styling. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

dalibran changed the title ~~docs(website): add Use Cases section with Wallet integration guide~~ docs(website): add Use Cases section with Light Wallets, Bridges; add Case Studies section with Daedalus May 13, 2026

jpraynaud reviewed May 13, 2026

View reviewed changes

dalibran and others added 3 commits May 14, 2026 15:56

Update docs/website/root/case-studies/daedalus.mdx

f8219ac

Co-authored-by: Jean-Philippe Raynaud <jp.raynaud@gmail.com>

Update docs/website/root/use-cases/bridges.mdx

0daea07

Co-authored-by: Jean-Philippe Raynaud <jp.raynaud@gmail.com>


		## How Mithril helps

		Fresh installations of Daedalus now download a Mithril-certified snapshot of the Cardano node database and restore it locally, rather than replaying the chain. The snapshot's integrity is verified against the Mithril certificate chain, anchored in Cardano's stake distribution — so users get the same trust guarantees as a chain-replayed node, without the wait.


		When a user locks assets on Cardano, the bridge needs to confirm that the lock transaction was included on-chain before authorizing the corresponding action on the destination chain. With Mithril, the bridge can verify this using a Merkle proof linked to a certificate signed by a stake-weighted quorum of SPOs. The proof can be checked locally, without trusting the source of the data.

		This changes the bridge's security posture. The integrity of cross-chain transfers no longer depends on the honesty of any single data provider or on the operational security of any one node. A compromised API, a misconfigured indexer, or a hostile relayer cannot produce a valid Mithril proof — and a bridge that verifies proofs will reject anything that fails verification.


		### How it fits into existing bridge architectures

		Most bridges have an off-chain component — relayers, validators, or watchers — that observes events on the source chain and submits attestations to the destination chain. Mithril does not replace this component. It strengthens it: instead of trusting whatever endpoint the relayer happens to query, the relayer verifies a Mithril proof against the current certificate chain before treating a Cardano transaction as final.


		## For bridge users

		When a bridge supports Mithril, cross-chain transfers from Cardano are more secure. Whether you interact with the bridge directly, or through a wallet or aggregator that abstracts the swap behind a simpler interface, the underlying assertion is the same: that your Cardano transaction was actually included on-chain before the bridge took action on the other side.

Conversation

dalibran commented Apr 14, 2026

Summary

Notes for reviewers

Test plan

Uh oh!

github-actions Bot commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Results

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions Bot commented Apr 14, 2026 •

edited

Loading