Motivation
Developers coming from the EVM/Solidity world face a steep mental-model jump when approaching Miden: account-based global state vs. account-centric local state, global on-chain execution vs. client-side proving, transfer() calls vs. note creation/consumption, etc.
The get-started section explains Miden's concepts (accounts, notes, storage) well on their own terms, but there is no single page that maps familiar EVM/Solidity concepts to their Miden counterparts. Such a mapping page would significantly flatten the onboarding curve for the largest existing developer audience in web3.
Proposed change
Add a new page under docs/builder/get-started/ (working title: "Coming from Ethereum / Solidity", e.g. evm-developers.md), containing:
-
Concept mapping table — a quick-reference cheat sheet, roughly:
| Ethereum / Solidity |
Miden |
| Smart contract (code + storage) |
Account (code + storage) |
| Storage slots / mappings |
Account storage slots & storage maps |
| ERC-20 token |
Fungible asset issued by a faucet account |
transfer(to, amount) |
Creating a P2ID note, which the recipient consumes |
msg.sender |
Account authentication component (e.g. signature scheme) |
| Events / logs |
Notes (the primary communication primitive) |
| Global, on-chain execution |
Local execution with a ZK proof submitted on-chain |
| Public mempool |
Public vs. private notes; note transport for private data |
-
Mental model shifts — short paragraphs on the big differences:
- Note-based (UTXO-like) asset transfers vs. account-based balance updates
- Client-side proving & local state vs. global state machine replication
- Public and private state/notes
-
Side-by-side code comparison — a minimal Solidity ERC-20 transfer() next to its TypeScript web-client equivalent (creating/consuming a P2ID note), so readers can anchor new concepts to code they already understand.
-
Where to go next — relative links to the existing accounts, notes, read-storage, and smart-contract sections.
Notes
- The get-started sidebar is autogenerated, so the page only needs frontmatter (
sidebar_position) — no sidebars.ts change required.
- I will follow the repo conventions: run
npm run build before opening the PR, use relative internal links, and keep the diff limited to the new page.
I'm happy to write this page and open the PR. Could a maintainer confirm the placement/title and assign this issue to me?
Motivation
Developers coming from the EVM/Solidity world face a steep mental-model jump when approaching Miden: account-based global state vs. account-centric local state, global on-chain execution vs. client-side proving,
transfer()calls vs. note creation/consumption, etc.The get-started section explains Miden's concepts (accounts, notes, storage) well on their own terms, but there is no single page that maps familiar EVM/Solidity concepts to their Miden counterparts. Such a mapping page would significantly flatten the onboarding curve for the largest existing developer audience in web3.
Proposed change
Add a new page under
docs/builder/get-started/(working title: "Coming from Ethereum / Solidity", e.g.evm-developers.md), containing:Concept mapping table — a quick-reference cheat sheet, roughly:
transfer(to, amount)msg.senderMental model shifts — short paragraphs on the big differences:
Side-by-side code comparison — a minimal Solidity ERC-20
transfer()next to its TypeScript web-client equivalent (creating/consuming a P2ID note), so readers can anchor new concepts to code they already understand.Where to go next — relative links to the existing
accounts,notes,read-storage, and smart-contract sections.Notes
sidebar_position) — nosidebars.tschange required.npm run buildbefore opening the PR, use relative internal links, and keep the diff limited to the new page.I'm happy to write this page and open the PR. Could a maintainer confirm the placement/title and assign this issue to me?