Skip to content

docs(tutorials): add "Browser dApp with an injected wallet" tutorial#1109

Open
DpacJones wants to merge 6 commits into
midnightntwrk:mainfrom
DpacJones:dpac-browser-dapp-tutorial
Open

docs(tutorials): add "Browser dApp with an injected wallet" tutorial#1109
DpacJones wants to merge 6 commits into
midnightntwrk:mainfrom
DpacJones:dpac-browser-dapp-tutorial

Conversation

@DpacJones

Copy link
Copy Markdown

Adds a tutorial showing how to deploy a Compact contract, call a circuit, and read contract state from a minimal browser dApp that delegates chain sync, balancing, proving, and signing to an injected wallet (Lace or 1AM) via the DApp connector API — avoiding a headless wallet sync. Targets the current SDK line (midnight-js 4.x, compact-runtime 0.15, ledger v8) and works on preview and preprod. Linked from the Tutorials landing page.

Adds a tutorial showing how to deploy a Compact contract, call a circuit,
and read contract state from a minimal browser dApp that delegates chain
sync, balancing, proving, and signing to an injected wallet (Lace or 1AM)
via the DApp connector API — avoiding a headless wallet sync. Targets the
current SDK line (midnight-js 4.x, compact-runtime 0.15, ledger v8) and
works on preview and preprod. Linked from the Tutorials landing page.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@DpacJones DpacJones requested review from a team as code owners June 26, 2026 06:37
@vercel

vercel Bot commented Jun 26, 2026

Copy link
Copy Markdown

@DpacJones is attempting to deploy a commit to the Midnight Foundation Team on Vercel.

A member of the Team first needs to authorize it.

@oduameh oduameh left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good tutorial covering a real gap in the docs (wallet-delegated browser DApp). The architecture is sound and the code examples verified against the current SDK types via tsc --noEmit. Build passes locally.

A few items to address before merge:

Must fix:

  • Em-dashes throughout (8 instances in tutorial, 1 in tile) -- our style uses commas, periods, or parentheses
  • description exceeds 120-160 char limit (212 chars)
  • Indexer URL uses /api/v3/graphql, should be /api/v4/graphql
  • inMemoryPrivateStateProvider() is used but never imported or defined
  • Missing _category_.yaml for the browser-dapp/ directory. All other tutorial directories include one (verified: bboard, bship, leaderboard, zk-loan, private-party). Without it, the sidebar label and collapsible behavior fall back to Docusaurus defaults. Consider adding:
position: 60
label: 'Browser DApp'
description: "Intermediate: deploy, call, and read contract state from a browser DApp with an injected wallet."
collapsible: true
collapsed: true
link:
  type: doc
  id: tutorials/browser-dapp/index
  • compact-runtime 0.15 is outdated (0.16.0 is latest)

Should fix:

  • "dApp" should be "DApp" per brand guide (6 instances)
  • Missing toc_max_heading_level: 2 in frontmatter
  • FinalizedTransaction should use import type
  • as any in 6 places obscures type information
  • No next-steps section
  • Tags missing difficulty level

Suggestions are batch-committable.

Comment thread docs/tutorials/browser-dapp/index.md Outdated
Comment thread docs/tutorials/browser-dapp/index.md
Comment thread docs/tutorials/browser-dapp/index.md
Comment thread docs/tutorials/browser-dapp/index.md Outdated
Comment thread docs/tutorials/browser-dapp/index.md Outdated
Comment thread docs/tutorials/browser-dapp/index.md Outdated
Comment on lines +199 to +200
'https://indexer.preview.midnight.network/api/v3/graphql',
'wss://indexer.preview.midnight.network/api/v3/graphql/ws',

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The current indexer API version is v4. The indexer 4.0.0 release notes state: "v3 is available as an alias of v4 to support migration windows for existing clients." All other tutorials use v4 (verified against docs/tutorials/bboard/bboard-cli-implementation.mdx:192).

Suggested change
'https://indexer.preview.midnight.network/api/v3/graphql',
'wss://indexer.preview.midnight.network/api/v3/graphql/ws',
'https://indexer.preview.midnight.network/api/v4/graphql',
'wss://indexer.preview.midnight.network/api/v4/graphql/ws',

Comment thread docs/tutorials/browser-dapp/index.md Outdated
Comment thread docs/tutorials/browser-dapp/index.md Outdated
Comment thread docs/tutorials/browser-dapp/index.md Outdated
Comment thread docs/tutorials/index.mdx Outdated
Bump the coordinated SDK set so the tutorial targets the current line.
compact-js exact-pins compact-runtime, so the runtime cannot be bumped
in isolation; move the whole set together:
- compact-js ^2.5.0 -> ^2.5.1 (2.5.1 pins compact-runtime 0.16.0)
- compact-runtime ^0.15.0 -> ^0.16.0
- ledger-v8 ^8.0.0 -> ^8.0.3
- document the compactc 0.31.x / language 0.23 / runtime 0.16 coupling
  in prerequisites and troubleshooting

Address review feedback:
- fix undefined inMemoryPrivateStateProvider (would throw ReferenceError):
  add the import and cross-link the Leaderboard tutorial's complete
  in-memory PrivateStateProvider implementation
- add missing browser-dapp/_category_.yaml so the sidebar label and
  collapsible behavior match the other tutorial directories
- correct hosted indexer URL from /api/v3/graphql to /api/v4/graphql
@DpacJones

Copy link
Copy Markdown
Author

Thanks @oduameh, this was a really thorough review, appreciated. Pushed a commit addressing the must-fixes:

Fixed in the latest push

  • ✅ Indexer URL → /api/v4/graphql (http + ws)
  • ✅ inMemoryPrivateStateProvider — it isn't a published SDK export, so I added the import and cross-linked the Leaderboard tutorial, which ships a complete in-memory PrivateStateProvider readers can copy verbatim. Happy to inline a minimal version instead if you'd rather keep this page self-contained.
  • ✅ Added browser-dapp/category.yaml (position 60, matching the sibling format)
  • ✅ Moved to the 0.16 runtime line — one nuance below

On the runtime bump: bumping compact-runtime alone to ^0.16.0 actually reintroduces a version mismatch, because @midnight-ntwrk/compact-js@2.5.0 exact-pins compact-runtime@0.15.0 — npm still resolves 0.15 transitively and proving fails at runtime. tsc --noEmit won't catch it, since the mismatch surfaces at proof time, not compile time. So I moved the coordinated set together:

  • compact-js ^2.5.0 → ^2.5.1 (2.5.1 pins runtime 0.16.0)
  • compact-runtime ^0.15.0 → ^0.16.0
  • ledger-v8 ^8.0.0 → ^8.0.3

…and documented the compactc 0.31.x / language 0.23 / runtime 0.16 coupling in the prerequisites and troubleshooting, since the reader's compiled bindings have to match the runtime they install.

Accepting your inline suggestions for the remaining style items (em-dashes, dApp→DApp, description length, toc_max_heading_level, import type FinalizedTransaction, difficulty tag) — batching those now.

Still considering the as any cleanup via a CompiledContract.make() type param like zk-loan does — will follow up if I can preserve the types cleanly through the chain.

Thanks again!

DpacJones and others added 2 commits June 29, 2026 10:54
Co-authored-by: Emmanuel Ameh <oduameh@gmail.com>
Signed-off-by: Dpac / Dennis <dpacjones@gmail.com>
Style cleanup the batch suggestions did not reach:
- frontmatter title: dApp -> DApp (the H1 was fixed, the title was not)
- troubleshooting "dApp tab" -> "DApp tab"
- replace the two em-dashes introduced in the 0.16 prerequisites and
  version-drift notes with periods, per the docs style guide
@DpacJones DpacJones requested a review from oduameh June 29, 2026 18:05
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.

2 participants