Skip to content

Commit a146e99

Browse files
BrianSeong99BrianSeong99
committed
fix: resolve merge conflicts with main in patterns.md
Take main's shorter description and remove unverified code examples (Basic wallet, Counter) that were intentionally removed on main.
2 parents 870ace5 + e0d8265 commit a146e99

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+504
-33089
lines changed

docs/builder/smart-contracts/notes/note-types.md renamed to docs/builder/develop/note-types.md

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
---
2-
title: "Note Types"
3-
sidebar_position: 2
4-
description: "Built-in note types: P2ID, P2IDE (with expiration), and SWAP (atomic exchange)."
2+
title: "Standard Note Types"
3+
sidebar_position: 3
4+
description: "Built-in note types from miden-standards: P2ID, P2IDE (with expiration), and SWAP (atomic exchange)."
55
---
66

7-
# Note Types
7+
# Standard Note Types
88

9-
Miden provides built-in note patterns for common asset transfer scenarios. These are protocol primitives you can use directly or extend for custom behavior.
9+
The `miden-standards` crate provides built-in note patterns for common asset transfer scenarios. These are pre-compiled note scripts you can use directly via the builder API in client code.
1010

1111
## P2ID (Pay to ID)
1212

@@ -155,8 +155,8 @@ create_swap_note(
155155

156156
Returns a tuple of `(Note, NoteDetails)` — the SWAP note to submit and the expected payback note details (for tracking).
157157

158-
`NoteAttachment` is defined in the `miden-standards` crate (not the core `miden` SDK). It wraps the attachment data that gets set on output notes — see [note attachments](./output-notes#note-attachments) for the underlying SDK API.
158+
`NoteAttachment` is defined in the `miden-standards` crate (not the core `miden` SDK). It wraps the attachment data that gets set on output notes — see [note attachments](../smart-contracts/notes/output-notes#note-attachments) for the underlying SDK API.
159159

160160
## More note types
161161

162-
For writing custom note scripts, see [Note Scripts](./note-scripts). For the transaction context and `#[tx_script]`, see [Transaction Context](../transactions/transaction-context). For common patterns, see [Patterns & Security](../patterns).
162+
For writing custom note scripts, see [Note Scripts](../smart-contracts/notes/note-scripts). For the transaction context and `#[tx_script]`, see [Transaction Context](../smart-contracts/transactions/transaction-context).

‎docs/builder/smart-contracts/accounts/account-operations.md‎

Lines changed: 55 additions & 143 deletions
Original file line numberDiff line numberDiff line change
@@ -1,166 +1,78 @@
11
---
22
title: "Account Operations"
33
sidebar_position: 4
4-
description: "Query account state with active_account and mutate the vault with native_account."
4+
description: "Query account state and mutate the vault using self methods in Miden components."
55
---
66

77
# Account Operations
88

9-
Miden provides two modules for interacting with the current account during a transaction: `active_account` for read-only queries (balance, nonce, commitments) and `native_account` for mutations (add/remove assets, increment nonce). The split reflects the ZK proof model — `active_account` calls don't affect the proof's state transition, while `native_account` calls represent state changes that must be proven. The vault is the account's asset container where all fungible and non-fungible assets live.
9+
The `#[component]` macro automatically provides methods on `self` for interacting with the current account during a transaction. Read-only queries are available on `&self`, and mutations (add/remove assets, increment nonce) require `&mut self`.
1010

11-
## `active_account` — Read-only queries
12-
13-
These functions query the current account's state without modifying it. They're available in both `&self` and `&mut self` methods.
14-
15-
```rust
16-
use miden::active_account;
17-
```
18-
19-
### Account identity
20-
21-
```rust
22-
// Get the account ID
23-
let id: AccountId = active_account::get_id();
24-
25-
// Get the current nonce
26-
let nonce: Felt = active_account::get_nonce();
27-
```
28-
29-
### Vault queries
30-
31-
```rust
32-
// Get fungible asset balance for a specific faucet
33-
let balance: Felt = active_account::get_balance(faucet_id);
34-
35-
// Get the balance at the start of this transaction
36-
let initial: Felt = active_account::get_initial_balance(faucet_id);
37-
38-
// Check if a non-fungible asset exists in the vault
39-
let has_nft: bool = active_account::has_non_fungible_asset(asset);
40-
41-
// Get vault commitment (Merkle root)
42-
let root: Word = active_account::get_vault_root();
43-
let initial_root: Word = active_account::get_initial_vault_root();
44-
```
45-
46-
### Commitment queries
47-
48-
```rust
49-
// Full account commitment (code + storage + vault + nonce)
50-
let commitment: Word = active_account::compute_commitment();
51-
let initial: Word = active_account::get_initial_commitment();
52-
53-
// Storage commitment only
54-
let storage: Word = active_account::compute_storage_commitment();
55-
let initial_storage: Word = active_account::get_initial_storage_commitment();
56-
57-
// Code commitment
58-
let code: Word = active_account::get_code_commitment();
59-
```
60-
61-
### Procedure queries
62-
63-
```rust
64-
// Number of exported procedures
65-
let count: Felt = active_account::get_num_procedures();
66-
67-
// Get the root hash of procedure at index
68-
let root: Word = active_account::get_procedure_root(0);
69-
70-
// Check if a procedure exists
71-
let exists: bool = active_account::has_procedure(proc_root);
72-
```
73-
74-
## native_account — Mutations
75-
76-
`add_asset`, `remove_asset`, and `incr_nonce` require `&mut self` and modify account state. `compute_delta_commitment` and `was_procedure_called` take `&self` — they are read-only queries on the native account.
77-
78-
```rust
79-
use miden::native_account;
80-
```
81-
82-
### Asset operations
83-
84-
```rust
85-
// Add an asset to the vault — returns the asset as stored
86-
let stored: Asset = native_account::add_asset(asset);
87-
88-
// Remove an asset from the vault — returns the removed asset
89-
// Proof generation fails if the asset doesn't exist or insufficient balance
90-
let removed: Asset = native_account::remove_asset(asset);
91-
```
92-
93-
### Nonce management
94-
95-
```rust
96-
// Increment the account nonce (replay protection)
97-
let new_nonce: Felt = native_account::incr_nonce();
98-
```
99-
100-
:::warning
101-
The nonce must be incremented for any transaction that modifies account state. Without it, the same transaction could be replayed.
102-
:::
103-
104-
### Transaction tracking
11+
## Read-only queries (`&self`)
10512

10613
```rust
107-
// Compute commitment of all state changes in this transaction
108-
let delta: Word = native_account::compute_delta_commitment();
109-
110-
// Check if a specific procedure was called during this transaction
111-
let called: bool = native_account::was_procedure_called(proc_root);
14+
#[component]
15+
impl MyAccount {
16+
pub fn check_state(&self) {
17+
// Account identity
18+
let id: AccountId = self.get_id();
19+
let nonce: Felt = self.get_nonce();
20+
21+
// Vault queries
22+
let balance: Felt = self.get_balance(faucet_id);
23+
let initial: Felt = self.get_initial_balance(faucet_id);
24+
let has_nft: bool = self.has_non_fungible_asset(asset);
25+
let root: Word = self.get_vault_root();
26+
let initial_root: Word = self.get_initial_vault_root();
27+
28+
// Commitment queries
29+
let commitment: Word = self.compute_commitment();
30+
let initial_commit: Word = self.get_initial_commitment();
31+
let storage: Word = self.compute_storage_commitment();
32+
let initial_storage: Word = self.get_initial_storage_commitment();
33+
let code: Word = self.get_code_commitment();
34+
35+
// Procedure queries
36+
let count: Felt = self.get_num_procedures();
37+
let proc_root: Word = self.get_procedure_root(0);
38+
let exists: bool = self.has_procedure(proc_root);
39+
}
40+
}
11241
```
11342

114-
## Auto-generated methods on components
115-
116-
`#[component]` implements the `ActiveAccount` and `NativeAccount` traits on the struct, exposing these functions as methods on `self`:
43+
## Mutations (`&mut self`)
11744

11845
```rust
11946
#[component]
12047
impl MyAccount {
12148
pub fn receive_asset(&mut self, asset: Asset) {
122-
// These are equivalent:
123-
self.add_asset(asset); // via NativeAccount trait
124-
native_account::add_asset(asset); // direct module call
49+
// Add an asset to the vault — returns the asset as stored
50+
let stored: Asset = self.add_asset(asset);
12551
}
12652

127-
pub fn check_balance(&self, faucet_id: AccountId) -> Felt {
128-
// These are equivalent:
129-
self.get_balance(faucet_id) // via ActiveAccount trait
130-
active_account::get_balance(faucet_id) // direct module call
53+
pub fn send_asset(&mut self, asset: Asset, note_idx: NoteIdx) {
54+
// Remove an asset from the vault — returns the removed asset
55+
// Proof generation fails if the asset doesn't exist or insufficient balance
56+
let removed: Asset = self.remove_asset(asset);
57+
output_note::add_asset(removed, note_idx);
58+
}
59+
60+
pub fn auth(&mut self) {
61+
// Increment the account nonce (replay protection)
62+
let new_nonce: Felt = self.incr_nonce();
63+
64+
// Compute commitment of all state changes in this transaction
65+
let delta: Word = self.compute_delta_commitment();
66+
67+
// Check if a specific procedure was called during this transaction
68+
let called: bool = self.was_procedure_called(proc_root);
13169
}
13270
}
13371
```
13472

135-
### NativeAccount methods (on `&mut self`)
136-
137-
| Method | Signature |
138-
|--------|-----------|
139-
| `add_asset` | `fn add_asset(&mut self, asset: Asset) -> Asset` |
140-
| `remove_asset` | `fn remove_asset(&mut self, asset: Asset) -> Asset` |
141-
| `incr_nonce` | `fn incr_nonce(&mut self) -> Felt` |
142-
| `compute_delta_commitment` | `fn compute_delta_commitment(&self) -> Word` |
143-
| `was_procedure_called` | `fn was_procedure_called(&self, proc_root: Word) -> bool` |
144-
145-
### ActiveAccount methods (on `&self`)
146-
147-
| Method | Signature |
148-
|--------|-----------|
149-
| `get_id` | `fn get_id(&self) -> AccountId` |
150-
| `get_nonce` | `fn get_nonce(&self) -> Felt` |
151-
| `get_balance` | `fn get_balance(&self, faucet_id: AccountId) -> Felt` |
152-
| `get_initial_balance` | `fn get_initial_balance(&self, faucet_id: AccountId) -> Felt` |
153-
| `has_non_fungible_asset` | `fn has_non_fungible_asset(&self, asset: Asset) -> bool` |
154-
| `get_vault_root` | `fn get_vault_root(&self) -> Word` |
155-
| `get_initial_vault_root` | `fn get_initial_vault_root(&self) -> Word` |
156-
| `compute_commitment` | `fn compute_commitment(&self) -> Word` |
157-
| `get_initial_commitment` | `fn get_initial_commitment(&self) -> Word` |
158-
| `compute_storage_commitment` | `fn compute_storage_commitment(&self) -> Word` |
159-
| `get_initial_storage_commitment` | `fn get_initial_storage_commitment(&self) -> Word` |
160-
| `get_code_commitment` | `fn get_code_commitment(&self) -> Word` |
161-
| `get_num_procedures` | `fn get_num_procedures(&self) -> Felt` |
162-
| `get_procedure_root` | `fn get_procedure_root(&self, index: u8) -> Word` |
163-
| `has_procedure` | `fn has_procedure(&self, proc_root: Word) -> bool` |
73+
:::warning
74+
The nonce must be incremented for any transaction that modifies account state. Without it, the same transaction could be replayed.
75+
:::
16476

16577
## When proof generation fails
16678

@@ -179,7 +91,7 @@ When proof generation fails:
17991
3. No state changes occur
18092
4. The client receives an error describing the failure
18193

182-
## ManagedWallet component
94+
## Example: ManagedWallet
18395

18496
```rust
18597
#![no_std]
@@ -210,8 +122,8 @@ impl ManagedWallet {
210122
}
211123
```
212124

213-
To move assets out of an account, create [output notes](../notes/output-notes) with `output_note::add_asset`. For signature verification and nonce management, see [Authentication](./authentication). For complete function signatures, see the [Cheatsheet](../api-reference).
125+
To move assets out of an account, create [output notes](../notes/output-notes) with `output_note::add_asset`. For signature verification and nonce management, see [Authentication](./authentication).
214126

215127
:::info API Reference
216-
Full API docs on docs.rs: [`miden::active_account`](https://docs.rs/miden/latest/miden/active_account/), [`miden::native_account`](https://docs.rs/miden/latest/miden/native_account/)
128+
Full API docs on docs.rs: [`miden`](https://docs.rs/miden/latest/miden/)
217129
:::

‎docs/builder/smart-contracts/accounts/authentication.md‎

Lines changed: 37 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -20,41 +20,56 @@ The advice provider supplies auxiliary data during proof generation — see [Adv
2020

2121
## Auth component implementation
2222

23+
From the [compiler examples](https://github.com/0xMiden/compiler/tree/next/examples/auth-component-rpo-falcon512):
24+
2325
```rust
2426
#![no_std]
2527
#![feature(alloc_error_handler)]
2628

27-
use miden::*;
28-
use miden::intrinsics::advice::emit_falcon_sig_to_stack;
29+
extern crate alloc;
30+
31+
use miden::{
32+
Felt, Value, ValueAccess, Word, component, felt, hash_words,
33+
intrinsics::advice::adv_insert, native_account, tx,
34+
};
2935

3036
#[component]
3137
struct AuthComponent {
32-
/// RPO256 hash of the Falcon512 public key
33-
#[storage(description = "auth::rpo_falcon512::pub_key")]
34-
pub_key: Value,
38+
/// The account owner's public key (RPO-Falcon512 public key hash).
39+
#[storage(
40+
description = "owner public key",
41+
type = "miden::standards::auth::falcon512_rpo::pub_key"
42+
)]
43+
owner_public_key: Value,
3544
}
3645

3746
#[component]
3847
impl AuthComponent {
39-
/// Verify the caller has the correct private key.
40-
/// Called during transaction execution to authenticate state changes.
41-
pub fn auth(&mut self) -> Felt {
42-
// 1. Read the stored public key hash
43-
let pub_key: Word = self.pub_key.read();
48+
pub fn auth_procedure(&mut self, _arg: Word) {
49+
let ref_block_num = tx::get_block_number();
50+
let final_nonce = self.incr_nonce();
51+
52+
// Gather tx summary parts
53+
let acct_delta_commit = self.compute_delta_commitment();
54+
let input_notes_commit = tx::get_input_notes_commitment();
55+
let output_notes_commit = tx::get_output_notes_commitment();
4456

45-
// 2. Build the message to verify (transaction summary)
46-
let commitment = self.compute_delta_commitment();
47-
let nonce = Word::from(self.incr_nonce()); // Felt → [0, 0, 0, nonce_felt]
48-
let msg: Word = hash_words(&[commitment, nonce]).into();
57+
let salt = Word::from([felt!(0), felt!(0), ref_block_num, final_nonce]);
4958

50-
// 3. Request signature from advice provider
51-
emit_falcon_sig_to_stack(msg, pub_key);
59+
let mut tx_summary = [acct_delta_commit, input_notes_commit, output_notes_commit, salt];
60+
let msg: Word = hash_words(&tx_summary).into();
61+
// On the advice stack the words are expected to be in reverse order
62+
tx_summary.reverse();
63+
// Insert tx summary into advice map under key `msg`
64+
adv_insert(msg, &tx_summary);
5265

53-
// 4. Verify the signature
54-
// Panics if signature is invalid -> proof generation fails
55-
rpo_falcon512_verify(pub_key, msg);
66+
let pub_key: Word = self.owner_public_key.read();
5667

57-
felt!(1)
68+
// Emit signature request event to advice stack
69+
miden::emit_falcon_sig_to_stack(msg, pub_key);
70+
71+
// Verify the signature loaded on the advice stack
72+
miden::rpo_falcon512_verify(pub_key, msg);
5873
}
5974
}
6075
```
@@ -66,14 +81,11 @@ The nonce prevents replay attacks — each transaction must use a unique nonce:
6681
```rust
6782
// Increment and return the new nonce
6883
let new_nonce: Felt = self.incr_nonce();
69-
70-
// Or via the module function
71-
let new_nonce: Felt = native_account::incr_nonce();
7284
```
7385

7486
The nonce is automatically included in the transaction's proof. If someone tries to replay a transaction, the nonce won't match and verification will fail.
7587

76-
Auth components are typically called via [cross-component calls](../cross-component-calls) from note scripts or [transaction scripts](../transactions/transaction-scripts). For access control and security patterns, see [Patterns & Security](../patterns).
88+
Auth components are typically called via [cross-component calls](../cross-component-calls) from note scripts or [transaction scripts](../transactions/transaction-scripts). For access control and security patterns, see [Patterns](../patterns).
7789

7890
:::info API Reference
7991
Full API docs on docs.rs: [`miden`](https://docs.rs/miden/latest/miden/) (`rpo_falcon512_verify`)
@@ -83,4 +95,4 @@ Full API docs on docs.rs: [`miden`](https://docs.rs/miden/latest/miden/) (`rpo_f
8395

8496
- [Cryptography](./cryptography) — RPO-Falcon512 verification and hashing primitives
8597
- [Advice Provider](../transactions/advice-provider) — supplying auxiliary data during proof generation
86-
- [Patterns & Security](../patterns) — access control, rate limiting, and anti-patterns
98+
- [Patterns](../patterns) — access control, rate limiting, and anti-patterns

0 commit comments

Comments
 (0)