Docs: Notes Page improvements
- 主要语言
- Rust
- 星标
- 132
- 派生
- 167
- 平均合并
- 1 天 23 小时
- 30 天内合并 PR
- 110
描述
This issue refers to the following page: https://0xmiden.github.io/miden-docs/imported/miden-base/src/note.html
There are multiple things that can be improved on the Notes page documentation. Here's a list:
### 1. Purpose and Scope Clarification
**Issue:** Unclear if Notes are only for asset transfers
- Documentation states "Notes are how Accounts communicate with each other"
- **Needs clarification:** Are Notes only for asset transfers, or also for state changes and other communications?
### 2. Serial Number Explanation
**Issue:** Serial number explanation assumes prior knowledge of Note hash and nullifier concepts
- **Suggested replacement:**
```
**Serial number**
In order to explain the purpose of the serial number, we must first cover two important aspects of a Note:
- **Commitment**: A hash of the Note's data (including the serial number) that can be publicly stored without revealing the Note's details.
- **Nullifier**: A value derived from the Note's data (including the serial number) that uniquely identifies it as consumed, without allowing the original Note data to be reconstructed.
With this added context, the serial number serves two key purposes:
**Uniqueness:** By adding randomness, it ensures that each Note's commitment is unique even if two Notes contain identical assets, scripts, and inputs. This prevents accidental collisions in the Note database. Remember, the Note commitment is computed based on the Note's contents components.
**Privacy protection:** In Miden, each Note has both a **commitment** (used to represent it in the notes database, especially in private mode) and a **nullifier** (used when the Note is consumed to mark it as spent).
- Therefore, the serial number acts as a "secret link" between the commitment and the nullifier. If an attacker learns the serial number of a private Note, they can recompute its nullifier from the commitment. That would let them detect when the Note is spent, breaking privacy by linking creation to consumption events.
**Best practice:** The serial number must be generated randomly (32 bytes) and kept secret for private Notes. If leaked, privacy is compromised even if the Note's other data remains hidden.
```
### 3. Vault Hash Definition
**Issue:** Missing explanation of `vault_hash` property
- **Action needed:** Add explainer/disclaimer that briefly explains what the `vault_hash` property is
### 4. Note Tag composition explanation
I noticed that the current docs do not explain the Note Tag composition, i.e. how Note Tags are derived.
There should be better explanation and/or a disclaimer for that when first mentioned.
This would preferably be included at the following section: https://0xmiden.github.io/miden-docs/imported/miden-base/src/note.html#note-discovery
贡献指南
评估
这个 Issue 还没有评估数据。