Read-through: a Michelson developer trying to call an existing EVM contract

[NicNomadic]

The persona: a competent Tezos developer — 4 years of SmartPy, FA2 contracts in production, fluent with Taquito and octez-client, but zero Solidity and no idea what ABI encoding or a function selector is. The goal: a loyalty-points contract in SmartPy that, via NAC, (a) transfers USDC (an existing ERC-20 on the EVM side) to a user, (b) reads a USDC balance first, (c) handles a failed transfer cleanly.

The journey

1. They open the obvious page, michelson/nac-usage.md, and hit line 19: "Call an EVM contract by providing … the destination address, entrypoint selector, and ABI-encoded data." Neither "entrypoint selector" nor "ABI-encoded" is defined or linked anywhere (both are absent from the glossary), no Michelson types are given for the parameters, and there is no code example — in either Michelson or SmartPy — on the entire page. Compare evm/nac-usage.md:30-43, which gives the opposite direction a full Solidity interface plus a concrete call. The asymmetry is exactly backwards relative to need: the Solidity dev already knows ABI encoding; the Michelson dev is the one who needs the worked example.
2. They spot the ERC-20 wrapper (michelson/nac-usage.md:24-30, KT18oDJ…KvCChb) — which sounds like exactly the escape hatch they need. But the page lists no entrypoint signatures, no parameter types, no example call, and doesn't say whether the wrapper takes the target token address as a parameter (usable for any ERC-20, including USDC) or is bound to a fixed token. They literally cannot use it from what's written.
3. They look for the USDC address. It exists — evm/developing/tokens.mdx:38 — but that page is never linked from michelson/nac-usage.md or the NAC overview; our reader only found it by grepping. A Michelson dev following the docs' own navigation doesn't think to look under EVM → Developing.
4. They want to read the balance before transferring, so they look for the Michelson→EVM equivalent of callMichelsonView (evm/nac-usage.md:62-91). There is none, anywhere — and the docs don't say whether that's because it doesn't exist yet or because it's just undocumented. Silence reads as a docs gap; if the feature doesn't exist, saying so explicitly (with the workaround, e.g. an off-chain relayer doing eth_call) would actually be the better page.
5. They ask "what happens to my contract if the EVM transfer reverts?" The answer exists — overview/resources.md:38-39 (whole operation group reverts, standard Michelson semantics) — but not on the NAC usage page, and nothing links the two. Same for gas: the conversion is automatic (overview/resources.md:34-40), consistent with call_evm taking no gas parameter, but the reader has to cross-reference two pages to conclude that. The callback pattern with_result is named (michelson/nac-usage.md:36) with no signature and no example of the callback entrypoint a contract must implement.
6. They fall back to the tutorial — and discover tutorials/nac-counter.md only wires the EVM→Michelson direction (michelson/getting-started.md:26-28 says as much). examples/potluck-game.md is also EVM→Michelson (via an off-chain relayer). There is no worked example of a Michelson contract initiating a NAC call in the whole doc set.

Where they end up: they know the mechanism exists (call_evm, the wrapper, with_result) but cannot write a single line of it without guessing or asking a Solidity colleague. A recurring pattern: much of the information exists but was written from the EVM context and is never linked from the Michelson entry point — gas, alias formula, token addresses are all findable only if you already know to look on the other side.

Suggested scope for the follow-up issue

1. Rewrite michelson/nac-usage.md to mirror evm/nac-usage.md: exact call_evm signature with Michelson types (parameter/type table), one complete SmartPy example calling an arbitrary ERC-20, direct links to overview/resources.md (gas/failure semantics) and to the token-address table.
2. Document the ERC-20 wrapper properly: entrypoint signatures, whether it's parameterized by token address, one example against an already-deployed token, failure behavior.
3. A "read-only calls from Michelson" section: either the view mechanism if it exists, or an explicit "not currently possible — here is the workaround" note. (Question for the kernel team: does a Michelson→EVM view exist, and is the wrapper token-parameterized? The docs should state whichever is true.)
4. Specify with_result: the callback entrypoint's exact parameter type, a SmartPy example, and the no-callback failure behavior stated on this page (not only in resources.md).
5. A mirror tutorial (Michelson contract initiating a NAC call to an ERC-20 on Previewnet), with success verified on both sides (Michelson storage + Blockscout).
6. Glossary: add ABI encoding and function selector.