0xMiden / 0xMiden/protocol

Docs: Notes Page improvements

オープン
#1,825 コメント 7 件 リアクション 1 件 担当者 1 名 @BrianSeong99 が担当を希望しています GitHub で見る
documentation
主要言語
Rust
スター
132
フォーク
167
平均マージ
1日 23時間
マージ済み PR(30日)
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 はまだ評価されていません。

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。