eth-to-sol

# eth-to-sol Translate Ethereum/Solidity contracts to production-grade Solana programs. The goal is not a 1:1 port — it is Solana-native code plus a teaching artifact that makes every decision legible to a developer who knows Solidity well and Solana barely. This skill ships standalone from any app that invokes it. Keep outputs scoped to programs, accounts, transactions, and developer-facing API integration. Do not produce UI artifacts such as React components, screens, CSS, app copy, or visual design guidance. ## Two-pass protocol (hard rule) Every translation produces two outputs in sequence. Do not collapse them. 1. **Pass 1 — Faithful port.** A semantically identical Anchor program. No restructuring, no SPL CPI substitutions, no parallelism rework. It exists so the refactor's value is legible. Mark obviously un-Solana patterns with `// SMELL:` comments rather than fixing them. 2. **Pass 2 — Solana-native refactor.** Restructured for Solana primitives: SPL programs via CPI, per-entity PDAs, parallelism-friendly account layout, explicit rent/sizing, compute-budget awareness, program splitting where warranted. Production-ready. If a contract is trivially served by an existing Solana program (e.g. a vanilla ERC-20), the optimized version will be drastically smaller than the naive port. That is the lesson. ## Output contract For an input named `foo`, produce exactly these artifacts: | File | Contents | |---|---| | `01-original.<ext>` | The input (Solidity, Vyper, etc.). Already present; do not rewrite. | | `02-naive-port.rs` | Pass 1. Compiles. Inline `// SMELL:` markers on antipatterns. | | `03-optimized.rs` | Pass 2. Production-ready, fully commented at non-obvious sites. | | `04-diff.md` | Structured diff. **Group sections by theme** (State model / Parallelism / Security / CPI & program reuse / Compute & rent / Idioms) — mirror the explanation log. Each section: short header, before/after snippets, `file:line` references to the two `.rs` files. | | `05-explanation.md` | The explanation log. One entry per change in `04-diff.md`, grouped by theme. Schema below. | When the optimized version meaningfully changes non-program integration (typically: SPL Token replaces a custom token surface, balance/aggregate lookups move off the program, or transaction/account lists change), append a `## Client/API integration notes` section at the bottom of `05-explanation.md`. Keep it to account derivation, required accounts, ATA creation, transaction construction, SDK call shape, and migration scoping. Do not include UI components, screens, styling, or app-specific copy. If the integration shift is minor, fold it into a relevant entry's Tradeoff instead. `05-explanation.md` is the teaching surface. Treat it as a first-class deliverable, not a comment block. ## Read first Before producing any translation, internalize the EVM → SVM mental shift in `translation/mental-model.md`. The one-line summary: *on Ethereum the contract knows where its state lives; on Solana the caller brings it.* Every translation rule below is a consequence — if a step ever feels wrong, return to that file. ## Decision tree — which sub-files to load Default-load: `translation/mental-model.md`, `translation/type-mapping.md`, `translation/pattern-mapping.md`, `security/arithmetic.md`, `security/account-validation.md`, `security/pda-canonicalization.md`. The default loads are non-negotiable. The mental-model file frames every other decision; arithmetic, account validation, and PDA canonicalization are the three security classes that bite *every* ported contract. | Source contains | Also load | |---|---| | ERC-20 / fungible token | `translation/stdlib-mapping.md`, `optimization/account-model.md`, `security/cpi-safety.md` | | ERC-20 with `_update` / `_beforeTokenTransfer` override (fee-on-transfer, blacklist, paused-transfer, rebasing) | `translation/stdlib-mapping.md` (Token-2022 section); target Token-2022 with the matching extension (transfer fee, transfer hook, default account state, interest-bearing). Do **not** target classic SPL — the semantics cannot be expressed. | | ERC-721 / ERC-1155 / NFT | `translation/stdlib-mapping.md`, `optimization/account-model.md`, `optimization/pdas.md` | | `mapping(...)` storage | `optimization/account-model.md`, `optimization/pdas.md`, `optimization/parallelism.md` | | Ownable / AccessControl / roles | `translation/stdlib-mapping.md`, `security/signer-checks.md` | | Custom modifiers | `translation/pattern-mapping.md`, `security/signer-checks.md` | | External calls / interfaces | `security/cpi-safety.md`, `security/reentrancy.md`, `optimization/program-splitting.md` | | Heavy arithmetic / fixed-point | `security/arithmetic.md` (also default-loaded) | | Hot-write global state (counters, `totalSupply`) | `optimization/parallelism.md`, `optimization/account-model.md` | | Dynamic-sized state (arrays, mappings of unknown size) | `optimization/rent-and-size.md`, `optimization/account-model.md` | | Multi-contract system | `optimization/program-splitting.md`, `security/cpi-safety.md` | | Anything writing state after an external call | `security/reentrancy.md`, `security/cpi-safety.md` | | Compute-pressured paths (multi-CPI swaps, loops in hot path, >300 expected CU per call) | `optimization/compute-budget.md` | | Multiple account types owned by the program (type-confusion risk surface) | `security/account-validation.md` (also default-loaded) | | Any PDA the program will sign for | `security/pda-canonicalization.md` (also default-loaded), `optimization/pdas.md` | | Protocol takes a user-supplied token Mint as configuration (vault, AMM, lending market) | `security/reentrancy.md`, `security/account-validation.md`, `security/cpi-safety.md` | | Vault/AMM/4626-shaped protocol (share/asset conversion math, deposit + withdraw + redeem semantics) | `security/arithmetic.md` (rounding-direction discipline), `optimization/account-model.md` (read aggregates from SPL Token), `optimization/parallelism.md` (read-only vault pattern) | | Time-delta math (`now - last_update`, accumulator periods) | `security/arithmetic.md` (clock-skew + negative-delta-cast pitfall) | | Large account graph, payment batch, swap route, many recipients, or transaction-size concern | `optimization/transactions-and-commitment.md`, `optimization/compute-budget.md` | | Priority fees, local fee markets, compute limit, recent blockhash, retry/expiry, or landing strategy | `optimization/transactions-and-commitment.md`, `optimization/compute-budget.md` | | Settlement, irreversible off-chain action, indexer correctness, or commitment-level choice | `optimization/transactions-and-commitment.md` | | Client SDK/tooling/testing migration asks (`@solana/kit`, `web3.js`, Anchor client, LiteSVM, Bankrun, local validator) | `optimization/transactions-and-commitment.md` | Always load every security/* file relevant to the constructs present. Security is non-negotiable. ## Module 1B source alignment This skill tracks Solana Enterprise Training Module 1B, "From EVM to SVM": https://github.com/solana-foundation/solana-enterprise-training/tree/main/module-1b-from-evm-to-svm Use the module as source alignment, not as shipped course UI. The skill should reference the engineering concepts below and avoid slides, quizzes, UI, or app-specific teaching surfaces. | Module 1B topic | Skill coverage | |---|---| | Purpose, prerequisites, and learning objectives | This `SKILL.md` assumes a Solidity-fluent reader with baseline Solana awareness and scopes outputs to translation artifacts, not course delivery. | | Mental-model shift: "you bring the state" | `translation/mental-model.md` | | Account model translation: storage slots, mappings, PDAs, explicit signers, upgrades, IDL/logs/time | `translation/mental-model.md`, `translation/type-mapping.md`, `translation/pattern-mapping.md`, `optimization/account-model.md`, `optimization/pdas.md` | | ERC-20 vs SPL Token: Mint, Token Account, ATA, allowances/delegates, decimals, token-account creation | `translation/stdlib-mapping.md`, `optimization/account-model.md`, `security/cpi-safety.md` | | Composability: EVM `call` vs Solana CPI and account-graph propagation | `translation/mental-model.md`, `security/cpi-safety.md`, `optimization/program-splitting.md` | | Reentrancy as a structural property and the replacement failure modes | `security/reentrancy.md`, `security/cpi-safety.md`, `security/account-validation.md` | | Solana program security checklist: ownership, signer checks, substitution, discriminators, arithmetic, CPI authority, safe close, rent | `security/account-validation.md`, `security/signer-checks.md`, `security/pda-canonicalization.md`, `security/arithmetic.md`, `security/cpi-safety.md`, `optimization/rent-and-size.md` | | Transactions in practice: recent blockhash, expiry, versioned transactions, ALTs, compute budget, priority fees, local fee markets | `optimization/transactions-and-commitment.md`, `optimization/compute-budget.md`, `optimization/parallelism.md` | | Commitment levels for settlement and indexing | `optimization/transactions-and-commitment.md` | | Developer workflow: `@solana/kit`, legacy `web3.js`, Anchor client, LiteSVM, Bankrun, local validator | `optimization/transactions-and-commitment.md` | | Cumulative EVM/SVM reference | `translation/mental-model.md` plus the referenced translation, optimization, and security files | | Quiz and slides | Do not ship; those are course surfaces, not skill runtime material. | | Additional resources | Keep external: Solana Cookbook, Anchor Book, Neodyme Common Pitfalls, Sec3 audit checklist, Solana Program Examples, Helius priority-fee guide, and official Solana fee docs. | ## Pre-flight checklist (gate on the optimized version) Every item must hold before emitting `03-optimized.rs`. If one fails, fix and re-check. - [ ] Every arithmetic op is `checked_*` — or has an inline justification for `saturating_*` / `wrapping_*`. No bare `+ - * /` on user-controlled values. - [ ] Every `Account<'info, T>` either uses Anchor's typed checks or includes explicit owner + discriminator validation. No `AccountInfo` smuggled through without checks. - [ ] Every signer-required path uses `Signer<'info>` or a manual `is_signer` check. No "the client won't call it without a signer" reasoning. - [ ] Every PDA derivation either uses `seeds = [...], bump = stored_bump` (preferred — saves ~1.5k CU per call) or bare `seeds = [...], bump,` (acceptable when CU is not pressured; both forms enforce canonicalization via Anchor's `find_program_address` check). The cached form is strongly preferred — all reference examples use it. Do **not** use `bump = <user_input>` — that's the actual canonicalization vulnerability. - [ ] CPIs use `CpiContext::new` or `CpiContext::new_with_signer`. The program arg is a `Pubkey` (use `ctx.accounts.<program>.key()`) — Anchor 1.0+ removed the `AccountInfo` form. No hand-rolled `invoke`/`invoke_signed` with manually assembled `AccountInfo` arrays unless raw Solana is justified. - [ ] No path mutates state after a CPI to an untrusted program without re-reading and re-validating. (See `security/reentrancy.md` for why account locking is necessary but not sufficient.) - [ ] Account sizing is explicit: `space = 8 + <sum>`; the 8 is the Anchor discriminator. Variable-size fields have hard caps. - [ ] Errors use `#[error_code]`. No `ProgramError::Custom(n)` literals, no `msg!`-then-fail. - [ ] No PDA shares a write lock with high-frequency unrelated state. Per-entity PDAs over global counters where the protocol allows. - [ ] If the contract emits events that SPL programs already emit (Transfer for SPL Token), prefer not duplicating them. - [ ] Re-init protection: PDAs that should only init once use `init` (not `init_if_needed`) and have unique seeds. ## Tooling — Solana Developer MCP `rust_autofixer` If your environment exposes the Solana Developer MCP (`https://mcp.solana.com/mcp`), the `rust_autofixer` tool is part of the workflow — not optional. **When to call it:** every time you have produced or modified Anchor or Pinocchio Rust that you intend to ship. That includes `02-naive-port.rs` and `03-optimized.rs`, and any in-flight fix you apply after a failed `cargo check`. **How to call it:** pass the full Rust source. Specify the framework (`auto`, `anchor`, or `pinocchio`) if the caller hasn't already. **The loop:** 1. Call `rust_autofixer` on the current Rust. 2. Apply every suggested fix (they are mechanical, structured, and safe). 3. Call `rust_autofixer` again. 4. Repeat until `require_another_tool_call_after_fixing` is `false`. Only emit the artifact once the loop terminates. This is in addition to — not a replacement for — the pre-flight checklist above; the autofixer catches the structural-safety class of bug, the checklist catches design/idiom issues. **Do not use any other Solana MCP tool** (`list_sections`, `read_section`, `search`, etc.) for this workflow. Stay scoped to `rust_autofixer`. ## Explanation log opener Before the first `## Theme` heading, the explanation log opens with a short prose preamble. The preamble must, in this order: 1. **One paragraph: what the program does in EVM-developer terms.** State the protocol the way you'd state it to a Solidity dev who's never seen the contract — "a one-shot ERC-20 crowdfund: supporters deposit tokens before a deadline; if the goal is met the creator claims the pot, otherwise supporters refund." Don't lead with what the example *teaches*; lead with what the program *does*. 2. **One paragraph: the Solana shape it ports to.** What the program looks like on Solana at the same height of abstraction — "On Solana, the same protocol becomes one PDA per supporter plus a singleton fundraiser account; SPL Token handles the actual token movement via CPIs." Still no per-line / per-symbol detail. Any optional context that follows (vocabulary list, reference-implementation link, etc.) comes after these two paragraphs, not before. ## Explanation log schema Each entry is exactly five fields. Keep them tight — one to four sentences each. ``` ### <short title> - **Title rules.** When the change has a Solidity counterpart (most state-model / security / idiom entries), frame the title as `Solidity-side → Solana-side` — e.g. `mapping(address => uint256) ledger → per-supporter PDA`, not `Vec<Contribution> → per-supporter PDA`. A Solidity-fluent reader of `03-optimized.rs` has not opened the naive port; titles that name naive-port Rust types (`Vec<X>`, `iter_mut().find(...)`, etc.) read as gibberish to them. When the change is Solana-only hygiene (no Solidity counterpart — bump caching, PDA seed consolidation, account-size optimizations), use a plain descriptive title without the arrow. - **What:** the concrete change as a diff between the naive port and the optimized port. Reference the diff section or `file:line` in the .rs files. This is the LOW-LEVEL diff view; cite specific identifiers, function names, line numbers. Written for someone reviewing the diff side-by-side. - **Annotation:** a self-contained explanation of THIS code (the optimized version) for a Solidity-fluent reader who is looking only at the optimized file and has never seen the naive port. State what the optimized code does at this point, why a Solidity developer's mental model has to shift here, and — when meaningful — what a naive translation would have done and why this shape is preferable. Do NOT cite the naive port by filename or reference any line outside the optimized file. Two to four sentences. - **Why:** the platform-level reasoning, structured as a two-sided contrast for a Solidity-fluent reader. Lead the first sentence(s) with **"On Ethereum, ..."** and describe the EVM/Solidity paradigm the developer is bringing with them. Then lead the next sentence(s) with **"On Solana, ..."** and describe the paradigm that diverges. Keep it HIGH-LEVEL — platform mechanics, mental model, what serializes / what doesn't, who owns what, what the runtime guarantees. Save the per-line / per-symbol detail for `What:` and `Annotation:`. Avoid backtick code fragments here unless absolutely necessary. - **Benefit:** what is gained. Be specific: CU saved, parallelism unlocked, security class avoided, code deleted. - **Tradeoff:** what is given up. If nothing meaningful, say so and justify briefly. ``` `What` is the "code review" view of the diff; `Annotation` is the "reader of the final code" view. They cover different audiences — both are needed because the final code is shipped on its own, but the diff is also part of the artifact set. Group entries under thematic headers: `## State model`, `## Parallelism`, `## Security`, `## CPI & program reuse`, `## Compute & rent`, `## Idioms`. ## Explanation style — write for a Solidity-fluent reader who has never seen Solana The reader knows Solidity well. They know financial systems. They have **not** internalized PDAs, the account model, SPL Token, rent, CPI, or Anchor's constraint vocabulary. The explanation log is where they bridge — every entry must land for that reader. ### Rules 1. **First-use translation, always inline.** The first time any Solana-specific term appears in a given explanation log, give a short EVM analog in parentheses or em-dashes. Don't assume a glossary; weave it into the prose. After first use, the term is fair game. Required glossing on first use (non-exhaustive): - **PDA** — "PDA (Program-Derived Address — a deterministic account address derived from seeds the program controls; analog of a Solidity storage slot keyed by `(address, mapping)` — but each PDA is its own account, not a slot inside the program)" - **SPL Token** — "SPL Token (the shared on-chain token program every fungible token reuses on Solana — instead of each ERC-20 deploying its own contract, every token is just configuration on this one program)" - **CPI** — "CPI (cross-program invocation — Solana's version of one contract `call`-ing another, but every account the callee will touch must already be in the caller's transaction)" - **rent** — "rent (a refundable SOL deposit every account pays to live on-chain; ~0.001 SOL per KB of account data, returned in full when the account is closed)"