Skip to content

docs: add "Coming from Ethereum" page for EVM/Solidity developers - #354

Draft
mehmetkr-31 wants to merge 2 commits into
0xMiden:mainfrom
mehmetkr-31:docs-evm-developers-onboarding
Draft

docs: add "Coming from Ethereum" page for EVM/Solidity developers#354
mehmetkr-31 wants to merge 2 commits into
0xMiden:mainfrom
mehmetkr-31:docs-evm-developers-onboarding

Conversation

@mehmetkr-31

Copy link
Copy Markdown

Closes #353

Summary

Adds a new get-started page, "Coming from Ethereum" (docs/builder/get-started/evm-developers.md), that maps familiar Ethereum/EVM/Solidity concepts to their Miden equivalents. The goal is to flatten the onboarding curve for the largest existing web3 developer audience.

The page contains:

  1. The three big shifts — local execution + ZK proofs vs. global re-execution; note-based (UTXO-like) two-transaction transfers vs. account-based balance updates; privacy by default.
  2. Concept mapping table — smart contract → account, mapping/state variables → storage slots & maps, ERC-20 → fungible faucet, transfer() → P2ID note, msg.sender → authentication component, eth_callexecuteProgram, events → notes, etc.
  3. Side-by-side code comparison — a Solidity ERC-20 transfer() next to the TypeScript web-client equivalent (client.transactions.send + consume), with the two-transaction model explained.
  4. Smart contract differences — Rust → MASM, 255 storage slots + storage maps, no implicit msg.sender.
  5. Where to go next — relative links to accounts, notes, read-storage, and smart-contracts.

Conventions followed

  • sidebar_position: 6 in frontmatter only — the get-started sidebar is autogenerated, so no sidebars.ts change is needed.
  • Only relative internal links; all four link targets verified to exist locally.
  • Terminology and code style matched to the existing accounts.md / notes.md pages (e.g. "onchain", MidenClient.createTestnet(), the executeProgrameth_call analogy already used in the web-client docs).

Build note

npm run build fails locally on a pre-existing, unrelated issue: sidebars.ts references doc IDs that are ingested from external repos at CI time (rust-client, note-transport, bridging, tutorials/recipes, miden-bank, …), which don't exist in a fresh local clone. I verified the failure is identical on a clean main checkout, and that this new page (builder/get-started/evm-developers) is correctly discovered by the docs plugin. The full build should pass in CI where ingestion runs.

Happy to adjust the page title, placement (sidebar_position), or content scope if you'd prefer something different.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 39a4539f35

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

});

// Tx 2 (Bob): consume the note; the tokens move into Bob's vault.
await client.transactions.consume({ account: bobWallet, notes: noteId });

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Define the note before consuming it

In this private-transfer example, the send call only destructures txId, but the next transaction consumes noteId, which is never declared or fetched. Readers copying this snippet will hit a runtime/reference error rather than learning the two-step flow; the example needs to either request/derive the created note ID (for example via the documented return/list path) and, for a private note, make it available to Bob through transport/import before calling consume.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 39d89a2 — the example is now split into two snippets: Tx 1 uses the documented returnNote: true path so the created note (and its ID) is defined, and Tx 2 shows Bob's client fetching the private note via client.notes.fetchPrivate() + listAvailable() before consume().

@mehmetkr-31
mehmetkr-31 marked this pull request as draft August 10, 2026 17:10
@mehmetkr-31

Copy link
Copy Markdown
Author

Converted to draft: holding for maintainer confirmation on #353 (placement / title / assignment). The page is ready as a preview here — happy to adjust once a maintainer weighs in.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

1 participant