chore: migrate tutorials to v14 by Keinberger · Pull Request #186 · 0xMiden/tutorials

Keinberger · 2026-04-14T12:51:15Z

Summary

bumps @miden-sdk/{miden-sdk,react} to 0.14.4 and migrates all web tutorials to the /lazy entry point with MidenClient.ready() gating for Next.js SSR safety
migrates rust-client/ to miden-client 0.14 on testnet and rewrites examples/miden-bank/ against miden-base 0.12 / miden-mast-package 0.22.1
syncs every web and rust tutorial doc to its companion source, removes stale devnet IDs, and centralises the Next.js setup flow in docs/src/web-client/setup_guide.md

Details

rust-client

all tutorials switched from localhost devnet to testnet (https://rpc.testnet.miden.io)
Client::builder() / Endpoint::new plumbing follows the 0.14 API, keystore initialisation uses the explicit path
counter contract create_library updated to the 0.14 two-argument signature (library path + source code)
FPI tutorial updated to 0.14's ForeignAccount / AccountStorageRequirements surface

web-client

@miden-sdk/miden-sdk@0.14.4 + @miden-sdk/react@0.14.4; every library file and doc imports from @miden-sdk/miden-sdk/lazy (or @miden-sdk/react/lazy) and calls await MidenClient.ready() right after the browser guard
testnet-only flow everywhere: rpcUrl: 'https://rpc.testnet.miden.io', StorageMode.Public, NoteVisibility.Public; removed the devnet/local-prover branches
counter tutorial reads count from storage.getItem(...).toU64s()[0] (fixes a prior off-by-index that always returned 0); FPI reader contract read-back fixed the same way
FPI script pushes counterComponent.getProcedureHash('get_count') followed by prefix/suffix in the order execute_foreign_procedure expects, with padw padw padw padw for the 16-word input region
mint / multi-send / unauthenticated-note TS paths use client.transactions.consumeAll({ account }) to match the companion source; the React tabs keep the waitForConsumableNotes + consume hook flow
Playwright harness strengthened to assert per-tutorial success strings (Tokens sent successfully!, All notes created ✅, Count: 1, Asset transfer chain completed ✅, Count copied via Foreign Procedure Invocation: 1)

examples/miden-bank

contracts migrated to the #[component] / #[note_script] / #[storage] macros from miden-base 0.12
NoteScript::from_package / AccountComponent::from_package + InitStorageData::insert_value(StorageValueName, Word) replace the hand-rolled assembler plumbing
integration tests now invoke cargo_miden::run as a library call; all 4 tests pass on miden-mast-package 0.22.1

docs

every web tutorial code block matches its companion source verbatim (imports, guards, ready() gate, consume flow, Account vs AccountId arguments, mint destructuring)
counter + FPI narratives rewritten to reflect the actual in-session deploy flow; stale devnet (mdev1…) sample output replaced with <testnet_account_id> / indexed <account_N_id> placeholders where the chain relationships need to be readable
new docs/src/web-client/setup_guide.md centralises the one-time Next.js setup, /lazy vs eager entry rationale, and the v0.14 SDK API patterns consumers will hit

node 22 polyfill

web-client/next.config.ts keeps a small in-memory localStorage polyfill for the Node SSR context used by next dev. Node 22+ defines globalThis.localStorage but leaves its methods undefined unless started with --localstorage-file, which crashes the Next.js dev overlay on every page request. Documented in setup_guide.md, harmless on Node ≤21. Unrelated to the SDK, but without it the Playwright verification cannot run on modern Node.

…import path) Three independent audits of PR #242 (Claude sub-agent, OpenAI Codex CLI, and reviewer feedback on Felt usage) surfaced the following refinements. All validated via the updated mockchain-demo harness in docs-tests, which now exercises the exact `add_account(NoAuth+build_existing) → build_tx_context → execute → apply_delta` sequence from test.md. Bug fix (Codex found): - Walkthrough snippet at line 223 bound counter_account as immutable but line 271 mutates it via apply_delta(&mut self). Changed to `let mut counter_account = …` to match the main snippet at line 113. Style refinements: - Prefer u32 primitive literals over Felt::new for Word construction: Word::from([0u32, 0, 0, 1]) reads cleaner than Word::from([Felt::new(0), Felt::new(0), Felt::new(0), Felt::new(1)]). Word impls From<[u32; 4]>, From<[u16; 4]>, From<[u8; 4]> — u64 is NOT impl'd (u64 doesn't fit in a Felt's ~2^64 modulus), so stick to u32 or smaller for literal construction. - Use Word::default() for all-zeros instead of the 4×Felt::new(0) form. - Drop the now-unused Felt import from the miden_client import block. - Aligns with the style Philipp is using in the tutorials v14 migration PR (0xMiden/tutorials#186 — e.g. Word::default() for zero slots). Import hygiene (Claude reviewer #1): - Move `use miden_protocol::transaction::RawOutputNote` to `miden_client::transaction::RawOutputNote` so all `use miden_client::…` imports stay homogeneous and reader code doesn't need a direct miden_protocol dep.

…hemeId) Cross-checked PR #242 against the authoritative v0.14 reference for testing patterns — Philipp's tutorials-repo v14 migration branch (0xMiden/tutorials#186, branch kbg/chore/v14-migration). His updated examples/miden-bank/integration/src/helpers.rs and the tests that exercise it (tests/deposit_test.rs etc.) use `AuthSchemeId` imported from `miden_client::auth`, not `AuthScheme` from `miden_client::account::component`. Both paths resolve to the same `miden_protocol::account::auth::AuthScheme` type (the former is a `pub use … as AuthSchemeId` re-export in miden-client's lib.rs), so the previous form was not a compile error — but aligning with Philipp's established idiom keeps the Miden docs, tutorials, and example projects visually consistent. Harness (`docs-tests/crates/mockchain-demo`) updated to the same import path and re-runs green against shipped miden-testing 0.14.4. Everything else in this PR was already aligned with Philipp's v14 branch: `builder.add_account(counter_account.clone())?` matches his test pattern verbatim (20+ call sites across tutorials tests), `RawOutputNote::Full(note)` matches, the helper-call shape (`create_testing_account_from_package(pkg, cfg).await?` returning an `Account`) matches his updated helpers.rs verbatim.

Testnet was upgraded to v0.14, so the default network across all tutorials can flip back from devnet to testnet. This is the final open item on PR #186 (v0.14 migration) tracked in issue #185. Changes: - Rust binaries (11 in rust-client/src/bin + miden-bank helpers): Endpoint::devnet() -> Endpoint::testnet(), NetworkId::Devnet -> NetworkId::Testnet. - Web client (6 lib/*.ts + 3 lib/react/*.tsx): https://rpc.devnet.miden.io -> https://rpc.testnet.miden.io; rpcUrl/prover 'devnet' -> 'testnet'. - Explorer URLs: devnet.midenscan.com -> testnet.midenscan.com across all rust-client, web-client, and docs files. - Counter contract redeployed on testnet; new bech32 mtst1apsd609q5966cqra992t4a00tgstrkfk replaces the old mdev1 address in counter_contract_increment, counter_contract_fpi, and 3 docs. - Four user/recipient addresses re-encoded from mdev1 -> mtst1 with testnet HRP + checksum (same underlying AccountId). - Docs prose: "Miden devnet" -> "Miden testnet", removed all "Oracle not available on devnet" / "wallet adapter requires testnet" caveats, updated SDK shorthand hint in react_wallet_tutorial.md. - Regenerated sample output in creating_notes_in_masm_tutorial.md and network_transactions_tutorial.md from fresh testnet runs (so they no longer contain stale mdev1 bech32 addresses with invalid checksums). - Cargo.lock bump: miden-client 0.14.0 -> 0.14.3 (resolves testnet protobuf wire-type mismatch), miden-protocol pulled to 0.14.4 transitively. Verification (all green): - cargo build --release on rust-client + miden-bank. - yarn build + yarn tsc --noEmit on web-client. - Full Playwright run on devnet testnet: T1 "Tokens sent successfully!", T2 "All notes created", T3 "Count: 0", T4 "Asset transfer chain completed", T5 "Foreign Procedure Invocation Transaction completed!". - Fresh rust-client runs on testnet: create_mint_consume_send, note_creation_in_masm, network_notes_counter_contract (all complete, URLs in docs refreshed where applicable). - `rg -in devnet` on source + docs: 0 matches. - prettier --check "**/*.md": clean. Known pre-existing issue (not introduced by this commit): miden-bank integration tests still fail because `miden-mast-package 0.22.0` was yanked on crates.io and the only available 0.22.x is 0.22.1, whose `unwrap_program()` assertion plus stricter `@note_script` attribute requirement don't interop with the current cargo-miden 0.8.1 + miden-base-macros 0.11 toolchain. This was already broken on baf4a4d before any testnet work. `cargo build` still passes for miden-bank; only `cargo test` fails. Separate upstream fix needed.

WiktorStarczewski

LGTM for the web client, like the new setup guide a lot and how comprehensive but easy to read it is. nice.

partylikeits1983

LGTM. I only reviewed masm code. I think there are some minor formatting of stack comment issues, but probably best to do in a follow up PR.

Just would like the conventions in MASM in the tutorials to follow what is in miden-protocol & VM repos

partylikeits1983 · 2026-04-22T14:44:17Z

 const COUNT_READER_SLOT = word("miden::tutorials::count_reader")

-# => [account_id_prefix, account_id_suffix, get_count_proc_hash]
+# => [account_id_suffix, account_id_prefix, PROC_HASH(4), foreign_procedure_inputs(16)]


Suggested change

# => [account_id_suffix, account_id_prefix, PROC_HASH(4), foreign_procedure_inputs(16)]

#! Inputs: [account_id_suffix, account_id_prefix, PROC_HASH(4), foreign_procedure_inputs(16)]

#! Outputs: []

partylikeits1983 · 2026-04-22T14:44:54Z

 # => []
 begin


Updating syntax of stack comments etc can probably done in a followup PR

Will open an issue for this

Keinberger force-pushed the kbg/chore/v14-migration branch from 7630916 to 6876cc9 Compare April 14, 2026 13:10

This comment was marked as resolved.

Sign in to view

Keinberger force-pushed the kbg/chore/v14-migration branch from 08549b6 to 45b4c58 Compare April 17, 2026 07:25

Keinberger force-pushed the kbg/chore/v14-migration branch from 5a5331d to 9c1fd93 Compare April 21, 2026 10:14

Keinberger changed the title ~~chore: migrate tutorials repo to v0.14~~ chore: migrate tutorials to v14 Apr 21, 2026

Keinberger force-pushed the kbg/chore/v14-migration branch from 9c1fd93 to 12b0262 Compare April 22, 2026 07:25

Keinberger requested review from WiktorStarczewski and partylikeits1983 April 22, 2026 07:26

Keinberger marked this pull request as ready for review April 22, 2026 07:26

chore: migrate tutorials to v14

63cc332

Keinberger force-pushed the kbg/chore/v14-migration branch from 12b0262 to 63cc332 Compare April 22, 2026 07:34

WiktorStarczewski approved these changes Apr 22, 2026

View reviewed changes

partylikeits1983 approved these changes Apr 22, 2026

View reviewed changes

BrianSeong99 mentioned this pull request Apr 23, 2026

fix(sidebars): drop recipes/web/setup_guide until PR #186 merges 0xMiden/docs#255

Merged

Keinberger merged commit 71cc533 into main Apr 23, 2026
6 checks passed

Keinberger deleted the kbg/chore/v14-migration branch April 23, 2026 10:11

BrianSeong99 mentioned this pull request Apr 23, 2026

docs: add midenup page · flip tutorials ingest back to main 0xMiden/docs#257

Merged

5 tasks

This was referenced Apr 24, 2026

feat(skills): add MASM formatting skill covering ecosystem conventions 0xMiden/agent-tools#6

Closed

chore: standardize MASM formatting in tutorial files #190

Open

fix: refactor miden-bank tutorial test flow and init guard progression #184

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore: migrate tutorials to v14#186

chore: migrate tutorials to v14#186
Keinberger merged 1 commit into
mainfrom
kbg/chore/v14-migration

Keinberger commented Apr 14, 2026 •

edited

Loading

Uh oh!

This comment was marked as resolved.

Uh oh!

WiktorStarczewski left a comment

Uh oh!

partylikeits1983 left a comment

Uh oh!

partylikeits1983 Apr 22, 2026

Uh oh!

partylikeits1983 Apr 22, 2026

Uh oh!

Keinberger Apr 23, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	# => [account_id_suffix, account_id_prefix, PROC_HASH(4), foreign_procedure_inputs(16)]
	#! Inputs: [account_id_suffix, account_id_prefix, PROC_HASH(4), foreign_procedure_inputs(16)]
	#! Outputs: []

Conversation

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

Uh oh!

Summary

Details

rust-client

web-client

examples/miden-bank

docs

node 22 polyfill

Uh oh!

This comment was marked as resolved.

Uh oh!

WiktorStarczewski left a comment

Choose a reason for hiding this comment

Uh oh!

partylikeits1983 left a comment

Choose a reason for hiding this comment

Uh oh!

partylikeits1983 Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

partylikeits1983 Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

Keinberger Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Keinberger commented Apr 14, 2026 •

edited

Loading