Skip to content

docs: Add an EVM/Solidity developer onboarding page (mental model mapping) #353

Description

@mehmetkr-31

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:

  1. 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
  2. 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
  3. 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.

  4. 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?

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    Priority

    None yet

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions