0xMiden / 0xMiden/protocol

Docs: Assets Page improvements

Open
#1,827 5 comments 1 reaction 0 assignees View on GitHub
documentation
Dominant language
Rust
Stars
132
Forks
167
Avg merge
1d 23h
Merged PRs (30d)
110

Description

This issue refers to the following page: https://0xmiden.github.io/miden-docs/imported/miden-base/src/account/overview.html

There are multiple things that can be improved on the Accounts page documentation. Here's a list:

### 1. Title and Smart Contract Clarification

**Issues:**
- Change title from current to just "Accounts"
- Not clear that Accounts are Smart Contracts, especially confusing for Ethereum developers who distinguish between EOAs and Smart Contracts
- **Suggested improvement:**
```
An Account represents the primary entity in Miden. All accounts are smart contracts, programmable entities capable of holding assets, storing data, and executing code. Each Account is a smart contract with a programmable interface through which note scripts (logic attached to messages/notes) and transaction scripts (logic executed during a transaction) can interact with the account's state and assets. By executing transactions against an account, its state can be modified.
```

### 2. SWAP Notes Example

**Issue:** "Two SWAP notes matched together" explanation unclear
- **Suggested improvement:** "For example, if two trade orders are matched entirely within existing notes without altering the account's vault or storage"

### 3. Asset Encoding Explanation

**Issue:** Page doesn't explain how "encoding" of assets works, making fungible/non-fungible distinction unclear
- **Action needed:** Add disclaimer about how encoding works to improve clarity of asset type distinctions

### 4. Native Asset definition

**Issue:** "Native asset" definition needs clarification
- **Suggested improvement:**
```
A native asset is one that follows Miden's standard encoding, issuance, and storage rules. This makes it directly compatible with the protocol's asset-handling functions and guarantees it can be stored in accounts and notes without custom logic.
```

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.