Skip to content

fix(get-started): repair the programmatic path end to end — install, snippets, storage seeding - #352

Merged
0xrouss-miden merged 8 commits into
0xMiden:mainfrom
walnuthq:fix/programmatic-path-is-broken-end-to-end
Aug 18, 2026
Merged

fix(get-started): repair the programmatic path end to end — install, snippets, storage seeding#352
0xrouss-miden merged 8 commits into
0xMiden:mainfrom
walnuthq:fix/programmatic-path-is-broken-end-to-end

Conversation

@melnikga

Copy link
Copy Markdown
Contributor

Closes #343. The programmatic (Rust/TypeScript) path through Get Started had drifted away from what miden new actually generates and from the v0.15 SDK, so anyone following it top to bottom ran into errors. This resyncs the path and folds in review feedback.

What changed

Installation

  • cargo install midenup is the primary install command again. --version is documented in a follow-up sentence for anyone who needs to pin a release.
  • The install-from-source snippet now names the package, because the repo ships more than one binary.

Your First Smart Contract (create / test / deploy)

  • miden build becomes cargo miden build. The old one proxies to midenc and dies with expected input file.
  • miden-project.toml matches what miden new generates now: the note's package-derived namespace (miden-increment-note) and supported-types = ["RegularAccountImmutableCode"].
  • The note script uses the miden prelude. assert_eq there is a prelude function rather than Rust's macro, so the hand-written import list didn't compile.
  • Storage seeding uses the current SDK: InitStorageData plus insert_map_entry, instead of building StorageSlots by hand.
  • Note creation goes through NoteBuilder (miden_standards::testing::note).
  • The mockchain test is rewritten around AccountComponent::from_package(), add_account_from_builder(.., AccountState::Exists) and mock_chain.committed_account(). The manual apply_delta step is gone.
  • Storage slot names use the manifest namespace form (counter_account::counter_contract::count_map).

Notes (transfer policies)

  • Minted assets carry AssetCallbackFlag::Enabled so the faucet's send/receive transfer policies actually run.
  • The vault lookup key uses the same flag. With the flag mismatched, the lookup misses and the balance reads 0.
  • Asset imports moved from miden_protocol::asset to miden_client::asset.
  • Hardcoded recipient account IDs are placeholders now.

Read Storage Values

  • Snippets resynced. The slot name and map key come from the project's integration/src/helpers.rs instead of being repeated as literals.
  • The hint about where the counter account ID comes from moved out of a :::note and into the code comments, right next to the placeholder it explains.

Prose cleanups from review

  • Dropped the first-run compile-time notes. Slow first builds are normal Rust behavior and don't need calling out.
  • Dropped the Word layout explanations. The "[value, 0, 0, 0] layout" framing was wrong (a Word is four field elements, and what they mean is up to the contract), and Create Your Contract already introduces Word.
  • Expected output blocks now match what the current examples print.

@melnikga

Copy link
Copy Markdown
Contributor Author

cc @BrianSeong99 for visibility.

This also closes the docs side of 0xMiden/project-template#54 , the template doesn't need a `miden-protocol` dependency, the Get Started examples just had the wrong import path.

@marijamijailovic

Copy link
Copy Markdown

@WiktorStarczewski I am tagging you for visibility

@0xrouss-miden 0xrouss-miden left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Thanks for working through this. I tested the Rust and TypeScript flows against toolchain 0.15.0. The dependency/import updates, component metadata, note namespace, callback flag, and counter storage initialization fixes look correct.

I left inline comments for the remaining issues: stale naming, TypeScript runtime and output mismatches, examples that are not self-contained, and the counter fixture.

I don’t think this PR should change miden build to cargo miden build yet, since the expected behaviour is still being resolved in midenup#233.

The Installation card 404 reported in #343 also remains unresolved and should be included in this fix.

Comment thread docs/builder/get-started/read-storage.md Outdated
Comment thread docs/builder/get-started/read-storage.md Outdated
Comment thread docs/builder/get-started/read-storage.md Outdated
Comment thread docs/builder/get-started/read-storage.md Outdated
Comment thread docs/builder/get-started/notes.md Outdated
Comment thread docs/builder/get-started/your-first-smart-contract/create.md Outdated
Comment thread docs/builder/get-started/read-storage.md Outdated
Comment thread docs/builder/get-started/notes.md Outdated
Comment thread docs/builder/get-started/notes.md Outdated
Comment thread docs/builder/get-started/notes.md Outdated
@melnikga

Copy link
Copy Markdown
Contributor Author

@0xrouss-miden Hi! I pushed the review fixes:

  • both counter examples read the deployed testnet counter 0x6a1b2d59a9ebd3f1534cfb2fcf4d7e
  • token-balance and send examples create their own Alice/faucet/Bob
  • TS: toHex() for tx IDs, toU64s()[0], refetch + vault().getBalance() after consuming, outputs match now
  • back to miden build, and the walkthrough snippet now says Wallet instead of CounterAccount

I would skip the 404 for now. docs.miden.xyz/builder/get-started serves versioned_docs/version-0.15/, so editing docs/ only shows up on /next and the live page stays broken until 0.16. Absolute paths don't help either, on /next they'd send readers back into 0.15. I think it's better to resolve it in a separate pr

@0xrouss-miden 0xrouss-miden left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Reviewed the latest changes. The inline feedback has been addressed. I’m okay with tracking the cards 404 separately.

@0xrouss-miden
0xrouss-miden merged commit 00886f8 into 0xMiden:main Aug 18, 2026
@TomasArrachea

TomasArrachea commented Aug 19, 2026

Copy link
Copy Markdown

I would skip the 404 for now. docs.miden.xyz/builder/get-started serves versioned_docs/version-0.15/, so editing docs/ only shows up on /next and the live page stays broken until 0.16. Absolute paths don't help either, on /next they'd send readers back into 0.15. I think it's better to resolve it in a separate pr

FYI there is an open PR that would be useful for fixing the paths: #262

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.

Get Started: programmatic path is broken end-to-end (SDK examples, cargo miden build, 404)

4 participants