English for Solidity Smart Contracts

Solidity discussions carry real financial stakes, so precise vocabulary around cost (gas) and safety (reentrancy) matters more than in most backend work — a vague description of a bug in a smart contract review can be the difference between catching an exploit and shipping one.

Key Vocabulary

Gas — the unit measuring the computational cost of an operation on Ethereum, paid by the transaction sender, which makes every loop, storage write, and external call a cost decision rather than just a performance one. “This function’s gas cost scales with array length, which means it’ll eventually become too expensive to call as the array grows — we need a different data structure.”

Reentrancy — a vulnerability where an external contract call, before the calling function finishes updating its own state, calls back into the original contract and exploits the stale state. “This withdrawal function is vulnerable to reentrancy because it sends funds before updating the balance — an attacker’s fallback function can call back in and drain it repeatedly.”

Modifier — a reusable piece of code, such as onlyOwner, that wraps a function to enforce a precondition before its body runs, keeping access control logic out of the function itself. “Add the onlyOwner modifier to this function instead of repeating the ownership check manually — it’s the idiomatic way to express that precondition.”

Upgradeability (proxy pattern) — a design pattern that separates a contract’s storage from its logic, letting the logic contract be swapped out while the storage and address stay the same, since deployed bytecode is otherwise immutable. “Because this contract isn’t behind a proxy, we can’t fix a bug post-deployment — we’d have to migrate users to an entirely new contract address.”

Checks-Effects-Interactions — the recommended pattern of validating conditions, then updating internal state, and only then making external calls, specifically to prevent reentrancy-style exploits. “Reorder this function to follow checks-effects-interactions — update the balance before calling .transfer(), not after.”

Common Phrases

• “What’s the gas cost of this loop at realistic array sizes, not just in the test case?”
• “Is this function vulnerable to reentrancy — does it call out before it finishes updating state?”
• “Should this precondition be its own modifier instead of inline require statements?”
• “Is this contract upgradeable, or is the current logic permanent once deployed?”
• “Does this function follow checks-effects-interactions, or is the external call happening too early?”

Example Sentences

Flagging a security issue in review: “This is a classic reentrancy pattern — the external .call() happens before the state update, so an attacker’s contract can re-enter and withdraw multiple times in one transaction.”

Explaining a gas optimization: “We moved this validation into a modifier and cached the array length outside the loop, which cut gas cost meaningfully for the common case.”

Discussing a deployment decision: “We’re deploying behind a proxy specifically so we can patch this logic if an audit turns up an issue post-launch, without having to migrate every user’s balance to a new address.”

Professional Tips

• Quantify gas cost concretely in review comments — “this is expensive” is vague, while “this loop’s gas cost grows linearly with array length” tells the author exactly what to fix.
• Name reentrancy explicitly when flagging the specific external-call-before-state-update pattern — it’s the single most consequential vocabulary word in a smart contract security review.
• Recommend checks-effects-interactions as the fix, not just “reorder your code” — naming the pattern shows the reviewer recognizes it as an established defense, not an ad hoc opinion.
• Clarify whether a contract is upgradeable early in any discussion of a bug fix timeline — it fundamentally changes whether a fix ships in hours or requires a full migration.

Practice Exercise

1. Explain what makes a function vulnerable to reentrancy in one sentence.
2. Describe why gas cost, not just correctness, matters when reviewing a loop in Solidity.
3. Write a sentence explaining what the proxy pattern trades off to allow upgradeability.

In Practice: Navigating Nuance for Non-Native Speakers

The transition to professional English in a technical field like Solidity can feel overwhelming. It’s not just about knowing the words – it’s understanding how those words are used within specific contexts, particularly when communicating with experienced developers and stakeholders. For non-native speakers, this often means grappling with subtle differences in phrasing that can significantly alter meaning or impact perception. Let’s consider a few common scenarios where precision is paramount.

One frequent issue arises during code reviews. A comment like “This function could be more gas efficient” might seem straightforward, but it’s frequently followed by a request for clarification: “Can you elaborate on why it’s inefficient? What specific areas are consuming the most gas?” The original statement lacks actionable information. A better phrasing, aiming for clarity and collaboration, would be, “I’m seeing elevated gas costs in this function. Specifically, the transfer() call is contributing significantly – perhaps we could explore using a more efficient method like send() or consider batching transactions if feasible.” Notice how that version provides context and suggests potential solutions, moving beyond a simple critique. Similarly, Slack messages discussing PRs often require carefully chosen language to avoid misunderstandings. “I’ve implemented the upgradeability feature as described in the design document” is technically correct but lacks impact. “This PR introduces the necessary smart contract upgradeability logic, following the specifications outlined in doc-ID #427” immediately provides crucial context and a reference point for further discussion.

Another area of difficulty often lies in the use of technical jargon when explaining complex concepts to non-technical stakeholders. Translating terms like “reentrancy” or “delegatecall” into accessible language is critical, but even seemingly simple explanations can be misinterpreted if not carefully crafted. Instead of stating, “This contract has a reentrancy vulnerability,” one might say, “There’s a potential risk that an external contract could interrupt the execution of this function and cause unintended consequences.” This phrasing highlights the risk rather than simply identifying a technical flaw, framing it in terms understandable to someone without a deep understanding of Solidity’s internals.

Furthermore, paying attention to modal verbs – “should,” “could,” “may” – is crucial for expressing uncertainty or recommendations within code documentation and PR descriptions. Using “This contract should implement… ” implies an obligation, while “This contract might benefit from…” suggests a possibility without imposing a requirement. These subtle differences can drastically alter the tone and impact of your communication.

Here’s a simple example demonstrating how to use forge’s built-in gas estimation:

forge build --source my_contract.sol --gas-limit 200000

This command, when executed, will automatically estimate the gas cost of compiling and deploying your smart contract. Understanding the output from forge, particularly the gas limit and estimated gas usage, is key to optimizing your code for efficiency – a skill that directly translates to effective communication about performance issues during code reviews.