[Docs]: Update `Asset` and `State` sections #1030

phklive · 2024-12-19T16:59:10Z

In this PR I propose to update the Asset section of the Miden documentation:

more explanative
more approachable for new developers
shortened
simplified
re-phrased
updated structure

Additional questions:

Should we describe what Miden asset model is?

Dominik1999

Looks good, thanks. I left some comments. I am not sure, if I would use a white background for the pictures, that looks weird in DarkMode.

docs/architecture/assets.md

Co-authored-by: Dominik Schmid <35031754+Dominik1999@users.noreply.github.com>

…n/miden-base into phklive-docs-update-assets

bobbinth

Looks good! Thank you. I left some comments inline.

docs/architecture/assets.md

bobbinth · 2024-12-30T08:04:27Z

docs/architecture/assets.md


-Faucets can create assets and immediately distribute them by producing notes. However, assets can also stay in the faucet after creation to be sent later, e.g., in a bundle. That way, one can mint a million NFTs locally in a single transaction and then send them out as needed in separate transactions in the future.
+Faucets can issue either fungible or non-fungible assets as defined at account creation. The faucet's code specifies the asset minting conditions: i.e., how, when, and by whom these assets can be minted. Once minted, they can be transferred to other accounts using notes.

 ![Architecture core concepts](../img/architecture/asset/asset-issuance.png)


I think this picture could be improved:

It feels disproportionally big (I think we can reduce the size of text and shapes quite a bit).

I would probably not introduce new colors - e.g., in Miden VM docs arrows also use back color.

I would maybe add some simple comments to make it easier to understand what's what.

Agreed. Perhaps the arrows from the faucet to the note should be labelled "issues", as in, "the faucet issues notes" and the arrows from the notes to the accounts should be labelled "transferred", as in, "the notes are transferred to the accounts"?

bobbinth · 2024-12-30T08:05:17Z

docs/architecture/assets.md


 ### Storage

-[Accounts](accounts.md) and [notes](notes.md) contain asset vaults that are used to store assets. Accounts can keep unlimited assets in a sparse Merkle tree called `account vault`. Notes can store up to `255` distinct assets.
+[Accounts](accounts.md) and [notes](notes.md) have vaults used to store assets.

 ![Architecture core concepts](../img/architecture/asset/asset-storage.png)


Similar to the above comment, I think this graphic can be improved.

docs/architecture/assets.md

bobbinth · 2024-12-30T08:10:07Z

docs/architecture/assets.md


-### Issuance
+## What is an asset?


I find having lots of small sections a bit distracting - though, maybe that's just in Github rendering and it it would look better in mdBook rendering.

PhilippGackstatter

Looks good to me!

When I run the serve-doc-site.sh script as-is with mkdocs --strict I'm getting a few errors regarding broken links. Looks like this isn't part of CI but it probably should be to catch such errors?

docs/architecture/accounts.md

docs/architecture/assets.md

PhilippGackstatter · 2025-01-07T13:12:53Z

docs/architecture/assets.md


-Faucets can create assets and immediately distribute them by producing notes. However, assets can also stay in the faucet after creation to be sent later, e.g., in a bundle. That way, one can mint a million NFTs locally in a single transaction and then send them out as needed in separate transactions in the future.
+Faucets can issue either fungible or non-fungible assets as defined at account creation. The faucet's code specifies the asset minting conditions: i.e., how, when, and by whom these assets can be minted. Once minted, they can be transferred to other accounts using notes.

 ![Architecture core concepts](../img/architecture/asset/asset-issuance.png)


Agreed. Perhaps the arrows from the faucet to the note should be labelled "issues", as in, "the faucet issues notes" and the arrows from the notes to the accounts should be labelled "transferred", as in, "the notes are transferred to the accounts"?

docs/architecture/assets.md

docs/architecture/notes.md

docs/architecture/assets.md

docs/architecture/accounts.md

* Updated docs state * Update docs/architecture/state.md Co-authored-by: Dominik Schmid <35031754+Dominik1999@users.noreply.github.com> * Update docs/architecture/state.md Co-authored-by: Dominik Schmid <35031754+Dominik1999@users.noreply.github.com> * Update docs/architecture/state.md Co-authored-by: Dominik Schmid <35031754+Dominik1999@users.noreply.github.com> * Update docs/architecture/state.md Co-authored-by: Dominik Schmid <35031754+Dominik1999@users.noreply.github.com> * Update docs/architecture/state.md Co-authored-by: Dominik Schmid <35031754+Dominik1999@users.noreply.github.com> * Rewording * Singular for titles * Update docs/architecture/state.md Co-authored-by: Dominik Schmid <35031754+Dominik1999@users.noreply.github.com> * Rewording for nullifiers * Update docs/architecture/state.md Co-authored-by: Philipp Gackstatter <PhilippGackstatter@users.noreply.github.com> * Update docs/architecture/state.md Co-authored-by: Philipp Gackstatter <PhilippGackstatter@users.noreply.github.com> * Second wave of updates * Updated notes section * Standardize writing accross modified docs --------- Co-authored-by: Dominik Schmid <35031754+Dominik1999@users.noreply.github.com> Co-authored-by: Philipp Gackstatter <PhilippGackstatter@users.noreply.github.com>

Dominik1999

Left some smaller comments. Once resolved we can merge

docs/architecture/assets.md

docs/architecture/notes.md

docs/architecture/state.md

Dominik1999 · 2025-01-21T09:23:23Z

docs/architecture/state.md

-Nullifiers are stored in a sparse Merkle tree, which maps [note nullifiers](notes.md#note-nullifier-to-ensure-private-consumption) to block numbers at which the nullifiers are inserted into the chain (or to `0` for nullifiers which haven't been recorded yet). Nullifiers provide information on whether a specific note has been consumed. The database allows proving that a given nullifier is not in the database.
+Each [note](notes.md) has an associated nullifier which enables the tracking of whether it's associated note has been consumed or not, preventing double-spending.
+
+To prove that a note has not been consumed, the operator must provide a Merkle path to the corresponding node and show that the node’s value is 0. Since nullifiers are 32 bytes each, the Sparse Merkle Tree height must be sufficient to represent all possible nullifiers. Operators must maintain the entire nullifier set to compute the new tree root after inserting new nullifiers. For each nullifier we also record the block in which it was created. This way "unconsumed" nullifiers have block 0, but all consumed nullifiers have a non-zero block.


To prove that a note has not been consumed, the operator must provide a Merkle path to the corresponding node and show that the node’s value is 0.

It should be Note, right?

But why does the operator need to do that?

Here note is correct.

Will merge it like that and change it if needed.

My understanding is that the node must respond to the user with a merkle proof to the nullifier with a node value of 0, proving that the note has not been consummed.

If the node value is something else (e.g. the block in which the note has been consume) it means that the note has been consummed.

Hence this check is needed before a user consumes a note to make sure he consumes a note that has not yet been consummed.

But here is node, no? to the corresponding node

docs/architecture/state.md

…n/miden-base into phklive-docs-update-assets

Updated assets documentation

4487764

phklive added the no changelog This PR does not require an entry in the `CHANGELOG.md` file label Dec 19, 2024

phklive self-assigned this Dec 19, 2024

phklive requested a review from Dominik1999 December 19, 2024 16:59

phklive marked this pull request as ready for review December 19, 2024 17:09

Dominik1999 approved these changes Dec 20, 2024

View reviewed changes

phklive and others added 11 commits December 20, 2024 13:03

Update docs/architecture/assets.md

235cbfa

Co-authored-by: Dominik Schmid <35031754+Dominik1999@users.noreply.github.com>

Update docs/architecture/assets.md

506050b

Co-authored-by: Dominik Schmid <35031754+Dominik1999@users.noreply.github.com>

Update docs/architecture/assets.md

d54f645

Co-authored-by: Dominik Schmid <35031754+Dominik1999@users.noreply.github.com>

Update docs/architecture/assets.md

5b06041

Co-authored-by: Dominik Schmid <35031754+Dominik1999@users.noreply.github.com>

Update docs/architecture/assets.md

e078b9a

Co-authored-by: Dominik Schmid <35031754+Dominik1999@users.noreply.github.com>

Update docs/architecture/assets.md

8f96ae1

Co-authored-by: Dominik Schmid <35031754+Dominik1999@users.noreply.github.com>

Update docs/architecture/assets.md

2ca6f27

Co-authored-by: Dominik Schmid <35031754+Dominik1999@users.noreply.github.com>

Update docs/architecture/assets.md

2d48a50

Co-authored-by: Dominik Schmid <35031754+Dominik1999@users.noreply.github.com>

Update docs/architecture/assets.md

6c9248d

Co-authored-by: Dominik Schmid <35031754+Dominik1999@users.noreply.github.com>

Updates

2782e65

Merge branch 'phklive-docs-update-assets' of github.com:0xPolygonMide…

71126fc

…n/miden-base into phklive-docs-update-assets

phklive requested a review from bobbinth December 20, 2024 16:47

bobbinth reviewed Dec 30, 2024

View reviewed changes

phklive requested a review from PhilippGackstatter January 7, 2025 10:10

PhilippGackstatter reviewed Jan 7, 2025

View reviewed changes

docs/architecture/accounts.md Show resolved Hide resolved

phklive and others added 4 commits January 7, 2025 17:14

Applied first wave of comments

d6c8580

Added dot in notes

a2d508e

Standardize writing accross modified docs

d008cc0

phklive changed the title ~~[Docs]: Update Asset section~~ [Docs]: Update Asset and State sections Jan 9, 2025

Dominik1999 approved these changes Jan 21, 2025

View reviewed changes

phklive added 2 commits January 21, 2025 19:38

Merge branch 'main' into phklive-docs-update-assets

bbab787

Started final update

8f1d925

phklive added 2 commits January 21, 2025 19:42

Merge branch 'phklive-docs-update-assets' of github.com:0xPolygonMide…

b6bffe3

…n/miden-base into phklive-docs-update-assets

Added final updates

f7635dd

phklive merged commit e2f6883 into main Jan 21, 2025
9 checks passed

phklive deleted the phklive-docs-update-assets branch January 21, 2025 21:41

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Docs]: Update `Asset` and `State` sections #1030

[Docs]: Update `Asset` and `State` sections #1030

phklive commented Dec 19, 2024

Dominik1999 left a comment

bobbinth left a comment

bobbinth Dec 30, 2024

PhilippGackstatter Jan 7, 2025

bobbinth Dec 30, 2024

bobbinth Dec 30, 2024

PhilippGackstatter left a comment •

edited

Loading

PhilippGackstatter Jan 7, 2025

Dominik1999 left a comment

Dominik1999 Jan 21, 2025

Dominik1999 Jan 21, 2025

phklive Jan 21, 2025

phklive Jan 21, 2025

Dominik1999 Jan 21, 2025

[Docs]: Update Asset and State sections #1030

[Docs]: Update Asset and State sections #1030

Conversation

phklive commented Dec 19, 2024

Dominik1999 left a comment

Choose a reason for hiding this comment

bobbinth left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

PhilippGackstatter left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Dominik1999 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

[Docs]: Update `Asset` and `State` sections #1030

[Docs]: Update `Asset` and `State` sections #1030

PhilippGackstatter left a comment •

edited

Loading