fix: address rust tutorial issues from #191#192
Open
Keinberger wants to merge 4 commits intomainfrom
Open
Conversation
… wording Reorder oracle_data_query.rs to compile the oracle reader contract and tx script BEFORE the live Pragma storage walk, so a dead Pragma deployment no longer blocks local verification of the template substitution and MASM assembly path. Add three log lines (template substituted, component compiled, tx_script compiled) so the verification script can classify oracle import failure as TEMP PASS when the local compile path is healthy. Add oracle_tutorial.md to docs/src/lib.rs for doctesting alongside the other tutorial pages. Strengthen the Pragma callout in oracle_tutorial.md: after Pragma redeploys, the oracle account ID and GET_MEDIAN_PROC_HASH constant must be re-verified; do not assume either survives a redeploy unchanged. Apply prettier-formatting fixes to oracle_tutorial.md (italics syntax and three fenced-block language hints).
Reorder the doc snippet in oracle_tutorial.md to match the runnable oracle_data_query.rs: build and locally compile the oracle reader contract and tx script BEFORE walking Pragma's storage, with the same three progress println lines (template substituted, component compiled, tx_script compiled). The doc and bin now read identically through the local-compile path, so the tutorial accurately reflects how a dead Pragma deployment surfaces (only the storage walk fails). Replace stale 'trading_pair requirement' wording with 'pair_word' to match the actual function-signature argument.
partylikeits1983
approved these changes
Apr 29, 2026
Collaborator
partylikeits1983
left a comment
partylikeits1983
left a comment
There was a problem hiding this comment.
Looks great! Thanks for doing this.
Leaving a conditional approval, I'd remove all the comment references to that VM issue/PR, its irrelevant context for a future reader / consumer of the tutorials & examples. There are more references to vm #2778 than what I listed below
| // Compile the account code into `AccountComponent` with one storage slot. | ||
| // Using `client.code_builder()` makes the assembler share the client's | ||
| // persisted source manager, which keeps debug spans coherent for any | ||
| // libraries that link against this code later (see miden-vm#2778). |
Collaborator
There was a problem hiding this comment.
Could you refactor this comment to not reference the VM PR?
|
|
||
| // Compile the script with the counter contract code linked as a dynamic | ||
| // module on the same `CodeBuilder`. This shares the client's source | ||
| // manager between parsing and assembly, which is what miden-vm#2778 |
| // Compile the transaction script with the library. | ||
| // Compile the transaction script with the account code linked as a | ||
| // module on the same `CodeBuilder` chain (avoids the source-span | ||
| // mismatch from miden-vm#2778). |
|
|
||
| // Link the counter contract code into the same `CodeBuilder` chain that | ||
| // compiles the script, so the assembler shares the client's persisted | ||
| // source manager (avoids the source-span mismatch from miden-vm#2778). |
|
|
||
| // Compile the note script with the counter contract library | ||
| // Compile the note script with the counter contract code linked as a | ||
| // module on the same `CodeBuilder` chain (avoids miden-vm#2778). |
|
|
||
| // Link the counter contract code into the same `CodeBuilder` chain that | ||
| // compiles the script, so the assembler shares the client's persisted | ||
| // source manager (avoids the source-span mismatch from miden-vm#2778). |
|
|
||
| // Compile the note script with the counter contract library | ||
| // Compile the note script with the counter contract code linked as a | ||
| // module on the same `CodeBuilder` chain (avoids miden-vm#2778). |
|
|
||
| // Link the counter contract code into the same `CodeBuilder` chain that | ||
| // compiles the script, so the assembler shares the client's persisted | ||
| // source manager (avoids the source-span mismatch from miden-vm#2778). |
|
|
||
| // Compile the note script with the counter contract library | ||
| // Compile the note script with the counter contract code linked as a | ||
| // module on the same `CodeBuilder` chain (avoids miden-vm#2778). |
|
|
||
| // Compile the script against the counter contract code via a single | ||
| // `CodeBuilder` chain so the assembler shares the client's persisted | ||
| // source manager (avoids the source-span mismatch from miden-vm#2778). |
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
2 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.
Summary
create_libraryhelper and the cwd-dependentPath::new("../masm/...")pattern; rust-client tutorials now compile MASM viaclient.code_builder().with_linked_module(...)and load source viainclude_str!hash_preimage_note,iterative_output_note,network_increment_note) to the v0.14.5 library form (@note_script pub proc main); both lockfiles bumped tomiden-{client,client-sqlite-store,protocol,standards}@0.14.5oracle_data_queryto mirrorastraly-labs/pragma-miden/examples/consume-price: parameterized MASM template, explicitpair_wordargument,AccountId::parsefor hex-or-bech32 input, and a strict template-substitution gateDetails
create_libraryremovalDefaultSourceManager, parsed aModule, and assembled aLibrary. The resulting library was then linked into aclient.code_builder()chain whose assembler used a different source manager — the cross-manager handoff is what triggersinvalid source span: starting byte is out of bounds(miden-vm#2778)client.code_builder().with_linked_module(path, source).compile_tx_script(script)— single chain, single manager, no intermediateLibraryCodeBuilder::new().compile_component_code(...)→client.code_builder().compile_component_code(...)counter_contract_deploy,counter_contract_increment,counter_contract_fpi,oracle_data_query,network_notes_counter_contract,mapping_examplecounter_contract_tutorial,foreign_procedure_invocation_tutorial,mappings_in_masm_how_to,network_transactions_tutorial,oracle_tutorial,public_account_interaction_tutorialpath handling
Path::new("../masm/...")resolved against cwd, so users following the docs literally (withmasm/inside their own project root) hitOs { code: 2, NotFound }include_str!("../masm/...")(docs) andinclude_str!("../../../masm/...")(repo bins) — both resolve at compile time relative to the source file, regardless of wherecargo runis invoked..count because the repo'smasm/is shared withweb-clientand lives at repo root, while user projects havemasm/at project root@note_scriptmigration (v0.14.5)miden-protocol@0.14.5,CodeBuilder::compile_note_scriptcallsAssembler::assemble_library(notassemble_program), so the legacybegin..endform is rejected withinvalid module: unexpected entrypoint definitionand a singlepub proccarrying the@note_scriptattribute is required (per0xMiden/protocol#2822)rust-client/Cargo.lockanddocs/Cargo.locknow pinmiden-{client,client-sqlite-store,protocol,standards}@0.14.5(verified via crate-by-crate sweep in the verification script)pub proc mainas the entrypoint procedure, matching upstream P2ID/P2IDE/SWAP/MINT/BURN convention; the doc snippets that mirror them are updated alongside, with a one-line prose note explaining the conventionhash_preimage_note.rs,note_creation_in_masm.rs,network_notes_counter_contract.rs) chainclient.code_builder().with_linked_module(...).compile_note_script(...)for the network-note-+-counter case, orcompile_note_scriptdirectly for the standalone notesoracle tutorial
oracle_data_query.rsacceptsAccountId::parseso both Pragma README hex (0x...) and bech32 (mtst1...) forms work; the panic message points at theastraly-labs/pragma-miden#deploymentsREADME as the source of truth for the live testnet IDmasm/accounts/oracle_reader.masmis now a template with placeholders{pair_prefix},{pair_suffix},{get_median_proc_hash},{oracle_id_prefix}, and{oracle_id_suffix}. The Rust binary fills these viaoracle_reader_source(oracle_id)before MASM compilation. A defensive runtime gate panics with a clear message if any placeholder leaks through (catches typos before the assembler emits an opaque error)get_oracle_foreign_accountsnow mirrorsastraly-labs/pragma-miden/examples/consume-price/src/main.rsverbatim: readspragma::oracle::next_publisher_index, walks thepragma::oracle::publishersmap fori in 2..publisher_count(Pragma reserves 0/1 as sentinels), then for each publisher requests itspragma::publisher::entriesmap gated on the suppliedpair_word. The function takespair_word: Wordas an explicit argument, so the BTC/USD assumption is in the caller, not a hidden globalget_medianprocedure root and the parsed oracle account ID are threaded through the template via Rust constants rather than hardcoded into MASM, so changing oracle deployments requires updating one constant inoracle_data_query.rsand re-running rather than hand-patching.masmParsed oracle ID:,oracle_reader template substituted (no leftover placeholders),Compiled oracle_reader component locally,Compiled tx_script with linked oracle_reader module), so the verification harness can confirm the full local path is healthy independent of Pragma's live deployment statusPragma blocker
The live oracle path is currently blocked pending a v0.14-compatible Pragma deployment. Pragma's source repo is on
miden-protocol@0.13; the migration is tracked inastraly-labs/pragma-miden#40(open PR). After Pragma migrates, the oracle account ID and theget_medianprocedure hash hardcoded inoracle_data_query.rs(constantGET_MEDIAN_PROC_HASH) must be re-verified against the new deployment — the doc and the constant comment both call this out explicitly.cleanup
rust-client/Cargo.toml: droppedserde,serde_json,rand_chacha(none referenced fromrust-client/src/)docs/Cargo.toml: same three deps dropped after confirming doctests still pass without them (17 passed / 16 ignored / 0 failed)network_transactions,creating_notes_in_masm,public_account_interaction,delegated_proving,counter_contract,create_deploy) had stale[dependencies]blocks repeating the dropped deps; removedmint_consume_create,unauthenticated_note_how_to,delegated_proving,create_deploy) used inlinestd::path::PathBuf::from(...)despitePathBufbeing importable; consolidated toPathBuf::from(...)withPathBufadded to the existingstd::{...}groupend-to-end verification
The verification script
/tmp/claude/verify-pr-192-rev6.shruns (in order): lockfile pinning checks,cargo build --releaseinrust-client,cargo test --doc --release --lockedindocs,npx prettier --check,cargo checkper changed binary, end-to-end runs of all 10 non-oracle tutorials in freshmktempcwds, oracle runs against both Pragma README IDs with the strict TEMP-PASS classifier, and the full sweep set. Every "expect 0" sweep is wrapped to beset -e-safe; every "expect ≥ N" forces a 0 on no-match. Replace transcript-paste with the standalone script.The oracle TEMP PASS gate requires all of these to hold (any other failure mode is NOT PASS): build clean,
Latest block:printed,Parsed oracle ID:printed,oracle_reader template substituted (no leftover placeholders)printed,Compiled oracle_reader component locallyprinted,Compiled tx_script with linked oracle_reader moduleprinted, no template tokens leaked, no MASM assembly error, and the residual error isAccountNotFoundOnChainagainst Pragma's documented testnet ID. The three local-compile log lines together prove that the template fill, the component compile, and the tx-script compile all succeeded before the live storage walk — so a Pragma-side failure is the only thing that can cause the residual error, and the local Rust + MASM path is verified end-to-end.Final commit shape: three signed local commits stacked on top of the original PR head
659b4a0—043be43(initial revision),12bc332(oracle local-compile path + Pragma re-verify wording), and16c9298(oracle tutorial doc snippet synced to the runnable source order). No--amend, no force-push.