From 7f7c5927a3af537e579fbfb8f5f37da110f75786 Mon Sep 17 00:00:00 2001 From: Brian Seong Date: Fri, 20 Mar 2026 19:18:09 +0800 Subject: [PATCH 1/2] docs: fix Your First Smart Contract page issues MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix "compiles to Miden assembly" → compiles to .masp package file - Add note explaining felt macro vs Felt type - Fix "Miden component" → "Miden account component" - Clarify storage key strategy wording - Add trace log output and explanation to expected output - Add MidenScan link for verifying deployment Closes #218 --- .../your-first-smart-contract/create.md | 10 +++++++--- .../your-first-smart-contract/deploy.md | 15 +++++++++++---- 2 files changed, 18 insertions(+), 7 deletions(-) diff --git a/docs/builder/get-started/your-first-smart-contract/create.md b/docs/builder/get-started/your-first-smart-contract/create.md index b5d37c2..e458b6e 100644 --- a/docs/builder/get-started/your-first-smart-contract/create.md +++ b/docs/builder/get-started/your-first-smart-contract/create.md @@ -53,7 +53,7 @@ cd ../increment-note miden build ``` -This compiles the Rust contract code into Miden assembly, making it ready for deployment and interaction. +This compiles the Rust contract code into a `.masp` package file, making it ready for deployment and interaction. ## Understanding the Counter Account Contract @@ -127,6 +127,10 @@ These imports provide: - **`StorageMap`**: Key-value storage within account storage slots - **`StorageMapAccess`**: Needed for reading storage values (`get_count` function) +:::note[`felt` vs `Felt`] +`felt` is a macro (`felt!(1)`) for creating `Felt` values from compile-time constants, while `Felt` is the actual field element type used at runtime. Think of `felt!` as shorthand for creating `Felt` values. +::: + #### Contract Structure Definition ```rust @@ -138,7 +142,7 @@ struct CounterContract { } ``` -The `#[component]` attribute marks this as a Miden component. The `count_map` field is a `StorageMap` stored in a named storage slot of the account. In v0.13, storage slots are identified by name rather than explicit index numbers — the slot name is derived automatically from the component's package name and field name (e.g., `miden::component::miden_counter_account::count_map`). +The `#[component]` attribute marks this as a Miden account component. The `count_map` field is a `StorageMap` stored in a named storage slot of the account. In v0.13, storage slots are identified by name rather than explicit index numbers — the slot name is derived automatically from the component's package name and field name (e.g., `miden::component::miden_counter_account::count_map`). **Important**: Storage slots in Miden hold `Word` values, which are composed of four field elements (`Felt`). Each `Felt` is a 64-bit unsigned integer (u64). The `StorageMap` provides a key-value interface within a single storage slot, allowing you to store multiple key-value pairs within the four-element word structure. @@ -158,7 +162,7 @@ The `CounterContract` implementation defines the external interface that other c let key = Word::from_u64_unchecked(0, 0, 0, 1); ``` -Both functions use the same fixed key `[0, 0, 0, 1]` to store and retrieve the counter value within the storage map. The `Word::from_u64_unchecked` constructor creates a `Word` from four `u64` values. This demonstrates a simple but effective storage pattern. +Both functions in the counter contract use the same fixed key `[0, 0, 0, 1]` to store and retrieve the counter value within the storage map. The `Word::from_u64_unchecked` constructor creates a `Word` from four `u64` values. This demonstrates a simple but effective storage pattern. ## Understanding the Increment Note Script diff --git a/docs/builder/get-started/your-first-smart-contract/deploy.md b/docs/builder/get-started/your-first-smart-contract/deploy.md index c6a5f36..65543a8 100644 --- a/docs/builder/get-started/your-first-smart-contract/deploy.md +++ b/docs/builder/get-started/your-first-smart-contract/deploy.md @@ -86,14 +86,21 @@ cargo run --bin increment_count --release Account ID: V0(AccountIdV0 { prefix: 14134910893364381952, suffix: 3644349760121494784 }) Sender account ID: "0xd85b347218c5a80052dbd47b2f36ad" Counter note hash: "0xf0e821396a896eb9983e682bc056021d57ddcaa43082f34597bf9e026421e566" -Note publish transaction ID: "0xc6f080855724402cadf26650ffe993fe97a127a8f6c9c82ec621960e936e6d732 +Note publish transaction ID: "0xc6f080855724402cadf26650ffe993fe97a127a8f6c9c82ec621960e936e6d732" +Trace with id 240 emitted at step 2679 in context 2666 +Trace with id 252 emitted at step 2689 in context 2666 +... (trace output omitted) Consume transaction ID: "0x2d1d8510e546ce0fbc22fa7d1a82322259d73cd1d7e0ca86622d0be70fab0548" -Account delta: AccountDelta { account_id: V0(AccountIdV0 { prefix: 7255964780328958976, suffix: 2724050564200846336 }), storage: AccountStorageDelta { values: {}, maps: {0: StorageMapDelta({LexicographicWord(Word([0, 0, 0, 1])): Word([0, 0, 0, 1])})} }, vault: AccountVaultDelta { fungible: FungibleAssetDelta({}), non_fungible: NonFungibleAssetDelta({}) }, nonce_delta: 1 } +Account delta: AccountDelta { ... storage: AccountStorageDelta { ... maps: {0: StorageMapDelta({...: Word([0, 0, 0, 1])})} }, ... nonce_delta: 1 } ``` +:::note +The `Trace with id ... emitted at step ...` lines are debug output from the Miden VM and can be safely ignored. Your actual account IDs and transaction IDs will differ from this example. +::: + -Congratulations, you have successfully deployed the Counter Contract to the Miden Testnet, and incremented its count by one! +Congratulations, you have successfully deployed the Counter Contract to the Miden Testnet, and incremented its count by one! You can verify your transaction on [MidenScan](https://testnet.midenscan.com) by searching for your transaction ID. ### What Happens During Execution @@ -149,7 +156,7 @@ let note_package = Arc::new( The `build_project_in_dir()` function: - Takes the path to your contract's Rust source code -- Compiles the Rust code into Miden assembly +- Compiles the Rust code into a Miden package (`.masp` file) - Generates a package containing the compiled contract bytecode and metadata - This is equivalent to manually running `miden build` in each contract directory From ff3d393f34a78cce32e2d5d275becf731854bb9b Mon Sep 17 00:00:00 2001 From: Brian Seong Date: Sat, 21 Mar 2026 18:06:49 +0800 Subject: [PATCH 2/2] docs: fix felt vs Felt note with accurate details - felt! accepts integer literals (not constants) with compile-time validation - Currently restricted to u32 range due to compiler limitation - Mention Felt::from_u64_unchecked() for larger values --- docs/builder/get-started/your-first-smart-contract/create.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/builder/get-started/your-first-smart-contract/create.md b/docs/builder/get-started/your-first-smart-contract/create.md index e458b6e..c950678 100644 --- a/docs/builder/get-started/your-first-smart-contract/create.md +++ b/docs/builder/get-started/your-first-smart-contract/create.md @@ -128,7 +128,7 @@ These imports provide: - **`StorageMapAccess`**: Needed for reading storage values (`get_count` function) :::note[`felt` vs `Felt`] -`felt` is a macro (`felt!(1)`) for creating `Felt` values from compile-time constants, while `Felt` is the actual field element type used at runtime. Think of `felt!` as shorthand for creating `Felt` values. +`Felt` is the field element type representing values in the Goldilocks prime field (p = 2^64 - 2^32 + 1). `felt!(1)` is a compile-time macro that creates `Felt` values from integer literals with compile-time range validation. Currently `felt!` only accepts values up to 2^32 (compiler limitation); for larger values use `Felt::from_u64_unchecked()`. ::: #### Contract Structure Definition